Configuração de parâmetros para a implantação de pacote da Web

  • Artigo

por Jason Lee

Este tópico descreve como definir valores de parâmetro, como nomes de aplicativos Web do IIS (Serviços de Informações da Internet), cadeias de conexão e pontos de extremidade de serviço, quando você implanta um pacote da Web em um servidor Web do IIS remoto.

Quando você cria um projeto de aplicativo Web, o processo de build e empacotamento gera três arquivos principais:

  • Um arquivo [nome do projeto].zip . Este é o pacote de implantação da Web para seu projeto de aplicativo Web. Esse pacote contém todos os assemblies, arquivos, scripts de banco de dados e recursos necessários para recriar seu aplicativo Web em um servidor Web IIS remoto.
  • Um arquivo [nome do projeto].deploy.cmd . Isso contém um conjunto de comandos de Implantação da Web (MSDeploy.exe) parametrizados que publicam seu pacote de implantação da Web em um servidor Web do IIS remoto.
  • Um arquivo [nome do projeto].SetParameters.xml . Isso fornece um conjunto de valores de parâmetro para o comando MSDeploy.exe. Você pode atualizar os valores nesse arquivo e passá-los para Implantação da Web como um parâmetro de linha de comando ao implantar seu pacote da Web.

Observação

Para obter mais informações sobre o processo de build e empacotamento, consulte Compilando e empacotando projetos de aplicativo Web.

O arquivo SetParameters.xml é gerado dinamicamente do arquivo de projeto do aplicativo Web e de todos os arquivos de configuração no projeto. Quando você compila e empacota seu projeto, o WPP (Web Publishing Pipeline) detecta automaticamente muitas das variáveis que provavelmente serão alteradas entre ambientes de implantação, como o aplicativo Web IIS de destino e quaisquer cadeias de conexão de banco de dados. Esses valores são automaticamente parametrizados no pacote de implantação da Web e adicionados ao arquivo SetParameters.xml . Por exemplo, se você adicionar uma cadeia de conexão ao arquivo web.config em seu projeto de aplicativo Web, o processo de build detectará essa alteração e adicionará uma entrada ao arquivo SetParameters.xml adequadamente.

Em muitos casos, essa parametrização automática será suficiente. No entanto, se os usuários precisarem variar outras configurações entre ambientes de implantação, como configurações de aplicativo ou URLs de ponto de extremidade de serviço, você precisará informar ao WPP para parametrizar esses valores no pacote de implantação e adicionar entradas correspondentes ao arquivo SetParameters.xml . As seções a seguir explicam como fazer isso.

Parametrização automática

Quando você compila e empacota um aplicativo Web, o WPP parametriza automaticamente estes itens:

  • O caminho e o nome do aplicativo Web do IIS de destino.
  • Todas as cadeias de conexão no arquivo web.config .
  • Cadeias de conexão para todos os bancos de dados adicionados à guia Pacote/Publicar SQL nas páginas de propriedades do projeto.

Por exemplo, se você compilasse e empacotasse a solução de exemplo do Contact Manager sem tocar no processo de parametrização de forma alguma, o WPP geraria esse arquivo ContactManager.Mvc.SetParameters.xml :

<parameters>
  <setParameter 
    name="IIS Web Application Name" 
    value="Default Web Site/ContactManager.Mvc_deploy" />  
  <setParameter 
    name="ApplicationServices-Web.config Connection String" 
    value="Data Source=DEVWORKSTATION\SQLEXPRESS;Initial Catalog=CMAppServices;
           Integrated Security=true;" />
</parameters>

Nesse caso:

  • O parâmetro Nome do Aplicativo Web do IIS é o caminho do IIS em que você deseja implantar o aplicativo Web. O valor padrão é obtido da página da Web Pacote/Publicação nas páginas de propriedades do projeto.
  • O parâmetroApplicationServices-Web.config Connection String foi gerado a partir de um elemento connectionStrings/add no arquivo web.config . Ele representa a cadeia de conexão que o aplicativo deve usar para entrar em contato com o banco de dados de associação. O valor fornecido aqui será substituído no arquivo web.config implantado. O valor padrão é obtido do arquivo deweb.config de pré-implantação.

O WPP também parametriza essas propriedades no pacote de implantação gerado. Você pode fornecer valores para essas propriedades ao instalar o pacote de implantação. Se você instalar o pacote manualmente por meio do Gerenciador do IIS, conforme descrito em Instalando manualmente pacotes Web, o assistente de instalação solicitará que você forneça valores para quaisquer parâmetros. Se você instalar o pacote remotamente usando o arquivo .deploy.cmd , conforme descrito em Implantando pacotes Web, a Implantação da Web procurará esse arquivo SetParameters.xml para fornecer os valores de parâmetro. Você pode editar os valores no arquivo SetParameters.xml manualmente ou personalizar o arquivo como parte de um processo automatizado de build e implantação. Esse processo é descrito mais detalhadamente mais adiante neste tópico.

Parametrização personalizada

