How to build a Private Assembly in Rainbow (Module Plug-in)

By, Leo Duran

 

What is a Private Assembly?

I like to relate a private assembly to a module plug-in. A lot of Rainbow development seems to happen by opening the Rainbow Solution file in VS.Net and proceeding to add your custom code for your own modules. When you build the result, it ends up being part of the Rainbow.DLL file; hence you’ve added your changes to the Rainbow Core. When using a Private Assembly, all of the building of your module takes place outside of the Rainbow Project; because you create a new VS.Net solution file and reference the Rainbow.DLL file from within your new solution file. After building your solution it can be added to Rainbow by copying the YourSolution.DLL file to the Rainbow BIN folder, and adding your ASCX, and ASPX files to the DesktopModules/YourSolution/ folder. Lastly you tell Rainbow about your solution using an Install XML file or by adding it directly to the database. The result is a Plug-in that you can deploy to any rainbow installation with ease. When you make changes to your plug-in, simply XCOPY install them over to Rainbow again, and your changes are in place.

 

This document will refer to a Private Module Assembly as a Plug-In.

 

One clear advantage to this way of developing modules for rainbow is that you don’t ever have to rebuild the Rainbow Core, so you only have to rebuild your particular module, and it results in saving time for you as a developer.

 

Another advantage is that your code is separate from the Rainbow Core and can be installed in most any Rainbow Installation that exists.

 

I can’t think of any other reasons at the moment but if you do… feel free to add them.

Requirements

• Visual Studio .Net 2003
• You should have Rainbow installed and running on your development machine. Refer to **** Rainbow Install Instructions **** for help on installing Rainbow.

 

The instructions in this document have been tested with VS.Net 2003. I am fairly certain that they will also work in earlier versions of VS.Net as well.

Creating your Plug-in

Follow these instructions exactly, and when you get the general idea you can modify them to your specific situation.

Create a default project to host your plugin.

1. Start VS.Net
2. Select New Project from the File Menu.
3. Click on Visual C# Projects, and then on ASP.Net Web Application.
4. In the Location field, change the name from http://localhost/WebApplication1 to http://localhost/MyRainbowPlugin.

 

Add a Reference to the Rainbow.DLL and other dependencies.

1. Right click on “MyRainbowPlugin” project from the VS.Net Solution Explorer and choose “Add Reference”.
2. From the “Add Reference” window, click the “Browse” button.
3. Navigate to the location of your Rainbow Bin folder. If you installed the Rainbow Portal on your C: drive then the location should be c:/Rainbow/bin/. Change the location depending on where you installed Rainbow.
4. Click on the file named Rainbow.dll and then click “Open”.
5. Leaving the “Add Reference” window open, select Brows again and add the following DLL files… Esperantus.dll and log4net.dll. Note: When I failed to load the last two dll files I got miscellaneous errors when VS.Net tried to load my ascx, and the result was that I could only see the html code and not the form designer.
6. Click on the “OK” button to close the window and add the references.

 

Creating the Module

1. Go ahead and close (or even delete) the WebForm1.aspx file that VS.Net automatically created for you.
2. From the “Project” menu, click on “Add Web User Control”.
3. In the “Add New Item” dialog, type in the name “MyHelloWorldPlugin.ascx”.
4. This is where you begin to add content to your control. For our example, just type the words “Hello World!” on the “MyHelloWorldPlugin.ascx” page.
5. Click on the “View” menu and select “Code”.
6. We need to make some changes to make sure we create a Rainbow Portal Module and not just a default ASCX control.
7. After the last using statement, create a new line and type in the following code…

using Rainbow.UI;

using Rainbow.UI.WebControls;

8. Move down to the line that starts with…

public class MyHelloWorldPlugin : System.Web.UI.UserControl

and change it to read

public class MyHelloWorldPlugin : PortalModuleControl

9. Move down to the section that reads… “Web Form Designer generated code” and expand the section.
10. Type the following code between the lines that read…

InitializeComponent();

base.OnInit(e);

       so that it reads like this…

InitializeComponent();

 

ModuleTitle = new DesktopModuleTitle();

Controls.AddAt(0, ModuleTitle);

 

base.OnInit(e);

11. Create new line after the #endregion code and type in the following…

public override Guid GuidID

{

  get

  {

      return new Guid("{38536E21-A815-4499-97B8-9D 8F 755CE3D8}");

  }

}

12. Make sure not to use the GUID code supplied in this document, instead follow these instructions to create your own GUID.

