Using Appcmd to Install and Manage Modules
The Appcmd command line tool also provides
top-level support for managing modules. To begin with, you can always
edit the IIS configuration via the Appcmd Config object to perform all
the tasks necessary to install and manage modules. However, the tool
also provides a module object, which directly supports common module
management tasks. This is why Windows Setup calls into Appcmd to install
modules and is the reason Appcmd is often the quickest way to install
and manage modules. Appcmd is also the only tool available for managing
modules on Windows Server 2008 Server Core installations, which do not
support IIS Manager.
Appcmd is located in the %windir%\System32\Inetsrv
directory, which is not present in the PATH variable by default, so you
need to use the full path to the tool to run it.
%windir%\system32\inetsrv\AppCmd
You must be logged in as an
administrator when using Appcmd. Also, be sure to execute Appcmd
commands from an elevated command line prompt (click Start, right-click
Command Prompt, and choose Run As Administrator). If you get lost while learning
Appcmd, be sure to check out the built-in command line help, which
provides parameters and examples.
AppCmd module /? - See all commands on the module object
AppCmd install module /? - See the usage help for the install module command
In the help output for the MODULE object, you can see that the tool supports the following commands:
-
List. Enables you to examine enabled modules at the server level or for a specific application.
-
Install. Enables you to install new native modules on the server.
-
Uninstall. Enables you to uninstall currently installed native modules on the server.
-
Add. Enables you to add a new module. You can also opt to enable an installed native module for a specific application.
-
Delete. Enables you to disable a managed module You can also opt to disable a native module, optionally for a specific application.
-
Set. Enables
you to edit specific entries in the modules configuration section for
the purposes of changing the name or preconditions of a module or
editing type information for managed modules.
In the next section, we’ll provide some examples of using these commands to manage modules with Appcmd.
Installing and Uninstalling Modules
The Install and Uninstall module
commands provide support for—you guessed it—installing and uninstalling
native modules on the server.
To install native modules, you can use the following syntax.
AppCmd Install Module /name:string /image:string [/precondition:string]
[/add:bool] [/lock:bool]
This command accepts the parameters shown in Table 7.
Table 7. Appcmd Install Module Parameters
|
Parameter |
Description |
|---|
|
name (required) |
Module name. |
|
image (required) |
The path to the module DLL. |
|
preCondition |
Optionally specifies the list of
valid load preconditions for the module. If specified, controls whether
the module is loaded by the IIS worker processes in particular
application pools. The default is empty. |
|
add |
Optionally specifies whether to also enable the module at the server level. The default is TRUE. |
|
lock |
Optionally specifies whether to also lock the
module entry so that it cannot be disabled by applications. This only
applies if the module is being enabled. The default is FALSE. |
The simplest case is installing a module by simply specifying its name and image path.
AppCmd install module /name:MyNativeModule /image:c:\modules\mymodule.dll
This installs and automatically enables the
new module at the server level so that it’s loaded by all IIS worker
processes and enabled for all applications by default. If you wanted to
install the module but enable it selectively for specific applications
only, you would include the /add:false parameter. Then, you could use
the Appcmd Add Module
command later to enable it for a specific application by using the
/app.name parameter. If, on the other hand, you wanted to install and
enable this module and prevent applications from disabling it, you would
include the /lock:true parameter for the install command. You could
also set the precondition parameter to one of the supported values to control which application pools the module is loaded and available in.
To uninstall a module, you can use the following syntax.
AppCmd Uninstall Module ModuleName
This command accepts the module’s name as the identifier.
Tip
The uninstall command uses the standard
Appcmd identifier pattern for specifying the module name, as opposed to
using the /name parameter that the Install command uses. This is done so
that all commands that work on specific existing instances of objects
can use the identifier format instead of using different parameter names
to identify objects.
Here is an example of how you can uninstall the module you installed earlier.
AppCmd uninstall module MyNativeModule
Note
This also automatically disables the module
at the server level, which makes sense because allowing this module to
be enabled would result in an incorrect configuration after the module
is uninstalled. However, if for some reason you wanted to uninstall a
module but leave it enabled (this would cause request errors on the
entire server if left unchanged), you can specify the /remove:false
parameter.
Enabling and Disabling Modules
You can use the Add Module and Delete Module commands to manage the modules enabled on the server or for a particular application. You can also use the Add Module
command to add new managed modules. These commands manipulate the
modules configuration section, which contains the entries for enabled
native modules and defines managed modules. Therefore, you can perform a
number of different tasks around module management.
One of the most common uses for the Add Module
command is to add new managed modules. Because native modules have to
be installed on the server first before they are enabled, the Install Module
command is more appropriate for installing and automatically enabling
them. You can add a new managed module at the server level or for any
particular application using the following syntax.
AppCmd Add Module /name:string [/type:string] [/precondition:string]
[/app.name:string] [/lockItem:bool]
This command supports the parameters shown in Table 8.
Table 8. Appcmd Add Module Parameters
|
name (required) |
Module name. |
|
type (required) |
The fully qualified .NET type of the module. If
the module is being added at the server level, the type must be in an
assembly registered with the machine’s Global Assembly Cache. If it’s
being added for a specific application, then it can also be deployed
with the application. |
|
preCondition |
Optionally specifies the list of
valid enablement preconditions for the module. If specified, controls
whether the module is enabled in specific application pools and for
specific requests. The default is empty. |
|
app.name |
Optionally specifies the application path for the modules to be added to. The default is empty, meaning the server level. |
|
lockItem |
Optionally specifies whether or not to lock the module entry against removal at lower configuration levels. |
For example, to add a new managed module at the server level, you can do the following.
AppCmd add module /name:MyManagedModule /type:MyModules.MyModule
This makes this module enabled by default
for all applications on the server. If you wanted to add it only to the
root application in the default Web site, you would also add the
/app.name:"Default Web Site/" parameter. You could also set the
preCondition parameter to one of the supported values to control for which application pools and requests the module is enabled.
You can also use the lockItem parameter just
like you can when creating new configuration collection entries to lock
the module entry, which prevents lower configuration levels from
removing the module configuration entry. You can leverage this when
adding new managed modules at the server level to prevent them from
being disabled at the application level.
Another common use of the Add Module
command is to enable a native module that is not currently enabled. For
example, if you installed a native module with the /add:false
parameter, resulting in it being installed but not enabled by default,
you can directly enable it.
AppCmd add module /name:MyNativeModule
You can use the /app.name parameter here to
specify the application where the module should be enabled. This only
works for native modules; that is, when re-enabling managed modules for a
specific application, you always have to specify the type because this
information is not available elsewhere like it is for native modules.
You can use the Delete Module
command to do the opposite—to disable a module that is currently
enabled. You can also use this command to disable native module or
managed modules at the server level, or for a specific application,
using the following syntax.
AppCmd Delete Module ModuleName [/app.name:string]
Tip
The delete command uses the standard
Appcmd identifier pattern for specifying the module name, as opposed to
using the /name parameter that the add command uses. This syntax exists
so that all commands that work on specific existing instances of
objects can use the identifier format instead of using different
parameter names to identify objects.
For example, to disable a module that is enabled at the server level, you can do the following.
AppCmd delete module MyModule
This works for both managed and native
modules, with a slight caveat: if you disable a native module, you can
re-enable it simply by using the Add Module /name:ModuleName
command. However, if you disable a managed module, you will need to
specify its full type to re-enable it. If you delete a managed module at
the level where it’s defined for the first time, you may lose the type
information in case you need to re-add it later.
Examining Enabled Modules
In addition to installing/uninstalling
and enabling/disabling modules, Appcmd supports examining the enabled
modules with the LIST command. This can prove valuable when diagnosing
module-related issues by enabling you to quickly determine which modules
are enabled for a specific application, or if a specific module is
enabled.
The List Module
command, much like the LIST commands for other Appcmd objects, enables
you to display all modules as well as query for modules that satisfy a
specific query. In the simplest use, it enables you to quickly list the
modules that are enabled at the server level.
AppCmd list modules
To see which modules are enabled for a specific application, use the /app.name:AppPath parameter to specify the application path for which the enabled modules should be displayed.
Note
Because applications can remove certain
modules or add new ones, their module set can often be different from
that of the server itself. Be sure to check the module list for the
application you’re interested in when you’re investigating problems with
that application.
You can also specify queries for one or more of the module attributes, including precondition and type,
to find modules that have that attribute. For example, to find all
managed modules that have the managedHandler precondition set, you can
use the following code.
AppCmd list modules "/type:$<>" "/precondition:$=*managedHandler*"
You can also look for specific modules by using the module name as the identifier.
AppCmd list module DefaultDocumentModule
