.NET 2.0 C# – Windows Installer and the Connection String

I was working on a project a few months ago and when it came time to deploy, the client wanted to connect to any MS SQL server no matter where they were. Sometimes this server would be local, other times it would not. The IP address might change depending upon which machine it was installed on, and where you were at. So needless to say the client needed an application that could install easily, and allow the setting of the applications connection string during the installation process.

During my time on this part of the project, I looked all over the Internet for something to help me, but to no avail. So I decided I would write a little walk-through to help anyone else in this situation. Let’s get started.

 Step 1 – Make a Setup Project

Okay lets start off by adding a setup project to our current solution. If that sounds confusing don’t worry, it might be. You should already have a solution open, that you’re working in. This would be the software application that you want to deploy, and the application that the connection string need’s to be changed based on installation conditions. So in any event, my application looks like this after i have created a setup project. (Ignore the popup in the middle of the screenshot.) So now you can see that we have added a setup project to our main solution. I called mine PETSetup, PET being the inital project that I wish to delpoy.

It should automatically detect dependancies from your solution and inform you of other resources it will need for the project. One of the most improtant things to include with the setup project is the .NET 2.0 installation. You can leave it out, however if the person installing the product does not have .NET 2.0 framework installed, it will promt them to download it from microsoft. This is usually a hassle for the person installing your software, so just package it together unless you need to keep the install smaller.

The way that you generally navigate around a setup project is by right clicking the project itself. So when i right click “PETSetup” I get a nice little menu. The parts were worried about here is “View” and “Add”. These are where the magic happens in a setup project, you can view different areas of the setup, like the registry entires, UI flow, and other things. I bet you cant guess what you can do with Add, yep, you can add all those things we just mentioned. I will touch on each section a little bit, maybe I can write in more detail in another tutorial, but here is a quick over view.

File System View

In this view you can see what the user is going to have installed on their machine. It allows you to create start menu items, and desktop shortcuts as well as a few other things. Mainly you want to make sure that you have a start menu icon, and a desktop icon for most applications. In fact, it would be even better if you could ask if they want those things before you just throw them all over your users computers.

Registry

Using this view you can tell the installation to add system registry keys. If you don’t know what you’re doing here you can really mess things up so make sure that you’re sure of what you need from this view before you do anything. These are system wide variables that handle system critical information about the operation of you computers software, so don’t change these if you don’t know what they are.

File Types

This is where you tell your setup project what file types are associated with your application. Ever wonder how .doc files get associated with Microsoft Word? They use something like this to tell windows, “hey, all these .doc files open with our program.” Needless to say you can take association away from files that may already have an association with something else, so be careful.

User Interface

In this view, you can see exactly how the installation will flow. This is kind of weird at first as there are two flows you can see, one of them is for a normal user, the other is for the administrator. So if you are making a new installation and both setups need to be the same, make sure you make the additional changes to BOTH setup UI’s or else some of you users are going to get errors.

Custom Actions

I still havent dove all the way into custom actions, these tell the setup what they need to run after certain things happen. So you can tell the setup to roll back some database changes if you have a database installed but they cancel the installation. Really, this is mainly for telling the setup what stuff it needs to run outside of itself, when certain install events happen.

Launch Conditions

In this view we can see what our launch conditions are, imagine that. If you have something that you require from your application like…. Microsoft SQL Express Server, you can add this to the launch conditions and if they end up not having it, they will be notified. Be careful not to add launch conditions, that you don’t bundle with your installation. For instance, if you need SQL Express to run your application, don’t give your installation out, or setup a launch condition, without packaging that inside your setup. You dont want you users to stop installing your program just so they can go download some huge file and install something else.

Step 2 – Making our Custom Installation Dialog

Okay, so by now you have that setup project added to your solution. If you right click on the setup project, and select “Install” it will run for you and you’ll be able to see exactly what it does. When you get done, you can right click and hit “Uninstall” to make sure your program uninstalls correctly. In any event you will notice that there are a set of dialogs that microsoft already has there. If we want to add to these, unfortunately it’s just not as easy as right clicking and adding a new form to our setup project.

