.NET proje SDK'ları

Makale
04/11/2023

.NET Core ve .NET 5 ve üzeri projeler bir yazılım geliştirme seti (SDK) ile ilişkilendirilir. Her proje SDK'sı , kod derleme, paketleme ve yayımlamadan sorumlu bir MSBuild hedefleri ve ilişkili görevler kümesidir. Proje SDK'sına başvuran bir proje bazen SDK stilinde bir proje olarak adlandırılır.

Kullanılabilir SDK'lar

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

Kimlik	Açıklama	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 Blazor WebAssembly SDK'sı	https://github.com/dotnet/aspnetcore
`Microsoft.NET.Sdk.Razor`	.NET Razor SDK'sı	https://github.com/dotnet/aspnetcore
`Microsoft.NET.Sdk.Worker`	.NET Çalışan Hizmeti SDK'sı
`Microsoft.NET.Sdk.WindowsDesktop`	Windows Forms (WinForms) ve Windows Presentation Foundation (WPF) içeren .NET Masaüstü SDK'sı.*	https://github.com/dotnet/winforms ve https://github.com/dotnet/wpf

.NET SDK, .NET için temel SDK'dır. Diğer SDK'lar .NET SDK'sına başvurur ve diğer SDK'larla ilişkilendirilmiş projeler tüm .NET SDK özelliklerine sahiptir. Örneğin Web SDK'sı hem .NET SDK'ya hem de Razor SDK'ya bağlıdır.

NuGet aracılığıyla dağıtabileceğiniz kendi SDK'nızı da yazabilirsiniz.

* .NET 5'den başlayarak, Windows Forms ve Windows Presentation Foundation (WPF) projeleri yerine Microsoft.NET.Sdk.WindowsDesktop.NET SDK'sını (Microsoft.NET.Sdk) belirtmelidir. Bu projeler için, ve UseWPF veya UseWindowsFormstrue olarak ayarlanırsa TargetFrameworknet5.0-windows Windows masaüstü SDK'sı otomatik olarak içeri aktarılır. Projeniz .NET 5 veya üzerini hedefler ve SDK'yı Microsoft.NET.Sdk.WindowsDesktop belirtirse, NETSDK1137 derleme uyarısı alırsınız.

Proje dosyaları

.NET projeleri MSBuild biçimini temel alır. C# projeleri için .csproj ve F# projeleri için .fsproj gibi uzantılara sahip proje dosyaları XML biçimindedir. MSBuild proje dosyasının kök öğesi Project öğesidir. öğesinin Project , hangi SDK'nın (ve sürümün) kullanılacağını belirten isteğe bağlı Sdk bir özniteliği vardır. .NET araçlarını kullanmak ve kodunuzu oluşturmak için özniteliğini Kullanılabilir SDK'lar tablosundaki kimliklerden birine ayarlayınSdk.

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

NuGet'ten gelen bir SDK belirtmek için adın sonuna sürümü ekleyin veya global.json dosyasında adı ve sürümü belirtin.

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

SDK'yi belirtmenin bir diğer yolu da üst düzey Sdk öğesidir:

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

Bir SDK'ya bu yollardan biriyle başvurmak.NET için proje dosyalarını büyük ölçüde basitleştirir. MSBuild, projeyi değerlendirirken proje dosyasının en üstüne ve Sdk.targets en altına için Sdk.props örtük içeri aktarmalar 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

Bir Windows makinesinde 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

MSBuild, SDK ve hedefleri komutu kullanılarak dotnet msbuild -preprocess eklendikten sonra tam olarak genişletilmiş projeyi görebilirsiniz. Komutun dotnet msbuild önişlem anahtarı, projeyi oluşturmadan hangi dosyaların içeri aktarılacağını, kaynaklarını ve derlemeye katkılarını gösterir.

Projenin birden çok hedef çerçevesi varsa, komutu 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 eklemeler ve dışlamalar

Varsayılan olarak öğeler, ekli kaynaklar ve NoneCompile öğeler SDK'da tanımlanır. SDK olmayan .NET Framework projelerinden farklı olarak, varsayılanlar en yaygın kullanım örneklerini kapsadığından bu öğeleri proje dosyanızda belirtmeniz gerekmez. Bu davranış, proje dosyasını küçültür ve gerekirse el ile anlaşılmasını ve düzenlenmesini kolaylaştırır.

