.NET-projekt SDK-k

A modern .NET-projektek projektszoftver-fejlesztési készlethez (SDK) vannak társítva. Minden projekt SDK msBuild célok és kapcsolódó feladatok készlete, amelyek a kód összeállításáért, csomagolásáért és közzétételéért felelősek. A projekt SDK-ra hivatkozó projekteket néha SDK-stílusú projektnek is nevezik.

Elérhető SDK-k

Az elérhető SDK-k a következők:

A .NET SDK a .NET alap SDK-ja. A többi SDK a .NET SDK-ra hivatkozik, a többi SDK-hoz társított projektek pedig az összes .NET SDK-tulajdonsággal rendelkeznek. A webes SDK például a .NET SDK-tól és a Razor SDK-tól is függ.

Windows Forms és Windows megjelenítési alaprendszer (WPF) projektek esetén adja meg a .NET SDK-t (Microsoft.NET.Sdk), és adjon meg néhány további tulajdonságot a projektfájlban. További információ: .NET Desktop SDK engedélyezése.

A build konfigurálásához és bővítéséhez használható MSBuild SDK-k az MSBuild SDK-kban találhatók.

Saját SDK-t is létrehozhat, amely a NuGeten keresztül terjeszthető.

Projektfájlok

A .NET-projektek az MSBuild formátumon alapulnak . A C#-projektekhez a .csproj és az F#-projektekhez készült .fsproj kiterjesztésű projektfájlok XML formátumúak. Az MSBuild projektfájl gyökéreleme a Project elem. Az Project elem rendelkezik egy választható Sdk attribútummal, amely meghatározza, hogy melyik SDK-t (és verziót) használja. A .NET-eszközök használatához és a kód létrehozásához állítsa be az Sdk attribútumot az Elérhető SDK-táblák egyik azonosítójára.

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

Az Project/Sdk attribútum és Sdk az elem lehetővé teszi az additív SDK-k használatát. Vegye figyelembe a következő példát, ahol a .NET Aspire SDK (Aspire.AppHost.Sdk) hozzáadódik a projekthez a Microsoft.NET.Sdkkövetkező címen:

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

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

</Project>

Az előző projektfájlban mindkét SDK az additív jellegű függőségek feloldására szolgál. További információ: .NET Aspire SDK.

A NuGetből származó SDK megadásához adja meg a név végén található verziót, vagy adja meg a nevet és a verziót a global.json fájlban.

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

Az SDK megadásának másik módja a legfelső szintű Sdk elem:

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

Ha ilyen módon hivatkozik egy SDK-ra, az jelentősen leegyszerűsíti a .NET-hez készült projektfájlokat. A projekt kiértékelése során az MSBuild implicit importot Sdk.props ad hozzá a projektfájl tetején és Sdk.targets alján.

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

A projektfájl előfeldolgozása

A teljes mértékben kibontott projektet az MSBuild látja, miután az SDK és a célokat a parancs használatával dotnet msbuild -preprocess belefoglalta. A parancs előfeldolgozási kapcsolója megmutatja, dotnet msbuild hogy mely fájlokat importálja a rendszer, milyen forrásokkal és hozzájárulásokkal járul hozzá a buildhez a projekt tényleges létrehozása nélkül.

Ha a projekt több cél-keretrendszert is tartalmaz, a parancs eredményeit csak egy keretrendszerre összpontosíthatja, ha MSBuild tulajdonságként adja meg. Példa:

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

Az alapértelmezett tartalmazza és kizárja

Az alapértelmezett elemek, beágyazott erőforrások és Compile elemek az SDK-ban vannak definiálva és kizárvaNone. A nem SDK-.NET-keretrendszer projektektől eltérően ezeket az elemeket nem kell megadnia a projektfájlban, mert az alapértelmezett értékek a leggyakoribb használati esetekre vonatkoznak. Ez a viselkedés kisebbé teszi a projektfájlt, és szükség esetén könnyebben érthetővé és szerkeszthetővé teszi a projektfájlt.

Az alábbi táblázat a .NET SDK-ban szereplő és kizárt elemeket és globokat mutatja be:

A .NET Desktop SDK-nak további tartalmai és kizárásai vannak a WPF-hez. További információ: A WPF alapértelmezett tartalma és kizárása.

Ha a projektfájlban explicit módon definiálja ezeket az elemeket, valószínűleg NETSDK1022 buildelési hibát fog kapni. A hiba megoldásáról további információt a NETSDK1022: Ismétlődő elemek szerepeltek benne.

Implicit, direktívák használatával

A .NET 6-tól kezdve implicit global using irányelvek jelennek meg az új C#-projektekben. Ez azt jelenti, hogy az ezekben a névterekben definiált típusokat anélkül használhatja, hogy meg kellene adnia a teljes nevet, vagy manuálisan kellene hozzáadnia egy using irányelvet. Az implicit szempont arra utal, hogy az global using irányelveket hozzáadják egy létrehozott fájlhoz a projekt obj könyvtárában.

Implicit global using irányelvek jelennek meg az alábbi SDK-k egyikét használó projektekhez:

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

A global using rendszer a projekt SDK-ján alapuló alapértelmezett névterek minden egyes névteréhez hozzáad egy direktívát. Ezek az alapértelmezett névterek az alábbi táblázatban láthatók.

