Appcmd.exe (IIS 8)

 

Applies To: Windows Server 2012 R2, Windows Server 2012

IIS 8 provides a command-line tool, Appcmd.exe, to configure and query objects on your web server, and to return output in text or XML. The following examples are tasks that you can complete with Appcmd.exe:

• Create and configure sites, applications, application pools, and virtual directories.

• Start and stop sites.

• Start, stop, and recycle application pools.

• View information about worker processes and requests that are running on the web server.

Appcmd.exe provides consistent commands for common queries and configuration tasks, which reduces the complexity of learning syntax. For example, you can use the list command to search for information about an object, such as an application, or you can use the add command to create an object, such as a site.

Additionally, you can combine commands together to return more complex data about objects on your web server or to perform tasks that are more complex. For example, you can complete complex tasks like stopping all sites that have requests that have been running longer than 60 seconds.

In this document

• Start Appcmd.exe

• Get help about Appcmd.exe

• Working with objects in Appcmd.exe

• Working with commands in Appcmd.exe

• Working with attributes and values in Appcmd.exe

• Errors and the AppHostConfig attribute

• Configure server-level settings by using Appcmd.exe

• Configure settings for a site, application, virtual directory, or URL by using Appcmd.exe

• Use Appcmd.exe to change configuration in a Web.config file

• Use Appcmd.exe to change configuration in a parent-level configuration file

Start Appcmd.exe

Open Appcmd.exe if you want to configure IIS 8 settings by using a command-shell window. Appcmd.exe resides in the %windir%\system32\inetsrv directory, which is available only to the Administrator account or to users who are members of the Administrators group on the computer. In addition, members of the Administrators group must start Appcmd.exe with elevated permissions to view and change settings in the server-level configuration files: Machine.config, the root Web.config file (in the .NET Framework directory), and in ApplicationHost.config. Users who view or change Web.config files in site or application directories must have access to read and write to files in those directories.

Note

If you are running 64-bit Windows, use Appcmd.exe from the %windir%\system32\inetsrv directory, not the %windir%\syswow64\inetsrv directory.

To start Appcmd.exe

1. Click Start, and then click All Programs.

2. Click Accessories, and then click Command Prompt.

3. At the Command Prompt, type cd %windir%\system32\inetsrv, and then press ENTER.

Note

To run the Command Prompt as an administrator, right-click the icon in the Start menu, and then click Run as administrator.

Get help about Appcmd.exe

Appcmd.exe contains built-in help information. To view help information about Appcmd.exe, type a command and then type /?.

For example, if you want to view introductory help information about Appcmd.exe, type the following command at the command prompt, and then press ENTER:

appcmd /?

To view help information about a specific Appcmd.exe object, such as the commands that you can use with the site object, type the following command at the command prompt, and then press ENTER:

appcmd site /?

To view help information about the settings that you can configure by using an Appcmd.exe object and command, such as the site object and add command, type the following at the command prompt, and then press ENTER:

appcmd add site /?

Working with objects in Appcmd.exe

Use objects in Appcmd.exe to specify what you want to view or change in configuration. To view a list of Appcmd.exe objects, type the following command at the command prompt, and then press ENTER:

appcmd /?

You can then configure the object by using commands. For more information about commands, see Working with commands in Appcmd.exe.

Working with commands in Appcmd.exe

Use Appcmd.exe commands to view or change configuration settings for an Appcmd.exe object. Each of these objects has commands that enable you to work with that object. To view the commands for an object, use the following syntax:

appcmd object /?

The variable object is the name of the object for which you want to view commands. For example, to view a list of commands for the site object, type the following command at the command prompt, and then press ENTER:

appcmd site /?

For more information about Appcmd.exe objects, see Working with objects in Appcmd.exe.

Working with attributes and values in Appcmd.exe

Specify values for attributes when you want to limit the results of a list command, or when you want to change the value of an attribute for an Appcmd.exe object.

For example, to list application pools configured to use Network Service, type the following command at the command prompt, and then press ENTER:

appcmd list apppool /processModel.identityType:NetworkService

Alternatively, to configure an application pool named Marketing to use Network Service, type the following command at the command prompt, and then press ENTER:

appcmd set apppool /apppool.name:Marketing /processModel.identityType:NetworkService

The processModel.identityType attribute is used in both of the previous examples. In the first example, the attribute limits the query results by listing only application pools that are configured to use Network Service. In the second example, the attribute specifies that the Marketing application pool use the Network Service identity.

Errors and the AppHostConfig attribute

