Sady SDK projektu .NET

Článek
04/30/2024

Moderní projekty .NET jsou přidružené k sadě SDK (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

K dispozici jsou následující sady SDK:

ID	Popis	Úložiště
`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.BlazorWebAssembly`	Sada .NET Blazor WebAssembly SDK	https://github.com/dotnet/aspnetcore
`Microsoft.NET.Sdk.Razor`	Sada .NET Razor SDK	https://github.com/dotnet/aspnetcore
`Microsoft.NET.Sdk.Worker`	Sada .NET Worker Service SDK

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

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

Pro projekty model 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.

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">
  ...
</Project>

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 horní část souboru projektu a Sdk.targets dole.

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

Tip

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, protože ho nástroj MSBuild uvidí po sadě SDK a jeho cílech pomocí dotnet msbuild -preprocess příkazu. 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, vložené prostředky aNonepoložky jsou definovány Compile 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 v případě potřeby menší a srozumitelnější a ručně upravit.

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

Element (Prvek)	Zahrnout glob	Vyloučení globu	Odebrání globu
Compile	*/.cs (nebo jiná jazyková rozšíření)	*/.Uživatele; */.Proj; /.sln; */.vssscc	–
EmbeddedResource	*/.resx	*/.Uživatele; */.Proj; /.sln; */.vssscc	–
None	*/	*/.Uživatele; */.Proj; /.sln; */.vssscc	*/.Cs; */.resx

Poznámka:

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

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 explicitně definujete některou z těchto položek v souboru projektu, pravděpodobně se zobrazí chyba NETSDK1022 sestavení. 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 global using každý obor názvů se přidá direktiva v sadě výchozích oborů názvů, které jsou založené na sadě SDK projektu. Tyto výchozí obory názvů jsou uvedeny v následující tabulce.

Sada 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 (model 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ěn System.IO Odstraněn 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>

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, 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 nastavte BeforeTargets vlastnost nebo PreBuildAfterTargets vlastnost 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á a PreBuildPostBuild cíl, takže pomocí těchto názvů můžete příkazy v integrovaném vývojovém prostředí upravit.
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ůsobení 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 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.

Tip

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í kód XML je fragment kódu ze souboru .csproj , který dává příkazu pokyn, dotnet pack 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>

Pokud chcete využívat vlastní cíl v projektu, přidejte PackageReference prvek, který odkazuje na balíček a jeho verzi. Na rozdíl od nástrojů je balíček vlastních cílů zahrnutý do uzavření závislostí projektu využívajícího.

Můžete nakonfigurovat, jak používat vlastní cíl. Vzhledem k tomu, že se jedná o cíl NÁSTROJE MSBuild, může záviset na daném cíli, spustit po jiném cíli nebo ho ručně vyvolat 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 projektu si můžete prohlédnout ukázku tohoto druhu součinnosti na MVP Summitu 2016 Hackathon.dotnet-packer