Edytuj

Udostępnij za pośrednictwem

Failure Settings for an Application Pool <failure>

  • Artykuł

Overview

The <failure> element of the <add> element in the <applicationPools> collection configures the actions to take when an application pool fails. The autoShutdownExe, orphanActionExe, rapidFailProtection attributes of the <failure> element can be especially useful when troubleshooting or debugging applications, because they give you the flexibility to specify the action that Internet Information Services (IIS) will take when an application fails, such as running an external executable to log or debug the failure.

Compatibility

Version Notes
IIS 10.0 The <failure> element was not modified in IIS 10.0.
IIS 8.5 The <failure> element was not modified in IIS 8.5.
IIS 8.0 The <failure> element was not modified in IIS 8.0.
IIS 7.5 The <failure> element was not modified in IIS 7.5.
IIS 7.0 The <failure> element was introduced in IIS 7.0.
IIS 6.0 The <failure> element replaces portions of the IIS 6.0 IIsApplicationPools metabase property.

Setup

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

How To

How to edit rapid-fail protection configuration settings

  1. 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.

  2. In the Connections pane, expand the server name, click Application Pools, and click the application pool you want to edit.
    Image of Connections pane displaying App Default Pool option highlighted.

  3. In the Actions pane, click Advanced Settings...

  4. In the Advanced Settings dialog box, click the rapid-fail protection property that you want to edit, then edit the value in the property value section of the dialog box, and then click OK. For example, change the Failure Interval (minutes) to 4 and Maximum Failures to 4.
    Screenshot of Advanced Settings dialog box displaying Maximum Failures highlighted.

Configuration

Attributes

Attribute Description
autoShutdownExe Optional string attribute. Specifies an executable to run when the WWW service shuts down an application pool. You can use the autoShutdownParams attribute to send parameters to the executable.
autoShutdownParams Optional string attribute. Specifies command-line parameters for the executable that is specified in the autoShutdownExe attribute.
loadBalancerCapabilities Optional enum attribute. Specifies behavior when a worker process cannot be started, such as when the request queue is full or an application pool is in rapid-fail protection. The loadBalancerCapabilities attribute can be one of the following possible values. The default value is HttpLevel.

Value Description
HttpLevel Specifies that a 503 error code has been returned. Load balancers that are not HTTP aware will not switch to a different node because the 503 response tells the load balancer that the computer is healthy.

The numeric value is 2.

TcpLevel Specifies that the TCP connection will terminate. This is useful when you use a load balancer that is not HTTP aware.

The numeric value is 1.
orphanActionExe Optional string attribute. Specifies an executable to run when the WWW service orphans a worker process (if the orphanWorkerProcess attribute is set to true). You can use the orphanActionParams attribute to send parameters to the executable.
orphanActionParams Optional string attribute. Indicates command-line parameters for the executable named by the orphanActionExe attribute. To specify the process ID of the orphaned process, use %1%.
orphanWorkerProcess Optional Boolean attribute. Specifies whether to assign a worker process to an orphan state instead of terminating it when an application pool fails.

The default value is false.
rapidFailProtection Optional Boolean attribute. Setting to true instructs the WWW service to remove from service all applications that are in an application pool when:

  • The number of worker process crashes has reached the maximum specified in the rapidFailProtectionMaxCrashes attribute.
  • The crashes occur within the number of minutes specified in the rapidFailProtectionInterval attribute.
The default value is true.
rapidFailProtectionInterval Optional timeSpan attribute. Specifies the number of minutes before the failure count for a process is reset.

The default value is 00:05:00 (five minutes).
rapidFailProtectionMaxCrashes Optional uint attribute. Specifies the maximum number of failures that are allowed within the number of minutes specified by the rapidFailProtectionInterval attribute. Note: Starting in IIS 7.5 this value must be between 1 and 2147483647.

The default value is 5.

Child Elements

None.

Configuration Sample

The following configuration sample enables rapid failure protection for a single application pool named DefaultAppPool, configures a rapid fail protection interval of 5 minutes, and sets the maximum number of failures within the number of minutes to 5.

<applicationPools>
   <add name="DefaultAppPool">
     <failure rapidFailProtection="true"
        rapidFailProtectionInterval="00:05:00"
        rapidFailProtectionMaxCrashes="5" />
   </add>
   <applicationPoolDefaults>
     <processModel identityType="NetworkService" />
   </applicationPoolDefaults>
</applicationPools>

Sample Code

The following code examples enable rapid fail protection for the DefaultAppPool on your server, then set the protection interval to five minutes, and set the maximum number of crashes to 5.

AppCmd.exe

appcmd.exe set config -section:system.applicationHost/applicationPools /[name='DefaultAppPool'].failure.rapidFailProtection:"True" /commit:apphost

appcmd.exe set config -section:system.applicationHost/applicationPools /[name='DefaultAppPool'].failure.rapidFailProtectionInterval:"00:05:00" /commit:apphost

appcmd.exe set config -section:system.applicationHost/applicationPools /[name='DefaultAppPool'].failure.rapidFailProtectionMaxCrashes:"5" /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 = FindElement(applicationPoolsCollection, "add", "name", @"DefaultAppPool");
         if (addElement == null) throw new InvalidOperationException("Element not found!");

         ConfigurationElement failureElement = addElement.GetChildElement("failure");
         failureElement["rapidFailProtection"] = true;
         failureElement["rapidFailProtectionInterval"] = TimeSpan.Parse("00:05:00");
         failureElement["rapidFailProtectionMaxCrashes"] = 5;
         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", "DefaultAppPool")

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

      Dim failureElement As ConfigurationElement = addElement.GetChildElement("failure")
      failureElement("rapidFailProtection") = True
      failureElement("rapidFailProtectionInterval") = TimeSpan.Parse("00:05:00")
      failureElement("rapidFailProtectionMaxCrashes") = 5

      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", "DefaultAppPool"]);
if (addElementPos == -1) throw "Element not found!";
var addElement = applicationPoolsCollection.Item(addElementPos);

var failureElement = addElement.ChildElements.Item("failure");
failureElement.Properties.Item("rapidFailProtection").Value = true;
failureElement.Properties.Item("rapidFailProtectionInterval").Value = "00:05:00";
failureElement.Properties.Item("rapidFailProtectionMaxCrashes").Value = 5;

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 = WScript.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", "DefaultAppPool"))

If (siteElementPos = -1) Then
   WScript.Echo "Element not found!"
   WScript.Quit
End If

Set addElement = applicationPoolsCollection.Item(addElementPos)
Set failureElement = addElement.ChildElements.Item("failure")
failureElement.Properties.Item("rapidFailProtection").Value = true
failureElement.Properties.Item("rapidFailProtectionInterval").Value = "00:05:00"
failureElement.Properties.Item("rapidFailProtectionMaxCrashes").Value = 5

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 IsNull(value) Then
               value = CStr(value)
            End If
            If Not value = CStr(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