Partilhar via

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

  • Artigo

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

Nota

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 de propriedades comuns do MSBuild, consulte Propriedades comuns do MSBuild.

Propriedades de validação de montagem

Essas propriedades e itens são passados para a ValidateAssemblies tarefa. Para obter mais informações sobre validação de assembly, consulte Assembly validation.

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

Nota

Essas propriedades não fazem parte do SDK do .NET (ainda). Para usá-los, você também deve adicionar um PackageReference a Microsoft.DotNet.ApiCompat.Task.

Além disso, as seguintes propriedades documentadas nas propriedades de validação de pacote também se aplicam à validação de assembly:

ApiCompatStrictMode

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

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

ApiCompatValidateAssemblies

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

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

Propriedades do atributo Assembly

GenerateAssemblyInfo

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

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

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

Quando o GenerateAssemblyInfo valor é true, as propriedades do 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, consulte Definir atributos de assembly em um arquivo de projeto.

GeneratedAssemblyInfoFile

A GeneratedAssemblyInfoFile propriedade define o caminho relativo ou absoluto do arquivo de informações do assembly gerado. O padrão é um arquivo chamado [project-name]. AssemblyInfo. [CS|VB]$(IntermediateOutputPath) no diretório (geralmente o obj).

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

Propriedades da estrutura

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

TargetFramework

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

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

Para obter mais informações, consulte Estruturas de destino em projetos no estilo SDK.

TargetFrameworks

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

Nota

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

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

Para obter mais informações, consulte Estruturas de destino em projetos no estilo SDK.

NetStandardImplicitPackageVersion

Nota

Esta propriedade só se aplica a projetos que usam netstandard1.xo . Não se aplica a projetos que usam netstandard2.xo .

Use a NetStandardImplicitPackageVersion propriedade quando quiser especificar uma versão do framework que seja inferior à versão do metapacote. O arquivo de projeto no exemplo a seguir tem como destino 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, , PackageIconTitle, e Description descrever o pacote que é criado a partir do seu projeto. Para obter informações sobre essas e outras propriedades, consulte Destino do pacote.

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

PackRelease

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

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

Nota

  • A partir do SDK do .NET 8, PackRelease o padrão é true. Para obter mais informações, consulte 'dotnet pack' usa a configuração de versão.
  • Somente SDK do .NET 7: Para usar PackRelease em um projeto que faz parte de uma solução do Visual Studio, você deve definir a variável DOTNET_CLI_ENABLE_PACK_RELEASE_FOR_SOLUTIONS de ambiente como true (ou qualquer outro valor). Para soluções que têm muitos projetos, definir essa variável aumenta o tempo necessário para empacotar.

Propriedades de validação do pacote

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

Para obter as propriedades da tarefa, consulte ValidateAssemblies de validação de assembly.

As seguintes propriedades e itens do MSBuild estão documentados nesta seção:

ApiCompatEnableRuleAttributesMustMatch

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

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

ApiCompatEnableRuleCannotChangeParameterName

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

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

ApiCompatExcludeAttributesFile

O ApiCompatExcludeAttributesFile item 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 ApiCompatGenerateSuppressionFile propriedade especifica se um arquivo de supressão de compatibilidade deve ser gerado.

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

ApiCompatPermitDesnecessárioSupressões

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

A predefinição é false.

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

ApiCompatPreserveDesnecessárioSupressões

A ApiCompatPreserveUnnecessarySuppressions propriedade especifica se as 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, em seguida, 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) definindo essa propriedade como true.

A predefinição é false.

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

ApiCompatRespectInternals

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

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

ApiCompatSuppressionFile

O ApiCompatSuppressionFile item especifica o caminho para um ou mais arquivos de supressão para leitura. 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 ApiCompatSuppressionOutputFile propriedade especifica o caminho para um arquivo de supressão para gravar quando <ApiCompatGenerateSuppressionFile> é true. Se não for especificado, o primeiro ApiCompatSuppressionFile item é usado.

EnablePackageValidation

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

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

EnableStrictModeForBaselineValidation

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

EnableStrictModeForCompatibleFrameworksInPackage

Quando definida como true, a propriedade habilita EnableStrictModeForCompatibleFrameworksInPackage estrito para assemblies que são compatíveis com base em sua estrutura de destino. A predefinição é false.

EnableStrictModeForCompatibleTfms

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

NãoAvisar

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

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

PackageValidationBaselineFrameworkToIgnore

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

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

PackageValidationBaselineName

A PackageValidationBaselineName propriedade especifica o nome do pacote de linha de base para validar o pacote atual. Se não for especificado, o PackageId valor é usado.

