Transformación del código fuente y los archivos de configuración

Una transformación de código fuente aplica el reemplazo unidireccional de tokens a los archivos en la carpeta content o contentFiles del paquete (content para los clientes que usan packages.config y contentFiles para PackageReference) al instalar el paquete, donde los tokens se refieren a las propiedades del proyecto de Visual Studio. Esto le permite insertar un archivo en el espacio de nombres del proyecto, o personalizar el código que normalmente se incluiría en global.asax en un proyecto de ASP.NET.

Una transformación de archivo de configuración permite modificar los archivos que ya existen en un proyecto de destino, como web.config y app.config. Por ejemplo, es posible que el paquete tenga que agregar un elemento a la modules sección del archivo de configuración. Esta transformación se realiza mediante la inclusión de archivos especiales en el paquete que describen las secciones que se van a agregar a los archivos de configuración. Cuando se desinstala un paquete, esos mismos cambios se invierten, lo que hace que sea una transformación bidireccional.

Especificación de transformaciones de código fuente

Los archivos que desea insertar desde el paquete en el proyecto deben encontrarse dentro de las carpetas content y contentFiles del paquete. Por ejemplo, si desea instalar un archivo llamado ContosoData.cs en una Models carpeta del proyecto de destino, debe estar dentro de las content\Models carpetas y contentFiles\{lang}\{tfm}\Models del paquete.
Para indicar a NuGet que aplique el reemplazo de tokens en tiempo de instalación, anexe .pp al nombre del archivo de código fuente. Después de la instalación, el archivo no tendrá la .pp extensión .

Por ejemplo, para realizar transformaciones en ContosoData.cs, asigne al archivo el nombre en el paquete ContosoData.cs.pp. Después de la instalación, aparecerá como ContosoData.cs.
En el archivo de código fuente, use tokens que no distinguen entre mayúsculas y minúsculas de la forma $token$ para indicar los valores que NuGet debe sustituir por las propiedades del proyecto.
```
namespace $rootnamespace$.Models
{
    public struct CategoryInfo
    {
        public string categoryid;
        public string description;
        public string htmlUrl;
        public string rssUrl;
        public string title;
    }
}
```
Tras la instalación, NuGet reemplaza $rootnamespace$ por Fabrikam suponiendo que el proyecto de destino cuyo espacio de nombres raíz sea Fabrikam.

El $rootnamespace$ token es la propiedad de proyecto más usada; todas las demás se muestran en las propiedades del proyecto. Tenga en cuenta, por supuesto, que algunas propiedades pueden ser específicas del tipo de proyecto.

Especificación de transformaciones de archivos de configuración

Como se describe en las secciones siguientes, las transformaciones de archivos de configuración se pueden realizar de dos maneras:

Incluir app.config.transform y web.config.transform archivos en la carpeta del content paquete, donde la .transform extensión indica a NuGet que estos archivos contienen el XML para combinarlos con los archivos de configuración existentes cuando se instala el paquete. Cuando se desinstala un paquete, se quita ese mismo XML.
Incluir los archivos app.config.install.xdt y web.config.install.xdt en la carpeta content del paquete, mediante la sintaxis XDT para describir los cambios deseados. Con esta opción también puede incluir un .uninstall.xdt archivo para revertir los cambios cuando el paquete se quita de un proyecto.

Nota:

Las transformaciones no se aplican a .config los archivos a los que se hace referencia como vínculo en Visual Studio.

La ventaja de usar XDT es que, en lugar de simplemente combinar dos archivos estáticos, proporciona una sintaxis para manipular la estructura de un DOM XML mediante la coincidencia de elementos y atributos mediante compatibilidad completa con XPath. Después, XDT puede agregar, actualizar o quitar elementos, colocar nuevos elementos en una ubicación específica o reemplazar o quitar elementos (incluidos los nodos secundarios). Esto facilita la creación de transformaciones de desinstalación que revierten todas las transformaciones realizadas durante la instalación del paquete.

Transformaciones XML

app.config.transform y web.config.transform en la carpeta content de un paquete solo contienen esos elementos que se van a fusionar en los archivos app.config y web.config existentes del proyecto.

Por ejemplo, supongamos que el proyecto contiene inicialmente el siguiente contenido en web.config:

<configuration>
    <system.webServer>
        <modules>
            <add name="ContosoUtilities" type="Contoso.Utilities" />
        </modules>
    </system.webServer>
</configuration>

Para agregar un MyNuModule elemento en la sección modules durante la instalación del paquete, crea un web.config.transform archivo en la carpeta del content paquete que tenga este aspecto:

<configuration>
    <system.webServer>
        <modules>
            <add name="MyNuModule" type="Sample.MyNuModule" />
        </modules>
    </system.webServer>
</configuration>

Una vez que NuGet instale el paquete, web.config aparecerá de la siguiente manera:

<configuration>
    <system.webServer>
        <modules>
            <add name="ContosoUtilities" type="Contoso.Utilities" />
            <add name="MyNuModule" type="Sample.MyNuModule" />
        </modules>
    </system.webServer>
</configuration>

Observe que NuGet no reemplazó la modules sección, simplemente combinó la nueva entrada en ella agregando solo nuevos elementos y atributos. NuGet no cambiará ningún elemento o atributo existente.

Cuando se desinstala el paquete, NuGet volverá a examinar los .transform archivos y quitará los elementos que contiene de los archivos adecuados .config . Tenga en cuenta que este proceso no afectará a las líneas del .config archivo que modifique después de la instalación del paquete.

Como ejemplo más extenso, el paquete Módulos y controladores de registro de errores para ASP.NET (ELMAH) agrega muchas entradas a web.config, que se quitan de nuevo cuando se desinstala un paquete.

Para examinar su web.config.transform archivo, descargue el paquete ELMAH del vínculo anterior, cambie la extensión de paquete de .nupkg a .zipy, a continuación, abra content\web.config.transform en ese archivo ZIP.

Para ver el efecto de instalar y desinstalar el paquete, cree un nuevo proyecto de ASP.NET en Visual Studio (la plantilla se encuentra en Visual C# > Web en el cuadro de diálogo Nuevo proyecto) y seleccione una aplicación ASP.NET vacía. Abra web.config para ver su estado inicial. A continuación, haga clic con el botón derecho en el proyecto, seleccione Administrar paquetes NuGet, busque ELMAH en nuget.org e instale la versión más reciente. Observe todos los cambios en web.config. Ahora desinstale el paquete y vea web.config revertir a su estado anterior.

Transformaciones XDT

Nota:

Como se mencionó en la sección de problemas de compatibilidad de paquetes de los documentos para la migración de packages.config a PackageReference, las transformaciones XDT, como se describe a continuación, solo son compatibles con packages.config. Si agrega los siguientes archivos al paquete, los consumidores que usan el paquete con PackageReference no tendrán aplicadas las transformaciones (consulte este ejemplo para que las transformaciones XDT funcionen).PackageReference

Puede modificar los archivos de configuración mediante la sintaxis XDT. También puede hacer que NuGet reemplace tokens por propiedades del proyecto mediante la inclusión del nombre de propiedad dentro de delimitadores $ (sin distinción entre mayúsculas y minúsculas).

Por ejemplo, el siguiente app.config.install.xdt archivo insertará un appSettings elemento en app.config que contiene los FullPathvalores , FileNamey ActiveConfigurationSettings del proyecto:

<?xml version="1.0"?>
<configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">
    <appSettings xdt:Transform="Insert">
        <add key="FullPath" value="$FullPath$" />
        <add key="FileName" value="$filename$" />
        <add key="ActiveConfigurationSettings " value="$ActiveConfigurationSettings$" />
    </appSettings>
</configuration>

En otro ejemplo, supongamos que el proyecto contiene inicialmente el siguiente contenido en web.config:

<configuration>
    <system.webServer>
        <modules>
            <add name="ContosoUtilities" type="Contoso.Utilities" />
        </modules>
    </system.webServer>
</configuration>

Para agregar un MyNuModule elemento a la sección modules durante la instalación del web.config.install.xdt paquete, contendrá lo siguiente:

<?xml version="1.0"?>
<configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">
    <system.webServer>
        <modules>
            <add name="MyNuModule" type="Sample.MyNuModule" xdt:Transform="Insert" />
        </modules>
    </system.webServer>
</configuration>

Después de instalar el paquete, web.config tendrá este aspecto:

<configuration>
    <system.webServer>
        <modules>
            <add name="ContosoUtilities" type="Contoso.Utilities" />
            <add name="MyNuModule" type="Sample.MyNuModule" />
        </modules>
    </system.webServer>
</configuration>

Para quitar solo el elemento MyNuModule durante la desinstalación del paquete, el archivo web.config.uninstall.xdt debe contener lo siguiente:

<?xml version="1.0"?>
<configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">
    <system.webServer>
        <modules>
            <add name="MyNuModule" xdt:Transform="Remove" xdt:Locator="Match(name)" />
        </modules>
    </system.webServer>
</configuration>

Comentarios

¿Le ha resultado útil esta página?

Last updated on 2025-10-31