ASP.NET веб-развертывание с помощью Visual Studio: преобразования файлов web.config

Том Дайкстра

Скачивание начального проекта

В этой серии учебников показано, как развернуть (опубликовать) веб-приложение ASP.NET в Azure App Service Web Apps или у стороннего поставщика услуг хостинга с помощью Visual Studio 2012 или Visual Studio 2010. Сведения о серии смотрите в первом руководстве из этой серии.

Обзор

В этом руководстве показано, как автоматизировать процесс изменения файла web.config при его развертывании в разных целевых средах. Большинство приложений имеют параметры в файле web.config , который должен отличаться при развертывании приложения. Автоматизация процесса внесения этих изменений позволяет избежать необходимости выполнять их вручную каждый раз при развертывании, что было бы утомительно и подвержено ошибкам.

Напоминание: Если вы получите сообщение об ошибке или что-то не работает, когда вы проходите руководство, обязательно проверьте страницу устранения неполадок.

Преобразования Web.config против параметров Web Deploy

Существует два способа автоматизации процесса изменения параметров файла Web.config : преобразования web.config и параметры веб-развертывания. Файл преобразования Web.config содержит XML-разметку, указывающую, как изменить файл web.config при его развертывании. Можно указать различные изменения для определенных конфигураций сборки и для определенных профилей публикации. Конфигурации сборки по умолчанию — отладка и выпуск, и вы можете создавать пользовательские конфигурации сборки. Профиль публикации обычно соответствует целевой среде. (Дополнительные сведения о профилях публикации см. в разделе Развертывание в IIS в качестве тестовой среды .)

Параметры веб-развертывания можно использовать для указания различных типов параметров, которые должны быть настроены во время развертывания, включая параметры, найденные в файлах web.config . Если используется для указания изменений файла конфигурации Web.config, настройка параметров Web Deploy более сложна, но они полезны, если вы не знаете значение, которое нужно задать, пока не будет произведено развертывание. Например, в корпоративной среде можно создать пакет развертывания и передать его сотруднику в ИТ-отдел для установки в продакшн, и этот сотрудник должен иметь возможность вводить строки подключения или пароли, которые неизвестны.

Для сценария, который охватывает эта серия руководств, вы заранее знаете все, что необходимо сделать с файлом Web.config, поэтому вам не нужно использовать параметры Web Deploy. Вы настроите некоторые преобразования, которые отличаются в зависимости от используемой конфигурации сборки, а некоторые отличаются в зависимости от используемого профиля публикации.

Указание параметров конфигурации Web.config в Azure

Если параметры файла конфигурации Web.config, которые вы хотите изменить, находятся в <connectionStrings> элементе или <appSettings> элементе, а если вы развертываете веб-приложения в службе приложение Azure, у вас есть еще один вариант для автоматизации изменений во время развертывания. Вы можете задать параметры, которые должны применяться в Azure, на вкладке «Настройка» страницы портала управления для вашего веб-приложения (прокрутите вниз до разделов "настройки приложения" и "строки подключения"). При развертывании проекта Azure автоматически применяет изменения. Дополнительные сведения см. в разделе Windows Azure Web Sites: как работают строки приложения и строки подключения.

Файлы преобразования по умолчанию

В Обозревателе решений разверните Web.config, чтобы просмотреть файлы преобразования Web.Debug.config и Web.Release.config, созданные по умолчанию для двух конфигураций сборки.

Вы можете создать файлы преобразования для пользовательских конфигураций сборки, щелкнув правой кнопкой мыши файл Web.config и выбрав в контекстном меню Добавить преобразования конфигурации. Для этого руководства вам не нужно это сделать, и параметр меню отключен, так как вы не создали пользовательские конфигурации сборки.

Позже вы создадите еще три файла преобразования, по одному для тестовых, промежуточных и рабочих профилей публикации. Типичный пример параметра, который будет обрабатываться в файле преобразования профиля публикации, так как он зависит от конечной среды — это конечная точка WCF, которая отличается от тестовой и рабочей среды. Вы создадите файлы преобразования профилей публикации в последующих руководствах после того, как создадите соответствующие профили публикации.

Отключение режима отладки

Пример параметра, который зависит от конфигурации сборки, а не целевой среды, является атрибутом debug . Для релизной сборки обычно требуется отключить отладку независимо от среды развертывания. Поэтому по умолчанию шаблоны проектов Visual Studio создают файлы преобразования Web.Release.config с кодом, который удаляет debug атрибут из compilation элемента. Ниже приведена конфигурация по умолчанию Web.Release.config: помимо некоторого примера кода преобразования, который закомментирован, он включает в себя код в элементе compilation, который удаляет атрибут debug.

<?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>

Атрибут xdt:Transform="RemoveAttributes(debug)" указывает, что debug атрибут должен быть удален из system.web/compilation элемента в развернутом файле web.config . Это будет выполнено каждый раз при развертывании сборки релиза.

Ограничение доступа к журналу ошибок администраторам

Если во время выполнения приложения возникает ошибка, приложение отображает универсальную страницу ошибок вместо страницы ошибки, созданной системой, и использует пакет Elmah NuGet для ведения журнала ошибок и создания отчетов. Элемент customErrors в файле конфигурации application Web.config указывает страницу ошибки:

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

