Referencia de MSBuild para proyectos del SDK de .NET

Esta página es una referencia de las propiedades y los elementos de MSBuild que puede usar para configurar proyectos de .NET.

Nota:

Esta página es un trabajo en curso y no muestra todas las propiedades de MSBuild útiles para el SDK de .NET. Para obtener una lista de las propiedades comunes de MSBuild, vea Propiedades comunes de MSBuild.

Propiedades del marco de trabajo

En esta sección se documentan las siguientes propiedades de MSBuild:

TargetFramework

La propiedad TargetFramework especifica la versión de la plataforma de destino de la aplicación. Para obtener una lista de los monikers de plataforma de destino válidos, vea Plataformas de destino en proyectos de estilo SDK.

<PropertyGroup>
  <TargetFramework>netcoreapp3.1</TargetFramework>
</PropertyGroup>

Para obtener más información, vea Plataformas de destino en proyectos de estilo SDK.

TargetFrameworks

Use la propiedad TargetFrameworks cuando quiera que la aplicación tenga varias plataformas como destino. Para obtener una lista de los monikers de plataforma de destino válidos, vea Plataformas de destino en proyectos de estilo SDK.

Nota:

Esta propiedad se omite si se especifica TargetFramework (singular).

<PropertyGroup>
  <TargetFrameworks>netcoreapp3.1;net462</TargetFrameworks>
</PropertyGroup>

Para obtener más información, vea Plataformas de destino en proyectos de estilo SDK.

NetStandardImplicitPackageVersion

Nota:

Esta propiedad solo se aplica a los proyectos que usan netstandard1.x. No se aplica a los que usan netstandard2.x.

Use la propiedad NetStandardImplicitPackageVersion si quiere especificar una versión del marco que sea inferior a la de la versión del metapaquete. El archivo del proyecto del ejemplo siguiente tiene como destino netstandard1.3 pero usa la versión 1.6.0 de NETStandard.Library.

<PropertyGroup>
  <TargetFramework>netstandard1.3</TargetFramework>
  <NetStandardImplicitPackageVersion>1.6.0</NetStandardImplicitPackageVersion>
</PropertyGroup>

Propiedades de atributo de ensamblado

GenerateAssemblyInfo

La propiedad GenerateAssemblyInfo controla la generación del atributo AssemblyInfo del proyecto. El valor predeterminado es true. Use false para deshabilitar la generación del archivo:

<PropertyGroup>
  <GenerateAssemblyInfo>false</GenerateAssemblyInfo>
</PropertyGroup>

El valor de configuración GeneratedAssemblyInfoFile controla el nombre del archivo generado.

Si el valor GenerateAssemblyInfo es true, las propiedades del proyecto relacionadas con el paquete se transforman en atributos de ensamblado. En la siguiente tabla se enumeran las propiedades del proyecto que generan los atributos. También se enumeran las propiedades que puede usar para deshabilitar esa generación por atributo, por ejemplo:

<PropertyGroup>
  <GenerateNeutralResourcesLanguageAttribute>false</GenerateNeutralResourcesLanguageAttribute>
</PropertyGroup>
Propiedad de MSBuild Atributo de ensamblado Propiedad para deshabilitar la generación de atributos
Company AssemblyCompanyAttribute GenerateAssemblyCompanyAttribute
Configuration AssemblyConfigurationAttribute GenerateAssemblyConfigurationAttribute
Copyright AssemblyCopyrightAttribute GenerateAssemblyCopyrightAttribute
Description AssemblyDescriptionAttribute GenerateAssemblyDescriptionAttribute
FileVersion AssemblyFileVersionAttribute GenerateAssemblyFileVersionAttribute
InformationalVersion AssemblyInformationalVersionAttribute GenerateAssemblyInformationalVersionAttribute
Product AssemblyProductAttribute GenerateAssemblyProductAttribute
AssemblyTitle AssemblyTitleAttribute GenerateAssemblyTitleAttribute
AssemblyVersion AssemblyVersionAttribute GenerateAssemblyVersionAttribute
NeutralLanguage NeutralResourcesLanguageAttribute GenerateNeutralResourcesLanguageAttribute

Notas sobre dichos valores de configuración:

  • AssemblyVersion y FileVersion tienen como valor predeterminado el valor de $(Version) sin el sufijo. Por ejemplo, si $(Version) es 1.2.3-beta.4, entonces el valor sería 1.2.3.
  • El valor predeterminado de InformationalVersion es el de $(Version).
  • Si la propiedad $(SourceRevisionId) está presente, se anexa a InformationalVersion. Puede deshabilitar este comportamiento mediante IncludeSourceRevisionInInformationalVersion.
  • Las propiedades Copyright y Description también se utilizan para metadatos de NuGet.
  • Configuration, que tiene Debug como valor predeterminado, se comparte con todos los destinos de MSBuild. Se puede establecer con la opción --configuration de los comandos dotnet; por ejemplo, dotnet pack.
  • Algunas de las propiedades se usan al crear un paquete NuGet. Para obtener más información, consulte Propiedades del paquete.

Migración de .NET Framework

Las plantillas de proyectos de .NET Framework crean un archivo de código con estos atributos de información de ensamblado definidos. Normalmente, el archivo se encuentra en .\Properties\AssemblyInfo.cs o .\Properties\AssemblyInfo.vb. Los proyectos de estilo SDK generan este archivo para el usuario de acuerdo con la configuración del proyecto. No es posible tener ambas cosas. Al portar el código a .NET 5 (o .NET Core 3.1) o versiones posteriores, siga uno de estos pasos:

  • Deshabilite la generación del archivo de código temporal que contiene los tributos de información de ensamblado. Para ello, establezca GenerateAssemblyInfo en false en el archivo del proyecto. Esto le permite conservar el archivo AssemblyInfo.
  • Migre la configuración del archivo AssemblyInfo al archivo del proyecto y elimine el archivo AssemblyInfo.

GeneratedAssemblyInfoFile

La propiedad GeneratedAssemblyInfoFile define la ruta de acceso relativa o completa del archivo de información de ensamblado generado. Tiene un archivo denominado [nombre-proyecto].AssemblyInfo.[cs|vb] en el directorio $(IntermediateOutputPath) (normalmente, obj) como valor predeterminado.

<PropertyGroup>
  <GeneratedAssemblyInfoFile>assemblyinfo.cs</GeneratedAssemblyInfoFile>
</PropertyGroup>

Propiedades del paquete

Puede especificar propiedades como PackageId, PackageVersion, PackageIcon, Title y Description para describir el paquete que se crea a partir del proyecto. Para más información sobre estas y otras propiedades, vea Destino de pack.

<PropertyGroup>
  ...
  <PackageId>ClassLibDotNetStandard</PackageId>
  <Version>1.0.0</Version>
  <Authors>John Doe</Authors>
  <Company>Contoso</Company>
</PropertyGroup>

PackRelease

La PackRelease propiedad es similar a la propiedad PublishRelease , salvo que cambia el comportamiento predeterminado de dotnet pack.

<PropertyGroup>
  <PackRelease>true</PackRelease>
</PropertyGroup>

En esta sección se documentan las siguientes propiedades de MSBuild:

AppendTargetFrameworkToOutputPath

La propiedad AppendTargetFrameworkToOutputPath controla si el moniker de la plataforma de destino (TFM) se anexa a la ruta de salida (definida por OutputPath). El SDK de .NET anexa automáticamente el marco de destino (y, si está disponible, también el id. del entorno de ejecución) a la ruta de salida. El hecho de establecer AppendTargetFrameworkToOutputPath en false impide que el TFM se anexe a la ruta de salida. Sin embargo, sin el TFM en la ruta de salida, es posible que varios artefactos de compilación se sobrescriban entre sí.

Por ejemplo, en el caso de una aplicación de .NET 5, la ruta de salida cambia de bin\Debug\net5.0 a bin\Debug con la opción de configuración siguiente:

<PropertyGroup>
  <AppendTargetFrameworkToOutputPath>false</AppendTargetFrameworkToOutputPath>
