Introduction
Even though Cassini is the default development web server in Visual Studio, Microsoft has provided a stand-alone option that also integrates with Visual Studio. IIS Express is almost exactly like the full IIS, only it is self-contained, it isn’t a service, and it doesn’t need admin rights for most tasks. We are going to walk through how to get it, how to configure it, and how to make the most of it without spending a lot of time on it.
Background
In the beginning, there was Cassini and it was bad. Cassini is the web server that is shipped with Visual Studio. It is also known as the “Visual Studio Development web server” or “ASP.NET Development Server”. Whenever you wanted to test out a web application on your computer, you would start the debugger and the following icon and message would pop up in your system tray:
That indicated that a small webserver had been launched on a random port and it was hosting your application. That way, when the browser was launched, you could see your site in action. OK, that’s cool but there were a lot of limitations. For one thing, it only worked on your local computer. You couldn’t open up your firewall and have your buddy test out your site. It also didn’t play nice with SSL or other instances of Cassini. Speaking of which, if you weren’t careful, you would end up with multiple instances of Cassini running on your computer at once. Basically, a nice idea but the implementation was lacking. Enter IIS Express.
Getting IIS Express
To get IIS Express, you can either install WebMatrix or you can install the stand-alone version of IIS Express. The direct download can be found here:
http://www.microsoft.com/en-us/download/details.aspx?id=1038 This raises an interesting point of interest: IIS Express is not tied to Visual Studio. This is an awesome feature because it means we can use it for other website development projects. In fact, IIS Express supports PHP as well as the standard HTML files. That alone puts this web server a step ahead of Cassini and we are just getting started.
Configuring Visual Studio
Once IIS Express has been installed, you will need to update Visual Studio to use the web server. This can be on a per-project basis or it can be the default for all new projects. To change one project over to using IIS Express, simply right-click on the project and select “Use IIS Express…” like so:
You will be asked if you want to configure your project to use IIS Express. This step will change your project properties and it will update a user-specific configuration file that IIS Express uses to know which sites go where. The prompt should look something like this:
When you hit yes, the changes will be made and you will be informed what the new URL for your site will be, like so:
You have now done everything necessary to configure IIS Express to work with your application. Simple, huh? Before we move into why this change is so significant, let’s tell Visual Studio to use IIS Express as our default development web server. It turns out that this, too, is quickly accomplished. In Visual Studio, select Options under the Tools menu. Inside the Options, there is a Projects and Solutions section. Under that is the Web Projects sub-section. When you select that you will be overwhelmed with the choices you are presented with…OK, so there is only one checkbox. Check the box that says “Use IIS Express for new file-based web sites and projects”. Here is what it looks like:
You have now performed the arduous task of setting up IIS Express to be the default development web server for Visual Studio. This includes ASP.NET sites, WCF sites, and other web projects.
The Benefits of IIS Express
For such a simple application, there are a lot of really great benefits that you will experience as a result of using IIS Express. Here is a list of what I see as the important benefits (each links to the section below that explains how to configure it and what it does):
Each of these items has a section below dedicated to showing you how they work. However, you only need to use what your project requires. You have already done all of the configuration you will need for most projects. Look at the information below as a “what else can it do” rather than a “what do I need to do yet”.
SSL Configuration
It used to be that in order to test SSL, you needed to create a self-signed certificate and host it on a full web server on your machine. The steps were numerous and a bit complicated, especially if you weren’t very confident of what you were doing. Here is a good article on how to create a self-signed certificate in IIS 7 (which, as the article points out, is much easier to do than in previous versions): Create a Self Signed Certificate. Compare that to the steps we need to do: Select your project and view the properties. In the properties, set SSL Enabled to True. I think we all owe the developers of IIS Express a coffee or something for that little gem. It doesn’t get much easier than that.
Just to be clear, you do not modify the project properties but instead change the setting in the properties when you select the project. For whatever reason, Microsoft decided to name the property sheet of a project “Properties” when there was already the “Properties” window. Here is a screenshot to make it clearer:
Notice also that there are other options on this property sheet that you can play with. For instance, you could disable anonymous authentication or enable Windows authentication. Not bad for a couple of simple properties. One important thing to note here is that the certificate won’t be trusted. You will still be told “This certificate is untrusted” when you browse to the site. This is fine. You aren’t testing the certificate itself, but how the site responds on SSL.
One quick note here is that IIS Express is set up to use ports 44300 through 44399 for SSL. If you change to a port outside that range for SSL, you will get an error. I have seen a lot of “solutions” for changing to the default 443 port but most don’t work. The one way I found that works is to follow Scott Hanselman’s directions here: Using SSL on 443
Virtual Directories and Custom Pathing
There are times when you need to test out how a site will interact with another site. Maybe you are developing two sites at once and one refers to another using a relative URL. Again, IIS Express to the rescue. To modify the default path of your application, open the Properties sheet under your project. In the tabs on the left, select Web. Under the Servers section, you will see the Project URL. You can modify this by adding a path to the end of it and then selecting Create Virtual Directory. For sites that work together, you can also change the port to match that of the other project so the two will use the same root path. For example, I will modify my application to operate out of a folder underneath an application I already have running on port 21000.
First, I open the property sheet to the right location. My current config looks like this:
I modify the Project URL to point to the new port and a virtual directory called Demo. I click the Create Virtual Directory button and get this message:
Now when I launch this website, it will operate on the same port as my other site. The way it does this without conflict is because it is using the Virtual Directory. Now my first site can access this site using the relative path of /Demo.
Running Your Site without the Debugger
IIS Express isn’t a part of Visual Studio; it just plays nicely with it. That means it can serve up your site without the debugger running. In fact, it is a misconception to think that the way you start IIS Express is by starting the debugger. That definitely does it, but that is just a convenience. IIS Express can run your site independently of Visual Studio. The benefit here is that you can make changes to your project, hit the save button, and then refresh your browser to see the results instantly. If you change back-end code, you will need to do a project build before you refresh the page. Either way, this is a great option. Now you can keep your site running all day while you tweak it. As you will see, there are other benefits to this feature as well.
Watching Your Site Work
Like I mentioned before, starting IIS Express through the debugger is just a convenience. In fact, it probably isn’t the best way to launch IIS Express. A better way to launch the web server is through the command line. Doing so gives you a few features that you would otherwise not have. One of the best benefits is that you will be able to see each request and the result of the request with HTTP status codes. This can be especially useful when you are debugging a site. Identifying that you are sending a GET instead of a POST is easy and it will save you a lot of time.
To run IIS Express from the command line, open up a command prompt (type cmd in the search box of your Start Menu and hit enter) and type the following:
cd %programfiles%\IIS Express
for 32-bit operating systems or
cd c:\Program Files (x86)\IIS Express
if you are on a 64-bit machine. That puts you in the proper directory. Now you can run IIS Express using the following command:
iisexpress /site:[site_name]
The site name is usually the name of your project. However, if you have made changes to your site or if you have created a couple different configurations for your project, that may not work. One easy way to determine your site name is to run the debugger and then check the system tray icon. It will tell you the names of the sites that are running. Once the site is running, your command window should look like this:
IIS Express is now running and waiting for activity on your site. In the text that is already displayed, you can see what protocols are enabled and on what ports. In this case, I’m actually running the same site on both HTTP and HTTPS. Let’s browse to the root of our HTTPS site to see what the command window shows us:
When the request was finished, I saw the above four lines show up. First, I see that I made a GET request to my HTTPS site. The request ended with a HTTP status of 200 (success). Then a second GET request was made for the favicon.ico file. I don’t have one of those on my site, so a HTTP status of 404 was returned. On my site, everything looked like it worked. I would not have known that I was actually doing two round-trips and that one was returning a 404. This feature was already helpful in a small demo project. Imagine what it can do when you are passing JSON requests around in a full MVC site, along with GETs and POSTS. It may not be Fiddler, but it is still very useful.
Running Multiple Sites
Why is it that best practice encourages us to break apart monolithic applications and yet our tools expect us to only have one website running at a time? Here in the real world, I often find myself developing applications that interact with other websites and services. Fortunately, IIS Express again comes to our rescue. If you have multiple projects open in Visual Studio, running each in the debugger once will start that application in IIS Express. After you have started and stopped your last application, you will have all of the sites running in IIS Express still. Now they can all interact.
The better way, in my opinion, to do this is to launch the sites from the command prompt. We already know how to do this for one site, but we have a couple options for how to do it with multiple sites. One way is to launch all of the sites that use the same application pool. To do this, use the following command line:
IISExpress /AppPool:Clr4IntegratedAppPool
That launches the sites that use the specified application pool (which, on my machine, is the default application pool). Unless you have changed the default configuration (which we will see how to do below), that will launch every site you have ever configured in IIS Express. That might not be what you were looking for (on my testing machine, I loaded over thirty sites at once). A far better way, in my mind, to launch multiple sites from the command prompt is to launch multiple command prompts. This may sound like a mess, but think about it: each window will display only the messages it is sending and receiving. That will more easily show you if you are having a communication issue. The nice thing about this method is that IIS Express will only open up one system tray icon. You can see all of your sites together in one place. It does, however, open up one instance of the IIS Express web server per command window. In this way, it truly is like two different web servers talking to each other.
The benefit of this really comes into play when you are developing both web sites and web services at the same time. You can start up the web service in IIS Express and then interact with it like it was in the live environment. The same is true for sites that reference each other (as we saw above with a site that was in a Virtual Directory underneath another site).
Transferring Settings Full IIS
Let’s face it – you aren’t going to publish the live version of your site using IIS Express. There is going to come a day where the baby bird needs to leave the nest. At that time, you probably want to replicate the settings in your dev environment over to your live environment, since you set your dev environment up to mimic how it would work in the real world. The good news is that IIS Express thought about that and made it simple. To set this up, go into the Properties sheet under your web project and select the Package/Publish Web tab. Under the section Items to deploy (applies to Web Deploy only), check the box that says Include IIS settings as configured in IIS Express like so:
Done. Remember, this isn’t total magic, so if you don’t use the Web Deploy, it won’t work automatically.
Showing Off Your Work
You know you want to. Maybe your boss wants to see your progress or you want to give the internal customer a quick demo of your new site. No matter what your reason, there is going to come a time when it would be nice for someone else to see your work. Instead of deploying half-baked code to a server somewhere, now you can just share out your work. IIS Express will accept calls from outside your computer, once you open up your firewall and tweak your applicationhost.config file.
To modify your config file, browse to your “Documents” folder. Inside there will be a directory called IIS Express. Inside there will be a folder called config. The full path should be C:\Users\{username}\Documents\IISExpress\config. Inside this folder is your applicationhost.config file. This is where IIS Express stores all of your configuration information. Remember, IIS Express is user-specific which is why the settings are here. Open up the config file. If you are familiar with IIS config files, this will look very familiar. If you aren’t, don’t worry, it isn’t that bad. Scroll down to a section called “Sites”. Inside that section will be a sub-section for each site. Find your site and look for the binding tags. Modify each binding by taking off the “localhost”. Do not replace it with an IP address unless you want to limit your connection to only one IP. Here is what my first connection looks like (with the binding line highlighted):
Now here is the same line after I have modified it:
Save the configuration file and start IIS Express as an administrator (IIS Express cannot bind to anything but localhost unless it is running under administrative rights). There is no further configuration that needs to be made. Just point your users to your computer and port number, and your computer will become a temporary web server. This, again, is where running IIS Express from the command prompt is so beneficial. You will be able to watch the calls come in, which makes for much better diagnostics.
Per User Configuration Files
As I pointed out a couple times already, IIS Express operates with per-user configuration files. Each user can tweak how their settings are laid out in their own configuration. In fact, they can add their own settings that affect how your project operates on their machine. Your project, too, carries some settings. That means that when you move or copy your project to another machine, the applicationhost.config file will need to be updated to reflect the settings stored in your project. Fortunately, Visual Studio recognizes this and prompts you like so:
If you say Yes, Visual Studio will take care of adding the appropriate settings to the config file. Piece of cake, right?
Advanced: Command Line Configuration
We have already touched upon a few of the command-line goodies, including launching IIS Express to watch the traffic and also loading all of the sites for a particular AppPool. However, there are other hidden gems in the form of command line options that can be very useful, including:
- None – If you don’t specifying any parameters for the application and just run it, it will launch the first website in the list.
- /config:[full path to config] – This command will allow you to point IIS Express to a new config file. You could try out someone else’s configuration or you could use different config files for different projects. You will still need to specify what you want to start as well unless you want to start the first site in the config (which is the default).
- /siteid:[id] – Just like launching a site by its site name, you can also launch it by its ID, which is specified in the config file. Normally these IDs are sequential starting at 1.
- /systray:[true/false] – This identifies whether the icon for IIS Express is placed in the system tray. By default, it will be placed there.
- /trace:[value] – The options here are none/n, info/i, warning/w, and error/e. You can specify either the short or the long value. The default is none. Trace will give you more information about the application itself and how it is running. You will get a lot of information about how the server is interacting with the websites beyond just the calls themselves. This is most useful when it seems that IIS Express is having an issue.
I have intentionally omitted a few switches from the above list. The reason for this is because they operate differently than the rest. There are some times when you want to run a site without adding an entry in the configuration. These switches are for just this case. They will not work with most of the other commands, which is another reason why they are separate. Here are the extra options:
- /path:[full app path] – This is used to point to the root path of the site you want to run.
- /port:[number] – You can specify the port that your specified application will run on. This has to be used in conjunction with the /path option.
- /clr:[version] – You can specify the CLR version that you run you application against. Again, you will need to use this with the /path option.
The commands here are simple, but there are a lot of nice features that come in handy every once in a while. As always, you can use the /? command to give you these commands and basic explanations of each.
Advanced: Configuration Flexibility
Here is where we get into the deep weeds. We are going to dig into the config file and change some settings manually. This will give us a better idea of how IIS Express works and how we can change it to fit our needs. Navigate to your config file (by default, it will be located in C:\Users\{username}\Documents\IISExpress\config). Remember that you can load other config files, so you might want to work on a copy. If you want to modify your existing file in place, at least make a backup first.
I’m going to go over a few sections that you can play with. Modifying the config file in any serious manner would require an entire article (which wouldn’t be a bad thing). I will focus on just a few key areas that might benefit you the most.
Reviewing Your Sites
There is a section titled “sites” that contains a set of sites underneath it. Each site corresponds to a saved site in IIS Express (makes sense, right?). When you run IIS Express from the command prompt, you are given the option of launching the website via site name or ID number. This information is listed in the site tag.
Underneath the site tag, you will find sections for application and bindings. The application section maps the URL path to the physical path. The bindings section tells IIS Express what protocols to bind to this website and which ports to use. This is where we changed the binding information to allow external users to load our site by taking off the localhost designation.
Here is what this section looks like for my default site (before I modified it):
Changing Your Directory
There may come a time when you want to move the location where a site points. To do this, simply edit the physicalPath attribute of the virtualDirectory element to reflect the new location. As an example, my example site (Website1) points to C:\Program Files\IIS Express\WebSite1. I am going to change that to point to a directory that contains my test site like so:
Now when I boot up my site, it pulls from this new location. Just make sure you refresh your browser in order to clear out any cache.
Changing Your Binding
This is a more common task for me, primarily because it is how we allow outside people use our site. However, you can also change the port number. This can be useful when you have another application that comes along and wants to use a port you are already using (rare but it happens). IIS Express is good about handling port issues internally but sometimes there are issues outside of your application that will interfere. For my example, I will change my port to be 12345 so it is easy to remember and I am going to take off the localhost designation so it can be accessed by my coworkers:
Now I can tell my coworkers to load my site at http://computername:12345/
Adding a Binding
Here is an easy way to add SSL to your site. Simply add a https binding and point the bindingInformation to a port number between 44300 and 44399. In my example, I added a HTTPS site that listens to port 44332:
Don’t forget that you will need to launch the command prompt as an administrator in order to launch this site, since it will need admin rights to bind the port to SSL.
Creating a New Site
If you have been following along, this step should be easy. We are going to put it all together into a new section. The one real thing I am going to add is to specify in the application element the applicationPool, just to show that I can do it in case you need to change which AppPool to use. This could be used to load up someone else’s assembly without even opening their application in Visual Studio. Here is my example entry:
Note that I changed the site id to be 17. That is because 17 is the next free ID number in my config file currently. If I were to put a duplicate ID number in the config, even if I tried to just load the one site, it would throw an error.
Modifying the Defaults
Right below the last specified site still inside the sites element is a set of defaults. Here is where you can change where the log files are written or even what the default applicationPool is. This is what it looks like:
I won’t be changing anything here, but this is where you would make a change in certain rare circumstances.
Webserver Changes
You can modify how IIS Express works in the same way you can modify IIS. For the most part, you should never go into these sections. However, there are a couple places that might need a change once in a while. These include:
Default Document
This is the section that will be looked through to find the first file that matches to be used as the homepage:
Custom Error Pages
Here is where you would change your error pages for each type of HTTP error:
Looking Forward
This article focused primarily on IIS Express 7.5. In the new release of Visual Studio, there will also be IIS Express 8.0. While Cassini will still be available, IIS Express will be the default development web server for Visual Studio 2012. I will be updating this article to include a section on the changes in IIS Express 8.0 and how they work. However, the primary focus of this article will remain on how to use IIS Express 7.5 with Visual Studio 2010, since that is the primary development system as of the time of the publication of this article.
Conclusion
IIS Express is an amazing product that blows Cassini out of the water. We have seen how easy it is to use and configure. We have also looked at how you can get a lot more information about what is going on in the webserver by running it from the command line. Finally, we walked through configuring the system to make the most of IIS Express. I hope you found this article useful. I would appreciate constructive comments on how I can make this article even better.
History
- June 4, 2012 - Initial Version
