Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
Os projetos .NET modernos estão associados ao SDK (kit de desenvolvimento de software) de um projeto. Cada SDK de projeto é um conjunto de destinos do MSBuild e tarefas associadas responsáveis por compilar, empacotar e publicar código. Um projeto que faz referência a um SDK de projeto às vezes é conhecido como um projeto no estilo SDK.
SDKs disponíveis
Os SDKs disponíveis incluem:
| ID | Descrição | Repositório |
|---|---|---|
Microsoft.NET.Sdk |
O SDK do .NET | https://github.com/dotnet/sdk |
Microsoft.NET.Sdk.Web |
O SDK da Web do .NET | https://github.com/dotnet/sdk |
Microsoft.NET.Sdk.Razor |
O .NET Razor SDK | https://github.com/dotnet/aspnetcore |
Microsoft.NET.Sdk.BlazorWebAssembly |
O SDK de WebAssembly do .NET | https://github.com/dotnet/aspnetcore |
Microsoft.NET.Sdk.Worker |
O SDK do Serviço de Trabalho do .NET | https://github.com/dotnet/aspnetcore |
Aspire.AppHost.Sdk |
O SDK do .NET Aspire | https://github.com/dotnet/aspire |
MSTest.Sdk |
MSTest SDK | https://github.com/microsoft/testfx |
O SDK do .NET é o SDK base do .NET. Os outros SDKs fazem referência ao SDK do .NET e os projetos associados aos outros SDKs têm todas as propriedades do SDK do .NET disponíveis para eles. O SDK da Web, por exemplo, depende do SDK do .NET e do SDK do Razor.
Para projetos do Windows Forms e do WPF (Windows Presentation Foundation), especifique o SDK do .NET (Microsoft.NET.Sdk) e defina algumas propriedades adicionais no arquivo de projeto. Para obter mais informações, consulte Habilitar SDK do .NET Desktop.
Os SDKs do MSBuild, que você pode usar para configurar e estender seu build, estão listados em SDKs do MSBuild.
Você também pode criar seu próprio SDK que pode ser distribuído por meio do NuGet.
Arquivos de projeto
Os projetos do .NET são baseados no formato MSBuild. Os arquivos de projeto, que têm extensões como .csproj para projetos C# e .fsproj para projetos F#, estão em formato XML. O elemento raiz de um arquivo de projeto MSBuild é o elemento Project. O elemento Project tem um atributo opcional Sdk que especifica qual SDK (e versão) usar. Para usar as ferramentas .NET e criar seu código, defina o Sdk atributo como uma das IDs na tabela SDKs disponíveis.
<Project Sdk="Microsoft.NET.Sdk">
<!-- Omitted for brevity... -->
</Project>
O Project/Sdk atributo e o Sdk elemento habilitam SDKs aditivos. Considere o exemplo a seguir, em que o SDK do Aspire (Aspire.AppHost.Sdk) é adicionado ao projeto em cima do Microsoft.NET.Sdk:
<Project Sdk="Microsoft.NET.Sdk">
<Sdk Name="Aspire.AppHost.Sdk" Version="9.0.0" />
<!-- Omitted for brevity... -->
</Project>
No arquivo de projeto anterior, ambos os SDKs são usados para resolver dependências de forma aditiva. Para obter mais informações, consulte o SDK do Aspire.
Para especificar um SDK proveniente do NuGet, inclua a versão no final do nome ou especifique o nome e a versão no arquivo global.json.
<Project Sdk="MSBuild.Sdk.Extras/2.0.54">
...
</Project>
Outra maneira de especificar o SDK é com o elemento Sdk de nível superior:
<Project>
<Sdk Name="Microsoft.NET.Sdk" />
...
</Project>
Fazer referência a um SDK de uma dessas maneiras simplifica muito os arquivos de projeto para .NET. Ao avaliar o projeto, o MSBuild adiciona importações implícitas para Sdk.props na parte superior do arquivo de projeto e Sdk.targets na parte inferior.
<Project>
<!-- Implicit top import -->
<Import Project="Sdk.props" Sdk="Microsoft.NET.Sdk" />
...
<!-- Implicit bottom import -->
<Import Project="Sdk.targets" Sdk="Microsoft.NET.Sdk" />
</Project>
Dica
Em um computador Windows, os arquivos Sdk.props e Sdk.targets podem ser encontrados na pasta %ProgramFiles%\dotnet\sdk\[version]\Sdks\Microsoft.NET.Sdk\Sdk\Sdk.
Pré-processar o arquivo de projeto
Você pode ver o projeto totalmente expandido, pois o MSBuild o vê depois que o SDK e seus destinos são incluídos usando o comando dotnet msbuild -preprocess. A opção de pré-processamento do comando dotnet msbuild mostra quais arquivos são importados, as fontes e as contribuições deles para a compilação sem realmente criar o projeto.
Se o projeto tiver várias estruturas de destino, concentre os resultados do comando em apenas uma estrutura especificando-o como uma propriedade MSBuild. Por exemplo:
dotnet msbuild -property:TargetFramework=net8.0 -preprocess:output.xml
Inclusões e exclusões padrão
O SDK gerencia automaticamente três tipos de itens para seu projeto:
-
Compileitens: arquivos de código-fonte (*.cs,*.vbe outras extensões específicas do idioma) que são compilados em seu assembly. -
EmbeddedResourceitens:*.resxarquivos incorporados ao seu assembly. -
Noneitens: todos os outros arquivos rastreados no projeto, como arquivos de configuração e conteúdo, que não são compilados ou inseridos.
Ao contrário dos projetos não SDK do .NET Framework, você não precisa especificar esses itens no arquivo de projeto, pois os padrões abrangem os casos de uso mais comuns. Esse comportamento torna o arquivo de projeto menor e mais fácil de entender e editar manualmente, se necessário.
O SDK usa padrões glob para determinar quais arquivos pertencem a cada tipo de item:
- Incluir glob: especifica quais arquivos adicionar ao tipo de item.
- Excluir glob: especifica quais arquivos ignorar ao aplicar o glob de inclusão.
- Remover glob: especifica quais arquivos devem ser removidos dos itens que já foram adicionados pelo glob de inclusão.
A tabela a seguir mostra os padrões de glob padrão para cada tipo de item no SDK do .NET:
| Elemento | Incluir glob | Excluir glob | Remover glob |
|---|---|---|---|
| Compile | **/*.cs (ou outras extensões de linguagem) | **/*.utilizador; **/*.*proj; **/*.sln(x); **/*.vssscc | N/D |
| EmbeddedResource | **/*.resx | **/*.utilizador; **/*.*proj; **/*.sln(x); **/*.vssscc | N/D |
| None | **/* | **/*.utilizador; **/*.*proj; **/*.sln(x); **/*.vssscc | **/*.Cs; **/*.resx |
Como None usa **/* como glob de inclusão, ele incluiria arquivos .cs e .resx que já foram capturados por Compile e EmbeddedResource. O glob remove (**/*.cs; **/*.resx) impede que esses arquivos apareçam em ambos os tipos de item ao mesmo tempo.
Observação
As pastas ./bin e ./obj, representadas pelas propriedades MSBuild $(BaseOutputPath) e $(BaseIntermediateOutputPath), são excluídas dos globs por padrão. As exclusões são representadas pela propriedade DefaultItemExcludes.
O SDK do .NET Desktop possui inclusões e exclusões adicionais para o WPF. Para obter mais informações, confira Includes e excludes padrão do WPF.
Aviso
Evite definir Compile, EmbeddedResourceou None itens que duplicam os globs padrão Include do SDK. A duplicação de arquivos incluídos faz com que o build inclua os mesmos arquivos duas vezes, o que resulta em um erro de compilação NETSDK1022 . Há suporte para personalizações que usam Remove ou Update, ou que adicionam itens depois de definir EnableDefaultItems, EnableDefaultCompileItemsou EnableDefaultEmbeddedResourceItems para false. Para obter informações sobre como resolver o erro, consulte NETSDK1022: Itens duplicados foram incluídos.
Diretivas de uso implícito
Do .NET 6 em diante, diretivas global using implícitas são adicionadas a novos projetos em C#. Isso significa que você pode usar tipos definidos nesses namespaces sem precisar especificar seu nome totalmente qualificado ou adicionar manualmente uma diretiva using. O aspecto implícito refere-se ao fato de que as diretivas global using são adicionadas a um arquivo gerado no diretório obj do projeto.
Diretivas implícitas global using são adicionadas para projetos que usam um dos seguintes SDKs:
Microsoft.NET.SdkMicrosoft.NET.Sdk.WebMicrosoft.NET.Sdk.WorkerMicrosoft.NET.Sdk.WindowsDesktop
Uma diretiva global using é adicionada para cada namespace em um conjunto de namespaces padrão que são baseados no SDK do projeto. Esses namespaces padrão são mostrados na tabela a seguir.
| SDK | Namespaces padrão |
|---|---|
| Microsoft.NET.Sdk | System System.Collections.Generic System.IO System.Linq System.Net.Http System.Threading System.Threading.Tasks |
| Microsoft.NET.Sdk.Web | Namespaces do Microsoft.NET.Sdk System.Net.Http.Json Microsoft.AspNetCore.Builder Microsoft.AspNetCore.Hosting Microsoft.AspNetCore.Http Microsoft.AspNetCore.Routing Microsoft.Extensions.Configuration Microsoft.Extensions.DependencyInjection Microsoft.Extensions.Hosting Microsoft.Extensions.Logging |
| Microsoft.NET.Sdk.Worker | Namespaces do Microsoft.NET.Sdk Microsoft.Extensions.Configuration Microsoft.Extensions.DependencyInjection Microsoft.Extensions.Hosting Microsoft.Extensions.Logging |
| Microsoft.NET.Sdk.WindowsDesktop (Windows Forms) | Namespaces do Microsoft.NET.Sdk System.Drawing System.Windows.Forms |
| Microsoft.NET.Sdk.WindowsDesktop (WPF) | Namespaces do Microsoft.NET.Sdk Removido System.IO Removido System.Net.Http |
Se você quiser desabilitar esse recurso ou se quiser habilitar diretivas implícitas global using em um projeto C# existente, poderá fazê-lo por meio da propriedade ImplicitUsings MSBuild.
Você pode especificar mais diretivas implícitas global using adicionando itens Using (ou itens Import para projetos do Visual Basic) ao arquivo do projeto, por exemplo:
<ItemGroup>
<Using Include="System.IO.Pipes" />
</ItemGroup>
Observação
A partir do .NET 8 SDK, System.Net.Http não está mais incluído ao direcionar para o Microsoft.NET.Sdk .NET Framework.
Referências de pacote implícitas
Quando seu projeto adota como destino o .NET Standard 1.0 – 2.0, o SDK do .NET adiciona referências implícitas a determinados metapacotes. Um metapacote é um pacote baseado em estrutura que consiste apenas em dependências em outros pacotes. Os metapacotes são referenciados implicitamente com base nas estruturas de destino especificadas na propriedade TargetFramework ou TargetFrameworks (plural) do arquivo de projeto.
<PropertyGroup>
<TargetFramework>netstandard2.0</TargetFramework>
</PropertyGroup>
<PropertyGroup>
<TargetFrameworks>netstandard2.0;net462</TargetFrameworks>
</PropertyGroup>
Se necessário, você pode desabilitar referências implícitas de pacote usando a propriedade DisableImplicitFrameworkReferences e adicionar referências explícitas apenas às estruturas ou pacotes necessários.
Recomendações:
- Ao direcionar o .NET Framework ou o .NET Standard 1.0 – 2.0, não adicione uma referência explícita aos metapacotes
NETStandard.Librarypor meio de um item<PackageReference>no arquivo de projeto. Para projetos do .NET Standard 1.0 – 2.0, esses metapacotes são implicitamente referenciados. Para projetos do .NET Framework, se qualquer versão deNETStandard.Libraryfor necessária ao usar um pacote NuGet baseado em .NET Standard, o NuGet instalará automaticamente essa versão. - Se precisar de uma versão específica do metapacote
NETStandard.Libraryao ter como destino o .NET Standard 1.0 – 2.0, use a propriedade<NetStandardImplicitPackageVersion>e defina a versão necessária.
Eventos de build
Em projetos no estilo SDK, use um destino MSBuild chamado PreBuild ou PostBuild e defina a propriedade BeforeTargets como PreBuild ou a propriedade AfterTargets para PostBuild.
<Target Name="PreBuild" BeforeTargets="PreBuildEvent">
<Exec Command=""$(ProjectDir)PreBuildEvent.bat" "$(ProjectDir)..\" "$(ProjectDir)" "$(TargetDir)"" />
</Target>
<Target Name="PostBuild" AfterTargets="PostBuildEvent">
<Exec Command="echo Output written to $(TargetDir)" />
</Target>
Observação
- Você pode usar qualquer nome para os destinos do MSBuild. No entanto, o IDE do Visual Studio reconhece os destinos
PreBuildePostBuild, portanto, usando esses nomes, você pode editar os comandos no IDE. - As propriedades
PreBuildEventePostBuildEventnão são recomendadas em projetos no estilo SDK, pois macros como$(ProjectDir)não são resolvidas. Por exemplo, não há suporte para o seguinte código:
<PropertyGroup>
<PreBuildEvent>"$(ProjectDir)PreBuildEvent.bat" "$(ProjectDir)..\" "$(ProjectDir)" "$(TargetDir)"</PreBuildEvent>
</PropertyGroup>
Personalizar a compilação
Há várias maneiras de personalizar um build. Talvez você queira substituir uma propriedade passando-a como um argumento para um comando msbuild ou dotnet. Você também pode adicionar a propriedade ao arquivo de projeto ou a um arquivo Directory.Build.props. Para obter uma lista de propriedades úteis para projetos .NET, confira Referência do MSBuild para projetos do SDK do .NET.
Dica
Uma maneira fácil de criar um arquivo Directory.Build.props a partir da linha de comando é usar o comando dotnet new buildprops na raiz do seu repositório.
Destinos personalizados
Projetos do .NET podem empacotar destinos e propriedades personalizadas do MSBuild para uso por projetos que consomem o pacote. Use esse tipo de extensibilidade quando quiser:
- Estenda o processo de compilação.
- Acesse artefatos do processo de compilação, como arquivos gerados.
- Inspecione a configuração sob a qual a compilação é invocada.
Você adiciona destinos ou propriedades de compilação personalizados colocando arquivos no formulário <package_id>.targets ou <package_id>.props (por exemplo, Contoso.Utility.UsefulStuff.targets) na pasta de compilação do projeto.
O XML a seguir é um snippet de um arquivo .csproj que instrui o comando dotnet pack sobre o que empacotar. O elemento <ItemGroup Label="dotnet pack instructions"> coloca os arquivos de destino na pasta de compilação dentro do pacote. O elemento <Target Name="CollectRuntimeOutputs" BeforeTargets="_GetPackageFiles"> coloca os assemblies e arquivos .json na pasta de compilação.
<Project Sdk="Microsoft.NET.Sdk">
...
<ItemGroup Label="dotnet pack instructions">
<Content Include="build\*.targets">
<Pack>true</Pack>
<PackagePath>build\</PackagePath>
</Content>
</ItemGroup>
<Target Name="CollectRuntimeOutputs" BeforeTargets="_GetPackageFiles">
<!-- Collect these items inside a target that runs after build but before packaging. -->
<ItemGroup>
<Content Include="$(OutputPath)\*.dll;$(OutputPath)\*.json">
<Pack>true</Pack>
<PackagePath>build\</PackagePath>
</Content>
</ItemGroup>
</Target>
...
</Project>
Para consumir um destino personalizado em seu projeto, adicione um elemento PackageReference que aponte para o pacote e sua versão. Ao contrário das ferramentas, o pacote de destinos personalizados está incluído no fechamento de dependência do projeto consumidor.
Você pode configurar como usar o destino personalizado. Como ele é um destino MSBuild, ele pode depender de um determinado destino, executar após outro destino ou ser invocado manualmente usando o comando dotnet msbuild -t:<target-name>. No entanto, para fornecer uma melhor experiência do usuário, você pode combinar ferramentas por projeto e destinos personalizados. Nesse cenário, a ferramenta por projeto aceita todos os parâmetros necessários e os converte na invocação dotnet msbuild necessária que executa o destino. Veja um exemplo desse tipo de sinergia no repositório Exemplos do MVP Summit 2016 Hackathon do projeto dotnet-packer.
Confira também
Colaborar conosco no GitHub
A fonte deste conteúdo pode ser encontrada no GitHub, onde você também pode criar e revisar problemas e solicitações de pull. Para obter mais informações, confira o nosso guia para colaboradores.