Ha le szeretné tiltani ezt a funkciót, vagy ha implicit irányelveket szeretne engedélyezni global using egy meglévő C#-projektben, ezt az ImplicitUsings MSBuild tulajdonságon keresztül teheti meg.

További implicit global using direktívák megadásához elemeket Using (vagy Import Visual Basic-projektek elemeit) adhat hozzá a projektfájlhoz, például:

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

Implicit csomaghivatkozások

Amikor a projekt a .NET Standard 1.0-2.0-s verziót célozza, a .NET SDK implicit hivatkozásokat ad hozzá bizonyos metacsomagokhoz. A metacsomagok olyan keretrendszeralapú csomagok, amelyek csak más csomagoktól való függőségekből állnak. A metacsomagokra implicit módon hivatkozunk a projektfájl TargetFramework vagy TargetFrameworks (többes szám) tulajdonságában megadott cél-keretrendszerek alapján.

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

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

Szükség esetén letilthatja az implicit csomaghivatkozásokat a DisableImplicitFrameworkReferences tulajdonsággal, és explicit hivatkozásokat adhat hozzá csak a szükséges keretrendszerekhez vagy csomagokhoz.

Ajánlások:

• Ha .NET-keretrendszer vagy .NET Standard 1.0-2.0-s verziót céloz meg, ne adjon hozzá explicit hivatkozást a NETStandard.Library metacsomagokra a projektfájl egyik <PackageReference> elemével. A .NET Standard 1.0-2.0-s projektek esetében ezekre a metacsomagokra implicit módon hivatkozunk. Ha .NET-keretrendszer projektek esetében a .NET Standard-alapú NuGet-csomag használatakor bármilyen verzióra NETStandard.Library van szükség, a NuGet automatikusan telepíti ezt a verziót.
• Ha a .NET Standard 1.0-2.0-s verziójának megcélzásakor szüksége van a NETStandard.Library metacsomag adott verziójára, használhatja a <NetStandardImplicitPackageVersion> tulajdonságot, és beállíthatja a szükséges verziót.

Események létrehozása

SDK-stílusú projektekben használjon egy MSBuild nevű célértéketPreBuild, vagy PostBuild állítsa be a BeforeTargets tulajdonságot PreBuild vagy a tulajdonságotAfterTargets.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>

<PropertyGroup>
  <PreBuildEvent>"$(ProjectDir)PreBuildEvent.bat" "$(ProjectDir)..\" "$(ProjectDir)" "$(TargetDir)"</PreBuildEvent>
</PropertyGroup>

A build testreszabása

A buildek testreszabásának különböző módjai vannak. Érdemes lehet felülbírálni egy tulajdonságot úgy, hogy argumentumként átadja az msbuild vagy dotnet parancsnak. A tulajdonságot a projektfájlhoz vagy a Directory.Build.props fájlhoz is hozzáadhatja. A .NET-projektek hasznos tulajdonságainak listáját az MSBuild .NET SDK-projektekre vonatkozó hivatkozásában találja.

Egyéni célok

A .NET-projektek egyéni MSBuild-célokat és tulajdonságokat csomagolhatnak a csomagot használó projektek számára. Az alábbi bővíthetőségi típust használja a következő esetekben:

• A buildelési folyamat kiterjesztése.
• Hozzáférés a buildelési folyamat összetevőihez, például a létrehozott fájlokhoz.
• Vizsgálja meg a build meghívásának konfigurációját.

Egyéni buildcélokat vagy tulajdonságokat úgy adhat hozzá, hogy fájlokat helyez el az űrlapon <package_id>.targets vagy <package_id>.props (például) a Contoso.Utility.UsefulStuff.targets.

A következő XML egy .csproj fájlból származó kódrészlet, amely a parancsnak a csomagra vonatkozó utasítását adja dotnet pack meg. Az <ItemGroup Label="dotnet pack instructions"> elem a célfájlokat a csomag buildmappájába helyezi. Az <Target Name="CollectRuntimeOutputs" BeforeTargets="_GetPackageFiles"> elem a szerelvényeket és .json fájlokat a buildmappába helyezi.

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

Ha egyéni célértéket szeretne használni a projektben, adjon hozzá egy PackageReference elemet, amely a csomagra és annak verziójára mutat. Az eszközökkel ellentétben az egyéni célcsomag a fogyasztó projekt függőségi zárása részét képezi.

Konfigurálhatja az egyéni cél használatát. Mivel ez egy MSBuild-cél, függhet egy adott céltól, futtatható egy másik cél után, vagy manuálisan hívható meg a dotnet msbuild -t:<target-name> parancs használatával. A jobb felhasználói élmény érdekében azonban kombinálhatja a projektenkénti eszközöket és az egyéni célokat. Ebben a forgatókönyvben a projektenkénti eszköz elfogadja a szükséges paramétereket, és lefordítja azt a cél végrehajtásához szükséges dotnet msbuild meghívásra. A projekt MVP Summit 2016 Hackathon-mintáinakdotnet-packerlátható.

Lásd még

• A build testreszabása (MSBuild)
• MSBuild projekt SDK-k használata
• Egyéni MSBuild-célok és kellékek csomagolása a NuGettel