Desktop Sidebar allows you to create an installation file for your panel. This file allows your panel's users to easily install the panel into Desktop Sidebar. The install file is a compressed file (*.zip), which contains your panel's files, but has a *.dspackage extension. In order to install the panel, the user needs to open the dspackage installation file while Desktop Sidebar is running. Desktop Sidebar will automatically install the panel and add it to the panel list.
How to create an installation file (*.dspackage file):
1. Open a text editor (for example, MS notepad) and copy the follwing information (depending on your programming language) into it:
<?xml version="1.0" encoding="utf-8" ?> <root> <requirements> <item condition="$NET11" text="This panel requires .NET Framework v1.1 to be installed" /> </requirements> <filegroups> <group destination="$PLUGINS\MyPanel"> <files name="*.*"/> <files name="MyPanel.dll" action="$NET11DIR\regasm /codebase /silent "%1""/> </group> </filegroups> <actions> <action cmd="ADDPANEL MyPanel" /> </actions> </root>
<?xml version="1.0" encoding="utf-8" ?> <root> <filegroups> <group destination="$PLUGINS\MyPanel"> <files name="*.*"/> </group> </filegroups> <actions> <action cmd="ADDPANEL MyPanel" /> </actions> </root>
2.Save the file as *.install - replace the * with the actual name of the panel's DLL (For example, MyPlugin.install) and copy it into your panel project directory (where the *.dll and *.dsplugin files of your panel are).
3.Compress your panel files (see details below) into a *.zip file.
For exapmle, MyPanel.zip.
Panel files that need to be inserted
into the installation file: *.dll , *.dsplugin and the file dsidebarpia.dll you
used in your panel for forward compatibility reasons. Make sure that it is the
latest version. If your panel uses more files for features such as skinning and
translating - include them also.
4.Rename the *.zip file and change it into a *.dspackage file.
For example, change MyPanel.zip into MyPanel.dspackage.
More Information:
Panel installation process
When the panel is installed using the installation file (*.dspackage), the panel's files (or directories) that were zipped are being extracted into a directory with the same name as the panel's name, which is located in the "plugins" folder inside the Desktop Sidebar instance's settings folder
When the user runs more than one instance of Desktop Sidebar:
When the user installs the panel while running more than one instance of
Desktop Sidebar, the files will be extracted into the "plugins" directory of
the instance which was running when the installation started, or the "plugins"
directory of the instance that was in focus at the time of installation (for
example, the user just clicked on DS before intalling the panel).
That "plugins" directory is located in
Desktop Sidebar instance's settings folder.
In such a case, the user will be able to use the panel only with the instance
where the panel's files were extracted.
*.Install file reference:
Version Validation:
<item condition="$NET11" text="This plugin requires .NET Framework v1.1 to be installed" />This line handles a case in which the user doesn't have .NET Framework v1.1 installed. The message that will be displayed to the user in that case, should be written after text="Display Message" .
Example,
<requirements> <item condition="$NET11" text="This plugin requires .NET Framework v1.1 to be installed" /> </requirements>Extracting Files:
You can set the files that will be extracted from the *.dspackage file and the location to where they will be extracted.
First set the path by using this line:
<group destination="$PLUGINS\MyPanel">
the destination="" is the path to where the files will be extracted.
$PLUGINS is the path to the plugins directory which is located in the Desktop Sidebar instance's settings folder.
$NET11DIR is the directory of the .NET Framework v1.1 (Required only for .NET plugins)
$SIDEBAR is Desktop Sidebar installation directory.
After writing the destination, write the names of the files that you want to be extracted into it, by using:
<files name="*.*"/>
After name=" write the name of the file to be extracted, or *.* for all files. You can also choose to extract all files with the same initial or with the same extension.
Registering a .NET panel (Required only for .NET panels):
<files name="$PACKAGE.dll" action="$NET11DIR\regasm /codebase /silent "%1"" />
This line registers a panel that was written in .NET .
Adding the panel into Desktop Sidebar After Installation:
Use the folowing line to set Desktop Sidebar to automatically add your panel to it:
<action cmd="ADDPANEL MyPanel" />
Instead of MyPanel write the name of your panel. It should match the actual name of the *.dll file of the panel.
Example:
<actions>
<action cmd="ADDPANEL MyPanel" />
</actions>
Signing .NET panels (Required only for .NET panels):
If you develop panels in .NET you need to sign them, otherwise the user will get a warning message during the installation process. To sign your panel, just follow these instructions:
1.Make sure that you have .NET Framework SDK v1.1 installed. If not, download and install it. You can download it from Microsoft Download Center
2.Open the bin directory of the .NET Framework SDK (usually in: "HomeDrive:\Program Files\Microsoft .NET\SDK\v1.1\Bin\") with Windwos Command Prompt.
3.Write the following line:
sn -k c:\keys\key.snk
This will create the file key.snk in the given path (you can change this path)
4.Open the project of your panel and edit the code of the file
"AssemblyInfo.cs".
Search for the line:
[assembly:AssemblyKeyFile("")]
5.Write inside the quotation marks, the path to the *.snk file. Don't forget to
add @ before the quoatation marks !
For example:[assembly:AssemblyKeyFile(@"c:\keys\key.snk")]
6.Compile your project.
Upgrading a panel:
Not all panels can be upgraded - sometimes the user will not be able to install a panel over a previous installation, even if they are different versions. In this case, when trying to install over a previous installation, Desktop Sidebar will suggest that the user disable the panel and restart Desktop Sidebar. Only after the panel is disabled and Desktop Sidebar is restarted, can the panel be installed. You can alternatively make a *.zip installation of your panel in addition to the *.dspackage file and instruct your panel's users extract the files, into where they previously installed the panel. This process should be done when Desktop Sidebar is not loaded, since Desktop Sidebar is using the panel's .dll files while it is loaded.
Siging a panel that includes a refrence to non strongly named files (using c#)
This project includes two references which effectively wrapper the Flash.ocx component released by Macromedia. Unfortunately, Macromedia does not strongly name this component. This means that any application/component that uses this as a reference cannot be strongly named. There is, however, a way around this.
1) Once you've added the Flash.ocx ("Shockwave Flash" through the Add Reference Dialog under COM) you will see the reference "ShockwaveFlashObjects" added. You may or may not see the additional reference "AxShockwaveFlashObjects" but once you add the flash control to a form through your Toolbox you should see both. These references are interops created by .NET to wrapper your communication to the Flash.ocx installed somewhere on your system.
2) Once you are ready to create your "strongly named" component you will need to find your Flash.ocx on your system. This will generally be found at: "C:\<WINDIR>\system32\Macromed\Flash\Flash.ocx". I generally copy this file somewhere separate (like my project directory TEMPORARILY) and then start a VS.NET 2003 Command Prompt.
3) Now you're going to need a keypair to use for strongly naming both Flash.ocx and your project. You can easily create this on your machine by typing: "sn -k sgKey.snk" (without the quotes). It's that easy. This keypair will be used in the next step. Some notes here... depending on your OS you may have some difficulty here. Windows XP should work fine whether you have Home or Professional Edition. Windows 2000, however, and very likely Windows 9x/ME/NT will require the latest version of Internet Explorer AND the "High Encryption Pack". These can be downloaded from Microsoft easily enough.
4) Assuming you copied your Flash.ocx file and sgKey.snk files to your main Project directory, you now simply need to run the following command from that same VS.NET 2003 Command Prompt: "AxImp Flash.ocx /keyfile:sgKey.snk" (without the quotes). The resulting output of this command should be readily apparent... two files: "AxShockwaveFlashObjects.dll" and "ShockwaveFlashObjects.dll".
5) Go to your project and delete those two references for Flash. Then re-add them except this time re-add them using the Add Reference Dialog and BROWSING to these two files you just created. Essentially you just recreated the interops but made them strongly named interops.
6) In C# you'll want to add this to your AssemblyInfo.cs:
[assembly: AssemblyKeyFile(@"..\..\sgKey.snk")]
and remove this:
[assembly: AssemblyKeyName("")]
Compiling should now give you a strongly named assembly.