Adding Application Pools <add>
Overview
The <add> element of the <applicationPools> element controls the configuration settings for an IIS 7 and later application pool. You create an <add> element in the ApplicationHost.config file for each application pool that you want to run on your IIS server.
The <add> element can contain attributes and child elements that configure the pipeline processing mode and the version of the .NET Framework the worker processes in the application pool use for incoming requests. This element also contains child elements that configure application pool identity, performance, and health and recycling application pool settings.
When you create a new application pool on IIS 7 and later, at a minimum you must assign the application pool a unique name. Configure all other properties as needed for the applications that use the application pool.
New in IIS 7.5 and later
Starting in IIS 7.5, you can configure an application to start automatically by using the managedRuntimeLoader, CLRConfigFile, and startMode attributes of the <add> element. These attributes configure, respectively, the name of the managed DLL that provides runtime loading for your application, the common language runtime configuration file for the application, and the startup type for the application.
Also new in IIS 7.5 and later is a new ApplicationPoolIdentity type for the identityType attribute of the <processModel> element. This new identity type is now the default process identity for applications, and makes it possible to set the security for your content areas to allow access for a specific application pool. To do so, you would set your security using the name of an application pool by using syntax like "IIS AppPool\DefaultAppPool." This identity is created dynamically, thereby dramatically reducing the surface attack area of your server.
Compatibility
| Version | Notes |
|---|---|
| IIS 10.0 | The <add> element was not modified in IIS 10.0. |
| IIS 8.5 | The <add> element was not modified in IIS 8.5. |
| IIS 8.0 | The default value of the managedRuntimeVersion attribute was changed to "", and v4.0 was added as a value for managedRuntimeVersion. |
| IIS 7.5 | The <add> element of the <applicationPools> element was updated in IIS 7.5 to include attributes that allow you to preload applications. |
| IIS 7.0 | The <add> element of the <applicationPools> collection was introduced in IIS 7.0. |
| IIS 6.0 | The <applicationPools> collection replaces portions of the IIS 6.0 IIsApplicationPools metabase property. |
Setup
The <applicationPools> collection is included in the default installation of IIS 7 and later.
How To
How to create a new application pool
Open Internet Information Services (IIS) Manager:
If you are using Windows Server 2012 or Windows Server 2012 R2:
- On the taskbar, click Server Manager, click Tools, and then click Internet Information Services (IIS) Manager.
If you are using Windows 8 or Windows 8.1:
- Hold down the Windows key, press the letter X, and then click Control Panel.
- Click Administrative Tools, and then double-click Internet Information Services (IIS) Manager.
If you are using Windows Server 2008 or Windows Server 2008 R2:
- On the taskbar, click Start, point to Administrative Tools, and then click Internet Information Services (IIS) Manager.
If you are using Windows Vista or Windows 7:
- On the taskbar, click Start, and then click Control Panel.
- Double-click Administrative Tools, and then double-click Internet Information Services (IIS) Manager.
In the Connections pane, expand the server name, and then click Application Pools.
In the Actions pane, click Add Application Pool....
In the Add Application Pool dialog box, enter the name of the application pool in the Name: box, in the .NET Framework version: drop-down list select the .NET Framework version your site or application uses, in the Managed pipeline mode: drop-down list select Integrated or Classic, and then click OK.
How to configure the application pool for an existing site or application
- In the Connections pane, expand Sites, and then navigate to the Web site or application you want to add to the application pool.
- In the Actions pane, click Advanced Settings...
- In the General section of the Advanced Settings dialog box, click the Application Pool entry, and then click the ellipses button.
- In the Select Application Pool dialog box, select the application pool from the Application pool: drop-down box, click OK, and then click OK again.
Configuration
The <add> element of the <applicationPools> collection is configurable at the server level in the ApplicationHost.config file.
Attributes
| Attribute | Description | ||||||||
|---|---|---|---|---|---|---|---|---|---|
autoStart |
Optional Boolean attribute. When true, indicates to the World Wide Web Publishing Service (W3SVC) that the application pool should be automatically started when it is created or when IIS is started. The default value is true. |
||||||||
CLRConfigFile |
Optional string value. Specifies the .NET configuration file for the application pool. Note: This attribute was added in IIS 7.5. There is no default value. |
||||||||
enable32BitAppOnWin64 |
Optional Boolean attribute. When true, enables a 32-bit application to run on a computer that runs a 64-bit version of Windows. The default value is false. |
||||||||
enableConfigurationOverride |
Optional Boolean attribute. When true, indicates that delegated settings in Web.config files will processed for applications within this application pool. When false, all settings in Web.config files will be ignored for this application pool. The default value is true. |
||||||||
managedPipelineMode |
Optional enum attribute. Specifies the request-processing mode that is used to process requests for managed content. The managedPipelineMode attribute can be one of the following possible values.
Integrated. |
||||||||
managedRuntimeLoader |
Optional string attribute. Specifies the managed loader to use for pre-loading the application pool. Note: This attribute was added in IIS 7.5. The default value is webengine4.dll. |
||||||||
managedRuntimeVersion |
Optional string attribute. Specifies the CLR version to be used by the application pool. The managedRuntimeVersion attribute can be one of the following possible values.
"". |
||||||||
name |
Required string attribute. Specifies a unique name for an application pool on the server. |
||||||||
passAnonymousToken |
Optional Boolean attribute. If true, the Windows Process Activation Service (WAS) creates and passes a token for the built-in IUSR anonymous user account to the Anonymous authentication module. The Anonymous authentication module uses the token to impersonate the built-in account. When PassAnonymousToken is false, the token will not be passed. Note: The IUSR anonymous user account replaces the IIS_MachineName anonymous account. The IUSR account can be used by IIS or other applications. It does not have any privileges assigned to it during setup. The default value is true. |
||||||||
queueLength |
Optional uint attribute. Indicates to HTTP.sys how many requests to queue for an application pool before rejecting future requests. The default value is 1000.When the value set for this property is exceeded, IIS rejects subsequent requests with a 503 error. If the loadBalancerCapabilities setting is true, the connection is closed instead of rejecting requests with a 503. For more information about loadBalancerCapabilities, see Failure Settings for an Application Pool. |
||||||||
startMode |
Optional enum value. Specifies the startup type for the application pool. Note: This attribute was added in IIS 7.5. The startMode attribute can be one of the following possible values.
OnDemand. |
Child Elements
| Element | Description |
|---|---|
cpu |
Configures CPU affinity and CPU actions. |
environmentVariables |
Configures a collection of environment variables to pass to worker processes. |
failure |
Configures actions to take when an application pool fails. |
processModel |
Configures process management attributes for an application pool. |
recycling |
Configures application pool recycling. |
Configuration Sample
The following configuration sample uses the application pool <add> element to create a new application pool named Contoso. The <recycling> element configures logging for application pool restarts, the <periodicRestart> element configures when the application pool restarts, and the <processModel> element configures the shutdownTimeLimit and startupTimeLimit attributes for shutting down and starting the worker processes in the application pool for 30 seconds each. If these time limits are exceeded, IIS terminates the worker process.
<add name="Contoso">
<recycling logEventOnRecycle="Schedule">
<periodicRestart>
<schedule>
<clear />
<add value="03:00:00" />
</schedule>
</periodicRestart>
</recycling>
<processModel identityType="NetworkService" shutdownTimeLimit="00:00:30" startupTimeLimit="00:00:30" />
</add>
Sample Code
The following code examples add an application pool named Contoso to your IIS 7 and later server, then set the application pool to daily recycle at 3:00 A.M.
AppCmd.exe
appcmd.exe set config -section:system.applicationHost/applicationPools /+"[name='Contoso']" /commit:apphost
appcmd.exe set config -section:system.applicationHost/applicationPools /+"[name='Contoso'].recycling.periodicRestart.schedule.[value='03:00:00']" /commit:apphost
You can also use the following syntax:
appcmd.exe add apppool /name:"Contoso"
appcmd.exe set config -section:system.applicationHost/applicationPools /+"[name='Contoso'].recycling.periodicRestart.schedule.[value='03:00:00']" /commit:apphost
Note
You must be sure to set the commit parameter to apphost when you use AppCmd.exe to configure these settings. This commits the configuration settings to the appropriate location section in the ApplicationHost.config file.
C#
using System;
using System.Text;
using Microsoft.Web.Administration;
internal static class Sample
{
private static void Main()
{
using (ServerManager serverManager = new ServerManager())
{
Configuration config = serverManager.GetApplicationHostConfiguration();
ConfigurationSection applicationPoolsSection = config.GetSection("system.applicationHost/applicationPools");
ConfigurationElementCollection applicationPoolsCollection = applicationPoolsSection.GetCollection();
ConfigurationElement addElement = applicationPoolsCollection.CreateElement("add");
addElement["name"] = @"Contoso";
ConfigurationElement recyclingElement = addElement.GetChildElement("recycling");
ConfigurationElement periodicRestartElement = recyclingElement.GetChildElement("periodicRestart");
ConfigurationElementCollection scheduleCollection = periodicRestartElement.GetCollection("schedule");
ConfigurationElement addElement1 = scheduleCollection.CreateElement("add");
addElement1["value"] = TimeSpan.Parse("03:00:00");
scheduleCollection.Add(addElement1);
applicationPoolsCollection.Add(addElement);
serverManager.CommitChanges();
}
}
}
VB.NET
Imports System
Imports System.Text
Imports Microsoft.Web.Administration
Module Sample
Sub Main()
Dim serverManager As ServerManager = New ServerManager
Dim config As Configuration = serverManager.GetApplicationHostConfiguration
Dim applicationPoolsSection As ConfigurationSection = config.GetSection("system.applicationHost/applicationPools")
Dim applicationPoolsCollection As ConfigurationElementCollection = applicationPoolsSection.GetCollection
Dim addElement As ConfigurationElement = applicationPoolsCollection.CreateElement("add")
addElement("name") = "Contoso"
Dim recyclingElement As ConfigurationElement = addElement.GetChildElement("recycling")
Dim periodicRestartElement As ConfigurationElement = recyclingElement.GetChildElement("periodicRestart")
Dim scheduleCollection As ConfigurationElementCollection = periodicRestartElement.GetCollection("schedule")
Dim addElement1 As ConfigurationElement = scheduleCollection.CreateElement("add")
addElement1("value") = TimeSpan.Parse("03:00:00")
scheduleCollection.Add(addElement1)
applicationPoolsCollection.Add(addElement)
serverManager.CommitChanges()
End Sub
End Module
JavaScript
var adminManager = new ActiveXObject('Microsoft.ApplicationHost.WritableAdminManager');
adminManager.CommitPath = "MACHINE/WEBROOT/APPHOST";
var applicationPoolsSection = adminManager.GetAdminSection("system.applicationHost/applicationPools", "MACHINE/WEBROOT/APPHOST");
var applicationPoolsCollection = applicationPoolsSection.Collection;
var addElement = applicationPoolsCollection.CreateNewElement("add");
addElement.Properties.Item("name").Value = "Contoso";
var recyclingElement = addElement.ChildElements.Item("recycling");
var periodicRestartElement = recyclingElement.ChildElements.Item("periodicRestart");
var scheduleCollection = periodicRestartElement.ChildElements.Item("schedule").Collection;
var addElement1 = scheduleCollection.CreateNewElement("add");
addElement1.Properties.Item("value").Value = "03:00:00";
scheduleCollection.AddElement(addElement1);
applicationPoolsCollection.AddElement(addElement);
adminManager.CommitChanges();
VBScript
Set adminManager = createObject("Microsoft.ApplicationHost.WritableAdminManager")
adminManager.CommitPath = "MACHINE/WEBROOT/APPHOST"
Set applicationPoolsSection = adminManager.GetAdminSection("system.applicationHost/applicationPools", "MACHINE/WEBROOT/APPHOST")
Set applicationPoolsCollection = applicationPoolsSection.Collection
Set addElement = applicationPoolsCollection.CreateNewElement("add")
addElement.Properties.Item("name").Value = "Contoso"
Set recyclingElement = addElement.ChildElements.Item("recycling")
Set periodicRestartElement = recyclingElement.ChildElements.Item("periodicRestart")
Set scheduleCollection = periodicRestartElement.ChildElements.Item("schedule").Collection
Set addElement1 = scheduleCollection.CreateNewElement("add")
addElement1.Properties.Item("value").Value = "03:00:00"
scheduleCollection.AddElement(addElement1)
applicationPoolsCollection.AddElement(addElement)
adminManager.CommitChanges()