ADDING USER INTERFACES (FORMS) TO YOUR INSTALLER CLASS
You can implement windows forms into your Installer Class fairly easy. First you should add a Reference to the System.Windows.Form namespace to your Installer Class project.
Then, add a reference to this namespace at the top of your installer class, with the following using statement:
Code:
using System.Windows.Forms;
|
Next click on Project (in your installer class IDE) followed by Add Windows Form; that's partially it. This form will contain all the control your installation requires.
Now, within any of the Installer Class events you can open the form with the code below:
Code:
frmMonitor f = new frmMonitor("Install"); f.ShowDialog();
|
In the example, the form was named frmMonitor and it is taking a single parameter. We passed Install to it (as shown in the code); You should always keep in mind that installer classes have different "installation modes", such us Install, Commit, Rollback and Uninstall. You may implement individual forms for each one of these modes or a single one capable of handling any combination of them; the latter will require a parameter telling the form the "installation mode" taking place, but the choice is yours.
Also notice that the form is shown as a dialog (ShowDialog()). It should be like that to prevent the event completion before the user even gets a chance to see your form.
Based on the explanation given in this section so far, the screenshot below was taken from an installation having an Installer Class with a form showing the Install event's Context and stateSaver dictionaries on its form's multi line textbox:
The form on the latest example receives three parameters in one of its constructors, as shown below:
Code:
public frmMonitor(string eventName , System.Configuration.Install.InstallContext context , System.Collections.IDictionary savedState ) {
|
Where:
- eventName is the name of the event calling the form.
- context is the variable receiving the Installer Class context dictionary. Notice its type, which is System.Configuration.Install.InstallContext
- savedState is the savedStated parameter received by the Installer Class's event.
The Installer Class's Install event code is shown below:
Code:
public override void Install(System.Collections.IDictionary stateSaver) { base.Install(stateSaver); stateSaver.Add("TargetDir", Context.Parameters["DP_TargetDir"].ToString()); frmMonitor f = new frmMonitor("Install", Context, stateSaver); f.ShowDialog(); f.Dispose(); }
|
The tricky part of the example is how to pass around the Installer Class Context object.
KEEPING THE MOUSE WITHIN THE FORM SHOWN AS ShowDialog()
Although the form is shown by the ShowDialog() method, the mouse can move away from it, able to click on the Installer main form displayed behind it, this is an undesired behaviour, it probably happens because your form and the Installer are running on different threads, you can prevent this behaviour by trapping the mouse within your form boundaries. Any attempt for the mouse to leave your form borders will keep it inside it, you can do that with the form's MouseMove event, as explained next:
You should declare a couple of private variables, _X and _Y, they will keep track of your mouse position within the form.
private int _X; // mouse's X position private int _Y; // mouse's Y position |
Then within the form's mouse move event, you record the mouse current position like this:
private void Form1_MouseMove(object sender, MouseEventArgs e) { _X = e.X; _Y = e.Y; } |
Now, when the mouse tries to leave the form, you can keep it inside its boudaries by using the Mouse Leave event, with the code show next:
private void Form1_MouseLeave(object sender, EventArgs e) { if (Cursor.Position.X < this.Left + 4 || Cursor.Position.Y < this.Top + 30 || Cursor.Position.X > this.Left + this.Width - 5 || Cursor.Position.Y > this.Top + this.Height - 31) { Cursor.Position = new Point(this.Left + _X + 4, this.Top + _Y + 30); } } |
Here the constants 4, 5, 30 and 31 are related to the form borders and title bar, if your form does not have border or a title bar, you should adjust the code above accordingly.
I tested the code above with the following form:
The mouse pointer was able to "escape" from the form when moving it really fast over the buttons (side ways) or any control on the form, my guess is that the mouse events on those controls obscures the form own mouse events allowing the mouse pointer to escape, once I made the form higher and widers, it was most difficult for the mouse pointer to escape.
LAUNCH YOUR APPLICATION AFTER INSTALLATION
You can launch your application once it has been installed with the Installer Class' Commit event. Although possible, you should carefully assess implementing this feature, particularly so, when your application has any dependency with any installed component that requires rebooting the workstation (Target Machine); in the latter case, your application will mercilessly crash on the user installing it.
Now that we are aware of the disclaimer, you should add a reference to the System.Diagnostics at the top of your Installer Class code:
Code:
using System.Diagnostics;
|
Then you can launch your application with this code located at the Commit event in your Installer Class.
Code:
public override void Commit(System.Collections.IDictionary savedState) { base.Commit(savedState); // let's launch the application
Process.Start(@savedState["TargetDir"].ToString() + "Testings"); }
|
Comments:
CONCLUSIONS
- Visual Studio Setup and Deployment Projects' Installer Class implementation as Custom Actions expose powerful features at your disposal to create very professional and robust installation packages for your applications.
- It will take a while to master the different features exposed by the Installer Class. We strongly recommend throughly testing them before distributing your application,. Keep in mind that first impressions count in your users (customers) mind. You don't want your application to crash at installation time, or end up having to request your customers to apply several changes to the environment to complete your application installation; It will be wise to test your installation package on a Virtual PC environment or any spare PC made available to you.
- Unhandled exceptions are your worst enemy when developing and implementing Installer Class objects. You should carefully assess the code you are using without taking risky assumptions. Keep in mind that the Target PC where your application will be installed on, is not within your control.
Remember, this article is based on VS 2005 Setup and Deployment Projects and its Installer Class object. Although previous versions of Visual Studio support them (Installer Class objects) you should consider testing your functionalities if you are not using VS 2005; They may well work, Provoding that everything is hooked properly.
At the time we wrote this article, the installation's Rollback event was failing to fully delete the TargetDir on the target PC.
- There is no limitation (or we are not aware of any) on the number of Installer Class objects your Setup and Deployment Projects can reference. Based on this, you should not overload your Installer Class object with many functionalities making them very complex. Think about implementing specialized Installer Class objects instead.
- You should become familiar with the Environment and Application objects when developing Installer Class modules. Both objects expose helpful properties, like the operating system version, so keep an eye on them.
REFERENCES
This article is based on self experience creating Setup and Deployment Projects and reading several articles from the MSDN site and other authors. Some interesting articles are listed below, you may find them helpful or lead you to other articles associated with deploying applications.
Walkthrough: Creating a Custom Action
Walkthrough: Using a Custom Action to Display a Message at Installation
CustomActionData for InstallerClass actions must be in format '/name1=value1 /name2=value2'
Walkthrough: Using a Custom Action to Create a Database at Installation
Custom Actions Management in Deployment
Error Handling in Custom Actions
How to: Add Predefined Custom Actions in the Custom Actions Editor