Comece a usar o AppCmd.exe

  • Artigo

por Mike Volodarsky

Visão geral

O AppCmd.exe é a única ferramenta de linha de comando para gerenciar o IIS 7 e superior. Ele expõe todas as principais funcionalidades de gerenciamento de servidor por meio de um conjunto de objetos de gerenciamento intuitivos que podem ser manipulados da linha de comando ou de scripts.

O AppCmd permite controlar facilmente o servidor sem usar uma ferramenta de administração gráfica e automatizar rapidamente as tarefas de gerenciamento do servidor sem escrever o código.

Algumas das coisas que você pode fazer com o AppCmd:

  • Criar e configurar sites, aplicativos, pools de aplicativos e diretórios virtuais
  • Iniciar e parar sites e reciclar pools de aplicativos
  • Listar processos de trabalho em execução e examinar as solicitações em execução no momento
  • Pesquisar, manipular, exportar e importar configuração do IIS e ASP.NET

O AppCmd também permite que os administradores do servidor criem tarefas de gerenciamento avançadas simplesmente combinando vários comandos AppCmd.exe mais simples ou reutilizando a saída da ferramenta dentro de outro programa.

Você também pode encontrar mais tópicos do AppCmd e aprender maneiras poderosas de gerenciar seu servidor a partir da linha de comando no meu blog, em https://mvolo.com/category/appcmd/.

Como usar o AppCmd.exe

A linha de comando AppCmd.exe é criada sobre um conjunto de objetos de gerenciamento de servidor de nível superior, como Site e Aplicativo. Esses objetos expõem métodos que podem ser usados para executar várias ações nesses objetos, e as instâncias de objeto expõem propriedades que podem ser inspecionadas e manipuladas.

Por exemplo, o objeto Site fornece métodos para listar, criar e excluir instâncias de site (esses são métodos padrão que estão presentes em quase todos os objetos), bem como parar e iniciar sites. Cada instância do site, por sua vez, conterá propriedades, como nome do site e ID do site, que podem ser inspecionadas, pesquisadas ou definidas. A saída de cada comando é sempre uma lista de instâncias de objeto.

Observação

O AppCmd.exe está localizado no diretório %systemroot%\system32\inetsrv\. Como ele não faz parte do PATH automaticamente, você precisará usar o caminho completo para o executável ao executar comandos como no %systemroot%\system32\inetsrv\AppCmd.exe list sites. Como alternativa, você poderá adicionar manualmente o diretório inetsrv ao caminho em seu computador para poder acessar o AppCmd.exe diretamente de qualquer local.

A ferramenta funciona executando um comando em um dos objetos de gerenciamento suportados, com parâmetros opcionais usados para personalizar ainda mais o comportamento do comando:

APPCMD (command) (object-type) <identifier> < /parameter1:value1 ... >*

Onde <COMMAND> é um dos comandos compatíveis com <OBJECT>. A maioria dos objetos oferece suporte a esse conjunto básico de comandos:

  • LIST Exibe os objetos no computador. Uma <ID> opcional pode especificar um objeto exclusivo para listar ou um ou mais parâmetros podem ser especificados para corresponder às propriedades do objeto.
  • ADD Cria um novo objeto com as propriedades de objeto especificadas a serem definidas durante a criação.
  • DELETE Exclui o objeto especificado pela <ID>.
  • SET Define parâmetros no objeto especificado pela <ID>.

Um objeto geralmente dará suporte a comandos adicionais, como START e STOP do objeto Site.

Por exemplo, o conjunto atual de objetos disponíveis por meio do AppCmd é (onde <OBJECT> é um dos objetos de gerenciamento suportados pela ferramenta):

Objeto Descrição
Site Administração de sites virtuais
Aplicativo Administração de aplicativos
VDir Administração de diretórios virtuais
Apppool Administração de pools de aplicativos
Config Administração de seções de configuração geral
Backup Gerenciamento de backups de configuração do servidor
WP Administração de processos de trabalho
Solicitação Exibição de solicitações HTTP ativas
Módulo Administração de módulos do servidor
Trace Gerenciamento de logs de rastreamento do servidor

Onde <ID> é o identificador específico do objeto para a instância do objeto que você deseja especificar para o comando. O formato do identificador é específico para cada tipo de objeto. Por exemplo, o objeto Site usa o nome do site, o objeto App usa o caminho do aplicativo e o objeto AppPool usa o nome do pool de aplicativos.

Onde [ /parameter:value ]* é zero ou mais parâmetros para o comando. Cada comando oferece suporte a um conjunto diferente de parâmetros, dependendo do objeto. Normalmente, os comandos que pesquisam objetos ou manipulam propriedades do objeto permitirão que qualquer uma das propriedades do objeto seja especificada como um parâmetro.

A ferramenta em si também suporta uma série de parâmetros que afetam a execução geral do comando e não são específicos para nenhum dos objetos. Eles estão listados na página de ajuda de nível superior disponível em "AppCmd.exe /?" e incluem parâmetros como /text, /config e /xml para controlar a saída da ferramenta e /commit para controlar o local das alterações de configuração.

Obtendo ajuda

O AppCmd fornece ajuda autodescritiva que pode ser usada como referência para todos os objetos e comandos com suporte. Há três tipos de ajuda disponíveis à medida que você se aprofunda na tarefa que gostaria de fazer.

