Compartilhar via

Referência do MSBuild para projetos do SDK do .NET

  • Artigo

Esta página é uma referência para as propriedades e itens do MSBuild que você pode usar para configurar projetos .NET.

Observação

Esta página é um trabalho em andamento e não lista todas as propriedades úteis do MSBuild para o SDK do .NET. Para obter uma lista das propriedades comuns do MSBuild, confira as propriedades comuns do MSBuild.

Propriedades de validação de assemblies

Essas propriedades e itens são transmitidos para a tarefa ValidateAssemblies. Para obter mais informações sobre a validação de assemblies, confira Validação de assemblies.

As seguintes propriedades do MSBuild estão documentadas nesta seção:

Observação

Essas propriedades não fazem parte do SDK do .NET (ainda). Para usá-las, você também precisa adicionar uma PackageReference à Microsoft.DotNet.ApiCompat.Task.

Além disso, as seguintes propriedades que estão documentadas nas Propriedades de validação de pacotes também se aplicam à validação de assemblies:

ApiCompatStrictMode

Quando definida como true, a propriedade ApiCompatStrictMode especifica que as verificações de compatibilidade da API devem ser executadas no modo estrito.

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

ApiCompatValidateAssemblies

A propriedade ApiCompatValidateAssemblies habilita uma série de validações nos assemblies especificados. Para obter mais informações, consulte Validação de assemblies.

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

Propriedades do atributo Assembly

GenerateAssemblyInfo

A propriedade GenerateAssemblyInfo controla a geração de atributos de AssemblyInfo para o projeto. O valor padrão é true. Use false para desabilitar a geração do arquivo:

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

A configuração GeneratedAssemblyInfoFile controla o nome do arquivo gerado.

Quando o valor de GenerateAssemblyInfo é true, as propriedades de projeto relacionadas ao pacote são transformadas em atributos de assembly.

Para obter mais informações sobre como gerar atributos de assembly usando um arquivo de projeto, confira Definir atributos de assembly em um arquivo de projeto.

GeneratedAssemblyInfoFile

A propriedade GeneratedAssemblyInfoFile define o caminho relativo ou absoluto do arquivo de informações de assembly gerado. O padrão é um arquivo chamado [nome do projeto].Assemblyinfo.[cs|vb] no diretório $(IntermediateOutputPath) (geralmente obj).

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

Propriedades do Framework

As seguintes propriedades do MSBuild estão documentadas nesta seção:

TargetFramework

A propriedade TargetFramework especifica a versão da estrutura de destino para o aplicativo. Para obter uma lista de monikers de estrutura de destino válidos, confira Estruturas de destino em projetos no estilo SDK.

<PropertyGroup>
  <TargetFramework>net8.0</TargetFramework>
</PropertyGroup>

Para obter mais informações sobre TFMs, confira Estruturas de destino em projetos em estilo SDK.

TargetFrameworks

Use a propriedade TargetFrameworks quando quiser que seu aplicativo vise várias plataformas. Para obter uma lista de monikers de estrutura de destino válidos, confira Estruturas de destino em projetos no estilo SDK.

Observação

Essa propriedade será ignorada se TargetFramework (singular) for especificado.

<PropertyGroup>
  <TargetFrameworks>net8.0;net462</TargetFrameworks>
</PropertyGroup>

Para obter mais informações sobre TFMs, confira Estruturas de destino em projetos em estilo SDK.

NetStandardImplicitPackageVersion

Observação

Essa propriedade só se aplica a projetos que usam netstandard1.x. Ela não se aplica a projetos que usam netstandard2.x.

Use a propriedade NetStandardImplicitPackageVersion para especificar uma versão da estrutura menor que a versão do metapacote. O arquivo de projeto no exemplo a seguir visa netstandard1.3, mas usa a versão 1.6.0 do NETStandard.Library.

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

Propriedades do pacote

Propriedades descritivas

Você pode especificar propriedades, como PackageId, PackageVersion, PackageIcon, Titlee Description, para descrever o pacote criado a partir do seu projeto. Para obter informações sobre essas e outras propriedades, confira destino do pacote.

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

PackRelease

A propriedade PackRelease é semelhante à propriedade PublishRelease , exceto que altera o comportamento padrão de dotnet pack. Essa propriedade foi introduzida no .NET 7.

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

Observação

  • Do SDK do .NET 8 em diante, o padrão de PackRelease é true. Para obter mais informações, confira O 'dotnet pack' usa a configuração Release.
  • Somente no SDK do .NET 7: para usar PackRelease em um projeto que faz parte de uma solução do Visual Studio, você precisa definir a variável de ambiente DOTNET_CLI_ENABLE_PACK_RELEASE_FOR_SOLUTIONS como true (ou qualquer outro valor). Para soluções que têm muitos projetos, a definição dessa variável aumenta o tempo necessário para o empacotamento.

Propriedades de validação de pacotes

Essas propriedades e itens são transmitidos para a tarefa ValidatePackage. Para obter mais informações sobre a validação de pacotes, confira a Visão geral da validação de pacotes.

Para obter as propriedades para a tarefa ValidateAssemblies, consulte as propriedades de validação de assemblies.

As seguintes propriedades do MSBuild estão documentadas nesta seção:

ApiCompatEnableRuleAttributesMustMatch

Quando definida como true, a propriedade ApiCompatEnableRuleAttributesMustMatch habilita a regra de validação que verifica se os atributos correspondem. O padrão é false.

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

ApiCompatEnableRuleCannotChangeParameterName

Quando definida como true, a propriedade ApiCompatEnableRuleCannotChangeParameterName habilita a regra de validação que verifica se os nomes dos parâmetros foram alterados nos métodos públicos. O padrão é false.

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

ApiCompatExcludeAttributesFile

O item ApiCompatExcludeAttributesFile especifica o caminho para um arquivo que contém atributos a serem excluídos no formato DocId.

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

ApiCompatGenerateSuppressionFile

A propriedade ApiCompatGenerateSuppressionFile especifica se um arquivo de supressão de compatibilidade deve ser gerado.

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

ApiCompatPermitUnnecessarySuppressions

A propriedade ApiCompatPermitUnnecessarySuppressions especifica se supressões desnecessárias devem ser permitidas no arquivo de supressão.

O padrão é false.

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

ApiCompatPreserveUnnecessarySuppressions

A propriedade ApiCompatPreserveUnnecessarySuppressions especifica se supressões desnecessárias devem ser preservadas ao regenerar o arquivo de supressão. Quando um arquivo de supressão existente é regenerado, seu conteúdo é lido, desserializado em um conjunto de supressões e, a seguir, armazenado em uma lista. Algumas das supressões podem não ser mais necessárias se a incompatibilidade tiver sido corrigida. Quando as supressões são serializadas de volta ao disco, você pode optar por manter todas as expressões existentes (desserializadas) configurando essa propriedade como true.

O padrão é false.

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

ApiCompatRespectInternals

A propriedade ApiCompatRespectInternals especifica se as APIs internal devem ser verificadas quanto à compatibilidade além das APIs public.

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

ApiCompatSuppressionFile

O item ApiCompatSuppressionFile especifica o caminho para um ou mais arquivos de supressão que devem ser lidos. Se não for especificado, o arquivo de supressão <project-directory>/CompatibilitySuppressions.xml será lido (se existir).

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

ApiCompatSuppressionOutputFile

A propriedade ApiCompatSuppressionOutputFile especifica o caminho para um arquivo de supressão onde gravar quando <ApiCompatGenerateSuppressionFile> for true. Se não for especificada, o primeiro item do ApiCompatSuppressionFile será usado.

EnablePackageValidation

A propriedade EnablePackageValidation habilita uma série de validações no pacote após a tarefa Pack. Para obter mais informações, confira validação de pacote.

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

EnableStrictModeForBaselineValidation

Quando definida como true, a propriedade EnableStrictModeForBaselineValidation habilita o modo estrito para verificações da linha de base do pacote. O padrão é false.

EnableStrictModeForCompatibleFrameworksInPackage

Quando definida como true, a propriedade EnableStrictModeForCompatibleFrameworksInPackage habilita o modo estrito para assemblies compatíveis, baseadas na respectiva estrutura de destino. O padrão é false.

EnableStrictModeForCompatibleTfms

Quando definida como true, a propriedade EnableStrictModeForCompatibleTfms habilita o modo estrito para os assemblies de contrato e implementação para todas as estruturas de destino compatíveis. O padrão é true.

NoWarn

A propriedade NoWarn especifica as IDs de diagnóstico a serem suprimidas.

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

PackageValidationBaselineFrameworkToIgnore

O item PackageValidationBaselineFrameworkToIgnore especifica uma estrutura de destino do pacote da linha de base a ser ignorada. A cadeia de caracteres da estrutura deve corresponder exatamente ao nome da pasta no pacote da linha de base.

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

PackageValidationBaselineName

A propriedade PackageValidationBaselineName especifica o nome do pacote da linha de base com relação ao qual o pacote atual deve ser validado. Se não for especificada, o valor PackageId será usado.

PackageValidationBaselineVersion

A propriedade PackageValidationBaselineVersion especifica a versão do pacote da linha de base com relação ao qual o pacote atual deve ser validado.

PackageValidationReferencePath

O item PackageValidationReferencePath especifica o caminho do diretório no qual o assembly de referência pode ser encontrado, por TFM.

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

