Справочник по преобразованиям файлов и подстановкам переменных

Azure DevOps Services | Azure DevOps Server 2022 — Azure DevOps Server 2019

Некоторые задачи, такие как приложение Azure служба развертывания задачи 3 и более поздних версий, а также задача развертывания веб-приложений IIS, позволяют пользователям настраивать пакет на основе указанной среды. Эти задачи используют msdeploy.exe, которые поддерживают переопределение значений в файле web.config со значениями из файла parameters.xml . Однако преобразования файлов и подстановка переменных не ограничиваются файлами веб-приложения. Эти методы можно использовать с любыми XML-файлами или JSON.

Примечание.

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

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

• Преобразование XML
• Подстановка переменных XML
• Подстановка переменных JSON

При выполнении задачи сначала выполняется преобразование XML, подстановка переменных XML и подстановка переменных JSON в файлах конфигурации и параметров. Затем он вызывает msdeploy.exe, который использует файл parameters.xml для замены значений в файле web.config.

Преобразование XML

Преобразование XML поддерживает преобразование файлов конфигурации (*.config файлов), следуя синтаксису преобразования Web.config и основан на среде, в которой будет развернут веб-пакет. Этот параметр полезен при добавлении, удалении или изменении конфигураций для разных сред. Преобразование будет применяться для других файлов конфигурации, включая файлы конфигурации консольного или службы Windows (например, FabrikamService.exe.config).

Соглашения об именовании файлов конфигурации

Преобразование XML будет выполняться в *.config файле для файлов конфигурации преобразования с именем *.Release.config или *.<stage>.config будет выполняться в следующем порядке:

1. *.Release.config (например, fabrikam. Release.config)
2. *.<stage>.config (например, fabrikam. Production.config)

Например, если пакет содержит следующие файлы:

• Web.config
• Web.Debug.config
• Web.Release.config
• Web.Production.config

и имя сцены — Production, преобразование применяется для Web.configWeb.Release.config последующего Web.Production.configвыполнения.

Пример преобразования XML

1. Создайте пакет веб-приложения с необходимыми файлами конфигурации и преобразования. Например, используйте следующие файлы конфигурации:

   Файл конфигурации

   <?xml version="1.0" encoding="utf-8"?>
   <configuration>
     <connectionStrings>
       <add name="DefaultConnection"
            connectionString="Data Source=(LocalDb)\\MSDB;DbFilename=aspcore-local.mdf;" />
     </connectionStrings>
     <appSettings>
       <add key="webpages:Version" value="3.0.0.0" />
       <add key="webpages:Enabled" value="false" />
     </appSettings>
     <system.web>
       <authentication mode="None" />
       <compilation targetFramework="4.5" debug="true" />
     </system.web>
   </configuration>
   

   Файл преобразования

   <?xml version="1.0"?>
   <configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">
       <connectionStrings>
         <add name="MyDB"
              connectionString="Data Source=ReleaseSQLServer;Initial Catalog=MyReleaseDB;Integrated Security=True"
              xdt:Transform="Insert" />
       </connectionStrings>
     <appSettings>
       <add xdt:Transform="Replace" xdt:Locator="Match(key)" key="webpages:Enabled" value="true" />
     </appSettings>
     <system.web>
       <compilation xdt:Transform="RemoveAttributes(debug)" />
     </system.web>
   </configuration>
   

   В этом примере файл конфигурации преобразования выполняет три действия.

   • Он добавляет новую базу данных строка подключения внутри ConnectionStrings элемента.
   • Он изменяет значение Webpages:Enabled внутри appSettings элемента.
   • Он удаляет debug атрибут из compilation элемента внутри System.Web элемента.

   Дополнительные сведения см. в разделе Синтаксис преобразования Web.config для развертывания веб-проекта с помощью Visual Studio

2. Создайте конвейер выпуска с этапом с именем Release.

