Using ahadmin to read/write IIS configuration - Part 1

The Application Host Administration API (ahadmin.idl) interface library can be accessed using native code and any COM-interop means like script or managed code. This blog post details how to use this interface in scripts (all samples are in javascript) to read/write IIS7 configuration information.

Getting/Setting property values

You start by getting an instance of IAppHostAdminManager if you want to only read the config. If you want to write to config as well, you will need an instance of IAppHostWritableAdminManager which derives from IAppHostAdminManager. IAppHostWritableAdminManager has additionally CommitChanges method to commit changes to disk and CommitPath get/set property which dictates where the configuration settings are written. Lets create an instance of these.

var ahread  = new ActiveXObject("Microsoft.ApplicationHost.AdminManager");
var ahwrite = new ActiveXObject("Microsoft.ApplicationHost.WritableAdminManager"); 


We will work with ahwrite in this post. You should always use an instance of AdminManager to read the config which always give you effective config for a config path. WritableAdminManager might give wrong values which can vary depending on value of CommitPath. If you are not planning to write to IIS config files, you can just replace ahwrite with ahread in the samples. CommitChanges(), CommitPath get/set calls need ahwrite. Lets read system.webServer/urlCompression doStaticCompression, doDynamicCompression property values for server root using IAppHostAdminManager. You do this by getting IAppHostElement instance corresponding to urlCompression section using GetAdminSection. GetAdminSection take two parameters. First parameter is the section name and second parameter is config path. MACHINE/WEBROOT/APPHOST is the path corresponding to server root. This can be changed to  MACHINE/WEBROOT/APPHOST/<SITENAME>/<APPNAME>/<VDIR>/<FOLDER>/<FILENAME>.

var urlCompressionSection = ahwrite.GetAdminSection("system.webServer/urlCompression", "MACHINE/WEBROOT/APPHOST");

// Get properties collection for section/element
var urlCompressionProperties = urlCompressionSection.Properties;

IAppHostElement.Properties return in instance of IAppHostPropertyCollection. This interface has Count property which gives you number of properties in the collection and each individual property item can be obtained using Item method. Each individual property item is an instance of IAppHostProperty which has a get/set Value property. Following lines will print the values of doStaticCompression and doDynamicCompression properties.

WScript.Echo(urlCompressionProperties.Item("doStaticCompression").Value);
WScript.Echo(urlCompressionProperties.Item("doDynamicCompression").Value);

Item can be used with indexes as well. Following code gives you the same output as above.

WScript.Echo(urlCompressionProperties.Item(0).Value);
WScript.Echo(urlCompressionProperties.Item(1).Value);

Instead of getting all the properties collection and picking one property item, IAppHostElement interface provides a utility method GetPropertyByName which can be used directly to get IAppHostProperty interface for an attribute. So above code can be written as

WScript.Echo(urlCompressionSection.GetPropertyByName("doStaticCompression").Value);
WScript.Echo(urlCompressionSection.GetPropertyByName("doDynamicCompression").Value);

IAppHostProperty.Value setter can be used to change the value as well. Following code sets doDynamicCompression to true in memory. Changes are not written to disk until you call IAppHostWritableAdminManager.CommitChanges.

urlCompressionProperties.Item("doDynamicCompression").Value = true;
ahwrite.CommitChanges();

You should see doDyanmicCompression set to true in applicationHost.config. What if you wanted to enable doDynamicCompression only for Default web site. This requires you to get urlCompression section for that site as written below.

var urlCompressionSection = ahwrite.GetAdminSection("system.webServer/urlCompression", "MACHINE/WEBROOT/APPHOST/Default Web Site");

If you follow the same steps as written above, you will see doDynamicCompression set to true in applicationHost.config under a location tag for Default Web Site. What about writing these settings in Default Web Site root web.config? If you get the default commit path using ahwrite.CommitPath, it will return you MACHINE/WEBROOT/APPHOST which indicates that if you make any changes using ahadmin, changes will be persisted in applicationHost.config. Lets change CommitPath to write to Default Web Site root web.config.

ahwrite.CommitPath = "MACHINE/WEBROOT/APPHOST/Default Web Site");
urlCompressionSection.Properties.Item("doDynamicCompression").Value = true;
ahwrite.CommitChanges();

Running code above will give you the following in site root web.config.

<configuration>
    <system.webServer>
        <urlCompression doDynamicCompression="true" />
    </system.webServer>
</configuration>

Working with collections

Lets use ahadmin to work with default collections. Default collections are collections which are not contained in a child element in a section. There can be only one default collection under a section. Mime types collection under system.webServer/staticContent is one such example. Lets get list of mimeTypes defined in applicationHost.config.

var staticContentSection = ahwrite.GetAdminSection("system.webServer/staticContent", "MACHINE/WEBROOT/APPHOST");

// Get IAppHostElementCollection which points to the entire collection of elements
var mimeTypesCollection = staticContentSection.Collection;

