Process Model Settings for an Application Pool <processModel>

Overview

By using the <processModel> element, you can configure many of the security, performance, health, and reliability features of application pools on Internet Information Services (IIS) 7.0. These include the following features:

• Application pool identity, which is the name of the service or user account under which the application pool's worker process runs. This is defined by the identityType attribute. By default, an application pool runs under the built-in NetworkService account. You can change the identityType attribute value to the built-in LocalService account, the built-in LocalSystem account, or a custom account that you create. If you choose a custom account, define the account credentials using the userName and password attributes. Be aware, however, that the LocalService and LocalSystem accounts have more user rights than the NetworkService account. It is a serious security risk to run an application pool using high-level user rights.
• Web gardening, which you can configure by setting the maxProcesses attribute to a value greater than one.
• Idle time-out settings, which allows you to set how long a worker process remains idle before it shuts downs. Edit the idleTimeout attribute to configure this setting.
• Health monitoring by enabling pings against the worker process, the maximum time allowed for a worker process to respond to a ping, and the frequency of pings sent to a worker process to monitor its health. Edit the pingingEnabled, pingInterval, and pingResponseTime attributes to configure these settings.
• Worker process shutdown and startup time limits. The first limit is set by the shutdownTimeLimit attribute and determines the interval that IIS 7.0 gives a worker process to finish all requests before the WWW service terminates the worker process. The second limit is set by the startupTimeLimit attribute and specifies the amount of time IIS 7.0 allows an application pool to start.

Compatibility

	IIS 7.0	IIS 6.0
Notes	The <processModel> element is new in IIS 7.0.	The <processModel> element replaces some of the settings in the IIS 6.0 IIsApplicationPools metabase object.

Setup

The <applicationPools> collection is included in the default installation of IIS 7.0.

How To

How to edit process model configuration settings

1. On the taskbar, click Start, point to Administrative Tools, and then click Internet Information Services (IIS) Manager.
2. In the Connections pane, expand the server name, click Application Pools, and click the application pool you want to edit.

   

3. In the Actions pane, click Advanced Settings...
4. In the Advanced Settings dialog box, click the process model property that you want to edit, and then edit it in the property value section of the dialog box, and then click OK. For example, change the Shutdown Time Limit (seconds) and Startup Time Limits (seconds) to 30.

   

Configuration

You configure the <processModel> element at the server level in the ApplicationHost.config file.

Attributes