</PropertyGroup>

AppendRuntimeIdentifierToOutputPath

La propiedad AppendRuntimeIdentifierToOutputPath controla si el id. del entorno de ejecución (RID) se anexa a la ruta de salida. El SDK de .NET anexa automáticamente el marco de destino (y, si está disponible, también el id. del entorno de ejecución) a la ruta de salida. El hecho de establecer AppendRuntimeIdentifierToOutputPath en false impide que el RID se anexe a la ruta de salida.

Por ejemplo, en el caso de una aplicación de .NET 5 y un RID de win10-x64, la ruta de salida cambia de bin\Debug\net5.0\win10-x64 a bin\Debug\net5.0 con la opción de configuración siguiente:

<PropertyGroup>
  <AppendRuntimeIdentifierToOutputPath>false</AppendRuntimeIdentifierToOutputPath>
</PropertyGroup>

CopyLocalLockFileAssemblies

La propiedad CopyLocalLockFileAssemblies es útil para los proyectos de complementos que tienen dependencias de otras bibliotecas. Si establece esta propiedad en true, todas las dependencias de paquetes NuGet se copian en el directorio de salida. Esto significa que puede usar la salida de dotnet build para ejecutar el complemento en cualquier equipo.

<PropertyGroup>
  <CopyLocalLockFileAssemblies>true</CopyLocalLockFileAssemblies>
</PropertyGroup>

Sugerencia

Como alternativa, puede usar dotnet publish para publicar la biblioteca de clases. Para obtener más información, vea dotnet publish.

ErrorOnDuplicatePublishOutputFiles

La propiedad ErrorOnDuplicatePublishOutputFiles está relacionada con si el SDK genera el error NETSDK1148 cuando MSBuild detecta archivos duplicados en la salida de la publicación, pero no puede determinar qué archivos se van a quitar. Establezca la propiedad ErrorOnDuplicatePublishOutputFiles en false si no quiere que se genere el error.

<PropertyGroup>
  <ErrorOnDuplicatePublishOutputFiles>false</ErrorOnDuplicatePublishOutputFiles>
</PropertyGroup>

Esta propiedad se ha introducido en .NET 6.

EnablePackageValidation

La propiedad EnablePackageValidation permite una serie de validaciones en el paquete después de la tarea pack. Para más información, consulte Validación de paquetes.

<PropertyGroup>
  <EnablePackageValidation>true</EnablePackageValidation>
</PropertyGroup>

Esta propiedad se ha introducido en .NET 6.

GenerateRuntimeConfigDevFile

A partir del SDK de .NET 6, el archivo [Appname].runtimesettings.dev.jsonya no se genera de forma predeterminada en tiempo de compilación. Si desea que se genere este archivo, establezca la GenerateRuntimeConfigDevFile propiedad trueen .

<PropertyGroup>
  <GenerateRuntimeConfigDevFile>true</GenerateRuntimeConfigDevFile>
</PropertyGroup>

GenerateRuntimeConfigurationFiles

La propiedad GenerateRuntimeConfigurationFiles controla si las opciones de configuración del entorno de ejecución se copian del archivo runtimeconfig.template.json al archivo [appname].runtimeconfig.json. Para las aplicaciones en las que se necesita un archivo runtimeconfig.json, esto es, aquellas cuyo valor de OutputType es Exe, esta propiedad tiene true como valor predeterminado.

<PropertyGroup>
  <GenerateRuntimeConfigurationFiles>true</GenerateRuntimeConfigurationFiles>
</PropertyGroup>

GenerateSatelliteAssembliesForCore

La GenerateSatelliteAssembliesForCore propiedad controla si se generan ensamblados satélite mediante csc.exe o Al.exe (Assembly Linker) en proyectos de .NET Framework. (Los proyectos de .NET Core y .NET 5+ siempre usan csc.exe para generar ensamblados satélite). En el caso de los proyectos de .NET Framework, los ensamblados satélite se crean medianteal.exe, de forma predeterminada. Al establecer la GenerateSatelliteAssembliesForCore propiedad trueen , los ensamblados satélite se crean mediantecsc.exe en su lugar. El uso decsc.exe puede ser ventajoso en las situaciones siguientes:

<PropertyGroup>
  <GenerateSatelliteAssembliesForCore>true</GenerateSatelliteAssembliesForCore>
</PropertyGroup>

IsPublishable

La propiedad IsPublishable permite ejecutar el destino Publish. Esta propiedad solo afecta a los procesos que usan archivos .*proj y el Publish destino, como el comando dotnet publish . No afecta a la publicación en Visual Studio, que usa el destino PublishOnly. El valor predeterminado es true.

Esta propiedad es útil si se ejecuta dotnet publish en un archivo de solución, ya que permite la selección automática de los proyectos que deben publicarse.

<PropertyGroup>
  <IsPublishable>false</IsPublishable>
</PropertyGroup>

PreserveCompilationContext

La propiedad PreserveCompilationContext permite a una aplicación creada o publicada compilar más código en tiempo de ejecución con la misma configuración que se utilizó en el momento de la creación. Los ensamblados a los que se hace referencia en el tiempo de compilación se copiarán en el subdirectorio ref del directorio de salida. Los nombres de los ensamblados de referencia se almacenan en el archivo .deps.json de la aplicación junto con las opciones que se pasan al compilador. Puede recuperar esta información mediante las propiedades DependencyContext.CompileLibraries y DependencyContext.CompilationOptions.

Esta funcionalidad la usan principalmente MVC de ASP.NET Core y páginas Razor para admitir la compilación en tiempo de ejecución de archivos Razor.

<PropertyGroup>
  <PreserveCompilationContext>true</PreserveCompilationContext>
</PropertyGroup>

PreserveCompilationReferences

La propiedad PreserveCompilationReferences es similar a la propiedad PreserveCompilationContext, salvo que solo copia los ensamblados a los que se hace referencia en el directorio de publicación, sin el archivo .deps.json.

<PropertyGroup>
  <PreserveCompilationReferences>true</PreserveCompilationReferences>
</PropertyGroup>

Para obtener más información, consulte las propiedades del SDK de Razor.

ProduceReferenceAssemblyInOutDir

En .NET 5 y versiones anteriores, los ensamblados de referencia siempre se escriben en el OutDir directorio . En .NET 6 y versiones posteriores, puede usar la ProduceReferenceAssemblyInOutDir propiedad para controlar si los ensamblados de referencia se escriben en el OutDir directorio. El valor predeterminado es falsey los ensamblados de referencia solo se escriben en el IntermediateOutputPath directorio . Establezca el valor true en para escribir ensamblados de referencia en el OutDir directorio .

<PropertyGroup>
  <ProduceReferenceAssemblyInOutDir>true</ProduceReferenceAssemblyInOutDir>
</PropertyGroup>

Para obtener más información, consulte Escritura de ensamblados de referencia en la salida intermedia.

PublishRelease

La PublishRelease propiedad informa dotnet publish para aprovechar la Release configuración en lugar de la Debug configuración. Se recomienda agregar esta propiedad a un Directory.Build.props archivo en lugar de a un archivo de proyecto para que se evalúe lo suficientemente pronto como para que el cambio de configuración se propague.

<PropertyGroup>
  <PublishRelease>true</PublishRelease>
</PropertyGroup>

Nota:

Esta propiedad no afecta al comportamiento de dotnet build /t:Publish.

RollForward

La propiedad RollForward controla cómo elige la aplicación un entorno de ejecución cuando hay varias versiones disponibles. Este valor se representa en .runtimeconfig.json como el valor rollForward.

<PropertyGroup>
  <RollForward>LatestMinor</RollForward>
</PropertyGroup>

Establezca RollForward en uno de los valores siguientes:

Value Descripción
Minor Default si no se especifica.
Puesta al día con la versión secundaria mínima superior, si no se encuentra la versión secundaria solicitada. Si se encuentra la versión secundaria solicitada, se usa la directiva LatestPatch.
Major Puesta al día con la siguiente versión principal superior disponible, y con la versión secundaria mínima si no se encuentra la versión principal solicitada. Si se encuentra la versión principal solicitada, se usa la directiva Minor.
LatestPatch Puesta al día con la versión de revisión más alta. Este valor deshabilita la puesta al día de versiones secundarias.
LatestMinor Puesta al día con la versión secundaria más alta, aunque la versión secundaria solicitada esté presente.
LatestMajor Puesta al día con la última versión principal y la última versión secundaria, aunque la versión principal solicitada esté presente.
Disable No se realiza la puesta al día, solo se enlaza a la versión especificada. No se recomienda esta directiva para uso general, ya que deshabilita la capacidad de puesta al día con las revisiones más recientes. Este valor solo se recomienda a efectos de pruebas.

Para obtener más información, vea Control del comportamiento de la puesta al día.

RuntimeFrameworkVersion

La propiedad RuntimeFrameworkVersion especifica la versión del entorno de ejecución que se usará al realizar la publicación. Especifique una versión del entorno de ejecución:

<PropertyGroup>
  <RuntimeFrameworkVersion>5.0.7</RuntimeFrameworkVersion>
</PropertyGroup>

Al publicar una aplicación dependiente del marco, este valor especifica la versión mínima necesaria. Al publicar una aplicación independiente, este valor especifica la versión exacta necesaria.

RuntimeIdentifier

La propiedad RuntimeIdentifier permite especificar un único identificador de tiempo de ejecución (RID) para el proyecto. El RID permite publicar una implementación autocontenida.

<PropertyGroup>
  <RuntimeIdentifier>ubuntu.16.04-x64</RuntimeIdentifier>
</PropertyGroup>

RuntimeIdentifiers

La propiedad RuntimeIdentifiers permite especificar una lista delimitada por puntos y coma de identificadores de tiempo ejecución (RID) para el proyecto. Use esta propiedad si tiene que publicar para varios entornos de ejecución. RuntimeIdentifiers se usa en el momento de la restauración para asegurarse de que los recursos adecuados están en el gráfico.

Sugerencia

RuntimeIdentifier (singular) puede proporcionar compilaciones más rápidas cuando solo se requiere un entorno de ejecución.

<PropertyGroup>
  <RuntimeIdentifiers>win10-x64;osx.10.11-x64;ubuntu.16.04-x64</RuntimeIdentifiers>
</PropertyGroup>

SatelliteResourceLanguages

La propiedad SatelliteResourceLanguages permite especificar los lenguajes para los que desea conservar los ensamblados de recursos satélite durante la compilación y publicación. Muchos paquetes NuGet incluyen ensamblados satélite de recursos localizados en el paquete principal. En el caso de los proyectos que hacen referencia a estos paquetes NuGet que no requieren recursos localizados, los ensamblados localizados pueden inflar innecesariamente el tamaño de la compilación y la publicación. Al agregar la propiedad SatelliteResourceLanguages al archivo del proyecto, solo se incluirán en la salida de compilación y publicación los ensamblados localizados para los lenguajes especificados. Por ejemplo, en el siguiente archivo del proyecto, solo se conservarán los ensamblados satélite de recursos en inglés (EE. UU.).

<PropertyGroup>
  <SatelliteResourceLanguages>en-US</SatelliteResourceLanguages>
</PropertyGroup>

Nota:

Debe especificar esta propiedad en el proyecto que hace referencia al paquete NuGet con ensamblados satélite de recursos localizados.

UseAppHost

La propiedad UseAppHost controla si se crea o no un archivo ejecutable nativo para una implementación. Un archivo ejecutable nativo es obligatorio para las implementaciones independientes.

En .NET Core 3.0 y versiones posteriores, se crea de forma predeterminada un ejecutable dependiente del marco de trabajo. Establezca la propiedad UseAppHost en false para deshabilitar la generación del archivo ejecutable.

<PropertyGroup>
  <UseAppHost>false</UseAppHost>
</PropertyGroup>

Para más información sobre la implementación, consulte Implementación de aplicaciones .NET.

Hay numerosas propiedades MSBuild disponibles para ajustar el recorte, que es una característica que recorta el código sin usar de las implementaciones independientes. Estas opciones se describen en detalle en Opciones de recorte. En la tabla siguiente se proporciona una referencia rápida.

Propiedad Valores Descripción
PublishTrimmed true o false Controla si el recorte está habilitado durante la publicación.
TrimMode link o copyused Controla la granularidad de recorte. Esta propiedad se puede establecer globalmente para el proyecto o en el nivel de ensamblado como metadatos.
SuppressTrimAnalysisWarnings true o false Controla si se generan advertencias de análisis de recorte.
EnableTrimAnalyzer true o false Controla si se genera un subconjunto de advertencias de análisis de recorte. Puede habilitar el análisis aunque PublishTrimmed esté establecido en false.
ILLinkWarningLevel 5-9999, preview, o latest Controla la versión de advertencias de análisis de recorte.
ILLinkTreatWarningsAsErrors true o false Controla si las advertencias de recorte se tratan como errores. Por ejemplo, puede que desee establecer esta propiedad false en cuando TreatWarningsAsErrors se establece en true.
TrimmerSingleWarn true o false Controla si se muestra una sola advertencia por ensamblado o todas las advertencias.
TrimmerRemoveSymbols true o false Controla si todos los símbolos se quitan de una aplicación recortada.

En esta sección se documentan las siguientes propiedades de MSBuild:

Las opciones del compilador de C# (como LangVersion y Nullable) también se pueden especificar como propiedades de MSBuild en el archivo del proyecto. Para obtener más información, vea Opciones del compilador de C#.

DisableImplicitFrameworkDefines

La DisableImplicitFrameworkDefines propiedad controla si el SDK genera símbolos de preprocesador para el marco de destino y la plataforma para el proyecto de .NET. Cuando esta propiedad se establece en o no está establecida false (que es el valor predeterminado) se generan símbolos de preprocesador para:

  • Framework sin versión (NETFRAMEWORK, NETSTANDARD, NET)
  • Marco con versión (NET48, NETSTANDARD2_0, NET6_0)
  • Marco con límite mínimo de versión (NET48_OR_GREATER, NETSTANDARD2_0_OR_GREATER, NET6_0_OR_GREATER)

Para obtener más información sobre los monikers de plataforma de destino y estos símbolos de preprocesador implícitos, consulte Marcos de destino.

Además, si especifica un marco de destino específico del sistema operativo en el proyecto (por ejemplo net6.0-android), se generan los siguientes símbolos de preprocesador:

  • Plataforma sin versión (ANDROID, IOS, WINDOWS)
  • Plataforma con versión (IOS15_1)
  • Plataforma con límite mínimo de versión (IOS15_1_OR_GREATER)

Para obtener más información sobre los monikers de plataforma de destino específicos del sistema operativo, consulte TFMs específicos del sistema operativo.

Por último, si la plataforma de destino implica compatibilidad con plataformas de destino anteriores, se emiten símbolos de preprocesador para esas plataformas anteriores. Por ejemplo, net6.0implica la compatibilidad con net5.0 y así sucesivamente de vuelta a .netcoreapp1.0. Por lo tanto, para cada una de estas plataformas de destino, se definirá el símbolo de marco con límite mínimo de versión .

DocumentationFile

La propiedad DocumentationFile permite especificar un nombre de archivo para el archivo XML que contiene la documentación de la biblioteca. Para que IntelliSense funcione correctamente con la documentación, el nombre de archivo debe ser el mismo que el nombre del ensamblado y debe estar en el mismo directorio que este. Si no especifica esta propiedad pero establece GenerateDocumentationFile en true, el nombre del archivo de documentación tiene como valor predeterminado el nombre del ensamblado, pero con una extensión de archivo .xml. Por este motivo, suele ser más fácil omitir esta propiedad y usar en su lugar la propiedad GenerateDocumentationFile.

Si no especifica esta propiedad pero establece GenerateDocumentationFile en false, el compilador no genera un archivo de documento. Si no especifica esta propiedad y omite la propiedad GenerateDocumentationFile, el compilador genera un archivo de documentación.