6. 1. Highlight the GUID that appears on code… it is on the line that reads… return new Guid(“{38536E21-A815-4499-97B8-9D 8F 755CE3D8}”);
   2. Click on the “Tools” menu and select “Create GUID”.
   3. Select option “4. Registry Format…”
   4. Click on the “Copy” button, and then click on the “Exit” button to close the “Create GUID” dialog box.
   5. Select the “Edit” menu and click “Paste”.
   6. Your new GUID should overwrite the one mentioned in this document.

13. Build your project by selecting “Build Solution” from the “Build” menu.

 

Congratulations, you just made your very own rainbow plug-in module. Now we can use XCOPY deployment and deploy the files from our module folder to the Rainbow Folder.

Installing your Module Files

1. Open up windows explorer and copy the MyRainbowPlugin.dll and the MyRainbowPlugin.pdb from your applications bin folder into the Rainbow/bin folder. Note: Your application should have been created, by default, in the <drive>/inetpub/wwwroot folder.
2. Navigate to your Rainbow installation and under Rainbow/DesktopModules/ create a new folder called MyRainbowPlugin.
3. Copy the MyRainbowPlugin.ascx file from your application folder into the /Rainbow/DesktopModules/MyRainbowPlugin folder that you created in the previous step.

Telling Rainbow about your new module

There are probably easier ways to do this, but I am doing to show you the method I use to hook the module up to rainbow after you’ve physically moved all the necessary files into the right locations.

 

The table that contains the module information is called rb_GeneralModuleDefinitions and is in the Raibow database. You need to create a new entry in this database for your module. Below is a SQL Insert Statement that you can use as a template. Just fill in the blanks with the specifics of your module and add run the query against the Rainbow database using something like Query Analyzer.

 

INSERT INTO [Rainbow].[dbo].[rb_GeneralModuleDefinitions]

(

  [GeneralModDefID],

  [FriendlyName],

  [DesktopSrc],

  [MobileSrc],

  [AssemblyName],

  [ClassName],

  [Admin],

  [Searchable]

)

 

VALUES

(

  '{5D4D00B8-9D81-485d-B 04A -04DD6802BC8D}',   --GUID

  'MyHelloWorldPlugin',               --FriendlyName

  'DesktopModules/MyRainbowPlugin/MyHelloWorldPlugin.ascx', --DesktopSrc

  ' ',                        --MobileSrc

  'MyRainbowPlugin.DLL',          --AssemblyName

  'MyRainbowPlugin.MyHelloWorldPlugin',   --ClassName

  0,                      --Admin

  0                       --Searchable

)

 

Rainbow should now recognize your module, but there are just a few more steps before we add to your home page so we can test it out completely.

1. Launch Rainbow in your web browser.
2. Select the “Admin All” tab.
3. Click the “Edit this item…” edit icon next to the “MyHelloWorldPlugin”. The icon usually looks like a pencil.
4. In the next screen choose “Select All” to make the module available in all portals. Alternatively, if you only want the module available for a few portals select them individually.
5. Select “Apply Changes”.

 

Now let’s add the module to our home page

1. Select “Admin This”.
2. Scroll down to the “Tabs” Section.
3. Click the “Home”.
4. Click the “Edit this item…” edit icon.
5. Click the “Module Type” drop down list and choose “MyHelloWorldPlugin”.
6. Change the “Module Name” to “Hello World”.
7. Click “Add to “Organize Modules” Below”.
8. Click “Apply Changes”.
9. Navigate to the Rainbow “ Home ” page.

 

Congratulations! You should now see your module as one of the modules on the home page. From here you can start creating your own new modules without having to build from the rainbow core.

Debugging your “Plug-in” Modules

Normally modules developed within the Rainbow core are debugged by starting Rainbow from within VS.Net in Debug Mode. How then do you debug Private Assemblies?

 

The answer is simple…

1. Start your web browser and make sure you have the Rainbow Portal Home page loaded.
2. Switch to your VS.Net project and open your Plug-in Module.
3. From the “Tools” menu in VS.Net, Choose “Debug Process”.
4. In the “Processes” dialog box, select “aspnet_wp.exe”.
5. Click the “Attach” button.
6. A new window called “Attach to Process” pops up. In this window make sure the check mark next to “Common Language Runtime” is selected.
7. Click “OK” and the “Attach to Process” pop up closes.
8. Click “Close” in the “Processes” window.
9. You are now attached to the debugger in order to debug your newly developed Plug-in Module. Any break points you select will jump you to the code when you navigate to the part of the web page that contains your module.

Tips…

• Create a batch file to move your files from your inetpub/yourmodule and inetpub/yourmodule/bin file into their Rainbow locations. It will make it much easier for you to load new versions between testing.
• To test your module, follow the tip above and just restart the web browser. Technically you don’t even have to restart the web browser, just refresh or navigate to the portal tab that hosts your module.

 

I hope you have enjoyed this guide.

 

Leo