Aşağıdaki tabloda.NET SDK'sında hangi öğelerin ve hangi globların dahil ve dışlandığı gösterilmektedir:

Öğe	Glob ekle	Glob'ı dışla	Glob kaldırma
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

./bin ve MSBuild özellikleriyle $(BaseOutputPath) temsil edilen ve ./obj$(BaseIntermediateOutputPath) klasörleri varsayılan olarak glob'ların dışında tutulur. Dışlamalar DefaultItemExcludes özelliğiyle temsil edilir.

.NET Masaüstü SDK'sı WPF için daha fazla içerir ve dışlar. Daha fazla bilgi için bkz. WPF varsayılan ekleme ve dışlamaları.

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 dahil edildi. .NET SDK'sı varsayılan olarak proje dizininizdeki 'Compile' öğelerini içerir. Bu öğeleri proje dosyanızdan kaldırabilir veya proje dosyanıza açıkça eklemek istiyorsanız 'EnableDefaultCompileItems' özelliğini 'false' olarak ayarlayabilirsiniz.

Yinelenen 'EmbeddedResource' öğeleri dahil edildi. .NET SDK'sı varsayılan olarak proje dizininizdeki 'EmbeddedResource' öğelerini içerir. Bu öğeleri proje dosyanızdan kaldırabilir veya proje dosyanıza açıkça eklemek istiyorsanız 'EnableDefaultEmbeddedResourceItems' özelliğini 'false' olarak ayarlayabilirsiniz.

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

Önceki tabloda listelenen örtük öğelerle eşleşen açık Compile, EmbeddedResourceveya None öğelerini kaldırın.
Tüm örtük dosya ekleme özelliğini devre dışı bırakmak için false EnableDefaultItems özelliğini olarak ayarlayın:
```
<PropertyGroup>
  <EnableDefaultItems>false</EnableDefaultItems>
</PropertyGroup>
```
Uygulamanızla yayımlanacak dosyaları belirtmek istiyorsanız, bunun için bilinen MSBuild mekanizmalarını (örneğin, Content öğesi) kullanmaya devam edebilirsiniz.
EnableDefault Items, EnableDefault Items veya EnableDefaultNoneEmbeddedResourceItems özelliğini olarak ayarlayarak yalnızca Compile, EmbeddedResourceveya glob'ları falseseçmeli olarak devre dışı bırakın:NoneCompile
```
<PropertyGroup>
  <EnableDefaultCompileItems>false</EnableDefaultCompileItems>
  <EnableDefaultEmbeddedResourceItems>false</EnableDefaultEmbeddedResourceItems>
  <EnableDefaultNoneItems>false</EnableDefaultNoneItems>
</PropertyGroup>
```
Yalnızca glob'ları devre dışı bırakırsanız Compile Visual Studio'daki Çözüm Gezgini yine de proje kapsamında *.cs öğeleri gösterir ve öğeler olarak None eklenir. Örtük None glob'ı devre dışı bırakmak için false de olarak ayarlayınEnableDefaultNoneItems.

Örtük kullanım yönergeleri

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

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

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

global using Projenin SDK'sını temel alan bir dizi varsayılan ad alanına her ad alanı için bir 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	Microsoft.NET.Sdk ad alanları 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.NET.Sdk ad alanları 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 veya var olan bir C# projesinde örtük global using yönergeleri etkinleştirmek istiyorsanız, bunu MSBuild özelliği aracılığıyla ImplicitUsings yapabilirsiniz.

Proje dosyanıza öğe (veya Import Visual Basic projeleri için öğeler) ekleyerek Using ek örtük global using yönergeler belirtebilirsiniz, örneğin:

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

Örtük paket başvuruları

.NET Core 1.0 - 2.2 veya .NET Standard 1.0 - 2.0 hedeflendiğinde, .NET SDK belirli meta paketlere örtük başvurular ekler. Meta paket oluşturma, yalnızca diğer paketlere bağımlılıklardan oluşan çerçeve tabanlı bir pakettir. Meta paketlere, proje dosyanızın TargetFramework veya TargetFrameworks özelliğinde belirtilen hedef çerçevelere göre örtük olarak başvurulur.

