IIS 7.0 : Using Command Line Tools - Getting Started with Appcmd (part 1) - Appcmd Syntax

Appcmd.exe

Appcmd.exe is a new command line tool included with IIS 7.0. It exposes most of the Web server management tasks through a single intuitive command line interface. This tool replaces a host of command line tools and scripts provided in IIS 6.0 to perform key management scenarios.

Appcmd enables a Web server administrator to do the following from the command line:

1. Add and configure Web sites, applications, virtual directories, and application pools

2. Install, enable, and configure Web server modules

3. Start and stop sites and recycle application pools

4. View currently running worker processes and list requests that are currently executing

5. Search, list, and manipulate IIS and ASP.NET configuration

6. Configure Failed Request Tracing (FRT) settings

Most notable is the ability to list and edit IIS configuration, which enables administrators to quickly perform or automate any configuration task regardless of the feature they are trying to configure. The other functionality exposes some of the common configuration and management tasks for convenience.

Appcmd.exe is intended for local management of the Web server (it does not support remoting in IIS 7.0) and requires the user to have administrative privileges when using it. If you require remote management or the ability to configure the Web server without being an administrator on the server, you need to use the remote delegation support that IIS Manager provides. 

Getting Started with Appcmd

Appcmd.exe is located in the %SystemRoot%\System32\Inetsrv directory. Because this directory is not part of the PATH environment variable by default, you will need to either add it to the PATH or always use the full path to the command to be able to run Appcmd commands. For example, when using the latter, you can always run Appcmd as follows.

%systemroot%\system32\inetsrv\Appcmd list sites

We will omit the full path when showing Appcmd commands, assuming that you have either added the Inetsrv directory to the PATH environment variable or will manually add the full path to each command.

Note

To run Appcmd.exe, you will need to either add the Inetsrv directory to the PATH environment variable or use a full path to Appcmd.exe to run Appcmd commands.

To run Appcmd, you must be logged in as a member of the Administrators group on the local computer. Additionally, when using Appcmd on Windows Vista, you will need to run the tool as Administrator to make sure that the User Account Control does not prevent the tool from executing correctly. To do this, you should launch Appcmd commands from an elevated command prompt by launching the command prompt with the Run As Administrator option. To do this, open the Start menu, click All Programs, select Accessories, right-click Command Prompt, and choose Run As Administrator.

Note

To use Appcmd, you must be logged in as a member of the Administrators group. On Windows Vista, you will need to launch Appcmd commands from a command prompt started with the Run As Administrator option.

Appcmd commands use a natural language syntax of verb object, instead of the object verb syntax that some other Windows tools use to support commands on multiple object contexts (for example, netsh). For example, to list the Web sites on the server that are using the Site object, you would use the following command.

Appcmd list sites

Each command outputs one or more object instances or messages generated during the command execution. For example, the previous command may have the following output.

SITE "Default Web Site" (id:1,bindings:http/*:80:,state:Started)
SITE "TestSite" (id:2,bindings:http/*:80:testsite,state:Started)

The output is a list of Site objects, including their identifiers (Default Web Site, TestSite, and some of the key attributes of the object [id, bindings, state]).

Appcmd supports a number of objects, and most of the objects support a standard set of verbs such as List, Add, Set, and Delete. Some objects have additional verbs specific to the object. All verbs accept one or more parameters that you can use to customize the behavior of each command. Finally, some verbs accept a special parameter called the identifier, which uniquely identifies an instance of an object on which the verb should operate using an object-specific naming convention.

For example, you can use the Delete Site command with the site name as the identifier to delete a Web site, as in the following example.

Appcmd Delete Site "TestSite"

This has the following output.

SITE object "TestSite" deleted

Appcmd Syntax

Appcmd uses the following syntax.

Appcmd <verb> <object> [identifier] [/parameter:value]

This syntax includes the following parts:

• Verb. The verb is the action to be performed on the specified object. Each object supports a fixed set of verbs, and each verb may support using the identifier and one or more parameters, some of which may be required. Most objects support basic commands such as List, Add, Set, and Delete, and some objects support additional commands. The verb must always be specified. It is not case-sensitive.

• Object. The object is the name of the management object on which the specified verb is being invoked. Together with the verb, it determines the actual command that will be executed. The supported objects are listed in Table 1. The object must always be specified. It is not case-sensitive.

• Identifier. The identifier is an optional argument that follows the object, which you can use to uniquely identify the specific instance of the object that the command is being performed on. It is required by most commands that perform actions on a specific instance of the object, such as the Set and Delete commands. The identifier has an object-specific format used to identify instances of that object, and it may or may not be case-sensitive.
  

• Parameter. Each verb supports zero or more parameters, which are in the /name:value format, to control the execution of the command. The parameter names are not case-sensitive, but the values may be. 

Each Appcmd command must at minimum specify the object and verb. For example, to use the List verb on the Site object to list Web sites on the server, you can use the following command.

Appcmd List Site

The List verb of the Site object can accept an optional identifier to uniquely specify the Web site you are interested in listing. The Site object uses the Web site name as the unique identifier (not the Web site id). Therefore, to find a specific Web site named Default Web Site, we can use the following syntax.

Appcmd List Site "Default Web Site"

Alternatively, we can use optional parameters instead of the identifier to search for all Web site instances that have certain attributes. In fact, you can specify any of the configuration attributes in the Web site definition as parameters to the List Site command, to find all sites that have those configuration parameters set to the provided values. For example, to find all Web sites that have the serverAutoStart configuration attribute set to false, you can use the following syntax.

Appcmd List Site /serverAutoStart:false

For the list of supported objects and verbs, see the following section titled Supported Objects.

Supported Objects

Appcmd supports the objects and corresponding commands listed in Table 1.

Table 1. Appcmd-Supported Objects

Object	Description	Commands
Site (Sites)	Manage Web sites	List, Set, Add, Delete, Start, Stop
App (Apps)	Manage applications	List, Set, Add, Delete
Vdir (Vdirs)	Manage virtual directories	List, Set, Add, Delete
Apppool (Apppools)	Manage application pools	List, Set, Add, Delete, Start, Stop, Recycle
Config (Configs)	Manage IIS configuration sections	List, Set, Search, Lock, Unlock, Clear, Reset, Migrate
Wp (Wps)	List currently executing worker processes	List
Request (Requests)	List currently executing HTTP requests	List
Module (Modules)	Manage Web server modules	List, Set, Add, Delete, Install, Uninstall
Backup (Backups)	Manage configuration backups	List, Add, Delete, Restore
Trace (Traces)	Manage Failed Request Tracing (FRT) configuration and trace logs	List, Configure, Inspect

Note

Note that in the Object column, the plural form of each object name is also listed. This is because Appcmd supports an alias for each object and uses this to enable the plural form of the object to also be used to refer to it. Because of this, you can use the List Sites (plural) command to list Web sites while using Set Site (singular) to set a configuration attribute on the Web site.