RoslynAssembliesPath

A propriedade RoslynAssembliesPath especifica o caminho para o diretório que contém os assemblies de Microsoft.CodeAnalysis que você quer usar. Você só precisará definir essa propriedade se quiser testar com um compilador mais recente que o que está no SDK.

As seguintes propriedades do MSBuild estão documentadas nesta seção:

AppendTargetFrameworkToOutputPath

A propriedade AppendTargetFrameworkToOutputPath controla se o moniker da estrutura de destino (TFM) é acrescentado ao caminho de saída (que é definido por OutputPath). O SDK do .NET acrescenta automaticamente a estrutura de destino e, se presente, o identificador de runtime ao caminho de saída. Configurar AppendTargetFrameworkToOutputPath como false impede que o TFM seja acrescentado ao caminho de saída. No entanto, sem o TFM no caminho de saída, vários artefatos de compilação podem substituir uns aos outros.

Por exemplo, para um aplicativo .NET 5, o caminho de saída muda de bin\Debug\net5.0 para bin\Debug a seguinte configuração:

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

AppendRuntimeIdentifierToOutputPath

A propriedade AppendRuntimeIdentifierToOutputPath controla se o RID (identificador de runtime) é acrescentado ao caminho de saída. O SDK do .NET acrescenta automaticamente a estrutura de destino e, se presente, o identificador de runtime ao caminho de saída. Configurar AppendRuntimeIdentifierToOutputPath como false impede que o TFM seja acrescentado ao caminho de saída.

Por exemplo, para um aplicativo .NET 5 e um RID de , a configuração a seguir altera o caminho de win-x64saída de bin\Debug\net5.0\win-x64 para bin\Debug\net5.0:

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

CopyLocalLockFileAssemblies

A propriedade CopyLocalLockFileAssemblies é útil para projetos de plug-in que têm dependências em outras bibliotecas. Se você definir essa propriedade como true, todas as dependências transitivas do pacote NuGet serão copiadas para o diretório de saída. Isso significa que você pode usar a saída de dotnet build executar o plug-in em qualquer computador.

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

O valor padrão de pode variar de acordo com o tipo de CopyLocalLockFileAssemblies saída. Por exemplo, para bibliotecas de classes, o valor padrão é false, enquanto para aplicativos de console o padrão é true. Você pode especificar essa propriedade explicitamente para substituir o padrão, se necessário.

Dica

Como alternativa, você pode usar dotnet publish para publicar a biblioteca de classes. Para obter mais informações, confira dotnet publish.

ErrorOnDuplicatePublishOutputFiles

A propriedade ErrorOnDuplicatePublishOutputFiles se refere a se o SDK gera um erro NETSDK1148 quando o MSBuild detecta arquivos duplicados na saída de publicação, mas não pode determinar quais arquivos remover. Defina a propriedade ErrorOnDuplicatePublishOutputFiles como false se você não quiser que o erro seja gerado.

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

Essa propriedade foi introduzida no .NET 6.

GenerateRuntimeConfigDevFile

A partir do SDK do .NET 6, o arquivo [Appname].runtimesettings.dev.jsonnão é mais gerado por padrão no momento da compilação. Se você ainda quiser que esse arquivo seja gerado, defina a propriedade GenerateRuntimeConfigDevFile como true.

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

GenerateRuntimeConfigurationFiles

A propriedade GenerateRuntimeConfigurationFiles controla se as opções de configuração de runtime são copiadas do arquivo runtimeconfig.template.json para o arquivo [appname].runtimeconfig.json. No caso de aplicativos que exigem um arquivo runtimeconfig.json, isto é, aqueles em que OutputType é Exe, essa propriedade tem o valor padrão de true.

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

GenerateSatelliteAssembliesForCore

A propriedade GenerateSatelliteAssembliesForCore controla se assemblies satélites são gerados usando csc.exe ou Al.exe (Assembly Linker) em projetos .NET Framework. Os projetos (.NET Core e .NET 5+ sempre usam csc.exe para gerar assemblies satélites). Para projetos .NET Framework, os assemblies satélites são criados por al.exe, por padrão. Ao definir a propriedade GenerateSatelliteAssembliesForCore como true, os assemblies satélite são criados por csc.exe em vez disso. Usar csc.exe pode ser vantajoso nas seguintes situações:

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

IsPublishable

A propriedade IsPublishable permite que o destino Publish seja executado. Essa propriedade afeta apenas os processos que usam arquivos .*proj e o destino Publish, como o comando de dotnet publish. Isso não afeta a publicação no Visual Studio, que usa o destino PublishOnly. O valor padrão é true.

Essa propriedade será útil se você executar dotnet publish em um arquivo de solução, pois ela permitirá a seleção automática de projetos que devem ser publicados.

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

PreserveCompilationContext

A propriedade PreserveCompilationContext permite que um aplicativo criado ou publicado compile mais código em tempo de execução usando as mesmas configurações que foram usadas no tempo de compilação. Os assemblies referenciados em tempo de compilação serão copiados para o subdiretório ref do diretório de saída. Os nomes dos assemblies de referência são armazenados no arquivo .deps.json do aplicativo com as opções passadas para o compilador. Você pode recuperar essas informações usando as propriedades DependencyContext.CompileLibraries e DependencyContext.CompilationOptions.

Essa funcionalidade é usada principalmente internamente por páginas MVC e Razor do ASP.NET Core para permitir a compilação em tempo de execução de arquivos Razor.

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

PreserveCompilationReferences

A propriedade PreserveCompilationReferences é semelhante à propriedade PreserveCompilationContext, exceto que ela copia apenas os assemblies referenciados para o diretório de publicação e não o arquivo .deps.json.

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

Para obter mais informações, confira Propriedades do SDK do Razor.

ProduceReferenceAssemblyInOutDir

No .NET 5 e em versões anteriores, os assemblies de referência são sempre gravados no diretório OutDir. No .NET 6 e versões posteriores, você pode usar a propriedade ProduceReferenceAssemblyInOutDir para controlar se os assemblies de referência são gravados no diretório OutDir. O valor padrão é false, e assemblies de referência são gravados apenas no diretório IntermediateOutputPath. Defina o valor como true para gravar assemblies de referência no diretório OutDir.

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

Para obter mais informações, confira Gravar assemblies de referência para saída intermediária.

PublishDocumentationFile

Quando essa propriedade for true, o arquivo de documentação XML do projeto, se for gerado, será incluído na saída de publicação do projeto. Essa propriedade tem como padrão true.

Dica

Defina GenerateDocumentationFile como true para gerar um arquivo de documentação XML no momento da compilação.

PublishDocumentationFiles

Essa propriedade é um sinalizador de ativação para várias outras propriedades que controlam se vários tipos de arquivos de documentação XML são copiados para o diretório de publicação por padrão, ou seja, PublishDocumentationFile e PublishReferencesDocumentationFiles. Se essas propriedades não estiverem definidas e essa propriedade estiver definida, essas propriedades serão padronizadas para true. Essa propriedade tem como padrão true.

PublishReferencesDocumentationFiles

Quando essa propriedade é true, os arquivos de documentação XML para as referências do projeto são copiados para o diretório de publicação, em vez de apenas ativos de tempo de execução, como arquivos DLL. Essa propriedade tem como padrão true.

PublishRelease

A propriedade PublishRelease informa dotnet publish para usar a configuração por padrão Release em vez da configuração Debug. Essa propriedade foi introduzida no .NET 7.

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

Observação

  • Do SDK do .NET 8 em diante, o padrão de PublishRelease é true para projetos direcionados ao .NET 8 ou posterior. Para obter mais informações, confira O 'dotnet publish' usa a configuração Release.
  • Essa propriedade não afeta o comportamento de dotnet build /t:Publish e só altera a configuração em publicações por meio da CLI do .NET.
  • Somente no SDK do .NET 7: para usar PublishRelease em um projeto que faz parte de uma solução do Visual Studio, você precisa definir a variável de ambiente DOTNET_CLI_ENABLE_PUBLISH_RELEASE_FOR_SOLUTIONS como true (ou qualquer outro valor). Ao publicar uma solução com essa variável habilitada, o valor PublishRelease do projeto executável tem precedência e flui a nova configuração padrão para quaisquer outros projetos na solução. Se uma solução contiver vários projetos executáveis ou de nível superior com valores diferentes de PublishRelease, a solução não será publicada com êxito. Para soluções que têm muitos projetos, o uso dessa configuração aumenta o tempo necessário para publicação.

PublishSelfContained

A propriedade PublishSelfContained informa dotnet publish para publicar um aplicativo como um aplicativo independente. Essa propriedade é útil quando você não pode usar o argumento --self-contained para o comando dotnet publish, por exemplo, quando você está publicando no nível da solução. Nesse caso, você pode adicionar a propriedade do MSBuild PublishSelfContained a um projeto ou arquivo Directory.Build.Props.

Essa propriedade foi introduzida no .NET 7. É semelhante à propriedade SelfContained, exceto que ela é específica para o verbo publish. É recomendável usar PublishSelfContained em vez de SelfContained.

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

RollForward

A propriedade RollForward controla como o aplicativo escolhe um runtime quando várias versões de runtime estão disponíveis. Esse valor é a saída de .runtimeconfig.json como a configuração rollForward.

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

Configure RollForward para um dos seguintes valores:

Valor Descrição
Minor Padrão, se não especificado.
Se a versão secundária solicitada estiver ausente, efetue roll forward para a menor versão secundária mais recente. Se a versão secundária solicitada estiver presente, a política LatestPatch será usada.
Major Se a versão principal solicitada estiver ausente, efetuar roll forward para a versão principal mais recente disponível e a versão secundária mais antiga. Se a versão principal solicitada está presente, a política Minor é usada.
LatestPatch Efetuar roll forward para a versão de patch mais recente. Esse valor desabilita o roll forward da versão secundária.
LatestMinor Efetuar roll forward para a versão secundária mais recente, mesmo se a versão secundária solicitada estiver presente.
LatestMajor Efetuar roll forward para a versão principal e a secundária mais recentes, mesmo se a principal solicitada estiver presente.
Disable Não efetuar roll forward, apenas associar à versão especificada. Essa política não é recomendada para uso geral, pois desabilita a capacidade de efetuar roll forward para os patches mais recentes. Esse valor só é recomendado para teste.

Para obter mais informações, confira Comportamento de roll-forward do controle.

RuntimeFrameworkVersion

A propriedade RuntimeFrameworkVersion especifica a versão do runtime a ser usada durante a publicação. Especifique uma versão de runtime:

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

Ao publicar um aplicativo dependente de estrutura, esse valor especifica a versão mínima necessária. Ao publicar um aplicativo autocontido, esse valor especifica a versão exata necessária.

RuntimeIdentifier

A propriedade RuntimeIdentifier permite especificar um identificador de runtime (RID) específico ao projeto. O RID permite a publicação de uma implantação autossuficiente.

<PropertyGroup>
  <RuntimeIdentifier>linux-x64</RuntimeIdentifier>
</PropertyGroup>

RuntimeIdentifiers

A propriedade RuntimeIdentifiers permite especificar uma lista delimitada por ponto e vírgula de RIDs (Identificadores de Runtime) para o projeto. Use essa propriedade se você precisar publicar para vários runtimes. RuntimeIdentifiers é usado no momento da restauração para garantir que os ativos certos estejam no grafo.

Dica

RuntimeIdentifier (singular) pode fornecer compilações mais rápidos quando apenas um único runtime é necessário.

<PropertyGroup>
  <RuntimeIdentifiers>win-x64;osx-x64;linux-x64</RuntimeIdentifiers>
</PropertyGroup>

SatelliteResourceLanguages

A propriedade SatelliteResourceLanguages permite especificar para quais idiomas você quer preservar assemblies de recursos satélite durante a compilação e publicação. Muitos pacotes NuGet incluem assemblies satélite de recursos localizados no pacote principal. Para projetos que fazem referência a esses pacotes NuGet que não exigem recursos localizados, os assemblies localizados podem aumentar desnecessariamente o tamanho de compilação e da saída da publicação. Ao adicionar a propriedade SatelliteResourceLanguages ao arquivo de projeto, somente assemblies localizados para os idiomas especificados serão incluídos na saída de compilação e publicação. Por exemplo, no arquivo de projeto a seguir, somente assemblies satélites de recurso em inglês (EUA) e alemão (Alemanha) serão mantidos.

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

Observação

  • Você precisa especificar essa propriedade no projeto que faz referência ao pacote NuGet com assemblies satélite de recursos localizados.

  • Para especificar vários idiomas como um argumento para dotnet publish, você deve adicionar três pares de aspas ao redor dos identificadores de idioma. Por exemplo:

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

SelfContained

A propriedade SelfContained informa dotnet build e dotnet publish para criar ou publicar um aplicativo como um aplicativo independente. Essa propriedade é útil quando você não pode usar o argumento --self-contained com o comando dotnet, por exemplo, quando você está publicando no nível da solução. Nesse caso, você pode adicionar a propriedade do MSBuild SelfContained a um projeto ou arquivo Directory.Build.Props.

Essa propriedade é semelhante à propriedade PublishSelfContained. É recomendável usar PublishSelfContained em vez de SelfContained quando possível.

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

UseAppHost

A propriedade UseAppHost controla se um executável nativo é criado ou não para uma implantação. Um executável nativo é necessário para implantações autocontidas. Por padrão, é criado um executável dependente da estrutura. Defina a propriedade UseAppHost como false para desabilitar a geração do executável.

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

Para saber mais sobre implantação, confira Implantação no Visual C++.

Várias propriedades do MSBuild estão disponíveis para ajustar o corte, que é um recurso que corta o código não utilizado de implantações autocontidas. Essas opções são discutidas detalhadamente nas Opções de corte. A tabela a seguir fornece uma referência rápida.

Propriedade Valores Descrição
PublishTrimmed true ou false Controla se o corte está habilitado durante a publicação.
TrimMode full ou partial O padrão é full. Controla a granularidade de corte.
SuppressTrimAnalysisWarnings true ou false Controla se os avisos de análise de corte são produzidos.
EnableTrimAnalyzer true ou false Controla se os avisos de análise de corte são produzidos. Você pode habilitar a análise mesmo se PublishTrimmed estiver definido como false.
ILLinkTreatWarningsAsErrors true ou false Controla se os avisos de corte são tratados como erros. Por exemplo, você pode definir essa propriedade para false quando TreatWarningsAsErrors está definido como true.
TrimmerSingleWarn true ou false Controla se um único aviso por assembly é mostrado ou todos os avisos.
TrimmerRemoveSymbols true ou false Controla se todos os símbolos são removidos de um aplicativo cortado.

As seguintes propriedades do MSBuild estão documentadas nesta seção:

As opções do compilador C#, como LangVersion e Nullable, também podem ser especificadas como propriedades do MSBuild em seu arquivo de projeto. Para obter mais informações, confira Opções do compilador C#.

ContinuousIntegrationBuild

A propriedade ContinuousIntegrationBuild indica se um build está sendo executado em um servidor de CI (integração contínua). Quando definida como true, essa propriedade habilita configurações que se aplicam somente a builds oficiais, não a builds locais em um computador do desenvolvedor. Por exemplo, caminhos de arquivo armazenados são normalizados para builds oficiais. No entanto, em um computador de desenvolvimento local, o depurador não poderá encontrar arquivos de origem locais se os caminhos de arquivo forem normalizados.

Observação

Atualmente, definir essa propriedade como true funciona somente se você adicionar uma referência de pacote de provedor SourceLink específica ou um item <SourceRoot Include="$(MyDirectory)" />. Para obter mais informações, consulte o problema dotnet/roslyn 55860.

Você pode usar a variável do sistema de CI para definir condicionalmente a propriedade ContinuousIntegrationBuild. Por exemplo, o nome da variável para o Azure Pipelines é TF_BUILD:

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

Para o GitHub Actions, o nome da variável é GITHUB_ACTIONS:

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

CopyDebugSymbolFilesFromPackages

Quando essa propriedade é definida como true, todos os arquivos de símbolos (também conhecidos como arquivos PDB) dos itens PackageReference no projeto são copiados para a saída da compilação. Esses arquivos podem fornecer rastreamentos de pilha mais informativos para exceções e tornar os despejos de memória e rastreamentos do aplicativo em execução mais fáceis de entender. No entanto, incluir esses arquivos resulta em um tamanho maior do pacote de implantação.

Essa propriedade foi introduzida no .NET SDK 7.0.100, embora o padrão não seja especificado.

CopyDocumentationFilesFromPackages

Quando essa propriedade é definida como true, todos os arquivos de documentação XML gerados de itens PackageReference no projeto são copiados para a saída de compilação. Habilitar esse recurso resultará no aumento do tamanho do pacote de implantação.

Essa propriedade foi introduzida no .NET SDK 7.0.100, embora o padrão não seja especificado.

DisableImplicitFrameworkDefines

A propriedade DisableImplicitFrameworkDefines controla se o SDK gera ou não símbolos de pré-processador para a estrutura de destino e a plataforma do projeto .NET. Quando essa propriedade é definida como false ou não é definida (que é o valor padrão), os símbolos do pré-processador são gerados para:

  • Estrutura sem versão (NETFRAMEWORK, NETSTANDARD, NET)
  • Estrutura com versão (NET48, NETSTANDARD2_0, NET6_0)
  • Estrutura com limite mínimo de versão (NET48_OR_GREATER, NETSTANDARD2_0_OR_GREATER, NET6_0_OR_GREATER)

Para obter mais informações sobre os monikers da estrutura de destino e esses símbolos implícitos de pré-processador, confira Estruturas de destino.

Além disso, se você especificar uma estrutura de destino específica do sistema operacional no projeto (por exemplo net6.0-android), os seguintes símbolos de pré-processador serão gerados:

  • Plataforma sem versão (ANDROID, IOS, WINDOWS)
  • Plataforma com versão (IOS15_1)
  • Plataforma com limite mínimo de versão (IOS15_1_OR_GREATER)

Para obter mais informações sobre monikers de estrutura de destino específicos do sistema operacional, confira TFMs específicos do sistema operacional.

Por fim, se a estrutura de destino implicar compatibilidade com estruturas de destino mais antigas, os símbolos de pré-processador para essas estruturas mais antigas serão emitidos. Por exemplo, net6.0 implica suporte para net5.0 e assim por diante até .netcoreapp1.0. Portanto, para cada uma dessas estruturas de destino, a Estrutura com símbolo de limite mínimo de versão será definida.