PackageValidationBaselineVersion

A PackageValidationBaselineVersion propriedade especifica a versão do pacote de linha de base para validar o pacote atual.

PackageValidationReferencePath

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

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

RoslynAssembliesPath

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

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

AppendTargetFrameworkToOutputPath

A AppendTargetFrameworkToOutputPath propriedade controla se o moniker da estrutura de destino (TFM) é anexado ao caminho de saída (que é definido por OutputPath). O SDK .NET acrescenta automaticamente a estrutura de destino e, se presente, o identificador de tempo de execução ao caminho de saída. Configuração AppendTargetFrameworkToOutputPath para false impedir que o TFM seja anexado 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 com bin\Debug a seguinte configuração:

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

AppendRuntimeIdentifierToOutputPath

A AppendRuntimeIdentifierToOutputPath propriedade controla se o identificador de tempo de execução (RID) é anexado ao caminho de saída. O SDK .NET acrescenta automaticamente a estrutura de destino e, se presente, o identificador de tempo de execução ao caminho de saída. Configuração AppendRuntimeIdentifierToOutputPath para false impedir que o RID seja anexado ao caminho de saída.

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

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

CopyLocalLockFileAssemblies

A CopyLocalLockFileAssemblies propriedade é útil para projetos de plug-in que têm dependências de 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 para executar seu plugin em qualquer máquina.

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

O valor padrão de pode variar com base no 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.

Gorjeta

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

ErrorOnDuplicatePublishOutputFiles

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

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

Esta propriedade foi introduzida no .NET 6.

GenerateRuntimeConfigDevFile

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

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

GenerateRuntimeConfigurationFiles

A GenerateRuntimeConfigurationFiles propriedade controla se as opções de configuração de tempo de execução são copiadas do arquivo runtimeconfig.template.json para o arquivo [appname].runtimeconfig.json . Para aplicativos que exigem um arquivo runtimeconfig.json , ou seja, aqueles cujo OutputType é Exe, essa propriedade assume como truepadrão .

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

GerarSatelliteAssembliesForCore

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

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

IsPublishable

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

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

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

PreserveCompilationContext

A PreserveCompilationContext propriedade permite que um aplicativo criado ou publicado compile mais código em tempo de execução usando as mesmas configurações que foram usadas em tempo de compilação. Os assemblies referenciados no momento da 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 junto com as opções passadas para o compilador. Você pode recuperar essas informações usando as DependencyContext.CompileLibraries propriedades e DependencyContext.CompilationOptions .

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

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

PreserveCompilationReferences

A PreserveCompilationReferences propriedade é 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, consulte Propriedades do SDK do Razor.

ProduceReferenceAssemblyInOutDir

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

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

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

PublishDocumentationFile

Quando essa propriedade é true, o arquivo de documentação XML para o projeto, se for gerado, é incluído na saída de publicação para o projeto. O padrão desta propriedade é true.

Gorjeta

Defina GenerateDocumentationFile como true para gerar um arquivo de documentação XML em tempo de compilação.

PublishDocumentationFiles

Esta 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 como true. O padrão desta propriedade é 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. O padrão desta propriedade é true.

PublicarLançamento

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

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

Nota

  • A partir do SDK do .NET 8, PublishRelease o padrão é para true projetos destinados ao .NET 8 ou posterior. Para obter mais informações, consulte 'dotnet publish' usa a configuração de versão.
  • Essa propriedade não afeta o comportamento do , e só altera a configuração somente ao publicar por meio da dotnet build /t:PublishCLI do .NET.
  • Somente SDK do .NET 7: Para usar PublishRelease em um projeto que faz parte de uma solução do Visual Studio, você deve definir a variável DOTNET_CLI_ENABLE_PUBLISH_RELEASE_FOR_SOLUTIONS de ambiente como true (ou qualquer outro valor). Ao publicar uma solução com essa variável habilitada, o valor do PublishRelease 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 PublishSelfContained propriedade informa dotnet publish para publicar um aplicativo como um aplicativo independente. Essa propriedade é útil quando você não pode usar o --self-contained argumento para o comando dotnet publish — por exemplo, quando você está publicando no nível da solução. Nesse caso, você pode adicionar a PublishSelfContained propriedade MSBuild a um projeto ou arquivo Directory.Build.Props .

Esta propriedade foi introduzida no .NET 7. É semelhante à propriedade SelfContained , exceto que é específica para o verbo publish . Recomenda-se usar PublishSelfContained em vez de SelfContained.

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

RollForward

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

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

Defina RollForward como um dos seguintes valores:

