.NET proje SDK'ları

.NET Core ve .NET 5 ve sonraki projeler bir yazılım geliştirme seti (SDK) ile ilişkilendirilmiştir. Her proje SDK'sı, MSBuild, paketleme ve yayımlamadan sorumlu olan bir dizi farklı hedef ve ilişkili görevdir. Bir proje SDK'sine başvurulan bir proje bazen SDK stilinde proje olarak adlandırılır.

Kullanılabilir SDK'lar

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

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

Ayrıca, NuGet aracılığıyla dağıtılacak kendi SDK'NuGet.

*.NET 5'te Windows Formlar ve Windows Presentation Foundation (WPF) projelerinde yerine .NET SDK ( Microsoft.NET.Sdk ) belirt Microsoft.NET.Sdk.WindowsDesktop gerekir. Bu projeler için ayarı ve TargetFramework veya net5.0-windows olarak UseWPF UseWindowsForms true ayarlanırsa, masaüstü SDK'Windows otomatik olarak içeri aktarılır. Projeniz .NET 5 veya sonraki bir sürümü hedeflese ve Microsoft.NET.Sdk.WindowsDesktop SDK'yı belirtirse, NETSDK1137 derleme uyarısıyla karşınıza çıkar.

Project dosyaları

.NET projeleri, MSBuild temel alan bir biçimdir. Project projeleri için .csproj ve F# projeleri için .fsproj gibi uzantılara sahip dosyalar XML biçimindedir. Bir proje dosyasının MSBuild öğesi, Project öğesidir. öğesi, Project hangi Sdk SDK'nın (ve sürümün) kullanılamayacaklarını belirten isteğe bağlı bir özniteliğine sahip. .NET araçlarını kullanmak ve kodunuzu derlemek için özniteliğini Kullanılabilir Sdk CD'ler tablosunda kimliklerden biri olarak ayarlayın.

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

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

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

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

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

Sdk'ya bu yöntemlerden birini kullanarak başvurmak, .NET için proje dosyalarını büyük ölçüde basitleştiriyor. Proje değerlendirme sırasında MSBuild dosyanın üst kısmında ve alt kısmında için Sdk.props örtülü içeri Sdk.targets 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>

Proje dosyasını ön işleme

SDK ve hedefleri dahil edildikten sonra MSBuild tam olarak genişletilmiş projeyi görmek için komutunu dotnet msbuild -preprocess kullanın. Komutun ön işlem anahtarı, projeyi oluşturmadan hangi dosyaların içe aktarılmış olduğunu, kaynaklarını ve dotnet msbuild derlemeye olan katkılarını gösterir.

Proje birden çok hedef çerçeveye sahipse, komut sonuçlarını yalnızca bir çerçeveye odaklanarak bunu bir MSBuild belirtin. Örnek:

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

Varsayılan dahil ve dışlamalar

Varsayılan öğeler, katıştırılmış kaynaklar ve Compile öğeleri için içerirve None dışlar SDK'da tanımlanır. SDK olmayan .NET Framework projelerden farklı olarak, bu öğeleri proje dosyanıza belirtmenize gerek yoktur çünkü varsayılanlar en yaygın kullanım durumlarını içerir. Bu davranış proje dosyasını daha küçük hale getirir ve gerekirse el ile daha kolay anlaşılır ve düzenlenebilir.

Aşağıdaki tabloda .NET SDK'sı içinde hangi öğelerin ve hangi globların dahil olduğu ve dışlanmış olduğu gösterir:

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

Derleme hataları

Proje dosyanıza 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 varsayılan olarak Compile proje dizininizin ' öğelerini içerir. Bu öğeleri proje dosyanıza açıkça eklemek için proje dosyanıza kaldırabilir veya 'EnableDefault Items' özelliğini Compile 'false' olarak ayarlayın.

Yinelenen ' EmbeddedResource ' öğeleri dahil edildi. .NET SDK varsayılan olarak EmbeddedResource proje dizininizin ' öğelerini içerir. Bu öğeleri proje dosyanıza açıkça eklemek için proje dosyanıza kaldırabilir veya 'EnableDefault Items' özelliğini EmbeddedResource 'false' olarak ayarlayın.

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

• Önceki tabloda Compile listelenen EmbeddedResource örtülü None öğelerle eşan açık , veya öğelerini kaldırın.

• EnableDefaultItems özelliğini, tüm örtülü false dosya dahil etme özelliğini devre dışı bırakmak için olarak ayarlayın:

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

  Uygulamanıza yayımlanacak dosyaları belirtmek için, bu öğe gibi bilinen MSBuild mekanizmalarını kullanmaya devam Content edersiniz.

• Compile EmbeddedResource None EnableDefault Items , EnableDefault Compile Itemsveya EnableDefault EmbeddedResource Items None özelliğini olarak ayarerek yalnızca , veya globlarını seçmeli olarak devre dışı false bırakma:

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

  Yalnızca globları devre dışı Çözüm Gezgini, Visual Studio proje kapsamında .cs öğelerini öğe Compile * olarak da None gösterir. Örtülü glob'ı devre None dışı bırakmak için de olarak EnableDefaultNoneItems false ayarlayın.

Yönergeleri kullanarak örtülü

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

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

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

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

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

Proje dosyanıza öğe (veya Visual Basic öğeleri) ekleyerek ek global using Using örtülü yönergeler Import 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, proje dosyanıza bir öğe aracılığıyla veya meta veri paketlerine açık bir başvuru Microsoft.NETCore.App NETStandard.Library <PackageReference> ekleyin. .NET Core 1.0 - 2.2 ve .NET Standard 1.0 - 2.0 projeleri için bu meta paketlere örtülü olarak başvurur. Bu .NET Framework, .NET Standard tabanlı bir NuGet paketi kullanırken herhangi bir NETStandard.Library 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, meta pakete başvurmak yerine projenizin <RuntimeFrameworkVersion> ö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.
• .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 kullanabilir ve ihtiyacınız NETStandard.Library <NetStandardImplicitPackageVersion> olan sürümü ayarlayabilirsiniz.

Derleme olayları

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

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

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çersiz kılmak istiyor olabilir. Özelliğini proje dosyasına veya bir Directory.Build.props dosyasına da ekebilirsiniz. .NET projeleri için yararlı özelliklerin listesi için bkz. .NET SDK MSBuild için başvuru.

Özel hedefler

.NET projeleri, özel MSBuild ve özellikleri paketi kullanan projeler tarafından kullanım için pakete dahil olabilir. Ş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 (örneğin, ) formuna yerleştirerek özel derleme <package_id>.targets <package_id>.props hedefleri veya özellikleri Contoso.Utility.UsefulStuff.targets eklersiniz.

Aşağıdaki XML, komutuna neyi paketley talimatı olan bir .csproj dotnet pack dosyasından bir kod parçacığıdır. <ItemGroup Label="dotnet pack instructions">öğesi, hedef dosyaları paketin içindeki derleme klasörüne yer almaktadır. öğesi <Target Name="CollectRuntimeOutputs" BeforeTargets="_GetPackageFiles"> derlemeleri ve .json dosyalarını 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 dotnet msbuild -t:<target-name> ç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. Projesinde MVP Zirvesi 2016 Hackathon örnek repolarında bu tür bir sinerji örneği dotnet-packer yer alıyor.

Ayrıca bkz.

• .NET Core yükleme
• MSBuild proje SDK'lerini kullanma
• Özel MSBuild hedeflerini ve tekliflerini NuGet