ASP.NET Implantação da Web usando o Visual Studio: transformações de arquivo Web.config

por Tom Dykstra

Baixar Projeto Inicial

Esta série de tutoriais mostra como implantar (publicar) um aplicativo Web ASP.NET em Aplicativos Web do Serviço de Aplicativo do Azure ou em um provedor de hospedagem de terceiros, usando o Visual Studio 2012 ou o Visual Studio 2010. Para obter informações sobre a série, consulte o primeiro tutorial da série.

Visão geral

Este tutorial mostra como automatizar o processo de alteração do arquivo Web.config ao implantá-lo em diferentes ambientes de destino. A maioria dos aplicativos tem configurações no arquivo Web.config que devem ser diferentes quando o aplicativo é implantado. Automatizar o processo de fazer essas alterações evita que você tenha que fazê-las manualmente toda vez que implantar, o que seria tedioso e propenso a erros.

Lembrete: Se você receber uma mensagem de erro ou algo não funcionar durante o tutorial, verifique a página de solução de problemas.

Transformações Web.config versus parâmetros de Implantação da Web

Há duas maneiras de automatizar o processo de alteração das configurações do arquivo Web.config : transformações Web.config e parâmetros de Implantação da Web. Um arquivo de transformação Web.config contém marcação XML que especifica como alterar o arquivo Web.config quando ele é implantado. Você pode especificar alterações diferentes para configurações de compilação específicas e para perfis de publicação específicos. As configurações de compilação padrão são Depuração e Versão, e você pode criar configurações de compilação personalizadas. Um perfil de publicação normalmente corresponde a um ambiente de destino. Saiba mais sobre a publicação de perfis na Tutorial Implantando no IIS como um Ambiente de Teste.)

Os parâmetros de Implantação da Web podem ser usados para especificar muitos tipos diferentes de configurações que devem ser definidas durante a implantação, incluindo configurações encontradas em arquivos Web.config . Quando usados para especificar alterações de arquivo Web.config , os parâmetros de Implantação da Web são mais complexos de configurar, mas são úteis quando você não sabe o valor a ser definido até implantar. Por exemplo, em um ambiente corporativo, você pode criar um pacote de implantação e entregá-lo a uma pessoa do departamento de TI para instalar em produção, e essa pessoa precisa ser capaz de inserir cadeias de conexão ou senhas que você não conhece.

Para o cenário que esta série de tutoriais aborda, você sabe com antecedência tudo o que precisa ser feito no arquivo Web.config , portanto, não é necessário usar parâmetros de Implantação da Web. Você configurará algumas transformações que diferem dependendo da configuração de build usada e algumas que diferem dependendo do perfil de publicação usado.

Especificando as configurações do Web.config no Azure

Se as configurações de arquivo Web.config que você deseja alterar estiverem no elemento ou <appSettings> e se você estiver implantando em Aplicativos Web no Serviço de Aplicativo do Azure, terá outra opção para automatizar as alterações durante a <connectionStrings> implantação. Você pode inserir as configurações que deseja que entrem em vigor no Azure na guia Configurar da página do portal de gerenciamento do seu aplicativo Web (role para baixo até as seções de configurações do aplicativo e cadeias de conexão). Quando você implanta o projeto, o Azure aplica automaticamente as alterações. Para obter mais informações, consulte Sites do Windows Azure: como funcionam as cadeias de caracteres de aplicativo e as cadeias de conexão.

Arquivos de transformação padrão

No Gerenciador de Soluções, expanda Web.config para ver os arquivos de transformação Web.Debug.config e Web.Release.config criados por padrão para as duas configurações de build padrão.

Você pode criar arquivos de transformação para configurações de compilação personalizadas clicando com o botão direito do mouse no arquivo Web.config e escolhendo Adicionar Transformações de Configuração no menu de contexto. Para este tutorial, você não precisa fazer isso e a opção de menu está desabilitada, porque você não criou nenhuma configuração de build personalizada.

Posteriormente, você criará mais três arquivos de transformação, um para os perfis de publicação de teste, preparo e produção. Um exemplo típico de uma configuração que você manipularia em um arquivo de transformação de perfil de publicação porque depende do ambiente de destino é um ponto de extremidade WCF diferente para teste e produção. Você criará arquivos de transformação de perfil de publicação em tutoriais posteriores depois de criar os perfis de publicação que os acompanham.

Desativar o modo de depuração

