.NET projesi SDK 'Ları

.NET Core ve .NET 5 ve sonraki projeler yazılım geliştirme seti (SDK) ile ilişkilendirilir. her proje SDK 'sı , kodu derleme, paketleme ve yayımlama konusunda sorumlu bir MSBuild hedefi ve ilişkili görevler kümesidir. Proje SDK 'Sına başvuran bir proje bazen bir SDK stili projeolarak adlandırılır.

Kullanılabilir SDK 'lar

Aşağıdaki SDK 'lar kullanılabilir:

ID Description Depo
Microsoft.NET.Sdk .NET SDK https://github.com/dotnet/sdk
Microsoft.NET.Sdk.Web .NET Web SDK 'sı https://github.com/dotnet/sdk
Microsoft.NET.Sdk.BlazorWebAssembly .NET webassembly SDK 'sı
Microsoft.NET.Sdk.Razor .NET Razor SDK 'sı
Microsoft.NET.Sdk.Worker .NET Worker hizmeti SDK 'Sı
Microsoft.NET.Sdk.WindowsDesktop Windows Forms (WinForms) ve Windows Presentation Foundation (WPF) içeren .net Desktop SDK. * https://github.com/dotnet/winforms ve https://github.com/dotnet/wpf

.NET SDK, .NET için temel SDK 'dir. Diğer SDK 'lar .NET SDK 'ya başvuru sağlar ve diğer SDK 'lar ile ilişkili projelere tüm .NET SDK özellikleri de mevcuttur. Örneğin, Web SDK 'sı, hem .NET SDK hem de Razor SDK 'ya bağlıdır.

Ayrıca, NuGet aracılığıyla dağıtılabilecek kendi SDK 'nizi de yazabilirsiniz.

* .net 5 ' den itibaren Windows Forms ve Windows Presentation Foundation (WPF) projeleri yerine Microsoft.NET.Sdk.WindowsDesktop .net SDK ( Microsoft.NET.Sdk ) belirtmelidir. bu projeler için, ve UseWindowsFormsUseWPFtrue için ayarı TargetFrameworknet5.0-windows , Windows masaüstü SDK 'sını otomatik olarak içeri aktarır. Projeniz .NET 5 veya üstünü hedefliyorsa ve SDK 'yı belirtirse Microsoft.NET.Sdk.WindowsDesktop , derleme uyarısı NETSDK1137 alırsınız.

Project dosyaları

.net projeleri MSBuild biçimine dayalıdır. C# projeleri için . csproj ve F # projeleri için . fsproj gibi uzantılara sahip Project dosyaları XML biçimindedir. MSBuild proje dosyasının kök öğesi Project öğesidir. ProjectÖğesi HANGI SDK (ve sürümü) kullanacağınızı belirten isteğe bağlı Sdk bir özniteliğe sahiptir. .NET araçlarını kullanmak ve kodunuzu derlemek için, özniteliğini Sdk 'Lar tablosundaki kimliklerden birine ayarlayın Sdk .

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

NuGet gelen bir SDK 'yı belirtmek için, adın sonundaki sürümü ekleyin veya global. json dosyasındaki adı ve sürümü belirtin.

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

SDK 'yı belirtmenin bir başka yolu da en üst düzey SDK öğesidir:

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

Bu yollarla bir SDK 'ya başvurmak, .NET için proje dosyalarını büyük ölçüde basitleştirir. proje değerlendirilirken MSBuild, proje dosyasının üst kısmına ve Sdk.targets alt kısmına örtük içeri aktarmalar Sdk.props ekler.

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

İpucu

Windows bir makinede sdk. props ve sdk. targets dosyaları %ProgramFiles%\dotnet\sdk\ [version] \Sdks\Microsoft.NET.Sdk\Sdk klasöründe bulunabilir.

Proje dosyasını ön işleme

tam genişletilmiş projeyi, SDK ve hedefi komutu kullanılarak dotnet msbuild -preprocess dahil edildikten sonra MSBuild gördüğü şekilde görebilirsiniz. Komutun ön işlem anahtarı hangi dosyaların içeri aktarılacağını, kaynaklarını ve derleme için gerçekten projeyi oluşturmadan yapıya katkılarını gösterir.

