Настройка параметров для развертывания веб-пакета

Джейсон Ли

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

При создании проекта веб-приложения процесс сборки и упаковки создает три ключевых файла:

• Файл .zip[имя проекта] . Это пакет веб-развертывания для проекта веб-приложения. Этот пакет содержит все сборки, файлы, скрипты базы данных и ресурсы, необходимые для повторного создания веб-приложения на удаленном веб-сервере IIS.
• Файл .deploy.cmd [имя проекта]. Это содержит набор параметризованных команд веб-развертывания (MSDeploy.exe), публикующих пакет веб-развертывания на удаленном веб-сервере IIS.
• Файл .SetParameters.xml[имя проекта] . Это предоставляет набор значений параметров для команды MSDeploy.exe. Значения в этом файле можно обновить и передать в Web Deploy в качестве параметра командной строки при развертывании web package.

Файл SetParameters.xml динамически создается из файла проекта веб-приложения и всех файлов конфигурации в проекте. При сборке и пакете проекта конвейер веб-публикации (WPP) автоматически обнаруживает множество переменных, которые, скорее всего, изменяются между средами развертывания, такими как целевое веб-приложение IIS и все строки подключения к базе данных. Эти значения автоматически параметризируются в пакете веб-развертывания и добавляются в файл SetParameters.xml . Например, если добавить строку подключения в файл web.config в проекте веб-приложения, процесс сборки обнаружит это изменение и добавит запись в файл SetParameters.xml соответствующим образом.

В большинстве случаев эта автоматическая параметризация будет достаточной. Однако если пользователям нужно изменить другие параметры между средами развертывания, такими как параметры приложения или URL-адреса конечной точки службы, необходимо сообщить WPP параметризировать эти значения в пакете развертывания и добавить соответствующие записи в файл SetParameters.xml . В следующих разделах объясняется, как это сделать.

Автоматическая параметризация

При сборке и пакете веб-приложения WPP автоматически параметризует следующие элементы:

• Путь и имя целевого веб-приложения IIS.
• Все строки подключения в файле web.config .
• Строки подключения для всех баз данных, которые вы добавляете на вкладку "Пакет/Публиковать SQL" страницы свойств проекта.

Например, если вы хотите создать и упаковать пример решения Contact Manager без касания процесса параметризации каким-либо образом, WPP создаст этот файл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>

В данном случае:

• Параметр IIS Web Application Name указывает путь IIS, где вы хотите развернуть веб-приложение. Значение по умолчанию берется со страницы Package/Publish Web в страницах свойств проекта.
• Параметр строки подключенияApplicationServices-Web.config был создан из элемента connectionStrings/add в файле web.config . Он представляет строку подключения, которую приложение должно использовать для связи с базой данных членства. Значение, указанное здесь, будет подставлено в файл web.config, задействованный при развертывании. Значение по умолчанию берется из файлаweb.config предварительного развертывания.

WPP также параметризирует эти свойства в пакете развертывания, который он создает. Эти свойства можно указать при установке пакета развертывания. При установке пакета вручную с помощью диспетчера IIS, как описано в руководстве по установке веб-пакетов вручную, мастер установки предложит указать значения для любых параметров. Если вы устанавливаете пакет удаленно с помощью файла .deploy.cmd, как описано в разделе "Развертывание веб-пакетов", программа Web Deploy обратится к этому SetParameters.xml файлу, чтобы задать значения параметров. Значения в файле SetParameters.xml можно изменить вручную или настроить файл в рамках автоматизированного процесса сборки и развертывания. Этот процесс подробно описан далее в этом разделе.

Настраиваемая параметризация

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

• Конечные точки службы в файлеweb.config .
• Параметры приложения в файлеweb.config .
• Любые другие декларативные свойства, которые требуется указать пользователям.

Самый простой способ параметризации этих свойств — добавить файлparameters.xml в корневую папку проекта веб-приложения. Например, в решении Диспетчера контактов проект ContactManager.Mvc содержит файлparameters.xml в корневой папке.

При открытии этого файла вы увидите, что он содержит одну запись параметров . Запись использует запрос на языке XML Path (XPath) для поиска и параметризации URL-адреса конечной точки службы Windows Communication Foundation (WCF) ContactService в файле 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>

Помимо параметризации URL-адреса конечной точки в пакете развертывания, WPP также добавляет соответствующую запись в файл SetParameters.xml , который создается вместе с пакетом развертывания.

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