IAppHostElementCollection interface can be used to get collection count, add/delete/clear and to get individual collection elements. Each collection element is again an instance of IAppHostElement and can further have default collections. Lets play with it a little.

// Print the number of mimeType entries in the collection
WScript.Echo("Count=" + mimeTypesCollection.Count + "\n");

// Print properties of first 10 collection elements
for(var i = 0; i < 10; i++)
{
    var mimeElement = mimeTypesCollection.Item(i);

    // Print its properties
    var mimeElementProperties = mimeElement.Properties;
    var printString = "";

    for(var j = 0; j < mimeElementProperties.Count; j++)
    {
        // Get the value of each property using index
        printString += mimeElementProperties.Item(j).Value;
        if(j < mimeElementProperties.Count - 1)
        {
            printString += ", ";
        }
    }

    WScript.Echo(printString);
}

I get the following on my machine.

Count=338

.323, text/h323
.aaf, application/octet-stream
.aca, application/octet-stream
.accdb, application/msaccess
.accde, application/msaccess
.accdt, application/msaccess
.acx, application/internet-property-stream
.afm, application/octet-stream
.ai, application/postscript
.aif, audio/x-aiff

What if I want to print the name of the attributes with their values as well. But I dont remember the schema of mimeType element. Lets first get property names from schema.

var mimeElementPropertiesCollection = mimeTypesCollection.Item(0).Properties;
var mimeElementSProperties = new Array(); for(var i = 0; i < mimeElementPropertiesCollection.Count; i++)

{

    // Get IAppHostElementSchema by calling IAppHostElement.Schema

    mimeElementSProperties[i] = mimeElementPropertiesCollection.Item(i).Schema.Name;
    WScript.Echo(mimeElementSProperties[i]);
}

Now that we have attribute names as well, we can modify the sample code above to print attribute names as well. Also mimeElementProperties.Item calls can be changed to take attribute name in place of index like following.

printString += mimeElementSProperties[j] + "=\"" + mimeElementProperties.Item(mimeElementSProperties[j]).Value + "\"";

 

What about child elements?

 

Child elements are elements under sections/elements and are treated little differently in ahadmin. Example of child elements under system.webServer/httpCompression section are staticTypes and dynamicTypes. IAppHostElement interface which is returned by GetAdminSection for a section can be used to get IAppHostElement for a child element. Lets write code to get all child elements present under httpCompression section.

// Get IAppHostElement for httpCompression section
var httpCompressionSection = ahwrite.GetAdminSection(
                                 "system.webServer/httpCompression",
                                 "MACHINE/WEBROOT/APPHOST");

// Get IAppHostChildElementCollection from IAppHostElement
var hcChildElementCollection = httpCompressionSection.ChildElements;

IAppHostChildElementCollection has Count property and Item method which can be used to get IAppHostElement instance of each child element. Following code get each child element by index and then print the count of collection elements contained in the collection under this element.

for(var i = 0; i < hcChildElementCollection.Count; i++)
{
    var childElement = hcChildElementCollection.Item(i);
    WScript.Echo(childElement.Name);

    // Also print how many entries are there in the collection contained in this childElement
    WScript.Echo(childElement.Collection.Count);
}

Child elements can again have child elements which can be obtained using IAppHostElement.ChildElements.Individual child elements can also be obtained using element names from IAppHostChildElementCollection as in the code below.

var staticTypesChildElement   = hcChildElementCollection.Item("staticTypes");
var dynamicTypesChild Element = hcChildElementCollection.Item("dynamicTypes");

Similar to GetPropertyByName, IAppHostElement includes another utility function to get the child element by name directly. Above code can be written as

var staticTypesChildElement  = httpCompressionSection.GetElementByName("staticTypes");

var dynamicTypesChildElement = httpCompressionSection.GetElementByName("dynamicTypes");

 

Code below prints all sites, their binding information and applications/vdirs under each site.

var sitesSection    = ahwrite.GetAdminSection("system.applicationHost/sites", "MACHINE/WEBROOT/APPHOST");
var sitesCollection = sitesSection.Collection;