Em cenários de implantação mais complexos, muitas vezes você desejará parametrizar propriedades adicionais antes de implantar seu projeto. Em termos gerais, você deve parametrizar todas as propriedades e configurações que variam entre ambientes de destino. Isso inclui:

  • Pontos de extremidade de serviço no arquivo web.config .
  • Configurações de aplicativo no arquivo web.config .
  • Quaisquer outras propriedades declarativas que você deseja solicitar que os usuários especifiquem.

A maneira mais fácil de parametrizar essas propriedades é adicionar um arquivo parameters.xml à pasta raiz do projeto de aplicativo Web. Por exemplo, na solução Contact Manager, o projeto ContactManager.Mvc inclui um arquivo parameters.xml na pasta raiz.

Na solução Gerenciador de Contatos, o projeto ContactManager.Mvc inclui um arquivo parameters.xml na pasta raiz.

Se você abrir esse arquivo, verá que ele contém uma única entrada de parâmetro . A entrada usa uma consulta XPath (Linguagem de Caminho XML) para localizar e parametrizar a URL do ponto de extremidade do serviço WCF (ContactService Windows Communication Foundation) no arquivo web.config .

<parameters>
  <parameter name="ContactService Service Endpoint Address"
             description="Specify the endpoint URL for the ContactService WCF 
                          service in the destination environment"
             defaultValue="http://localhost/ContactManagerService">
    <parameterEntry kind="XmlFile" scope="Web.config"
                    match="/configuration/system.serviceModel/client
                           /endpoint[@name='BasicHttpBinding_IContactService']
                           /@address" />
  </parameter>
</parameters>

Além de parametrizar a URL do ponto de extremidade no pacote de implantação, o WPP também adiciona uma entrada correspondente ao arquivo SetParameters.xml que é gerado junto com o pacote de implantação.

<parameters>
  ...  
  <setParameter 
    name="ContactService Service Endpoint Address" 
    value="http://localhost/ContactManagerService" />
  ...
</parameters>

Se você instalar o pacote de implantação manualmente, o Gerenciador do IIS solicitará o endereço do ponto de extremidade de serviço junto com as propriedades que foram parametrizadas automaticamente. Se você instalar o pacote de implantação executando o arquivo .deploy.cmd , poderá editar o arquivo SetParameters.xml para fornecer um valor para o endereço do ponto de extremidade de serviço junto com valores para as propriedades que foram parametrizadas automaticamente.

Para obter detalhes completos sobre como criar um arquivo deparameters.xml , consulte Como usar parâmetros para definir configurações de implantação quando um pacote é instalado. O procedimento chamado Para usar parâmetros de implantação para Web.config configurações de arquivo fornece instruções passo a passo.

Modificando o arquivo de SetParameters.xml

Se você planeja implantar o pacote de aplicativos Web manualmente, executando o arquivo .deploy.cmd ou executando MSDeploy.exe na linha de comando, não há nada que impeça a edição manual do arquivo SetParameters.xml antes da implantação. No entanto, se você estiver trabalhando em uma solução de escala empresarial, talvez seja necessário implantar um pacote de aplicativos Web como parte de um processo de compilação e implantação maiores e automatizados. Nesse cenário, você precisa do Microsoft Build Engine (MSBuild) para modificar o arquivo deSetParameters.xml para você. Você pode fazer isso usando a tarefa XmlPoke do MSBuild.

A solução de exemplo do Gerenciador de Contatos ilustra esse processo. Os exemplos de código a seguir foram editados para mostrar apenas os detalhes relevantes para este exemplo.

Observação

Para obter uma visão geral mais ampla do modelo de arquivo de projeto na solução de exemplo e uma introdução aos arquivos de projeto personalizados em geral, consulte Noções básicas sobre o arquivo de projeto e Noções básicas sobre o processo de build.

Primeiro, os valores de parâmetro de interesse são definidos como propriedades no arquivo de projeto específico do ambiente (por exemplo, Env-Dev.proj).

<PropertyGroup> 
  <ContactManagerIisPath Condition=" '$(ContactManagerIisPath)'=='' ">
    DemoSite/ContactManager
  </ContactManagerIisPath>
  <ContactManagerTargetUrl Condition =" '$(ContactManagerTargetUrl)'=='' ">
    http://localhost:85/ContactManagerService/ContactService.svc
  </ContactManagerTargetUrl>
  <MembershipConnectionString Condition=" '$(MembershipConnectionString)'=='' ">
    Data Source=TESTDB1;Integrated Security=true;Initial Catalog=CMAppServices
  </MembershipConnectionString>  
</PropertyGroup>

Observação

Para obter diretrizes sobre como personalizar os arquivos de projeto específicos do ambiente para seus próprios ambientes de servidor, consulte Configurar propriedades de implantação para um ambiente de destino.

Em seguida, o arquivo Publish.proj importa essas propriedades. Como cada arquivo SetParameters.xml está associado a um arquivo .deploy.cmd e, por fim, queremos que o arquivo de projeto invoque cada arquivo .deploy.cmd , o arquivo de projeto cria um item do MSBuild para cada arquivo .deploy.cmd e define as propriedades de interesse como metadados de item.