При установке пакета развертывания вручную диспетчер IIS предложит вам адрес конечной точки службы вместе со свойствами, которые были параметризованы автоматически. Если установить пакет развертывания, выполнив файл .deploy.cmd , можно изменить файл SetParameters.xml , чтобы указать значение адреса конечной точки службы вместе со значениями свойств, которые были параметризованы автоматически.

Полные сведения о создании файлаparameters.xml см. в разделе "Практическое руководство. Использование параметров для настройки параметров развертывания при установке пакета". Процедура с именем "Использовать параметры развертывания для параметров Web.config файлов" содержит пошаговые инструкции.

Изменение файла SetParameters.xml

Если вы планируете развернуть пакет веб-приложения вручную, запустив файл .deploy.cmd или выполнив MSDeploy.exe из командной строки, вам ничего не нужно, чтобы вручную изменить файл SetParameters.xml до развертывания. Однако при работе с решением корпоративного масштаба может потребоваться развернуть пакет веб-приложения в рамках более крупного автоматизированного процесса сборки и развертывания. В этом сценарии вам необходима подсистема сборки Майкрософт (MSBuild), чтобы изменить файл SetParameters.xml. Это можно сделать с помощью задачи MSBuild XmlPoke .

Пример решения Диспетчера контактов иллюстрирует этот процесс. Приведенные ниже примеры кода были изменены, чтобы отобразить только сведения, относящиеся к этому примеру.

Во-первых, значения параметров, интересующие вас, определяются как свойства в файле проекта для конкретной среды (например, 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>

Затем файл Publish.proj импортирует эти свойства. Так как каждый файлSetParameters.xml связан с файлом .deploy.cmd , и мы в конечном итоге хотим, чтобы файл проекта вызвал каждый файл .deploy.cmd , файл проекта создает элемент MSBuild для каждого файла .deploy.cmd и определяет свойства интересующего элемента как метаданные элемента.

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

В данном случае:

• Значение метаданных ParametersXml указывает расположение файла SetParameters.xml .
• Значение IisWebAppName — это путь IIS, к которому требуется развернуть веб-приложение.
• Значение MembershipDBConnectionString — это строка подключения для базы данных членства, а значение MembershipDBConnectionName — это атрибут имени соответствующего параметра в файле SetParameters.xml .
• Значение ServiceEndpointValue — это адрес конечной точки для службы WCF на целевом сервере, а значение ServiceEndpointParamName — это атрибут имени соответствующего параметра в файлеSetParameters.xml .

Наконец, в файле Publish.proj целевой объект PublishWebPackages использует задачу XmlPoke для изменения этих значений в файле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>

Вы заметите, что каждая задача XmlPoke указывает четыре значения атрибутов:

• Атрибут XmlInputPath указывает задаче, где найти файл, который требуется изменить.
• Атрибут query — это запрос XPath, определяющий узел XML, который требуется изменить.
• Атрибут Value — это новое значение, которое нужно вставить в выбранный XML-узел.
• Атрибут Условия — это критерии, в которых задача должна выполняться или не выполняться. В этих случаях условие гарантирует, что вы не пытаетесь вставить значение NULL или пустое значение в файл SetParameters.xml .

Conclusion

В этом разделе описана роль файла SetParameters.xml и объясняется, как он создается при создании проекта веб-приложения. В нем объясняется, как параметризировать дополнительные параметры, добавив в проект файлparameters.xml . В нем также описано, как изменить файлSetParameters.xml в рамках более крупного автоматизированного процесса сборки с помощью задачи XmlPoke в файлах проекта.

В следующем разделе , в разделе "Развертывание веб-пакетов" описывается, как развернуть веб-пакет, выполнив файл .deploy.cmd или с помощью команд MSDeploy.exe напрямую. В обоих случаях можно указать файлSetParameters.xml в качестве параметра развертывания.

Дальнейшее чтение

Сведения о создании веб-пакетов см. в разделе "Создание и упаковка проектов веб-приложений". Инструкции по развертыванию веб-пакета см. в разделе "Развертывание веб-пакетов". Пошаговое руководство по созданию файлаparameters.xml см. в разделе "Практическое руководство. Использование параметров для настройки параметров развертывания при установке пакета".

Для получения общей информации о параметризации в Web Deploy см. запись в блоге «Параметризация в Web Deploy в действии».