While a Rhino plug-in can simply be distributed as an .RHP file, and activated/loaded using Rhino's PlugInManager command, it is often necessary to install the plug-in as part of a product installation process. To install plug-ins from an installer, your installer will be required to access a number of entries in the Windows Registry.
While reading this article, it is helpful to use the standard Windows Registry editing tool, REGEDIT.EXE, to follow along and see how Rhino's Registry entries are structured.
Because it is possible for more than one copy of Rhino to be installed on a computer, you can determine the most recently used copy of Rhino looking for the MostRecent registry value name, which can be found in the following key locations depending on the Rhino version:
HKEY_LOCAL_MACHINE\SOFTWARE\McNeel\Rhinoceros\3.0
or
HKEY_LOCAL_MACHINE\SOFTWARE\McNeel\Rhinoceros\4.0
The data in this value is a 10-character date string (REG_SZ) in the form of YYYY-MM-DD that identifies the build date of Rhino. An example date string is "2006-05-19" which identifies Rhino 3.0 SR5b. If the MostRecent key name does not exist, or if the string value is empty, then Rhino is not installed on the computer, or the installation is damaged.
As mentioned above, it is possible for more than one copy of Rhino to be installed on a computer. (Exception: Rhino 4.0 is designed to have just one active installation.) To discover all of the Rhino editions on the system would require enumerating all of the date keys found in the following locations depending on the Rhino version:
HKEY_LOCAL_MACHINE\SOFTWARE\McNeel\Rhinoceros\3.0
or
HKEY_LOCAL_MACHINE\SOFTWARE\McNeel\Rhinoceros\4.0
Typically, plug-ins are only registered with the most recently used version of Rhino. Most users have only one Rhino installed.
If the MostRecent Registry key name contains a valid date string, then you can find Rhino's Registry key in the following locations depending on the Rhino version:
HKEY_LOCAL_MACHINE\SOFTWARE\McNeel\Rhinoceros\3.0\<date>\Install
or
HKEY_LOCAL_MACHINE\SOFTWARE\McNeel\Rhinoceros\4.0\<date>\Install
where <date> is the string value identified by the MostRecent key name.
In this key, you will find the Edition key value that will identify the edition, or type, of Rhino: Beta, Release, or Evaluation. If the value of Edition is Evaluation, then the Evaluation version of Rhino was either the most recently installed or most recently run edition. Every time Rhino is installed, or run and then closed, the MostRecent key value is modified to reflect that Rhino's build date.
If the value of Edition is "Release", then the Commercial version of Rhino version of Rhino was either the most recently installed or most recently run edition. This includes any Rhino that can be installed from a Rhino CD, including Commercial, Educational, and Not-for-Resale versions. Note, these versions only differ in their CD keys.
Beta - Unless your intent is for your plug-in to run with Beta editions of Rhino, you will probably want to avoid installing your plug-in on these editions. For one reason, Rhino 3.0 and 4.0 Beta editions have long since expired and no longer run. Also, for your plug-in to work with Beta editions, they are requried to be built with the same SDK version.
Commercial - This edition should be your primary target.
Evaluation - Supporting this edition is a good way for customers to evaluate your plug-in. Note, when the Rhino evaluation period has expired, it will no longer load all 3rd-party plug-ins.
There are other useful key values that are found in the following locations depending on the Rhino version:
HKEY_LOCAL_MACHINE\SOFTWARE\McNeel\Rhinoceros\3.0\<date>\Install
or
HKEY_LOCAL_MACHINE\SOFTWARE\McNeel\Rhinoceros\4.0\<date>\Install
Default Language - identifies the language used by Rhino.
InstallPath - contains the full path to the Rhinoceros installation folder.
LicenseNodeType - identifies if Rhino is installed as standalone or as a network node.
Path - contains the full path to the System folder under the Rhinoceros folder.
To register your plug-in with Rhino, you will need to create a new Registry key in the following locations depending on the Rhino version:
HKEY_LOCAL_MACHINE\SOFTWARE\McNeel\Rhinoceros\3.0\<date>\Plug-Ins
or
HKEY_LOCAL_MACHINE\SOFTWARE\McNeel\Rhinoceros\4.0\<date>\Plug-Ins
The name of the Registry key will be your plug-in's GUID, the value returned by your plug-in's CRhinoPlugIn::PlugInID() derived member, formatted as a string. For example:
HKEY_LOCAL_MACHINE\SOFTWARE\McNeel\Rhinoceros\3.0\<date>\Plug-ins\<your_plugin_guid>
or
HKEY_LOCAL_MACHINE\SOFTWARE\McNeel\Rhinoceros\4.0\<date>\Plug-ins\<your_plugin_guid>
Under this new Registry key, create two new value names, Name and FileName that contain strings that identify your plug-in's name and the full path to the .RHP file, respectivly. For example, if I had created a new plug-in named "FooBar" that I has installed in Rhino's system folder, The registry would look like the following:
HKEY_LOCAL_MACHINE\SOFTWARE\McNeel\Rhinoceros\3.0\<date>\Plug-Ins\F3CF4A28-EA9E-4E08-BABA-5FC6645A5D72
or
HKEY_LOCAL_MACHINE\SOFTWARE\McNeel\Rhinoceros\4.0\<date>\Plug-Ins\F3CF4A28-EA9E-4E08-BABA-5FC6645A5D72
Key Name: Name
Key Value: FooBar (REG_SZ)
Key Name: FileName
Key Value: C:\Program Files\Rhinoceros 3.0\System\FooBar.rhp (REG_SZ)
Rhino will attempt to load your plug-in the next time Rhino launches if the Name and FileName Registry key names and values are present in your plug-in's Registry key. Rhino will briefly display a "Preparing plug-ins for first use" dialog if the plug-in loads correctly.
When your plug-in loads for the first time, the rest of the normal Registry keys/value pairs in your plug-in's Registry key fill be filled in.
Look in the Registry with REGEDIT.EXE and confirm that existing plug-ins follow these conventions.
Use the right-click context menu in REGEDIT.EXE to access the "Copy Key Name" and "Rename" functions so you can get accurate copies of names and values in the Registry.
Test your installer to handle all of these situations: