Virtual Developer Workshop: Containerized Development with Docker
Part 1 of this series explained the different ways of deploying a Windows application with the .NET Framework and identified when to use which deployment option. It also demonstrated the configurations that are required to create an installer package. Part 2 examines the different editors that Visual Studio.NET provides and identifies the steps involved in using them.
As Part 1 showed, you can access six types of editors in Visual Studio .NET deployment projects through the View | Editors menu. These types are as follows:
- File System Editor—Adds files and shortcuts, such as Start menu items, to the installation package.
- Registry Editor—Manipulates Registry entries on the target computer.
- File Types Editor—Associates file extensions with applications; useful when your application uses custom file extensions and you want to associate a specific application with that file extension.
- User Interface Editor—Configures the dialogs that are shown during the installation.
- Custom Actions Editor—Starts external programs during installs and uninstalls.
- Launch Conditions Editor—Specifies the requirements for your application to be installed on the target computer.
Editors in Visual Studio .NET Deployment Projects
The following section takes an in-depth look at each of these editors, beginning with the File System Editor.
File System Editor
As its name suggests, the File System Editor allows you to add project output files, assemblies, and other files to the deployment project. By using this editor, you also can specify the directory location where these files will be installed on the end user's computer. You can open the File System Editor by selecting View->Editor->File System. The menu looks like Figure 1.
Figure 1: File System Editor Menu
By using any of the pre-defined folders displayed in Figure 1, you can choose a destination folder on a target computer without even having to know the actual path to that folder. The installer determines it from the virtual path during installation. Take a brief look at each of the pre-defined folders and their purposes:
- Application Folder—Application Folder is normally represented by the path [ProgramFilesFolder][Manufacturer]\[ProductName]. On English systems, the [ProgramFilesFolder] folder resolves to [Drive Name]\Program Files by default. The Manufacturer and ProductName directories take their names from the settings that you defined while setting the project properties. End users also can override these settings while installing the application.
- Global Assembly Cache folder—This folder allows you to specify the assemblies that must be installed as shared assemblies on the target computer.
- User's Desktop—This folder acts as a placeholder for files and folders that should appear on the end user's desktop. The default location for this folder is [DriveName]\Documents and Settings\[UserName]\Desktop. The username represents the name of the user who performs the installation.
- User's Programs Menu—This folder acts as a placeholder for entries that should appear on the programs group of the user. The default location for this folder is [DriveName]\Documents and Settings\[UserName]\Start Menu\Programs. The username represents the name of the user who performs the installation.
Apart from these folders, you also can add custom folders to the File System Editor from a pre-defined list. To display the list of special folders, right-click the File System on the Target Machine folder from the File System Editor and select Add Special Folder from the context menu.
Add Items to Special Folders
By using the File System Editor, you can add any of the following items to the special folders:
- Folder—Allows you to create a folder on the target machine in the specified directory
- Project Output—Allows you to specify where the output of one or more projects (.dll or .exe files) in the solution will be deployed on a target computer; also adds all the dependencies to the folder
- File—Allows you to deploy loose (zero compression) files to a target computer; very useful for deploying help files such as Readme.txt
- Assembly—Allows you to specify the assemblies that need to be added; adds all the referenced assemblies as well
Now that you've seen the different editors, configure your deployment project using the File System Editor. The following steps will use the FormattingApplication from the previous article. The first step in creating a setup is specifying which files you want to copy to the target computer:
- Add the primary output of the FormattingApplication to the installer using the Project | Add | Project Output menu. After selecting the Application Folder directory, select Primary Output in the Add Project Output Group dialog box. Pressing OK in the dialog box adds the primary output of the FormattingApplication project to the Application Folder of File System Editor. At the same time, it also adds the dependencies to the installer project.
- The FormattingApplication requires the .NET runtime, which it automatically adds to the installer project. As a result, the merge module for the .NET runtime dotnetfxredist_x86_enu.msm becomes visible in the Solution Explorer. This merge module includes all files for the .NET runtime. If the .NET runtime is not already installed on the target system, it will be installed along with your application.
This case requires that the .NET runtime be already present in the target machine. So, you'll exclude this file from the package. Select the file dotnetfxredist_x86_enu.msm and then set the Exclude property to true through its properties window.
- Now, add the additional folders and files. Right-click on Application Folder in the File System Editor and select Add->Folder. Name the created folder Support. This folder serves as a placeholder where you'll store all the supporting files for the application.
- Right-click on the Support folder and select Add | File, and then add the files readme.rtf, license.rtf, Readme.txt, and developer.bmp.
- Readme.txt should be available as an individual file so the end user can read that information before the installation. Make it a loose file (uncompressed) in the installer package. Select Readme.txt from the Support folder and select View->Properties Window. Change the PackageAs property to vsdpaLoose. This new setting overrides the setting vsdpaDefault, which packages the overall application.
- Add a provision that allows users to create a shortcut to the FormattingApplication in their desktops. As before, you'll need to add the shortcut to the User's Desktop folder. Right-click on Primary output from the FormattingApplication (Active) item in the Application folder and select Create Shortcut to Primary output from FormattingApplication (Active) from the context menu. Rename the shortcut Formatting Application. Drag and drop it in the User's Desktop folder. However, you want this shortcut to be installed only if the user wants to install it. Therefore, set the Condition property of the User's Desktop folder to SHORTCUTDEMO. This ensures that the shortcut will be installed only if this condition is set to true. Later in this article, you will create a dialog box where this property can be set.
- Make the program available from the Start->Programs menu by adding a shortcut to the User's Program Menu folder. Create another shortcut as before, renaming it Formatting Application. Drag and drop this shortcut in the User's Program's Menu folder. This time, you want this shortcut always to install so don't alter the Condition property.
The Registry Editor allows you to manage the Registry settings on the target computer where the application will be installed. By default, the Registry Editor displays the standard Windows Registry keys, such as HKEY_CLASSES_ROOT, HKEY_CURRENT_USER, HKEY_LOCAL_MACHINE, and HKEY_USERS. By using the Registry Editor, you also can add custom Registry keys under any of the above keys. Selecting View->Editor->Registry from the menu displays the Registry Editor shown in Figure 2.
Figure 2: Registry Editor
To add additional Registry information that your application requires at runtime, you can use either HKEY_LOCAL_MACHINE\Software\[Manufacturer] or HKEY_CURRENT_USER\Software\[Manufacturer]. Be sure to add the application-specific information under the value specified in the Manufacturer property.
File Types Editor
The File Types Editor allows you to set up file associations on the target computer by assigning an application to a file extension. Double-clicking the file in turn launches the correct application. Once the initial association is done, the extension and the file type description appear in the file types list in Windows Explorer. This is very useful if your application uses custom file types that require a separate external application to be launched. The following are important properties associated with the File Types Editor:
- Name—Specifies the name used in the File Types Editor to identify a particular file type
- Command—Sets the executable file that should be launched when the user opens a file with this type
- Description—Provides the description for the file type
- Extensions—Specifies the file extensions with which the executable should be registered
- Icon—Specifies an icon to be displayed for the file type
- MIME—Specifies one or more MIME types to be associated with the selected file type
- Verb—Specifies the verbs (such as open, edit, and play) that are used to invoke the selected action for the file type
Custom Actions Editor
The Custom Actions Editor allows you to link to another program that can be launched at the end of the application install. To create a custom action, you need to create a .dll or .exe file that performs the custom action and add it to the deployment project. The custom actions can be launched only at the end of the installation. Custom actions can be associated with any one of the following four installation outcomes:
For example, if you want to launch a specific external program after installing the application, you can accomplish this by associating that external program with the Install node.
Launch Conditions Editor
By using the Launch Conditions Editor, you can specify conditions that must be met in order for the setup to run. If the user tries to install the application on a system that does not meet the launch conditions, the setup will not run. While setting the launch condition, you also can specify that searches be performed on the target computer to determine the existence of items such as a particular file, Registry key, component, and so on.
This editor has two sections to specify the requirements:
- Search Target Machine—Allows you to specify the kind of search that needs to be performed on the target computer (may include search for a specific file, Registry key, and so on)
- Launch Conditions—Allows you to define the conditions that need to be met to before allowing the application setup to be launched (one is already defined for the setup application)
For example, by using the Launch Conditions Editor, you can configure any of the following conditions:
- File Launch—Searches for installed files on the target system
- Registry Launch—Searches for Registry keys before the start of the installation
- Windows installer launch—Searches for Windows Installer files
- .NET Framework launch—Checks for the .NET Framework on the target computer
- Internet Information Services launch—Check for the installed version of IIS
While adding the primary output of the FormattingApplication project to the installer, you excluded the .NET runtime file (dotnetfxredist_x86_enu.msm) from the installer package. Therefore, you will check for the existence of the .NET runtime on the target computer by using the .NET Framework launch condition. To do this, you need to perform the following steps:
- Open the Launch Conditions Editor by selecting View | Editor | Launch Conditions.
- Add a launch condition using the Action | Add .NET Framework Launch Condition menu. Set the Name property to CHECKDOTNETCONDITION.
Now that you have set this launch condition, if the user tries to run the installation without having the .NET Framework installed, the installation will not run.
User Interface Editor
As its name indicates, the User Interface Editor permits you to specify the sequence of user interface dialogs displayed during the application install on the target computer. (You will see an example of this later when you configure these dialog boxes.)
The User Interface Editor consists of two high-level installation modes:
- Install—The Install section lists all the dialog boxes that will be displayed when the end user runs the installer.
- Administrative Install—This section lists all the dialog boxes that will be displayed when a system administrator uploads the installer to a network location. \
The pre-defined dialog boxes in the Install and Administrative Install sections can be further sub-divided into the following three categories:
- Start dialog boxes—Display before the installation begins
- Progress dialog box—Allows you to provide the users with feedback on the progress of the installation
- End dialog boxes—Informs user that the installation has successfully completed; can also be used to allow the user to look at the Readme file or launch the application
You can easily rearrange the dialog boxes by dragging and dropping them onto other locations. The above-mentioned default set of dialog boxes always shows up in the installation sequence of the application, even if you have not configured them.
Now that you have had a look at the dialog boxes, it's time to learn how to configure them for setting up your FormattingApplication. Here are the steps:
- Select the Welcome dialog and then select the View | Properties window. Set the BannerBitmap property to developer.gif by clicking Browse... in the combo box and navigating to the Application Folder\Support (where you already placed all the support files). Also set the CopyrightWarning and WelcomeText properties to values that suit your requirements.
- Because you want the logo bitmap to display on all the default dialogs, set the BannerBitMap property to developer.gif in the Installation Folder, Confirm Installation, Progress, and Finished dialog boxes as well.
Add Additional Custom Dialogs
In the previous section, you configured the properties of the default dialogs, which are very flexible and can form the core foundation for simple installations. However, sometimes you may want to customize the installation sequence to support your application's requirements. You can accomplish this by adding a new set of dialog boxes with the Add Dialog menu. Select Start from the User Interface Editor and then choose Action | Add Dialog menu. Figure 3 shows the Add Dialog window you will see. It will only contain the dialogs that you can add, so you may see a slightly different selection.
Figure 3: The Action | Add Dialog Menu in the User Interface Editor
You can choose the dialog box you want to add to your installation sequence from this menu. The following list briefly discusses these dialog boxes and the dialogs already present by default:
- Welcome—Allows you to display an introductory window that can display text information from CopyrightWarning and WelcomeText properties
- Customer Information—Allows you to display a window that requires customer information such as name, organization name, and so on; also can force the user to enter a serial number and perform simple validations
- License Agreement—Allows you to display licensing information that requires the users to agree to the licensing conditions; obtains licensing information from an external file, which is linked to this dialog through the LicenseFile property that can be assigned a Rich Text Format (.rtf) file
- Read Me—Displays information from the .rtf file specified by the ReadmeFile property
- Register User—Allows users to complete the installation by asking them to register the installation; displays a Register Now button that either launches an external executable or takes the users to a Web site. (You specify the information about the external application and the arguments to be passed to it through Executable and Arguments properties, respectively.)
- Splash—Displays the company logo (that you can set through the SplashBitmap property) at the beginning of the install
As you can see, the Windows Installer is very restricted. It doesn't allow you to design custom windows and add them to the deployment project. However, Windows Installer does define a standard approach for creating installers that are consistent and simple to use. In this section, you add some additional dialog boxes to your installation sequence by using the Add Dialog menu. Here are the required steps:
- Select Start from the User Interface Editor and choose the Action | Add Dialog menu.
- In the Add Dialog box, select the Checkboxes (A), License Agreement, Read Me, and Splash dialog boxes, and then add them to the Start sequence.
- Drag and drop the dialog boxes into the proper sequence, as displayed in Figure 4.
- To have the developer.com logo display on all of these additional default dialogs, set the BannerBitMap property to developer.gif.
- Select the License Agreement dialog box and view its properties window. Change the LicenseFile property to license.rtf.
- Select the Read Me dialog box and select View | Properties Window to bring up its properties window. Change the ReadMeFile property to readme.rtf.
- Use the Checkboxes (A) dialog box to ask the user whether the demo shortcut you placed in the User's Desktop folder should be installed or not. Modify the properties of this dialog box to match the Figure 5 screenshot.
- Remember to set the CheckBox1Property to SHORTCUTDEMO. This value is the same as the Condition property that you set for the User's Desktop folder in the File System Editor. If the user selects this checkbox during installation, the value of the SHORTCUTDEMO condition is set to true. As a result, the shortcut installs on the user's desktop. If the user does not select this checkbox, the SHORTCUTDEMO condition is set to false and the shortcut does not install. In the Figure 4 dialog, you also set the Visible property for the rest of the checkboxes to false to prevent them from being displayed.
Figure 4: The Proper Sequence for the Dialog Boxes
Figure 5: Modified Properties of Checkboxes (A) Dialog Box
Build the Installer Package
Now that you have configured all the editors and set all the options, you can build the installer project. Select Build | Build Solution from the menu to create the MSI installer package. Once the installer is successfully built, you will see the files shown in Figure 6 in the Release directory of your installer project directory.
Figure 6: Files in the Release Directory of Your Installer Project Directory
The Readme.txt file appears as a single file because you set the PackageAs property to vsdpaLoose when you configured the File System Editor. In addition, you see two variants of Windows Installers: one version (InstMsiA.exe) for Windows 98/ME; another version (InstMsiW.exe) for Windows NT/2000/XP.
Install the FormattingApplication
To install the FormattingApplication, you can use either of the following options:
- Double-click on either the FormattingApplicationSetup.msi file or the Setup.exe file from Windows Explorer.
- Right-click on the FormattingApplication.msi file and then choose Install from the context menu.
Now, follow the steps for installing the FormattingApplication on the end user's computer. Start the installation by double-clicking the FormattingApplicationSetup.msi file from Windows Explorer. The following steps lead you through the installation:
- Splash screen—The first dialog, appears after a popup window that states Preparing to install; displays the bitmap you specified using the SplashBitmap property.
- Welcome dialog box—The next dialog; displays the developer.com logo because you set the BannerBitMap property to it.
- Read me dialog box—Displays the contents of the readme.rtf file that you specified using the ReadMeFile property; also displays the developer.com logo.
- License Agreement—Displays the contents of the license.rtf file that you specified using the LicenseFile property; also displays the developer.com logo. (The Next button in the dialog box is enabled only when the user selects the I Agree option, thereby making sure that the user agrees to the licensing terms and conditions.)
- Shortcut checkbox dialog box—Asks the user whether he or she wants a shortcut to the application to be installed in his or her desktop. (When the user checks the checkbox, he or she sets the condition SHORTCUTDEMO to true, thereby installing a shortcut to the application on the desktop.)
- Installation folder—Displays the path to the installation folder where the application will be installed; also provides the user with an option to change the installation folder, if required. (You also can specify whether you want to install the application only for yourself or make it available to everyone who will be using that computer. You can also find out how much disk space is required to install the application by clicking the Disk Cost button.)
- Disk cost—Helps identify the suitable drive (that has enough space) in which the application can be installed; displays the amount of disk space required for installing the application, as well as the free space available in each drive.
- Confirm Installation—Allows you to provide the final confirmation before the application install can proceed. (Clicking the Next button on this dialog box installs the application on the user's computer. Its progress is displayed in the Progress dialog box as a progress bar.)
- Finished Installation—Once the installation is complete, you see the Installation Complete dialog box, which confirms that the installation has successfully completed.
Uninstalling and Repairing the Application
Now that you have successfully installed the application, consider the uninstall process, which is very simple. Just open up the Add/Remove Programs window on the end user's computer by going to Start | Control Panel, and then double-click the Add/Remove Programs icon. Now, all you have to do is click the Remove button and a confirmation dialog box (asking you to confirm the uninstall process) appears. If you click Yes, the uninstall process begins and the application is completely removed. You also can uninstall the application by right-clicking on the FormattingApplicationSetup.msi from Windows Explorer and selecting Uninstall from the context menu. When you right-click on the FormattingApplicationSetup.msi file, you also see the Repair option in the context menu, which is very useful when you accidentally delete any of the application-related files from the machine and need to bring the application back to its original state.
What You've Learned
In this article, you learned the different aspects of deploying a Windows forms application. The discussion began with an introduction to deployment and its fundamentals and then went on to cover the different types of deployments supported by .NET. Specifically, the article covered XCOPY deployment and Windows Installer-based deployment.
After considering both types, you learned why the features that Windows Installer offers make it the preferred choice. Then you walked through a complete Windows forms application deployment using the Visual Studio .NET installer, including customization with various editors, installation on an end user's computer, and the uninstall process.