Web service versioning in IIS


If you have an open web service that your customers can call then you must be prepared to have different versions of the web service available. Your customers may have scheduled calls to your web service so that they can build reports or whatever, without getting an exception. At times a new version of your web service will contain breaking changes. If you deploy that version then the clients of the web service won’t be impressed even if you send out emails and prepare them for the change. They will have to follow you and it will consume their time.

Instead, you can build new versions of the web service without affecting the old version and the clients can update their systems if and when they wish. You can just inform them that there’s a new version available and this and this call will require an extra parameter.

There are certainly various ways to solve this issue and including the version in the URI path is one of them



…where ‘current’ always contains the latest version. Some clients may always want to use the most recent version of our service but they need to understand the risks.

You may first think that if this is some MVC-style routing, such as in Web API, you’ll need to include the version in the routes as follows:


Don’t worry, it’s not necessary. The base routing will be as follows:


The version can be inserted using IIS.

How to do

On the deployment server you can set up the folder structure as follows:

IIS versioning folder structure

Within each version folder you can have subfolders following the conventions at your company, e.g. Staging, Live and Backup.

In IIS you create a new website and specify the ‘mygreatwebservice’ as the physical path:

Setting up web site in IIS

So you set the top folder as the physical path and not any of the version folders. You’ll see the the following under the Sites node in IIS:

IIS before adjustment

Right-click each folder under the site and select “Convert to Application” in the context menu. Press OK in the Add Application menu that appears. You should see the following picture after this step:

IIS after converting to applications

This is it actually. The versions can be added to the URL path after the domain name:


Just make sure you deploy the right version in each version folder and IIS will direct the traffic to the correct subfolder based on the first section in the path.

About Andras Nemes
I'm a .NET/Java developer living and working in Stockholm, Sweden.

2 Responses to Web service versioning in IIS

  1. Cassio de Vargas Oliveira says:

    Very good!
    This tutorial solve my quastion.

  2. Pingback: Architecture and patterns | Michael's Excerpts

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s


A great WordPress.com site

Elliot Balynn's Blog

A directory of wonderful thoughts

HarsH ReaLiTy

A Good Blog is Hard to Find

Softwarearchitektur in der Praxis

Wissenswertes zu Webentwicklung, Domain-Driven Design und Microservices

Technology Talks

on Microsoft technologies, Web, Android and others

Software Engineering

Web development

Disparate Opinions

Various tidbits

chsakell's Blog


Once Upon a Camayoc

Bite-size insight on Cyber Security for the not too technical.

Guru N Guns's

OneSolution To dOTnET.

Johnny Zraiby

Measuring programming progress by lines of code is like measuring aircraft building progress by weight.

%d bloggers like this: