.NET proje SDK'ları

Modern .NET projeleri bir proje 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

Kullanılabilir SDK'lar şunlardır:

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

Windows Forms ve Windows Presentation Foundation (WPF) projeleri için .NET SDK'sını (Microsoft.NET.Sdk) belirtir ve proje dosyasında bazı ek özellikler ayarlarsınız. Daha fazla bilgi için bkz . .NET Masaüstü SDK'sını etkinleştirme.

Derlemenizi yapılandırmak ve genişletmek için kullanabileceğiniz MSBuild SDK'ları MSBuild SDK'ları'nda listelenir.

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

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'larSdkkimliklerden birine ayarlayın.

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

Project/Sdk Özniteliği ve Sdk öğesi, ek SDK'ları etkinleştirir. .NET Aspire SDK'sının (Aspire.AppHost.Sdk) projenin üzerinde Microsoft.NET.Sdkeklendiği aşağıdaki örneği göz önünde bulundurun:

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

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

</Project>

Yukarıdaki proje dosyasında her iki SDK da bağımlılıkları ek bir nitelikte çözümlemek için kullanılır. Daha fazla bilgi için bkz. .NET Aspire SDK .

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 öğedir:

<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.props en altına için Sdk.targets ö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>

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. dotnet msbuild 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=net8.0 -preprocess:output.xml

Varsayılan eklemeler ve dışlamalar

Varsayılan olarak öğeler, ekli kaynaklar ve None 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:

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

Proje dosyanızda bu öğelerden herhangi birini açıkça tanımlarsanız, büyük olasılıkla NETSDK1022 derleme hatası alırsınız. Hatayı düzeltme hakkında bilgi için bkz . NETSDK1022: Yinelenen öğeler dahil edildi.

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

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ğiImplicitUsings yapabilirsiniz.

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

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

Örtük paket başvuruları

Projeniz .NET Standard 1.0-2.0'ı hedeflediğinde, .NET SDK'sı 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 paketler, proje dosyanızın TargetFramework veya TargetFrameworks (çoğul) özelliğinde belirtilen hedef çerçevelere göre örtük olarak başvurulur.

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

<PropertyGroup>
  <TargetFrameworks>netstandard2.0;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 veya .NET Standard 1.0-2.0'ı hedeflerken, proje dosyanızdaki bir öğe aracılığıyla meta paketlere NETStandard.Library açık bir <PackageReference> başvuru eklemeyin. .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 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 BeforeTargetsPreBuild ayarlayınAfterTargets.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>

Derlemeyi özelleştirme

Bir derlemeyi özelleştirmenin çeşitli yolları vardır. Bir özelliği 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.

Ö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, <package_id>.props) Contoso.Utility.UsefulStuff.targets hedefleri veya ö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.

Ayrıca bkz.

• Derlemenizi özelleştirme (MSBuild)
• MSBuild proje SDK'larını kullanma
• NuGet ile özel MSBuild hedeflerini ve desteklerini paketleme