Referencia de MSBuild para proyectos del SDK de .NET

  • Artículo

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 de validación de ensamblado

Estas propiedades y elementos se pasan a la tarea ValidateAssemblies. Para obtener más información acerca de la validación de ensamblados, consulte Validación de ensamblados.

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

Nota:

Estas propiedades no forman parte del SDK de .NET (todavía). Para usarlas, también debe agregar un PackageReference a Microsoft.DotNet.ApiCompat.Task.

Además, las siguientes propiedades que se documentan en las Propiedades de validación de paquetes también se aplican a la validación de ensamblados:

ApiCompatStrictMode

Cuando se establece en true, la propiedad ApiCompatStrictMode especifica que se deben realizar comprobaciones de compatibilidad de API en modo estricto.

<PropertyGroup>
  <ApiCompatStrictMode>true</ApiCompatStrictMode>
</PropertyGroup>

ApiCompatValidateAssemblies

La propiedad ApiCompatValidateAssemblies habilita una serie de validaciones en los ensamblados especificados. Para obtener más información, consulte Validación de ensamblados.

<PropertyGroup>
  <ApiCompatValidateAssemblies>true</ApiCompatValidateAssemblies>
</PropertyGroup>

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>net8.0</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>net8.0;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.

Para obtener más información sobre cómo generar atributos de ensamblado mediante un archivo de proyecto, vea Establecer atributos de ensamblado en un archivo de proyecto.

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

Propiedades descriptivas

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 propiedad PackRelease es similar a la propiedad PublishRelease, salvo que cambia el comportamiento predeterminado de dotnet pack. Esta propiedad se ha introducido en .NET 7.

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

Nota:

  • A partir del SDK de .NET 8, el valor predeterminado de PackRelease es true. Para obtener más información, vea "dotnet pack" usa la configuración Release.
  • Solo en el SDK de .NET 7: para usar PackRelease en un proyecto que forme parte de una solución de Visual Studio, debe establecer la variable de entorno DOTNET_CLI_ENABLE_PACK_RELEASE_FOR_SOLUTIONS en true (o cualquier otro valor). En el caso de las soluciones que tienen muchos proyectos, establecer esta variable aumenta el tiempo necesario para empaquetar.

Propiedades de validación de paquetes

Estas propiedades y elementos se pasan a la tarea ValidatePackage. Para obtener más información sobre la validación de paquetes, consulte Introducción a la validación de paquetes.

Para ver las propiedades de la tarea ValidateAssemblies, consulte Propiedades de validación de ensamblados.

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

ApiCompatEnableRuleAttributesMustMatch

Cuando se establece en true, la propiedad ApiCompatEnableRuleAttributesMustMatch habilita la regla de validación que comprueba si los atributos coinciden. El valor predeterminado es false.

<PropertyGroup>
  <ApiCompatEnableRuleAttributesMustMatch>true</ApiCompatEnableRuleAttributesMustMatch>
</PropertyGroup>

ApiCompatEnableRuleCannotChangeParameterName

Cuando se establece en true, la propiedad ApiCompatEnableRuleCannotChangeParameterName habilita la regla de validación que comprueba si los nombres de parámetro han cambiado en métodos públicos. El valor predeterminado es false.

<PropertyGroup>
  <ApiCompatEnableRuleCannotChangeParameterName>true</ApiCompatEnableRuleCannotChangeParameterName>
</PropertyGroup>

ApiCompatExcludeAttributesFile

El elemento ApiCompatExcludeAttributesFile especifica la ruta de acceso a un archivo que contiene atributos que se van a excluir en formato DocId.

<ItemGroup>
  <ApiCompatExcludeAttributesFile Include="ApiCompatExcludedAttributes.txt" />
  <ApiCompatExcludeAttributesFile Include="ApiCompatBaselineExcludedAttributes.txt" />
</ItemGroup>

ApiCompatGenerateSuppressionFile

La propiedad ApiCompatGenerateSuppressionFile especifica si se va a generar un archivo de supresión de compatibilidad.

<PropertyGroup>
  <ApiCompatGenerateSuppressionFile>true</ApiCompatGenerateSuppressionFile>
</PropertyGroup>

ApiCompatPermitUnnecessarySuppressions

La propiedad ApiCompatPermitUnnecessarySuppressions especifica si se deben permitir supresiones innecesarias en el archivo de supresión.

El valor predeterminado es false.

<PropertyGroup>
  <ApiCompatPermitUnnecessarySuppressions>true</ApiCompatPermitUnnecessarySuppressions>
</PropertyGroup>

ApiCompatPreserveUnnecessarySuppressions