<ItemGroup>
  <PublishPackages Include="$(_ContactManagerDest)ContactManager.Mvc.deploy.cmd"> 
    <ParametersXml>
      $(_ContactManagerDest)ContactManager.Mvc.SetParameters.xml
    </ParametersXml>
    <IisWebAppName>
      $(ContactManagerIisPath)
    </IisWebAppName> 
    <MembershipDBConnectionName>
      ApplicationServices-Web.config Connection String
    </MembershipDBConnectionName>
    <MembershipDBConnectionString>
      $(MembershipConnectionString.Replace(";","%3b"))
    </MembershipDBConnectionString>
    <ServiceEndpointParamName>
      ContactService Service Endpoint Address
    </ServiceEndpointParamName>
    <ServiceEndpointValue>
      $(ContactManagerTargetUrl)
    </ServiceEndpointValue>
  </PublishPackages>
  ...
</ItemGroup>

Nesse caso:

  • O valor de metadados ParametersXml indica o local do arquivo SetParameters.xml .
  • O valor IisWebAppName é o caminho do IIS no qual você deseja implantar o aplicativo Web.
  • O valor MembershipDBConnectionString é a cadeia de conexão do banco de dados de associação e o valor MembershipDBConnectionNameé o atributo name do parâmetro correspondente no arquivo SetParameters.xml .
  • O valor ServiceEndpointValue é o endereço do ponto de extremidade para o serviço WCF no servidor de destino e o valor ServiceEndpointParamName é o atributo name do parâmetro correspondente no arquivo SetParameters.xml .

Por fim, no arquivo Publish.proj , o destino PublishWebPackages usa a tarefa XmlPoke para modificar esses valores no arquivo SetParameters.xml .

<Target Name="PublishWebPackages" Outputs="%(PublishPackages.Identity)">
  <XmlPoke 
    XmlInputPath="%(PublishPackages.ParametersXml)"
    Query="//parameters/setParameter[@name='%(PublishPackages.ConnectionName)']
           /@value"
    Value="%(PublishPackages.ConnectionString)"
    Condition =" '%(PublishPackages.ConnectionName)'!=''" 
  />
  <XmlPoke 
    XmlInputPath="%(PublishPackages.ParametersXml)"
    Query="//parameters/setParameter
           [@name='%(PublishPackages.MembershipDBConnectionName)']/@value"
    Value='%(PublishPackages.MembershipDBConnectionString)'
    Condition =" '%(PublishPackages.MembershipDBConnectionName)'!=''" 
  />
  <XmlPoke 
    XmlInputPath="%(PublishPackages.ParametersXml)"
    Query="//parameters/setParameter[@name='IIS Web Application Name']/@value"
    Value="%(PublishPackages.IisWebAppName)"
    Condition =" '%(PublishPackages.IisWebAppName)'!=''" 
  />
  <XmlPoke 
    XmlInputPath="%(PublishPackages.ParametersXml)"
    Query="//parameters/setParameter
           [@name='%(PublishPackages.ServiceEndpointParamName)']/@value"
    Value="%(PublishPackages.ServiceEndpointValue)"
    Condition =" '%(PublishPackages.ServiceEndpointParamName)'!=''" 
  /> 
  <!--Execute the .deploy.cmd file--> 
  ...
</Target>

Você observará que cada tarefa XmlPoke especifica quatro valores de atributo:

  • O atributo XmlInputPath informa à tarefa onde encontrar o arquivo que você deseja modificar.
  • O atributo Query é uma consulta XPath que identifica o nó XML que você deseja alterar.
  • O atributo Value é o novo valor que você deseja inserir no nó XML selecionado.
  • O atributo Condição são os critérios nos quais a tarefa deve ser executada ou não. Nesses casos, a condição garante que você não tente inserir um valor nulo ou vazio no arquivo SetParameters.xml .

Conclusão

Este tópico descreveu a função do arquivo SetParameters.xml e explicou como ele é gerado quando você cria um projeto de aplicativo Web. Ele explicou como você pode parametrizar configurações adicionais adicionando um arquivo parameters.xml ao seu projeto. Ele também descreveu como você pode modificar o arquivo SetParameters.xml como parte de um processo de build maior e automatizado, usando a tarefa XmlPoke em seus arquivos de projeto.

O próximo tópico, Implantando pacotes da Web, descreve como você pode implantar um pacote da Web executando o arquivo .deploy.cmd ou usando MSDeploy.exe comandos diretamente. Em ambos os casos, você pode especificar o arquivo SetParameters.xml como um parâmetro de implantação.

Leitura Adicional

Para obter informações sobre como criar pacotes Web, consulte Compilando e empacotando projetos de aplicativo Web. Para obter diretrizes sobre como realmente implantar um pacote da Web, consulte Implantando pacotes Da Web. Para obter um passo a passo sobre como criar um arquivo deparameters.xml , consulte Como usar parâmetros para definir configurações de implantação quando um pacote é instalado.

Para obter informações mais gerais sobre parametrização na Implantação da Web, consulte Parametrização de implantação da Web em ação (postagem no blog).

AnteriorAvançar