<PropertyGroup>
  <DocumentationFile>path/to/file.xml</DocumentationFile>
</PropertyGroup>

EmbeddedResourceUseDependentUponConvention

La propiedad EmbeddedResourceUseDependentUponConvention define si los nombres del archivo de manifiesto del recurso se generan a partir de la información de tipo de los archivos de código fuente que se ubican conjuntamente con archivos de recursos. Por ejemplo, si Form1.resx está en la misma carpera que Form1.cs, y EmbeddedResourceUseDependentUponConvention se establece en true, el archivo .resources generado toma su nombre del primer tipo que se define en Form1.cs. Por ejemplo, si MyNamespace.Form1 es el primer tipo definido en Form1.cs, el nombre de archivo generado es myNameSpace.Form1.Resources.

Nota:

Si se especifican los metadatos LogicalName, ManifestResourceName o DependentUpon para un elemento EmbeddedResource, el nombre del archivo de manifiesto generado para ese archivo de recurso se basa en esos metadatos.

De forma predeterminada, en un nuevo proyecto de .NET, esta propiedad se establece en true. Si se establece en false y no se especifica ningún metadato LogicalName, ManifestResourceName o DependentUpon para el elemento EmbeddedResource del archivo de proyecto, el nombre del archivo de manifiesto del recurso se basa en el espacio de nombres raíz del proyecto y en la ruta de acceso relativa al archivo .resx. Para más información, consulte Denominación de los archivos de manifiesto de recurso.

<PropertyGroup>
  <EmbeddedResourceUseDependentUponConvention>true</EmbeddedResourceUseDependentUponConvention>
</PropertyGroup>

EnablePreviewFeatures

La propiedad EnablePreviewFeatures define si el proyecto depende de las API o ensamblados que se decoran con el atributo RequiresPreviewFeaturesAttribute. Este atributo se utiliza para indicar que una API o un ensamblado utilizan características que se consideran en versión preliminar para la versión del SDK que se está utilizando. Las características en versión preliminar no se admiten y se pueden quitar en una versión futura. Para habilitar el uso de características en versión preliminar, establezca la propiedad en True.

<PropertyGroup>
  <EnablePreviewFeatures>True</EnablePreviewFeatures>
</PropertyGroup>

Cuando un proyecto contiene esta propiedad establecida en True, se agrega el siguiente atributo de nivel de ensamblado al archivo AssemblyInfo.cs:

[assembly: RequiresPreviewFeatures]

Un analizador advierte si este atributo está presente en las dependencias de los proyectos en los que EnablePreviewFeatures no está establecido en True.

Los autores de bibliotecas que pretenden enviar ensamblados de versión preliminar deben establecer esta propiedad en True. Si un ensamblado necesita enviarse con una mezcla de API que están en versión preliminar y otras que no lo están, consulte la sección GenerateRequiresPreviewFeaturesAttribute a continuación.

GenerateDocumentationFile

La propiedad GenerateDocumentationFile controla si el compilador genera un archivo de documentación XML para la biblioteca. Si establece esta propiedad en true y no especifica un nombre de archivo a través de la propiedad DocumentationFile, el archivo XML generado se coloca en el mismo directorio de salida que el ensamblado y tiene el mismo nombre de archivo (pero con una extensión .xml).

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>