La propiedad ApiCompatPreserveUnnecessarySuppressions especifica si se deben conservar las supresiones innecesarias al volver a generar el archivo de supresión. Cuando se vuelve a generar un archivo de supresión existente, se lee su contenido, se deserializa en un conjunto de supresiones y a continuación se almacena en una lista. Es posible que algunas de las supresiones ya no sean necesarias si se ha corregido la incompatibilidad. Cuando las supresiones se serializan de nuevo en el disco, puede optar por mantener todas las expresiones existentes (deserializadas) estableciendo esta propiedad en true.

El valor predeterminado es false.

<PropertyGroup>
  <ApiCompatPreserveUnnecessarySuppressions>true</ApiCompatPreserveUnnecessarySuppressions>
</PropertyGroup>

ApiCompatRespectInternals

La propiedad ApiCompatRespectInternals especifica si se debe comprobar la compatibilidad de las API internal además de las API public.

<PropertyGroup>
  <ApiCompatRespectInternals>true</ApiCompatRespectInternals>
</PropertyGroup>

ApiCompatSuppressionFile

El elemento ApiCompatSuppressionFile especifica la ruta de acceso a uno o varios archivos de supresión desde los que se va a leer. Si no se especifica, se lee el archivo de supresión <project-directory>/CompatibilitySuppressions.xml (si existe).

<ItemGroup>
  <ApiCompatSuppressionFile Include="CompatibilitySuppressions.xml;CompatibilitySuppressions.WasmThreads.xml" />
</ItemGroup>

ApiCompatSuppressionOutputFile

La propiedad ApiCompatSuppressionOutputFile especifica la ruta de acceso a un archivo de supresión en el que se va a escribir cuando <ApiCompatGenerateSuppressionFile> es true. Si no se especifica, se usa el primer elemento ApiCompatSuppressionFile.

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>

EnableStrictModeForBaselineValidation

Cuando se establece en true, la propiedad EnableStrictModeForBaselineValidation habilita el modo strict para las comprobaciones de línea base del paquete. El valor predeterminado es false.

EnableStrictModeForCompatibleFrameworksInPackage

Cuando se establece en true, la propiedad EnableStrictModeForCompatibleFrameworksInPackage habilita el modo strict para ensamblados compatibles en función de su marco de destino. El valor predeterminado es false.

EnableStrictModeForCompatibleTfms

Cuando se establece en true, la propiedad EnableStrictModeForCompatibleTfms habilita el modo strict para ensamblados de contrato e implementación para todos los marcos de destino compatibles. El valor predeterminado es true.

NoWarn

La propiedad NoWarn especifica los id. de diagnóstico que se van a suprimir.

<PropertyGroup>
  <NoWarn>$(NoWarn);PKV0001</NoWarn>
</PropertyGroup>

PackageValidationBaselineFrameworkToIgnore

El elemento PackageValidationBaselineFrameworkToIgnore especifica un marco de destino que se omitirá desde el paquete de línea base. La cadena de marco debe coincidir exactamente con el nombre de carpeta del paquete de línea base.

<ItemGroup>
  <PackageValidationBaselineFrameworkToIgnore Include="netcoreapp2.1" />
</ItemGroup>

PackageValidationBaselineName

La propiedad PackageValidationBaselineName especifica el nombre del paquete de línea base con el que validar el paquete actual. Si no se especifica, se usa el valor PackageId.

PackageValidationBaselineVersion

La propiedad PackageValidationBaselineVersion especifica la versión del paquete de línea base con la que validar el paquete actual.

PackageValidationReferencePath

El elemento PackageValidationReferencePath especifica la ruta de acceso del directorio donde se puede encontrar el ensamblado de referencia por TFM.

<ItemGroup>
  <PackageValidationReferencePath Include="path/to/reference-assembly" TargetFramework="net7.0" />
</ItemGroup>

RoslynAssembliesPath

La propiedad RoslynAssembliesPath especifica la ruta de acceso al directorio que contiene los ensamblados Microsoft.CodeAnalysis que desea usar. Solo tiene que establecer esta propiedad si desea probar con un compilador más reciente que lo que hay en el SDK.

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, para una aplicación de .NET 5 y un RID de win-x64, la siguiente configuración cambia la ruta de acceso de salida de bin\Debug\net5.0\win-x64 a bin\Debug\net5.0:

<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 trueen , las dependencias de paquetes NuGet transitivas 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>

El valor predeterminado de CopyLocalLockFileAssemblies puede variar en función del tipo de salida. Por ejemplo, para las bibliotecas de clases, el valor predeterminado es false, mientras que para las aplicaciones de consola el valor predeterminado es true. Puede especificar esta propiedad explícitamente para invalidar el valor predeterminado si es necesario.

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.

GenerateRuntimeConfigDevFile

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

