Sdílet prostřednictvím

Projektové sady SDK pro .NET

Moderní projekty .NET jsou přidružené k sadě SDK (Project Software Development Kit). Každá sada SDK projektu je sada cílů MSBuild a přidružených úkolů, které zodpovídají za kompilaci, balení a publikování kódu. Projekt, který odkazuje na sadu SDK projektu, se někdy označuje jako projekt ve stylu sady SDK.

Dostupné sady SDK

Mezi dostupné sady SDK patří:

Průkaz totožnosti Popis Repozitář
Microsoft.NET.Sdk Sada .NET SDK https://github.com/dotnet/sdk
Microsoft.NET.Sdk.Web Webová sada .NET SDK https://github.com/dotnet/sdk
Microsoft.NET.Sdk.Razor Sada .NET Razor SDK https://github.com/dotnet/aspnetcore
Microsoft.NET.Sdk.BlazorWebAssembly Sada .NET Blazor WebAssembly SDK https://github.com/dotnet/aspnetcore
Microsoft.NET.Sdk.Worker Sada nástrojů pro službu pracovník .NET SDK https://github.com/dotnet/aspnetcore
Aspire.AppHost.Sdk Sada .NET Aspire SDK https://github.com/dotnet/aspire
MSTest.Sdk Sada nástrojů MSTest SDK https://github.com/microsoft/testfx

.NET SDK je základní sada SDK pro .NET. Ostatní sady SDK odkazují na sadu .NET SDK a projekty, které jsou přidružené k ostatním sadám SDK, mají k dispozici všechny vlastnosti sady .NET SDK. Například webová sada SDK závisí na sadě .NET SDK i na sadě Razor SDK.

Pro projekty Windows Forms a Windows Presentation Foundation (WPF) zadáte sadu .NET SDK (Microsoft.NET.Sdk) a v souboru projektu nastavíte některé další vlastnosti. Další informace naleznete v tématu Povolení sady .NET Desktop SDK.

Sady SDK pro MSBuild, které můžete použít ke konfiguraci a rozšíření svého sestavení, jsou uvedeny v části MSBuild SDKs.

Můžete také vytvořit vlastní sadu SDK, kterou je možné distribuovat prostřednictvím NuGetu.

Soubory projektu

Projekty .NET jsou založeny na formátu MSBuild . Soubory projektu, které mají přípony jako .csproj pro projekty jazyka C# a .fsproj pro projekty F#, jsou ve formátu XML. Kořenový prvek souboru projektu MSBuild je Project element. Element Project má volitelný Sdk atribut, který určuje, která sada SDK (a verze) se má použít. Pokud chcete použít nástroje .NET a sestavit kód, nastavte Sdk atribut na jedno z ID v tabulce Dostupných sad SDK .

<Project Sdk="Microsoft.NET.Sdk">
    <!-- Omitted for brevity... -->
</Project>

Atribut Project/Sdk a Sdk prvek umožňují doplňkové sady SDK. Podívejte se na následující příklad, ve kterém je sada .NET Aspire SDK (Aspire.AppHost.Sdk) přidána do projektu na vrcholu Microsoft.NET.Sdk:

<Project Sdk="Microsoft.NET.Sdk">

    <Sdk Name="Aspire.AppHost.Sdk" Version="9.0.0" />
    <!-- Omitted for brevity... -->

</Project>

V předchozím souboru projektu se obě sady SDK používají k řešení závislostí v doplňkové povaze. Další informace najdete v tématu .NET Aspire SDK.

Pokud chcete zadat sadu SDK, která pochází z NuGetu, zadejte verzi na konec názvu nebo zadejte název a verzi v souboru global.json .

<Project Sdk="MSBuild.Sdk.Extras/2.0.54">
  ...
</Project>

Další způsob, jak určit sadu SDK, je s elementem nejvyšší úrovně Sdk :