Attribute	Description
identityType	Optional enum attribute. Specifies the account identity under which the application pool runs. The identityType attribute can be one of the following possible values. The default is NetworkService. Value Description LocalService Specifies that the application pool runs under the built-in LocalService account, which has the same user rights as NetworkService. When an application pool runs under the LocalService account, the application pool presents anonymous credentials on the network. The numeric value is 1. LocalSystem Specifies that the application pool runs under the built-in LocalSystem account, which has extensive privileges on the local computer and acts as the computer on the network. Note: Running an application pool under an account that has high-level user rights is a serious security risk. The numeric value is 0. NetworkService Specifies that the application pool runs under the built-in NetworkService account. This is the default built-in account under which to run application pools. When an application pool runs under the NetworkService account, the application pool accesses network resources as the computer account. The numeric value is 2. SpecificUser Specifies that the application pool runs under a custom identity, which is configured by using the userName and password attributes. Note: To avoid storing unencrypted password strings in configuration files, always use AppCmd.exe or IIS Manager to enter passwords. If you use these management tools, the password strings will be encrypted automatically before they are written to the XML configuration files. This provides better password security than storing unencrypted passwords. The numeric value is 3.
idleTimeout	Optional timeSpan attribute. Specifies how long (in minutes) a worker process should run idle if no new requests are received and the worker process is not processing requests. After the allocated time passes, the worker process should request that it be shut down by the WWW service. The default value is 00:20:00.
loadUserProfile	Optional Boolean attribute. Specifies whether IIS loads the user profile for the application pool identity. Setting this value to false causes IIS to revert to IIS 6.0 behavior. IIS 6.0 does not load the user profile for an application pool identity. The default value is false.
manualGroupMembership	Optional Boolean attribute. Specifies whether the IIS_IUSRS group Security Identifier (SID) is added to the worker process token. When false, IIS automatically uses an application pool identity as though it were a member of the built-in IIS_IUSRS group, which has access to necessary file and system resources. When true, an application pool identity must be explicitly added to all resources that a worker process requires at runtime. The default value is false.
maxProcesses	Optional uint attribute. Specifies the number of worker processes associated with the application pool. A value other than 1 indicates a Web garden. The default value is 1.
password	Optional string attribute. Specifies the password associated with the userName attribute. This attribute is only necessary when the value of identityType is SpecificUser. Note: To avoid storing unencrypted password strings in configuration files, always use AppCmd.exe or IIS Manager to enter passwords. If you use these management tools, the password strings will be encrypted automatically before they are written to the XML configuration files. This provides better password security than storing unencrypted passwords.
pingingEnabled	Optional Boolean attribute. Specifies whether pinging is enabled for the worker process. The default value is true.
pingInterval	Optional timeSpan attribute. Specifies the time between health-monitoring pings that the WWW service sends to a worker process. The default value is 00:00:30 (30 seconds).
pingResponseTime	Optional timeSpan attribute. Specifies the time that a worker process is given to respond to a health-monitoring ping. After the time limit is exceeded, the WWW service terminates the worker process. The default value is 00:01:30 (1 minute 30 seconds).
shutdownTimeLimit	Optional timeSpan attribute. Specifies the time that the W3SVC service waits after it initiated a recycle. If the worker process does not shut down within the shutdownTimeLimit, it will be terminated by the W3SVC service. The default value is 00:01:30 (1 minute 30 seconds).
startupTimeLimit	Optional timeSpan attribute. Specifies the time that IIS waits for an application pool to start. If the application pool does not startup within the startupTimeLimit, the worker process is terminated and the rapid-fail protection count is incremented. The default value is 00:01:30 (1 minute 30 seconds).
userName	Optional string attribute. Specifies the identity under which the application pool runs when the identityType is SpecificUser.

Child Elements

None.

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 examples change the processModel.shutdownTimeLimit and processModule.startupTimeLimit property values to 30 seconds each for an application pool named Contoso.

AppCmd.exe

appcmd.exe set apppool "Contoso" /processModel.shutdownTimeLimit:00:00:30

appcmd.exe set apppool "Contoso" /processModel.startupTimeLimit:00:00:30

You can also use the following syntax:

appcmd.exe set config -section:system.applicationHost/applicationPools /[name='Contoso'].processModel.shutdownTimeLimit:"00:00:30" /commit:apphost