<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 propiedad GenerateSatelliteAssembliesForCore controla si los ensamblados satélite se generan 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 mediante al.exe, de forma predeterminada. Al establecer la propiedad GenerateSatelliteAssembliesForCore en true, los ensamblados satélite se crean mediante csc.exe en su lugar. El uso de csc.exe puede ser ventajoso en las siguientes situaciones:

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

IsPublishable

La propiedad IsPublishable permite ejecutar el destino Publish. Esta propiedad solo afecta a los procesos que usan archivos .*projy al destino Publish, 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 directorio OutDir. En .NET 6 y versiones posteriores, puede usar la propiedad ProduceReferenceAssemblyInOutDir para controlar si los ensamblados de referencia se escriben en el directorio OutDir. El valor predeterminado es false, y los ensamblados de referencia solo se escriben en el directorio IntermediateOutputPath. Establezca el valor en true para escribir ensamblados de referencia en el directorio OutDir.

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

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

PublishDocumentationFile

Cuando esta propiedad es true, el archivo de documentación XML del proyecto, si se genera uno, se incluye en la salida de publicación del proyecto. El valor predeterminado de esta propiedad es true.

Sugerencia

Establezca GenerateDocumentationFile en true para generar un archivo de documentación XML en tiempo de compilación.

PublishDocumentationFiles

Esta propiedad es una marca de habilitación para otras propiedades que controlan si se copian varios tipos de archivos de documentación XML en el directorio de publicación de manera predeterminada, es decir, PublishDocumentationFile y PublishReferencesDocumentationFiles. Si esas propiedades no están establecidas y esta propiedad está establecida, esas propiedades tendrán como valor predeterminado true. El valor predeterminado de esta propiedad es true.

PublishReferencesDocumentationFiles

Cuando esta propiedad es true, los archivos de documentación XML de las referencias del proyecto se copian en el directorio de publicación, en lugar de simplemente en recursos en tiempo de ejecución, como archivos DLL. El valor predeterminado de esta propiedad es true.

PublishRelease

La propiedad PublishRelease informa dotnet publish para usar la configuración de Release de forma predeterminada en lugar de la configuración de Debug . Esta propiedad se ha introducido en .NET 7.

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

Nota:

  • A partir del SDK de .NET 8, el valor predeterminado de PublishRelease es true para los proyectos que tienen como destino .NET 8 o una versión posterior. Para obtener más información, vea "dotnet publish" usa la configuración Release.
  • Esta propiedad no afecta al comportamiento de dotnet build /t:Publish y solo cambia la configuración cuando se publica mediante la CLI de .NET.
  • Solo en el SDK de .NET 7: para usar PublishRelease en un proyecto que forme parte de una solución de Visual Studio, debe establecer la variable de entorno DOTNET_CLI_ENABLE_PUBLISH_RELEASE_FOR_SOLUTIONS en true (o cualquier otro valor). Al publicar una solución con esta variable habilitada, el valor del PublishRelease proyecto ejecutable tiene prioridad y fluye la nueva configuración predeterminada a cualquier otro proyecto de la solución. Si una solución contiene varios proyectos ejecutables o de nivel superior con valores diferentes de PublishRelease, la solución no se publicará correctamente. En el caso de las soluciones que tienen muchos proyectos, el uso de esta configuración aumenta el tiempo necesario para publicar.

PublishSelfContained

La propiedad PublishSelfContained informa a dotnet publish para publicar una aplicación como una aplicación independiente. Esta propiedad es útil cuando no se puede usar el argumento --self-contained para el comando dotnet publish, por ejemplo, al publicar en el nivel de solución. En ese caso, puede agregar la propiedad MSBuild PublishSelfContained a un proyecto o archivo Directory.Build.Props.

Esta propiedad se ha introducido en .NET 7. Es similar a la propiedad SelfContained, salvo que es específica del verbo publish. Se recomienda usar PublishSelfContained en lugar de SelfContained.

<PropertyGroup>
  <PublishSelfContained>true</PublishSelfContained>
</PropertyGroup>

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>linux-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>win-x64;osx-x64;linux-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.) y en alemán (Alemania).

<PropertyGroup>
  <SatelliteResourceLanguages>en-US;de-DE</SatelliteResourceLanguages>
</PropertyGroup>

Nota:

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

  • Para especificar varios idiomas como argumento para dotnet publish, debe agregar tres pares de comillas alrededor de los identificadores de idioma. Por ejemplo:

    dotnet msbuild multi.msbuildproj -p:SatelliteResourceLanguages="""de;en"""

SelfContained

La propiedad SelfContained informa a dotnet build y dotnet publish para compilar una aplicación como una aplicación independiente. Esta propiedad es útil cuando no se puede usar el argumento --self-contained para el comando dotnet, por ejemplo, al publicar en el nivel de solución. En ese caso, puede agregar la propiedad MSBuild SelfContained a un proyecto o archivo Directory.Build.Props.

