MSBuild referência para projetos do SDK do .NET

  • Artigo
  • 37 minutos para o fim da leitura

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

Observação

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

Propriedades da estrutura

As seguintes propriedades de 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 as estruturas de destino em projetos no estilo SDK.

<PropertyGroup>
  <TargetFramework>netcoreapp3.1</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 direcione várias plataformas. Para obter uma lista de monikers de estrutura de destino válidos, consulte as estruturas de destino em projetos no estilo SDK.

Observação

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

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

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

NetStandardImplicitPackageVersion

Observação

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

Use a NetStandardImplicitPackageVersion propriedade quando quiser especificar uma versão da estrutura menor que a versão do metapacote. O arquivo de projeto nos seguintes destinos de exemplo, netstandard1.3 mas usa a versão 1.6.0 de NETStandard.Library.

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

Propriedades do atributo Assembly

GenerateAssemblyInfo

A GenerateAssemblyInfo propriedade controla AssemblyInfo a geração de atributos 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 GenerateAssemblyInfo valor é true, as propriedades de projeto relacionadas ao pacote são transformadas em atributos de assembly. A tabela a seguir lista as propriedades do projeto que geram os atributos. Ele também lista as propriedades que você pode usar para desabilitar essa geração por atributo, por exemplo:

<PropertyGroup>
  <GenerateNeutralResourcesLanguageAttribute>false</GenerateNeutralResourcesLanguageAttribute>
</PropertyGroup>
propriedade MSBuild Atributo de assembly Propriedade para desabilitar a geração de atributo
Company AssemblyCompanyAttribute GenerateAssemblyCompanyAttribute
Configuration AssemblyConfigurationAttribute GenerateAssemblyConfigurationAttribute
Copyright AssemblyCopyrightAttribute GenerateAssemblyCopyrightAttribute
Description AssemblyDescriptionAttribute GenerateAssemblyDescriptionAttribute
FileVersion AssemblyFileVersionAttribute GenerateAssemblyFileVersionAttribute
InformationalVersion AssemblyInformationalVersionAttribute GenerateAssemblyInformationalVersionAttribute
Product AssemblyProductAttribute GenerateAssemblyProductAttribute
AssemblyTitle AssemblyTitleAttribute GenerateAssemblyTitleAttribute
AssemblyVersion AssemblyVersionAttribute GenerateAssemblyVersionAttribute
NeutralLanguage NeutralResourcesLanguageAttribute GenerateNeutralResourcesLanguageAttribute

Anotações sobre essas configurações:

  • AssemblyVersion e FileVersion padrão para o valor de $(Version) sem o sufixo. Por exemplo, se $(Version) fosse 1.2.3-beta.4, então o valor seria 1.2.3.
  • InformationalVersion usa por padrão o valor de $(Version).
  • Se a $(SourceRevisionId) propriedade estiver presente, ela será acrescentada a InformationalVersion. Você pode desabilitar esse comportamento usando IncludeSourceRevisionInInformationalVersion.
  • As propriedades Copyright e Description também são usadas para metadados do NuGet.
  • Configuration, o padrão é Debugcompartilhado com todos os destinos MSBuild. Você pode defini-lo por meio da opção --configuration de dotnet comandos, por exemplo, pacote dotnet.
  • Algumas das propriedades são usadas ao criar um pacote NuGet. Para obter mais informações, consulte propriedades do pacote.

Migrando de .NET Framework

.NET Framework modelos de projeto criam um arquivo de código com esses atributos de informações de assembly definidos. O arquivo normalmente está localizado em .\Properties\AssemblyInfo.cs ou .\Properties\AssemblyInfo.vb. Projetos no estilo SDK geram esse arquivo para você com base nas configurações do projeto. Você não pode ter os dois. Ao portar seu código para o .NET 5 (ou .NET Core 3.1) ou posterior, siga um destes procedimentos:

  • Desabilite a geração do arquivo de código temporário que contém os atributos de informações do assembly definindo GenerateAssemblyInfofalse em seu arquivo de projeto. Isso permite que você mantenha o arquivo AssemblyInfo .
  • Migre as configurações no AssemblyInfo arquivo para o arquivo de projeto e exclua o AssemblyInfo arquivo.

