How can my Grasshopper plugin be added to ShapeDiver?
Read this if you are a Grasshopper plugin developer. No need to read this for users of Grasshopper.
Our Geometry Backend systems are designed for high security, reliability, and scalability. Before we roll out a new Grasshopper plugin on one of the shared systems, or one of the dedicated systems operated for our Enterprise customers, the plugin has to undergo a reviewing process which includes the following checks:
Value
Does the plugin bring significant value to the users of ShapeDiver?
(Enterprise customers can ask us to deploy any plugin, although it still needs to pass some of the other checks).
Security
Could the plugin harm our Geometry Backend system?
Reliability and maintainability
Does the plugin have proper versioning?
Are the plugin authors aware of how to ensure backward compatibility?
Are the plugin authors actively maintaining the plugin?
Is the plugin open source (which makes it easy to maintain in case the original authors stop doing that)?
Which version of Rhino is the plugin built against?
Depending on the outcome of the review, the following may happen:
We deploy and fully support the plugin
We deploy the plugin but disallow some of the components of the plugin
We do not support the plugin
Please continue reading for details on the reviewing process.
Security
We do not allow plugin components that do one of the following:
File system access
Accessing the local file system could cause harm to the security of our cloud servers and is therefore not allowed. In some cases, we might allow read-only file system access, e.g. if the plugin needs to read configuration data.Network access
Allowing network access for plugins would be a security issue because the privileges of the cloud server could be abused. Again, in some cases, there can be exceptions to this rule.Accessing the Rhino document
Reading data from or writing data to the Rhino document in most cases does not make sense for applications built on ShapeDiver (which runs Grasshopper in a headless way), and could cause security issues. The ShapeDiver plugin for Grasshopper includes input and output components that allow getting all kinds of data into and out of Grasshopper in a meaningful way.
Reliability
We typically do not allow plugin components that do one of the following:
Scheduling the computation of further solutions
While our Geometry Backend systems can in principle deal with plugins that schedule the computation of further solutions, we do not encourage this.
Versioning
The Grasshopper plugin must include proper versioning information, which will allow our Geometry Backend systems to do the following:
Check whether uploaded models, which make use of the plugin, are supported by the currently installed version of the plugin.
Ensure backward compatibility for future plugin updates.
Each Grasshopper plugin includes a single implementation of the GH_AssemblyInfo class, which provides information about the plugin:
Id: the unique id of the plugin
Name: the name of the plugin, this is for information only
AuthorName: information about the author of the plugin
Version: the version code of the plugin
Further versioning information is provided by the AssemblyVersion attribute, which is typically defined in the file Properties/AssemblyInfo.cs of the plugin.
It might be that your plugin project does not include an AssemblyInfo.cs. In this case read this and look for the property <AssemblyVersion> or <Version> defined in your .csproj file.
The best way to debug the versioning information reported by your plugin is to save a Grasshopper file including one of your plugin’s components in .ghx XML format. Open the file in a text editor and search for the section “GHALibraries”. You will see something like this:
From this example we can see the following:
The plugin reports AssemblyVersion 0.0.5.0.
The plugin reports an Id.
The plugin reports an AuthorName.
The plugin reports a Name.
The plugin does not report a Version.
Versioning best practices
It’s perfectly fine if your plugin does not report a Version. In that case, make sure that you keep updating (increasing) the AssemblyVersion.
In case your plugin reports a Version, keep it consistent with AssemblyVersion. You can either do this manually or use the code snippet shown below.
Do not change the plugin Id when you update your plugin.
Provide an AuthorName and a Name.
How to keep Version automatically consistent with AssemblyVersion (add this to your plugin’s implementation of GH_AssemblyInfo):
public override string Version
{
get
{
return AssemblyVersion;
}
}
public override string AssemblyVersion
{
get
{
var assembly = Assembly.GetExecutingAssembly();
var assemblyName = new AssemblyName(assembly.FullName);
return assemblyName.Version.ToString();
}
}
In case you want to make use of semantic versioning, you can do that by overriding the Version property differently. However, it’s still a good idea to keep the MAJOR.MINOR.PATCH numbers part of your semantic version consistent with AssemblyVersion.
Versioning bad practices
In case you define a Version, it is a bad practice if you keep Version and AssemblyVersion out of sync (not consistent).
It is a bad practice to not update (increase) AssemblyVersion when releasing plugin updates.
Backward compatibility
Why is it really important that updates to your plugin stay backward compatible with previous versions of your plugin? Imagine the following scenario:
Your plugin Scarabaeus version 1.0.0 gets deployed to a ShapeDiver Geometry Backend.
Version 1.0.0 contains a component called MakeBall which creates a sphere from one numeric input: a number (the radius).
Users make use of the component and upload their models to ShapeDiver. Some of the users embed their models on a website.
Users ask you to make the component more useful and also accept a color input, in order to make colored spheres.
You update the component to have a color input and release it as part of version 1.1.0 of Scarabaeus. (Great, you increased the version number 🥳!)
Sadly, it will still be impossible for us to deploy version 1.1.0 of your plugin 😥. That is so because opening any of the Grasshopper models containing the previous version of the MakeBall component will cause Grasshopper to complain and show a pop-up window. Further computations of all these models on the ShapeDiver Geometry Backend would fail.
Luckily there is a simple solution to this challenge: Use the Obsolete property of Grasshopper components. Either
rename the component class to contain the string OBSOLETE, or
decorate the component class using an ObsoleteAttribute.
At the same time, you might want to set the Exposure property of the component to GH_Exposure.hidden, such that it doesn’t show up in the UI anymore. The component will still work when opening older models.
You should also keep old obsolete versions of your components in case you change their behavior in a way which could break older models. An example of this would be if you change MakeBall to output an ellipsoid instead of a sphere.
Backward compatibility best practices
Before releasing a plugin update, a good practice is to do this:
Save a Grasshopper model which contains one instance of each component of your previous plugin version. This model must also include the obsolete components which do not show up in the UI of Grasshopper anymore! You can use the “LibraryExplorer” Grasshopper model attached below to automatically instantiate all components of your plugin (Note that this model throws some errors when opening in Grasshopper, that’s ok).
Add this model to your repository for future backward compatibility checks.
Open the model using the updated version of the plugin.
If Grasshopper shows an error, fix the plugin.
Grasshopper plugin template
We published a template for Grasshopper and Rhino plug-ins, which follows best-practices we use. You can view and download the code from here: https://github.com/shapediver/GrasshopperPluginTemplate