Nota:
El acceso a esta página requiere autorización. Puede intentar iniciar sesión o cambiar directorios.
El acceso a esta página requiere autorización. Puede intentar cambiar los directorios.
Las propiedades y elementos de MSBuild se usan para pasar información a tareas, evaluar condiciones y almacenar valores a los que se puede hacer referencia en todo el archivo del proyecto.
Las propiedades son pares nombre-valor. Para obtener más información, consulte las propiedades de MSBuild .
Los elementos son objetos que normalmente representan archivos. Los objetos item pueden tener colecciones de metadatos asociadas. Los metadatos son pares nombre-valor. Para obtener más información, consulte Elementos.
Escalares y vectores
Dado que las propiedades de MSBuild son pares de nombre-valor que tienen solo un valor de cadena, a menudo se describen como escalares. Dado que los tipos de elementos de MSBuild son listas de elementos, a menudo se describen como vector. Sin embargo, en la práctica, las propiedades pueden representar varios valores y los tipos de elemento pueden tener cero o un elemento.
Inserción de dependencias de destino
Para ver cómo las propiedades pueden representar varios valores, considere un patrón de uso común para agregar un destino a una lista de destinos que se van a compilar. Normalmente, esta lista se representa mediante un valor de propiedad, con los nombres de destino separados por punto y coma.
<PropertyGroup>
<BuildDependsOn>
BeforeBuild;
CoreBuild;
AfterBuild
</BuildDependsOn>
</PropertyGroup>
La BuildDependsOn propiedad se usa normalmente como argumento de un atributo de destino DependsOnTargets , convirtiéndola de forma eficaz en una lista de elementos. Esta propiedad se puede invalidar para agregar un destino o cambiar el orden de ejecución de destino. Por ejemplo
<PropertyGroup>
<BuildDependsOn>
$(BuildDependsOn);
CustomBuild;
</BuildDependsOn>
</PropertyGroup>
agrega el destino CustomBuild a la lista de destino, lo que proporciona BuildDependsOn el valor BeforeBuild;CoreBuild;AfterBuild;CustomBuild.
A partir de MSBuild 4.0, la inserción de dependencias de destino está en desuso. Use los AfterTargets atributos y BeforeTargets en su lugar. Para obtener más información, consulte Orden de compilación de destino.
Conversiones entre cadenas y listas de elementos
MSBuild realiza conversiones hacia y desde tipos de elemento y valores de cadena según sea necesario. Para ver cómo una lista de elementos puede convertirse en un valor de cadena, tenga en cuenta lo que ocurre cuando se usa un tipo de elemento como valor de una propiedad de MSBuild:
<ItemGroup>
<OutputDir Include="KeyFiles\;Certificates\" />
</ItemGroup>
<PropertyGroup>
<OutputDirList>@(OutputDir)</OutputDirList>
</PropertyGroup>
El tipo de elemento OutputDir tiene un Include atributo con el valor "KeyFiles\; Certificados\". MSBuild analiza esta cadena en dos elementos: KeyFiles\ y Certificates\. Cuando el tipo de elemento OutputDir se usa como valor de la propiedad OutputDirList, MSBuild convierte o "aplana" el tipo de elemento en la cadena separada por punto y coma "KeyFiles\; Certificados\".
Propiedades y elementos en tareas
Las propiedades y los elementos se usan como entradas y salidas para las tareas de MSBuild. Para obtener más información, vea Tasks.
Las propiedades se pasan a tareas como atributos. Dentro de la tarea, una propiedad de MSBuild se representa mediante un tipo de propiedad cuyo valor se puede convertir a y desde una cadena. Los tipos de propiedad admitidos incluyen bool, char, DateTime, DecimalDouble, int, , stringy cualquier tipo que ChangeType pueda controlar.
Los elementos se pasan a tareas como ITaskItem objetos . Dentro de la tarea, ItemSpec representa el valor del elemento y GetMetadata recupera sus metadatos.
La lista de elementos de un tipo de elemento se puede pasar como una matriz de ITaskItem objetos. A partir de .NET Framework 3.5, los elementos se pueden quitar de una lista de elementos de un destino mediante el Remove atributo . Dado que los elementos se pueden quitar de una lista de elementos, es posible que un tipo de elemento tenga cero elementos. Si se pasa una lista de elementos a una tarea, el código de la tarea debe comprobar esta posibilidad.
Orden de evaluación de propiedades y elementos
Durante la fase de evaluación de una compilación, los archivos importados se incorporan a la compilación en el orden en que aparecen. Las propiedades y los elementos se definen en tres pasos en el orden siguiente:
Las propiedades se definen y modifican en el orden en que aparecen.
Las definiciones de elementos se definen y modifican en el orden en que aparecen.
Los elementos se definen y modifican en el orden en que aparecen.
Durante la fase de ejecución de una compilación, las propiedades y los elementos definidos dentro de los destinos se evalúan conjuntamente en una sola fase en el orden en que aparecen.
Sin embargo, esta no es la historia completa. Cuando se define una propiedad, definición de elemento o elemento, se evalúa su valor. El evaluador de expresiones expande la cadena que especifica el valor. La expansión de cadena depende de la fase de compilación. Este es un orden de evaluación de propiedades y elementos más detallado:
Durante la fase de evaluación de una compilación:
Las propiedades se definen y modifican en el orden en que aparecen. Las funciones de propiedad se ejecutan. Los valores de propiedad con el formato $(PropertyName) se expanden dentro de expresiones. El valor de la propiedad se establece en la expresión expandida.
Las definiciones de elementos se definen y modifican en el orden en que aparecen. Las funciones de propiedad ya se han expandido dentro de expresiones. Los valores de metadatos se establecen en las expresiones expandidas.
Los tipos de elemento se definen y modifican en el orden en que aparecen. Los valores de elemento con el formato @(ItemType) se expanden. Las transformaciones de elementos también se expanden. Las funciones de propiedad y los valores ya se han expandido dentro de expresiones. Los valores de lista de elementos y metadatos se establecen en las expresiones expandidas.
Durante la fase de ejecución de una compilación:
- Las propiedades y los elementos definidos dentro de los destinos se evalúan conjuntamente en el orden en que aparecen. Las funciones de propiedad se ejecutan y los valores de propiedad se expanden dentro de expresiones. Los valores de elemento y las transformaciones de elementos también se expanden. Los valores de propiedad, los valores de tipo de elemento y los valores de metadatos se establecen en las expresiones expandidas.
Efectos sutiles del orden de evaluación
En la fase de evaluación de una compilación, la evaluación de propiedades precede a la evaluación de elementos. Sin embargo, las propiedades pueden tener valores que parecen depender de los valores de elemento. Tenga en cuenta el siguiente guion.
<ItemGroup>
<KeyFile Include="KeyFile.cs">
<Version>1.0.0.3</Version>
</KeyFile>
</ItemGroup>
<PropertyGroup>
<KeyFileVersion>@(KeyFile->'%(Version)')</KeyFileVersion>
</PropertyGroup>
<Target Name="AfterBuild">
<Message Text="KeyFileVersion: $(KeyFileVersion)" />
</Target>
Al ejecutar la tarea Mensaje se muestra este mensaje:
KeyFileVersion: 1.0.0.3
Esto se debe a que el valor de KeyFileVersion es realmente la cadena "@(KeyFile->'%(Versión)')". Las transformaciones de elemento y elemento no se expandieron cuando se definió la propiedad por primera vez, por lo que a la KeyFileVersion propiedad se le asignó el valor de la cadena no expandida.
Durante la fase de ejecución de la compilación, cuando procesa la tarea Message, MSBuild expande la cadena "@(KeyFile->'%(Version)')" para producir "1.0.0.3".
Observe que el mismo mensaje aparecería incluso si los grupos de propiedades y elementos se invertiran en orden.
Como segundo ejemplo, tenga en cuenta lo que puede ocurrir cuando los grupos de propiedades y elementos se encuentran dentro de los destinos:
<Target Name="AfterBuild">
<PropertyGroup>
<KeyFileVersion>@(KeyFile->'%(Version)')</KeyFileVersion>
</PropertyGroup>
<ItemGroup>
<KeyFile Include="KeyFile.cs">
<Version>1.0.0.3</Version>
</KeyFile>
</ItemGroup>
<Message Text="KeyFileVersion: $(KeyFileVersion)" />
</Target>
La tarea Mensaje muestra este mensaje:
KeyFileVersion:
Esto se debe a que durante la fase de ejecución de la compilación, los grupos de propiedades y elementos definidos dentro de los destinos se evalúan de arriba abajo al mismo tiempo. Cuando KeyFileVersion se define, KeyFile se desconoce. Por lo tanto, la transformación de elemento se expande a una cadena vacía.
En este caso, revertir el orden de los grupos de propiedades y elementos restaura el mensaje original:
<Target Name="AfterBuild">
<ItemGroup>
<KeyFile Include="KeyFile.cs">
<Version>1.0.0.3</Version>
</KeyFile>
</ItemGroup>
<PropertyGroup>
<KeyFileVersion>@(KeyFile->'%(Version)')</KeyFileVersion>
</PropertyGroup>
<Message Text="KeyFileVersion: $(KeyFileVersion)" />
</Target>
El valor de KeyFileVersion se establece en "1.0.0.3" y no en "@(KeyFile->'%(Versión)')". La tarea Mensaje muestra este mensaje:
KeyFileVersion: 1.0.0.3