<Project>
  <Sdk Name="Microsoft.NET.Sdk" />
  ...
</Project>

Odkazování na sadu SDK jedním z těchto způsobů výrazně zjednodušuje soubory projektu pro .NET. Při vyhodnocování projektu přidá nástroj MSBuild implicitní importy pro Sdk.props na začátku souboru projektu a Sdk.targets na konci souboru.

<Project>
  <!-- Implicit top import -->
  <Import Project="Sdk.props" Sdk="Microsoft.NET.Sdk" />
  ...
  <!-- Implicit bottom import -->
  <Import Project="Sdk.targets" Sdk="Microsoft.NET.Sdk" />
</Project>

Návod

Na počítači s Windows najdete soubory Sdk.props a Sdk.targets ve složce %ProgramFiles%\dotnet\sdk\[version]\Sdks\Microsoft.NET.Sdk\Sdk\Sdk .

Předběžné zpracování souboru projektu

Plně rozbalený projekt můžete vidět tak, jak ho vidí MSBuild, po zahrnutí sady SDK a jejích cílů, pomocí příkazu dotnet msbuild -preprocess. Přepínač předzpracovánídotnet msbuild příkazu ukazuje, které soubory se naimportují, jejich zdroje a jejich příspěvky do sestavení bez skutečného sestavení projektu.

Pokud má projekt více cílových architektur, zaměřte výsledky příkazu pouze na jednu architekturu tak, že ho zadáte jako vlastnost MSBuild. Příklad:

dotnet msbuild -property:TargetFramework=net8.0 -preprocess:output.xml

Výchozí zahrnutí a vyloučení

Výchozí nastavení zahrnuje a vylučuje položky Compile položky, vložené prostředky a None položky jsou definovány v sadě SDK. Na rozdíl od projektů .NET Framework bez sady SDK nemusíte tyto položky v souboru projektu zadávat, protože výchozí hodnoty pokrývají nejběžnější případy použití. Díky tomuto chování je soubor projektu menší a v případě potřeby srozumitelnější a snadněji upravitelný ručně.

Následující tabulka uvádí, které prvky a které globy jsou zahrnuté a vyloučené v sadě .NET SDK:

Prvek Zahrnout glob Vyloučení globu Odstraňte glob
Compile **/*.cs (nebo jiná jazyková rozšíření) **/*.uživatel; **/*.*proj; **/*.sln(x); **/*.vssscc Nevztahuje se
EmbeddedResource **/*.resx **/*.uživatel; **/*.*proj; **/*.sln(x); **/*.vssscc Nevztahuje se
None **/* **/*.uživatel; **/*.*proj; **/*.sln(x); **/*.vssscc **/*.Cs; **/*.resx

Poznámka:

Složky ./bin a ./obj, které jsou reprezentovány vlastnostmi MSBuild $(BaseOutputPath) a $(BaseIntermediateOutputPath), jsou ve výchozím nastavení vyloučeny z globů. Excludes jsou reprezentovány vlastností DefaultItemExcludes.

Sada .NET Desktop SDK obsahuje další zahrnutí a vyloučení pro WPF. Další informace najdete v tématu Výchozí nastavení WPF zahrnuje a vylučuje.

Pokud v souboru projektu explicitně definujete některou z těchto položek, pravděpodobně obdržíte chybu sestavení NETSDK1022. Informace o tom, jak chybu vyřešit, najdete v tématu NETSDK1022: Byly zahrnuty duplicitní položky.

Implicitní direktivy using

Počínaje rozhraním .NET 6 se implicitní global using direktivy přidávají do nových projektů jazyka C#. To znamená, že můžete použít typy definované v těchto oborech názvů, aniž byste museli zadat jejich plně kvalifikovaný název nebo ručně přidat direktivu using . Implicitní aspekt odkazuje na skutečnost, že global using direktivy jsou přidány do vygenerovaného souboru v adresáři obj projektu.

Pro projekty, které používají jednu z následujících sad SDK, se přidávají implicitní global using direktivy:

  • Microsoft.NET.Sdk
  • Microsoft.NET.Sdk.Web
  • Microsoft.NET.Sdk.Worker
  • Microsoft.NET.Sdk.WindowsDesktop

Pro každý obor názvů v sadě výchozích oborů názvů, která je založena na SDK projektu, se přidá direktiva. Tyto výchozí obory názvů jsou uvedeny v následující tabulce.

Sada pro vývoj softwaru (SDK) Výchozí obory názvů
Microsoft.NET.Sdk System
System.Collections.Generic
System.IO
System.Linq
System.Net.Http
System.Threading
System.Threading.Tasks
Microsoft.NET.Sdk.Web Obory názvů 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 Obory názvů Microsoft.NET.Sdk
Microsoft.Extensions.Configuration
Microsoft.Extensions.DependencyInjection
Microsoft.Extensions.Hosting
Microsoft.Extensions.Logging
Microsoft.NET.Sdk.WindowsDesktop (Windows Forms) Obory názvů Microsoft.NET.Sdk
System.Drawing
System.Windows.Forms
Microsoft.NET.Sdk.WindowsDesktop (WPF) Obory názvů Microsoft.NET.Sdk
Odstraněno System.IO
Odstraněno System.Net.Http

Pokud chcete tuto funkci zakázat nebo pokud chcete povolit implicitní global using direktivy v existujícím projektu jazyka ImplicitUsings C#, můžete to provést prostřednictvím vlastnosti MSBuild.

Další implicitní global using direktivy můžete zadat přidáním Using položek (nebo Import položek pro projekty jazyka Visual Basic) do souboru projektu, například:

<ItemGroup>
  <Using Include="System.IO.Pipes" />
</ItemGroup>

Poznámka:

Počínaje sadou .NET 8 SDK, System.Net.Http již není zahrnuta v Microsoft.NET.Sdk při cílení na .NET Framework.

Implicitní odkazy na balíčky

Když projekt cílí na .NET Standard 1.0-2.0, sada .NET SDK přidá implicitní odkazy na určité metabalíčky. Metabalíč je balíček založený na rozhraní, který se skládá pouze ze závislostí na jiných balíčcích. Metabalíčky se implicitně odkazují na základě cílových architektur zadaných ve vlastnosti TargetFramework nebo TargetFrameworks (množné číslo) vašeho souboru projektu.

<PropertyGroup>
  <TargetFramework>netstandard2.0</TargetFramework>
</PropertyGroup>

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

V případě potřeby můžete implicitní odkazy na balíčky zakázat pomocí vlastnosti DisableImplicitFrameworkReferences a přidat explicitní odkazy pouze na architektury nebo balíčky, které potřebujete.

Doporučení:

  • Při cílení na rozhraní .NET Framework nebo .NET Standard 1.0-2.0 nepřidávejte explicitní odkaz na NETStandard.Library metabalíky prostřednictvím <PackageReference> položky v souboru projektu. U projektů .NET Standard 1.0-2.0 se na tyto metabalíčky implicitně odkazují. V případě projektů .NET Framework, pokud je při použití balíčku NuGet založeného na .NET Standard potřeba jakákoli verze NETStandard.Library, NuGet tuto verzi automaticky nainstaluje.
  • Pokud při cílení na .NET Standard 1.0-2.0 potřebujete konkrétní verzi NETStandard.Library metabalíku, můžete použít <NetStandardImplicitPackageVersion> vlastnost a nastavit požadovanou verzi.

Události sestavení

V projektech ve stylu sady SDK použijte cíl nástroje MSBuild s názvem PreBuild nebo PostBuild a nastavte vlastnost BeforeTargets pro PreBuild nebo vlastnost AfterTargets pro PostBuild.

<Target Name="PreBuild" BeforeTargets="PreBuildEvent">
    <Exec Command="&quot;$(ProjectDir)PreBuildEvent.bat&quot; &quot;$(ProjectDir)..\&quot; &quot;$(ProjectDir)&quot; &quot;$(TargetDir)&quot;" />
</Target>

<Target Name="PostBuild" AfterTargets="PostBuildEvent">
   <Exec Command="echo Output written to $(TargetDir)" />
</Target>

Poznámka:

  • Pro cíle nástroje MSBuild můžete použít libovolný název. Integrované vývojové prostředí sady Visual Studio ale rozpozná cíle PreBuild a PostBuild, takže pomocí těchto názvů můžete upravit příkazy v tomto prostředí.
  • Vlastnosti PreBuildEvent a PostBuildEvent nejsou doporučené v projektech ve stylu sady SDK, protože makra, jako $(ProjectDir) jsou například nejsou vyřešena. Například následující kód není podporován:
<PropertyGroup>
  <PreBuildEvent>"$(ProjectDir)PreBuildEvent.bat" "$(ProjectDir)..\" "$(ProjectDir)" "$(TargetDir)"</PreBuildEvent>
</PropertyGroup>

Přizpůsobit sestavení

Sestavení můžete přizpůsobit různými způsoby. Vlastnost můžete přepsat tak, že ji předáte jako argument příkazu msbuild nebo příkazu dotnet. Vlastnost můžete také přidat do souboru projektu nebo do souboru Directory.Build.props. Seznam užitečných vlastností pro projekty .NET najdete v referenčních informacích k nástroji MSBuild pro projekty .NET SDK.

Návod

Snadný způsob, jak vytvořit nový soubor Directory.Build.props z příkazového řádku, je pomocí příkazu dotnet new buildprops v kořenovém adresáři úložiště.

Vlastní cíle

Projekty .NET mohou zabalit vlastní cíle a vlastnosti nástroje MSBuild pro použití projekty, které balíček využívají. Tento typ rozšiřitelnosti použijte, pokud chcete:

  • Rozšiřte proces sestavení.
  • Získejte přístup k artefaktům procesu sestavení, jako jsou vygenerované soubory.
  • Zkontrolujte konfiguraci, pod kterou se sestavení vyvolá.

Vlastní cíle sestavení nebo vlastnosti přidáte umístěním souborů do formuláře <package_id>.targets nebo <package_id>.props (například Contoso.Utility.UsefulStuff.targets) do složky sestavení projektu.

Následující XML je výňatek ze souboru .csproj, který dává příkazu dotnet pack pokyn, co se má zabalit. Element <ItemGroup Label="dotnet pack instructions"> umístí cílové soubory do složky sestavení uvnitř balíčku. Prvek <Target Name="CollectRuntimeOutputs" BeforeTargets="_GetPackageFiles"> umístí sestavení a .json soubory do složky sestavení .

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

Pro přidání vlastního cíle do projektu přidejte prvek PackageReference, který odkazuje na balíček a jeho verzi. Na rozdíl od nástrojů je balíček vlastních cílů zahrnutý v rámci závislostí projektu, který ho využívá.

Můžete nakonfigurovat, jak používat přizpůsobený cíl. Vzhledem k tomu, že se jedná o úlohu MSBuild, může záviset na určené cílové úloze, spustit po jiné úloze nebo ji ručně spustit pomocí dotnet msbuild -t:<target-name> příkazu. Pokud ale chcete zajistit lepší uživatelské prostředí, můžete kombinovat nástroje pro jednotlivé projekty a vlastní cíle. V tomto scénáři nástroj pro jednotlivé projekty přijímá potřebné parametry a překládá je do požadovaného dotnet msbuild vyvolání, které spouští cíl. V rámci projektu si můžete prohlédnout ukázku tohoto druhu součinnosti na repozitáři vzorků dotnet-packer.

Viz také