GeneratedAssemblyInfoFile

A GeneratedAssemblyInfoFile propriedade 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]$(IntermediateOutputPath) no diretório (geralmente o obj).

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

Propriedades do pacote

Você pode especificar propriedades como PackageId, PackageVersion, PackageIcon, Titlee Description para descrever o pacote que é criado a partir de seu projeto. Para obter informações sobre essas e outras propriedades, consulte o 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 altera o comportamento padrão de dotnet pack.

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

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

AppendTargetFrameworkToOutputPath

A AppendTargetFrameworkToOutputPath propriedade controla se o moniker da estrutura de destino (TFM) é acrescentado ao caminho de saída (que é definido pelo OutputPath). O SDK do .NET acrescenta automaticamente a estrutura de destino e, se presente, o identificador de runtime ao caminho de saída. A configuração AppendTargetFrameworkToOutputPath para false impedir que o TFM seja acrescentado ao caminho de saída. No entanto, sem o TFM no caminho de saída, vários artefatos de build 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 AppendRuntimeIdentifierToOutputPath propriedade 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. Configuração AppendRuntimeIdentifierToOutputPath para false impedir que o RID seja acrescentado ao caminho de saída.

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

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

CopyLocalLockFileAssemblies

A CopyLocalLockFileAssemblies propriedade é útil para projetos de plug-in que têm dependências em outras bibliotecas. Se você definir essa propriedade comotrue, qualquer dependência de pacote NuGet será copiada para o diretório de saída. Isso significa que você pode usar a saída para dotnet build executar o plug-in em qualquer computador.

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

Dica

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

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

Essa propriedade foi introduzida no .NET 6.

EnablePackageValidation

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

<PropertyGroup>
  <EnablePackageValidation>true</EnablePackageValidation>
</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 GenerateRuntimeConfigDevFile propriedade como true.

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

GenerateRuntimeConfigurationFiles

A GenerateRuntimeConfigurationFiles propriedade controla se as opções de configuração de runtime 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 cuja OutputType propriedade éExe, essa propriedade é padrão.true

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

GenerateSatelliteAssembliesForCore

A GenerateSatelliteAssembliesForCore propriedade controla se assemblies satélites são gerados usando csc.exe ou Al.exe (Assembly Linker) em projetos de .NET Framework. Os projetos do .NET Core e do .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 GenerateSatelliteAssembliesForCore propriedade como true, assemblies satélites 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 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 de publicação do dotnet . Ele não afeta a publicação em Visual Studio, que usa o PublishOnly destino. 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 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 no tempo de build. Os assemblies referenciados no tempo de build 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, juntamente com as opções passadas para o compilador. Você pode recuperar essas informações usando as propriedades e DependencyContext.CompilationOptions as DependencyContext.CompileLibraries propriedades.

Essa funcionalidade é usada principalmente internamente por ASP.NET Core páginas MVC e Razor para dar suporte à 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 as propriedades do SDK do Razor.

ProduceReferenceAssemblyInOutDir

No .NET 5 e em versões anteriores, os 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 os assemblies de referência são gravados no OutDir diretório. O valor padrão é false, e assemblies de referência são gravados apenas no IntermediateOutputPath diretório. Defina o valor para true gravar assemblies de referência no OutDir diretório.

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

Para obter mais informações, consulte Assemblies de referência de gravação para saída intermediária.

PublishRelease

A PublishRelease propriedade informa dotnet publish para aproveitar a Release configuração em vez da Debug configuração. É recomendável adicionar essa propriedade a um Directory.Build.props arquivo em vez de um arquivo de projeto para que ele seja avaliado cedo o suficiente para que a alteração de configuração seja propagada.

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

Observação

Essa propriedade não afeta o comportamento de dotnet build /t:Publish.

RollForward

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

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

Defina RollForward como um dos seguintes valores:

Valor Descrição
Minor Padrão se não for especificado.
Reverta para a versão secundária 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 Avance para a próxima versão principal mais alta disponível e 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 Encaminhe para a versão mais alta do patch. Esse valor desabilita o roll-forward da versão secundária.
LatestMinor Avance para a versão secundária mais alta, mesmo que a versão secundária solicitada esteja presente.
LatestMajor Avance para a versão secundária mais alta e principal, mesmo se a major solicitada estiver presente.
Disable Não faça roll-forward, apenas associe-se à versão especificada. Essa política não é recomendada para uso geral, pois desabilita a capacidade de reverter para os patches mais recentes. Esse valor só é recomendado para teste.

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

RuntimeFrameworkVersion

A RuntimeFrameworkVersion propriedade 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 independente, esse valor especifica a versão exata necessária.

RuntimeIdentifier

A RuntimeIdentifier propriedade permite que você especifique um único identificador de runtime (RID) para o projeto. O RID permite a publicação de uma implantação autossuficiente.

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

RuntimeIdentifiers

A RuntimeIdentifiers propriedade permite que você especifique uma lista delimitada por ponto e vírgula de RIDs (identificadores de runtime) para o projeto. Use essa propriedade se 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 builds mais rápidos quando apenas um único runtime é necessário.

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

SatelliteResourceLanguages

A SatelliteResourceLanguages propriedade permite especificar para quais idiomas você deseja preservar assemblies de recursos satélites durante a compilação e publicação. Muitos pacotes NuGet incluem assemblies satélites de recursos localizados no pacote principal. Para projetos que fazem referência a esses pacotes de NuGet que não exigem recursos localizados, os assemblies localizados podem inflar desnecessariamente o tamanho da saída de compilação e publicação. Ao adicionar a SatelliteResourceLanguages propriedade 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) serão retidos.

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

Observação

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

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.

No .NET Core 3.0 e versões posteriores, um executável dependente de estrutura é criado por padrão. Defina a UseAppHost propriedade para false desabilitar a geração do executável.

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

Para obter mais informações sobre a implantação, consulte a implantação do aplicativo .NET.

Várias propriedades de 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 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 link ou copyused Controla a granularidade de corte. Essa propriedade pode ser definida globalmente para o projeto ou no nível do assembly como metadados.
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.
ILLinkWarningLevel 5-9999, previewou latest Controla a versão dos avisos de análise de corte.
ILLinkTreatWarningsAsErrors true ou false Controla se os avisos de corte são tratados como erros. Por exemplo, talvez você queira definir essa propriedade para false quando TreatWarningsAsErrors está definida 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 de MSBuild estão documentadas nesta seção:

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

DisableImplicitFrameworkDefines

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 false como ou não está definida (que é o valor padrão) os símbolos do pré-processador são gerados para:

  • Estrutura sem versão (NETFRAMEWORK, , NETNETSTANDARD)
  • Estrutura com versão (NET48, , NET6_0NETSTANDARD2_0)
  • Estrutura 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 do pré-processador, consulte as 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, , WINDOWSIOS)
  • 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íficas do sistema operacional.

Por fim, se a 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 suporte para e assim por net5.0 diante todo o caminho de volta para .netcoreapp1.0. Portanto, para cada uma dessas estruturas de destino, a Estrutura com o símbolo de limite mínimo de versão será definida.

DocumentationFile

A DocumentationFile propriedade permite que você especifique um nome de arquivo para o arquivo XML que contém a documentação da biblioteca. Para que 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 que o assembly. Se você não especificar essa propriedade, mas definir GenerateDocumentationFile como true, o nome do arquivo de documentação será o 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 EmbeddedResourceUseDependentUponConvention propriedade 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 co-localizados 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 no Form1.cs. Por exemplo, 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 os 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, essa propriedade é definida como true. Se definido como false, e não 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 de arquivo relativo para o arquivo .resx . Para obter mais informações, consulte Como os arquivos de manifesto de recurso são nomeados.

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

EnablePreviewFeatures

