Your First Component (Windows)

This guide walks you through your first custom Grasshopper component library using Visual Studio.

It is presumed you already have the necessary tools installed and are ready to go. If you are not there yet, see Installing Tools (Windows).

HelloGrasshopper

We will use the Grasshopper Assembly templates to create a new, basic, component library called HelloGrasshopper.

If you are familiar with Visual Studio, these step-by-step instructions may be overly detailed for you. The executive summary: create a new project using the Grasshopper Assembly template, build and run, and then make a change.

We are presuming you have never used Visual Studio before, so we’ll go through this one step at a time.

File New

  1. If you have not done so already, launch Visual Studio (for the purposes of this guide, we are using Visual Studio 2015 Community Edition and C#).
  2. Navigate to File > New > ProjectFile New Project
  3. A New Project wizard should appear. In the left column, find the Installed > Templates > Visual C# > Rhinoceros section. In the central list, select the Grasshopper Add-On template… New Project
  4. For the purposes of this Guide, we will name our demo plugin HelloGrasshopper. At the bottom of the window, fill in the Name field. Browse and select a location for this project on your disk… Project Configuration
  5. The New Grasshopper Assembly dialog appears. Check the Provide sample code checkbox. New Grasshopper Assembly
  6. This is where you fill out information about your first component:
    1. Add-on display name: the name of component library itself.
    2. Name: the name of the component as displayed in the ribbon bar and search menus.
    3. Nickname: the default name of the component when inserted into the canvas.
    4. Category: name of tab where component icon will be shown.
    5. Subcategory: name of group inside tab where icon will be shown.
    6. Description: description shown in tooltip when mouse is over the component icon in the menu.
  7. For the purposes of this guide, we will accept the defaults and click Finish
  8. A new solution called HelloGrasshopper should open… HelloGrasshopper Solution

Boilerplate Build

  1. Before we do anything, let’s build and run HelloGrasshopper to make sure everything is working as expected. We’ll just build the boilerplate Plugin template. Click Start (play) button in toolbar corner of Visual Studio (or press F5) to Start DebuggingStart Button
  2. Rhinoceros launches.
  3. Since this is the first time you are debugging the components, you need to tell Grasshopper where to look. In the Rhino command prompt, run the GrasshopperDeveloperSettings command… Grasshopper Developer Settings
  4. Uncheck the Memory load *.GHA assemblies using COFF byte arrays checkbox.
  5. Click the Add Folder button and add your bin output folder of your project to Grasshopper’s search path. NOTE: You only need to do this step once during the development of your component, unless you move it elsewhere.
  6. (Optional) Automatically start Grasshopper every time Rhino starts…
    1. Navigate to Tools > Options > General.
    2. In the Run these commands every time Rhino starts text area, type _Grasshopper then click OK.
  7. Run the Grasshopper command to start Grasshopper. If you don’t blink, you might see Grasshopper say it is loading “HelloGrasshopper” in the status bar of the splash screen.
  8. Navigate to Curve > Primitive in the components menus. You should see HelloGrasshopper in the list with a blank icon. Drag this onto the canvas. The component should “work.”
  9. Exit Rhinoceros. This stops the session. Go back to Visual Studio. Let’s take a look at the…

Component Anatomy

  1. Use the Solution Explorer to expand the Solution (.sln) so that it looks like this… Grasshopper Component Anatomy NOTE: Depending on your edition of Visual Studio, it may look slightly different.
  2. The HelloGrasshopper project (.csproj) has the same name as its parent solution…this is the project that was created for us by the Grasshopper Assembly template wizard earlier.
  3. Properties contains the AssemblyInfo.cs source file. This file contains the meta-data (author, version, etc) about the component library.
  4. References: Just as with most projects, you will be referencing other libraries. The Grasshopper Assembly template added the necessary references to create a custom Grasshopper component.
  5. GH_IO - or GH_IO.dll - is the Grasshopper Input/Output library required to read and write Grasshopper files.
  6. Grasshopper - or Grasshopper.dll - is the Grasshopper base namespace.
  7. RhinoCommon - or RhinoCommon.dll - is the Rhinoceros .NET SDK.
  8. System, System.Core, System.Drawing, System.Windows.Forms are .NET foundational libraries.
  9. HelloGrasshopperInfo.cs contains the component library information, such as the name, icon, etc.
  10. HelloGrasshopperComponent.cs is where the action is. Let’s take a look at this file…

Make Changes

  1. Open HelloGrasshopperComponent.cs in Visual Studio’s Source Editor (if it isn’t already).
  2. Notice that HelloGrasshopperComponent inherits from GH_Component

     public class HelloGrasshopperComponent : GH_Component
    
  3. If you hover over GH_Component you will notice this is actually Grasshopper.Kernel.GH_Component.
  4. HelloGrasshopperComponent also overrides two methods for determining the input and output parameters …

     protected override void RegisterInputParams(GH_Component.GH_InputParamManager pManager)
     ...
     protected override void RegisterOutputParams(GH_Component.GH_OutputParamManager pManager)
    
  5. The actual work done by the component is to be found in the SolveInstance method…

     protected override void SolveInstance(IGH_DataAccess DA)
    
  6. As you can see, this is where the action happens. This boilerplate component creates a spiral on a plane. Just to make sure everything is working, let’s change the default plane on which the spiral is constructed. On line1 67, in SolveInstance, notice that an XY plane is constructed…

     Plane plane = Plane.WorldXY;
    
  7. Further down in the SolveInstance method, you will notice that the input data is being fed into this plane…

     if (!DA.GetData(0, ref plane)) return;
    
  8. Go back to the RegisterInputParams, and find the line where the Plane input is registered. The last argument being fed to the method - Plane.WorldXY - is the default value of the input…

     pManager.AddPlaneParameter("Plane", "P", "Base plane for spiral", GH_ParamAccess.item, Plane.WorldXY);
    
  9. Change the default value of the Plane input to be Plane.WorldYZ

     pManager.AddPlaneParameter("Plane", "P", "Base plane for spiral", GH_ParamAccess.item, Plane.WorldYZ);
    
  10. Now let’s examine what happens when inputs are given to this component…

Debugging

  1. Set a breakpoint on line1 99 of HelloGrasshopperComponent.cs. You set breakpoints in Visual Studio by clicking in the gutter… Set a breakpoint
  2. Build and Run.
  3. In Grasshopper, place a HelloGrasshopper component on the canvas…as soon as you do, you should hit your breakpoint and pause… Hit a breakpoint
  4. The reason you hit the breakpoint is because the SolveInstance method was called once initially when the component was placed on the canvas. With Rhino and Grasshopper paused, in Visual Studio switch to the Autos tab (if it not already there). In the list, find the plane object. Our plane is a Rhino.Geometry.Plane with a value of {Origin=0,0,0 XAxis=0,1,0, YAxis=0,0,1, ZAxis=1,0,0} …an YZ plane, the default, as expected.
  5. Continue in Grasshopper by pressing the Continue button in the upper menu of Visual Studio (or press F5)… Continue Executing
  6. Control is passed back to Grasshopper and the spiral draws in the Rhino viewport. Now, place an XY Plane component on the canvas and feed it as an input into HelloGrasshopper’s Plane input. Notice you hit your breakpoint again, because the SolveInstance is being called now that the input values have changed.
  7. Exit Grasshopper and Rhino or Stop the debugging session.
  8. Remove the breakpoint you created above by clicking on it in the gutter.

DONE!

Congratulations! You have just built your first Grasshopper component for Rhino for Windows. Now what?


Next Steps

You’ve built a component library from boilerplate code, but what about putting together a new simple component “from scratch” and adding it to your project? (Component libraries are made up of multiple components after all). Next, check out the Simple Component guide.



Footnotes

  1. Line numbers in Visual Studio can be enabled and disabled in Tools > Options… > Text Editor section > All Languages entry > General sub-entry > Settings subsection > check Line numbers. Click OK to close the Options dialog.  2