Referencia de sustitución de variables y transformaciones de archivos

Artículo
04/04/2024

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

Algunas tareas, como la tarea Implementación de Azure App Service, versión 3 y posterior, y la tarea Implementación de aplicaciones web de IIS, permiten a los usuarios configurar el paquete en función del entorno especificado. Estas tareas usan msdeploy.exe, que admite la invalidación de valores en el archivo web.config con valores del archivo parameters.xml. Sin embargo, las transformaciones de archivos y la sustitución de variables no se limitan a los archivos de aplicación web. Puede usar estas técnicas con cualquier archivo XML o JSON.

Nota:

Las transformaciones de archivos y la sustitución de variables también son compatibles con la tarea Transformación de archivos independiente para su uso en Azure Pipelines. Puede usar la tarea Transformación de archivos para aplicar transformaciones de archivo y sustituciones de variables en cualquier archivo de configuración y parámetros.

La sustitución de configuración se especifica en la sección Opciones de transformación de archivos y sustitución de variables de la configuración de las tareas. Las opciones de transformación y sustitución son las siguientes:

Transformación XML
Sustitución de variables XML
Sustitución de variables JSON

Cuando se ejecuta la tarea, primero realiza la transformación XML, la sustitución de variables XML y la sustitución de variables JSON en los archivos de configuración y de parámetros. A continuación, invoca msdeploy.exe, que usa el archivo parameters.xml para sustituir los valores del archivo web.config.

Transformación XML

La transformación XML admite la transformación de los archivos de configuración (archivos *.config) siguiendo la sintaxis de transformación Web.config y se basa en el entorno en el que se va a implementar el paquete web. Esta opción es útil si desea agregar, quitar o modificar configuraciones en entornos diferentes. La transformación se aplicará a otros archivos de configuración, así como a los archivos de configuración de la aplicación de servicio de la consola o de Windows (por ejemplo, FabrikamService.exe.config).

Convenciones de nomenclatura de los archivos de transformación de configuración

La transformación XML se ejecutará en el archivo *.config para los archivos de configuración de transformación denominados *.Release.config o *.<stage>.config y se ejecutará en el orden siguiente:

*.Release.config (por ejemplo, fabrikam.Release.config)
*.<stage>.config (por ejemplo, fabrikam.Production.config)

Por ejemplo, si el paquete contiene los siguientes archivos:

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

y el nombre de la fase es Producción, la transformación se aplicará a Web.config con Web.Release.config seguido de Web.Production.config.

Ejemplo de transformación XML

Cree un paquete de aplicación web con los archivos de configuración y transformación necesarios. Por ejemplo, use los siguientes archivos de configuración:

Archivo de configuración

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

Archivo de transformación

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

Este archivo de configuración de transformación de ejemplo hace tres cosas:

Agrega una nueva cadena de conexión de base de datos dentro del elemento ConnectionStrings.
Modifica el valor de Webpages:Enabled dentro del elemento appSettings.
Quita el atributo debug del elemento compilation dentro del elemento System.Web.

Para obtener más información, consulte Sintaxis de transformación de Web.config para la implementación de proyectos web usando Visual Studio

Cree una canalización de versión con una fase denominada Versión.
Agregue una tarea Implementación de Azure App Service y establezca (marque) la opción Transformación XML.
Guarde la canalización de versión e inicie una nueva versión.

Abra el archivo Web.config para ver las transformaciones de 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>

Notas sobre la transformación XML

Puede usar esta técnica para crear un paquete predeterminado e implementarlo en varias fases.
La transformación XML solo surte efecto cuando el archivo de configuración y el archivo de transformación se encuentran en la misma carpeta dentro del paquete especificado.
De forma predeterminada, MSBuild aplica la transformación a medida que genera el paquete web si el elemento <DependentUpon> ya está presente en el archivo de transformación del archivo *.csproj. En tales casos, se producirá un error en la tarea Implementación de Azure App Service porque no se aplica ninguna transformación adicional en el archivo Web.config. Por lo tanto, se recomienda quitar el elemento <DependentUpon> de todos los archivos de transformación para deshabilitar cualquier configuración en tiempo de compilación al usar la transformación XML.

Establezca la propiedad Acción de compilación para cada uno de los archivos de transformación (Web.config) en Contenido para que los archivos se copien en la carpeta raíz.

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

Sustitución de variables XML

Esta característica permite modificar las opciones de configuración de los archivos de configuración (archivos *.config) dentro de paquetes web y de archivos de parámetros XML (parameters.xml). De este modo, el mismo paquete se puede configurar en función del entorno en el que se va a implementar.

La sustitución de variables solo surte efecto en los elementos applicationSettings, appSettings, connectionStrings y configSections de los archivos de configuración. Si desea sustituir valores fuera de estos elementos, puede usar un archivo (parameters.xml), pero deberá usar una tarea de canalización de terceros para controlar la sustitución de variables.

Ejemplo de sustitución de variables XML

Por ejemplo, observe la tarea de cambiar los siguientes valores en 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>