Esta propiedad es similar a la propiedad PublishSelfContained. Se recomienda usar PublishSelfContained en lugar de SelfContained.

<PropertyGroup>
  <SelfContained>true</SelfContained>
</PropertyGroup>

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. De forma predeterminada, se crea un archivo ejecutable dependiente del marco. 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 de MSBuild disponibles para ajustar el recorte, que es una característica que recorta el código sin usar de las implementaciones autocontenidas. 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 full o partial El valor predeterminado es full. Controla la granularidad de recorte.
SuppressTrimAnalysisWarnings true o false Controla si se generan advertencias de análisis de recorte.
EnableTrimAnalyzer true o false Controla si se generan advertencias de análisis de recorte. Puede habilitar el análisis incluso si PublishTrimmed está establecido en false.
ILLinkTreatWarningsAsErrors true o false Controla si las advertencias de recorte se tratan como errores. Por ejemplo, puede que desee establecer esta propiedad en false 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#.

ContinuousIntegrationBuild

La propiedad ContinuousIntegrationBuild indica si una compilación se está ejecutando en un servidor de integración continua (CI). Cuando se establece en true, esta propiedad habilita la configuración que solo se aplica a las compilaciones oficiales, en lugar de las compilaciones locales en un equipo para desarrolladores. Por ejemplo, las rutas de acceso de archivo almacenadas se normalizan para las compilaciones oficiales. Pero en un equipo de desarrollo local, el depurador no puede encontrar archivos de código fuente locales si se normalizan las rutas de acceso de archivo.

Nota:

Actualmente, establecer esta propiedad true en solo funciona si agrega una referencia de paquete de proveedor SourceLink específica o un elemento <SourceRoot Include="$(MyDirectory)" />. Para obtener más información, consulte incidencia 55860 de dotnet/roslyn.

Puede usar la variable del sistema de CI para establecer condicionalmente la propiedad ContinuousIntegrationBuild. Por ejemplo, el nombre de la variable para Azure Pipelines es TF_BUILD:

<PropertyGroup Condition="'$(TF_BUILD)' == 'true'">
  <ContinuousIntegrationBuild>true</ContinuousIntegrationBuild>
</PropertyGroup>

Para Acciones de GitHub, el nombre de la variable es GITHUB_ACTIONS:

<PropertyGroup Condition="'$(GITHUB_ACTIONS)' == 'true'">
  <ContinuousIntegrationBuild>true</ContinuousIntegrationBuild>
</PropertyGroup>

CopyDebugSymbolFilesFromPackages

Cuando esta propiedad se establece en true, todos los archivos de símbolos (también conocidos como archivos PDB) de los elementos PackageReference del proyecto se copian en la salida de la compilación. Estos archivos pueden proporcionar seguimientos de pila más informativos para las excepciones y hacer que los volcados de memoria y los seguimientos de la aplicación en ejecución sean más fáciles de entender. Sin embargo, incluir estos archivos da como resultado un mayor tamaño del conjunto de implementación.

Esta propiedad se presentó en el SDK de .NET 7.0.100, aunque el valor predeterminado es que no esté especificada.

CopyDocumentationFilesFromPackages

Cuando esta propiedad se establece en true, todos los archivos de documentación XML generados de los elementos PackageReference del proyecto se copian en la salida de la compilación. Tenga en cuenta que la habilitación de esta característica dará lugar a un mayor tamaño del conjunto de implementación.

Esta propiedad se presentó en el SDK de .NET 7.0.100, aunque el valor predeterminado es que no esté especificada.

DisableImplicitFrameworkDefines

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

  • Marco 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 del marco de destino y estos símbolos de preprocesador implícitos, consulte Marcos de destino.

Además, si especifica una plataforma de destino específica 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 la compatibilidad con plataformas de destino anteriores, se emiten símbolos de preprocesador para esas plataformas anteriores. Por ejemplo, net6.0 implica 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. 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 .NET destinado a .NET Core 3.0 o una versión posterior, 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.

EnableWindowsTargeting

Establezca la propiedad EnableWindowsTargeting en true para compilar aplicaciones de Windows (por ejemplo, aplicaciones de Windows Forms o Windows Presentation Foundation) en una plataforma que no sea Windows. Si no establece esta propiedad en true, obtendrá la advertencia de compilación NETSDK1100. Este error se produce porque los paquetes de destino y del entorno de ejecución no se descargan automáticamente en plataformas que no se admiten. Al establecer esta propiedad, esos paquetes se descargan cuando se usan destinos cruzados.

Nota