appcmd.exe set config -section:system.applicationHost/applicationPools /[name='Contoso'].processModel.startupTimeLimit:"00:00:30" /commit:apphost

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 = FindElement(applicationPoolsCollection, "add", "name", @"Contoso");
         if (addElement == null) throw new InvalidOperationException("Element not found!");

         ConfigurationElement processModelElement = addElement.GetChildElement("processModel");
         processModelElement["shutdownTimeLimit"] = TimeSpan.Parse("00:00:30");
         processModelElement["startupTimeLimit"] = TimeSpan.Parse("00:00:30");

         serverManager.CommitChanges();
      }
   }

   private static ConfigurationElement FindElement(ConfigurationElementCollection collection, string elementTagName, params string[] keyValues)
   {
      foreach (ConfigurationElement element in collection)
      {
         if (String.Equals(element.ElementTagName, elementTagName, StringComparison.OrdinalIgnoreCase))
         {
            bool matches = true;
            for (int i = 0; i < keyValues.Length; i += 2)
            {
               object o = element.GetAttributeValue(keyValues[i]);
               string value = null;
               if (o != null)
               {
                  value = o.ToString();
               }
               if (!String.Equals(value, keyValues[i + 1], StringComparison.OrdinalIgnoreCase))
               {
                  matches = false;
                  break;
               }
            }
            if (matches)
            {
               return element;
            }
         }
      }
      return null;
   }
}

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 = FindElement(applicationPoolsCollection, "add", "name", "Contoso")

      If (addElement Is Nothing) Then
         Throw New InvalidOperationException("Element not found!")
      End If

      Dim processModelElement As ConfigurationElement = addElement.GetChildElement("processModel")
      processModelElement("shutdownTimeLimit") = TimeSpan.Parse("00:00:30")
      processModelElement("startupTimeLimit") = TimeSpan.Parse("00:00:30")
      serverManager.CommitChanges()
   End Sub

   Private Function FindElement(ByVal collection As ConfigurationElementCollection, ByVal elementTagName As String, ByVal ParamArray keyValues() As String) As ConfigurationElement
      For Each element As ConfigurationElement In collection
         If String.Equals(element.ElementTagName, elementTagName, StringComparison.OrdinalIgnoreCase) Then
            Dim matches As Boolean = True
            Dim i As Integer
            For i = 0 To keyValues.Length - 1 Step 2
               Dim o As Object = element.GetAttributeValue(keyValues(i))
               Dim value As String = Nothing
               If (Not (o) Is Nothing) Then
                  value = o.ToString
               End If
               If Not String.Equals(value, keyValues((i + 1)), StringComparison.OrdinalIgnoreCase) Then
                  matches = False
                  Exit For
               End If
            Next
            If matches Then
               Return element
            End If
         End If
      Next
      Return Nothing
   End Function
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 addElementPos = FindElement(applicationPoolsCollection, "add", ["name", "Contoso"]);
if (addElementPos == -1) throw "Element not found!";

var addElement = applicationPoolsCollection.Item(addElementPos);
var processModelElement = addElement.ChildElements.Item("processModel");
processModelElement.Properties.Item("shutdownTimeLimit").Value = "00:00:30";
processModelElement.Properties.Item("startupTimeLimit").Value = "00:00:30";

adminManager.CommitChanges();

function FindElement(collection, elementTagName, valuesToMatch) {
   for (var i = 0; i < collection.Count; i++) {
      var element = collection.Item(i);
      if (element.Name == elementTagName) {
         var matches = true;
         for (var iVal = 0; iVal < valuesToMatch.length; iVal += 2) {
            var property = element.GetPropertyByName(valuesToMatch[iVal]);
            var value = property.Value;
            if (value != null) {
               value = value.toString();
            }
            if (value != valuesToMatch[iVal + 1]) {
               matches = false;
               break;
            }
         }
         if (matches) {
            return i;
         }
      }
   }
   return -1;
}

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

addElementPos = FindElement(applicationPoolsCollection, "add", Array("name", "Contoso"))
If siteElementPos = -1 Then
   WScript.Echo "Element not found!"
   WScript.Quit
End If

Set addElement = applicationPoolsCollection.Item(addElementPos)
Set processModelElement = addElement.ChildElements.Item("processModel")
processModelElement.Properties.Item("shutdownTimeLimit").Value = "00:00:30"
processModelElement.Properties.Item("startupTimeLimit").Value = "00:00:30"

adminManager.CommitChanges()

Function FindElement(collection, elementTagName, valuesToMatch)
   For i = 0 To CInt(collection.Count) - 1
      Set element = collection.Item(i)
      If element.Name = elementTagName Then
         matches = True
         For iVal = 0 To UBound(valuesToMatch) Step 2
            Set Property = element.GetPropertyByName(valuesToMatch(iVal))
            value = property.Value
            If Not value = Null Then
               value = CStr(value)
            End If
            If Not value = valuesToMatch(iVal + 1) Then
               matches = False
               Exit For
            End If
         Next
         If matches Then
            Exit For
         End If
      End If
   Next
   If matches Then
      FindElement = i
   Else
      FindElement = -1
   End If
End Function