Sdílet prostřednictvím

Sady SDK projektu .NET

  • Článek

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ří:

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.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 .NET Worker Service SDK https://github.com/dotnet/aspnetcore
Aspire.AppHost.Sdk Sada .NET Aspire SDK https://github.com/dotnet/aspire
MSTest.Sdk Sada 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 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.

Sady SDK nástroje MSBuild, které můžete použít ke konfiguraci a rozšíření sestavení, jsou uvedeny v sadách SDK nástroje MSBuild.

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 naleznete 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 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 aNone polož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živatel; **/*.*proj; **/*.sln; **/*.vssscc –
EmbeddedResource **/*.resx **/*.uživatel; **/*.*proj; **/*.sln; **/*.vssscc –
None **/* **/*.uživatel; **/*.*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>

Poznámka:

Počínaje sadou .NET 8 SDK System.Net.Http už není zahrnuta Microsoft.NET.Sdk při cílení na rozhraní .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, 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 PreBuild AfterTargets 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 PreBuild PostBuild 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

Viz také