FileTransform@2: tarea Transformación de archivos v2

Artículo
04/29/2024

Use esta tarea para reemplazar tokens por valores de variable en archivos de configuración XML o JSON.

Sintaxis

# File transform v2
# Replace tokens with variable values in XML or JSON configuration files.
- task: FileTransform@2
  inputs:
    folderPath: '$(System.DefaultWorkingDirectory)/**/*.zip' # string. Required. Package or folder. Default: $(System.DefaultWorkingDirectory)/**/*.zip.
    #xmlTransformationRules: '-transform **\*.Release.config -xml **\*.config' # string. XML Transformation rules. Default: -transform **\*.Release.config -xml **\*.config.
  # Variable Substitution
    #jsonTargetFiles: # string. JSON target files. 
    #xmlTargetFiles: # string. XML target files.

Entradas

folderPath - Paquete o carpeta
string. Obligatorio. Valor predeterminado: $(System.DefaultWorkingDirectory)/**/*.zip.

Ruta de acceso del archivo al paquete o a una carpeta.

Las variables son Build y Release. Se admite caracteres comodín.

Por ejemplo, $(System.DefaultWorkingDirectory)/**/*.zip. Para las carpetas comprimidas, el contenido se extrae en la ubicación TEMP, las transformaciones ejecutadas y los resultados comprimidos en la ubicación del artefacto original.

xmlTransformationRules - Reglas de transformación XML
string. Valor predeterminado: -transform **\*.Release.config -xml **\*.config.

Proporciona una lista de reglas de archivo de transformación separadas por líneas mediante la sintaxis : -transform <pathToTransformFile> -xml <pathToSourceConfigurationFile>. La ruta de acceso del archivo de resultado es opcional y, si no se especifica, el archivo de configuración de origen se reemplazará por el archivo de resultados transformado.

jsonTargetFiles - Archivos de destino JSON
string.

Proporciona una lista de archivos separados por líneas nuevas para sustituir los valores de variable. Los nombres de archivo se deben proporcionar en relación con la carpeta raíz.

Por ejemplo, para reemplazar el valor de ConnectionString en el ejemplo siguiente, debe definir una variable como Data.DefaultConnection.ConnectionString en la canalización de compilación o versión (o el entorno de la canalización de versión).

{
  "Data": {
    "DefaultConnection": {
      "ConnectionString": "Server=(localdb)\SQLEXPRESS;Database=MyDB;Trusted_Connection=True"
    }
  }
}

La sustitución de variables se ejecuta después de las transformaciones de configuración.

Nota: Solo se usan variables personalizadas definidas en canalizaciones de compilación o versión en sustitución. Se excluyen las variables de canalización definidas por el sistema o predeterminadas. Si las mismas variables se definen en la canalización de versión y en la fase, las variables de fase reemplazarán las variables de canalización de versión.

xmlTargetFiles - Archivos de destino XML
string.

Proporciona una lista de archivos separados por líneas nuevas para sustituir los valores de variable. Los nombres de archivo se deben proporcionar en relación con la carpeta raíz.

Para XML, las variables definidas en las canalizaciones de compilación o versión coincidirán con las key entradas o name de las appSettingssecciones , applicationSettingsy connectionStrings de cualquier archivo de configuración y parameters.xml.

La sustitución de variables se ejecuta después de las transformaciones de configuración.

Opciones de control de tareas

Todas las tareas tienen opciones de control además de sus entradas de tareas. Para obtener más información, vea Opciones de control y propiedades de tareas comunes.

Variables de salida

Ninguno.

Observaciones

Novedades de la transformación de archivos versión 2:

Campos de tareas más optimizados que permiten a los usuarios habilitar todas o todas las características de transformación (XML), sustitución de variables (JSON y XML) en una sola instancia de tarea.
Se produce un error en la tarea cuando no se aplica ninguna de las transformaciones o sustitución configuradas o cuando la tarea no es operativa.

Use esta tarea para aplicar transformaciones de archivos y sustituciones de variables en archivos de configuración y parámetros. Para obtener más información sobre cómo se procesan las traducciones, consulte Referencia de transformaciones de archivos y sustitución de variables.

Importante

Esta tarea está pensada para paquetes web y requiere un archivo de paquete web. No funciona en archivos JSON independientes.

Transformaciones de archivos

En la actualidad, las transformaciones de archivos solo se admiten para archivos XML.
Para aplicar una transformación XML a los archivos de configuración (*.config), debe especificar una lista separada por líneas nuevas de reglas de archivo de transformación mediante la sintaxis :-t ransform <path to the transform file> -xml <path to the source file> -result <path to the result file>
Las transformaciones de archivos son útiles en muchos escenarios, especialmente cuando se implementa en un servicio de aplicaciones y desea agregar, quitar o modificar configuraciones para distintos entornos (como Dev, Test o Prod) siguiendo la sintaxis de transformación deWeb.config estándar.
También puede usar esta funcionalidad para transformar otros archivos, incluidos los archivos de configuración de la aplicación de servicio de Consola o Windows (por ejemplo, FabrikamService.exe.config).
Las transformaciones de archivo de configuración se ejecutan antes de las sustituciones de variables.

Sustitución de variables

En la actualidad, solo se admiten formatos de archivo XML y JSON para la sustitución de variables.
Los tokens definidos en los archivos de configuración de destino se actualizan y, a continuación, se reemplazan por valores de variable.
Las sustituciones de variables se ejecutan después de las transformaciones del archivo de configuración.
La sustitución de variables solo se aplica a las claves JSON predefinidas en la jerarquía de objetos. No crea nuevas claves.

Nota:

Solo se usan variables personalizadas definidas en canalizaciones de compilación y versión en sustitución. Se excluyen las variables de canalización predeterminadas y del sistema.

Esta es una lista de prefijos excluidos actualmente:

agent.
azure_http_user_agent
build.
common.
release.
system.
tf_

Si las mismas variables se definen en la canalización de versión y en una fase, las variables definidas por fases reemplazan a las variables definidas por la canalización.

Consulte también: Referencia de transformaciones de archivos y sustitución de variables.

Ejemplos

Si necesita que la transformación XML se ejecute en todos los archivos de configuración denominados con el patrón .Production.config, se debe especificar la regla de transformación como:

-transform **\*.Production.config -xml **\*.config

Si tiene un archivo de configuración denominado en función del nombre de fase de la canalización, puede usar:

-transform **\*.$(Release.EnvironmentName).config -xml **\*.config

Para sustituir variables JSON anidadas o jerárquicas, especifíquelas mediante expresiones JSONPath. Por ejemplo, para reemplazar el valor de ConnectionString en el ejemplo siguiente, debe definir una variable como Data.DefaultConnection.ConnectionString en la canalización de compilación o versión (o en una fase dentro de la canalización de versión).

{
  "Data": {
    "DefaultConnection": {
      "ConnectionString": "Server=(localdb)\SQLEXPRESS;Database=MyDB;Trusted_Connection=True"
    }
  }
}

Requisitos

Requisito	Descripción
Tipos de canalización	YAML, compilación clásica, versión clásica
Se ejecuta en	Agente, DeploymentGroup
Peticiones	Ninguno
Capabilities	Esta tarea no satisface ninguna demanda de tareas posteriores en el trabajo.
Restricciones de comandos	Any
Variables que se pueden establecer	Any
Versión del agente	Todas las versiones de agente compatibles.
Categoría de la tarea:	Utilidad

Consulte también

Referencia de transformaciones de archivos y sustitución de variables