DocumentationFile

A propriedade DocumentationFile permite especificar um nome de arquivo para o arquivo XML que contém a documentação da biblioteca. Para que o IntelliSense funcione corretamente com sua documentação, o nome do arquivo precisa ser o mesmo que o nome do assembly e estar no mesmo diretório que o assembly. Se você não especificar essa propriedade, mas definir GenerateDocumentationFile como true, o nome do arquivo de documentação será padrão para o nome do assembly, mas com uma extensão de arquivo .xml. Por esse motivo, geralmente é mais fácil omitir essa propriedade e usar a propriedade GenerateDocumentationFile.

Se você especificar essa propriedade, mas definir GenerateDocumentationFile como false, o compilador não gerará um arquivo de documentação. Se você especificar essa propriedade e omitir a propriedade GenerateDocumentationFile, o compilador gerará um arquivo de documentação.

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

EmbeddedResourceUseDependentUponConvention

A propriedade EmbeddedResourceUseDependentUponConvention define se os nomes de arquivo de manifesto de recurso são gerados a partir de informações de tipo em arquivos de origem que estão localizados junto com arquivos de recurso. Por exemplo, se Form1.resx estiver na mesma pasta que Form1.cs e EmbeddedResourceUseDependentUponConvention for definido como true, o arquivo .resources gerado usará seu nome do primeiro tipo definido em Form1.cs. Se MyNamespace.Form1 for o primeiro tipo definido em Form1.cs, o nome do arquivo gerado será MyNamespace.Form1.resources.

Observação

Se LogicalName, ManifestResourceNameou DependentUpon metadados for especificado para um item EmbeddedResource, o nome do arquivo de manifesto gerado para esse arquivo de recurso será baseado nesses metadados.

Por padrão, em um novo projeto .NET voltado para o .NET Core 3.0 ou uma versão posterior, essa propriedade é definida como true. Se definido como false, e não LogicalName, ManifestResourceNameou DependentUpon, os metadados são especificados para o item EmbeddedResource no arquivo de projeto, o nome do arquivo de manifesto do recurso será baseado no namespace raiz do projeto e no caminho de arquivo relativo para o arquivo .resx. Para obter mais informações, confira Como os arquivos de manifesto de recurso são nomeados.

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

EnablePreviewFeatures

A propriedade EnablePreviewFeatures define se o projeto depende de alguma API ou assemblies que são decorados com o atributo RequiresPreviewFeaturesAttribute. Esse atributo é usado para significar que uma API ou assembly usa recursos considerados em versão prévia para a versão do SDK que você está usando. Recursos de visualização não têm compatibilidade e podem ser removidos em uma versão futura. Para habilitar o uso de recursos de visualização, defina a propriedade como True.

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

Quando um projeto contém essa propriedade definida como True, o seguinte atributo de nível de assembly é adicionado ao arquivo AssemblyInfo.cs:

[assembly: RequiresPreviewFeatures]

Um analisador avisa se esse atributo está presente em dependências para projetos em que EnablePreviewFeatures não está definido como True.

Os autores da biblioteca que pretendem enviar assemblies de visualização devem definir essa propriedade como True. Se um assembly precisar ser enviado com uma mistura de APIs de visualização e não visualização, confira a seção GenerateRequiresPreviewFeaturesAttribute abaixo.

EnableWindowsTargeting

Defina a propriedade EnableWindowsTargeting como true para criar aplicativos do Windows (por exemplo, aplicativos Windows Forms ou Windows Presentation Foundation) em uma plataforma não Windows. Se você não definir essa propriedade como true, receberá o aviso de build NETSDK1100. Esse erro ocorre porque os pacotes de runtime e de destino não são baixados automaticamente nas plataformas que não têm suporte. Ao definir essa propriedade, esses pacotes são baixados durante o direcionamento cruzado.

Observação

Essa propriedade é atualmente recomendada porque permite o desenvolvimento em plataformas diferentes do Windows. No entanto, quando o aplicativo estiver pronto para ser lançado, ele deverá ser criado no Windows. Ao criar em uma plataforma diferente do Windows, a saída pode não ser igual àquela do Windows. Em particular, o executável não é marcado como um aplicativo do Windows (o que significa que sempre abrirá uma janela de console) e não terá um ícone inserido.

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

GenerateDocumentationFile

A propriedade GenerateDocumentationFile controla se o compilador gera um arquivo de documentação XML para sua biblioteca. Se você definir essa propriedade para true e não especificar um nome de arquivo por meio da propriedade DocumentationFile, o arquivo XML gerado será colocado no mesmo diretório de saída que o assembly e terá o mesmo nome de arquivo (mas com extensão .xml).

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

