PowerShell Snap-in: Using the Task-based Cmdlets of the IIS PowerShell Snap-in
by Thomas Deml
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
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:
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:
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
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 extrememly 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"
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.