Getting Help
Because
Appcmd supports such a variety of objects and verbs, and each has a
different set of parameters, it provides a fairly extensive help system
to aid you as you navigate the usage of the tool.
You can get three levels of help from Appcmd:
-
Top-level help. Provides
a list of objects supported by Appcmd, as well as the general tool
parameters that you can use with any command. To obtain this help,
simply run Appcmd with no parameters or use the /? parameter, for example, Appcmd /?.
-
Object help. Provides a list of verbs supported on a specific object. To obtain this help, use the /? parameter following the object name, for example, Appcmd Site /?.
-
Verb help. Provides a list of supported parameters and examples for a specific verb of a specific object. To obtain this help, use the /? parameter following the verb and object names, for example, Appcmd List Site /?.
These three levels represent the typical
ways people use the Appcmd help system to learn how to perform a
particular command. First, you can display the list of the supported
objects by using the top-level help. The resulting output will include
the list of supported objects, as shown here.
General purpose IIS command line administration tool.
APPCMD (command) (object-type) <identifier> </parameter1:value1 ...>
Supported object types:
SITE Administration of virtual sites
APP Administration of applications
VDIR Administration of virtual directories
...
(To list commands supported by each object use /?,
e.g. 'appcmd.exe site /?')
General parameters:
/? Display context-sensitive help message.
/text<:value> Generate output in text format (default).
/text:* shows all object properties in detail view.
/text:<attribute> shows the value of the specified
attribute for each object.
/xml Generate output in XML format.
Use this to produce output that can be sent to another
command running in /in mode.
Use "!" to escape parameters that have same names as the general
parameters, like "/!debug:value" to set a config property named "debug".
In
addition, the top-level help shows the list of general tool parameters
that control the operation of the tool regardless of the command.
At this point, you can get more information about a specific object type by using the Appcmd Object /? syntax to display the list of supported verbs. For example, to get the list of supported verbs on the Site object, use the following.
Appcmd Site /?
The output will contain the following.
Administration of virtual sites
APPCMD (command) SITE <identifier> <-parameter1:value1 ...>
Supported commands:
list List virtual sites
set Configure virtual site
add Add new virtual site
delete Delete virtual site
start Start virtual site
stop Stop virtual site
(To get help for each command use /?, e.g. 'appcmd.exe add site /?'.)
At this point, the final step is to obtain the specific syntax of the required verb by using the Appcmd Verb Object /? syntax. For example, to get the specific syntax for the List Site command, use the following.
Appcmd List Site /?
This will have the following output.
List virtual sites
APPCMD list SITE <identifier> <-parameter1:value1 ...>
Lists the virtual sites on the machine. This command can be used to find a
specific site by using its identifier or url, or match zero or more sites
based on the specified site attributes.
Supported parameters:
identifier
Site name or url of the site to find
/site.name
Site name or url of the site to find (same as identifier)
/?
Display the dynamic site properties that can be used to find one
or more site objects
Examples:
appcmd list sites
List all sites on the machine.
appcmd list site "Default Web Site"
Find the site "Default Web Site".
appcmd list site http://localhost/app1
Find the site associated with the specified url.
appcmd list site /serverAutoStart:false
Find all sites that have the "serverAutoStart" configuration
property set to "false".
Note that the help output contains the list of supported parameters, including the identifier. The /? parameter listed here indicates that you can also use dynamic parameters exposed by each instance of the object. With the List Site
command, you can specify any of the configuration attributes in the Web
site definition as parameters to find all Web site instances that have
the specified values.
Note
To get the list of dynamic parameters, you can use the Set verb with an instance of the object specified with the identifier and then use the /? parameter to list the supported attributes. For example: Appcmd Set Site "Default Web Site" /?.
This is not ideal, but it does provide a quick way to look up dynamic
parameters you can use for each command that supports dynamic object
parameters.
The list of examples for each command is
valuable, because it showcases the common ways for using each command.
For example, for the Web site object, it shows how to list all sites,
list sites using their identifier (name), list sites that serve a
particular URL, or list sites by searching for a specific configuration
parameter value.
Note
Be sure to review examples in the verb help to get a quick feel for different ways of using the command.
Understanding Appcmd Output
The output of Appcmd typically contains a list of items. For commands that retrieve lists of object instances, such as the List
command, it is the list of object instances. For commands that perform
actions on object instances, it is a list of messages that indicate the
action that was performed.
For instance, for the List Site command, the output contains a list of Web site object instances. Here is an example.
SITE "Default Web Site" (id:1,bindings:http/*:80:,state:Started)
SITE "TestSite" (id:2,bindings:http/*:80:testsite,state:Started)
By default, Appcmd uses a friendly list
view that lists the object type, the identifier that can be used to
identify each of the instances in subsequent commands, and several
common attributes of each object instance. For the Site
object, it is the Web site id, a list of configured bindings, and the
state of the Web site (indicating whether it is started or stopped).
In fact, each Site
object instance contains more attributes than are shown in the friendly
list view. To display those parameters, you have several options:
-
Text view. In this view, all of the attributes of each object instance are displayed in a hierarchical text property/value tree.
-
Single parameter view. In this view, you can display the value of a particular attribute of each object instance.
-
Configuration view. In this view, the underlying configuration element for each object instance is shown as a configuration fragment.
The text view can be a quick way to show all
of the attributes of each object instance. To use the text view, you
need to use the /text:* general parameter. For example, following is a fragment of the output for the List Sites command when using the /text:* parameter.
SITE
SITE.NAME:"Default Web Site"
SITE.ID:"1"
bindings:"http/*:80:,https/*:443:
state:"Started"
[site]
name:"Default Web Site"
id:"1"
serverAutoStart:"true"
[bindings]
[binding]
protocol:"http"
bindingInformation:"*:80:"
[binding]
protocol:"https"
bindingInformation:"*:443:"
[limits]
maxBandwidth:"4294967295"
maxConnections:"4294967295"
connectionTimeout:"00:02:00"
As you can see, this output contains more information about each Web site instance than the default output.
Alternatively, if you are interested
in just the specific attribute of each object instance, you can use the
single parameter view by using the /text:ParameterName general parameter, where ParameterName is the attribute whose value you want to display. Here is the output of the List Sites command when using the /text:name parameter to show just the site names.
Default Web Site
TestSite
Finally, you can use the
configuration view to display the configuration element associated with
each object instance as a configuration fragment. You can do this by
using the /config general parameter to display all explicitly set configuration or by using /config:* to display all configuration. The Config object uses this format by default. Here is the output of the List Sites commands with the /config switch.
<site name="Default Web Site" id="1">
<bindings>
<binding protocol="http" bindingInformation="*:80:" />
<binding protocol="https" bindingInformation="*:443:" />
</bindings>
<limits />
<logFile />
<traceFailedRequestsLogging enabled="true" />
<applicationDefaults />
<virtualDirectoryDefaults />
<application path="/">
<virtualDirectoryDefaults />
<virtualDirectory path="/" physicalPath="C:\inetpub\wwwroot" />
</application>
</site>
You can also use the /xml
switch to output the results of Appcmd commands in XML. This switch can
be used to pipe the results from one Appcmd command to chain multiple
related commands together when using command pipelining.
The XML output mode can also be used to export
results of Appcmd commands to other software programs and perform bulk
operations.
In
addition to verb-specific parameters, Appcmd also supports general
parameters that affect the execution of all Appcmd commands. These
parameters are listed in Table 2.
Table 2. Appcmd General Parameters
|
Parameter |
Description |
|---|
|
/? |
Display context-sensitive help message. |
|
/text |
Generate the output in text format. This is the default. You can also specify /text:*
to show a detailed text view containing all attributes of each object
being displayed. Alternatively, you can also specify /text: attribute to display only the value of the specific attribute for each object. |
|
/xml |
Generate the output in XML format. You can use
this format to store or transport the output of the tool to another
program, and it is the basis for the command pipelining support. |
|
- or /in |
Perform the command on the dataset provided from
the standard input. Use this parameter to execute Appcmd commands on
sets of objects provided by the output of another command. |
|
/config |
Show the configuration associated with each displayed object. You can also use /config:* to display all configuration, including values that are inherited from the schema defaults. |
|
/metadata |
Show the configuration metadata when displaying configuration objects and using /text:*. This includes information about the type of each configuration attribute. |
|
/commit |
Controls for which the command commits
configuration. By default, the configuration is written to the same
configuration path where it applies, which by default favors delegated
configuration when setting configuration at the Web site, application,
or URL levels. However, using this parameter allows you to control this
independent of the configuration path to which the configuration is
being applied. You can specify a fixed configuration path, or apphost, machine, and webroot for the corresponding server-level configuration files. Alternatively, you can use the Site, App, and Parent values to commit to a segment of the current configuration path. |
|
/debug |
Display debug information about the
execution of each command, including the time taken to execute, the
parameters passed in, how many objects were returned, and any errors.
You can use this to debug or optimize Appcmd commands. |
If you need to pass a parameter to a
command that has the same name as a general parameter, you can escape it
with a ! sign. For example, if you need to set the commit configuration attribute on the fictional mysection configuration section, you can use the following syntax.
appcmd set config /section:mysection /!commit:somevalue
When using the List
verb on any Appcmd object, you can include parameters to filter the
returned results by the values of the specified attributes. For example,
if you are looking for all sites that have the serverAutoStart attribute set to false, you can use the following syntax.
appcmd list sites /serverAutoStart:false
However, filtering by exact values of object
attributes may be limiting in some scenarios. Often, you need the
ability to search for objects that fall into a range of possible values.
To support this, Appcmd enables the use of range operators to filter
for objects that satisfy an expression on each attribute, rather then a
fixed value.
For example, if we wanted to find all Web sites that have ids larger than 300, we could use the >= operator as follows.
appcmd list sites "/id:$>=300"
Note
Because the > and <
characters have special handling at the command line, be sure to
enclose the entire parameter by placing the ranged operator in quotation
marks.
You can specify the range operators for any supported attribute by using the $OPVAL syntax, where OP corresponds to the ranged operator, and VAL corresponds to the value for the operator. Table 3 shows the supported operators.
Table 3. Appcmd-Supported Operators
|
Operator |
Description |
|---|
|
> |
Greater than operator, for numeric attributes.
Matches all values of the attribute that are greater than the value
specified. For example, /id:$>10 matches 11 but not 9. |
|
>= |
Greater than or equal to operator, for numeric
attributes. Matches all values of the attribute that are greater than
or equal to the value specified. For example, /id:$>=10 matches 10 but not 9. |
|
< |
Less than operator, for numeric
attributes. Matches all values of the attribute that are less than the
value specified. For example, /id:$<10 matches 9 but not 10. |
|
<= |
Less than or equal to operator, for numeric
attributes. Matches all values of the attribute that are less than or
equal to the value specified. For example, /id:$<=10 matches 10 but not 11. |
|
= |
Wildcard match expression for string attributes. The wildcard expression can contain * and ? characters. For example, /name:$=*Site matches MySite and Default Web Site but not Site 1. |
|
<> |
The not operator. Matches all of the objects that do not have the exact specified value for the attribute. For example, /name:$<>MySite matches everything but MySite. This operator does not support wildcards. |
You
can use the ranged operators to find objects that satisfy one or more
ranged conditions on their attributes. For example, to find all sites
that are stopped and have the name Site N where N is a one-digit number, you can use the following syntax.
appcmd list sites /state:stopped "/name:$=Site ?"
Avoiding Common Appcmd Pitfalls
When using Appcmd, you should keep in mind a
few particulars of the command line to avoid unexpected behavior. Use
the following techniques to keep out of trouble:
-
Surround the identifier and command
parameters with quotation mark (") characters to make sure that the
command line correctly keeps all of the parameter content together,
especially if it contains spaces or special characters such as > or <. You should always do this when you are writing scripts or batch files that call Appcmd commands. For example: appcmd list sites "/id:$>10". This is a command line shell limitation, not a limitation of Appcmd.
-
Be sure to use the standard ASCII
characters for - and / parameter delimiters, and the double quotation
mark (") and single quotation mark (’) characters, instead of the
extended characters such as (") and (‘).
When commands are sent in e-mail or pasted into Microsoft Office
programs, these characters may change to their extended versions, which
are actually different characters and may not be processed correctly by
the command line shell or Appcmd. For this reason, err on the side of
using / to begin parameter names instead of the - character. For
example, use /parameter, not -parameter.
-
Watch out for parameters
ending with the \" characters, because the \"combination escapes the
"character instead of using it to end the parameter. To avoid this, use a
double \\. For example, "/physicalPath:c:\test\\".