3. Добавьте задачу развертывания службы приложение Azure и установите (тик) параметр преобразования XML.

   

4. Сохраните конвейер выпуска и запустите новый выпуск.

5. Web.config Откройте файл, чтобы просмотреть преобразования из Web.Release.config.

   <?xml version="1.0" encoding="utf-8"?>
   <configuration>
     <connectionStrings>
       <add name="DefaultConnection"
            connectionString="Data Source=(LocalDb)\\MSDB;DbFilename=aspcore-local.mdf;" />
     <add name="MyDB"
          connectionString="Data Source=ReleaseSQLServer;Initial Catalog=MyReleaseDB;Integrated Security=True" />
     </connectionStrings>
     <appSettings>
       <add key="webpages:Version" value="3.0.0.0" />
       <add key="webpages:Enabled" value="true" />
     </appSettings>
     <system.web>
       <authentication mode="None" />
       <compilation targetFramework="4.5" />
     </system.web>
   </configuration>
   

Заметки о преобразовании XML

• Этот метод можно использовать для создания пакета по умолчанию и его развертывания на нескольких этапах.

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

• По умолчанию MSBuild применяет преобразование, так как он создает веб-пакет, если <DependentUpon> элемент уже присутствует в файле преобразования в *.csproj файле преобразования. В таких случаях задача развертывания службы приложение Azure завершится ошибкой, так как к файлу не применяется дальнейшее Web.config преобразование. Поэтому рекомендуется удалить <DependentUpon> элемент из всех файлов преобразования, чтобы отключить любую конфигурацию во время сборки при использовании преобразования XML.

• Задайте свойству Действия сборки для каждого из файлов преобразования (Web.config) значение Content , чтобы файлы копировались в корневую папку.

  ...
  <Content Include="Web.Debug.config">
     <DependentUpon>Web.config</DependentUpon>
  </Content>
  <Content Include="Web.Release.config">
     <DependentUpon>Web.config</DependentUpon>
  </Content>
  ...
  

Подстановка переменных XML

Эта функция позволяет изменять параметры конфигурации в файлах конфигурации (*.config файлах) в веб-пакетах и XML-файлах параметров (parameters.xml). Таким образом, один и тот же пакет можно настроить на основе среды, в которой она будет развернута.

Подстановка переменных действует только на applicationSettingsappSettingsэлементы файлов конфигурации , connectionStringsа также configSections элементы . Если вы хотите заменить значения за пределами этих элементов, можно использовать (parameters.xml) файл, однако для обработки подстановки переменной потребуется задача 3-го поставщика конвейера.

Пример подстановки xml-переменных

В качестве примера рассмотрим задачу изменения следующих значений в Web.config:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
    <configSection>
        <section name="entityFramework" />
    </configSection>
    <connectionStrings>
        <!-- Change connectionString in this line: --> 
        <add name="DefaultConnection"
             connectionString="Data Source=(LocalDB)\LocalDB;FileName=Local.mdf" />
    </connectionStrings>
    <appSettings>
        <add key="ClientValidationEnabled" value="true" />
        <add key="UnobstructiveJavascriptEnabled" value="true" />
        <!-- Change AdminUserName in this line: --> 
        <add key="AdminUserName" value="__AdminUserName__" />
        <!-- Change AdminPassword in this line: --> 
        <add key="AdminPassword" value="__AdminPassword__" />
    </appSettings>
    <entityFramework>
        <defaultConnectionFactory type="System.Data.Entity.LocalDbConnectionFactory">
            <parameters></parameters>
        </defaultConnectionFactory>
        <providers>
            <!-- Change invariantName in this line: --> 
            <provider invariantName="System.Data.SqlClient" type="System.Data.Entity.SqlServer" />
        </providers>
    </entityFramework>
</configuration>

1. Создайте конвейер выпуска с этапом с именем Release.

2. Добавьте задачу развертывания службы приложение Azure и установите (тик) параметр подстановки переменных XML.

   