projede birden çok hedef çerçeve varsa, komutun sonuçlarını MSBuild özelliği olarak belirterek yalnızca bir çerçeveye odaklayın. Örneğin:

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

Varsayılan içerme ve dışladığı

Öğelerin, katıştırılmış kaynaklarınve öğelerin varsayılan dahil ve hariç olması SDK 'da tanımlanmıştır. SDK olmayan .NET Framework projelerinin aksine, varsayılanlar en yaygın kullanım durumlarını kapsadığından proje dosyanızda bu öğeleri belirtmeniz gerekmez. Bu davranış, proje dosyasını daha küçük ve gerektiğinde daha kolay anlaşılır ve düzenlenebilir hale getirir.

Aşağıdaki tabloda, .NET SDK 'sında hangi öğelerin ve hangi genelleştirmeler dahil olduğu ve dışlandıkları gösterilmektedir:

Öğe Glob 'yi dahil et Glob 'yi hariç tut Glob 'yi kaldır
Compile * */*. cs (veya diğer dil uzantıları) * */*. Kullanıcı; * */*. * proj; * */*. sln; * */*. vssscc Yok
EmbeddedResource * */*. resx * */*. Kullanıcı; * */*. * proj; * */*. sln; * */*. vssscc Yok
None **/* * */*. Kullanıcı; * */*. * proj; * */*. sln; * */*. vssscc * */*. cs; * */*. resx

Not

./binve MSBuild özellikleriyle temsil edilen $(BaseOutputPath)$(BaseIntermediateOutputPath) ve ./obj klasörleri varsayılan olarak genelleştirmeler dışında tutulur. Dışlayarak DefaultItemExcludes özelliğitarafından temsil edilir.

.NET masaüstü SDK 'sının WPF için daha fazla içerme ve dışladığı vardır. Daha fazla bilgi için bkz. WPF varsayılan içerme ve dışladığı.

Derleme hataları

Proje dosyanızda bu öğelerden herhangi birini açıkça tanımlarsanız, büyük olasılıkla aşağıdakine benzer bir "NETSDK1022" derleme hatası alırsınız:

Yinelenen ' Compile ' öğeleri eklendi. .NET SDK, varsayılan olarak proje dizininizdeki ' Compile ' öğelerini içerir. Proje dosyanızdaki bu öğeleri kaldırabilir ya da bunları proje dosyanıza açıkça dahil etmek istiyorsanız ' EnableDefault Compile Items ' özelliğini ' false ' olarak ayarlayabilirsiniz.

Yinelenen ' EmbeddedResource ' öğeleri eklendi. .NET SDK, varsayılan olarak proje dizininizdeki ' EmbeddedResource ' öğelerini içerir. Proje dosyanızdaki bu öğeleri kaldırabilir ya da bunları proje dosyanıza açıkça dahil etmek istiyorsanız ' EnableDefault EmbeddedResource Items ' özelliğini ' false ' olarak ayarlayabilirsiniz.

Hataları gidermek için aşağıdakilerden birini yapın:

  • Önceki tabloda listelenenlerin bulunduğu açık Compile , EmbeddedResource veya None öğeleri kaldırın.

  • Tüm örtük dosya eklemeyi devre dışı bırakmak için Enabledefaultıtems özelliğini olarak ayarlayın:

    <PropertyGroup>
      <EnableDefaultItems>false</EnableDefaultItems>
    </PropertyGroup>
    

    uygulamanızla yayımlanacak dosyaları belirtmek istiyorsanız, bu gibi bilinen MSBuild mekanizmalarını de kullanabilirsiniz (örneğin, Content öğesi).

  • Compile, EmbeddedResourceveya None özelliğini şu şekilde false ayarlayarak yalnızca Compile , veya None genelleştirmeler öğesini EmbeddedResource Seçmeli olarak devre dışı bırakın:

    <PropertyGroup>
      <EnableDefaultCompileItems>false</EnableDefaultCompileItems>
      <EnableDefaultEmbeddedResourceItems>false</EnableDefaultEmbeddedResourceItems>
      <EnableDefaultNoneItems>false</EnableDefaultNoneItems>
    </PropertyGroup>
    

    yalnızca genelleştirmeler 'yi devre dışı Compile bırakırsanız, Visual Studio Çözüm Gezgini, öğe olarak None da dahil olmak üzere, *. cs öğelerini projenin bir parçası olarak gösterir. Örtük None Glob 'yi devre dışı bırakmak için, çok olarak false ayarlayın EnableDefaultNoneItems .

Örtülü using yönergeleri

.NET 6 ' dan başlayarak, örtülü yönergeler yeni C# projelerine eklenir. Bu, tam adını belirtmek veya el ile bir using yönerge eklemek zorunda kalmadan bu ad alanlarında tanımlanan türleri kullanabileceğiniz anlamına gelir. Örtülü boyut, yönergelerin projenin obj dizinindeki oluşturulan bir dosyaya eklendiği olguyu ifade eder.

Örtülü global using yönergeler aşağıdaki SDK 'lardan birini kullanan projeler için eklenir:

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

Proje SDK 'sını temel alan bir varsayılan ad alanı kümesindeki her ad alanı için bir global using yönerge eklenir. Bu varsayılan ad alanları aşağıdaki tabloda gösterilmiştir.

SDK Varsayılan ad alanları
Microsoft.NET.Sdk System
System.Collections.Generic
System.IO
System.Linq
System.Net.Http
System.Threading
System.Threading.Tasks
Microsoft.NET.Sdk.Web 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 Microsoft.Extensions.Configuration
Microsoft.Extensions.DependencyInjection
Microsoft.Extensions.Hosting
Microsoft.Extensions.Logging
Microsoft. NET. Sdk. windowsdesktop (Windows Forms) Microsoft. NET. SDK ad alanları
System.Drawing
System.Windows.Forms
Microsoft. NET. SDK. WindowsDesktop (WPF) Microsoft. NET. SDK ad alanları
Kaldırıldı System.IO
Kaldırıldı System.Net.Http

Bu özelliği devre dışı bırakmak global using veya mevcut bir C# projesinde örtülü yönergeleri etkinleştirmek için bu global usingözelliği MSBuild.

Proje dosyanıza öğe (Importveya global usingUsing Visual Basic öğeleri) ekleyerek ek örtülü yönergeler belirtebilirsiniz, örneğin:

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

Örtülü paket başvuruları

.NET Core 1.0 - 2.2 veya .NET Standard 1.0 - 2.0'i hedeflerken, .NET SDK belirli meta paketlere örtülü başvurular ekler. Meta paket, yalnızca diğer paketlere bağımlılıklardan oluşan çerçeve tabanlı bir pakettir. Meta paketlere, proje dosyanıza ait TargetFramework veya TargetFrameworks özelliğinde belirtilen hedef çerçevelere bağlı olarak örtülü olarak başvurur.

<PropertyGroup>
  <TargetFramework>netcoreapp2.1</TargetFramework>
</PropertyGroup>
<PropertyGroup>
  <TargetFrameworks>netcoreapp2.1;net462</TargetFrameworks>
</PropertyGroup>

Gerekirse DisableImplicitFrameworkReferences özelliğini kullanarak örtülü paket başvurularını devre dışı bırakabilir ve yalnızca ihtiyacınız olan çerçevelere veya paketlere açık başvurular ebilirsiniz.

Öneriler:

  • .NET Framework, .NET Core 1.0 - 2.2 veya .NET Standard 1.0 - 2.0 hedeflerini hedeflerken, Microsoft.NETCore.AppNETStandard.Library proje dosyanıza bir öğe aracılığıyla veya meta paketlerine <PackageReference> açık bir başvuru ekleyin. .NET Core 1.0 - 2.2 ve .NET Standard 1.0 - 2.0 projeleri için bu meta paketlere örtülü olarak başvuruldu. Bu .NET Framework, NETStandard.Library .NET Standard tabanlı bir NuGet paketi kullanırken herhangi bir sürümü gerekirse, NuGet otomatik olarak yüklenir.
  • .NET Core 1.0 - 2.2'i hedeflerken çalışma zamanının belirli bir sürümüne ihtiyacınız varsa, <RuntimeFrameworkVersion> meta pakete başvurmak yerine projenizin özelliğini (örneğin, 1.0.4) kullanın. Örneğin, kendi içinde dağıtımlar kullanıyorsanız, 1.0.0 LTS çalışma zamanının belirli bir düzeltme eki sürümüne ihtiyacınız olabilir.
  • NETStandard.Library.NET Standard 1.0 - 2.0 sürümünü hedeflerken meta paketin belirli bir sürümüne ihtiyacınız varsa özelliğini <NetStandardImplicitPackageVersion> kullanabilir ve ihtiyacınız olan sürümü ayarlayabilirsiniz.

Derleme olayları

SDK stili projelerde, adlı bir MSBuild hedef kullanın PreBuild ve PostBuild veya BeforeTargets özelliğini PreBuild veya özelliğini AfterTargets ayarlayınPostBuild.

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

Not

  • Hedeflere yönelik herhangi bir ad MSBuild kullanabilirsiniz. Ancak, Visual Studio IDE PreBuildPostBuild ve hedefleri tanır, bu nedenle bu adları kullanarak IDE'de komutları düzenleyebilirsiniz.
  • ve özellikleri PreBuildEventPostBuildEvent SDK stili projelerde önerilmez çünkü gibi makrolar $(ProjectDir) çözümlenmez. Örneğin, aşağıdaki kod desteklenmiyor:
<PropertyGroup>
  <PreBuildEvent>"$(ProjectDir)PreBuildEvent.bat" "$(ProjectDir)..\" "$(ProjectDir)" "$(TargetDir)"</PreBuildEvent>
</PropertyGroup>

Derlemeyi özelleştirme

Bir derlemeyi özelleştirmenin çeşitli yolları vardır. Bir özelliği bir msbuild veya dotnet komutuna bağımsız değişken olarak geçirmeyi geçersizkılmak istiyor olabilir. Özelliğini proje dosyasına veya bir Directory.Build.props dosyasına da ekebilirsiniz. .NET projeleri için kullanışlı özelliklerin listesi için bkz. .NET SDK MSBuild için başvuru.

Özel hedefler

.NET projeleri, özel MSBuild kullanan projeler tarafından kullanım için özel hedef ve özellikleri paketleyeblir. Şunları yapmak için bu tür genişletilebilirlik kullanın:

  • Derleme işlemini genişletme.
  • Oluşturulan dosyalar gibi derleme işleminin yapıtlarına erişin.
  • Derlemenin çağrıldığında yapılandırmayı inceler.

Dosyaları projenin derleme klasörüne veya <package_id>.targets<package_id>.props (örneğin, Contoso.Utility.UsefulStuff.targets) formuna yerleştirerek özel derleme <package_id>.targets veya özellikleri eklersiniz.

Aşağıdaki XML, komutuna neyi paketley talimatı olan bir .csproj dosyasından bir kod parçacığıdır. öğesi <ItemGroup Label="dotnet pack instructions"> , hedef dosyaları paketin <ItemGroup Label="dotnet pack instructions"> klasörüne yer almaktadır. öğesi <Target Name="CollectRuntimeOutputs" BeforeTargets="_GetPackageFiles"> derlemeleri ve <Target Name="CollectRuntimeOutputs" BeforeTargets="_GetPackageFiles"> derleme klasörüne yer almaktadır.

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

Projenize özel bir hedef kullanmak için pakete ve PackageReference sürümüne yönelik bir öğe ekleyin. Araçların aksine, özel hedefler paketi, tüketen projenin bağımlılık kapanışı içinde yer alır.

Özel hedefin nasıl kullan yapılandırıldığından emin olabilirsiniz. Bu bir hedef MSBuild, belirli bir hedefe bağlı olabilir, başka bir hedef sonra çalıştırılabilir veya komutu kullanılarak el ile çağrılabilirdotnet msbuild -t:<target-name>. Ancak, daha iyi bir kullanıcı deneyimi sağlamak için proje başına araçları ve özel hedefleri birleştirebilirsiniz. Bu senaryoda, proje başına araç gereken parametreleri kabul eder ve bunu hedefi yürüten dotnet msbuild gerekli çağrıya çevirir. Projesinde MVP Zirvesi 2016 Hackathon örnek repolarında bu tür bir sinerji örneği yer alıyor.

Ayrıca bkz.