Um exemplo de uma configuração que depende da configuração de build em vez do ambiente de destino é o debug atributo. Para um build de versão, você normalmente deseja que a depuração seja desabilitada, independentemente do ambiente em que você está implantando. Portanto, por padrão, os modelos de projeto do Visual Studio criam arquivos de transformação Web.Release.config com código que remove o debug atributo do compilation elemento. Aqui está o Web.Release.config padrão: além de algum código de transformação de exemplo comentado, ele inclui código no compilation elemento que remove o debug atributo:

<?xml version="1.0" encoding="utf-8"?>

<!-- For more information on using web.config transformation visit https://go.microsoft.com/fwlink/?LinkId=125889 -->

<configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">
  <!--
    In the example below, the "SetAttributes" transform will change the value of 
    "connectionString" to use "ReleaseSQLServer" only when the "Match" locator 
    finds an attribute "name" that has a value of "MyDB".
    
    <connectionStrings>
      <add name="MyDB" 
        connectionString="Data Source=ReleaseSQLServer;Initial Catalog=MyReleaseDB;Integrated Security=True" 
        xdt:Transform="SetAttributes" xdt:Locator="Match(name)"/>
    </connectionStrings>
  -->
  <system.web>
    <compilation xdt:Transform="RemoveAttributes(debug)" />
    <!--
      In the example below, the "Replace" transform will replace the entire 
      <customErrors> section of your web.config file.
      Note that because there is only one customErrors section under the 
      <system.web> node, there is no need to use the "xdt:Locator" attribute.
      
      <customErrors defaultRedirect="GenericError.htm"
        mode="RemoteOnly" xdt:Transform="Replace">
        <error statusCode="500" redirect="InternalError.htm"/>
      </customErrors>
    -->
  </system.web>
</configuration>

O xdt:Transform="RemoveAttributes(debug)" atributo especifica que você deseja que o debug atributo seja removido do system.web/compilation elemento no arquivo Web.config implantado. Isso será feito sempre que você implantar uma compilação de versão.

Limitar o acesso ao log de erros aos administradores

Se houver um erro durante a execução do aplicativo, o aplicativo exibirá uma página de erro genérica no lugar da página de erro gerada pelo sistema e usará o pacote Elmah NuGet para log e relatório de erros. O customErrors elemento no arquivo Web.config do aplicativo especifica a página de erro:

<customErrors mode="RemoteOnly" defaultRedirect="~/GenericErrorPage.aspx">
  <error statusCode="404" redirect="~/GenericErrorPage.aspx" />
</customErrors>

Para ver a página de erro, altere temporariamente o mode customErrors atributo do elemento de "RemoteOnly" para "On" e execute o aplicativo no Visual Studio. Cause um erro solicitando um URL inválido, como Studentsxxx.aspx. Em vez de uma página de erro "O recurso não pode ser encontrado" gerada pelo IIS, você verá a página GenericErrorPage.aspx .