valor Description
Minor Padrão se não especificado.
Roll-forward para a versão secundária superior mais baixa, se a versão secundária solicitada estiver ausente. Se a versão secundária solicitada estiver presente, a LatestPatch política será usada.
Major Avançar para a próxima versão principal superior disponível e para a versão secundária mais baixa, se a versão principal solicitada estiver ausente. Se a versão principal solicitada estiver presente, a Minor política será usada.
LatestPatch Roll-forward para a versão de patch mais alta. Esse valor desabilita o roll-forward da versão secundária.
LatestMinor Avançar para a versão secundária mais alta, mesmo que a versão secundária solicitada esteja presente.
LatestMajor Roll-forward para a versão principal mais alta e a versão secundária mais alta, mesmo que a versão principal solicitada esteja presente.
Disable Não faça roll-forward, apenas vincule-se à versão especificada. Esta política não é recomendada para uso geral, uma vez que desativa a capacidade de avançar para os patches mais recentes. Este valor só é recomendado para testes.

Para obter mais informações, consulte Controlar o comportamento de roll-forward.

RuntimeFrameworkVersion

A RuntimeFrameworkVersion propriedade especifica a versão do tempo de execução a ser usada ao publicar. Especifique uma versão de tempo de execução:

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

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

RuntimeIdentifier

A RuntimeIdentifier propriedade permite especificar um único identificador de tempo de execução (RID) para o projeto. O RID permite publicar uma implantação independente.

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

RuntimeIdentifiers

A RuntimeIdentifiers propriedade permite especificar uma lista delimitada por ponto-e-vírgula de identificadores de tempo de execução (RIDs) para o projeto. Use essa propriedade se precisar publicar para vários tempos de execução. RuntimeIdentifiers é usado no momento da restauração para garantir que os ativos certos estejam no gráfico.

Gorjeta

RuntimeIdentifier (singular) pode fornecer compilações mais rápidas quando apenas um único tempo de execução é necessário.

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

SatelliteResourceLanguages

A SatelliteResourceLanguages propriedade permite especificar para quais idiomas você deseja 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 inflar desnecessariamente o tamanho de saída de compilação e publicação. Ao adicionar a SatelliteResourceLanguages propriedade ao seu 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 recursos em inglês (EUA) e alemão (Alemanha) serão mantidos.

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

