Ensure App Pool
This is generated from the built in components of BuildMaster 2024.0, and may be different than what you have installed (especially if you have extensions); go to [Gear Icon] -> Administration -> Operations within your BuildMaster instance to see exactly what operations are available.
Ensures the existence of an application pool on a server.
Script usage:
IIS::Ensure-AppPool(
Name: <text>,
[Runtime: <text>],
[Enable32BitAppOnWin64: <true/false>],
[Pipeline: <integer>],
[AutoStart: <true/false>],
[StartMode: <integer>],
[QueueLength: <Int64>],
[State: <integer>],
[IdentityType: <integer>],
[Credentials: <text>],
[UserName: <text>],
[Password: <text>],
[CpuLimit: <Int64>],
[CpuAction: <integer>],
[CpuResetInterval: <TimeSpan>],
[CpuSmpAffinitized: <true/false>],
[CpuSmpProcessorAffinityMask: <Int64>],
[CpuSmpProcessorAffinityMask2: <Int64>],
[IdleTimeout: <TimeSpan>],
[LoadUserProfile: <true/false>],
[MaxProcesses: <Int64>],
[PingingEnabled: <true/false>],
[PingResponseTime: <TimeSpan>],
[PingInterval: <TimeSpan>],
[ShutdownTimeLimit: <TimeSpan>],
[StartupTimeLimit: <TimeSpan>],
[OrphanWorkerProcess: <true/false>],
[OrphanActionExe: <text>],
[OrphanActionParams: <text>],
[LoadBalancerCapabilities: <integer>],
[RapidFailProtection: <true/false>],
[RapidFailProtectionInterval: <TimeSpan>],
[RapidFailProtectionMaxCrashes: <Int64>],
[AutoShutdownExe: <text>],
[AutoShutdownParams: <text>],
[DisallowOverlappingRotation: <true/false>],
[DisallowRotationOnConfigChange: <true/false>],
[PeriodicRestartPrivateMemory: <Int64>],
[PeriodicRestartTime: <TimeSpan>],
[PeriodicRestartRequests: <Int64>],
[PeriodicRestartSchedule: <@(text)>],
[PeriodicRestartMemory: <Int64>],
[Exists: <true/false>]
);
Arguments:
| Name | Format | Script Usage | Usage Notes |
|---|---|---|---|
| ☆ Name | text | Name | The unique name of the IIS site or application pool. This argument is required. |
| .NET CLR version | text | Runtime | The .NET runtime version used by this application pool. Current valid values are v4.0, v2.0, v1.1, or none. |
| Enable 32-bit applications | true/false | Enable32BitAppOnWin64 | If set to True for an application pool on a 64-bit operating system, the worker process(es) serving the application pool run in WOW64 (Windows on Windows64) mode. In WOW64 mode, 32-bit processes load only 32-bit applications. |
| Managed pipeline mode | integer | Pipeline | Configures ASP.NET to run in classic mode as an ISAPI extension or in integrated mode where managed code is integrated into the request-processing pipeline. |
| Start automatically | true/false | AutoStart | If True, the application pool starts on creation or when IIS starts. Starting an application pool sets this property to True. Stopping an application sets this property to False. |
| Start mode | integer | StartMode | Configures application pool to run in On Demand Mode or Always Running Mode. |
| Queue length | Int64 | QueueLength | Maximum number of requests that Http.sys queues for the application pool. When the queue is full, new requests receive a 503 "Service Unavailable" response. |
| State | integer | State | Sets the running state for the application pool. |
| Identity type | integer | IdentityType | Configures the application pool to run as a built-in account, such as Network Service (recommended), Local Service, or as a specific user identity. |
| Credentials | text | Credentials | The credential name to use for the application pool's identity. If a credential name is specified, the username and password fields will be ignored. |
| User name | text | UserName | Configures the application pool to run as a built-in account, such as Network Service (recommended), Local Service, or as a specific user identity. |
| Password | text | Password | |
| Limit (percent) | Int64 | CpuLimit | Configures the maximum percentage of CPU time (in 1/1000ths of a percent) that the worker processes in an application pool are allowed to consume over a period of time as indicated by the Limit Interval setting (resetInterval property). If the limit set by Limit (limit property) is exceeded, the event is written to the event log and an optional set of events can be triggered or determined by the Limit Action setting (action property). Setting the value of Limit to 0 disables limiting the worker processes to a percentage of CPU time. |
| Limit action | integer | CpuAction | If set to NoAction, an event log entry is generated. If set to KillW3WP, the application pool is shut down for the duration of the reset interval and an event log entry is generated. |
| Limit interval (minutes) | TimeSpan | CpuResetInterval | Specifies the reset period (in minutes) for CPU monitoring and throttling limits on the application pool. When the number of minutes elapsed since the last process accounting reset equals the number specified by this property, IIS resets the CPU timers for both the logging and limit intervals. Setting the value of Limit Interval to 0 disables CPU monitoring. |
| Processor affinity enabled | true/false | CpuSmpAffinitized | If True, Processor Affinity Enabled forces the worker process(es) serving this application pool to run on specific CPUs. This enables sufficient use of CPU caches on multiprocessor servers. |
| Processor affinity mask | Int64 | CpuSmpProcessorAffinityMask | Hexadecimal mask that forces the worker process(es) for this application pool to run on a specific CPU. If processor affinity is enabled, a value of 0 causes an error condition. |
| Processor affinity (64-bit) | Int64 | CpuSmpProcessorAffinityMask2 | Hexadecimal mask that forces the worker process(es) for this application pool to run on a specific CPU. If processor affinity is enabled, a value of 0 causes an error condition. |
| Idle time-out (minutes) | TimeSpan | IdleTimeout | Amount of time (in minutes) a worker process remains idle before it shuts down. A worker process is idle if it is not processing requests and no new requests are received. |
| Load user profile | true/false | LoadUserProfile | Specifies whether IIS loads the user profile for an application pool identity. When set to True, IIS loads the user profile for the application pool identity. Set to False when you require IIS 6.0 behavior. |
| Max worker processes | Int64 | MaxProcesses | Maximum number of worker processes permitted to service requests for the application pool. If this number is greater than 1, the application pool is called a Web garden. |
| Ping enabled | true/false | PingingEnabled | If True, the worker process(es) serving this application pool are pinged periodically to ensure that they are still responsive. This process is called health monitoring. |
| Ping max response time (seconds) | TimeSpan | PingResponseTime | Maximum time (in seconds) that a worker process is given to respond to a health monitoring ping. If the worker process does not respond, it is terminated. |
| Ping period (seconds) | TimeSpan | PingInterval | Period of time (in seconds) between health monitoring pings sent to the worker process(es) serving this application pool. |
| Shutdown time limit (seconds) | TimeSpan | ShutdownTimeLimit | Period of time (in seconds) a worker process is given to finish processing requests and shut down. If the worker process exceeds the shutdown time limit, it is terminated. |
| Startup time limit (seconds) | TimeSpan | StartupTimeLimit | Period of time (in seconds) a worker process is given to start up and initialize. If the worker process initialization exceeds the startup time limit, it is terminated. |
| Process orphaning enabled | true/false | OrphanWorkerProcess | If True, an unresponsive worker process is abandoned (orphaned) instead of terminated. This feature can be used to debug a worker process failure. |
| Process orphaning executable | text | OrphanActionExe | Executable to run when a worker process is abandoned (orphaned). For example, C:\dbgtools tsd.exe would invoke NTSD to debug a worker process failure. |
| Executable parameters | text | OrphanActionParams | Parameters for the executable that is run when a worker process is abandoned (orphaned). For example, -g –p %1% is appropriate if the NTSD is the executable invoked for debugging worker process failures. |
| Service unavailable response type | integer | LoadBalancerCapabilities | If set to HttpLevel and the application pool is stopped, Http.sys returns an HTTP 503 error. If set to TcpLevel, Http.sys resets the connection. This is useful if the load balancer recognizes one of the response types and subsequently redirects it. |
| Rapid fail protection enabled | true/false | RapidFailProtection | If True, the application pool is shut down if there are a specified number of worker process failures (Maximum Failures) within a specified period (Failure Interval). By default, an application pool is shut down if there are five failures in a five minute period. |
| Failure interval (minutes) | TimeSpan | RapidFailProtectionInterval | The time interval (in minutes) during which the specified number of worker process failures (Maximum Failures) must occur before the application pool is shut down by Rapid Fail Protection. |
| Maximum failures | Int64 | RapidFailProtectionMaxCrashes | Maximum number of worker process failures permitted before the application pool is shut down by Rapid Fail Protection. |
| Shutdown executable | text | AutoShutdownExe | Executable to run when an application pool is shut down by Rapid Fail Protection.This can be used to configure a load balancer to redirect traffic for this application to another server. |
| Shutdown executable parameters | text | AutoShutdownParams | Parameters for the executable to run when an application pool is shut down by Rapid Fail Protection. |
| Disable overlapped recycle | true/false | DisallowOverlappingRotation | If True, when the application pool recycles, the existing worker process exits before another worker process is created. Set to True if the worker process loads an application that does not support multiple instances. |
| Disable for config changes | true/false | DisallowRotationOnConfigChange | If True, the application pool does not recycle when its configuration is changed. |
| Private memory limit (KB) | Int64 | PeriodicRestartPrivateMemory | Maximum amount of private memory (in KB) a worker process can consume before causing the application pool to recycle. A value of 0 means there is no limit. |
| Regular time interval (minutes) | TimeSpan | PeriodicRestartTime | Period of time (in minutes) after which an application pool recycles. A value of 0 means the application pool does not recycle at a regular interval. |
| Request Limit | Int64 | PeriodicRestartRequests | Maximum number of requests an application pool can process before it is recycled. A value of 0 means the application pool can process an unlimited number of requests. |
| Schedule | @(text) | PeriodicRestartSchedule | Specific times of day to recycle the application pool. For example, @(3:30:00, 10:00:00, 23:59:59). |
| Virtual memory limit (KB) | Int64 | PeriodicRestartMemory | Maximum amount of virtual memory (in KB) a worker process can consume before causing the application pool to recycle. A value of 0 means there is no limit. |
| Exists | true/false | Exists | Default value is "True". |
See also:
Example:
# ensures that the Otter application pool is present on the web server
IIS::Ensure-AppPool(
Name: OtterAppPool,
Pipeline: 1, # classic mode
Runtime: v4.0
);
# ensures that the DefaultAppPool is removed from the web server
IIS::Ensure-AppPool(
Name: DefaultAppPool,
Exists: false
);