Esta propiedad se recomienda actualmente para permitir el desarrollo en plataformas que no son de Windows. Pero cuando la aplicación esté lista para su lanzamiento, debe compilarse en Windows. Al compilar en una plataforma que no es de Windows, es posible que la salida no sea la misma que cuando se compila en Windows. En concreto, el archivo ejecutable no está marcado como una aplicación Windows (lo que significa que siempre iniciará una ventana de consola) y no tendrá un icono insertado.

<PropertyGroup>
  <EnableWindowsTargeting>true</EnableWindowsTargeting>
</PropertyGroup>

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>

DisableRuntimeMarshalling

La propiedad DisableRuntimeMarshalling le permite especificar que desea deshabilitar la compatibilidad de serialización en runtime para el proyecto. Si esta propiedad se establece en true, DisableRuntimeMarshallingAttribute se agrega al ensamblado y cualquier interoperabilidad basada en P/Invokes o basada en delegados seguirá las reglas para la serialización en tiempo de ejecución deshabilitada.

<PropertyGroup>
    <DisableRuntimeMarshalling>True</DisableRuntimeMarshalling>
</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>

DefaultItemExcludesInProjectFolder

Use la propiedad DefaultItemExcludesInProjectFolder 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 DefaultItemExcludesInProjectFolder, en lugar de DefaultItemExcludes.

