.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:
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.Razor |
.NET Razor SDK'sı | https://github.com/dotnet/aspnetcore |
Microsoft.NET.Sdk.BlazorWebAssembly |
.NET Blazor WebAssembly SDK'sı | https://github.com/dotnet/aspnetcore |
Microsoft.NET.Sdk.Worker |
.NET Çalışan Hizmeti SDK'sı | https://github.com/dotnet/aspnetcore |
Aspire.AppHost.Sdk |
.NET Aspire SDK'sı | https://github.com/dotnet/aspire |
MSTest.Sdk |
MSTest SDK'sı | https://github.com/microsoft/testfx |
.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'larSdk
kimliklerden 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.Sdk
eklendiğ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>
İ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.
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:
Öğ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 | **/*.bilgisayar bilimi; **/*.resx |
Not
./bin
ve MSBuild özellikleriyle ./obj
temsil edilen ve $(BaseOutputPath)
$(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 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.
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ğ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>
Not
.NET 8 SDK'sı ile başlayarak , System.Net.Http.NET Framework hedeflenirken artık dahilMicrosoft.NET.Sdk
değildir.
Ö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 BeforeTargets
PreBuild
ayarlayınAfterTargets
.PostBuild
<Target Name="PreBuild" BeforeTargets="PreBuildEvent">
<Exec Command=""$(ProjectDir)PreBuildEvent.bat" "$(ProjectDir)..\" "$(ProjectDir)" "$(TargetDir)"" />
</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
PreBuild
PostBuild
, bu adları kullanarak IDE'deki komutları düzenleyebilirsiniz. - gibi makrolar çözümlenmediğinden ve özellikleri
PreBuildEvent
PostBuildEvent
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 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, <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.