Чтобы просмотреть страницу ошибок, временно измените mode атрибут customErrors элемента с "RemoteOnly" на "Вкл." и запустите приложение из Visual Studio. Вызовите ошибку, запросив недопустимый URL-адрес, например Studentsxxx.aspx. Вместо страницы ошибок, созданной службой IIS , "Не удается найти ресурс", вы увидите страницу GenericErrorPage.aspx .

Чтобы просмотреть журнал ошибок, замените все в URL-адресе после номера порта на elmah.axd (например, http://localhost:51130/elmah.axd,) и нажмите клавишу ВВОД.

Не забудьте вернуть элемент customErrors в режим "RemoteOnly", когда закончите.

На компьютере разработки удобно разрешить бесплатный доступ к странице журнала ошибок, но в рабочей среде это будет риск безопасности. Для рабочего сайта необходимо добавить правило авторизации, ограничивающее доступ к журналам ошибок администраторам, и убедиться, что ограничение работает в тестовом и промежуточном режиме. Поэтому это еще одно изменение, которое вы хотите реализовать каждый раз при развертывании релизной сборки, и поэтому оно принадлежит в файле Web.Release.config.

Откройте Web.Release.config и добавьте новый location элемент непосредственно перед закрывающим configuration тегом, как показано здесь.

<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>

Значение атрибута Transform "Insert" приводит к добавлению этого элемента location в качестве соседнего по отношению ко всем существующим элементам location в файле Web.config. (Существует уже один location элемент, указывающий правила авторизации для страницы Update Credits .)

Теперь вы можете просмотреть преобразование, чтобы убедиться, что вы правильно закодировали его.

В Обозреватель решений щелкните правой кнопкой мыши web.Release.config и щелкните "Предварительный просмотр преобразования".

Откроется страница, показывающая файл Web.config разработки слева и как будет выглядеть развернутый файл Web.config справа, где изменения выделены.

(В предварительной версии вы можете заметить некоторые дополнительные изменения, для которых не были записаны преобразования: обычно это связано с удалением пробелов, которые не влияют на функциональные возможности.)

При тестировании сайта после развертывания вы также протестируете, чтобы убедиться, что правило авторизации действует.

Параметр, который будет обрабатываться в файлах преобразования публикационного профиля

Распространенный сценарий — иметь параметры файла web.config , которые должны отличаться в каждой среде, в которой выполняется развертывание. Например, приложению, вызывающей службу WCF, может потребоваться другая конечная точка в тестовой и рабочей средах. Приложение Contoso University также включает в себя параметр такого рода. Этот параметр управляет видимым индикатором на страницах сайта, указывающих, в какой среде вы находитесь, например разработка, тестирование или рабочая среда. Значение параметра определяет, будет ли приложение добавлять "(Dev)" или "(Test)" в основной заголовок на главной странице Сайта.Master :

Индикатор среды опущен при выполнении приложения в промежуточной или рабочей среде.

Веб-страницы Университета Contoso считывают значение, заданное в appSettingsфайле web.config , чтобы определить, в какой среде работает приложение:

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

Значение должно быть "Test" в тестовой среде и "Prod" для промежуточной и рабочей среды.

Следующий код в файле преобразования реализует это преобразование:

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

Значение xdt:Transform атрибута SetAttributes указывает, что целью этого преобразования является изменение значений атрибутов существующего элемента в файле конфигурации Web.config . Значение xdt:Locator атрибута "Match(key)" указывает, что элемент, который необходимо изменить, является элементом, атрибут которого key соответствует атрибуту key , указанному здесь. Единственным другим атрибутом add элемента является value, и это то, что будет изменено в развернутом файле web.config . Приведенный здесь код приводит к установке атрибута EnvironmentappSettings элемента в значение "Test" в файле Web.config, который развертывается.

Это преобразование должно быть в файлах преобразования профиля публикации, которые вы еще не создали. Вы создадите и обновите файлы преобразования, которые реализуют это изменение при создании профилей публикации для тестовых, промежуточных и рабочих сред. Это можно сделать в учебниках по развертыванию в IIS и в производственную среду.

Настройка строк подключения

Хотя файл преобразования по умолчанию содержит пример, показывающий, как обновить строки подключения, в большинстве случаев вам не нужно настраивать преобразования строк подключения, так как в профиле публикации можно указать строки подключения. Это можно сделать в руководствах по развертыванию в IIS и развертыванию в рабочую среду.

Итоги

Теперь вы сделали всё, что могли с помощью преобразований Web.config, прежде чем создавать профили публикации, и вы видели предварительный просмотр того, что будет в развернутом файле Web.config.

В следующем руководстве вы будете заботиться о задачах настройки развертывания, требующих задания свойств проекта.

Дополнительные сведения

Дополнительные сведения о разделах, описанных в этом руководстве, см. в разделе "Использование преобразований Web.config" для изменения параметров в целевом файле Web.config или файле app.config во время развертывания в карте содержимого веб-развертывания для Visual Studio и ASP.NET.