A EnablePreviewFeatures propriedade define se o projeto depende de apis ou assemblies decorados com o RequiresPreviewFeaturesAttribute atributo. 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 suporte 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 no nível do assembly é adicionado ao arquivo AssemblyInfo.cs :

[assembly: RequiresPreviewFeatures]

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

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, consulte a seção GenerateRequiresPreviewFeaturesAttribute abaixo.

GenerateDocumentationFile

A GenerateDocumentationFile propriedade controla se o compilador gera um arquivo de documentação XML para sua biblioteca. Se você definir essa propriedade 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 uma extensão de.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 de documentação XML (C#), documente seu código com XML (Visual Basic)ou documente seu código com XML (F#).

GenerateRequiresPreviewFeaturesAttribute

A GenerateRequiresPreviewFeaturesAttribute propriedade 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 GenerateRequiresPreviewFeaturesAttribute propriedade como False, você deve ter certeza de 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 por Visual Studio ignorar a análise de código, incluindo a análise anulável. Visual Studio dispara um build implícito ao executar testes, por exemplo. No entanto, os builds implícitos são otimizados somente quando TreatWarningsAsErrors não truesão . 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>

Propriedades de inclusão de item padrão

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

Para obter mais informações, consulte Padrão inclui e exclui.

DefaultItemExcludes

Use a DefaultItemExcludes propriedade 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>

DefaultExcludesInProjectFolder

Use a DefaultExcludesInProjectFolder propriedade para definir padrões 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 período (.como .git e .vs, são excluídas dos padrões glob.

Essa propriedade é muito semelhante à DefaultItemExcludes propriedade, exceto que ela considera apenas 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 DefaultExcludesInProjectFolder propriedade em vez da DefaultItemExcludes propriedade.

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

EnableDefaultItems

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

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

EnableDefaultCompileItems

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

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

EnableDefaultEmbeddedResourceItems

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

<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 build) são incluídos implicitamente no projeto. O valor padrão é true. Defina a EnableDefaultNoneItems propriedade para desabilitar a false inclusão implícita de None itens.

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

Propriedades de análise de código

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

AnalysisLevel

A AnalysisLevel propriedade permite que você especifique um conjunto de analisadores de código a serem executados de acordo com uma versão do .NET. Cada versão do .NET, começando no .NET 5, tem um conjunto de regras de análise de código. Desse conjunto, as regras habilitadas por padrão para essa versão analisarão seu código. Por exemplo, se você atualizar para o .NET 6, mas não quiser que o conjunto padrão de regras de análise de código seja alterado, defina AnalysisLevel como 5.

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

Opcionalmente, começando no .NET 6, você pode especificar um valor composto para essa propriedade que também especifica o quão agressivamente habilitar regras. Os valores compostos tomam o formulário <version>-<mode>, em que o <mode> valor é um dos valores AnalysisMode . O exemplo a seguir usa a versão prévia dos analisadores de código e habilita o conjunto de regras recomendado.

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

Observação

Se você definir AnalysisLevel ou 5-<mode>5.0-<mode> instalar o SDK do .NET 6 e recompilar seu projeto, poderá ver novos avisos de build inesperados. Para obter mais informações, consulte dotnet/roslyn-analyzers#5679.

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 <mode> valor 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 <mode> valor determina quais regras estão habilitadas.
6.0 O conjunto de regras que estava disponível para a versão do .NET 6 é usado, mesmo que regras mais recentes estejam disponíveis.
6.0-<mode> O conjunto de regras que estava disponível para a versão do .NET 6 é usado, mesmo que regras mais recentes estejam disponíveis. O <mode> valor determina quais regras estão habilitadas.
6 O conjunto de regras que estava disponível para a versão do .NET 6 é usado, mesmo que regras mais recentes estejam disponíveis.
6-<mode> O conjunto de regras que estava disponível para a versão do .NET 6 é usado, mesmo que regras mais recentes estejam disponíveis. O <mode> valor determina quais regras estão habilitadas.
5.0 O conjunto de regras que estava disponível para a versão do .NET 5 é usado, mesmo se as regras mais recentes estiverem disponíveis.
5.0-<mode> O conjunto de regras que estava disponível para a versão do .NET 5 é usado, mesmo se as regras mais recentes estiverem disponíveis. O <mode> valor determina quais regras estão habilitadas.
5 O conjunto de regras que estava disponível para a versão do .NET 5 é usado, mesmo se as regras mais recentes estiverem disponíveis.
5-<mode> O conjunto de regras que estava disponível para a versão do .NET 5 é usado, mesmo se as regras mais recentes estiverem disponíveis. O <mode> valor determina quais regras estão habilitadas.

Observação

Categoria AnalysisLevel<>

Introduzida no .NET 6, essa propriedade é a mesma que AnalysisLevel, exceto que ela se aplica apenas 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 para as outras categorias de regra. Se você omitir essa propriedade para uma determinada categoria de regras, ela será padronizada 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 de 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 (IDEXXXXX)
<AnalysisLevelUsage> Regras de uso

AnalysisMode

A partir do .NET 5, 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 AnalysisMode propriedade permite personalizar o conjunto de regras que estão habilitadas por padrão. Você pode alternar para um modo de análise mais agressivo em que pode recusar regras individualmente ou um modo de análise mais conservador em que você 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 no .NET 5 e no .NET 6. Eles são listados em ordem crescente do número de regras que habilitam.

Valor .NET 6+ Valor do .NET 5 Significado
None AllDisabledByDefault Todas as regras estão desabilitadas. Você pode aceitar seletivamente regras individuais para habilitá-las.
Default Default Modo padrão, em que determinadas regras são habilitadas como avisos de build, determinadas regras são habilitadas como Visual Studio sugestões de IDE e o restante está desabilitado.
Minimum N/D Modo mais agressivo do que o Default modo. Algumas sugestões altamente recomendadas para a imposição de build são habilitadas como avisos de build.
Recommended N/D Modo mais agressivo do que o Minimum modo, em que mais regras são habilitadas como avisos de build.
All AllEnabledByDefault Todas as regras são habilitadas como avisos de build. Você pode recusar seletivamente regras individuais para desabilitá-las.

Observação

  • No .NET 5, essa propriedade afeta apenas as regras de CAXXXX (qualidade de código). A partir do .NET 6, se você definir EnforceCodeStyleInBuild como true, essa propriedade afetará as regras de estilo de código (IDEXXXXX) também.
  • Se você usar um valor composto para AnalysisLevel, por exemplo, <AnalysisLevel>5-recommended</AnalysisLevel>poderá omitir totalmente essa propriedade. No entanto, se você especificar ambas as propriedades, AnalysisLevel terá precedência sobre AnalysisMode.
  • Se AnalysisMode estiver definido AllEnabledByDefault como ou AnalysisLevel55.0, e você instalar o SDK do .NET 6 e recompilar seu projeto, poderá ver novos avisos de build inesperados. Para obter mais informações, consulte dotnet/roslyn-analyzers#5679.
  • Essa propriedade não tem nenhum efeito na análise de código em projetos que não fazem referência a um SDK de projeto, por exemplo, projetos de .NET Framework herdados que fazem referência ao pacote NuGet Microsoft.CodeAnalysis.NetAnalyzers.

Categoria AnalysisMode<>

Introduzida no .NET 6, essa propriedade é igual a AnalysisMode, exceto que ela 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 iguais aos do AnalysisMode.

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

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

Nome da propriedade Categoria de 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 CodeAnalysisTreatWarningsAsErrors propriedade permite que você configure 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 -warnaserror sinalizador 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 CodeAnalysisTreatWarningsAsErrors propriedade false MSBuild 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 EnableNETAnalyzers propriedade 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+. 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 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 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 em violações de build e relatório.

Observação

Se você instalar o .NET 6 (ou Visual Studio 2022, que inclui o .NET 6), mas quiser criar seu projeto usando Visual Studio 2019, poderá ver novos avisos CS8032 se você tiver a EnforceCodeStyleInBuild propriedade definida como true. Para resolver os avisos, você pode especificar a versão do SDK do .NET com a qual criar seu projeto (nesse caso, algo semelhante 5.0.404) adicionando uma entrada global.json.

_SkipUpgradeNetAnalyzersNuGetWarning

A _SkipUpgradeNetAnalyzersNuGetWarning propriedade permite configurar se você recebe um aviso se estiver usando analisadores de código de um pacote de NuGet que está desatualizado quando comparado com os analisadores de código no SDK do .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'. 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 _SkipUpgradeNetAnalyzersNuGetWarningtrue no arquivo de projeto.

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

Propriedades de configuração do runtime

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

ConcurrentGarbageCollection

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

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

InvariantGlobalization

A InvariantGlobalization propriedade 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 a true ser executado no modo invariável de globalização. Para obter mais informações, consulte o modo Invariável.

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

PredefinedCulturesOnly

No .NET 6 e versões posteriores, a propriedade configura se os PredefinedCulturesOnly 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 para permitir a false criação de qualquer nova cultura no modo invariável à globalização.

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

Para obter mais informações, consulte a criação de cultura e o mapeamento de maiúsculas e minúsculas no modo invariável 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 para true 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 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 usar a true coleta de lixo do servidor. Para obter mais informações, consulte Workstation vs. server.

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

TieredCompilation

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

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

TieredCompilationQuickJit

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

<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 para true habilitar o JIT rápido em métodos que contêm loops. Para obter mais informações, consulte Quick JIT para obter loops.

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

Propriedades de referência

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

AssetTargetFallback

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

Você pode definir a AssetTargetFallback propriedade como uma ou mais versões 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 .NET Standard 2.0 e versões anteriores, 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 direcionar .NET Framework.

Defina essa propriedade para true 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>

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

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

ValidateExecutableReferencesMatchSelfContained

A ValidateExecutableReferencesMatchSelfContained propriedade 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 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 Windows. Essa propriedade foi introduzida no .NET 5 e substitui o uso do FrameworkReference item 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 destino do SDK 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 o uso de pacotes de visualização ou a necessidade de 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>

Dica

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 de MSBuild estão documentadas nesta seção:

HabilitarComHosting

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 do .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 de um host nativo ou usada como um plug-in. Definir essa propriedade para true ter os seguintes efeitos:

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

Propriedades de arquivo geradas

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

DisableImplicitNamespaceImports

A DisableImplicitNamespaceImports propriedade pode ser usada para desabilitar importações implícitas de namespace em projetos de Visual Basic direcionados 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 de Visual Basic. Defina essa propriedade para true desabilitar 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# 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 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 desabilitar diretivas implícitas global using , remova a propriedade ou defina-a como false ou disable.

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

Observação

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

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

Itens

MSBuild itens são entradas no sistema de build. 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 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 use Update para modificar um item existente. Por exemplo, geralmente é Update usado para modificar um item que foi adicionado implicitamente pelo SDK do .NET.

Assemblymetadata

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

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

Internalsvisibleto

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

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

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

PackageReference

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

O atributo Include especifica a ID do pacote. O Version atributo 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 TrimmerRootAssembly item permite que você exclua um assembly do corte. O corte é o processo de remoção de partes não utilizados 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 System.Security assembly do corte.

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

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

Usar

O Using item permite incluir 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. Esse item é semelhante ao Import item que pode ser usado para a mesma finalidade em projetos 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 Using item para definir diretivas e using static <type> globaisusing <alias>.

<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 sobre diretivas e using static <type> diretivas aliasedusing, consulte usando a diretiva.

Metadados do item

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

CopyToPublishDirectory

Os CopyToPublishDirectory metadados em um item de 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 foi alterado, Alwaysque 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 link do item para determinar para onde copiar o item. Linktambém determina como os itens fora da árvore de projeto são exibidos na janela Gerenciador de Soluções de Visual Studio.

Se Link não for especificado para um item que está fora do cone do projeto, ele será o padrão %(LinkBase)\%(RecursiveDir)%(Filename)%(Extension). LinkBase permite especificar uma pasta base sensata 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 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 em Gerenciador de Soluções.

Solution Explorer showing item with LinkBase metadata.

Confira também