Transformaciones de MSBuild

Actualización: noviembre 2007

Una transformación es una conversión unívoca de una colección de elementos en otra. Además de permitir que un proyecto convierta colecciones de elementos, las transformaciones permiten que un destino identifique una asignación directa entre sus entradas y resultados. En este tema se explican las transformaciones y cómo MSBuild las utiliza para generar los proyectos más eficazmente.

Modificadores de transformación

Las transformaciones no son arbitrarias, pero están limitadas por una sintaxis especial en la que todos los modificadores de transformación deben tener el formato %(ItemMetaDataName). Es posible utilizar cualquier metadato de elementos como modificador de transformación, incluidos los metadatos de elementos conocidos y asignados a cada elemento durante la creación. Para obtener una lista de metadatos de elementos conocidos, vea Metadatos de los elementos conocidos de MSBuild.

En el ejemplo siguiente, una lista de archivos .resx se transforma en una lista de archivos .resources. El modificador de transformación % (nombre de archivo) especifica que cada archivo .resources tiene el mismo nombre de archivo que el archivo .resx correspondiente.

@(RESXFile->'%(filename).resources')

Nota:
Es posible especificar un separador personalizado para una colección de elementos transformada de la misma manera en la que se haría con una colección de elementos normal. Por ejemplo, para separar una colección de elementos transformada con una coma (,) en lugar del punto y coma predeterminado (;), utilice el código XML siguiente. @(RESXFile->'Toolset\%(filename)%(extension)', ',')

Por ejemplo, si los elementos de la colección de elementos @(RESXFile) son Form1.resx, Form2.resx y Form3.resx, el resultado en la lista transformada será Form1.resources, Form2.resources y Form3.resources.

Utilizar varios modificadores

Una transformación puede contener varios modificadores, que se pueden combinar en cualquier orden, y éstos se pueden repetir en una expresión de transformación. En el ejemplo siguiente, el nombre del directorio que contiene los archivos se cambia, pero los archivos conservan el nombre y la extensión de archivo originales.

@(RESXFile->'Toolset\%(filename)%(extension)')

Por ejemplo, si los elementos incluidos en la colección de elementos RESXFile son Project1\Form1.resx, Project1\Form2.resx y Project1\Form3.text, el resultado en la lista transformada será Toolset\Form1.resx, Toolset\Form2.resx y Toolset\Form3.text.

Análisis de dependencia

Las transformaciones garantizan una asignación unívoca entre la colección de elementos transformada y la colección de elementos original. Debido a ello, si un destino crea resultados que son transformaciones de las entradas, MSBuild puede analizar las marcas de tiempo de las entradas y los resultados, y decidir si se debe omitir, construir o reconstruir parcialmente un destino.

En la tarea Copiar del ejemplo siguiente, cada archivo de la colección de elementos BuiltAssemblies se asigna a un archivo en la carpeta de destino de la tarea, especificado por una transformación en el atributo Outputs. Si cambia cualquiera de los archivos de la colección de elementos BuiltAssemblies, la tarea Copy sólo se ejecutará para los archivos modificados y se omitirán los demás. Para obtener más información sobre el análisis de dependencia y el uso de transformaciones, vea Cómo: Generar versiones incrementalmente.

<Target Name="CopyOutputs"
    Inputs="@(BuiltAssemblies)"
    Outputs="@(BuiltAssemblies -> '$(OutputPath)%(Filename)%(Extension)')">

    <Copy
        SourceFiles="@(BuiltAssemblies)"
        DestinationFolder="$(OutputPath)"/>

</Target>

Ejemplo

Descripción

El ejemplo siguiente muestra un archivo de proyecto de MSBuild con transformaciones. Este ejemplo da por hecho que existe un archivo .xsd único en el directorio c:\sub0\sub1\sub2\sub3 y en un directorio de trabajo de c:\sub0.

Código

<Project xmlns="https://schemas.microsoft.com/developer/msbuild/2003">
    <ItemGroup>
        <Schema Include="sub1\**\*.xsd"/>
    </ItemGroup>

    <Target Name="Messages">
        <Message Text="rootdir: @(schema->'%(rootdir)')"/>
        <Message Text="fullpath: @(schema->'%(fullpath)')"/>
        <Message Text="rootdir + directory + filename + extension: @(schema->'%(rootdir)%(directory)%(filename)%(extension)')"/>
        <Message Text="identity: @(schema->'%(identity)')"/>
        <Message Text="filename: @(schema->'%(filename)')"/>
        <Message Text="directory: @(schema->'%(directory)')"/>
        <Message Text="relativedir: @(schema->'%(relativedir)')"/>
        <Message Text="extension: @(schema->'%(extension)')"/>
    </Target>
</Project>

Comentarios

Este ejemplo produce el siguiente resultado.

rootdir: C:\

fullpath: C:\xmake\sub1\sub2\sub3\myfile.xsd

rootdir + directory + filename + extension: C:\xmake\sub1\sub2\sub3\myfile.xsd

identity: sub1\sub2\sub3\myfile.xsd

filename: myfile

directory: xmake\sub1\sub2\sub3\

relativedir: sub1\sub2\sub3\

extension: .xsd

Vea también

Tareas

Cómo: Generar versiones incrementalmente

Otros recursos

Conceptos de MSBuild

Referencia de MSBuild