Nota

  • Você deve 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 o 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"""

Autônomo

A SelfContained propriedade 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 --self-contained argumento com o comando dotnet — por exemplo, quando você está publicando no nível da solução. Nesse caso, você pode adicionar a SelfContained propriedade MSBuild a um projeto ou arquivo Directory.Build.Props .

Esta propriedade é semelhante à propriedade PublishSelfContend . Recomenda-se usar PublishSelfContained em vez de SelfContained quando possível.

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

UseAppHost

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

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

Para obter mais informações sobre implantação, consulte Implantação de aplicativos .NET.

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 independentes. Essas opções são discutidas em detalhes em Opções de corte. A tabela a seguir fornece uma referência rápida.

Property Valores Description
PublishTrimmed true ou false Controla se o corte está habilitado durante a publicação.
TrimMode full ou partial A predefiniçã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 um subconjunto de avisos de análise de corte é produzido. 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, talvez você queira definir essa propriedade como false quando TreatWarningsAsErrors estiver definida como true.
TrimmerSingleWarn true ou false Controla se um único aviso por montagem é 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 no arquivo de projeto. Para obter mais informações, consulte Opções do compilador C#.

Integração contínuaConstruir

A ContinuousIntegrationBuild propriedade indica se uma compilação está sendo executada em um servidor de integração contínua (CI). Quando definida como true, essa propriedade habilita configurações que se aplicam apenas a compilações oficiais, em vez de compilações locais em uma máquina de desenvolvedor. Por exemplo, os caminhos de arquivo armazenados são normalizados para compilações oficiais. Mas em uma máquina de desenvolvimento local, o depurador não é capaz de encontrar arquivos de origem locais se os caminhos de arquivo forem normalizados.

Nota

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

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

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

Para Ações do GitHub, 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ímbolo (também conhecidos como arquivos PDB) de PackageReference itens 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 despejos de memória e rastreamentos do aplicativo em execução mais fáceis de entender. No entanto, a inclusão desses arquivos resulta em um 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.

CopyDocumentationFilesFromPackages

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

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

DisableImplicitFrameworkDefine

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

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

Para obter mais informações sobre monikers de estrutura de destino e esses símbolos implícitos de pré-processador, consulte 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, consulte TFMs específicos do sistema operacional.

Finalmente, se sua estrutura de destino implicar suporte para estruturas de destino mais antigas, símbolos de pré-processador para essas estruturas mais antigas serão emitidos. Por exemplo, net6.0implica apoio para net5.0 e assim por diante todo o caminho de volta para .netcoreapp1.0. Assim, para cada uma dessas estruturas de destino, o Framework com o símbolo de limite mínimo de versão será definido.

DocumentaçãoArquivo

A DocumentationFile propriedade 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 deve ser o mesmo que o nome do assembly e deve estar no mesmo diretório do assembly. Se você não especificar essa propriedade, mas definir GenerateDocumentationFile como , o nome do arquivo de documentação assumirá como padrão o nome do assembly, mas com uma true. Por esse motivo, muitas vezes é 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 EmbeddedResourceUseDependentUponConvention propriedade define se os nomes de arquivo de manifesto de recursos são gerados a partir de informações de tipo em arquivos de origem que são colocalizados com arquivos de recurso. Por exemplo, se Form1.resx estiver na mesma pasta que Form1.cs e EmbeddedResourceUseDependentUponConvention estiver definido como true, o arquivo .resources gerado terá seu nome do primeiro tipo definido em Form1.cs. Se MyNamespace.Form1 for o primeiro tipo definido no Form1.cs, o nome do arquivo gerado será MyNamespace.Form1.resources.

Nota

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

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

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

EnablePreviewFeatures

A EnablePreviewFeatures propriedade define se seu projeto depende de quaisquer APIs ou assemblies decorados com o RequiresPreviewFeaturesAttribute atributo. Esse atributo é usado para indicar que uma API ou assembly usa recursos que são considerados em visualização para a versão do SDK que você está usando. As funcionalidades de pré-visualização não são suportadas e podem ser removidas numa 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 onde EnablePreviewFeatures não está definido como True.

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

HabilitarWindowsTargeting

Defina a EnableWindowsTargeting propriedade como true para criar aplicativos do Windows (por exemplo, aplicativos Windows Forms ou Windows Presentation Foundation) em uma plataforma que não seja Windows. Se você não definir essa propriedade como true, receberá um aviso de compilação NETSDK1100. Este erro ocorre porque os pacotes de segmentação e de tempo de execução não são baixados automaticamente em plataformas que não são suportadas. Ao definir essa propriedade, esses pacotes são baixados durante a segmentação cruzada.

Nota

Esta propriedade é atualmente recomendada para permitir o desenvolvimento em plataformas não-Windows. Mas quando o aplicativo estiver pronto para ser lançado, ele deve ser construído no Windows. Ao criar em uma plataforma que não seja Windows, a saída pode não ser a mesma que ao criar no Windows. Em particular, o executável não está marcado como um aplicativo do Windows (o que significa que ele sempre iniciará uma janela do console) e não terá um ícone incorporado.

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

GenerateDocumentationFile

A GenerateDocumentationFile propriedade controla se o compilador gera um arquivo de documentação XML para sua biblioteca. Se você definir essa propriedade como 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 do assembly e terá o mesmo nome de arquivo (mas com uma extensão .xml ).

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

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

GenerateRequiresPreviewFeaturesAttribute

A GenerateRequiresPreviewFeaturesAttribute propriedade está intimamente relacionada com a propriedade EnablePreviewFeatures . Se sua biblioteca usa recursos de visualização, mas você não deseja que o assembly inteiro seja marcado com o atributo, o RequiresPreviewFeaturesAttribute que exigiria que qualquer consumidor habilitasse os recursos de visualização, defina essa propriedade como False.

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

Importante

Se você definir a GenerateRequiresPreviewFeaturesAttribute propriedade como False, deverá ter certeza de decorar todas as APIs públicas que dependem de recursos de visualização com RequiresPreviewFeaturesAttributeo .

OptimizeImplicitlyTriggeredBuild

Para acelerar o tempo de compilação, compilações que são implicitamente acionadas pelo Visual Studio ignoram a análise de código, incluindo a análise anulável. Visual Studio dispara uma compilação implícita quando você executa testes, por exemplo. No entanto, compilações implícitas são otimizadas apenas quando TreatWarningsAsErrors não trueé . Se você definiu TreatWarningsAsErrors como true mas ainda deseja que compilações acionadas implicitamente sejam otimizadas, você pode definir OptimizeImplicitlyTriggeredBuild como True. Para desativar a otimização de compilação para compilações acionadas implicitamente, defina OptimizeImplicitlyTriggeredBuild como False.

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

DisableRuntimeMarshalling

A DisableRuntimeMarshalling propriedade permite que você especifique que gostaria de desabilitar o suporte de empacotamento de tempo de execução para seu projeto. Se essa propriedade for definida como true, então a será adicionada DisableRuntimeMarshallingAttribute ao assembly e qualquer interoperabilidade baseada em P/Invokes ou delegada seguirá as regras para empacotamento de tempo de execução desabilitado.

<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, consulte Inclui e exclui padrão.

DefaultItemExclui

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

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

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

EnableDefaultItems

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

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

EnableDefaultCompileItems

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

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

EnableDefaultEmbeddedResourceItems

A EnableDefaultEmbeddedResourceItems propriedade controla se os itens de recursos incorporados são incluídos implicitamente no projeto. O valor predefinido é true. Defina a propriedade como EnableDefaultEmbeddedResourceItems para desativar a false inclusão implícita de arquivos de recursos incorporados.

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

EnableDefaultNoneItems

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

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

Propriedades de análise de código

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

Nível de Análise

A AnalysisLevel propriedade permite especificar um conjunto de analisadores de código para executar 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 o quão agressivamente habilitar regras. Os valores compostos assumem a forma <version>-<mode>, onde o <mode> valor é um dos valores 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 predefinido:

  • Se o seu projeto tem como destino o .NET 5 ou posterior, ou se você adicionou a propriedade AnalysisMode , o valor padrão é 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. Esta é a predefinição.
latest-<mode> Os analisadores de código mais recentes que foram lançados são usados. O <mode> valor determina quais regras estão habilitadas.
preview Os analisadores de código mais recentes são usados, mesmo que estejam em visualização.
preview-<mode> Os analisadores de código mais recentes são usados, mesmo que estejam em visualização. O <mode> valor determina quais regras estão habilitadas.
9.0 O conjunto de regras que estava disponível para a versão .NET 9 é usado, mesmo se regras mais recentes estiverem disponíveis.
9.0-<mode> O conjunto de regras que estava disponível para a versão .NET 9 é usado, mesmo se regras mais recentes estiverem disponíveis. O <mode> valor determina quais regras estão habilitadas.
9 O conjunto de regras que estava disponível para a versão .NET 9 é usado, mesmo se regras mais recentes estiverem disponíveis.
9-<mode> O conjunto de regras que estava disponível para a versão .NET 9 é usado, mesmo se regras mais recentes estiverem disponíveis. O <mode> valor 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 que regras mais recentes estejam disponíveis.
8.0-<mode> O conjunto de regras que estava disponível para a versão do .NET 8 é usado, mesmo que regras mais recentes estejam disponíveis. O <mode> valor determina quais regras estão habilitadas.
8 O conjunto de regras que estava disponível para a versão do .NET 8 é usado, mesmo que regras mais recentes estejam disponíveis.
8-<mode> O conjunto de regras que estava disponível para a versão do .NET 8 é usado, mesmo que regras mais recentes estejam disponíveis. O <mode> valor determina quais regras estão habilitadas.
7.0 O conjunto de regras que estava disponível para a versão .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 .NET 7 é usado, mesmo se regras mais recentes estiverem disponíveis. O <mode> valor determina quais regras estão habilitadas.
7 O conjunto de regras que estava disponível para a versão .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 .NET 7 é usado, mesmo se regras mais recentes estiverem disponíveis. O <mode> valor determina quais regras estão habilitadas.

Nota

  • 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 o fizer, AnalysisLevel tem precedência sobre AnalysisMode.
  • Essa propriedade não tem efeito sobre a análise de código em projetos que não fazem referência a um SDK de projeto, por exemplo, projetos herdados do .NET Framework que fazem referência ao pacote NuGet Microsoft.CodeAnalysis.NetAnalyzers.

Categoria AnalysisLevel<>

Essa propriedade é a mesma que AnalysisLevel, exceto que ela só se aplica a uma categoria específica de regras de análise de código. Essa propriedade permite que você use uma versão diferente dos analisadores de código para uma categoria específica ou habilite ou desabilite regras em um nível diferente das outras categorias de regras. Se você omitir essa propriedade para uma categoria específica de regras, ela assumirá como padrão o valor AnalysisLevel . Os valores disponíveis são os mesmos de 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 conceção
<AnalysisLevelDocumentation> Regras de documentação
<AnalysisLevelGlobalization> Regras de globalização
<AnalysisLevelInteroperability> Regras de portabilidade e interoperabilidade
<AnalysisLevelMaintainability> Regras de manutenibilidade
<AnalysisLevelNaming> Regras de nomenclatura
<AnalysisLevelPerformance> Regras de desempenho
<AnalysisLevelSingleFile> Regras de aplicação de ficheiro único
<AnalysisLevelReliability> Regras de fiabilidade
<AnalysisLevelSecurity> Regras de segurança
<AnalysisLevelStyle> Regras de estilo de código (IDEXXXX)
<AnalysisLevelUsage> Regras de utilização

Modo de Análise

O SDK do .NET é fornecido com todas as regras de qualidade de código "CA". Por padrão, apenas algumas regras são habilitadas como avisos de compilação em cada versão do .NET. A AnalysisMode propriedade permite personalizar o conjunto de regras habilitado por padrão. Você pode mudar para um modo de análise mais agressivo, onde você pode optar por não participar de regras individualmente, ou um modo de análise mais conservador, onde você pode optar por regras específicas. Por exemplo, se você quiser habilitar todas as regras como avisos de compilação, 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 Description
None Todas as regras estão desativadas. Você pode optar seletivamente por regras individuais para habilitá-las.
Default Modo padrão, onde certas regras são habilitadas como avisos de compilação, certas regras são habilitadas como sugestões IDE do Visual Studio e o restante é desabilitado.
Minimum Modo mais agressivo do que Default o modo. Certas sugestões que são altamente recomendadas para a imposição de compilação são habilitadas como avisos de compilação. Para ver quais regras isso inclui, inspecione o arquivo %ProgramFiles%de /dotnet/sdk/[version]/Sdks/Microsoft.NET.Sdk/analyzers/build/config/analysislevel_[level]_minimum.globalconfig. (Para o .NET 7 e versões anteriores, a extensão do arquivo é .editorconfig.)
Recommended Modo mais agressivo do que o modo, onde mais regras são ativadas Minimum como avisos de compilação. Para ver quais regras isso inclui, inspecione o arquivo %ProgramFiles%de /dotnet/sdk/[version]/Sdks/Microsoft.NET.Sdk/analyzers/build/config/analysislevel_[level]_recommended.globalconfig. (Para o .NET 7 e versões anteriores, a extensão do arquivo é .editorconfig.)
All Todas as regras são ativadas como avisos de compilação*. Você pode desativar seletivamente regras individuais para desativá-las.

* As seguintes regras não são Essas regras herdadas podem ser preteridas em uma versão futura. No entanto, você ainda pode habilitá-los individualmente usando uma dotnet_diagnostic.CAxxxx.severity = <severity> entrada.

Nota

  • 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 completamente. No entanto, se você especificar ambas as propriedades, AnalysisLevel terá precedência sobre AnalysisMode.
  • Essa propriedade não tem efeito sobre a análise de código em projetos que não fazem referência a um SDK de projeto, por exemplo, projetos herdados do .NET Framework que fazem referência ao pacote NuGet Microsoft.CodeAnalysis.NetAnalyzers.

Categoria AnalysisMode<>

Essa propriedade é a mesma que AnalysisMode, exceto que ela só se aplica 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 regras. Se você omitir essa propriedade para uma categoria específica de regras, o padrão será o valor AnalysisMode . Os valores disponíveis são os mesmos de 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 conceção
<AnalysisModeDocumentation> Regras de documentação
<AnalysisModeGlobalization> Regras de globalização
<AnalysisModeInteroperability> Regras de portabilidade e interoperabilidade
<AnalysisModeMaintainability> Regras de manutenibilidade
<AnalysisModeNaming> Regras de nomenclatura
<AnalysisModePerformance> Regras de desempenho
<AnalysisModeSingleFile> Regras de aplicação de ficheiro único
<AnalysisModeReliability> Regras de fiabilidade
<AnalysisModeSecurity> Regras de segurança
<AnalysisModeStyle> Regras de estilo de código (IDEXXXX)
<AnalysisModeUsage> Regras de utilização

CodeAnalysisTreatWarningsAsErrors

A CodeAnalysisTreatWarningsAsErrors propriedade permite configurar se os avisos de análise de qualidade de código (CAxxxx) devem ser tratados como avisos e quebrar a compilação. Se você usar o sinalizador -warnaserror quando criar seus projetos, os avisos de análise de qualidade de 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ê pode definir a CodeAnalysisTreatWarningsAsErrors propriedade MSBuild como false em seu arquivo de projeto.

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

EnableNETAnalyzers

A análise de qualidade de código .NET é habilitada, por padrão, para projetos destinados ao .NET 5 ou 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 destinados a versões anteriores do .NET definindo a EnableNETAnalyzers propriedade como true. Para desativar a análise de código em qualquer projeto, defina esta propriedade como false.

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

Nota

Essa propriedade se aplica especificamente aos analisadores internos no SDK do .NET 5+. Ele não deve ser usado quando você instala um pacote de análise de código NuGet.

EnforceCodeStyleInBuild

A análise de estilo de código .NET é desabilitada, por padrão, na compilação para todos os projetos .NET. Você pode habilitar a análise de estilo de código para projetos .NET definindo a EnforceCodeStyleInBuild propriedade como true.

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

Todas as regras de estilo de código configuradas para serem avisos ou erros serão executadas na compilação e relatarão violações.

_SkipUpgradeNetAnalyzersNuGetWarning

A _SkipUpgradeNetAnalyzersNuGetWarning propriedade permite configurar se você recebe um aviso se estiver usando analisadores de código de um pacote NuGet desatualizado quando comparado com os analisadores de código no SDK .NET mais recente. O aviso é semelhante a:

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 esta 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 arquivo de projeto.

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

Propriedades de configuração de tempo de execução

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

AutoreleasePoolSupport

A AutoreleasePoolSupport propriedade configura se cada thread gerenciado recebe um NSAutoreleasePool implícito quando executado em uma plataforma macOS compatível. Para obter mais informações, consulte AutoreleasePool para threads gerenciados.

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

ConcurrentGarbageCollection

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

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

InvariantGlobalization

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

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

PredefinedCulturesOnly

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

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

Para obter mais informações, consulte Criação de cultura e mapeamento de casos no modo invariante de globalização.

RetainVMGarbageCollection

A RetainVMGarbageCollection propriedade 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 diz ao coletor de lixo para colocar os segmentos em uma lista de espera. Para obter mais informações, consulte Reter VM.

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

ServerGarbageCollection

A ServerGarbageCollection propriedade configura se o aplicativo usa a coleta de lixo da estação de trabalho ou a coleta de lixo do servidor. Defina o valor para true 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 ThreadPoolMaxThreads propriedade 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 ThreadPoolMinThreads propriedade configura o número mínimo de threads para o pool de threads de trabalho. Para obter mais informações, consulte Threads mínimos.

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

Compilação em camadas

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

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

TieredCompilationQuickJit

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

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

TieredCompilationQuickJitForLoops

A TieredCompilationQuickJitForLoops propriedade 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 TieredPGO propriedade controla se a otimização guiada por perfil (PGO) dinâmica ou hierárquica está habilitada. Defina o valor como true para habilitar o PGO hierárquico. Para obter mais informações, consulte Otimização guiada por perfil.

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

UseWindowsThreadPool

A UseWindowsThreadPool propriedade configura se o gerenciamento de threads do pool de threads é delegado ao pool de threads do Windows (somente Windows). O valor padrão é false, caso em que o pool de threads .NET é usado. 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 AssetTargetFallback propriedade 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 , TargetFrameworka AssetTargetFallback propriedade entrará em jogo. A compatibilidade do pacote referenciado é verificada novamente usando cada estrutura de destino especificada em AssetTargetFallback. Esta propriedade substitui a propriedade PackageTargetFallbackpreterida.

Você pode definir a propriedade para uma ou mais AssetTargetFallback de estrutura de destino.

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

DisableImplicitFrameworkReferences

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

Defina essa propriedade como true para desabilitar itens implícitos 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 DisableTransitiveFrameworkReferenceDownloads propriedade como true para evitar o download de pacotes extras de tempo de execução e segmentação que não são diretamente referenciados pelo seu projeto.

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

DisableTransitiveProjectReferences

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

Quando essa propriedade é true, ela tem um efeito semelhante ao de definir PrivateAssets="All" 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>

ManagePackageVersionsCentralmente

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

Exemplo de arquivo Directory.Packages.props :

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

Ficheiro de projeto individual:

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

Para obter mais informações, consulte Gerenciamento central de pacotes (CPM).

A restauração de 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, consulte restaurar destino.

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

UseMauiEssentials

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

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

ValidateExecutableReferencesMatchSelfContained

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

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

WindowsSdkPackageVersion

A WindowsSdkPackageVersion propriedade 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 FrameworkReference uso do item para essa finalidade.

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

Nota

Não recomendamos substituir a versão do SDK do Windows, porque 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 usar pacotes de visualização ou precisar substituir a versão do C#/WinRT.

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

RunArguments

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

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

Gorjeta

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

RunWorkingDirectory

A RunWorkingDirectory propriedade 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 não seja possível 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 ter que instalar o SDK mais antigo.

Os valores permitidos dessa propriedade são bandas de recursos SDK, por exemplo, 8.0.100 e 8.0.400. O valor assume como padrão a banda de recursos 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 é versionado, consulte Como o .NET é versionado.)

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

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

Propriedades relacionadas ao projeto de teste

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

IsTestProject

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 autônomo está desabilitada. Isso ocorre porque os projetos de teste têm um OutputType de Exe , mas geralmente chamam APIs em um executável referenciado em vez de tentar executar. Além disso, se um projeto fizer referência a um projeto onde 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.

Nota

Se seu projeto especifica o SDK MSTest, você não precisa 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 seu 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 especificado) faz o seguinte:

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

Definir a propriedade para false desativar a dependência transitiva para o 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ê define essa propriedade como false em um projeto que não é de teste e faz referência a um projeto de teste. Para obter mais informações, consulte o erro CS8892.

Se seu 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).

Ativar[NugetPackageNameWithoutDots]

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

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

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

EnableAspireTesting

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. Esta propriedade está disponível em MSTest 3.4 e versões posteriores.

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

HabilitarPlaywright

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. Esta propriedade está disponível em MSTest 3.4 e versões posteriores.

Para obter mais informações, consulte Playwright.

EnableMSTestRunner

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

Nota

Se seu projeto especifica o SDK MSTest, você não precisa definir essa propriedade. É definido automaticamente.

EnableNUnitRunner

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

GerarTestingPlatformEntryPoint

Definir a GenerateTestingPlatformEntryPoint propriedade para false desativar 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 para 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, informações de versão e informações de teste formatadas. Defina essa propriedade para false 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 trecho 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).

TestesPlataformaMostrarTestesFalha

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 true no arquivo de projeto.

TestingExtensionsProfile

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

valor Description
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 fornecidas pela Microsoft (incluindo extensões com uma licença restritiva).

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

UseVSTest

Defina a UseVSTest propriedade para true alternar do corredor MSTest para o executor 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 .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 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

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

Esta propriedade foi introduzida no .NET 9.

EnableComHosting

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

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

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

EnableDynamicLoading

A EnableDynamicLoading propriedade 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 a partir de um host nativo ou usado como um plugin. Definir essa propriedade para true tem os seguintes efeitos:

  • Um arquivo .runtimeconfig.json é gerado.
  • RollForward está 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 DisableImplicitNamespaceImports propriedade pode ser usada para desabilitar importações de namespace implícitas em projetos do Visual Basic destinados ao .NET 6 ou a uma versão posterior. Namespaces implícitos são os namespaces padrão que são importados globalmente em um projeto do Visual Basic. Defina essa propriedade como true para desabilitar as importações implícitas de namespace.

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

ImplicitUsings

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

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

Nota

Os modelos para novos projetos C# destinados ao .NET 6 ou posterior foram ImplicitUsings definidos como enable por padrão.

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

Items

Os itens do MSBuild são entradas no sistema de compilação. Os itens são especificados de acordo com seu tipo, que é o nome do elemento. Por exemplo, Compile e Reference são dois tipos de itens 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 use Update para modificar um item existente. Por exemplo, Update é frequentemente usado para modificar um item que foi implicitamente adicionado pelo SDK do .NET.

Metadados de montagem

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

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

InternalsVisibleTo

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

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

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

ReferênciaFrameworkReference

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

O Include atributo especifica o ID da estrutura.

O trecho do arquivo de projeto no exemplo a seguir faz referência ao Microsoft.AspNetCore.App estrutura compartilhada.

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

PackageReference

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

O Include atributo especifica a ID do pacote. O Version atributo especifica a versão ou o intervalo de versões. 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 trecho do 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 TrimmerRootAssembly item permite excluir um assembly do corte. O corte é o processo de remoção de partes não utilizadas do tempo de execução de um aplicativo empacotado. Em alguns casos, o corte pode remover incorretamente as referências necessárias.

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

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

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

Utilizar

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

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

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

<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 obter mais informações, consulte using aliased.

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 CopyToPublishDirectory metadados em um item MSBuild controla 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 permite uma compilação incremental.

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

Base de ligação

Para um item que está fora do diretório do projeto e seus subdiretórios, o destino de publicação usa os metadados 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 que está fora do cone do projeto, o padrão será %(LinkBase)\%(RecursiveDir)%(Filename)%(Extension). LinkBase Permite especificar uma pasta base sensível para itens fora do cone do projeto. A hierarquia de pastas sob a pasta base é preservada via RecursiveDir. Se LinkBase não for especificado, ele será omitido do Link caminho.

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

Solution Explorer mostrando o item com metadados LinkBase.

Consulte também