for(var i = 0; i < sitesCollection.Count; i++)
{
    var siteElement = sitesCollection.Item(i);

    // We can use siteElement.Properties.Item("name").Value as well.
    var siteName = siteElement.GetPropertyByName("name").Value;
    var siteId   = siteElement.GetPropertyByName("id").Value;
    WScript.Echo("Site Name=" + siteName + " Id=" + siteId);

    // Also print bindings information
    // Bindings is a childElement under site element

    var bindingsElement = siteElement.ChildElements.Item("bindings");

    // We could use siteElement.GetElementByName("bindings"); as well
    var bindingsCollection = bindingsElement.Collection;
    for(var j = 0; j < bindingsCollection.Count; j++)
    {
        var binding     = bindingsCollection.Item(j);
        var protocol    = binding.GetPropertyByName("protocol").Value;
        var bindingInfo = binding.GetPropertyByName("bindingInformation").Value;

        WScript.Echo("Binding protocol=" + protocol +
                            " bindingInformation=" + bindingInfo);
    }

 

    // Each siteElement has a default collection for applications
    var applications = siteElement.Collection;
    for(var j = 0; j < applications.Count; j++)
    {
        var appElement = applications.Item(j);
        var appPath    = appElement.Properties.Item("path").Value;
        WScript.Echo("- Application with path=" + appPath);

        // Each application element has a default collection
        // for virtual directories
        var vdirs = appElement.Collection;

        for(var k = 0; k < vdirs.Count; k++)
        {
            var vdirElement      = vdirs.Item(k);
            var vdirPath         = vdirElement.Properties.Item("path").Value;
            var vdirPhysicalPath = vdirElement.GetPropertyByName("physicalPath").Value;

            WScript.Echo("-- VDir path=" + vdirPath +
                                      " physicalPath=" + vdirPhysicalPath);
        }
    }

    WScript.Echo();
}

Creating new collection elements 

IAppHostElementCollection.CreateNewElement and AddNewElement can be used to create new collection elements.

Following code can be used to create a new site.


var sitesSection = ahwrite.GetAdminSection("system.applicationHost/sites", "MACHINE/WEBROOT/APPHOST");

// Create a new site element
var newSiteElement = sitesSection.Collection.CreateNewElement();

// Set site name and site idnewSiteElement.Properties.Item("name").Value = "My New Site";
newSiteElement.Properties.Item("id").Value   = 3;

// Create a new app under this site and set its path to /
var newAppElement = newSiteElement.Collection.CreateNewElement();
newAppElement.Properties.Item("path").Value = "/";

// Create new vdir and set its path and physical path
var newVdirElement = newAppElement.Collection.CreateNewElement();
newVdirElement.Properties.Item("path").Value         = "/";
newVdirElement.Properties.Item("physicalPath").Value = "%systemdrive%\\inetpub\\MyNewSite";

// Add vdir to app and then app to site
newAppElement.Collection.AddElement(newVdirElement);
newSiteElement.Collection.AddElement(newAppElement);

// Create a new binding element under childElement bindings under siteElement
var newBindingsElement = newSiteElement.ChildElements.Item("bindings").Collection.CreateNewElement();

// Set protocol and binding information
newBindingsElement.GetPropertyByName("protocol").Value = "http";
newBindingsElement.GetPropertyByName("bindingInformation").Value = "*:80:MyNewSite";

// Add new binding element to collection under child element bindings
newSiteElement.GetElementByName("bindings").Collection.AddElement(newBindingsElement);

// Add new site element to default collection of sites section
sitesSection.Collection.AddElement(newSiteElement);

// Commit changes to disk
ahwrite.CommitChanges();

This will write the following in system.applicationHost/sites section.

<site name="My New Site" id="3">
    <application path="/">
        <virtualDirectory path="/" physicalPath="%systemdrive%\inetpub\MyNewSite" />
    </application>
    <bindings>
        <binding protocol="http" bindingInformation="*:80:MyNewSite" />
    </bindings>
</site>

Lets quickly write code to create an apppool as well.

// Get the applicationPools section and its default collection
var apppoolsSection    = ahwrite.GetAdminSection("system.applicationHost/applicationPools, "MACHINE/WEBROOT/APPHOST");
var apppoolsCollection = apppoolsSection.Collection;

// Create a new apppool element and set its name
var newAppPool = apppoolsCollection.CreateNewElement();
newAppPool.Properties.Item("name").Value = apppoolName;

// Set process model properties under processModel child element
var processModel = newAppPool.GetElementByName("processModel");
processModel.Properties.Item("identityType").Value = "SpecificUser";
processModel.Properties.Item("userName").Value     = "newapppool";
processModel.Properties.Item("password").Value     = "newapppool";

// Add to app pools collection and commit changes to disk

apppoolsCollection.AddElement(newAppPool);
ahwrite.CommitChanges();

How about writing a script to put </clear> for this site to clear mimeTypes collection?

var staticContentSection = ahwrite.GetAdminSection("system.webServer/staticContent", "MACHINE/WEBROOT/APPHOST/My New Site");
var mimeTypesCollection  = staticContentSection.Collection;

// blank corresponds to addElement of collection.// You can specify strings corresponding to removeElement and clearElement.
var clearElement = mimeTypesCollection.CreateNewElement("clear");
mimeTypesCollection.AddElement(clearElement);
ahwrite.CommitChanges();

This code writes following in applicationHost.config.

<location path="My New Site">
    <system.webServer>
        <staticContent>
            <clear />
        </staticContent>
    </system.webServer>
</location>   

Again, setting the CommitPath to "MACHINE/WEBROOT/APPHOST/My New Site" will make CommitChanges write to web.config of site root. I will cover working with section groups, section definitions, locations and metadata in my next post (available now).

View the original post

No Comments