Ajuda Geral

A tela de ajuda geral mostra os objetos suportados pela ferramenta, bem como os parâmetros da ferramenta aplicáveis de forma geral. Para exibir a ajuda geral:

APPCMD /?

As primeiras linhas de saída são:

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              

...

Ajuda do Objeto

A tela de ajuda do objeto mostra os comandos suportados por um objeto específico. Para exibir a ajuda do objeto:

APPCMD <OBJECT> /?

onde <OBJECT> é um dos tipos de objeto com suporte. Por exemplo, essa linha de comando exibirá ajuda para o objeto do site:

APPCMD site /?

Ajuda do Comando

A tela de ajuda do comando descreve a sintaxe de um comando e objeto específico, incluindo os parâmetros que ele oferece suporte e exemplos de tarefas comuns. Para exibir a ajuda do comando:

APPCMD <COMMAND> <OBJECT> /?

Por exemplo, essa linha de comando exibirá ajuda para o comando LIST do objeto App:

APPCMD list app /?

Localizar objetos com o comando LIST

O comando LIST é o comando mais versátil e é suportado por todos os objetos. O objetivo desse comando é localizar instâncias do objeto com base nos critérios especificados. A saída desse comando é uma lista de instâncias de objeto, que você pode inspecionar exibindo suas propriedades, exportar para recriação futura em outro computador ou usar junto com outro comando para executar ações nelas.

Listar todos os objetos

A maneira mais simples de usar o comando LIST é sem parâmetros, que simplesmente lista todas as instâncias conhecidas do objeto:

APPCMD list <OBJECT>

Por exemplo, para listar todos os sites na máquina, use esta linha de comando:

%systemroot%\system32\inetsrv\APPCMD list sites

A saída será semelhante a:

SITE "Default Web Site" (id:1,bindings:HTTP/*:80:,state:Started)
SITE "Site1" (id:2,bindings:http/*:81:,state:Started)
SITE "Site2" (id:3,bindings:http/*:82:,state:Stopped)

Por padrão, cada objeto é mostrado em uma única linha, especificando seu identificador específico do objeto (como "Site padrão") e uma ou mais propriedades importantes (como id, associações e estado).

Listar um objeto específico

O comando LIST pode ser usado para localizar uma instância de um objeto específico nomeado usando uma linha de comando neste formulário:

APPCMD list <OBJECT> <ID>

Por exemplo, use esta linha de comando para localizar o site com uma ID exclusiva de "Site padrão":

%systemroot%\system32\inetsrv\APPCMD list site "Default Web Site"

Listar objetos que atendem aos critérios de consulta

Para localizar todas as instâncias de objeto que correspondem a critérios particulares, especifique um ou mais parâmetros que indicam os valores de propriedade dos objetos a serem correspondidos. Por exemplo, use esta linha de comando para localizar todos os sites que estão parados:

%systemroot%\system32\inetsrv\APPCMD list sites /state:Stopped

Você pode especificar qualquer número de pares propriedade-valor, e a ferramenta garantirá que os objetos retornados satisfaçam todos os critérios especificados. Por exemplo, use esta linha de comando para localizar sites que estão parados e configurados para não iniciar automaticamente:

%systemroot%\system32\inetsrv\APPCMD list sites /serverAutoStart:false /state:Stopped

Manipular objetos com ADD, SET e DELETE

Além de LIST, a maioria dos objetos também oferece suporte aos comandos ADD, SET e DELETE.

Adicionar novos objetos

O comando ADD cria uma nova instância de um objeto. Por exemplo, esta linha de comando criará um novo Site:

%systemroot%\system32\inetsrv\APPCMD add site /name:MyNewSite /bindings:"http/*:81:" /physicalPath:"C:\MyNewSite"

Dependendo do objeto, alguns parâmetros serão necessários para definir as propriedades necessárias na nova instância, e outras propriedades podem ser opcionais. Um erro será retornado se um parâmetro necessário não for especificado.

A tela de ajuda do comando indica quais parâmetros são necessários. Por exemplo, use esta linha de comando para ver quais parâmetros são necessários para adicionar um Site:

%systemroot%\system32\inetsrv\APPCMD add site /?

Continue lendo para obter mais informações sobre como criar sites, aplicativos, diretórios virtuais e pools de aplicativos com o AppCmd.

Alterar objetos existentes

O comando SET define uma ou mais propriedades em uma instância de objeto especificada. Esse comando requer que o identificador específico do objeto seja especificado. Por exemplo, para alterar a propriedade id do "Site padrão", use esta linha de comando:

%systemroot%\system32\inetsrv\APPCMD set site "Default Web Site" /id:200

Use uma forma da sintaxe de ajuda do comando para ver quais propriedades podem ser definidas em um objeto específico. Por exemplo, para ver as propriedades suportadas pelo Site Padrão, use:

%systemroot%\system32\inetsrv\APPCMD set site "Default Web Site" /?

Excluindo objetos

O comando DELETE exclui uma instância de um objeto. Assim como SET, esse comando também requer que o identificador específico do objeto seja especificado. Por exemplo, use esta linha de comando para excluir o site chamado "MyNewSite":

%systemroot%\system32\inetsrv\APPCMD delete site "MyNewSite"

Gerenciando backups

O AppCmd permite criar e restaurar backups da configuração global do servidor. Você pode usar isso para se recuperar de alterações indesejadas na configuração do servidor e retornar ao estado do servidor em boas condições. É recomendável criar um backup antes de alterar a configuração do servidor ou instalar um componente que o altere. Cada backup contém a cópia do arquivo de configuração raiz ApplicationHost.config atual, bem como outro estado relacionado em todo o servidor, incluindo a configuração de FTP e a configuração da Ferramenta de Administração do IIS.

Para criar um backup, use o comando ADD do objeto Backup:

%systemroot%\system32\inetsrv\APPCMD add backup

BACKUP object "20060519T172530" added

Isso criou um backup com um nome gerado automaticamente que representa a data e a hora do backup.

Um nome específico para o backup pode ser especificado assim:

%systemroot%\system32\inetsrv\APPCMD add backup MyBackup

BACKUP object "MyBackup" added

Você pode exibir uma lista de backups disponíveis usando o comando LIST do objeto Backup:

%systemroot%\system32\inetsrv\APPCMD list backups

BACKUP "20060519T172530"

BACKUP "MyBackup"

Por fim, para restaurar um backup, use o comando RESTORE com o nome do backup:

%systemroot%\system32\inetsrv\APPCMD restore backup "MyBackup"

Restored configuration from backup "MyBackup"

A restauração de um backup interrompe o servidor e restaura a configuração global ao seu estado no momento em que o backup foi criado.

No Windows Server® 2008 e no Windows Vista SP1, o AppCmd também poderá trabalhar com backups de configuração periódicos feitos pelo serviço de histórico de configuração. Esses backups aparecerão na lista de backups do AppCmd e estarão disponíveis para restauração da mesma forma que os backups feitos manualmente por meio da ferramenta.

Para saber mais sobre como gerenciar backups de configuração com o AppCmd, confira http://mvolo.com/most-important-appcmd-commands-backing-up-and-restoring-iis7-configuration/.

Trabalhar com sites, aplicativos, diretórios virtuais e pools de aplicativos

Criar e gerenciar sites, aplicativos e diretórios virtuais são as tarefas mais comuns enfrentadas pelos administradores. O IIS 7 e superior usa uma hierarquia de independência mais rigorosa do que as versões anteriores que funciona assim:

  1. Site Um site recebe solicitações em pontos de extremidade de associação específicos definidos por endereços IP e cabeçalhos de host. Por exemplo, esse URL representa um site associado à porta 81: http://www.mysite.com:81.

    Um site contém um ou mais aplicativos.

  2. Aplicativo Um aplicativo é representado por seu caminho virtual dentro do namespace de URL de um site. Por exemplo, um aplicativo com um caminho virtual de "/app1" pode ser representado por este URL: http://www.mysite.com:81/app1.

    Um aplicativo pertence a um pool de aplicativos.

    Um aplicativo contém um ou mais diretórios virtuais.

  3. Diretório virtual Um diretório virtual é representado por seu caminho virtual dentro do namespace de URL de um aplicativo. Por exemplo, um diretório virtual com um caminho virtual de "/vdir1" pode ser representado por este URL: http://www.mysite.com:81/app1/vdir1.

    Um diretório virtual mapeia para um local físico no disco.

Essa hierarquia contrasta com o IIS 6.0, onde um site pode conter uma combinação de diretórios virtuais e aplicativos, e os aplicativos são apenas diretórios virtuais especialmente marcados.

Pool de aplicativos Um pool de aplicativos especifica um grupo de configurações dos processos de trabalho que executam o processamento de solicitações dos aplicativos nesse pool de aplicativos. Os pools de aplicativos não fazem parte da hierarquia site-app-vdir. Cada aplicativo especifica em qual pool de aplicativos será executado ou será executado no pool de aplicativos padrão. O pool de aplicativos define várias configurações de processo de trabalho, como a versão do CLR carregada por ele, o modo de integração do .NET, a conta sob a qual o processo de trabalho é executado e as configurações de reciclagem do processo.

Por padrão, o IIS 7 e superior são instalados com um site chamado "Site padrão" que escuta na porta 80 sem restrições de endereço IP nem cabeçalho de host. Este Site tem um aplicativo raiz e esse aplicativo tem um diretório virtual raiz. Há também um pool de aplicativos chamado "DefaultAppPool" que é usado por todos os novos aplicativos por padrão.

Esta linha de comando listará todos os Sites, incluindo o Site Padrão:

%systemroot%\system32\inetsrv\APPCMD list sites

SITE "Default Web Site" (id:1,bindings:HTTP/*:80:,state:Started)

Vamos examinar os aplicativos que pertencem ao Site Padrão, especificando a propriedade site.name ao listar os Aplicativos:

%systemroot%\system32\inetsrv\APPCMD list apps /site.name:"Default Web Site"

APP "Default Web Site/" (applicationPool:DefaultAppPool)

Um comando semelhante listará os diretórios virtuais dentro do aplicativo "Site padrão/" especificando a propriedade app.name ao listar Vdirs:

%systemroot%\system32\inetsrv\APPCMD list vdirs /app.name:"Default Web Site/"

VDIR "Default Web Site/" (physicalPath:C:\inetpub\wwwroot)

Por fim, examinaremos os pools de aplicativos:

%systemroot%\system32\inetsrv\APPCMD list apppools

APPPOOL "DefaultAppPool" (MgdVersion:v2.0,MgdMode:Integrated,state:Started)
APPPOOL "Classic .NET AppPool" (MgdVersion:v2.0,MgdMode:ISAPI,state:Started)

Criar sites, aplicativos, diretórios virtuais e pools de aplicativos

Agora, criaremos um novo site chamado "MySite", com o id de site de 2 que escuta na porta 81 de todos os endereços IP e cabeçalhos de host:

%systemroot%\system32\inetsrv\APPCMD add site /name:MySite /id:2 /bindings:http/*:81: /physicalPath:C:\inetpub\mysite

SITE object "MySite" added
APP object "MySite/" added
VDIR object "MySite/" added

Os parâmetros de nome devem ser especificados para criar um site. O parâmetro id é opcional e fará com que o AppCmd gere a próxima ID de site disponível para o novo site, se omitida. Também especificamos os parâmetros bindings e physicalPath, que são explicados abaixo. Você também pode especificar propriedades adicionais para definir seus valores.

A propriedade bindings usa o formato de protocol/bindingInformation, onde bindingInformation é específico do protocolo. Para HTTP, ele está no formato de IP:PORT:HOSTHEADER. Você pode especificar várias associações usando uma vírgula para separar cada definição.

Também especificamos uma propriedade physicalPath para o site. Embora um site em si não tenha um caminho físico, esse formulário curto é usado para criar convenientemente um site com um aplicativo raiz e um diretório virtual raiz mapeado para o caminho físico especificado.

Se você não especificar um caminho físico, o site será criado sem aplicativos; um aplicativo e um diretório virtual precisarão ser criados para ele explicitamente.

Vamos prosseguir e adicionar outro aplicativo ao site:

%systemroot%\system32\inetsrv\APPCMD add app /site.name:MySite /path:/app1 /physicalPath:C:\inetpub\mysite\app1

APP object "MySite/app1" added
VDIR object "MySite/app1/" added

Isso criou um novo aplicativo com caminho virtual "/app1" que pertence ao site que criamos acima, com um diretório virtual raiz apontando para C:\inetpub\mysite\app1. O parâmetro path obrigatório especifica o caminho virtual do novo aplicativo e o parâmetro site.name obrigatório especifica o site ao qual o aplicativo pertencerá. O parâmetro physicalPath opcional é um atalho, assim como no caso do Site, que cria um diretório virtual raiz junto com o aplicativo.

Se você não especificar o parâmetro physicalPath ou quiser adicionar outro diretório virtual ao aplicativo, use uma linha de comando como esta:

%systemroot%\system32\inetsrv\APPCMD add vdir /app.name:"MySite/app1" /path:/vdir1 /physicalPath:C:\inetpub\mysite\app1\vdir1

VDIR object "MySite/app1/vdir1" added

Isso criou um novo diretório virtual com o caminho virtual "/vdir1" que pertence ao aplicativo que criamos acima e apontando para C:\inetpub\mysite\app1\vdir1. O parâmetro path obrigatório especifica o caminho virtual do novo diretório virtual e o parâmetro app.name obrigatório especifica o aplicativo ao qual o diretório virtual pertencerá. O parâmetro physicalPath especifica o local físico do diretório virtual.

Por fim, criaremos um novo pool de aplicativos:

%systemroot%\system32\inetsrv\APPCMD add apppool /name:MyAppPool

APPPOOL object "MyAppPool" added

Isso criou um novo pool de aplicativos chamado "MyAppPool".

Para saber mais sobre sites, aplicativos e diretórios virtuais no IIS 7 e superior, e as opções que você tem ao criá-los com o AppCmd, confira Criar sites, aplicativos e diretórios virtuais do IIS7 e superior.

Configurar sites, aplicativos, diretórios virtuais e pools de aplicativos

Anteriormente, adicionamos um novo site completo com alguns aplicativos e diretórios virtuais. Agora, usaremos o AppCmd para modificar algumas de suas propriedades. Todos os objetos AppCmd oferecem suporte à mesma sintaxe padrão para definir propriedades:

APPCMD SET <OBJECT> <ID> [ /property:value ]*

Primeiro, exibiremos os aplicativos disponíveis no computador:

%systemroot%\system32\inetsrv\APPCMD list apps

APP "Default Web Site/" (applicationPool:DefaultAppPool)
APP "MySite/" (applicationPool:DefaultAppPool)
APP "MySite/app1" (applicationPool:DefaultAppPool)

Observe os dois aplicativos que criamos anteriormente no site "MySite". Ambos os aplicativos são definidos para usar o pool de aplicativos DefaultAppPool. Vamos alterar a propriedade applicationPool do aplicativo raiz "MySite/" para usar o novo pool de aplicativos que criamos anteriormente chamado "MyAppPool":

%systemroot%\system32\inetsrv\APPCMD set app "MySite/" /applicationPool:MyAppPool

APP object "MySite/" changed

Isso alterou o valor da propriedade applicationPool do aplicativo "MySite/" para o novo valor, movendo efetivamente o aplicativo para o novo pool de aplicativos.

O motivo pelo qual movemos o aplicativo para o novo pool de aplicativos é para que possamos alterar alguns dos parâmetros de runtime do processo de trabalho no qual esse aplicativo será executado. Para isso, alteraremos algumas das propriedades no pool de aplicativos "MyAppPool". Antes de alterar os valores da propriedade, muitas vezes é recomendável exibir primeiro as propriedades disponíveis e seus valores atuais. Podemos fazer isso listando nosso aplicativo em uma exibição detalhada:

%systemroot%\system32\inetsrv\APPCMD list apppool "MyAppPool" /text:*

APPPOOL
  APPPOOL.NAME: MyAppPool
  managedPipelineMode: Integrated
  managedRuntimeVersion: v2.0
  state: Started
  [add]
    name:"MyAppPool"
    queueLength:"1000"
    autoStart:"true"
    enable32BitAppOnWin64:"false"
    managedRuntimeVersion:"v2.0"
    managedPipelineMode:"Integrated"
    passAnonymousToken:"true"
    [processModel]
      identityType:"NetworkService"
      userName:""
      password:""

...
      pingingEnabled:"true"
...

Observe o número de propriedades no objeto do pool de aplicativos; a saída completa não é mostrada aqui.

Estamos interessados em alterar a propriedade managedRuntimeVersion para "v1.1" para executar nossos aplicativos neste pool de aplicativos com o ASP.NET v1.1. Aqui está a linha de comando para fazer isso:

%systemroot%\system32\inetsrv\APPCMD set apppool "MyAppPool" /managedRuntimeVersion:v1.1

APPPOOL object "MyAppPool" changed

Você pode ver na saída Lista acima que há várias propriedades disponíveis no objeto do pool de aplicativos, e algumas das propriedades são aninhadas em um subelemento de configuração. Por exemplo, as opções do processo são aninhadas abaixo do subelemento "processModel".

Se você quiser definir uma propriedade aninhada, aborde-a com a notação de caminho do elemento da seguinte maneira:

%systemroot%\system32\inetsrv\APPCMD set apppool "MyAppPool" /processModel.pingingEnabled:false

Outros elementos de configuração

Além de manipular as propriedades de configuração com os objetos AppCmd de nível superior, você pode definir as propriedades de configuração nas seções de configuração, incluindo as associadas aos objetos AppCmd de nível superior. Isso será abordado posteriormente na seção chamada "Trabalhar com a configuração".

Inspecionar o estado do servidor

O AppCmd fornece funcionalidade para inspecionar vários aspectos do estado de runtime do servidor, incluindo:

  • estado do site
  • estado do pool de aplicativos
  • processos de trabalho do servidor ativo
  • solicitações em execução no momento

Além disso, alguns objetos fornecem comandos que permitem controlar seu estado de runtime, como o comando STOP do objeto Site e o comando RECYCLE do objeto AppPool.

Inspecionar o estado do site e do pool de aplicativos

O estado dos sites e dos pools de aplicativos é relatado a partir da propriedade state de cada objeto. Ao listar sites ou pools de aplicativos, o estado é exibido na saída padrão. Por exemplo:

%systemroot%\system32\inetsrv\APPCMD list apppools DefaultAppPool

APPPOOL "DefaultAppPool" (MgdVersion:v2.0,MgdMode:Integrated,state:Started)

A propriedade state também pode ser usada para pesquisar sites ou pools de aplicativos que estão em um estado específico. Por exemplo, para localizar todos os pools de aplicativos iniciados:

%systemroot%\system32\inetsrv\APPCMD list apppools /state:started

APPPOOL "DefaultAppPool" (MgdVersion:v2.0,MgdMode:Integrated,state:Started)
APPPOOL "Classic .NET AppPool" (MgdVersion:v2.0,MgdMode:ISAPI,state:Started)

Inspecionar processos de trabalho em execução

Você pode usar o objeto WP (processo de trabalho) para listar processos de trabalho em execução:

%systemroot%\system32\inetsrv\APPCMD list wps

WP "3577" (apppool:DefaultAppPool)

Cada objeto WP tem uma propriedade apppool.name, que permite listar todos os processos de trabalho em execução de um pool de aplicativos específico:

%systemroot%\system32\inetsrv\APPCMD list wps /apppool.name:DefaultAppPool

WP "3577" (apppool:DefaultAppPool)

Inspecionar solicitações em execução no momento

O objeto Request permite inspecionar as solicitações em execução no servidor no momento:

%systemroot%\system32\inetsrv\APPCMD list requests

REQUEST "fb0000008000000e" (url:GET /wait.aspx?time=10000,time:4276 msec,client:localhost)

A lista pode ser restrita às solicitações de um determinado site, pool de aplicativos, processo de trabalho ou URL usando a propriedade apropriada para filtrar os resultados. Estes são alguns exemplos:

%systemroot%\system32\inetsrv\APPCMD list request /apppool.name:DefaultAppPool

%systemroot%\system32\inetsrv\
APPCMD list requests /wp.name:3567

%systemroot%\system32\inetsrv\APPCMD list requests /site.id:1

Trabalhar com a configuração

O IIS 7 e superior apresentam um sistema de configuração hierárquico baseado em XML semelhante ao sistema de configuração do ASP.NET que armazena a configuração do servidor em seções XML esquematizadas. A configuração pode ser localizada no arquivo ApplicationHost.config no nível do servidor ou colocada em arquivos de configuração Web.config distribuídos dentro da hierarquia do aplicativo.

O AppCmd permite a inspeção completa e a edição da hierarquia de configuração a partir da linha de comando por meio de seu objeto Config. Além disso, o AppCmd fornece outras funções úteis, como limpar a configuração, bloqueá-la e desbloqueá-la e pesquisá-la.

Exibir a configuração

O AppCmd trabalha com a configuração no nível das seções de configuração. Cada seção de configuração normalmente descreve um recurso de servidor e pode conter um ou mais subelementos e coleções.

A configuração pode ser definida para um namespace de URL arbitrário, como para um site, aplicativo ou URL. As definições de configuração definidas em um nível superior são herdadas por todos os níveis inferiores, a menos que sejam especificamente substituídas em níveis inferiores.

Para exibir a configuração efetiva para um determinado nível de URL, use o comando LIST do objeto Config da seguinte maneira:

%systemroot%\system32\inetsrv\APPCMD list config <URL> /section:SectionName

Onde <URL> é o caminho de configuração no qual a configuração efetiva deve ser lida, como "Site padrão/" ou "Web Site/app1/hello.html padrão". Se não for especificado, ele usará como padrão o nível do servidor.

Para saber mais sobre a hierarquia de configuração do IIS e como criar caminhos de configuração do IIS para usar com o AppCmd e outras ferramentas, confira Anatomia de um caminho de configuração do IIS7 e acima.

O parâmetro section especifica a seção de configuração que você gostaria de ler. Se não for especificado, todas as seções de configuração efetivas no nível do URL serão exibidas. Por exemplo, esta linha de comando exibe toda a configuração efetiva para o aplicativo raiz do site padrão:

%systemroot%\system32\inetsrv\APPCMD list config "Default Web Site/"

Para listar uma seção específica, use uma linha de comando como esta:

%systemroot%\system32\inetsrv\APPCMD list config "Default Web Site/" /section:asp

<system.webServer>
  <asp>
    <session />
    <comPlus />
    <cache />
    <limits />
</asp>
</system.webServer>

Por padrão, o AppCmd exibe apenas a configuração definida explicitamente. Se você quiser exibir a configuração efetiva, incluindo valores herdados ou padrão, especifique o parâmetro /config:*:

%systemroot%\system32\inetsrv\APPCMD list config "Default Web Site/" /section:asp /config:*

Para exibir uma lista de seções de configuração disponíveis, use esta linha de comando:

%systemroot%\system32\inetsrv\APPCMD list config /section:?

Editar as propriedades de configuração

No AppCmd, cada seção de configuração é exposta como uma instância de um objeto de configuração que expõe as propriedades que representam a seção de configuração subjacente. Use o comando SET do objeto Config para alterar essas propriedades. A sintaxe do é:

APPCMD set config <URL> /section:SectionName [ /property:value ]+

<URL> é opcional; especifica em qual caminho de configuração a alteração deve ser aplicada. Se omitido, as alterações serão aplicadas no nível do servidor e herdado por todos os URLs.

O parâmetro section é obrigatório, indica a seção que está sendo editada.

Por exemplo, para definir a propriedade appAllowClientDebug da seção ASP do URL http://localhost/app1:

%systemroot%\system32\inetsrv\APPCMD set config "http://localhost/app1" /section:asp /appAllowClientDebug:false

CONFIG object "asp" changed

Para definir as propriedades de configuração aninhadas em subelementos da seção de configuração, use esta notação de caminho do elemento:

%systemroot%\system32\inetsrv\APPCMD set config "http://localhost/app1" /section:asp /limits.requestQueueMax:4000

CONFIG object "asp" changed

Especifique mais de uma propriedade em uma única linha de comando para fazer várias edições na mesma seção de configuração.

Para exibir todas as propriedades que podem ser definidas em uma seção de configuração específica, use esta linha de comando:

%systemroot%\system32\inetsrv\APPCMD set config /section:asp /?

Observação

Observe que a seção asp está bloqueada por padrão, portanto, a execução desses comandos retornará um erro de violação de bloqueio. Você pode desbloquear essa seção primeiro, definir a configuração no nível do servidor omitindo o <URL>, ou confirmá-los na marca de local no nível do servidor usando /commit:apphost. Confira Controlar o local de configuração mais adiante no artigo.

Editar as coleções de configuração

O AppCmd também fornece suporte para editar coleções de configuração. Uma coleção de configuração pode conter vários elementos — por exemplo, a seção de configuração system.webServer/modules contém uma lista de elementos de configuração do módulo especificando os módulos executados pelo servidor.

Para definir uma propriedade em um elemento de coleção, especifique o elemento de coleção específico a ser editado usando uma expressão do indexador de coleção dentro da notação de caminho do elemento. A expressão do indexador de coleção usa valores de chave para identificar um elemento de coleção específico. O indexador tem o seguinte formato:

[key1='value1',key2='value2',...]

O número de chaves necessárias para identificar exclusivamente um elemento depende da coleção. A maioria das coleções requer apenas uma chave.

Por exemplo, para definir a propriedade type no elemento collection com a propriedade key name igual a "FormsAuthentication", use esta linha de comando:

%systemroot%\system32\inetsrv\APPCMD set config /section:system.webServer/modules /[name='FormsAuthentication'].type:System.Web.Security.FormsAuthenticationModule

Para adicionar um novo elemento de coleção, prefixe a notação do caminho do elemento com um sinal de adição, +. Dentro da expressão do indexador de coleção, forneça os valores para cada propriedade de chave. As propriedades adicionais não chave também podem ser incluídas na expressão do indexador de coleção. Por exemplo, isso adicionará um novo elemento de coleção de módulos:

%systemroot%\system32\inetsrv\APPCMD set config /section:system.webServer/modules /+[name='MyModule',type='MyType']

Para excluir um elemento de coleção, prefixe a notação de caminho do elemento com um sinal de subtração, -:

%systemroot%\system32\inetsrv\APPCMD set config /section:system.webServer/modules /-[name='MyModule']

Controlar o local de configuração

O sistema de configuração é hierárquico, permitindo que as definições de configuração sejam gravadas em vários níveis, desde o arquivo ApplicationHost.config no nível do servidor até os arquivos Web.config distribuídos que podem estar presentes nos níveis de site, aplicativo ou diretório virtual.

Quando a configuração é gravada em um nível específico, ela é herdada por todos os URLs nesse nível e inferior. Por exemplo, a configuração definida no arquivo de configuração Web.config na raiz do site é herdada por todas os URLs do site.

Por padrão, o AppCmd gravará a configuração no nível em que está sendo definida. Por exemplo, se você definir a configuração para o "Site padrão/", ele será gravado em um arquivo Web.config na raiz desse site.

No entanto, é possível gravar a configuração em um nível mais alto e aplicá-la somente a um subconjunto específico de URLs abaixo usando um constructo de local. Por exemplo, o aplicativo Web.config pode conter a configuração que é aplicada a apenas um único diretório dentro desse aplicativo. O AppCmd fornece esse recurso por meio de seu parâmetro commit.

O parâmetro de confirmação pode ser definido da seguinte forma:

  • (omitido) — padrão; gravar configuração no nível para o qual está definida
  • url — igual ao padrão; gravar configuração no nível para o qual está definida
  • site — gravar configuração no Web.config na raiz do site do URL para a qual está definido
  • app — gravar configuração no Web.config na raiz do aplicativo do URL para o qual está definido
  • apphost — gravar configuração no nível do servidor, no arquivo applicationHost.config
  • <PATH> — gravar configuração no caminho de configuração especificado

Por exemplo, essa linha de comando desativa a pesquisa no diretório de um aplicativo e grava essa configuração no arquivo Web.config da raiz do site:

%systemroot%\system32\inetsrv\APPCMD set config http://localhost/app1/ /section:directoryBrowse /enabled:false /commit:site

Para saber mais sobre os caminhos de configuração do IIS e controlar o local de configuração, confira Anatomia do caminho de configuração do IIS7 e superior.

Bloquear e desbloquear configuração

O sistema de configuração permite que as seções de configuração sejam bloqueadas em um nível específico, impedindo que suas propriedades sejam substituídas em níveis inferiores. Isso pode ser usado para impedir que os aplicativos alterem as configurações que o administrador do servidor deseja impor.

Por padrão, a maioria das seções de configuração do IIS está bloqueada no nível do servidor. Para configurar essas seções em níveis inferiores, elas precisam estar desbloqueadas. O AppCmd fornece o comando UNLOCK para esta finalidade:

%systemroot%\system32\inetsrv\APPCMD unlock config /section:asp

Use o comando LOCK para bloquear uma seção:

%systemroot%\system32\inetsrv\APPCMD lock config /section:asp

Observe que, se você bloquear uma seção de configuração, todos os aplicativos que já tiverem configurado essa seção em um nível inferior sofrerão um erro de violação de bloqueio quando tentarem acessar a seção de configuração.

Pesquisar configuração

O AppCmd pode pesquisar na hierarquia de configuração distribuída todos os locais que definem propriedades de configuração ou valores de propriedade específicos. O recurso de pesquisa de configuração pode ser usado para identificar locais onde um determinado recurso é habilitado ou para garantir a conformidade com um requisito de configuração específico.

Para pesquisar no servidor todos os locais que definem a configuração, você pode usar o comando SEARCH sem argumentos:

%systemroot%\system32\inetsrv\APPCMD search config

Para pesquisar todos os locais em um caminho de configuração específico, como todos os locais de configuração de um site específico, inclua o caminho na linha de comando:

%systemroot%\system32\inetsrv\APPCMD search config "Default Web Site/"

Para pesquisar locais que configuram uma seção de configuração específica:

%systemroot%\system32\inetsrv\APPCMD search config "Default Web Site/" /section:directoryBrowse

Para pesquisar locais que definem uma propriedade específica, inclua o nome da propriedade:

%systemroot%\system32\inetsrv\APPCMD search config "Default Web Site/" /section:directoryBrowse /enabled

E, finalmente, para pesquisar locais que definem uma propriedade para um valor específico:

%systemroot%\system32\inetsrv\APPCMD search config "Default Web Site/" /section:directoryBrowse /enabled:true

Trabalhar com a saída da ferramenta

Anteriormente, mencionamos que a saída do comando LIST é uma lista de instâncias de objeto. O AppCmd oferece diferentes modos de saída que permitem controlar o nível de detalhe exibido sobre cada objeto.

Saída padrão

Vamos pegar LIST Sites como exemplo. Por padrão, o AppCmd usa um formato de saída compacto:

%systemroot%\system32\inetsrv\APPCMD list sites

SITE "Default Web Site" (id:1,bindings:HTTP/*:80:,state:Started)
SITE "Site1" (id:2,bindings:http/*:81:,state:Started)
SITE "Site2" (id:3,bindings:http/*:82:,state:Stopped)

Nesse formato de saída, cada instância de objeto está em uma linha, especificando o tipo de objeto (SITE) e o identificador do objeto ("Site padrão"). Várias propriedades comuns ou importantes geralmente também são saídas (id, associação e estado do objeto Site).

Saída detalhada

A maioria dos objetos suporta significativamente mais propriedades do que as apresentadas na saída padrão. Para exibir todas as propriedades do objeto, especifique o parâmetro text:*. As propriedades de cada instância serão exibidas em um formato de árvore hierárquica:

APPCMD list site "Default Web Site" /text:*

SITE
  SITE.NAME: Default Web Site
  SITE.ID: 2
  bindings: http/*:80:
  state: Started
...

No exemplo acima, a saída foi abreviada — a saída real inclui muito mais propriedades.

Saída para trabalhar com outras ferramentas de linha de comando

O AppCmd fornece um modo de saída que exibe apenas uma propriedade específica de cada instância de objeto. Especifique o nome da propriedade a ser exibida com o parâmetro text:<PROPERTY>. Por exemplo, esse comando retornará todas as instâncias do diretório virtual disponíveis, exibindo apenas a propriedade physicalPath de cada uma:

%systemroot%\system32\inetsrv\APPCMD list vdirs /text:physicalPath

C:\inetpub\wwwroot
C:\inetpub\vdir1
D:\vdir2

É claro que você pode exibir qualquer uma das propriedades válidas do tipo de objeto que está sendo listado.

Às vezes, é desejável usar a saída do AppCmd com as ferramentas de linha de comando e os comandos shell existentes, como o comando FOR e FINDSTR.EXE. Essas ferramentas geralmente funcionam melhor quando cada item de dados de interesse está localizado em uma linha separada.

Como exemplo, imagine uma linha de comando que produz uma listagem de diretório de cada diretório virtual do IIS. A linha de comando precisa adquirir uma lista de caminhos físicos de cada um dos diretórios virtuais de interesse e, em seguida, executar um comando DIR em cada um desses caminhos usando o comando FOR para fazer um loop através deles:

FOR /F %f IN ('%systemroot%\system32\inetsrv\APPCMD list vdir /text:physicalPath') DO CALL DIR %f

Saída de configuração

Muitos dos objetos contêm dados de configuração que vêm diretamente das seções de configuração associadas. O objeto Config é o principal exemplo disso e serve como um wrapper direto sobre o sistema de configuração do IIS — cada instância de objeto retornada pelo objeto Config é uma seção de configuração. Outros objetos, como Site, também contêm informações de configuração como parte das propriedades do objeto.

Se desejar exibir as informações de configuração dos objetos retornados no formato XML bruto do sistema de configuração, use o parâmetro config. Por exemplo, para exibir as informações de configuração XML para o objeto de site, use uma linha de comando como esta:

%systemroot%\system32\inetsrv\APPCMD list site "Default Web Site" /config

<site name="Default Web Site" id="1">
  <bindings>
        <binding protocol="HTTP" bindingInformation="*:80:" />

...

Saída XML

A ferramenta também oferece suporte a seu próprio formato de saída XML, que gera conjuntos de resultados XML bem formado para os objetos retornados da execução do comando. Isso habilita alguns recursos interessantes que distinguem o AppCmd das ferramentas de linha de comando anteriores fornecidas pela equipe do IIS.

  • Criar tarefas de gerenciamento complexas. O principal objetivo dessa capacidade é permitir que os conjuntos de resultados gerados pelo AppCmd sejam inseridos em outro comando do AppCmd. Isso permite que você execute rapidamente as tarefas de gerenciamento complexas sem escrever o código do aplicativo.
  • Executar operações em lote com eficiência. A execução da ferramenta muitas vezes ao realizar um grande número de operações (por exemplo, a criação de 10.000 sites) pode ser lenta devido à sobrecarga de criação e inicialização do processo de cada operação. Em vez disso, um único comando de ferramenta pode ser executado sobre dados de entrada contidos em um conjunto de dados XML, reduzindo drasticamente o tempo de execução do processamento dos dados de entrada.
  • Exportar dados para outras ferramentas. O formato XML permite que os conjuntos de dados gerados pelo AppCmd sejam usados com outras ferramentas para processar, armazenar ou fornecer relatórios. Por exemplo, os dados do AppCmd podem ser usados com transformações XSLT em relatórios gerais de gerenciamento HTML, importados para o SQL Server 2005 para análise adicional ou carregados pelo ADO.NET para processamento programático.

Por exemplo, para gerar a saída da lista de sites no modo XML:

%systemroot%\system32\inetsrv\APPCMD list sites /xml

Para saber mais sobre o recurso de tubulação e como aproveitá-lo para um gerenciamento poderoso de linha de comando, confira http://mvolo.com/do-complex-iis-management-tasks-easily-with-appcmd-command-piping/.

Resumo

Nesta visão geral, apresentamos a você todos os diferentes comandos poderosos disponíveis usando o utilitário de linha de comando do IIS 7 e superior, AppCmd.exe.

Você também pode encontrar mais tópicos do AppCmd e aprender maneiras poderosas de gerenciar seu servidor a partir da linha de comando no meu blog, em http://mvolo.com/category/appcmd/.