PowerShell Snap-in: Using the Task-based Cmdlets of the IIS PowerShell Snap-in
by Thomas Deml
Introduction
IIS PowerShell Snap-in cmdlets can be grouped into three categories:
- Cmdlets required by the Provider Hierarchy
- low-level configuratioin cmdlets
- Task-based cmdlets
This walkthrough introduces the task-based IIS cmdlet and gives some examples how to use them.
Cmdlets Required by the Provider Hierarchy
IIS decided early on to make IIS configuration available as an hierarchy of Sites, Applications, Virtual Directories and Application Pools. The benefit is that customers can navigate to a location, e.g. a Site or Application, in the hierarchy and set settings in this context. To support a navigation hierarchy certain pre-defined PowerShell cmdlets like New-Item, Set-ItemProperty etc. have to be implemented. The hierarchy and these built-in cmdlets were shipped in Tech Preview 1 in April 2008.
Low-level Configuration Cmdlets
The IIS configuration system was completely revised in version 7. The new configuration system is fully XML-based, schema-driven and completely extensible. The new IIS FTP Server (FTP7) and many other IIS modules like the URL Rewriter, WebDAV etc. leverage this extensibilty to plug into the IIS configuration system.
This extensibilty makes it hard to ship cmdlets with static arguments. Imagine the case where somebody extends an existing configuration section, for example somebody adds a myFancyNewBehavior property to the virtualDirectory configuration section. Without revising the IIS cmdlets fancyNewBehavior setting wouldn't be settable via the PowerShell Snap-in cmdlets.
Technical Preview 1 of the IIS PowerShell Snap-in included only low-level cmdlets that took the total configuration extensibility in account. Every IIS configuration setting (more than 100 configuration sections with collections, enumerations etc.) can be configured using these cmdlets. These low-level cmdlets also work against custom configuration, for example if you extended IIS configuration with your own configuration section.
Here is the list of low-level cmdlets we ship since Tech Preview 1 back in April 2008:
Add-WebConfiguration
Add-WebConfigurationProperty
Begin-WebCommitDelay
Clear-WebConfiguration
End-WebCommitDelay
Get-WebURL
Get-WebConfiguration
Get-WebConfigurationProperty
Get-WebItemState
Remove-WebConfigurationProperty
Restart-WebItem
Set-WebConfiguration
Set-WebConfigurationProperty
Select-WebConfiguration
Start-WebItem
Stop-WebItem
Task-based Cmdlets
Here comes the exciting news. For day-to-day IIS tasks like creating web-sites, enabled request tracing, adding a handler or a module you probably want to use the task-based cmdlets that come with the IIS PowerShell Snap-in. Here is a list of the task-based cmdlets:
Add-WebConfigurationLock
Backup-WebConfiguration
Clear-WebRequestTracingSettings
ConvertTo-WebApplication
Disable-WebGlobalModule
Disable-WebRequestTracing
Enable-WebGlobalModule
Enable-WebRequestTracing
Get-WebAppDomain
Get-WebApplication
Get-WebAppPoolState
Get-WebBinding
Get-WebConfigFile
Get-WebConfigurationBackup
Get-WebConfigurationLocation
Get-WebConfigurationLock
Get-WebFilePath
Get-WebGlobalModule
Get-WebHandler
Get-WebItemState
Get-WebManagedModule
Get-WebRequest
Get-Website
Get-WebsiteState
Get-WebURL
Get-WebVirtualDirectory
New-WebApplication
New-WebAppPool
New-WebBinding
New-WebFtpSite
New-WebGlobalModule
New-WebHandler
New-WebManagedModule
New-Website
New-WebVirtualDirectory
Remove-WebApplication
Remove-WebAppPool
Remove-WebBinding
Remove-WebConfigurationBackup
Remove-WebConfigurationLocation
Remove-WebConfigurationLock
Remove-WebGlobalModule
Remove-WebHandler
Remove-WebManagedModule
Remove-Website
Remove-WebVirtualDirectory
Rename-WebConfigurationLocation
Restart-WebAppPool
Set-WebBinding
Set-WebGlobalModule
Set-WebHandler
Set-WebManagedModule
Start-WebAppPool
Start-Website
Stop-WebAppPool
Stop-Website
Help for the Task-based Cmdlets
'Using the built-in help system is the easiest way to find out what cmdlets are available and how to use them. The following command lists all IIS cmdlets.
get-command -pssnapin WebAdministration
Another way is to look for -Web prefix we use for all IIS cmdlets. Try this command:
get-command *-Web*
The built-in help system gives you a quick description about an individual cmdlet, about the parameters and arguments it takes and it has examples how to use the cmdlet. Try the following:
get-help New-WebSite
To receive the full help about a particular cmdlet you can enter the following:
get-help New-Website -full
If you only want to see an example how to use it try the following command:
get-help New-Website -example
End-to-end Example
The power of the task-based cmdlets shows when you use it for an end-to-end scenario. In the following example we will create an new web-site, add some content to the web-site, make some configuration changes, enable Request Tracing and request the new content page.
Step 1: Creating a new web-site
Enter the following commands:
PS IIS:\>mkdir "$env:systemdrive\inetpub\MyNewWebSite"
This creates a new physical directory for our new site.
PS IIS:\>New-Website -name "MyNewWebSite" -PhysicalPath "$env:systemdrive\inetpub\MyNewWebSite" -port 81
The line above creates a new web site pointing to the newly created directory and listening on port 81.
Step 2: Adding content to the site
The following commands will navigate the IIS namespace and create a new content file.
PS IIS:\>cd IIS:\sites\MyNewWebsite
The command above navigates to the MyNewWebSite node in the IIS namespace.
PS IIS:\Sites\MyNewWebSite> dir
The above command lists all the contents of the new web site. It won't show anything because there is no content.
PS IIS:\Sites\MyNewWebSite> notepad "$(Get-WebFilePath .)\test.htm"
The above command opens notepad and allows you to edit test.htm. Instead of having to remember where the physical path of your web site. Enter some text, e.g. "Hello World" and save the file in notepad.
PS IIS:\Sites\MyNewWebSite> dir
If you enter the dir command again it will show you the newly created file test.htm.
PS IIS:\Sites\MyNewWebSite> Get-WebURL -content ".\test.htm"
The above command will make a HTTP request to the newly created web site and return the content you entered into notepad.
Step 3: Enabling Request Tracing
IMPORTANT: For this example to work the IIS Tracing feature needs to be enabled. On Windows Vista open the Control Panel, click "Programs", select "Turn Windows features on or off". Find and select "Tracing" under "Internet Information Services", "World Wide Web Services", "Health and Diagnostics" and click "OK".
As a last step we are enabling Request Tracing. Web Request Tracing is an IIS feature which allows you to get a detailed log of what happened during a request was executing. This feature is extremely valuable for a lot of troubleshooting scenarios. To enable Web Request Tracing we just need to run another location-aware cmldet called Enable-WebRequestTracing.
PS IIS:\Sites\MyNewWebSite> Enable-WebRequestTracing
Now let's look into the web.config file what configuration got written by the Enable-WebRequestTracing cmdlet. We do this by using the Get-WebConfigFile cmdlet which is also location-aware:
PS IIS:\Sites\MyNewWebSite> notepad (Get-WebConfigFile)
The configuration looks like this:
Contents of web.config file
<?xml version="1.0" encoding="UTF-8"?>
<configuration>
<system.webServer>
<tracing>
<traceFailedRequests>
<add path="*">
<traceAreas>
<add provider="ASPNET" areas="Infrastructure,Module,Page,AppServices" verbosity="Verbose" />
</traceAreas>
<failureDefinitions timeTaken="00:00:30" statusCodes="200-500" verbosity="Warning" />
</add>
</traceFailedRequests>
</tracing>
</system.webServer>
</configuration>
The important configuration is the failureDefinitions rule. By default a trace file is generated when the error code is between 200 and 500 or when the request takes longer than 30 seconds. Let's issue a request that generates a response in the 200-500 error range by executing the following command:
PS IIS:\Sites\MyNewWebSite>Get-WebURL -url http://localhost:81/URL_DOES_NOT_EXIST
A request to a non-existing resource generates a 404 error. To look at the trace file you have to navigate to the following location:
PS IIS:\Sites\MyNewWebSite>cd "$env:systemdrive\inetpub\logs\failedReqLogfiles\w3svc2\"
Now you can look at the trace file by opening the xml file in Internet Explorer:
PS C:\inetpub\logs\FailedReqLogFiles\W3SVC2>&"$env:programfiles\Internet Explorer\iexplore.exe" "$env:systemdrive\inetpub\logs\failedReqLogfiles\w3svc2\fr000001.xml"
Summary
The new task-based cmdlets will give Administrators an easy way to accomplish day-to-day IIS task with PowerShell. The cmdlets offer location-awareness and intuitive syntax and help.
The low-level IIS cmdlets shipped since Tech Preview 1 will still allow more advanced IIS Administration tasks.