<PropertyGroup>
  <DefaultItemExcludesInProjectFolder>$(DefaultItemExcludesInProjectFolder);**/myprefix*/**</DefaultItemExcludesInProjectFolder>
</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 8 pero no quiere que cambie el conjunto predeterminado de reglas de análisis de código, establezca AnalysisLevel en 7.

<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>

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.
8.0 Se usa el conjunto de reglas que estaba disponible para .NET 8, incluso si hay reglas más recientes disponibles.
8.0-<mode> Se usa el conjunto de reglas que estaba disponible para .NET 8, incluso si hay reglas más recientes disponibles. El valor <mode> determina las reglas que están habilitadas.
8 Se usa el conjunto de reglas que estaba disponible para .NET 8, incluso si hay reglas más recientes disponibles.
8-<mode> Se usa el conjunto de reglas que estaba disponible para .NET 8, incluso si hay reglas más recientes disponibles. El valor <mode> determina las reglas que están habilitadas.
7.0 Se usa el conjunto de reglas que estaba disponible para .NET 7, incluso si hay reglas más recientes disponibles.
7.0-<mode> Se usa el conjunto de reglas que estaba disponible para .NET 7, incluso si hay reglas más recientes disponibles. El valor <mode> determina las reglas que están habilitadas.
7 Se usa el conjunto de reglas que estaba disponible para .NET 7, incluso si hay reglas más recientes disponibles.
7-<mode> Se usa el conjunto de reglas que estaba disponible para .NET 7, incluso si hay reglas más recientes disponibles. 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:

  • A partir de .NET 6, si establece EnforceCodeStyleInBuild en true, esta propiedad afecta a las reglas de estilo de código (IDEXXXX) (además de reglas de calidad del código).
  • 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>

Esta propiedad 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

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á habilitado de manera 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 siguiente tabla se muestran los valores de opción disponibles. Se muestran en orden creciente del número de reglas que habilitan.

Valor Descripción
None Todas las reglas están deshabilitadas. Puede incluir de forma selectiva reglas individuales para habilitarlas.
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 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. Para ver qué reglas incluye, inspeccione el archivo %ProgramFiles%/dotnet/sdk/[version]/Sdks/Microsoft.NET.Sdk/analyzers/build/config/analysislevel_[level]_minimum.editorconfig.
Recommended Modo más agresivo que el modo Minimum, donde se habilitan más reglas como advertencias de compilación. Para ver qué reglas incluye, inspeccione el archivo %ProgramFiles%/dotnet/sdk/[version]/Sdks/Microsoft.NET.Sdk/analyzers/build/config/analysislevel_[level]_recommended.editorconfig.
All Todas las reglas están habilitadas como advertencias de compilación*. Puede excluir de forma selectiva reglas individuales para deshabilitarlas.

* Las reglas siguientes no se habilitan al establecer AnalysisMode en All o establecer AnalysisLevel en latest-all: CA1017, CA1045, CA1005, CA1014, CA1060, CA1021 y las reglas del analizador de métricas de código (CA1501, CA1502, CA1505, CA1506 y CA1509). Estas reglas heredadas podrían quedar en desuso en versiones futuras. Sin embargo, todavía es posible habilitarlas individualmente mediante una entrada dotnet_diagnostic.CAxxxx.severity = <severity>.

Nota:

  • A partir de .NET 6, si establece EnforceCodeStyleInBuild en true, esta propiedad afecta a las reglas de estilo de código (IDEXXXX) (además de reglas de calidad del código).
  • Si usa un valor compuesto para AnalysisLevel (por ejemplo, <AnalysisLevel>8-recommended</AnalysisLevel>), puede omitir esta propiedad por completo. Sin embargo, si especifica ambas propiedades, 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>AnalysisMode

Esta propiedad 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.

_SkipUpgradeNetAnalyzersNuGetWarning

La propiedad _SkipUpgradeNetAnalyzersNuGetWarning le permite configurar si recibe una advertencia si usa analizadores de código de un paquete NuGet obsoleto 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 analizadores de código en el paquete NuGet, establezca _SkipUpgradeNetAnalyzersNuGetWarning en true en el archivo del proyecto.

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

Propiedades de configuración del entorno de ejecución

Puede configurar algunos comportamientos del entorno 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.

AutoreleasePoolSupport

La propiedad AutoreleasePoolSupport configura si cada subproceso administrado recibe un elemento NSAutoreleasePool implícito cuando se ejecuta en una plataforma macOS compatible. Para obtener más información, consulte AutoreleasePool para subprocesos administrados.

<PropertyGroup>
  <AutoreleasePoolSupport>true</AutoreleasePoolSupport>
</PropertyGroup>

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>

TieredPGO

La propiedad TieredPGO controla si está habilitada la optimización guiada por perfiles (PGO) dinámica o en capas. Establezca el valor en true para habilitar PGO en capas. Para más información, vea Optimización guiada por perfiles.

<PropertyGroup>
  <TieredPGO>true</TieredPGO>
</PropertyGroup>

UseWindowsThreadPool

La propiedad UseWindowsThreadPool configura si la administración de subprocesos del grupo de subprocesos se delega al grupo de subprocesos de Windows (solo Windows). El valor predeterminado es false, en cuyo caso se usa el grupo de subprocesos de .NET. Para obtener más información, consulte Grupo de subprocesos de Windows.

<PropertyGroup>
  <UseWindowsThreadPool>true</UseWindowsThreadPool>
</PropertyGroup>

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 implícitos FrameworkReference o PackageReference. Si establece esta propiedad en true, puede agregar referencias explícitas solo a las plataformas o paquetes que necesite.

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

DisableTransitiveFrameworkReferenceDownloads

Establezca la propiedad DisableTransitiveFrameworkReferenceDownloads en true para evitar la descarga de paquetes de destino y del entorno de ejecución adicionales a los que el proyecto no hace referencia directamente.

<PropertyGroup>
  <DisableTransitiveFrameworkReferenceDownloads>true</DisableTransitiveFrameworkReferenceDownloads>
</PropertyGroup>

DisableTransitiveProjectReferences

La propiedad DisableTransitiveProjectReferences controla las referencias implícitas del proyecto. Establezca esta propiedad en true para deshabilitar elementos de ProjectReference implícitos. Deshabilitar las referencias implícitas del proyecto da como resultado un comportamiento no transitivo similar al sistema de proyectos heredado.

Cuando esta propiedad es true, tiene un efecto similar al de establecer PrivateAssets="All" en todas las dependencias del proyecto dependiente.

Si establece esta propiedad en true, puede agregar referencias explícitas solo a los proyectos que necesite.

<PropertyGroup>
  <DisableTransitiveProjectReferences>true</DisableTransitiveProjectReferences>
</PropertyGroup>

ManagePackageVersionsCentrally

La propiedad ManagePackageVersionsCentrally se introdujo en .NET 7. Al establecerla en true en un archivo Directory.Packages.props en la raíz del repositorio, puede administrar dependencias comunes en los proyectos desde una ubicación. Agregue versiones para las dependencias comunes del paquete mediante elementos PackageVersion en el archivo Directory.Packages.props. A continuación, en los archivos de proyecto individuales, puede omitir atributos Version de cualquier elemento PackageReference que haga referencia a paquetes administrados centralmente.

Archivo Directory.Packages.props de ejemplo:

<PropertyGroup>
  <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
</PropertyGroup>
...
<ItemGroup>
  <PackageVersion Include="Microsoft.Extensions.Configuration" Version="7.0.0" />
</ItemGroup>

Archivo del proyecto individual:

<ItemGroup>
  <PackageReference Include="Microsoft.Extensions.Configuration" />
</ItemGroup>

Para obtener más información, vea Administración central de paquetes (CPM).

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>

UseMauiEssentials

Establezca la propiedad UseMauiEssentials en true para declarar una referencia explícita a un proyecto o paquete que depende de MAUI Essentials. Esta configuración garantiza que el proyecto extraiga la referencia de marco conocida correcta para MAUI Essentials. Si el proyecto hace referencia a un proyecto que usa MAUI Essentials, pero no establece esta propiedad en true, es posible que encuentre la advertencia de compilación NETSDK1186.

<PropertyGroup>
  <UseMauiEssentials>true</UseMauiEssentials>
</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 RunArguments propiedad 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>

Prueba de las propiedades relacionadas con el proyecto

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

IsTestProject

La IsTestProject propiedad indica que un proyecto es un proyecto de prueba. Cuando esta propiedad está establecida trueen , la validación para comprobar si el proyecto hace referencia a un archivo ejecutable autocontenida está deshabilitado. Esto se debe a que los proyectos de prueba tienen una OutputType api de Exe pero normalmente llaman a API en un ejecutable al que se hace referencia en lugar de intentar ejecutarse. Además, si un proyecto hace referencia a un proyecto en IsTestProject el que se establece trueen , el proyecto de prueba no se valida como referencia ejecutable.

Esta propiedad se necesita principalmente para el dotnet test escenario y no tiene ningún impacto al usar vstest.console.exe.

Nota:

Si el proyecto especifica el SDK de MSTest, no es necesario establecer esta propiedad. Se establece automáticamente. De forma similar, esta propiedad se establece automáticamente para los proyectos que hacen referencia al paquete NuGet Microsoft.NET.Test.Sdk vinculado a VSTest.

IsTestingPlatformApplication

Cuando el proyecto hace referencia al paquete Microsoft.Testing.Platform.MSBuild , el valor IsTestingPlatformApplication true en (que también es el valor predeterminado si no se especifica) hace lo siguiente:

  • Genera el punto de entrada al proyecto de prueba.
  • Genera el archivo de configuración.
  • Detecta las extensiones.

Al establecer la propiedad en , false se deshabilita la dependencia transitiva en el paquete. Una dependencia transitiva es cuando un proyecto que hace referencia a otro proyecto que hace referencia a un paquete determinado se comporta como si hace referencia al paquete. Normalmente, esta propiedad false se establece en en un proyecto que no es de prueba que hace referencia a un proyecto de prueba. Para obtener más información, consulte el error CS8892.

Si el proyecto de prueba hace referencia a MSTest, NUnit o xUnit, esta propiedad se establece en el mismo valor que EnableMSTestRunner, EnableNUnitRunner o UseMicrosoftTestingPlatformRunner (para xUnit).

Enable[NugetPackageNameWithoutDots]

Use una propiedad con el patrón Enable[NugetPackageNameWithoutDots] para habilitar o deshabilitar las extensiones Microsoft.Testing.Platform.

Por ejemplo, para habilitar la extensión de volcado de memoria (paquete NuGet Microsoft.Testing.Extensions.CrashDump), establezca en EnableMicrosoftTestingExtensionsCrashDump true.

Para obtener más información, vea Habilitar o deshabilitar extensiones.

EnableAspireTesting

Al usar el SDK del proyecto MSTest, puede usar la EnableAspireTesting propiedad para incluir todas las dependencias y directivas predeterminadas using que necesita para realizar pruebas con Aspire y MSTest. Esta propiedad está disponible en MSTest 3.4 y versiones posteriores.

Para obtener más información, consulte Prueba con .NET Aspire.

EnablePlaywright

Al usar el SDK del proyecto MSTest, puede usar la EnablePlaywright propiedad para incluir todas las dependencias y directivas predeterminadas using que necesita para realizar pruebas con Playwright y MSTest. Esta propiedad está disponible en MSTest 3.4 y versiones posteriores.

Para obtener más información, consulte Playwright.

EnableMSTestRunner

La EnableMSTestRunner propiedad habilita o deshabilita el uso del ejecutor de MSTest. El ejecutor de MSTest es una alternativa ligera y portátil a VSTest. Esta propiedad está disponible en MSTest 3.2 y versiones posteriores.

Nota:

Si el proyecto especifica el SDK de MSTest, no es necesario establecer esta propiedad. Se establece automáticamente.

EnableNUnitRunner

La EnableNUnitRunner propiedad habilita o deshabilita el uso del ejecutor de NUnit. El ejecutor NUnit es una alternativa ligera y portátil a VSTest. Esta propiedad está disponible en NUnit3TestAdapter en la versión 5.0 y posteriores.

GenerateTestingPlatformEntryPoint

Al establecer la GenerateTestingPlatformEntryPoint propiedad para false deshabilitar la generación automática del punto de entrada del programa en un proyecto de prueba msTest, NUnit o xUnit. Es posible que desee establecer esta propiedad false en cuando defina manualmente un punto de entrada o cuando haga referencia a un proyecto de prueba desde un archivo ejecutable que también tenga un punto de entrada.

Para obtener más información, consulte el error CS8892.

Para controlar la generación del punto de entrada en un proyecto de VSTest, use la GenerateProgramFile propiedad .

TestingPlatformCaptureOutput

La TestingPlatformCaptureOutput propiedad controla si todas las salidas de la consola que escribe un ejecutable de prueba se capturan y ocultan al usuario cuando se usan dotnet test para ejecutar Microsoft.Testing.Platform pruebas. De forma predeterminada, la salida de la consola está oculta. Esta salida incluye el banner, la información de versión y la información de prueba con formato. Establezca esta propiedad en false para mostrar esta información junto con la salida de MSBuild.

Para obtener más información, consulte Mostrar la salida completa de la plataforma.

TestingPlatformCommandLineArguments

La TestingPlatformCaptureOutput propiedad permite especificar argumentos de línea de comandos para la aplicación de prueba cuando se usan dotnet test para ejecutar Microsoft.Testing.Platform pruebas. En el siguiente fragmento de código de archivo de proyecto se muestra un ejemplo.

<PropertyGroup>
  ...
  <TestingPlatformCommandLineArguments>--minimum-expected-tests 10</TestingPlatformCommandLineArguments>
</PropertyGroup>

TestingPlatformDotnetTestSupport

La TestingPlatformDotnetTestSupport propiedad le permite especificar si VSTest se usa cuando se usa dotnet test para ejecutar pruebas. Si establece esta propiedad trueen , VSTest está deshabilitado y todas las Microsoft.Testing.Platform pruebas se ejecutan directamente.

Si tiene una solución que contiene proyectos de prueba de VSTest, así como proyectos de MSTest, NUnit o XUnit, debe realizar una llamada por modo (es decir, dotnet test no ejecutará pruebas de VSTest y las plataformas más recientes en una sola llamada).

TestingPlatformShowTestsFailure

La TestingPlatformShowTestsFailure propiedad permite controlar si se notifica un único error o todos los errores de una prueba con error cuando se usan dotnet test para ejecutar pruebas. De forma predeterminada, se resumen los errores de prueba en un archivo .log y se notifica un único error por proyecto de prueba a MSBuild. Para mostrar errores por prueba con errores, establezca esta propiedad true en en el archivo del proyecto.

TestingExtensionsProfile

Al usar el SDK del proyecto MSTest, la TestingExtensionsProfile propiedad le permite seleccionar un perfil que se va a usar. En la tabla siguiente se muestran los valores permitidos.

Valor Descripción
Default Habilita las extensiones recomendadas para esta versión de MSTest.SDK.
None No hay extensiones habilitadas.
AllMicrosoft Habilite todas las extensiones enviadas por Microsoft (incluidas las extensiones con una licencia restrictiva).

Para obtener más información, consulte Perfil de ejecutor de MSTest.

UseVSTest

Establezca la UseVSTest propiedad en true para cambiar del ejecutor de MSTest al ejecutor de VSTest al usar el SDK de proyectos de MSTest.

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

AppHostDotNetSearch

La AppHostDotNetSearch propiedad configura cómo el ejecutable nativo generado para una aplicación buscará una instalación de .NET. Esta propiedad solo afecta al ejecutable generado en la publicación, no a la compilación.

<PropertyGroup>
  <AppHostDotNetSearch>Global</AppHostDotNetSearch>
</PropertyGroup>

En la tabla siguiente se enumeran los valores válidos. Puede especificar varios valores, separados por punto y coma.

Valor Significado
AppLocal Carpeta del ejecutable de la aplicación
AppRelative Ruta de acceso relativa al archivo ejecutable de la aplicación tal y como se especifica en AppHostRelativeDotNet
EnvironmentVariables Valor de las variables de DOTNET_ROOT[_<arch>] entorno
Global Ubicaciones de instalación global registradas y predeterminadas

Esta propiedad se introdujo en .NET 9.

AppHostRelativeDotNet

La AppHostRelativeDotNet propiedad permite especificar una ruta de acceso relativa para que el ejecutable de la aplicación busque la instalación de .NET cuando esté configurada para hacerlo. Establecer la AppHostRelativeDotNet propiedad implica que AppHostDotNetSearch es AppRelative. Esta propiedad solo afecta al ejecutable generado en la publicación, no a la compilación.

<PropertyGroup>
  <AppHostRelativeDotNet>./relative/path/to/runtime</AppHostRelativeDotNet>
</PropertyGroup>

Esta propiedad se introdujo en .NET 9.

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.

FrameworkReference

El elemento FrameworkReference define una referencia a un marco compartido .NET.

El atributo Include especifica el identificador del marco.

El fragmento del archivo del proyecto del ejemplo siguiente hace referencia al marco compartido Microsoft.AspNetCore.App.

<ItemGroup>
  <FrameworkReference Include="Microsoft.AspNetCore.App" />
</ItemGroup>

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, consulte 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 más información, consulte las directivas de alias using y las directivas using static <type>.

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.

Elemento con metadatos de LinkBase en el Explorador de soluciones.

Vea también