3. Определите необходимые значения в переменных конвейера выпуска:

   Имя.	Значение	Защита	Область
   По умолчанию Подключение ion	Источник данных=(ProdDB)\MSSQLProdDB; AttachFileName=Local.mdf	No	Выпуск
   AdminUserName	Prod Администратор Name	No	Выпуск
   AdminPassword	[ваш пароль]	Да	Выпуск
   invariantName	System.Data.SqlClientExtension	No	Выпуск

4. Сохраните конвейер выпуска и запустите новый выпуск.

5. Web.config Откройте файл, чтобы просмотреть подстановки переменных.

   <?xml version="1.0" encoding="utf-8"?>
   <configuration>
       <configSection>
           <section name="entityFramework" />
       </configSection>
       <connectionStrings>
           <add name="DefaultConnection"
                connectionString="Data Source=(ProdDB)\MSSQLProdDB;AttachFileName=Local.mdf" />
       </connectionStrings>
       <appSettings>
           <add key="ClientValidationEnabled" value="true" />
           <add key="UnobstructiveJavascriptEnabled" value="true" />
           <add key="AdminUserName" value="ProdAdminName" />
           <add key="AdminPassword" value="*password_masked_for_display*" />
       </appSettings>
       <entityFramework>
           <defaultConnectionFactory type="System.Data.Entity.LocalDbConnectionFactory">
               <parameters></parameters>
           </defaultConnectionFactory>
           <providers>
               <provider invariantName="System.Data.SqlClientExtension"
                         type="System.Data.Entity.SqlServer" />
           </providers>
       </entityFramework>
   </configuration>
   

Заметки о подстановки XML-переменных

• По умолчанию ASP.NET приложения имеют параметризованный атрибут подключения по умолчанию. Эти значения переопределяются только в файле внутри parameters.xml веб-пакета.

• Так как перед развертыванием происходит подстановка, пользователь может переопределить значения в использовании parameters.xml (внутри Web.config веб-пакета) или setparameters файла.

Подстановка переменных JSON

Эта функция заменяет значения в файлах конфигурации JSON. Он переопределяет значения в указанных файлах конфигурации JSON (например, appsettings.json) со значениями, соответствующими именам конвейера выпуска и переменным этапа.

Чтобы заменить переменные в определенных JSON-файлах, укажите список файлов JSON, разделенных новой строкой. Имена файлов должны быть указаны относительно корневой папки. Например, если пакет имеет эту структуру:

/WebPackage(.zip)
  /---- content
    /----- website
      /---- appsettings.json
      /---- web.config
      /---- [other folders] 
  /--- archive.xml
  /--- systeminfo.xml

и вы хотите заменить значения в appsettings.json, введите относительный путь из корневой папки, например content/website/appsettings.json. Кроме того, используйте шаблоны wild карта для поиска определенных JSON-файлов. Например, **/appsettings.json возвращает относительный путь и имя файлов с именем appsettings.json.

Пример подстановки переменных JSON

Например, рассмотрим задачу переопределения значений в этом JSON-файле:

{
  "Data": {
    "DefaultConnection": {
      "ConnectionString": "Data Source=(LocalDb)\\MSDB;AttachDbFilename=aspcore-local.mdf;"
    },
    "DebugMode": "enabled",
    "DBAccess": {
      "Administrators": ["Admin-1", "Admin-2"],
      "Users": ["Vendor-1", "vendor-3"]
    },
    "FeatureFlags": {
      "Preview": [
        {
          "newUI": "AllAccounts"
        },
        {
          "NewWelcomeMessage": "Newusers"
        }
      ]
    }
  }
}

Задача заключается в переопределении значений Подключение ionString, DebugMode, первой из значений Users и NewWelcomeMessage в соответствующих местах в иерархии файлов JSON.

Классическое

1. Создайте конвейер выпуска с этапом с именем Release.