In Windows 8 and Windows Server 2012, the AppHostConfig attribute was added. The AppHostConfig attribute enables you to edit an AppHost configuration file that is not the default AppHost configuration file. Although this attribute is useful in many situations, invalid values are ignored under the following verb/object combinations:

Verb	Object
Start or Stop	Site
Start, Stop, or Recycle	AppPool
All verbs	Backup
All verbs	Request
All verbs	WP

Configure server-level settings by using Appcmd.exe

In IIS 8, you can configure settings in server-level configuration files or in Web.config files that are in a folder for a site, application, or virtual directory. Server-level configuration files are Machine.config, the root Web.config file, and ApplicationHost.config. These three files are available only to the Administrator account or to users who are members of the Administrators group on the web server. In addition, members of the Administrators group must open a command-shell window that uses their elevated administrator permissions to read and change settings in the server-level configuration files. For more information about starting Appcmd.exe in a command-shell window that uses elevated administrator permissions, see Start Appcmd.exe.

By default, ApplicationHost.config is the file from which Appcmd.exe reads configuration and to which Appcmd.exe writes changes. When you want to read changes from or write changes to Machine.config or the root Web.config file, include a commit parameter in your command. Specify MACHINE for the commit parameter when you want to affect the Machine.config file or specify WEBROOT when you want to affect the root Web.config file.

For example, to list the machineKey section in the root Web.config file, type the following command at the command prompt, and then press ENTER:

appcmd list config /section:machineKey /commit:WEBROOT

Configure settings for a site, application, virtual directory, or URL by using Appcmd.exe

In IIS 8, you can configure settings in server-level configuration files or in Web.config files for a site, application, or virtual directory on your web server. Users who view or change settings in Web.config files in site or application directories must have read and write access to files in those directories. Additionally, you must delegate features that you want to configure at the site, application, or virtual directory level in IIS 8. For more information about configuration files and delegating features, see Working With Configuration Files in IIS 7.0 and Delegate Web Site and Web Application Management.

Use Appcmd.exe to change configuration in a Web.config file

When you use Appcmd.exe to configure settings in a Web.config file for a specific site, application, or virtual directory, specify the path of the site, application, or virtual directory for which you want the configuration to apply. For example, to disable the default document feature for a web site named Contoso, type the following command at the command prompt, and then press ENTER:

appcmd set config "Contoso" /section:defaultDocument /enabled:false

In the previous example, the configuration changes are made in the Web.config file in the Contoso directory, and all the Contoso applications and virtual directories inherit the configuration from that Web.config file. However, if you want to enable default documents for a specific application in the Contoso site, you can use Appcmd.exe to provide the path of the application. For example, to enable default documents for an application named Gallery, type the following command at the command prompt, and then press ENTER:

appcmd set config "Contoso/Gallery" /section:defaultDocument /enabled:true

The command in the previous example enables default documents for the Gallery application in the Contoso site, and writes the configuration changes to the Web.config file in Gallery's directory.

Use Appcmd.exe to change configuration in a parent-level configuration file

The previous section explained how to use Appcmd.exe to configure features for a specific site, application, or virtual directory by writing changes to a Web.config file. You can also configure features for a specific site, an application, a virtual directory, or even a URL by using location tags in a parent configuration file.

When you want to configure settings for a site, application, or virtual directory but you want to store the settings in a parent configuration file, such as in ApplicationHost.config instead of in a Web.config file, use the Appcmd.exe commit parameter with your command. By using the examples in the previous section, you can now write the configuration changes to ApplicationHost.config instead of to the site and application Web.config files.

First, to disable default documents for the web site named Contoso, type the following command at the command prompt, and then press ENTER:

appcmd set config "Contoso" /section:defaultDocument /enabled:false /commit:APPHOST

The previous command disables default documents for the Contoso site, and writes the configuration settings with a location tag to ApplicationHost.config. The location tag specifies that the configuration applies to the Contoso site. The configuration section resembles the following example:

<location path="Contoso">
      <system.webServer>
            <defaultDocument enabled="false" />
      </system.webServer>
</location>

Second, to enable default documents for the application named Gallery, type the following command at the command prompt, and then press ENTER:

appcmd set config "Contoso/Gallery" /section:defaultDocument /enabled:true /commit:APPHOST

The previous command enables default documents for the Gallery application, and writes the configuration settings with a location tag to ApplicationHost.config. The location tag specifies that the configuration applies to the Gallery application. The configuration section looks like the following example:

<location path="Contoso/Gallery">
      <system.webServer>
            <defaultDocument enabled="true" />
      </system.webServer>
</location>