<PropertyGroup>
  <TargetFramework>netcoreapp2.1</TargetFramework>
</PropertyGroup>

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

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

Öneriler:

.NET Framework, .NET Core 1.0 - 2.2 veya .NET Standard 1.0 - 2.0 hedeflenirken, proje dosyanızdaki bir öğe aracılığıyla veya NETStandard.Library meta paketlerine Microsoft.NETCore.App açık bir <PackageReference> başvuru eklemeyin. .NET Core 1.0 - 2.2 ve .NET Standard 1.0 - 2.0 projeleri için bu meta paketlere örtük olarak başvurulur. .NET Framework projeleri için, .NET Standart tabanlı NuGet paketi kullanılırken herhangi bir sürümü NETStandard.Library gerekiyorsa, NuGet bu sürümü otomatik olarak yükler.
.NET Core 1.0 - 2.2'yi hedeflerken çalışma zamanının belirli bir sürümüne ihtiyacınız varsa, meta paketine başvurmak yerine projenizdeki (örneğin, 1.0.4) özelliğini kullanın<RuntimeFrameworkVersion>. Örneğin, bağımsız dağıtımlar kullanıyorsanız 1.0.0 LTS çalışma zamanının belirli bir yama sürümüne ihtiyacınız olabilir.
.NET Standard 1.0 - 2.0'ı hedeflerken meta paketin belirli bir sürümüne NETStandard.Library ihtiyacınız varsa özelliğini kullanabilir <NetStandardImplicitPackageVersion> ve ihtiyacınız olan sürümü ayarlayabilirsiniz.

Olayları derleme

SDK stili projelerde, veya adlı PreBuild bir MSBuild hedefi kullanın ve veya için PostBuildözelliğini PreBuildAfterTargets ayarlayınBeforeTargets.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>

Not

MSBuild hedefleri için herhangi bir ad kullanabilirsiniz. Ancak Visual Studio IDE PreBuildPostBuild , bu adları kullanarak IDE'deki komutları düzenleyebilirsiniz.
gibi makrolar çözümlenmediğinden ve özellikleri PreBuildEventPostBuildEvent SDK stili projelerde $(ProjectDir) önerilmez. Örneğin, aşağıdaki kod desteklenmez:

<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çirerek geçersiz kılmak isteyebilirsiniz. Özelliğini proje dosyasına veya Directory.Build.props dosyasına da ekleyebilirsiniz. .NET projeleri için yararlı özelliklerin listesi için bkz . .NET SDK projeleri için MSBuild başvurusu.

İpucu

Komut satırından yeni bir Directory.Build.props dosyası oluşturmanın kolay bir yolu, deponuzun kökündeki komutu dotnet new buildprops kullanmaktır.

Özel hedefler

.NET projeleri, paketi kullanan projeler tarafından kullanılmak üzere özel MSBuild hedeflerini ve özelliklerini paketleyebilir. Aşağıdaki işlemleri yapmak istediğinizde bu genişletilebilirlik türünü kullanın:

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

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

Aşağıdaki XML, komutuna paketlenmesi gerekenleri belirten bir .csproj dosyasından bir dotnet pack kod parçacığıdır. <ItemGroup Label="dotnet pack instructions"> öğesi, hedef dosyalarını paketin içindeki derleme klasörüne yerleştirir. <Target Name="CollectRuntimeOutputs" BeforeTargets="_GetPackageFiles"> öğesi derlemeleri ve .json dosyalarını derleme klasörüne yerleştirir.

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

Projenizde özel bir hedef kullanmak için pakete ve sürümüne işaret eden bir PackageReference öğe ekleyin. Araçlardan farklı olarak, özel hedefler paketi, tüketen projenin bağımlılık kapanışında yer alır.

Özel hedefin nasıl kullanılacağını yapılandırabilirsiniz. Bu bir MSBuild hedefi olduğundan, belirli bir hedefe bağımlı olabilir, başka bir hedef sonrasında çalışabilir veya komutu kullanılarak dotnet msbuild -t:<target-name> el ile çağrılabilir. 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 gerekli dotnet msbuild çağrıya çevirir. Projedeki MVP Summit 2016 Hackathon samples deposunda bu tür bir sinerji örneği dotnet-packer görebilirsiniz.