Para ver o log de erros, substitua tudo na URL após o número da porta por elmah.axd (por exemplo, http://localhost:51130/elmah.axd) e pressione Enter:

Não se esqueça de definir o elemento de volta para o customErrors modo "RemoteOnly" quando terminar.

Em seu computador de desenvolvimento, é conveniente permitir acesso gratuito à página de log de erros, mas na produção isso seria um risco de segurança. Para o site de produção, você deseja adicionar uma regra de autorização que restrinja o acesso ao log de erros aos administradores e, para garantir que a restrição funcione, você também deseja em teste e preparo. Portanto, essa é outra alteração que você deseja implementar sempre que implantar um build de versão e, portanto, ela pertence ao arquivo Web.Release.config .

Abra Web.Release.config e adicione um novo location elemento imediatamente antes da marca de fechamento configuration , conforme mostrado aqui.

<configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">
  <!--
    In the example below, the "SetAttributes" transform will change the value of 
    "connectionString" to use "ReleaseSQLServer" only when the "Match" locator 
    finds an attribute "name" that has a value of "MyDB".
    
    <connectionStrings>
      <add name="MyDB" 
        connectionString="Data Source=ReleaseSQLServer;Initial Catalog=MyReleaseDB;Integrated Security=True" 
        xdt:Transform="SetAttributes" xdt:Locator="Match(name)"/>
    </connectionStrings>
  -->
  <system.web>
    <compilation xdt:Transform="RemoveAttributes(debug)" />
    <!--
      In the example below, the "Replace" transform will replace the entire 
      <customErrors> section of your web.config file.
      Note that because there is only one customErrors section under the 
      <system.web> node, there is no need to use the "xdt:Locator" attribute.
      
      <customErrors defaultRedirect="GenericError.htm"
        mode="RemoteOnly" xdt:Transform="Replace">
        <error statusCode="500" redirect="InternalError.htm"/>
      </customErrors>
    -->
  </system.web>
  <location path="elmah.axd" xdt:Transform="Insert">
    <system.web>
      <authorization>
        <allow roles="Administrator" />
        <deny users="*" />
      </authorization>
    </system.web>
  </location>
</configuration>

O Transform valor do atributo "Insert" faz com que esse location elemento seja adicionado como um irmão a qualquer elemento existente location no arquivo Web.config . (Já existe um location elemento que especifica regras de autorização para a página Atualizar Créditos .)

Agora você pode visualizar a transformação para ter certeza de que a codificou corretamente.

No Gerenciador de Soluções, clique com o botão direito do mouse em Web.Release.config e clique em Visualizar Transformação.

Uma página é aberta mostrando o arquivo Web.config de desenvolvimento à esquerda e a aparência do arquivo Web.config implantado à direita, com as alterações realçadas.

(Na versão prévia, você pode notar algumas alterações adicionais para as quais não escreveu transformações: elas normalmente envolvem a remoção de espaço em branco que não afeta a funcionalidade.)

Ao testar o site após a implantação, você também testará para verificar se a regra de autorização é efetiva.

Uma configuração que você manipulará em arquivos de transformação de perfil de publicação

Um cenário comum é ter configurações de arquivo Web.config que devem ser diferentes em cada ambiente em que você implanta. Por exemplo, um aplicativo que chama um serviço WCF pode precisar de um ponto de extremidade diferente em ambientes de teste e produção. O aplicativo da Contoso University também inclui uma configuração desse tipo. Essa configuração controla um indicador visível nas páginas de um site que informa em qual ambiente você está, como desenvolvimento, teste ou produção. O valor de configuração determina se o aplicativo acrescentará "(Dev)" ou "(Test)" ao título principal na página mestra Site.Master:

O indicador de ambiente é omitido quando o aplicativo está sendo executado em preparo ou produção.

As páginas da Web da Contoso University leem um valor definido no appSettings arquivo Web.config para determinar em qual ambiente o aplicativo está sendo executado:

<appSettings>
    <add key="Environment" value="Dev" />
</appSettings>

O valor deve ser "Teste" no ambiente de teste e "Prod" para preparo e produção.

O código a seguir em um arquivo de transformação implementará essa transformação:

<appSettings>
    <add key="Environment" value="Test" xdt:Transform="SetAttributes" xdt:Locator="Match(key)"/>
</appSettings>

O xdt:Transform valor de atributo "SetAttributes" indica que a finalidade dessa transformação é alterar os valores de atributo de um elemento existente no arquivo Web.config . O xdt:Locator valor do atributo "Match(key)" indica que o elemento a ser modificado é aquele cujo key atributo corresponde ao key atributo especificado aqui. O único outro atributo do add elemento é value, e é isso que será alterado no arquivo Web.config implantado. O código mostrado aqui faz com que o value Environment appSettings atributo do elemento seja definido como "Test" no arquivo Web.config implantado.

Essa transformação pertence aos arquivos de transformação do perfil de publicação, que você ainda não criou. Você criará e atualizará os arquivos de transformação que implementam essa alteração ao criar os perfis de publicação para os ambientes de teste, preparo e produção. Você fará isso nos tutoriais de implantação no IIS e implantação em produção .

Configurar cadeias de conexão

Embora o arquivo de transformação padrão contenha um exemplo que mostra como atualizar uma cadeia de conexão, na maioria dos casos você não precisa configurar transformações de cadeia de conexão, pois pode especificar cadeias de conexão no perfil de publicação. Você fará isso nos tutoriais de implantação no IIS e implantação em produção .

Resumo

Agora você fez o máximo que pôde com as transformações Web.config antes de criar os perfis de publicação e viu uma visualização do que estará no arquivo Web.config implantado.

No tutorial a seguir, você cuidará das tarefas de configuração de implantação que exigem a configuração de propriedades do projeto.

Mais informações

Para obter mais informações sobre os tópicos abordados neste tutorial, consulte Usando transformações Web.config para alterar as configurações no arquivo Web.config de destino ou no arquivo app.config durante a implantação no Mapa de Conteúdo de Implantação da Web para Visual Studio e ASP.NET.