Para obter mais informações sobre como gerar documentação de comentários de código, confira Comentários da documentação XML (C#), Documente seu código com XML (Visual Basic) ou Documente seu código com XML (F#).

GenerateRequiresPreviewFeaturesAttribute

A propriedade GenerateRequiresPreviewFeaturesAttribute está intimamente relacionada à propriedade EnablePreviewFeatures. Se sua biblioteca usar recursos de visualização, mas você não quiser que todo o assembly seja marcado com o atributo, o RequiresPreviewFeaturesAttribute que exigiria que todos os consumidores habilitassem recursos de visualização, defina essa propriedade como False.

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

Importante

Se você definir a propriedade GenerateRequiresPreviewFeaturesAttribute como False, você precisa decorar todas as APIs públicas que dependem de recursos de visualização com RequiresPreviewFeaturesAttribute.

OptimizeImplicitlyTriggeredBuild

Para acelerar o tempo de compilação, compilações que são disparadas implicitamente pela análise de código de ignorar do Visual Studio, incluindo a análise anulável. O Visual Studio dispara uma compilação implícita ao executar testes, por exemplo. No entanto, os builds implícitos são otimizados somente quando TreatWarningsAsErrors não é true. Se você tiver TreatWarningsAsErrors definido como true, mas ainda quiser que os builds disparados implicitamente sejam otimizados, você poderá definir OptimizeImplicitlyTriggeredBuild como True. Para desativar a otimização de build para builds disparados implicitamente, defina OptimizeImplicitlyTriggeredBuild como False.

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

DisableRuntimeMarshalling

A propriedade DisableRuntimeMarshalling habilita você a especificar que gostaria de desabilitar o suporte ao marshalling em runtime para o seu projeto. Se essa propriedade for definida como true, o DisableRuntimeMarshallingAttribute será adicionado ao assembly e qualquer interoperação baseada em delegados ou P/Invokes seguirá as regras para desabilitar o marshalling em runtime.

<PropertyGroup>
    <DisableRuntimeMarshalling>True</DisableRuntimeMarshalling>
</PropertyGroup>

Propriedades de inclusão de item padrão

As seguintes propriedades do MSBuild estão documentadas nesta seção:

Para obter mais informações, confira Inclusões e exclusões padrão.

DefaultItemExcludes

Use a propriedade DefaultItemExcludes para definir padrões glob para arquivos e pastas que devem ser excluídos da inclusão, exclusão e remoção de globs. Por padrão, as pastas ./bin e ./obj são excluídas dos padrões glob.

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

DefaultItemExcludesInProjectFolder

Use a propriedade DefaultItemExcludesInProjectFolder para definir padrões glob para arquivos e pastas na pasta do projeto que devem ser excluídas dos globs de inclusão, exclusão e remoção. Por padrão, as pastas que começam com um ponto (.), como .git e .vs, são excluídas dos padrões glob.

Essa propriedade é muito semelhante à propriedade DefaultItemExcludes, exceto que ela considera apenas arquivos e pastas na pasta do projeto. Quando um padrão glob corresponder involuntariamente a itens fora da pasta do projeto com um caminho relativo, use a propriedade DefaultItemExcludesInProjectFolder em vez de DefaultItemExcludes.

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

EnableDefaultItems

A propriedade EnableDefaultItems controla se itens de compilação, itens de recurso inseridos e itens None são incluídos implicitamente no projeto. O valor padrão é true. Defina a propriedade EnableDefaultItems como false para desabilitar toda a inclusão implícita de arquivos.

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

EnableDefaultCompileItems

A propriedade EnableDefaultCompileItems controla se os itens de compilação são incluídos implicitamente no projeto. O valor padrão é true. Defina a propriedade EnableDefaultCompileItems como false para desabilitar a inclusão implícita de *.cs e outros arquivos de extensão de linguagem.

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

EnableDefaultEmbeddedResourceItems

A propriedade EnableDefaultEmbeddedResourceItems controla se itens de recurso inseridos são incluídos implicitamente no projeto. O valor padrão é true. Defina a propriedade EnableDefaultEmbeddedResourceItems como false para desabilitar a inclusão implícita de arquivos de recursos inseridos.

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

EnableDefaultNoneItems

A propriedade EnableDefaultNoneItems controla se os itens None (arquivos que não têm nenhuma função no processo de build) são incluídos implicitamente no projeto. O valor padrão é true. Defina a propriedade EnableDefaultNoneItems como false para desabilitar a inclusão implícita de itens None.

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

Propriedades de análise de código

As seguintes propriedades do MSBuild estão documentadas nesta seção:

AnalysisLevel

A propriedade AnalysisLevel permite especificar um conjunto de analisadores de código a ser executado de acordo com uma versão do .NET. Cada versão do .NET tem um conjunto de regras de análise de código. Desse conjunto, as regras habilitadas por padrão para essa versão analisam seu código. Por exemplo, se você atualizar do .NET 8 para o .NET 9, mas não quiser que o conjunto padrão de regras de análise de código seja alterado, defina AnalysisLevel como 8.

<PropertyGroup>
  <AnalysisLevel>8</AnalysisLevel>
</PropertyGroup>

Opcionalmente, você pode especificar um valor composto para essa propriedade que também especifica a agressividade das regras. Os valores compostos assumem o formulário <version>-<mode>, em que o valor <mode> é um dos valores de AnalysisMode. O exemplo a seguir usa a preview versão dos analisadores de código e habilita o recommended conjunto de regras.

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

Valor padrão:

  • Se o projeto for direcionado ao .NET 5 ou posterior ou se você tiver adicionado a propriedade AnalysisMode, o valor padrão será latest.
  • Caso contrário, essa propriedade será omitida, a menos que você a adicione explicitamente ao arquivo de projeto.

A tabela a seguir mostra os valores que você pode especificar.

Valor Significado
latest Os analisadores de código mais recentes que foram lançados são usados. Esse é o padrão.
latest-<mode> Os analisadores de código mais recentes que foram lançados são usados. O valor <mode> determina quais regras estão habilitadas.
preview Os analisadores de código mais recentes são usados, mesmo que estejam em versão prévia.
preview-<mode> Os analisadores de código mais recentes são usados, mesmo que estejam em versão prévia. O valor <mode> determina quais regras estão habilitadas.
9.0 O conjunto de regras que estava disponível para a versão do .NET 9 é usado, mesmo que regras mais recentes estejam disponíveis.
9.0-<mode> O conjunto de regras que estava disponível para a versão do .NET 9 é usado, mesmo que regras mais recentes estejam disponíveis. O valor <mode> determina quais regras estão habilitadas.
9 O conjunto de regras que estava disponível para a versão do .NET 9 é usado, mesmo que regras mais recentes estejam disponíveis.
9-<mode> O conjunto de regras que estava disponível para a versão do .NET 9 é usado, mesmo que regras mais recentes estejam disponíveis. O valor <mode> determina quais regras estão habilitadas.
8.0 O conjunto de regras que estava disponível para a versão do .NET 8 é usado, mesmo se regras mais recentes estiverem disponíveis.
8.0-<mode> O conjunto de regras que estava disponível para a versão do .NET 8 é usado, mesmo se regras mais recentes estiverem disponíveis. O valor <mode> determina quais regras estão habilitadas.
8 O conjunto de regras que estava disponível para a versão do .NET 8 é usado, mesmo se regras mais recentes estiverem disponíveis.
8-<mode> O conjunto de regras que estava disponível para a versão do .NET 8 é usado, mesmo se regras mais recentes estiverem disponíveis. O valor <mode> determina quais regras estão habilitadas.
7.0 O conjunto de regras que estava disponível para a versão do .NET 7 é usado, mesmo se regras mais recentes estiverem disponíveis.
7.0-<mode> O conjunto de regras que estava disponível para a versão do .NET 7 é usado, mesmo se regras mais recentes estiverem disponíveis. O valor <mode> determina quais regras estão habilitadas.
7 O conjunto de regras que estava disponível para a versão do .NET 7 é usado, mesmo se regras mais recentes estiverem disponíveis.
7-<mode> O conjunto de regras que estava disponível para a versão do .NET 7 é usado, mesmo se regras mais recentes estiverem disponíveis. O valor <mode> determina quais regras estão habilitadas.

Observação

  • Se você definir EnforceCodeStyleInBuild como true, essa propriedade afetará as regras de estilo de código (IDEXXXX) (além das regras de qualidade de código).
  • Se você definir um valor composto para AnalysisLevel, não precisará especificar um AnalysisMode. No entanto, se você fizer isso, AnalysisLevel terá precedência sobre AnalysisMode.
  • Essa propriedade não tem nenhum efeito na análise de código em projetos que não fazem referência a um SDK do projeto, por exemplo, projetos de .NET Framework herdados que fazem referência ao pacote NuGet Microsoft.CodeAnalysis.NetAnalyzers.

AnalysisLevel<Category>

Essa propriedade é igual a AnalysisLevel, exceto que se aplica apenas a uma categoria específica de regras de análise de código. Essa propriedade permite usar uma versão diferente dos analisadores de código para uma categoria específica ou habilitar ou desabilitar regras em um nível diferente para as outras categorias de regra. Se você omitir essa propriedade para uma categoria específica de regras, ela será padrão para o valor AnalysisLevel . Os valores disponíveis são os mesmos para AnalysisLevel.

<PropertyGroup>
  <AnalysisLevelSecurity>preview</AnalysisLevelSecurity>
</PropertyGroup>

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

A tabela a seguir lista o nome da propriedade para cada categoria de regra.

Nome da propriedade Categoria da regra
<AnalysisLevelDesign> Regras de design
<AnalysisLevelDocumentation> Regras de documentação
<AnalysisLevelGlobalization> Regras de globalização
<AnalysisLevelInteroperability> Regras de portabilidade e interoperabilidade
<AnalysisLevelMaintainability> Regras de facilidade de manutenção
<AnalysisLevelNaming> Regras de nomenclatura
<AnalysisLevelPerformance> Regras de desempenho
<AnalysisLevelSingleFile> Regras de aplicativo de arquivo único
<AnalysisLevelReliability> Regras de confiabilidade
<AnalysisLevelSecurity> Regras de segurança
<AnalysisLevelStyle> Regras de estilo de código (IDEXXXX)
<AnalysisLevelUsage> Regras de uso

AnalysisMode

O SDK do .NET é fornecido com todas as regras de qualidade de código "AC". Por padrão, apenas algumas regras são habilitadas como avisos de build em cada versão do .NET. A propriedade AnalysisMode permite personalizar o conjunto de regras habilitados por padrão. Você pode mudar para um modo de análise mais agressivo em que pode recusar regras individualmente ou um modo de análise mais conservador em que pode aceitar regras específicas. Por exemplo, se você quiser habilitar todas as regras como avisos de build, defina o valor como All.

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

A tabela a seguir mostra os valores de opção disponíveis. Eles são listados em ordem crescente do número de regras que habilitam.

Valor Descrição
None Todas as regras estão desabilitadas. Você pode aderir seletivamente a regras individuais para habilitá-las.
Default Modo padrão, no qual certas regras são ativadas como avisos de build, certas regras são habilitadas como sugestões do IDE do Visual Studio e as demais são desabilitadas.
Minimum Modo mais agressivo do que o modo Default. Algumas sugestões altamente recomendadas para a imposição de build são habilitadas como avisos de build. Para ver quais regras isso inclui, inspecione o arquivo %ProgramFiles%/dotnet/sdk/[version]/Sdks/Microsoft.NET.Sdk/analyzers/build/config/analysislevel_[level]_minimum.editorconfig.
Recommended Modo mais agressivo do que o modo Minimum, em que mais regras são habilitadas como avisos de build. Para ver quais regras isso inclui, inspecione o arquivo %ProgramFiles%/dotnet/sdk/[version]/Sdks/Microsoft.NET.Sdk/analyzers/build/config/analysislevel_[level]_recommended.editorconfig.
All Todas as regras são habilitadas como avisos de build*. Você pode recusar seletivamente regras individuais para desabilitá-las.

* As regras a seguir não são habilitadas definindo AnalysisMode como All ou AnalysisLevel como latest-all: CA1017, CA1045, CA1005, CA1014, CA1060 e CA1021 e as regras do analisador de métricas de código (CA1501, CA1502, CA1505, CA1506 e CA1509). Essas regras herdadas podem ser preteridas em uma versão futura. No entanto, você ainda pode habilitá-las individualmente usando uma entrada dotnet_diagnostic.CAxxxx.severity = <severity>.

Observação

  • Se você definir EnforceCodeStyleInBuild como true, essa propriedade afetará as regras de estilo de código (IDEXXXX) (além das regras de qualidade de código).
  • Se você usar um valor composto para AnalysisLevel, por exemplo, <AnalysisLevel>9-recommended</AnalysisLevel>poderá omitir essa propriedade inteiramente. No entanto, se você especificar ambas as propriedades, AnalysisLevel terá precedência sobre AnalysisMode.
  • Essa propriedade não tem nenhum efeito na análise de código em projetos que não fazem referência a um SDK do projeto, por exemplo, projetos de .NET Framework herdados que fazem referência ao pacote NuGet Microsoft.CodeAnalysis.NetAnalyzers.

AnalysisMode<Category>

Introduzida no .NET 6, essa propriedade é igual a AnalysisMode, exceto que se aplica apenas a uma categoria específica de regras de análise de código. Essa propriedade permite habilitar ou desabilitar regras em um nível diferente das outras categorias de regra. Se você omitir essa propriedade para uma categoria específica de regras, ela será padrão para o valor AnalysisMode. Os valores disponíveis são os mesmos para AnalysisMode.

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

A tabela a seguir lista o nome da propriedade para cada categoria de regra.

Nome da propriedade Categoria da regra
<AnalysisModeDesign> Regras de design
<AnalysisModeDocumentation> Regras de documentação
<AnalysisModeGlobalization> Regras de globalização
<AnalysisModeInteroperability> Regras de portabilidade e interoperabilidade
<AnalysisModeMaintainability> Regras de facilidade de manutenção
<AnalysisModeNaming> Regras de nomenclatura
<AnalysisModePerformance> Regras de desempenho
<AnalysisModeSingleFile> Regras de aplicativo de arquivo único
<AnalysisModeReliability> Regras de confiabilidade
<AnalysisModeSecurity> Regras de segurança
<AnalysisModeStyle> Regras de estilo de código (IDEXXXX)
<AnalysisModeUsage> Regras de uso

CodeAnalysisTreatWarningsAsErrors

A propriedade CodeAnalysisTreatWarningsAsErrors permite configurar se os avisos de análise de qualidade de código (CAxxxx) devem ser tratados como avisos e interromper o build. Se você usar o sinalizador -warnaserror ao criar seus projetos, os avisos de análise de qualidade do código .NET também serão tratados como erros. Se você não quiser que os avisos de análise de qualidade de código sejam tratados como erros, você poderá definir a propriedade CodeAnalysisTreatWarningsAsErrors do MSBuild para false no arquivo de projeto.

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

EnableNETAnalyzers

A análise de qualidade do código .NET está habilitada, por padrão, para projetos direcionados ao .NET 5 ou a uma versão posterior. Se você estiver desenvolvendo usando o SDK do .NET 5+, poderá habilitar a análise de código do .NET para projetos no estilo SDK direcionados a versões anteriores do .NET definindo a propriedade EnableNETAnalyzers como true. Para desabilitar a análise de código em qualquer projeto, defina essa propriedade como false.

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

Observação

Essa propriedade se aplica especificamente aos analisadores internos no SDK do .NET 5+. Ela não deve ser usada ao instalar um pacote de análise de código do NuGet.

EnforceCodeStyleInBuild

A análise de estilo de código do .NET está desabilitada, por padrão, no build para todos os projetos do .NET. Você pode habilitar a análise de estilo de código para projetos .NET definindo a propriedade EnforceCodeStyleInBuild como true.

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

Todas as regras de estilo de código configuradas para serem avisos ou erros serão executadas em violações de build e relatório.

_SkipUpgradeNetAnalyzersNuGetWarning

A propriedade _SkipUpgradeNetAnalyzersNuGetWarning permite configurar se você receberá um aviso se estiver usando analisadores de código de um pacote NuGet desatualizado quando comparado com os analisadores de código no SDK do .NET mais recente. O aviso tem essa aparência:

O SDK do .NET tem analisadores mais recentes com a versão “6.0.0” do que a versão “5.0.3” do pacote “Microsoft.CodeAnalysis.NetAnalyzers” fornece. Atualize ou remova essa referência de pacote.

Para remover esse aviso e continuar a usar a versão dos analisadores de código no pacote NuGet, defina _SkipUpgradeNetAnalyzersNuGetWarning como true no seu arquivo de projeto.

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

Propriedades de configuração de execução

Você pode configurar alguns comportamentos de runtime especificando as propriedades do MSBuild no arquivo de projeto do aplicativo. Para obter informações sobre outras maneiras de configurar o comportamento de runtime, confira Definições de configuração de runtime.

AutoreleasePoolSupport

A propriedade AutoreleasePoolSupport configura se cada thread gerenciado recebe uma NSAutoreleasePool implícita ao ser executada em uma plataforma macOS com suporte. Para obter mais informações, consulte AutoreleasePool para threads gerenciados.

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

ConcurrentGarbageCollection

A propriedade ConcurrentGarbageCollection configura se a coleta de lixo em segundo plano (simultânea) está habilitada. Defina o valor como false para desabilitar a coleta de lixo em segundo plano. Para obter mais informações, veja GC em segundo plano.

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

InvariantGlobalization

A propriedade InvariantGlobalization configura se o aplicativo é executado no modo invariável de globalização, o que significa que ele não tem acesso a dados específicos da cultura. Defina o valor como true para executar o modo invariável de globalização. Para obter mais informações, confira o Modo invariável.

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

PredefinedCulturesOnly

No .NET 6 e versões posteriores, a propriedade PredefinedCulturesOnly configura se os aplicativos podem criar culturas diferentes da cultura invariável quando o modo invariável de globalização está habilitado. O padrão é true. Defina o valor como false para permitir a criação de qualquer nova cultura no modo invariável de globalização.

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

Para mais informações, confira Criação de cultura e mapeamento de caso no modo invariável de globalização.

RetainVMGarbageCollection

A propriedade RetainVMGarbageCollection configura o coletor de lixo para colocar segmentos de memória excluídos em uma lista de espera para uso futuro ou liberá-los. Definir o valor como true para instruir o coletor de lixo a colocar os segmentos em uma lista em espera. Para obter mais informações, consulte Reter VM.

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

ServerGarbageCollection

A propriedade ServerGarbageCollection configura se o aplicativo usa a coleta de lixo da estação de trabalho ou a coleta de lixo do servidor. Defina o valor como true para usar a coleta de lixo do servidor. Para obter mais informações, consulte Estação de trabalho versus servidor.

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

ThreadPoolMaxThreads

A propriedade ThreadPoolMaxThreads configura o número máximo de threads para o pool de threads de trabalho. Para obter mais informações, consulte Máximo de threads.

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

ThreadPoolMinThreads

A propriedade ThreadPoolMinThreads configura o número mínimo de threads para o pool de threads de trabalho. Para obter mais informações, consulte Mínimo de threads.

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

TieredCompilation

A propriedade TieredCompilation configura se o compilador JIT (just-in-time) usa compilação em camadas. Defina o valor como false para desabilitar a compilação em camadas. Para mais informações, confira Compilação em camadas.

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

TieredCompilationQuickJit

A propriedade TieredCompilationQuickJit configura se o compilador JIT usa JIT rápido. Defina o valor como false para desabilitar o JIT rápido. Para obter mais informações, consulte JIT rápido.

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

TieredCompilationQuickJitForLoops

A propriedade TieredCompilationQuickJitForLoops configura se o compilador JIT usa JIT rápido em métodos que contêm loops. Defina o valor como true para habilitar o JIT rápido em métodos que contêm loops. Para obter mais informações, consulte JIT rápido para loops.

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

TieredPGO

A propriedade TieredPGO controla se a PGO (otimização guiada por perfil) dinâmica ou em camadas está habilitada. Defina o valor como true para habilitar a PGO em camadas. Para obter mais informações, confira Otimizações guiadas por perfil.

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

UseWindowsThreadPool

A propriedade UseWindowsThreadPool configura se o gerenciamento de threads do pool de threads é delegado ao pool de threads do Windows (somente Windows). O valor padrão é false, e nesse caso é usado o pool de threads do .NET. Para obter mais informações, consulte Pool de threads do Windows.

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

As seguintes propriedades do MSBuild estão documentadas nesta seção:

AssetTargetFallback

A propriedade AssetTargetFallback permite especificar versões de estrutura compatíveis adicionais para referências de projeto e pacotes NuGet. Por exemplo, se você especificar uma dependência de pacote usando PackageReference, mas esse pacote não contiver ativos compatíveis com o TargetFramework dos seus projetos, a propriedade AssetTargetFallback entrará em jogo. A compatibilidade do pacote referenciado é verificada novamente usando cada estrutura de destino especificada em AssetTargetFallback. Essa propriedade substitui a propriedade PackageTargetFallback preterida.

Você pode definir a propriedade AssetTargetFallback como uma ou mais versões de estrutura de destino.

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

DisableImplicitFrameworkReferences

A propriedade DisableImplicitFrameworkReferences controla itens FrameworkReference implícitos ao ter como destino o .NET Core 3.0 e versões posteriores. Ao ter o .NET Core 2.1 ou .NET Standard 2.0 e versões anteriores como destino, ele controla itens implícitos de PackageReference para pacotes em um metapacote. (Um metapacote é um pacote baseado em estrutura que consiste apenas em dependências em outros pacotes). Essa propriedade também controla referências implícitas, como System e System.Core ao ter .NET Framework como destino.

Configure essa propriedade como true para desabilitar itens implícitos de FrameworkReference ou PackageReference. Se você definir essa propriedade como true, poderá adicionar referências explícitas apenas às estruturas ou pacotes necessários.

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

DisableTransitiveFrameworkReferenceDownloads

Defina a propriedade DisableTransitiveFrameworkReferenceDownloads como true para evitar o download de runtime extra e pacotes de direcionamento que não fazem referência diretamente pelo seu projeto.

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

DisableTransitiveProjectReferences

A propriedade DisableTransitiveProjectReferences controla referências implícitas do projeto. Defina essa propriedade como true para desabilitar itens ProjectReference implícitos. Desabilitar as referências implícitas do projeto resulta em um comportamento não transitivo semelhante ao sistema de projeto legado.

Quando essa propriedade é true, ela tem um efeito semelhante ao de definir PrivateAssets="All" em todas as dependências do projeto dependente.

Se você definir essa propriedade como true, poderá adicionar referências explícitas apenas aos projetos necessários.

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

ManagePackageVersionsCentrally

A propriedade ManagePackageVersionsCentrally foi introduzida no .NET 7. Ao defini-la como true em um arquivo Directory.Packages.props na raiz do repositório, você pode gerenciar dependências comuns nos projetos de um local. Adicione versões para dependências de pacote comuns usando itens PackageVersion no arquivo Directory.Packages.props. Em seguida, nos arquivos de projeto individuais, você pode omitir atributos Version de todos os itens PackageReference que se referem a pacotes gerenciados centralmente.

Exemplo arquivo Directory.Packages.props:

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

Arquivo de projeto individual:

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

Para obter mais informações, confira CPM (gerenciamento central de pacotes).

Restaurar um pacote referenciado instala todas as suas dependências diretas e todas as dependências dessas dependências. Você pode personalizar a restauração do pacote especificando propriedades, como RestorePackagesPath e RestoreIgnoreFailedSources. Para obter mais informações sobre essas e outras propriedades, confira destino de restauração.

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

UseMauiEssentials

Defina a propriedade UseMauiEssentials como true para declarar uma referência explícita a um projeto ou pacote que depende do MAUI Essentials. Essa configuração garante que o projeto efetue pull na referência de estrutura conhecida correta para o MAUI Essentials. Se o projeto fizer referência a um projeto que usa o MAUI Essentials, mas você não definir essa propriedade como true, você pode encontrar um aviso de build NETSDK1186.

<PropertyGroup>
  <UseMauiEssentials>true</UseMauiEssentials>
</PropertyGroup>

ValidateExecutableReferencesMatchSelfContained

A propriedade ValidateExecutableReferencesMatchSelfContained pode ser usada para desabilitar erros relacionados a referências de projeto executáveis. Se o .NET detectar que um projeto executável independente faz referência a um projeto executável dependente da estrutura ou vice-versa, ele gerará erros NETSDK1150 e NETSDK1151, respectivamente. Para evitar esses erros quando a referência for intencional, defina a propriedade ValidateExecutableReferencesMatchSelfContained como false.

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

WindowsSdkPackageVersion

A propriedade WindowsSdkPackageVersion pode ser usada para substituir a versão do pacote de direcionamento do SDK do Windows. Essa propriedade foi introduzida no .NET 5 e substitui o uso do item FrameworkReference para essa finalidade.

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

Observação

Não recomendamos substituir a versão do SDK do Windows, pois os pacotes de direcionamento do SDK do Windows estão incluídos no SDK do .NET 5+. Em vez disso, para fazer referência ao pacote mais recente do SDK do Windows, atualize sua versão do SDK do .NET. Essa propriedade só deve ser usada em casos raros, como ao usar pacotes de visualização ou quando há necessidade de substituir a versão do C#/WinRT.

As seguintes propriedades são usadas para iniciar um aplicativo com o comando dotnet run:

RunArguments

A RunArguments propriedade define os argumentos que são passados para o aplicativo quando ele é executado.

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

Dica

Você pode especificar argumentos adicionais a serem passados para o aplicativo usando a opção -- para dotnet run.

RunWorkingDirectory

A propriedade RunWorkingDirectory define o diretório de trabalho para o processo de aplicativo a ser iniciado. Pode ser um caminho absoluto ou um caminho relativo ao diretório do projeto. Se você não especificar um diretório, OutDir será usado como o diretório de trabalho.

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

As seguintes propriedades do MSBuild estão documentadas nesta seção:

SdkAnalysisLevel

Introduzida no .NET 9, a SdkAnalysisLevel propriedade pode ser usada para configurar o quão rigorosas são as ferramentas do SDK. Ele ajuda você a gerenciar os níveis de aviso do SDK em situações em que talvez você não consiga fixar SDKs por meio de global.json ou outros meios. Você pode usar essa propriedade para dizer a um SDK mais recente para se comportar como se fosse um SDK mais antigo, em relação a uma ferramenta ou recurso específico, sem precisar instalar o SDK mais antigo.

Os valores permitidos dessa propriedade são bandas de recursos do SDK, por exemplo, 8.0.100 e 8.0.400. O valor padrão é a banda de recursos do SDK do SDK em execução. Por exemplo, para o SDK 9.0.102, o valor seria 9.0.100. (Para obter informações sobre como o SDK do .NET tem controle de versão, consulte Como o .NET tem controle de versão.)

<PropertyGroup>
  <SdkAnalysisLevel>8.0.400</SdkAnalysisLevel>
</PropertyGroup>

Para obter mais informações, consulte Propriedade e uso do nível de análise do SDK.

Testar propriedades relacionadas ao projeto

As seguintes propriedades do MSBuild estão documentadas nesta seção:

ÉTestProject

A IsTestProject propriedade significa que um projeto é um projeto de teste. Quando essa propriedade é definida como true, a validação para verificar se o projeto faz referência a um executável independente é desabilitada. Isso ocorre porque os projetos de teste têm um OutputType of, mas geralmente chamam APIs em um executável referenciado Exe em vez de tentar executar. Além disso, se um projeto fizer referência a um projeto em que IsTestProject está definido como true, o projeto de teste não será validado como uma referência executável.

Essa propriedade é necessária principalmente para o dotnet test cenário e não tem impacto ao usar vstest.console.exe.

Observação

Se o projeto especificar o SDK do MSTest, você não precisará definir essa propriedade. É definido automaticamente. Da mesma forma, essa propriedade é definida automaticamente para projetos que fazem referência ao pacote NuGet Microsoft.NET.Test.Sdk vinculado ao VSTest.

IsTestingPlatformApplication

Quando o projeto faz referência ao pacote Microsoft.Testing.Platform.MSBuild , a configuração IsTestingPlatformApplication como true (que também é o valor padrão, se não for especificado) faz o seguinte:

  • Gera o ponto de entrada para o projeto de teste.
  • Gera o arquivo de configuração.
  • Detecta as extensões.

Definir a propriedade como false desabilita a dependência transitiva do pacote. Uma dependência transitiva é quando um projeto que faz referência a outro projeto que faz referência a um determinado pacote se comporta como se fizesse referência ao pacote. Normalmente, você definiria essa propriedade como false em um projeto que não é de teste que faz referência a um projeto de teste. Para obter mais informações, consulte o erro CS8892.

Se o projeto de teste fizer referência a MSTest, NUnit ou xUnit, essa propriedade será definida com o mesmo valor que EnableMSTestRunner, EnableNUnitRunner ou UseMicrosoftTestingPlatformRunner (para xUnit).

Habilitar[NugetPackageNameWithoutDots]

Use uma propriedade com o padrão Enable[NugetPackageNameWithoutDots] para habilitar ou desabilitar extensões Microsoft.Testing.Platform.

Por exemplo, para habilitar a extensão de despejo de memória (pacote NuGet Microsoft.Testing.Extensions.CrashDump), defina o EnableMicrosoftTestingExtensionsCrashDump true.

Para obter mais informações, consulte Habilitar ou desabilitar extensões.

HabiliteAspireTesting

Ao usar o SDK do projeto MSTest, você pode usar a EnableAspireTesting propriedade para trazer todas as dependências e diretivas padrão using necessárias para testar com Aspire e MSTest. Essa propriedade está disponível no MSTest 3.4 e versões posteriores.

Para obter mais informações, consulte Testar com o .NET Aspire.

EnablePlaywright

Ao usar o SDK do projeto MSTest, você pode usar a EnablePlaywright propriedade para trazer todas as dependências e diretivas padrão using necessárias para testar com Playwright e MSTest. Essa propriedade está disponível no MSTest 3.4 e versões posteriores.

Para obter mais informações, consulte Dramaturgo.

HabilitarMSTestRunner

A EnableMSTestRunner propriedade habilita ou desabilita o uso do executor MSTest. O executor MSTest é uma alternativa leve e portátil ao VSTest. Essa propriedade está disponível no MSTest 3.2 e versões posteriores.

Observação

Se o projeto especificar o SDK do MSTest, você não precisará definir essa propriedade. É definido automaticamente.

AtivarNUnitRunner

A EnableNUnitRunner propriedade habilita ou desabilita o uso do executor NUnit. O corredor NUnit é uma alternativa leve e portátil ao VSTest. Essa propriedade está disponível em NUnit3TestAdapter na versão 5.0 e posterior.

GenerateTestingPlatformEntryPoint

Definir a GenerateTestingPlatformEntryPoint propriedade para false desabilitar a geração automática do ponto de entrada do programa em um projeto de teste MSTest, NUnit ou xUnit. Talvez você queira definir essa propriedade como false quando definir manualmente um ponto de entrada ou quando fizer referência a um projeto de teste de um executável que também tenha um ponto de entrada.

Para obter mais informações, consulte o erro CS8892.

Para controlar a geração do ponto de entrada em um projeto VSTest, use a GenerateProgramFile propriedade.

TestingPlatformCaptureOutput

A TestingPlatformCaptureOutput propriedade controla se toda a saída do console que um executável de teste grava é capturada e oculta do usuário quando você usa dotnet test para executar Microsoft.Testing.Platform testes. Por padrão, a saída do console está oculta. Essa saída inclui o banner, as informações de versão e as informações de teste formatadas. Defina essa propriedade como false para mostrar essas informações junto com a saída do MSBuild.

Para obter mais informações, consulte Mostrar saída completa da plataforma.

TestingPlatformCommandLineArguments

A TestingPlatformCaptureOutput propriedade permite especificar argumentos de linha de comando para o aplicativo de teste quando você usa dotnet test para executar Microsoft.Testing.Platform testes. O snippet de arquivo de projeto a seguir mostra um exemplo.

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

TestingPlatformDotnetTestSupport

A TestingPlatformDotnetTestSupport propriedade permite especificar se o VSTest é usado quando você usa dotnet test para executar testes. Se você definir essa propriedade como true, o VSTest será desabilitado e todos os Microsoft.Testing.Platform testes serão executados diretamente.

Se você tiver uma solução que contenha projetos de teste VSTest, bem como projetos MSTest, NUnit ou XUnit, deverá fazer uma chamada por modo (ou seja, dotnet test não executará testes do VSTest e das plataformas mais recentes em uma chamada).

TestingPlatformShowTestsFailure

A TestingPlatformShowTestsFailure propriedade permite controlar se uma única falha ou todos os erros em um teste com falha são relatados quando você usa dotnet test para executar testes. Por padrão, as falhas de teste são resumidas em um arquivo .log, e uma única falha por projeto de teste é relatada ao MSBuild. Para mostrar erros por teste com falha, defina essa propriedade como no arquivo de true projeto.

TestingExtensionsProfile

Quando você usa o SDK do projeto MSTest, a TestingExtensionsProfile propriedade permite selecionar um perfil a ser usado. A tabela a seguir mostra os valores permitidos.

Valor Descrição
Default Habilita as extensões recomendadas para esta versão do MSTest.SDK.
None Nenhuma extensão está habilitada.
AllMicrosoft Habilite todas as extensões enviadas pela Microsoft (incluindo extensões com uma licença restritiva).

Para obter mais informações, consulte Perfil do executor MSTest.

UseVSTest

Defina a UseVSTest propriedade como true para alternar do executor do MSTest para o executor do VSTest ao usar o SDK do projeto MSTest.

As seguintes propriedades do MSBuild estão documentadas nesta seção:

AppHostDotNetSearch

A AppHostDotNetSearch propriedade configura como o executável nativo produzido para um aplicativo procurará uma instalação do .NET. Essa propriedade afeta apenas o executável produzido na publicação, não na compilação.

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

A tabela a seguir lista os valores válidos. Você pode especificar vários valores, separados por ponto-e-vírgula.

Valor Significado
AppLocal Pasta do executável do aplicativo
AppRelative Caminho relativo ao executável do aplicativo, conforme especificado por AppHostRelativeDotNet
EnvironmentVariables Valor das variáveis de DOTNET_ROOT[_<arch>] ambiente
Global Locais de instalação globais registrados e padrão

Essa propriedade foi introduzida no .NET 9.

AppHostRelativeDotNet

A AppHostRelativeDotNet propriedade permite especificar um caminho relativo para o executável do aplicativo procurar a instalação do .NET quando ele estiver configurado para fazer isso. Definir a AppHostRelativeDotNet propriedade implica que AppHostDotNetSearch é AppRelative. Essa propriedade afeta apenas o executável produzido na publicação, não na compilação.

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

Essa propriedade foi introduzida no .NET 9.

EnableComHosting

A propriedade EnableComHosting indica que um assembly fornece um servidor COM. Definir EnableComHosting como true também implica que EnableDynamicLoading é true.

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

Para obter mais informações, confira Expor componentes do .NET ao COM.

EnableDynamicLoading

A propriedade EnableDynamicLoading indica que um assembly é um componente carregado dinamicamente. O componente pode ser uma biblioteca COM ou uma biblioteca não COM que pode ser usada de um host nativo ou usada como um plug-in. Definir essa propriedade como true tem os seguintes efeitos:

  • Um arquivo .runtimeconfig.json é gerado.
  • RollForward é definido como LatestMinor.
  • As referências do NuGet são copiadas localmente.
<PropertyGroup>
  <EnableDynamicLoading>true</EnableDynamicLoading>
</PropertyGroup>

Propriedades do arquivo gerado

As seguintes propriedades dizem respeito ao código em arquivos gerados:

DisableImplicitNamespaceImports

A propriedade DisableImplicitNamespaceImports pode ser usada para desabilitar importações implícitas de namespace em projetos do Visual Basic direcionados ao .NET 6 ou a uma versão posterior. Namespaces implícitos são os namespaces padrão importados globalmente em um projeto do Visual Basic. Defina essa propriedade como true para desabilitar importações implícitas de namespace.

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

ImplicitUsings

A propriedade ImplicitUsings pode ser usada para habilitar e desabilitar diretivas global using implícitas em projetos C# direcionados ao .NET 6 ou a uma versão posterior e ao C# 10 ou uma versão posterior. Quando o recurso está habilitado, o SDK do .NET adiciona diretivas global using a um conjunto de namespaces padrão com base no tipo de SDK do projeto. Defina essa propriedade como true ou enable para habilitar diretivas global using implícitas. Para desabilitar as diretivas global using implícitas, remova a propriedade ou defina-a como false ou disable.

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

Observação

Os modelos para novos projetos em C# direcionados ao .NET 6 ou posteriores têm ImplicitUsings definido como enable por padrão.

Para definir uma diretiva global using explícita, adicione um item Using.

Itens

Itens do MSBuild são entradas no sistema de compilação. Os itens são especificados de acordo com o tipo, que é o nome do elemento. Por exemplo, Compile e Reference são dois tipos de item comuns. Os seguintes tipos de item adicionais são disponibilizados pelo SDK do .NET:

Você pode usar qualquer um dos atributos de item padrão, por exemplo, Include e Update, nesses itens. Use Include para adicionar um novo item e Update para modificar um item existente. Por exemplo, geralmente Update é usado para modificar um item adicionado implicitamente pelo SDK do .NET.

AssemblyMetadata

O item AssemblyMetadata especifica um atributo de assembly AssemblyMetadataAttribute de par chave-valor. Os metadados Include se tornam a chave e os metadados Value se tornam o valor.

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

InternalsVisibleTo

O item InternalsVisibleTo gera um atributo de assembly InternalsVisibleToAttribute para o assembly amigo especificado.

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

Se o assembly amigável estiver assinado, você poderá especificar metadados Key opcionais para especificar sua chave pública completa. Se você não especificar metadados Key e $(PublicKey) estiver disponível, essa chave será usada. Caso contrário, nenhuma chave pública será adicionada ao atributo.

FrameworkReference

O item FrameworkReference define uma referência a uma estrutura compartilhada do .NET.

O atributo Include especifica a ID da estrutura.

O snippet do arquivo do projeto no exemplo a seguir faz referência à estrutura compartilhada Microsoft.AspNetCore.App.

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

PackageReference

O item PackageReference define uma referência a um pacote NuGet.

O atributo Include especifica a ID do pacote. O atributo Version especifica a versão ou o intervalo de versão. Para obter informações sobre como especificar uma versão mínima, versão máxima, intervalo ou correspondência exata, consulte intervalos de versão.

O snippet de arquivo de projeto no exemplo a seguir faz referência ao pacote System.Runtime.

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

Você também pode controlar ativos de dependência usando metadados como PrivateAssets.

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

Para obter mais informações, consulte Referências de pacote em arquivos de projeto.

TrimmerRootAssembly

O item TrimmerRootAssembly permite excluir um assembly do corte. O corte é o processo de remover partes não utilizadas do runtime de um aplicativo empacotado. Em alguns casos, o corte pode remover incorretamente as referências necessárias.

O XML a seguir exclui o assembly System.Security do corte.

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

Para obter mais informações, consulte Opções de corte.

Usar

O item Using permite incluir globalmente um namespace no seu projeto C#, de modo que você não precise adicionar uma diretiva using para o namespace na parte superior dos arquivos de origem. Esse item é semelhante ao item Import que pode ser usado para a mesma finalidade em projetos do Visual Basic. Essa propriedade está disponível a partir do .NET 6.

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

Você também pode usar o item Using para definir diretivas using <alias> e using static <type> globais.

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

Por exemplo:

  • <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 saber mais, confira diretivas using com alias e diretivas using static <type>.

Metadados do item

Além dos atributos de item padrão do MSBuild, as seguintes marcas de metadados de item são disponibilizadas pelo SDK do .NET:

CopyToPublishDirectory

Os metadados CopyToPublishDirectory em um item do MSBuild controlam quando o item é copiado para o diretório de publicação. Os valores permitidos são PreserveNewest, que só copia o item se ele tiver sido alterado, Always, que sempre copia o item e Never, que nunca copia o item. Do ponto de vista do desempenho, PreserveNewest é preferível porque habilita um build incremental.

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

LinkBase

Para um item que está fora do diretório do projeto e seus subdiretórios, o destino de publicação usa os metadados de link do item para determinar para onde copiar o item. Link também determina como os itens fora da árvore de projeto são exibidos na janela Gerenciador de Soluções do Visual Studio.

Se Link não for especificado para um item fora do cone do projeto, ele terá o valor padrão, %(LinkBase)\%(RecursiveDir)%(Filename)%(Extension). LinkBase permite especificar uma pasta base sensível para itens fora do cone do projeto. A hierarquia de pastas na pasta base é preservada por meio de RecursiveDir. Se LinkBase não for especificado, ele será omitido do caminho Link.

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

A imagem a seguir mostra como um arquivo incluído por meio do glob de item Include anterior é exibido no Gerenciador de Soluções.

O Gerenciador de Soluções mostra o item com metadados do LinkBase.

Confira também