Para más información sobre cómo generar documentación a partir de comentarios de código, consulte Comentarios de documentación XML (C#), Documentación del código con XML (Visual Basic) o Documentación del código con XML (F#).

GenerateRequiresPreviewFeaturesAttribute

La propiedad GenerateRequiresPreviewFeaturesAttribute está estrechamente relacionada con la propiedad EnablePreviewFeatures. Si su biblioteca utiliza características en versión preliminar pero no desea que todo el ensamblado se marque con el atributo RequiresPreviewFeaturesAttribute, lo que requeriría que cualquier consumidor habilitara las características en versión preliminar, establezca esta propiedad en False.

<PropertyGroup>
    <EnablePreviewFeatures>True</EnablePreviewFeatures>
    <GenerateRequiresPreviewFeaturesAttribute>False</GenerateRequiresPreviewFeaturesAttribute>
</PropertyGroup>

Importante

Si establece la propiedad GenerateRequiresPreviewFeaturesAttribute en False, debe estar seguro de decorar todas las API públicas que se basan en características en versión preliminar con RequiresPreviewFeaturesAttribute.

OptimizeImplicitlyTriggeredBuild

Para acelerar el tiempo de compilación, las compilaciones que se desencadenan implícitamente por Visual Studio omiten el análisis de código, incluyendo el análisis que admite un valor NULL. Visual Studio desencadena una compilación implícita al ejecutar pruebas, por ejemplo. Sin embargo, las compilaciones implícitas solo se optimizan cuando TreatWarningsAsErrors no es true. Si ha establecido TreatWarningsAsErrors en true pero todavía desea optimizar las compilaciones desencadenadas implícitamente, puede establecer OptimizeImplicitlyTriggeredBuild en True. Para desactivar la optimización de compilación para compilaciones desencadenadas implícitamente, establezca OptimizeImplicitlyTriggeredBuild en False.

<PropertyGroup>
    <OptimizeImplicitlyTriggeredBuild>True</OptimizeImplicitlyTriggeredBuild>
</PropertyGroup>

Propiedades de inclusión de elementos predeterminados

En esta sección se documentan las siguientes propiedades de MSBuild:

Para obtener más información, consulte Inclusiones y exclusiones predeterminadas.

DefaultItemExcludes

Use la propiedad DefaultItemExcludes para definir patrones globales para archivos y carpetas que deban excluirse de los patrones globales de inclusión, exclusión y eliminación. De forma predeterminada, las carpetas ./bin y ./obj se excluyen de los patrones globales.

<PropertyGroup>
  <DefaultItemExcludes>$(DefaultItemExcludes);**/*.myextension</DefaultItemExcludes>
</PropertyGroup>

DefaultExcludesInProjectFolder

Use la propiedad DefaultExcludesInProjectFolder para definir patrones globales para archivos y carpetas de la carpeta del proyecto que deban excluirse de los patrones globales de inclusión, exclusión y eliminación. De forma predeterminada, las carpetas que empiezan por un punto (.), como .git y .vs, se excluyen de los patrones globales.

Esta propiedad es muy similar a otra, DefaultItemExcludes, salvo por el hecho de que esta solo tiene en cuenta los archivos y las carpetas de la carpeta del proyecto. En el caso de que un patrón global pretenda, de forma no intencionada, relacionar elementos de fuera de la carpeta del proyecto con una ruta de acceso relativa, use la propiedad DefaultExcludesInProjectFolder, en lugar de DefaultItemExcludes.

<PropertyGroup>
  <DefaultExcludesInProjectFolder>$(DefaultExcludesInProjectFolder);**/myprefix*/**</DefaultExcludesInProjectFolder>
</PropertyGroup>

EnableDefaultItems

La propiedad EnableDefaultItems controla si los elementos de compilación, los elementos de los recursos incrustados y los elementos None se incluyen en el proyecto de forma implícita. El valor predeterminado es true. Establezca la propiedad EnableDefaultItems en false para deshabilitar toda inclusión de archivos implícita.

<PropertyGroup>
  <EnableDefaultItems>false</EnableDefaultItems>
</PropertyGroup>

EnableDefaultCompileItems

La propiedad EnableDefaultCompileItems controla si los elementos de compilación se incluyen en el proyecto de forma implícita. El valor predeterminado es true. Establezca la propiedad EnableDefaultCompileItems en false para deshabilitar la inclusión implícita de los archivos *.cs, así como la de otras extensiones de nombres de archivos.

<PropertyGroup>
  <EnableDefaultCompileItems>false</EnableDefaultCompileItems>
</PropertyGroup>

EnableDefaultEmbeddedResourceItems

La propiedad EnableDefaultEmbeddedResourceItems controla si los elementos de los recursos incrustados se incluyen en el proyecto de forma implícita. El valor predeterminado es true. Establezca la propiedad EnableDefaultEmbeddedResourceItems en false para deshabilitar la inclusión implícita de los archivos de los recursos incrustados.

<PropertyGroup>
  <EnableDefaultEmbeddedResourceItems>false</EnableDefaultEmbeddedResourceItems>
</PropertyGroup>

EnableDefaultNoneItems

La propiedad EnableDefaultNoneItems controla si los elementos None (archivos que no tienen ningún rol en el proceso de compilación) se incluyen implícitamente en el proyecto. El valor predeterminado es true. Establezca la propiedad EnableDefaultNoneItems en false para deshabilitar la inclusión implícita de elementos None.

<PropertyGroup>
  <EnableDefaultNoneItems>false</EnableDefaultNoneItems>
</PropertyGroup>

Propiedades de análisis de código

En esta sección se documentan las siguientes propiedades de MSBuild:

AnalysisLevel

La propiedad AnalysisLevel permite especificar un conjunto de analizadores de código para que se ejecuten según una versión de .NET. Cada versión de .NET, a partir de .NET 5, tiene un conjunto de reglas de análisis de código. De ese conjunto, las reglas que están habilitadas de forma predeterminada para esa versión serán las que analicen el código. Por ejemplo, si actualiza a .NET 6 pero no quiere que cambie el conjunto predeterminado de reglas de análisis de código, establezca AnalysisLevel en 5.

<PropertyGroup>
  <AnalysisLevel>preview</AnalysisLevel>
</PropertyGroup>

A partir de .NET 6, tiene la opción de especificar un valor compuesto para esta propiedad que también especifique la intensidad con la que se habilitan las reglas. Los valores compuestos adoptan el formato <version>-<mode>, donde el valor <mode> es uno de los valores de AnalysisMode. En el ejemplo siguiente se usa la versión preliminar de los analizadores de código y se habilita el conjunto de reglas recomendado.

<PropertyGroup>
  <AnalysisLevel>preview-recommended</AnalysisLevel>
</PropertyGroup>

Nota:

Si establece AnalysisLevel en 5-<mode> o 5.0-<mode> y, a continuación, instala el SDK de .NET 6 y vuelve a compilar el proyecto, puede que aparezcan nuevas advertencias de compilación inesperadas. Para obtener más información, consulte la incidencia 5679 de dotnet/roslyn-analyzers.

Valor predeterminado:

  • Si el proyecto tiene como destino .NET 5 o posterior, o si ha agregado la propiedad AnalysisMode, el valor predeterminado es latest.
  • De lo contrario, se omite esta propiedad, a menos que se agregue explícitamente al archivo de proyecto.

En la tabla siguiente se muestran los valores que puede especificar.

Valor Significado
latest Se usan los analizadores de código que se han publicado más recientemente. Este es el valor predeterminado.
latest-<mode> Se usan los analizadores de código que se han publicado más recientemente. El valor <mode> determina las reglas que están habilitadas.
preview Se usan los analizadores de código más recientes, incluso si están en versión preliminar.
preview-<mode> Se usan los analizadores de código más recientes, incluso si están en versión preliminar. El valor <mode> determina las reglas que están habilitadas.
6.0 Se usa el conjunto de reglas que estaba disponible para .NET 6, incluso si hay reglas más recientes disponibles.
6.0-<mode> Se usa el conjunto de reglas que estaba disponible para .NET 6, incluso si hay reglas más recientes disponibles. El valor <mode> determina las reglas que están habilitadas.
6 Se usa el conjunto de reglas que estaba disponible para .NET 6, incluso si hay reglas más recientes disponibles.
6-<mode> Se usa el conjunto de reglas que estaba disponible para .NET 6, incluso si hay reglas más recientes disponibles. El valor <mode> determina las reglas que están habilitadas.
5.0 Se usa el conjunto de reglas que estaba disponible para .NET 5, incluso si hay reglas más recientes disponibles.
5.0-<mode> Se usa el conjunto de reglas que estaba disponible para .NET 5, incluso si hay reglas más recientes disponibles. El valor <mode> determina las reglas que están habilitadas.
5 Se usa el conjunto de reglas que estaba disponible para .NET 5, incluso si hay reglas más recientes disponibles.
5-<mode> Se usa el conjunto de reglas que estaba disponible para .NET 5, incluso si hay reglas más recientes disponibles. El valor <mode> determina las reglas que están habilitadas.

Nota:

  • En .NET 5 y versiones anteriores, esta propiedad solo afecta a las reglas de calidad del código (CAXXXX). A partir de .NET 6, si establece EnforceCodeStyleInBuild en true, esta propiedad también afecta a las reglas de estilo de código (IDEXXXX).
  • Si establece un valor compuesto para AnalysisLevel, no es necesario especificar un valor de AnalysisMode. Sin embargo, si lo hace, AnalysisLevel tiene prioridad sobre AnalysisMode.
  • Esta propiedad no tiene ningún efecto en el análisis de código de los proyectos que no hacen referencia a un SDK de proyecto, por ejemplo, los proyectos de .NET Framework heredados que hacen referencia al paquete NuGet Microsoft.CodeAnalysis.NetAnalyzers.

Categoría AnalysisLevel<>

Esta propiedad, introducida en .NET 6, es igual que AnalysisLevel, salvo que solo se aplica a una categoría de reglas de análisis de código específica. Esta propiedad permite usar una versión distinta de los analizadores de código para una categoría específica o bien habilitar o deshabilitar reglas en un nivel diferente al de las otras categorías de reglas. Si omite esta propiedad para una categoría de reglas concreta, su valor predeterminado es AnalysisLevel. Los valores disponibles son los mismos que para AnalysisLevel.

<PropertyGroup>
  <AnalysisLevelSecurity>preview</AnalysisLevelSecurity>
</PropertyGroup>
<PropertyGroup>
  <AnalysisLevelSecurity>preview-recommended</AnalysisLevelSecurity>
</PropertyGroup>

En la tabla siguiente se muestra el nombre de propiedad de cada categoría de regla.

Nombre de la propiedad Categoría de regla
<AnalysisLevelDesign> Reglas de diseño
<AnalysisLevelDocumentation> Reglas de documentación
<AnalysisLevelGlobalization> Reglas de globalización
<AnalysisLevelInteroperability> Reglas de portabilidad e interoperabilidad
<AnalysisLevelMaintainability> Reglas de mantenimiento
<AnalysisLevelNaming> Reglas de nomenclatura
<AnalysisLevelPerformance> Reglas de rendimiento
<AnalysisLevelSingleFile> Reglas de aplicación de archivo único
<AnalysisLevelReliability> Reglas de confiabilidad
<AnalysisLevelSecurity> Reglas de seguridad
<AnalysisLevelStyle> Todas las reglas de estilo de código (IDEXXXX)
<AnalysisLevelUsage> Reglas de uso

AnalysisMode

A partir de .NET 5, el SDK de .NET incluye todas las reglas "CA" de calidad del código. De forma predeterminada, solo algunas reglas están habilitadas como advertencias de compilación en cada versión de .NET. La propiedad AnalysisMode le permite personalizar el conjunto de reglas que están habilitadas de forma predeterminada. Puede cambiar a un modo de análisis más agresivo en el que puede rechazar las reglas individualmente o a un modo de análisis más conservador en el que puede optar por reglas específicas. Por ejemplo, si quiere habilitar todas las reglas de forma predeterminada como advertencias de compilación, establezca el valor en All.

<PropertyGroup>
  <AnalysisMode>All</AnalysisMode>
</PropertyGroup>

En la tabla siguiente se muestran los valores de las opciones disponibles en .NET 5 y .NET 6. Se muestran en orden creciente del número de reglas que habilitan.

Valor de .NET 6+ Valor de .NET 5 Significado
None AllDisabledByDefault Todas las reglas están deshabilitadas. Puede incluir de forma selectiva reglas individuales para habilitarlas.
Default Default Modo predeterminado, en el que ciertas reglas están habilitadas como advertencias de compilación, otras están habilitadas como sugerencias del IDE de Visual Studio y el resto están deshabilitadas.
Minimum N/D Modo más agresivo que el modo Default. Algunas sugerencias que se recomiendan encarecidamente para el cumplimiento de la compilación se habilitan como advertencias de compilación.
Recommended N/D Modo más agresivo que el modo Minimum, donde se habilitan más reglas como advertencias de compilación.
All AllEnabledByDefault Todas las reglas están habilitadas como advertencias de compilación. Puede excluir de forma selectiva reglas individuales para deshabilitarlas.

Nota:

  • En .NET 5, esta propiedad solo afecta a las reglas de calidad del código (CAXXXX). A partir de .NET 6, si establece EnforceCodeStyleInBuild en true, esta propiedad también afecta a las reglas de estilo de código (IDEXXXX).
  • Si usa un valor compuesto para AnalysisLevel (por ejemplo, <AnalysisLevel>5-recommended</AnalysisLevel>), puede omitir esta propiedad por completo. Sin embargo, si especifica ambas propiedades, AnalysisLevel tiene prioridad sobre AnalysisMode.
  • Si AnalysisMode se establece en AllEnabledByDefault y AnalysisLevel se establece en 5 o 5.0 y, a continuación, instala el SDK de .NET 6 y vuelve a compilar el proyecto, puede que aparezcan nuevas advertencias de compilación inesperadas. Para obtener más información, consulte la incidencia 5679 de dotnet/roslyn-analyzers.
  • Esta propiedad no tiene ningún efecto en el análisis de código de los proyectos que no hacen referencia a un SDK de proyecto, por ejemplo, los proyectos de .NET Framework heredados que hacen referencia al paquete NuGet Microsoft.CodeAnalysis.NetAnalyzers.

Categoría AnalysisMode<>

Esta propiedad, introducida en .NET 6, es igual que AnalysisMode, salvo que solo se aplica a una categoría de reglas de análisis de código específica. Esta propiedad le permite habilitar o deshabilitar las reglas en un nivel distinto al de las otras categorías de reglas. Si omite esta propiedad para una categoría de reglas concreta, su valor predeterminado es AnalysisMode. Los valores disponibles son los mismos que para AnalysisMode.

<PropertyGroup>
  <AnalysisModeSecurity>All</AnalysisModeSecurity>
</PropertyGroup>

En la tabla siguiente se muestra el nombre de propiedad de cada categoría de regla.

Nombre de la propiedad Categoría de regla
<AnalysisModeDesign> Reglas de diseño
<AnalysisModeDocumentation> Reglas de documentación
<AnalysisModeGlobalization> Reglas de globalización
<AnalysisModeInteroperability> Reglas de portabilidad e interoperabilidad
<AnalysisModeMaintainability> Reglas de mantenimiento
<AnalysisModeNaming> Reglas de nomenclatura
<AnalysisModePerformance> Reglas de rendimiento
<AnalysisModeSingleFile> Reglas de aplicación de archivo único
<AnalysisModeReliability> Reglas de confiabilidad
<AnalysisModeSecurity> Reglas de seguridad
<AnalysisModeStyle> Todas las reglas de estilo de código (IDEXXXX)
<AnalysisModeUsage> Reglas de uso

CodeAnalysisTreatWarningsAsErrors

La propiedad CodeAnalysisTreatWarningsAsErrors le permite configurar si las advertencias de análisis de calidad del código (CAxxxx) se deben tratar como advertencias e interrumpir la compilación. Si usa la marca -warnaserror al compilar los proyectos, las advertencias de análisis de calidad del código de .NET también se tratan como errores. Si no quiere que las advertencias de análisis de calidad del código se traten como errores, puede establecer la propiedad CodeAnalysisTreatWarningsAsErrors de MSBuild en false en el archivo del proyecto.

<PropertyGroup>
  <CodeAnalysisTreatWarningsAsErrors>false</CodeAnalysisTreatWarningsAsErrors>
</PropertyGroup>

EnableNETAnalyzers

De forma predeterminada, el análisis de calidad del código de .NET está habilitado para los proyectos que tienen como destino .NET 5 o una versión posterior. Si desarrolla con el SDK de .NET 5+, puede establecer la propiedad EnableNETAnalyzers en true para permitir el análisis de código de .NET en los proyectos de estilo SDK que tienen como destino versiones anteriores de .NET. Para deshabilitar el análisis de código en cualquier proyecto, establezca esta propiedad en false.

<PropertyGroup>
  <EnableNETAnalyzers>true</EnableNETAnalyzers>
</PropertyGroup>

Nota:

Esta propiedad se aplica específicamente a los analizadores integrados en el SDK de .NET 5+. No se debe usar cuando se instala un paquete NuGet de análisis de código.

EnforceCodeStyleInBuild

El análisis del estilo del código de .NET está deshabilitado de forma predeterminada en la compilación para todos los proyectos de .NET. Puede habilitar el análisis del estilo del código para los proyectos de .NET estableciendo la propiedad EnforceCodeStyleInBuild en true.

<PropertyGroup>
  <EnforceCodeStyleInBuild>true</EnforceCodeStyleInBuild>
</PropertyGroup>

Todas las reglas de estilo del código configuradas como advertencias o errores se ejecutarán en la compilación y notificarán infracciones.

Nota

Si instala .NET 6 (o Visual Studio 2022, que incluye .NET 6), pero desea compilar el proyecto mediante Visual Studio 2019, es posible que vea nuevas advertencias de CS8032 si tiene la EnforceCodeStyleInBuild propiedad establecida trueen . Para resolver las advertencias, puede especificar la versión del SDK de .NET para compilar el proyecto con (en este caso, algo parecido 5.0.404a ) agregando una entrada global.json.

_SkipUpgradeNetAnalyzersNuGetWarning

La _SkipUpgradeNetAnalyzersNuGetWarning propiedad le permite configurar si recibe una advertencia si usa analizadores de código de un paquete de NuGet que no está actualizado en comparación con los analizadores de código en el SDK de .NET más reciente. La advertencia es similar a la siguiente:

El SDK de .NET tiene analizadores más recientes con la versión "6.0.0" que la versión "5.0.3" del paquete "Microsoft.CodeAnalysis.NetAnalyzers". Actualice o quite esta referencia de paquete.

Para quitar esta advertencia y seguir usando la versión de los analizadores de código en el paquete de NuGet, establezca _SkipUpgradeNetAnalyzersNuGetWarningtrue en el archivo del proyecto.

<PropertyGroup>
  <_SkipUpgradeNetAnalyzersNuGetWarning>true</_SkipUpgradeNetAnalyzersNuGetWarning>
</PropertyGroup>

Propiedades de configuración del entorno de ejecución

Puede configurar algunos comportamientos del tiempo de ejecución si especifica las propiedades de MSBuild en el archivo de proyecto de la aplicación. Para obtener información sobre otros métodos de configuración del comportamiento del entorno de ejecución, consulte Configuración del entorno de ejecución.

ConcurrentGarbageCollection

La propiedad ConcurrentGarbageCollection configura si está habilitada la recolección de elementos no utilizados en segundo plano (simultánea). Establezca el valor en false para deshabilitar la recolección de elementos no utilizados en segundo plano. Para obtener más información, vea Recolección de elementos no utilizados en segundo plano.

<PropertyGroup>
  <ConcurrentGarbageCollection>false</ConcurrentGarbageCollection>
</PropertyGroup>

InvariantGlobalization

La propiedad InvariantGlobalization configura si la aplicación se ejecuta en modo invariable de globalización, lo que significa que no tiene acceso a datos específicos de la referencia cultural. Establezca el valor en true para ejecutar en el modo invariable de globalización. Para obtener más información, consulte Modo invariable.

<PropertyGroup>
  <InvariantGlobalization>true</InvariantGlobalization>
</PropertyGroup>

PredefinedCulturesOnly

En .NET 6 y versiones posteriores, la propiedad PredefinedCulturesOnly determina si las aplicaciones pueden crear referencias culturales distintas a la referencia cultural invariable si está habilitado el modo invariable de globalización. El valor predeterminado es true. Establezca el valor en false para permitir la creación de cualquier nueva referencia cultural en el modo invariable de globalización.

<PropertyGroup>
  <PredefinedCulturesOnly>false</PredefinedCulturesOnly>
</PropertyGroup>

Para obtener más información, vea Creación de referencia cultural y asignación de casos en el modo invariable de globalización.

RetainVMGarbageCollection

La propiedad RetainVMGarbageCollection configura el recolector de elementos no utilizados para colocar los segmentos de memoria eliminados en una lista en espera para su uso futuro o para liberarlos. Al establecer el valor en true, se indica al recolector de elementos no utilizados que coloque los segmentos en una lista en espera. Para obtener más información, vea Retain VM (Conservar VM).

<PropertyGroup>
  <RetainVMGarbageCollection>true</RetainVMGarbageCollection>
</PropertyGroup>

ServerGarbageCollection

La propiedad ServerGarbageCollection configura si la aplicación usa la recolección de elementos no utilizados de estación de trabajo o la de servidor. Establezca el valor en true para usar la recolección de elementos no utilizados de servidor. Para obtener más información, vea Estación de trabajo frente a servidor.

<PropertyGroup>
  <ServerGarbageCollection>true</ServerGarbageCollection>
</PropertyGroup>

ThreadPoolMaxThreads

La propiedad ThreadPoolMaxThreads configura el número máximo de subprocesos para el grupo de subprocesos de trabajo. Para obtener más información, consulte Máximo de subprocesos.

<PropertyGroup>
  <ThreadPoolMaxThreads>20</ThreadPoolMaxThreads>
</PropertyGroup>

ThreadPoolMinThreads

La propiedad ThreadPoolMinThreads configura el número mínimo de subprocesos para el grupo de subprocesos de trabajo. Para obtener más información, consulte Mínimo de subprocesos.

<PropertyGroup>
  <ThreadPoolMinThreads>4</ThreadPoolMinThreads>
</PropertyGroup>

TieredCompilation

La propiedad TieredCompilation configura si el compilador Just-In-Time (JIT) usa la compilación en niveles. Establezca el valor en false para deshabilitar la compilación en niveles. Para obtener más información, vea Compilación en niveles.

<PropertyGroup>
  <TieredCompilation>false</TieredCompilation>
</PropertyGroup>

TieredCompilationQuickJit

La propiedad TieredCompilationQuickJit configura si el compilador JIT usa JIT rápido. Establezca el valor en false para deshabilitar JIT rápido. Para obtener más información, vea JIT rápido.

<PropertyGroup>
  <TieredCompilationQuickJit>false</TieredCompilationQuickJit>
</PropertyGroup>

TieredCompilationQuickJitForLoops

La propiedad TieredCompilationQuickJitForLoops configura si el compilador JIT usa JIT rápido en métodos que contienen bucles. Establezca el valor en true para habilitar JIT rápido en métodos que contienen bucles. Para obtener más información, vea JIT rápido para bucles.

<PropertyGroup>
  <TieredCompilationQuickJitForLoops>true</TieredCompilationQuickJitForLoops>
</PropertyGroup>

Propiedades de referencia

En esta sección se documentan las siguientes propiedades de MSBuild:

AssetTargetFallback

La propiedad AssetTargetFallback permite especificar versiones de la plataforma compatibles adicionales para las referencias de proyectos y los paquetes NuGet. Por ejemplo, si se especifica una dependencia de paquete mediante PackageReference pero ese paquete no contiene recursos compatibles con el valor TargetFramework del proyecto, entra en juego la propiedad AssetTargetFallback. La compatibilidad del paquete al que se hace referencia se vuelve a comprobar con cada plataforma de destino que se especifica en AssetTargetFallback. Esta propiedad reemplaza la propiedad en desuso PackageTargetFallback.

Puede establecer la propiedad AssetTargetFallback en una o varias versiones de plataforma de destino.

<PropertyGroup>
  <AssetTargetFallback>net461</AssetTargetFallback>
</PropertyGroup>

DisableImplicitFrameworkReferences

La propiedad DisableImplicitFrameworkReferences controla los elementos FrameworkReference implícitos cuando el destino es .NET Core 3.0 y versiones posteriores. Cuando el destino es .NET Core 2.1 o .NET Standard 2.0 y versiones anteriores, controla los elementos PackageReference implícitos en los paquetes de un metapaquete. (Un metapaquete es un paquete basado en marco compuesto únicamente por dependencias de otros paquetes). Esta propiedad también controla las referencias implícitas, como System y System.Core, cuando el destino establecido es .NET Framework.

Establezca esta propiedad en true para deshabilitar los elementos FrameworkReference o PackageReference implícitos. Si establece esta propiedad en true, puede agregar referencias explícitas solo a las plataformas o paquetes que necesite.

<PropertyGroup>
  <DisableImplicitFrameworkReferences>true</DisableImplicitFrameworkReferences>
</PropertyGroup>

La restauración de un paquete al que se hace referencia instala todas sus dependencias directas y todas las dependencias de esas dependencias. Puede personalizar la restauración de paquetes especificando propiedades como RestorePackagesPath y RestoreIgnoreFailedSources. Para más información sobre estas y otras propiedades, vea Destino de restore.

<PropertyGroup>
  <RestoreIgnoreFailedSource>true</RestoreIgnoreFailedSource>
</PropertyGroup>

ValidateExecutableReferencesMatchSelfContained

La propiedad ValidateExecutableReferencesMatchSelfContained se puede usar para deshabilitar los errores relacionados con las referencias de proyecto ejecutable. Si .NET detecta que un proyecto ejecutable autocontenido hace referencia a un proyecto ejecutable dependiente del marco, o viceversa, genera errores NETSDK1150 y NETSDK1151, respectivamente. Para evitar estos errores cuando la referencia es intencionada, establezca la propiedad ValidateExecutableReferencesMatchSelfContained en false.

<PropertyGroup>
  <ValidateExecutableReferencesMatchSelfContained>false</ValidateExecutableReferencesMatchSelfContained>
</PropertyGroup>

WindowsSdkPackageVersion

La propiedad WindowsSdkPackageVersion se puede usar para invalidar la versión del paquete de destino Windows SDK. Esta propiedad se introdujo en .NET 5 y reemplaza el uso del elemento FrameworkReference para este propósito.

<PropertyGroup>
  <WindowsSdkPackageVersion>10.0.19041.18</WindowsSdkPackageVersion>
</PropertyGroup>

Nota:

No se recomienda invalidar la versión de Windows SDK, ya que los paquetes de destino de Windows SDK se incluyen con el SDK de .NET 5+. En su lugar, para hacer referencia al paquete más reciente de Windows SDK, actualice la versión del SDK de .NET. Esta propiedad solo se debe usar en ocasiones excepcionales, como el uso de paquetes de versión preliminar o la necesidad de invalidar la versión de C#/WinRT.

Las siguientes propiedades se usan para iniciar una aplicación con el comando dotnet run:

RunArguments

La propiedad RunArguments define los argumentos que se pasan a la aplicación cuando se ejecuta.

<PropertyGroup>
  <RunArguments>-mode dryrun</RunArguments>
</PropertyGroup>

Sugerencia

Puede especificar los argumentos adicionales que se pasarán a la aplicación mediante la opción -- para dotnet run.

RunWorkingDirectory

La propiedad RunWorkingDirectory define el directorio de trabajo en el que se iniciará el proceso. Puede ser una ruta de acceso absoluta o relativa al directorio del proyecto. Si no se especifica un directorio, se usa OutDir como directorio de trabajo.

<PropertyGroup>
  <RunWorkingDirectory>c:\temp</RunWorkingDirectory>
</PropertyGroup>

En esta sección se documentan las siguientes propiedades de MSBuild:

EnableComHosting

La propiedad EnableComHosting indica que un ensamblado proporciona un servidor COM. Al establecer EnableComHosting en true también implica que EnableDynamicLoading es true.

<PropertyGroup>
  <EnableComHosting>True</EnableComHosting>
</PropertyGroup>

Para obtener más información, vea Exposición de componentes de .NET en COM.

EnableDynamicLoading

La propiedad EnableDynamicLoading indica que un ensamblado es un componente cargado dinámicamente. El componente podría ser una biblioteca de COM o una biblioteca que no es de COM que se puede usar desde un host nativo o como complemento. Establecer esta propiedad en true tiene los efectos siguientes:

  • Se genera un archivo runtimeconfig.json.
  • RollForward se establece en LatestMinor.
  • Las referencias de NuGet se copian localmente.
<PropertyGroup>
  <EnableDynamicLoading>true</EnableDynamicLoading>
</PropertyGroup>

Propiedades del archivo generado

Las siguientes propiedades se refieren al código de los archivos generados:

DisableImplicitNamespaceImports

La propiedad DisableImplicitNamespaceImports se puede usar para deshabilitar importaciones de espacios de nombres implícitos en proyectos de Visual Basic que tienen como destino .NET 6 o una versión posterior. Los espacios de nombres implícitos son los espacios de nombres predeterminados que se importan globalmente en un proyecto de Visual Basic. Establezca esta propiedad en true para deshabilitar las importaciones de espacios de nombres implícitos.

<PropertyGroup>
  <DisableImplicitNamespaceImports>true</DisableImplicitNamespaceImports>
</PropertyGroup>

ImplicitUsings

La propiedad ImplicitUsings se puede usar para habilitar y deshabilitar directivas de global using implícitas en proyectos de C# que tienen como destino .NET 6 o una versión posterior y en proyectos de C# 10 o una versión posterior. Cuando la característica está habilitada, el SDK de .NET agrega directivas de global using para un conjunto de espacios de nombres predeterminados basados en el tipo de SDK del proyecto. Establezca esta propiedad en true o enable para habilitar las directivas de global using implícitas. Para deshabilitar las directivas de global using implícitas, quite la propiedad o establézcala en false o disable.

<PropertyGroup>
  <ImplicitUsings>enable</ImplicitUsings>
</PropertyGroup>

Nota:

En las plantillas para nuevos proyectos de C# que tienen como destino .NET 6 o una versión posterior, ImplicitUsings se establece en enable de manera predeterminada.

Para definir una directiva global using explícita, agregue un elemento Using.

Elementos

Los elementos de MSBuild son entradas al sistema de compilación. Los elementos se especifican de acuerdo con su tipo, que es el nombre del elemento. Por ejemplo, Compile y Reference son dos tipos de elementos comunes. El SDK de .NET pone a disposición los siguientes tipos de elementos adicionales:

Puede usar cualquiera de los atributos de elementos estándar, por ejemplo, Include y Update, en dichos elementos. Use Include para agregar un nuevo elemento; y Update, para modificar uno existente. Por ejemplo, Update se suele usar para modificar un elemento que el SDK de .NET ha agregado de forma implícita.

AssemblyMetadata

El elemento AssemblyMetadata especifica un atributo de ensamblado AssemblyMetadataAttribute de par clave-valor. Los metadatos Include se convierten en la clave y los metadatos Value se convierten en el valor.

<ItemGroup>
  <AssemblyMetadata Include="Serviceable" Value="True" />
</ItemGroup>

InternalsVisibleTo

El elemento InternalsVisibleTo genera un atributo de ensamblado InternalsVisibleToAttribute para el ensamblado de confianza especificado.

<ItemGroup>
  <InternalsVisibleTo Include="MyProject.Tests" />
</ItemGroup>

Si el ensamblado de confianza está firmado, puede especificar metadatos Key opcionales para especificar su clave pública completa. Si no especifica metadatos Key y $(PublicKey) está disponible, se usa esa clave. De lo contrario, no se agrega ninguna clave pública al atributo.

PackageReference

El elemento PackageReference define una referencia a un paquete NuGet.

El atributo Include especifica el identificador del paquete. El atributo Version especifica la versión o el intervalo de versiones. Para obtener más información sobre cómo especificar una versión mínima, una máxima, un intervalo o una coincidencia exacta, vea Intervalos de versiones.

El fragmento del archivo del proyecto del ejemplo siguiente hace referencia al paquete System.Runtime.

<ItemGroup>
  <PackageReference Include="System.Runtime" Version="4.3.0" />
</ItemGroup>

También puede controlar los recursos de las dependencias mediante metadatos como PrivateAssets.

<ItemGroup>
  <PackageReference Include="Contoso.Utility.UsefulStuff" Version="3.6.0">
    <PrivateAssets>all</PrivateAssets>
  </PackageReference>
</ItemGroup>

Para obtener más información, vea Referencias de paquete en un archivo del proyecto.

TrimmerRootAssembly

El elemento TrimmerRootAssembly permite excluir del recorte un ensamblado. El recorte es el proceso de quitar de una aplicación empaquetada las partes que no se han usado del tiempo de ejecución. En algunos casos, el recorte podría quitar de forma incorrecta las referencias necesarias.

El siguiente código XML excluye del recorte el ensamblado System.Security.

<ItemGroup>
  <TrimmerRootAssembly Include="System.Security" />
</ItemGroup>

Para obtener más información, vea Opciones de recorte.

Uso

El elemento Using le permite incluir un espacio de nombres globalmente en todo el proyecto de C#, de modo que no tenga que agregar una directiva de using para el espacio de nombres en la parte superior de los archivos de origen. Este elemento es similar al elemento Import que se puede usar para el mismo propósito en los proyectos de Visual Basic. Esta propiedad está disponible a partir de .NET 6.

<ItemGroup>
  <Using Include="My.Awesome.Namespace" />
</ItemGroup>

También puede usar el elemento Using para definir directivas using <alias> y using static <type> globales.

<ItemGroup>
  <Using Include="My.Awesome.Namespace" Alias="Awesome" />
</ItemGroup>

Por ejemplo:

  • <Using Include="Microsoft.AspNetCore.Http.Results" Alias="Results" /> emite global using Results = global::Microsoft.AspNetCore.Http.Results;
  • <Using Include="Microsoft.AspNetCore.Http.Results" Static="True" /> emite global using static global::Microsoft.AspNetCore.Http.Results;

Para obtener más información sobre directivas de using y directivas de using static <type> con alias, vea Uso de directivas.

Metadatos de elementos

Además de los atributos de los elementos de MSBuild estándar, el SDK de .NET pone a disposición las siguientes etiquetas de metadatos de los elementos:

CopyToPublishDirectory

Los metadatos de CopyToPublishDirectory relativos a un elemento de MSBuild controlan cuándo se copia el elemento en el directorio de publicación. Los valores permitidos son PreserveNewest, que solo copia el elemento si ha cambiado; Always, que siempre lo copia; y Never, que nunca lo hace. Desde el punto de vista del rendimiento, PreserveNewest es preferible porque permite una compilación incremental.

<ItemGroup>
  <None Update="appsettings.Development.json" CopyToOutputDirectory="PreserveNewest" CopyToPublishDirectory="PreserveNewest" />
</ItemGroup>

LinkBase

En el caso de un elemento situado fuera del directorio del proyecto y sus subdirectorios, el destino de publicación usa los metadatos de Link del elemento para determinar dónde se debe copiar este. Link también determina cómo se muestran los elementos situados fuera del árbol del proyecto en la ventana Explorador de soluciones de Visual Studio.

Si no se especifica Link para un elemento situado fuera del cono del proyecto, este tiene %(LinkBase)\%(RecursiveDir)%(Filename)%(Extension) como valor predeterminado. LinkBase permite especificar una carpeta base razonable para los elementos situados fuera del cono del proyecto. La jerarquía de carpetas de la carpeta base se conserva por medio de RecursiveDir. Si no se especifica LinkBase, se omite de la ruta a Link.

<ItemGroup>
  <Content Include="..\Extras\**\*.cs" LinkBase="Shared"/>
</ItemGroup>

En la imagen siguiente, se ilustra cómo se muestra globalmente un archivo incluido en el elemento anterior Include en el Explorador de soluciones.

Solution Explorer showing item with LinkBase metadata.

Consulte también