2. Добавьте задачу развертывания службы приложение Azure и введите новый разделенный строкой список JSON-файлов, чтобы заменить значения переменных в текстовом поле подстановки переменных JSON. Имена файлов должны быть относительными к корневой папке. Для поиска JSON-файлов можно использовать дикие карта. Например, **/*.json означает, что значения заменяются во всех JSON-файлах в пакете.

   

3. Определите необходимые значения подстановки в конвейере выпуска или переменных этапа.

   Имя.	Значение	Защита	Область
   Data.DebugMode	disabled (выключено)	No	Выпуск
   Data.Default Подключение ion.ПодключениеionString	Data Source=(prodDB)\MSDB; AttachDbFilename=prod.mdf;	No	Выпуск
   Data.DBAccess.Users.0	Администратор-3	Да	Выпуск
   Data.FeatureFlags.Preview.1.NewWelcomeMessage	AllAccounts	No	Выпуск

4. Сохраните конвейер выпуска и запустите новый выпуск.

5. После преобразования JSON будет содержать следующее:

   {
     "Data": {
       "DefaultConnection": {
         "ConnectionString": "Data Source=(prodDB)\MSDB;AttachDbFilename=prod.mdf;"
       },
       "DebugMode": "disabled",
       "DBAccess": {
         "Administrators": ["Admin-1", "Admin-2"],
         "Users": ["Admin-3", "vendor-3"]
       },
       "FeatureFlags": {
         "Preview": [
           {
             "newUI": "AllAccounts"
           },
           {
             "NewWelcomeMessage": "AllAccounts"
           }
         ]
       }
     }
   }
   '''
   
   

YAML

После фрагмента кода YAML демонстрируется подстановка переменных JSON.

variables:
  Data.DebugMode: disabled
  Data.DefaultConnection.ConnectionString: 'Data Source=(prodDB)\MSDB;AttachDbFilename=prod.mdf;'
  Data.DBAccess.Users.0: Admin-3
  Data.FeatureFlags.Preview.1.NewWelcomeMessage: AllAccounts

# Update appsettings.json via FileTransform task.
- task: FileTransform@1
  displayName: 'File transformation: appsettings.json'
  inputs:
    folderPath: '$(Build.ArtifactStagingDirectory)/$(Build.BuildId).zip'
    targetFiles: '**/appsettings.json'
    fileType: json
  
# Deploy web app
- task: AzureWebApp@1
  inputs:
    azureSubscription: <Name of the Azure subscription>
    appName: <Name of the Azure WebApp>
    package: $(Build.ArtifactStagingDirectory)/$(Build.BuildId).zip

Заметки о подстановки переменных JSON

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

• Объект JSON может содержать массив, значения которого можно ссылаться по индексу. Например, чтобы заменить первое значение в массиве Users , приведенном выше, используйте имя DBAccess.Users.0переменной. Чтобы обновить значение в NewWelcomeMessage, используйте имя FeatureFlags.Preview.1.NewWelcomeMessageпеременной. Однако задача преобразования файлов имеет возможность преобразовывать целые массивы в JSON-файлах. Также можно использовать DBAccess.Users = ["NewUser1","NewUser2","NewUser3"].

• Для подстановки переменных JSON поддерживается только подстановка строк .

• Подстановка поддерживается только для файлов в кодировке UTF-8 и UTF-16 LE.

• Если указанная спецификация файла не соответствует файлу, задача завершится ошибкой.

• Сопоставление имен переменной учитывает регистр.

• Подстановка переменных применяется только для ключей JSON, предопределенных в иерархии объектов. Он не создает новые ключи.

• Если имя переменной содержит точки ("."), преобразование попытается найти элемент в иерархии. Например, если имя переменной имеется first.second.third, процесс преобразования будет искать:

  "first" : {
    "second": {
      "third" : "value"
    }
  }
  

  а также "first.second.third" : "value".