Deploying a CAB/SCSF Application with ClickOnce

From：http://rajsharma109.squarespace.com/
With CAB ( CompositeUI Application Block) and SCSF (Smart Client Software Factory) developers can incorporate proven patterns and best practices into their smart client applications.

Both CAB and SCSF use dependency injection to allow for the referencing of business and foundational modules via ObjectBuilder (which is also part of Enterprise Library 2.0). This allows application modules to be developed in isolation from each other and allows applications to be extended via a plug-in style architecture.

This is great in practice however it makes deployment with ClickOnce in Visual Studio 2005 a difficult process. ClickOnce publishing uses reflection within Visual Studio to determine assembly references so that applications can be packaged and deployed easily. CAB and SCSF modules ( dll's ) are not referenced directly in applications and cannot use the publishing feature within Visual Studio.

The alternative is to use the Manifest Generation and Editing Tool, Graphical Client (MageUI.exe). MageUI.exe supports the same functionality as the command-line tool Mage.exe with a Windows Forms based user interface. The ClickOnce publishing wizard uses Mage.exe uses under the covers, to create application and deployment manifests for application distribution.

This blog entry walks us through the process of creating a simple SCSF application and deploying it via ClickOnce using MageUI . A basic understanding of CAB and SCSF is necessary to complete this walkthrough.

The Application

The SCSF application takes a very simple form: The Shell application loads and a module with a Button is loaded into the Shell's right application workspace. Use the following steps create the application:

· In Visual Studio 2005 choose a new project template of type...Guidance Packages... SmartClientDevelopment and name it " deploySmartClient ".

· The "Creates a new Smart Client Solution" dialog appears: enter "root" for "Root namespace" and check "Create a separate module to define the layout for the shell". Uncheck "Show related documentation after running the recipe." Click "Finish."

· Right click the "Source" folder in Solution Explorer and from the Smart Client Factory submenu click "Add Business module...". Change the name to " buttonModule " and click OK.

· The "Create Business Module" dialog appears: Check "Create an interface library for this module" and Uncheck "Show related documentation after running the recipe". Click "Finish".

· The module we have just created is now going to be added to the right workspace of our SCSF application.

· Expand the buttonModule project in Solution Explorer and right click the "Views" folder. From the Smart Client Factory submenu choose the "Add View (with presenter...) menu item. The "Add View (with presenter)... dialog appears. Name the View " buttonView ", Check "Create a folder for this view" and Uncheck "Show related documentation after running the recipe." Click "Finish".

 

· Expand the " buttonView " folder in Solution Explorer and open buttonView.cs in Designer View.

· Drag a button onto the design surface.

· Double click the button to generate a Click event handler in code view.

· Add the following code:

private void button1_Click(object sender, EventArgs e) {
    MessageBox.Show ("Hello SCSF World!");
} 

· Open the ModuleController.cs file in code view add the following using statement:

using root.buttonModule.Interface.Constants; 

· Scroll down to find the AddViews method. Add the following code to this method:

private void AddViews () {
    buttonView bv = WorkItem.Items.AddNew < buttonView >(" buttonView ");
    WorkItem.Workspaces [ WorkspaceNames.RightWorkspace ].Show( bv );
} 

This adds the buttonView to Right Workspace in the Shell application.

· In Solution Explorer right click the Shell Project and choose "Set as Startup Project."

· Run the application and click button1:

That’s the application built, now onto deployment.

Deployment

To speed up the entire process we can use Visual Studio to create our initial ClickOnce package which we then subsequently modify for our purposes using the following steps:

· In Solution Explorer right click the Shell project and choose "Properties."

· Click the "Publish" tab, you are presented with the following view:

· Click the "Publish Wizard" button. The Publish Wizard appears: accept the defaults, Click "Next", "Next" and "Finish".

· Visual Studio then publishes your ClickOnce deployment package to your Inetpub \ wwwroot directory: the directory view of published files is as displayed:

 

 

 

 

 

This directory contains two deployment manifests for the application named " Shell.application " and "Shell_1_0_0_0.application" (note version number taken from the Publish tab in Visual Studio), a versioned folder that contains the files that Visual Studio has determined need to be deployed, a bootstrapper (setup.exe) and an htm file (publish.htm) that allows users to initiate installations.

Our main goal here is to create a new application manifest and deployment manifest that contains all our relevant CAB/SCSF modules including the ones that Visual Studio could not determine are part of the application and to repackage them. Use the following steps:

· Copy the folder Shell_1_0_0_0 and rename the copy to Shell_1_0_0_1 (note the incremented version number).

 

 

 

 

 

 

· Open the Shell_1_0_0_1 folder up in Windows Explorer.

· Find the directory in which the SCSF application was created and open up the bin\Debug directory in Windows Explorer. Compare the contents of the Shell_1_0_0_1 directory and this directory: note that each of the files in Shell_1_0_0_1 have a .deploy extension. You will notice that the SCSF folder contains some other modules and files which Visual Studio was unable to detect when it created our original deployment package.

· Copy those additional files from the SCSF directory to the Shell_1_0_0_1 directory:

buttonModule.dll

buttonModule.Interface.dll

Infrastructure.Layout.dll

Infrastructure.Module.dll

· Start up the MageUI.exe tool from a Visual Studio command prompt. From the File menu choose Open and open up the file Shell.exe.manifest within the Shell_1_0_0_1 directory. This is the application manifest file.

· Change the "Version" to be "1.0.0.1" to match the version number on the directory we copied previously.

· Now Click on "Files" on the list view to the left.

· For the "Application directory" text box ensure that the path is set to point to the Shell_1_0_0_1 directory. Click Populate. Note: It is likely that MageUI will crash now at some point as it adds the additional dlls we added to the folder. If so, restart MageUI and repeat the exercise remembering to check that the version is also incremented to 1.0.0.1.

· In Solution Explorer locate directory that contains the temporary signing key Shell_TemporaryKey.pfx file. Copy this file to the root of Shell directory in inetpub \ wwwroot .

· In MageUI click "Save", the "Signing Options" dialog appears. Select the temporary signing key Shell_TemporaryKey.pfx that you just copied by clicking the elipsis and navigating to the file. Of course in a real world deployment you would sign your application with a real key. Click "OK".

 

 

 

 

 

 

 

 

 

 

 

 

 

 

· Now we associate the application manifest with the deployment manifest. In MageUI from the "File" menu select "Open" and navigate to Shell.application in the main directory. This is the deployment manifest. The following view is displayed:

· Change the "Version" to be 1.0.0.1, then click on the Application Reference list view item to the left. The following view is displayed:

· Click the "Select Manifest" button and navigate to the Shell_1_0_0_1 directory and choose the file Shell.exe.manifest . Click "Save" and choose the temporary signing key as above.

· Close MageUI.exe.

· Double Click on setup.exe in the main directory - your application is now installed.

Application Updates

You can now try out a sample application update:

· In Solution Explorer open buttonView.cs in the Forms designer.

· Set the BackColor of the Button to another Color .

· Build the buttonModule .

· Copy the Shell_1_0_0_1 directory and rename it to Shell_1_0_0_2

· In the application's debug output directory copied the newly compiled buttonModule.dll to the Shell_1_0_0_2 directory.

· Open up Shell.exe.manifest in MageUI.exe and set the version to be 1.0.0.2.

· Click the files listview item in MageUI and Click Populate - overwriting any necessary files (note once again MageUI may crash, restart it and repeat).

· Save with the signing key.

· Open up Shell.application in the main directory in MageUI and set the version to 1.0.0.2 and in the application reference listview item select the manifest to be Shell_1_0_0_2\ Shell.exe.manifest .

· Save with the signing key.

· Re-run setup: the new version is deployed.

Rolling back application Updates

When you execute setup.exe (the bootstrapper ), it’s worth remembering that Shell.Application will be assigned to the version number you assigned using MageUI . If you need to rollback applications to prior versions you should back up your Shell_versionNumber directory and Shell.Application file. So say you wanted to rollback to a prior version : you would replace the exising Shell.Application with your backed up Shell.Application file and copy the versioned Shell_versionNumber directory then re-run setup.exe.

 

UPDATE

As my friend William pointed out there is an alternative approach that makes use of the ClickOnce within Visual Studio without having to use Mage:

* Add Infrastructure.Layout.dll, Infrastructure.Module.dll and your own module dll's (and interface dll's) as existing items to the Shell application project. Set their build action to be "Content" and Copy to Output Directory as "Copy Always". This allows ClickOnce to determine that these are required files.

* For ProfileCatalog.xml set Build Action to Content and Copy to "Output Directory" as "Copy Always".

* In the Publish Tab for Shell Properties click "Application files". Change the Publish Status of ProfileCatalog.xml to "Include."

* Publish as normal.

The Pros of this approach as I see it are:

1) If your application uses RegFree COM then this approach preserves the typelib information that is added to the application's manifest file which allows you to deploy COM components. Mage and MageUI remove this typelib information with updates and signing with certificates (not very handy!).

2) Reduced manual intervention bypassing the use of Mage and MageUI.

Cons:

1) You will always have to remove older versions of your modules and re-add them (remembering to set Build Action and Copy to Output directory properties) for any updates that you make. Likewise for Infrastructure.Layout.dll and Infrastructure.Module.dll