Microsoft.Web.Administration
Another way to access configuration data is
through the managed application programming interface (API) found in
the Microsoft.Web.Administration (MWA) assembly. The MWA assembly
enables you to access or change a configuration and access some server
object’s properties and state data through top-level administration
objects such as sites, application pools, and worker processes.
The following sections describe how to use
MWA for common administration tasks. These sections assume you have
some familiarity with managed code and the C# programming language.
The following example uses MWA to create a new
site called Fabrikam Site that listens on port 8080 and uses
C:\inetpub\wwwroot\fabrikam as the root directory for content.
using System;
using Microsoft.Web.Administration;
namespace Example {
class Program {
static void Main(string[] args) {
ServerManager mgr = new ServerManager();
Site site = mgr.Sites.Add("Fabrikam",
@"C:\inetpub\wwwroot\fabrikam", 8080);
site.ServerAutoStart = true;
mgr.CommitChanges();
}
}
}
In the example, note the use of the ServerManager object. It is the entry point for all actions using the MWA APIs. The ServerManager
object provides access to properties, methods, and collections that
provide access to the other classes in the assembly. Though it is
possible to manage server data directly through XML or state APIs, MWA
provides easy access to the data through these APIs.
The next thing to look at is the use of the Sites collection accessed through the Sites property of the ServerManager object instance. The Sites
collection provides access to all of the sites currently configured on
the system. You can add or remove sites as well as change existing
sites.
As you’ll notice, you can access the
properties of individual sites as well. In this example, you set the
automatic start option of the site to true. You can modify many site
properties directly through the Site class. You can also access the sites collection by accessing it by name, as seen here.
mgr.Sites["Fabrikam"].ServerAutoStart = true;
The last line to note is the call to the CommitChanges method. Up until that line is called, all changes are done in memory only and are not committed to the configuration system.
mgr.CommitChanges();
It is necessary to call CommitChanges whenever you want to update a configuration. If your program does not call CommitChanges, the configuration changes made in your application will be lost.
After the changes are committed, you should be
able to see your site configuration in the applicationHost.config file.
Your configuration should contain a section that looks something like
this.
<site name="Fabrikam" id="1000" serverAutoStart="true">
<application path="/">
<virtualDirectory path="/"
physicalPath="c:\inetpub\wwwroot\fabrikam" />
</application>
<bindings>
<binding protocol="http" bindingInformation=":8080:" />
</bindings>
</site>
Creating Application Pools with MWA
You can also use the MWA APIs to create application pools and assign them to a site. The following example shows how to do this.
using System;
using Microsoft.Web.Administration;
namespace Example {
class Program {
static void Main(string[] args) {
ServerManager mgr = new ServerManager();
ApplicationPool pool =
mgr.ApplicationPools.Add("FabrikamPool");
pool.ManagedPipelineMode
= ManagedPipelineMode.Classic;
Site = mgr.Sites["Fabrikam"];
site.Applications[0].ApplicationPoolName =
@"FabrikamPool";
mgr.CommitChanges();
}
}
}
The first line of this sample should look familiar. You use the ServerManager object to get a reference to the Fabrikam site. In the next line, you add an application pool by using the Add method of ApplicationPoolsCollection, which is returned from the ApplicationPools property.
ApplicationPool pool =
mgr.ApplicationPools.Add("FabrikamPool");
You want to set your application pool’s pipeline mode to Classic. You do this with the next line by using the ManagedPipelineMode property of the ApplicationPool class.
pool.ManagedPipelineMode
= ManagedPipelineMode.Classic;
Next, you access the root application of the Fabrikam site and set the application’s pool to your newly created "FabrikamPool".
Site = mgr.Sites["Fabrikam"];
site.Applications[0].ApplicationPoolName =
@"FabrikamPool";
Finally, you want to commit the changes.
mgr.CommitChanges();
The following code demonstrates how to use
Microsoft.Web.Administration APIs to enable the default document of the
"Default Web Site".
using System;
using Microsoft.Web.Administration;
namespace Example {
class Program {
static void Main(string[] args) {
ServerManager mgr = new ServerManager();
Configuration config =
mgr.GetWebConfiguration(
"Default Web Site");
ConfigurationSection section =
config.GetSection(
"system.webServer/defaultDocument");
ConfigurationAttribute enabled =
section.GetAttribute("enabled");
enabled.Value = true;
mgr.CommitChanges();
}
}
}
In this section, you used the Configuration
class to directly access a configuration section and set a node’s
value. To do this, you first have to access the root web configuration
file by using the GetWebConfiguration method of the server manager.
ServerManager mgr = new ServerManager();
Configuration config =
mgr.GetWebConfiguration(
"Default Web Site");
This returns an instance of a Configuration
class to the application. Use that object instance to access a
configuration section directly and then request the attribute you want
to change.
ConfigurationSection section =
config.GetSection(
"system.webServer/defaultDocument");
ConfigurationAttribute enabled =
section.GetAttribute("enabled");
Last, make a change to the attribute and follow that change up with a call to CommitChanges to update the configuration system.
enabled.Value = true;
mgr.CommitChanges();
You can use
Microsoft.Web.Administration to perform many more tasks. Familiarize
yourself with some of the properties and methods of the assembly through
MSDN reference documentation. You will find that most tasks are made
available through the API and are much easier to perform than editing a
configuration directly.
Windows PowerShell and IIS 7.0
Windows PowerShell provides a
full-featured command shell. Taking advantage of the Microsoft C#
scripting language and using an object model based on the .NET
Framework, Windows PowerShell provides powerful capabilities for
redirecting objects and dynamic manipulation of a result set. You can
run commands directly from the command line, and you can run them from
within scripts.
When working with Windows PowerShell, you use built-in commands called cmdlets
as you would use a command or utility at the command line. Cmdlets are
both simple and powerful. They are named using an easy-to-understand
word pairing:
-
New-. Creates a new instance of an item or object
-
Remove-. Removes an instance of an item or object
-
Set-. Modifies specific settings of an object
-
Get-. Queries a specific object or a subset of a type of object
For example, the Get-Credential cmdlet gets a credential object based on a password. You can get a list of all cmdlets by typing help * at the Windows PowerShell prompt.
As new cmdlets that are specific to
managing IIS servers become available, you can install them through
server updates or by downloading and installing an installation package.
WMI Provider
IIS 7.0 continues to support the legacy WMI
provider used in IIS 6.0 to manage the Web server. This WMI provider
works via the IIS 6.0 Metabase Compatibility role service that
translates the IIS 6.0 configuration settings and actions into the IIS
7.0 configuration structure. To use existing scripts that use the IIS
6.0 WMI object model, you need to install the IIS 6.0 WMI Compatibility
role service (from the Management Tools\IIS 6 Management Compatibility
category) when managing the Web Server (IIS) role in Server Manager on
Windows Server 2008. Alternatively, use the Turn Windows Components On
And Off page in Windows Vista.
Note
To use configuration scripts that call
into the legacy IIS 6.0 WMI object model, you need to install the IIS 6
WMI Compatibility role service.
The translation layer between the WMI
script, the metabase format, and the new configuration system may
introduce slight deviations in the configuration mapping when using
legacy IIS 6.0 configuration scripts and APIs, so it is recommended that
you migrate your existing scripts to use the new configuration APIs.
You may choose to use the new WMI provider, which exposes the new configuration system directly and has a different object model from the IIS 6.0 WMI provider.
Note
To use the new WMI provider in IIS 7.0,
you need to install the IIS Management Scripts And Tools role service.
Do not install the IIS 6 WMI Compatibility role service to use the new
WMI provider.
To learn about the new WMI provider object model, see the online documentation available at http://msdn2.microsoft.com/en-us/library/aa347459.aspx.
IIS 7.0 Configuration COM Objects
You can also use the IIS 7.0 configuration COM
objects directly to manage IIS configuration and access the
administration functionality in IIS 7.0. You can access these COM
objects from native C++ programs, .NET applications, or script
environments. For the latter, the configuration COM objects may provide a
more straightforward alternative to using the WMI provider both because
of simpler syntax and because the overhead of the WMI infrastructure
has been removed.
These COM objects are also always available
when IIS 7.0 is installed, and they do not depend on any externals
components. They do not require .NET Framework to be installed.
To learn more about using the IIS 7.0 configuration COM objects, see the online documentation for the Microsoft.ApplicationHost.WritableAdminManager and Microsoft.ApplicationHost.AdminManager classes.
