BuildMaster Documentation

Iis - Ensure App Pool

  • Last Modified: 2019-06-19

This is generated from the built-in components of BuildMaster 6.1.7, and may be different than what you have installed (especially if you have extensions); go to [User Icon] > Documentation within your BuildMaster instance to see exactly what operations are available.

Ensure App Pool

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>],
	[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", or "v1.1".
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.
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.
Otter credentials
text
Credentials
The Otter 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

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
);

Is this documentation incorrect or incomplete? Help us by contributing!

This documentation is licensed under CC-BY-SA-4.0 and stored in GitHub.