Since the project I’m installing is “PET” I know that after I have it installed its actually on the users system, in a location that they specified. So we know that the app.config file (where the connection string resides) is in the directory as well. Before we actually get to editing that, we need to create a form in the project were installing that will handle the input of our connection string. Here is what i made:

This form will take in our datasource, username, password, and then print out the connection string as it’s being built to show the user what it looks like, and in case they want to copy it. (In this case we are making a more technical setup, normally you would hide the connection string, and do it all on the back end.) I also have a check box to let them tell the application if the database is local or not. If it is were going to have a different conneciton string, than if it’s not.

Once that is completed you are ready to move onto the Installation.cs file step 3.

Step 3 – Installation File

In order for out setup project to know that we have an item in our installed project that needs to be run, we make an installer class file. I called this file Installer1.cs It looks something like this:

namespace Pet
{
[RunInstaller(true)]
public partial class Installer1 : Installer
{
public Installer1()
{
InitializeComponent();
Form frm = new frmDBSetup();
frm.BringToFront();
frm.ShowDialog();
}
}
}

This code is really simple, the important part is [RunInstaller(true)] this tells our installer that we want it to run this cose, at a specified time (which we’ll get to later) in our installation. Take note of the use of public partial class, and that it inherits from the Installer class.

As you can see the code has a constructor that makes a new db setup form (from setup 2) and brings the form to the front, and shows it as a dialog. You need to make sure you show it as a dialog instead of a form, so they MUST enter information before they can go back and mess around with the installation. Now you’re ready to move on to the final step.

Step 4 – Custom Actions

We now need to create a custom action to tell our installer to run our new installer.cs file. Go back to your setup project, right click it, select view, and then select “Custom Actions.” Once the screen comes up, right click on the Install file, and select “Add Custom Action.”

The next dialog is kind of confusing so I’ll explain it a little bit here. Since were dealing with an installation, there is no regual file view, or paths, it’s all relative to the installation. So were not presented with hard drives or CD drives, we have different folders for different areas of the installation. In our case were going to select the Application Folder. The next screen will show you all the files that are located in the Application Folder after it is installed on the client machine. What we want to do is make sure that our installer1.cs file is run, so we want to select the “Primary output from PET (Active)” in my case. After that click okay, it should have added to your installation custom actions screen and should look something like this:

Here is where i would take the time to test the installation. Your form currently doesnt do anything but you can at least see that its going to come up when you run the installation. Now we can move on to making the database setup form alter the app.config file to create a custom connection string.

 Step 5 – Editing the app.config connection string from installation

Well you made it this far don’t turn back. You’re almost finished but unfortunately I saved the hardest part for last. I wont go into all the details about how to setup the code, for that i will let you just download the .cs file, its easier than pasting it here and formatting it out for hours on end. But i can go over the important parts. I would recommend having file in front of you here it is: frmdbsetup.doc (In doc format since thats what wordpress allows.)

The most important part of the file is the finish button click event, locate it at the bottom of the frmDBsetup.cs file. Let’s take a look at how we alter the app.config:

Configuration c = ConfigurationManager.OpenExeConfiguration(System.Reflection.Assembly.GetExecutingAssembly().Location);
ConnectionStringsSection section = (ConnectionStringsSection)c.GetSection("connectionStrings");
section.ConnectionStrings["netTiersConnectionString"].ConnectionString = connectionString;
c.Save();

So we start off by making a new instance of the Configuration. Where the real magic happens here is in the System.Reflection.Assembly area, this tells the installer that were going to find the path of where the assembly its executing. Since were launching our dialog, from the application folder, no matter where they install the application, this will give us the path to the directory of the app.config, and esentially their application itself. Pretty neat huh? Once we have the directory, we are free to go about whatever we want. We finish by using the connection string section, it basically grabs the connection strings out of the app.config, and then we just make sure to add our own connection string that we built based off of our nice little dialog form from step 2.

 All Done!

Thats about it, its really not as hard as it seems. There are a lot of questions that come about with deployment of applications, one of the biggest ones is how do you alter stuff after installation. Now you know! You can use this same proccess to do anything you need after installation, the possibilites are endless. I hope you enjoyed learning, and I hope I made everything clear, if you have any questions or commends don’t hesitate to ask. Thanks!