Using ServerManager to create Application within Application

Question

I'm using ServerManager (Microsoft.Web.Administration.dll) to create an Application within a website on IIS 7. I need to create an application within this application or convert a virtual directory to an application (like the iis manager feature right-click -> convert to application) How is this doable? I found very little documentation regarding this lib, and none of it referred to this particular functionality. Thanks.

Kimble

Answer 1

The way to do this is to manipulate the Site.Applications collection which is a flattened tree of all the applications in your site.

For the sake of these examples we'll assume a site called "MySite" where the content is located on the local hard disk at: d:\mysite\www. The site's IIS number is 3 and the site resides in its own application pool also called "MySite".

We'll also assume the following folder structure for the site

To start with we get the site we want to add an application to, we'll use the variable site throughout:

// Get my site
Site site = serverManager.Sites.First(s => s.Id == 3);

The root "/" application:

Every site has a "root" application. If we open applicationHost.config located in %systemroot%\windows\system32\inetsrv\config and locate the <site> node for our site we see the following:

<site name="MySite" id="3">
  <application path="/" applicationPool="MySite">
    <virtualDirectory path="/" physicalPath="d:\mysite\www" />
  </application>
</site>

Each <site> contains a collection of <application>'s. There will always be at least one application which defines the root application, /.

The applicationPool attribute specifies which application pool to use.

Note that that there is a single child element: virtualDirectory.

Every application has a child collection of virtualDirectory elements and there will usually be at least one element in this collection.

The default <virtualDirectory> within the root application tells us:

• this this is the root (path="/") and
• that it's physically located on the file system at d:\MySite\www (physicalPath="d:\MySite\www").

The path of each virtualDirectory is relative to the path specified in the parent application path.

Adding a Virtual Directory:

If we wanted to add a virtual directory to the "site root" mapped to somewhere else on the filesystem we'd do:

Application rootApp = site.Applications.First(a => a.Path == "/");
rootApp.VirtualDirectories.Add("/vdir_1", @"D:\MySite\other_content");
serverManager.CommitChanges();

The resultant configuration looks like:

<site name="MySite" id="3">
  <application path="/" applicationPool="MySite">
    <virtualDirectory path="/" physicalPath="D:\MySite\www" />
    <virtualDirectory path="/vdir_1" physicalPath="D:\MySite\other_content" />
  </application>
</site>

And we see this in IIS Manager:

Adding a Virtual Directory to an existing Virtual Directory:

If we wanted to add a child virtual directory to vdir1 we'd do:

root.VirtualDirectories.Add("/vdir_1/sub_dir1", @"d:\MySite\more_content");

this results in:

<site name="MySite" id="3">
  <application path="/" applicationPool="MySite">
    <virtualDirectory path="/" physicalPath="D:\MySite\www" />
    <virtualDirectory path="/vdir_1" physicalPath="D:\MySite\other_content" />
    <virtualDirectory path="/vdir_1/sub_dir1" physicalPath="D:\MySite\more_content" />
  </application>
</site>

IIS Manager:

There's a couple things to keep in mind when adding virtual directories:

• As mentioned, the virtual path is always relative to the parent application path
• The last part of a virtual path e.g. /vdir_1 and .../sub_dir1 becomes the name of the virtual directory
• It's perfectly legal to have more than one virtual directory point to the same physical folder
• With the exception of the name part of a virtual directory path, all parts of the path should exist either as physical paths or as virtual paths within the website root (d:\MySite\www). i.e. the path should be able to overlay something that is already there otherwise a virtual directory won't be visible in IIS manager.

Regarding that last point, for example, we don't have a physical folder or virtual directory called /vdir_2 but the following code is perfectly legal:

root.VirtualDirectories.Add("/vdir_2/sub_dir1", @"d:\MySite\even_more_content");

You won't see /vdir_2/sub_dir1 show up in IIS manager but it is legal and you can actually browse to it. We can also see it in applicationHost.config:

<site name="MySite" id="3">
  <application path="/" applicationPool="MySite">
    <virtualDirectory path="/" physicalPath="D:\MySite\www" />
    <virtualDirectory path="/vdir_1" physicalPath="D:\MySite\other_content" />
    <virtualDirectory path="/vdir_1/sub_dir1" physicalPath="D:\MySite\more_content" />
    <virtualDirectory path="/vdir_2/sub_dir1" physicalPath="D:\MySite\even_more_content" />
  </application>
</site>

Convert Folder to Application:

If you just uploaded an ASP.NET application to the /app_1 folder in your site and you want to turn this into its own Application we do this:

Application app = site.Applications.Add("/app_1", @"d:\MySite\www\app_1");
// set application pool, otherwise it'll run in DefaultAppPool
app.ApplicationPoolName = "MySite";
serverManager.CommitChanges();    

In applicationHost.config we can see a new <application> element has been added:

<site name="MySite" id="3">
  <application path="/" applicationPool="MySite">
    <virtualDirectory path="/" physicalPath="D:\MySite\www" />
    <virtualDirectory path="/vdir_1" physicalPath="D:\MySite\other_content" />
    <virtualDirectory path="/vdir_1/sub_dir1" physicalPath="D:\MySite\more_content" />
    <virtualDirectory path="/vdir_2/sub_dir1" physicalPath="D:\MySite\even_more_content" />
  </application>
  <application path="/app_1" applicationPool="MySite">
    <virtualDirectory path="/" physicalPath="d:\MySite\www\app_1" />
  </application>
</site>

In IIS we see:

This is the equivalent of doing right-click "Convert to Application".

Add Application to Existing Application:

Adding an application as a child of an existing application is very simple. Say we want to make /app_1/sub_app_1 a sub application of /app_1:

We would simply do:

Application app = 
  site.Applications.Add("/app_1/sub_app_1", @"d:\mysite\www\app_1\sub_app_1");
app.ApplicationPoolName ="MySite";

The resultant configuration would look like:

<site name="MySite" id="3">
  <application path="/" applicationPool="MySite">
    <virtualDirectory path="/" physicalPath="D:\MySite\www" />
    <virtualDirectory path="/vdir_1" physicalPath="D:\MySite\other_content" />
    <virtualDirectory path="/vdir_1/sub_dir1" physicalPath="D:\MySite\more_content" />
    <virtualDirectory path="/vdir_2/sub_dir1" physicalPath="D:\MySite\even_more_content" />
  </application>
  <application path="/app_1" applicationPool="MySite">
    <virtualDirectory path="/" physicalPath="d:\MySite\www\app_1" />
  </application>
  <application path="/app_1/sub_app_1" applicationPool="MySite">
    <virtualDirectory path="/" physicalPath="d:\mysite\www\app_1\sub_app_1" />
  </application>
</site>

In IIS:

Add Virtual Directory to Application:

Now if we wanted to add a virtual directory to this application we would do:

Application app = site.Applications.First(a => a.Path == "/app_1");
app.VirtualDirectories.Add("/vdir_1", @"d:\MySite\other_content");

In applicationHost.config we can see a new <virtualDirectory> element has been added:

<site name="MySite" id="3">
  <application path="/" applicationPool="MySite">
    <virtualDirectory path="/" physicalPath="D:\MySite\www" />
    <virtualDirectory path="/vdir_1" physicalPath="D:\MySite\other_content" />
    <virtualDirectory path="/vdir_1/sub_dir1" physicalPath="D:\MySite\more_content" />
    <virtualDirectory path="/vdir_2/sub_dir1" physicalPath="D:\MySite\even_more_content" />
  </application>
  <application path="/app_1" applicationPool="MySite">
    <virtualDirectory path="/" physicalPath="d:\MySite\www\app_1" />
    <virtualDirectory path="/vdir_1" physicalPath="d:\MySite\other_content" />
  </application>
</site>

In IIS we see:

Again it is important to note that the virtual path /vdir1 is always relative to the path of the containing application.

Convert Existing Virtual Directory to Application:

What if we wanted to convert the virtual directory we just created (/app_1/vdir1) to an application? We'd need to do this in two steps:

// Get the application
Application app_1 = site.Applications.First(a => a.Path == "/app_1");
// Find the virtual directory
VirtualDirectory vdir_1 = app_1.VirtualDirectories.First(v => v.Path == "/vdir_1");
// Remove it from app_1
app_1.VirtualDirectories.Remove(vdir_1);
// Create our application
Application vdir_1_app = site.Applications.Add("/app_1/vdir_1", vdir_1.PhysicalPath);
// set application pool, otherwise it'll run in DefaultAppPool
vdir_1_app.ApplicationPoolName = "MySite";
serverManager.CommitChanges();    

The resultant applicationHost.config looks like:

<site name="MySite" id="3">
  <application path="/" applicationPool="MySite">
    <virtualDirectory path="/" physicalPath="D:\MySite\www" />
    <virtualDirectory path="/vdir_1" physicalPath="D:\MySite\other_content" />
    <virtualDirectory path="/vdir_1/sub_dir1" physicalPath="D:\MySite\more_content" />
    <virtualDirectory path="/vdir_2/sub_dir1" physicalPath="D:\MySite\even_more_content" />
  </application>
  <application path="/app_1" applicationPool="MySite">
    <virtualDirectory path="/" physicalPath="d:\MySite\www\app_1" />
  </application>
  <application path="/app_1/vdir_1" applicationPool="MySite">
    <virtualDirectory path="/" physicalPath="d:\MySite\other_content" />
  </application>
</site>

In IIS Manager we see:

Add Application to Existing Virtual Directory:

What happens if we want to add an application to a virtual directory, how does that work? In this example we'll add an application to the virtual directory /vdir_1/sub_dir1 which we created earlier.

Application app = 
   site.Applications.Add("/vdir_1/sub_dir1/app_2", @"d:\mysite\other_content");
app.ApplicationPoolName = "MySite";
serverManager.CommitChanges();

The resultant config looks like:

<site name="MySite" id="3">
  <application path="/" applicationPool="MySite">
    <virtualDirectory path="/" physicalPath="D:\MySite\www" />
    <virtualDirectory path="/vdir_1" physicalPath="D:\MySite\other_content" />
    <virtualDirectory path="/vdir_1/sub_dir1" physicalPath="D:\MySite\more_content" />
    <virtualDirectory path="/vdir_2/sub_dir1" physicalPath="D:\MySite\even_more_content" />
  </application>
  <application path="/app_1" applicationPool="MySite">
    <virtualDirectory path="/" physicalPath="d:\MySite\www\app_1" />
  </application>
  <application path="/app_1/vdir_1" applicationPool="MySite">
    <virtualDirectory path="/" physicalPath="d:\MySite\other_content" />
  </application>
  <application path="/vdir_1/sub_dir1/app_2" applicationPool="MySite">
    <virtualDirectory path="/" physicalPath="d:\mysite\other_content" />
  </application>
</site>

And in IIS manager we see:

Convert Existing Child Folder into an Application:

As a final example, we want to turn /other_apps/sub_app_1 into an application:

Our code looks like:

Application app = 
   site.Applications.Add("/other_apps/sub_app_1", @"d:\mysite\other_content");
app.ApplicationPoolName="MySite";
serverManager.CommitChanges();

The resultant config:

<site name="MySite" id="3">
  <application path="/" applicationPool="MySite">
    <virtualDirectory path="/" physicalPath="D:\MySite\www" />
    <virtualDirectory path="/vdir_1" physicalPath="D:\MySite\other_content" />
    <virtualDirectory path="/vdir_1/sub_dir1" physicalPath="D:\MySite\more_content" />
    <virtualDirectory path="/vdir_2/sub_dir1" physicalPath="D:\MySite\even_more_content" />
  </application>
  <application path="/app_1" applicationPool="MySite">
    <virtualDirectory path="/" physicalPath="d:\MySite\www\app_1" />
  </application>
  <application path="/app_1/vdir_1" applicationPool="MySite">
    <virtualDirectory path="/" physicalPath="d:\MySite\other_content" />
  </application>
  <application path="/vdir_1/sub_dir1/app_2" applicationPool="MySite">
    <virtualDirectory path="/" physicalPath="d:\mysite\other_content" />
  </application>
  <application path="/other_apps/sub_app_1" applicationPool="MySite">
    <virtualDirectory path="/" physicalPath="d:\mysite\other_content" />
  </application>
</site>

In IIS manager:

Hope this helps explain the relationship between sites, applications and virtual directories.

Abominable

Awesome, thanks @Kev. One to mention, under the Convert to Application instructions, one of my installers was creating the subdirectory as a VDir instead of a regular dir, so when I ran that code to covert it to an application it gave me a "directory already exists". The solution was just call the API to remove the existing VDir from the VirtualDirectories collection if it existed before adding the Application. Small item, but may be worth including in your instructions. – Caraway

@mike - thanks, glad this helped. I'll amend the post today. :) – Abominable

@mike - which (bold) section was that in? I can't seem to repro. – Abominable

That is one of the best and most detailed answers I have ever seen; awesome job! – Geralyngeraniaceous

tutorial like answer, the force is strong with you Kev. – Registrant

Outstanding answer -- thanks for putting all that time and effort into it. – Olcott

@Abominable This is a great post and helped me allot, Quick question, Id like to display virtual apps, and virtual directories separate from each other, Im thinking if(AppPoolName != "Null") but for some reason i can not get that to work. Any help would be appreciated. – Initiatory

Thank you a lot, your answer is really helpful for me – Bonspiel