Cree una canalización de versión con una fase denominada Versión.
Agregue una tarea Implementación de Azure App Service y establezca (marque) la opción Sustitución de variables XML.

Defina los valores necesarios en las variables de canalización de versión:

Nombre	Value	Seguridad	Ámbito
DefaultConnection	Data Source=(ProdDB)\MSSQLProdDB;AttachFileName=Local.mdf	No	Release
AdminUserName	ProdAdminName	No	Release
AdminPassword	[su-contraseña]	Sí	Release
invariantName	System.Data.SqlClientExtension	No	Release

Guarde la canalización de versión e inicie una nueva versión.

Abra el archivo Web.config para ver las sustituciones de variables.

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

Notas sobre la sustitución de variables XML

De forma predeterminada, las aplicaciones ASP.NET tienen un atributo de conexión predeterminado con parámetros. Estos valores solo se reemplazan en el archivo parameters.xml que hay dentro del paquete web.
Dado que la sustitución se produce antes de la implementación, el usuario puede invalidar los valores de Web.config mediante parameters.xml (dentro del paquete web) o con un archivo setparameters.

Sustitución de variables JSON

Esta característica sustituye los valores de los archivos de configuración JSON. Invalida los valores de los archivos de configuración JSON especificados (por ejemplo, appsettings.json) con los valores que coinciden con los nombres de las variables de fase y de canalización de versión.

Para sustituir variables en archivos JSON específicos, proporcione una lista de archivos JSON separados por líneas nuevas. Los nombres de los archivos deben especificarse en relación con la carpeta raíz. Por ejemplo, si el paquete tiene esta estructura:

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

y quiere sustituir valores del archivo appsettings.json, escriba la ruta de acceso relativa de la carpeta raíz; por ejemplo, content/website/appsettings.json. Como alternativa, puede usar patrones de caracteres comodín para buscar archivos JSON específicos. Por ejemplo, **/appsettings.json devuelve la ruta de acceso relativa y el nombre de los archivos denominados appsettings.json.

Ejemplo de sustitución de variables JSON

Por ejemplo, observe la tarea de invalidar valores en este archivo 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"
        }
      ]
    }
  }
}

La tarea consiste en invalidar los valores de ConnectionString, DebugMode, el primero de los valores de Users y NewWelcomeMessage en los lugares respectivos dentro de la jerarquía de archivos JSON.

Clásico
YAML

Cree una canalización de versión con una fase denominada Versión.
Agregue una tarea Implementación de Azure App Service y escriba una lista separada por líneas nuevas de archivos JSON para sustituir los valores de las variables en el cuadro de texto Sustitución de variables JSON. Los nombres de los archivos deben ser relativos a la carpeta raíz. Puede usar caracteres comodín para buscar archivos JSON. Por ejemplo, **/*.json comporta sustituir los valores de todos los archivos JSON del paquete.

Defina los valores de sustitución necesarios en las variables de fase o de canalización de versión.

Nombre	Value	Seguridad	Ámbito
Data.DebugMode	deshabilitado	No	Release
Data.DefaultConnection.ConnectionString	Data Source=(prodDB)\MSDB;AttachDbFilename=prod.mdf;	No	Release
Data.DBAccess.Users.0	Admin-3	Sí	Release
Data.FeatureFlags.Preview.1.NewWelcomeMessage	AllAccounts	No	Release

Guarde la canalización de versión e inicie una nueva versión.

Después de la transformación, el JSON contendrá lo siguiente:

{
  "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"
        }
      ]
    }
  }
}
'''

El fragmento de código YAML siguiente muestra la sustitución de variables 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

Notas sobre la sustitución de variables JSON

Para sustituir valores en niveles anidados del archivo, concatene los nombres con un punto (.) en orden jerárquico.
Un objeto JSON puede contener una matriz cuyos valores puede referenciar su índice. Por ejemplo, para sustituir el primer valor de la matriz Users que se mostró antes, use el nombre de la variable DBAccess.Users.0. Para actualizar el valor de NewWelcomeMessage, use el nombre de la variable FeatureFlags.Preview.1.NewWelcomeMessage. Sin embargo, la tarea de transformación de archivos tiene la capacidad de transformar matrices completas en archivos JSON. También se puede usar DBAccess.Users = ["NewUser1","NewUser2","NewUser3"].
Solo se admite la sustitución de cadenas para la sustitución de variables JSON.
La sustitución solo se admite para los archivos codificados con UTF-8 y UTF-16 LE.
Si la especificación de archivo que escriba no coincide con ningún archivo, se producirá un error en la tarea.
La coincidencia de nombres de variables distingue mayúsculas de minúsculas.
La sustitución de variables se aplica solo a las claves JSON predefinidas en la jerarquía de objetos; no crea claves nuevas.
Si un nombre de variable incluye puntos ("."), la transformación intentará localizar el elemento dentro de la jerarquía. Por ejemplo, si el nombre de la variable es first.second.third, el proceso de transformación buscará:
```
"first" : {
  "second": {
    "third" : "value"
  }
}
```
así como "first.second.third" : "value".

Compartir a través de