Build Installer Projects for C# Application Deployment

Last Update: 2 March 2005

Overview

You've worked frantically to get your C# application finished and it is finally tested and ready to go. Now you need to bundle everything into a neat package so that it can be distributed and easily installed to your end user's or customer's site. You can use a Visual Studio.Net Setup and Deployment project to do this. Not only can you create install packages for your executable programs but you can bundle in source files for developer projects and have them installed too. This can be useful when you want to move an entire development project from one developer's integrated development environment (IDE) to another in a complete and easy-to-install package.

Prerequisites

.NET applications need the .NET Framework in order to run on the target machine therefore we must make sure that the target machine for distribution has it. One way to do this is to download the .NET Framework Redistributable from the Microsoft site then include the dotnetfx.exe package with your distribution file. You could give users instructions on how to install the framework and then you could go install the application. This is fine for more technically-inclined users however, more often than not, the target user population does not have the technical familiarity to do something like this. It is much more efficient to include the .NET Framework with the deployment project so that it becomes a step in the installation process.

There is a package known as the "Bootstrapper Plug-in" that will enable you to bundle the .NET Framework in your deployment package. The user will be asked if installation of the .NET Framework is desired prior to installing the actual application. You can find information on downloading and installing the "Bootstrapper Plug-in" at the following link:

http://msdn.microsoft.com/vstudio/downloads/tools/bootstrapper/default.aspx?pull=/library/en-us/dnnetdep/html/vsredistdeploy1_1.asp

After you download the bootstrapper software, you want to make sure that it is running by going to the contol panel and add/remove programs screen. You should see the "Microsoft Visual Studio .NET 2003 Bootstrapper Plug-In" running. This is absolutely critical that it is actively running on your system.

Deployment Project Building

Now we will go through the steps for building a Visual Studio .NET 2003 Setup and Deployment project. For our example, we will deploy the ADONetTutorial Project. This application can be found at the following link:

http://www.codersource.net/csharp_adonet_tutorial_ed.html

Install the application on your system then open up Visual Studio .NET and select the ADONetTutorial solution. The Solution Explorer window in the IDE will probably look like that in figure 1:

Figure 1

What we are focusing on is the Solution Explorer window to the right. We are going to be adding a deployment project to it. From the main menu bar in Visual Studio .NET we want to select File, Add, Project, and New Project. Now we are presented with the "Add New Project" window. We want to select Setup and Deployment Projects in the Project Types tree. We want to select Setup Project in the Templates window. And finally, we want to type in the name of our associated setup project. We'll call it ADONetTutorialSetup. Figure 2 shows a picture of this dialogue:

Figure 2

Once we press OK, we will see a Solution Explorer window similar to what is in Figure 3. You now see that the setup project is part of the Visual Studio Solution ADONetTutorial.

Figure 3

We now have our project area defined for our Setup project. The next step is to add files to the setup project. Go back to the Solution Explorer window and right-click on the Setup Project name ADONetTutorialSetup. Select the "Add Files" menu option and you will be presented with a dialogue to begin adding the individual files. If you are making a runtime distribution, you only want to include the .exe file and any .dll files that go with the application (under the References node for the main project). This particular application uses a Microsoft Access database so you want to include the .mdb file for it as well. Since this particular project calls no .dll files, we should see a configuration such as that displayed in figure 4 when we are finished adding files.

Figure 4

Everything is in place now to build a setup file which will have a .msi extension. One way to do a build is to right-click on the ADONetTutorialSetup node in the Solution Explorer window and you will be presented a menu with a "Build" option. Click the "Build" option and your setup project will get built. Any errors in the build will get reported in the Output window as usual. After the build, you will see a subfolder in your project folder named after the setup project. For purposes of our example, there will be a subfolder named ADONetTutorialSetup and within it will be a Debug and Release folder along with a Visual Studio Deployment project named ADONetTutorialSetup. Figure 5 shows the folder's objects:

Figure 5

And, since this project was built in a debug configuration, our installer files will be in the Debug folder in Figure 5. Figure 6 shows the contents of the Debug subfolder:

Figure 6

There are two icons in the above folder. One is a standard .msi installer package (ADONetTutorialSetup.msi) while the other is a Visual Studio Installer Bootstrapper application (Setup.exe). What is a Bootstrapper? If you run either one of the icons, it seems they both do the same thing. They both install the ADONetTutorial project on your PC. That's only true if you have the .NET Framework installed on your machine already. However, if you don't have the .NET Framework Redistributable installed, the bootstrapper setup application will install it on the target machine if you request it.. This is how you get applications to an end user who does not have any .NET Framework on their machine. A .NET application will not run on a machine without the framework. The bootstrapper will also install the application ADONetTutorial.exe. Note that you must send the folder in figure 6 as a complete package to the target user because the file dotnetfx.exe (which is the .NET Framework package) is used by Setup.exe to install the framework on the end user's machine. 

After running either the setup.exe bootstrapper or the .msi file, your application will end up in the folder C:\Program Files\<Machine Name>\<Project Name>. You will see AdoNetTutorial.exe in that folder along with the database ADONetTutorialDb.mdb. Double-click on the application and it runs.

This is fine if you want to navigate to the target folder where it the application is installed all of the time. However, most distributions require that a shortcut be placed that is accessible from the users "Start" and "Programs" menu. The next section describes how to configure in the directive to install the shortcut on the user's Programs menu.

Controlling Target Menus

We will want most commercial-grade applications to have a shortcut placed in the users "Programs" menu instead of navigating to the program files folder for our project. We can configure and navigate this in Visual Studio .NET 2003. To add a shortcut to the application in the Programs menu, we need to select the ADONetTutorialSetup project on the Solution Explorer and then pick the File System tab. You will see something like what is displayed in figure 7:

Figure 7

What we want to do is a right-click of the mouse on the window area to the right of the window with the three folders in it. Choose the Create New Shortcut choice on the menu and you will be presented with a dialogue asking you to pick which folder you want the shortcut created in. Pick the application folder and you will then be presented with the dialogue as shown in figure 8:

Figure 8

You want to then pick the .exe program file and after pressing OK, you will see the shortcut appear in the window just to the left of the solution explorer window. You can change the properties on this shortcut so that the text will appear a certain way on the programs menu in Windows.

A Code Library Model

I use the setup and deployment function to also distribute the source code to my applications. You many have customers who require source code as well and putting these files as part of the overall Visual Studio solution is no problem. You basically add the source code files such as those ending with .cs in the solution explorer at the far right. If a certain file is in a subfolder to the main project folder, you can create this folder underneath of the three main folders in the File System Window. Figure 9 shows an example of another Visual Studio solution with all of the source code and .dll class library projects added. It is a Visual Basic .NET project however the concept remains the same for C#.NET projects.

Figure 9

Summary

We have only discussed some of the basics when it comes to creating Visual Studio .NET 2003 Setup and Deployment projects. Take some time to explore the robust set of features provided in the Visual Studio package when it comes to making this type of project. What is really nice is the ability to keep everything, including the installation process, in one nice, neat package that can be easily moved from system to system. The ability to bundle the .NET Framework in your setup project makes your application even more portable. This feature in the Visual Studio .NET 2003 package helps to alleviate some of the difficulties associated with deploying projects when they are ready to be distributed.