Most Appcmd objects support the basic set of verbs: List, Add, Set, and Delete.
These verbs operate in a fairly consistent way across objects, which
makes Appcmd easy to use after you get a feel for how these verbs work.
Using the List Command to List and Find Objects
The List
verb is one of the most useful verbs, and Appcmd provides it for all of
its object types. It is responsible for listing all of the available
instances of each object type, optionally enabling you to find a
specific instance of the object, and for searching for one or more
instances of the object by issuing queries involving one or more
attributes.
You can use the List verb to list all object instances of a specific object type by using the following Appcmd syntax:
appcmd list Object
where Object is the object whose instances
you wish to list. For example, to list all of the Web sites configured
on your server, use this.
appcmd list sites
You can also specify one or more parameters so
that you can restrict the list to only the Web sites that have the
specified attributes. The list of attributes available for this
operation is based on the Web site’s configuration definition and also
includes any of the attributes Appcmd generated for each Site object (such as the State attribute).
For example, if you want to look for any sites that have been stopped, type the following command.
appcmd list sites /state:Stopped
This command output will only return the
sites that are in a stopped state. You can specify as many parameters as
you want in the command. For instance, if you want to query sites that
do not automatically start when the server starts but are currently
running, you can issue the following command.
appcmd list sites /serverAutoStart:false /state:Started
In addition to specifying exact values for
attributes when querying for objects, you can use expressions to
broaden your query by using the Appcmd range operators. For example, you
can find all Web sites with ids larger than 300 by doing the following.
appcmd list sites "/id:$>300"
The range operator support includes not
equal to, greater than, greater than or equal to, less than, less than
or equal to, and a wildcard matching expression for string value types.
Finally, you can always find a unique Web site
instance by using its unique identifier, which is the site name for Web
sites. When listing objects, the identifier is displayed for each object
instance to make it easier to use later for referencing this object.
For example, to locate the Web site with the name Default Web Site, you
can use the following syntax.
appcmd list site "Default Web Site"
Additionally, the Site
object supports the use of a URL as the identifier, in which case the
tool will automatically resolve the URL to the Web site by using the
binding information for each Web site. This also works when listing the App and Vdir objects. For example, to list the Web site configured to serve the http://localhost/test.html URL, you can use the following syntax.
appcmd list site "http://localhost/test.html"
Keep in mind that the List
verb works for all object types. In addition to displaying Web sites,
you can list application pools, applications, virtual directories,
worker processes, and active HTTP requests. Try the List verb against all the supported object types.
Using the Add Verb to Create Objects
Many of the Appcmd objects support the
ability to create new object instances. For example, you can create new
Web sites, applications, virtual directories, and application pools. As
you might guess, you’ll use the Add verb to perform this task. The Add verb typically has the following syntax:
appcmd add Object [/parameter:value]*
Where Object is the object whose instance you are creating. The Add
verb for each object requires a certain set of parameters to be
specified to be used during the creation of the object instance. In
addition, you can typically specify any additional parameters that are
available for the Set verb when using the Add
verb to have those attributes set immediately after object creation.
You can get the list of required parameters that must be specified in
the verb help for the Add command. For example, to learn how to add a site, you can issue the following command.
appcmd add site /?
The output of our command line help request shows that you can add a site by providing the name, bindings, and physicalPath parameters. Here is an example of adding a Web site by using the Add Site command.
appcmd add site /name:MyWebSite /bindings:"http/*:81:"
/physicalPath:"c:\inetpub\wwwroot"
Note
The Add command output typically shows the objects the command created. In the previous example, the Add Site command creates a new Web site, root application, and root virtual directory.
Note
Unlike the Set and Delete commands, the Add command does not accept an identifier. This is because the Add
command doesn’t use the identifier to look up an existing object—it
creates a new object and requires the underlying parameters that may
comprise the identifier for later lookups to be provided to create the
object. For example, when using the Add Site command, you must provide the /name parameter instead of specifying the name as the identifier.
Using the Set Verb to Change Existing Objects
In addition to creating new objects by using the Add verb, you can also set configuration attributes on existing objects with the Set verb by using the following syntax:
appcmd set Object identifier [/parameter:value ...]
Where Object is the object whose instances you would like to modify The Set
verb requires the identifier to uniquely identify the object instance
being modified. To ensure correctness, the exact identifier must be
used, for example, use the site name instead of a URL for the Site object.
Note
Unlike the Add verb, you do not identify the desired object instance by specifying object-specific parameters, such as /name for the Site object. Instead, you must use the identifier to uniquely identify the object instance.
To find out what attributes you can set by specifying them as parameters for the Set verb, you can use the verb help. For example, to find out which parameters you can use with the Set Site command, use the following.
appcmd set site /?
If the displayed parameter list includes "/?",
this means that you can set configuration parameters that are not
listed in the help screen. This is the case for virtually all objects
Appcmd provides, because most have associated configuration information
that you can modify. To find out which configuration attributes you can
use with the Set verb, you have to inspect an existing object’s attributes using the List verb with a detailed text view or by using the /? switch with the Set verb. For example, to see the object properties you can set for each Site object, you can use the following syntax.
appcmd set site "Default Web Site" /?
Note
You need to specify an existing object instance with the Set verb when using the /? switch to list the supported parameters. Otherwise, you will get the default verb help screen.
The output of this command is a message that lists all parameters that can be used with the Set verb (as well as the List verb when querying) for the object. For example, here is a fragment of the output of the previous command.
-name
-id
-serverAutoStart
-bindings.[protocol='string',bindingInformation='string'].protocol
-bindings.[protocol='string',bindingInformation='string'].bindingInformation
-limits.maxBandwidth
-limits.maxConnections
...
Using the Delete Verb to Remove Objects
No configuration utility would be complete
without providing you with the ability to remove data. Appcmd provides
an obvious syntax for removing configuration by deleting objects with
the Delete verb.
appcmd delete Object identifier
Similar to the Set verb, the Delete
verb requires the identifier to uniquely identify the object instance
being modified. To ensure correctness, the exact identifier must be
used, for example, use the site name instead of a URL for the Site object.
Note
Unlike the Add verb, you do not identify the desired object instance by specifying object-specific parameters, such as /name for the Site object. Instead, you must use the identifier to uniquely identify the object instance.
For example, you can delete a Web site by using the Delete Site command as follows.
appcmd delete site "MyNewWebSite"
Caution
Deleting a Web site deletes all of the contained application and virtual directory definitions. It does not delete the content.
