Aracılığıyla paylaş

MSBuild kullanarak NuGet paketi oluşturma

Kodunuzdan bir NuGet paketi oluşturduğunuzda, bu işlevi herhangi bir sayıda diğer geliştiriciyle paylaşılabilen ve bu geliştiriciler tarafından kullanılabilen bir bileşende paketlersiniz. Bu makalede, MSBuild kullanarak bir paketin nasıl oluşturulacağı açıklanır. MSBuild, NuGet içeren tüm Visual Studio iş yüklerine önceden yüklenmiş olarak gelir. Ayrıca, dotnet CLI'de dotnet msbuild komutunu kullanarak MSBuild'i de kullanabilirsiniz.

SDK stili biçimini kullanan .NET Core ve .NET Standard projeleri ve diğer SDK stilindeki projeler için NuGet, paket oluşturmak için doğrudan proje dosyasındaki bilgileri kullanır. kullanan <PackageReference>SDK stili olmayan bir proje için NuGet, paket oluşturmak için proje dosyasını da kullanır.

SDK stilindeki projeler, varsayılan olarak kullanılabilir paket işlevselliğine sahiptir. SDK stili olmayan PackageReference projeleri için, Visual Studio 2026'dan başlayarak varsayılan olarak kullanılabilir. Visual Studio'nun önceki sürümlerinde proje bağımlılıklarına NuGet.Build.Tasks.Pack paketini eklemeniz gerekir ve Visual Studio 2026'ya yükseltirken bu paket başvurusunun kaldırılmasını öneririz. MSBuild paketi hedefleri hakkında ayrıntılı bilgi için bkz. NuGet paketi ve MSBuild hedefleri olarak geri yükleme.

SDK stili projeler için, msbuild -t:pack işlevsel olarak ile dotnet packeşdeğerdir.

Önemli

Bu konu genellikle .NET Core ve .NET Standard projeleri olmak üzere SDK stili projeler ve PackageReference kullanan SDK stili olmayan projeler için geçerlidir.

Özellikleri ayarlama

Paket oluşturmak için aşağıdaki özellikler gereklidir.

  • PackageId, paketi barındıran galeride benzersiz olması gereken paket tanımlayıcısı. Belirtilmezse, varsayılan değer olur AssemblyName.
  • Version, Major.Minor.Patch[-Suffix] biçimindeki belirli bir sürüm numarasıdır; burada -Suffixyayın öncesi sürümleri tanımlar. Belirtilmezse, varsayılan değer 1.0.0'dır.
  • Konakta görünmesi gereken paket başlığı (nuget.org gibi)
  • Authors, yazar ve sahip bilgileri. Belirtilmezse, varsayılan değer olur AssemblyName.
  • Company, şirket adınız. Belirtilmezse, varsayılan değer olur AssemblyName.

Ayrıca PackageReference kullanan SDK stili olmayan projeleri de paketliyorsanız, aşağıdakiler gereklidir:

  • PackageOutputPath, paket çağrılırken oluşturulan paketin çıkış klasörü.

Visual Studio'da bu değerleri proje özelliklerinde ayarlayabilirsiniz (Çözüm Gezgini'nde projeye sağ tıklayın, Özellikler'i seçin ve Paket sekmesini seçin). Bu özellikleri doğrudan proje dosyalarında (.csproj) da ayarlayabilirsiniz.

<PropertyGroup>
  <PackageId>ClassLibDotNetStandard</PackageId>
  <Version>1.0.0</Version>
  <Authors>your_name</Authors>
  <Company>your_company</Company>
</PropertyGroup>

Önemli

Pakete nuget.org veya kullandığınız paket kaynağında benzersiz bir tanımlayıcı verin.

Aşağıdaki örnekte, bu özelliklere sahip basit ve eksiksiz bir proje dosyası gösterilmektedir.

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
    <PackageId>ClassLibDotNetStandard</PackageId>
    <Version>1.0.0</Version>
    <Authors>your_name</Authors>
    <Company>your_company</Company>
  </PropertyGroup>
</Project>

Title, PackageDescription ve PackageTagsNuGet meta veri özelliklerinde açıklandığı gibi , ve gibi isteğe bağlı özellikleri de ayarlayabilirsiniz.

Uyarı

Genel tüketim için oluşturulan paketler için, etiketler başkalarının paketinizi bulmasına ve ne yaptığını anlamasına yardımcı olduğundan PackageTags özelliğine özellikle dikkat edin.

Bağımlılıkları bildirme ve sürüm numaralarını belirtme hakkında ayrıntılı bilgi için bkz. Proje dosyalarında paket başvuruları ve Paket sürümü oluşturma. <IncludeAssets> ve <ExcludeAssets> özniteliklerini kullanarak bağımlılıklardaki varlıkları doğrudan paketin içinde ortaya çıkarmak da mümkündür. Daha fazla bilgi için bkz. Bağımlılık varlıklarını denetleme.

İsteğe bağlı açıklama alanı ekleme

Paketin isteğe bağlı açıklaması, paketin nuget.org sayfasının BENİOKU sekmesinde görünür. Açıklama, proje dosyasındaki <Description> veya $description dosyasındaki öğelerinden çekilir.

Aşağıdaki örnekte, bir .NET paketi için Description dosyasında bir örnek gösterilmektedir:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <PackageId>Azure.Storage.Blobs</PackageId>
    <Version>12.4.0</Version>
    <PackageTags>Microsoft Azure Storage Blobs;Microsoft;Azure;Blobs;Blob;Storage;StorageScalable</PackageTags>
    <Description>
      This client library enables working with the Microsoft Azure Storage Blob service for storing binary and text data.
      For this release see notes - https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/storage/Azure.Storage.Blobs/README.md and https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/storage/Azure.Storage.Blobs/CHANGELOG.md
      in addition to the breaking changes https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/storage/Azure.Storage.Blobs/BreakingChanges.txt
      Microsoft Azure Storage quickstarts and tutorials - https://learn.microsoft.com/azure/storage/
      Microsoft Azure Storage REST API Reference - https://learn.microsoft.com/rest/api/storageservices/
      REST API Reference for Blob Service - https://learn.microsoft.com/rest/api/storageservices/blob-service-rest-api
    </Description>
  </PropertyGroup>
</Project>

Benzersiz bir paket tanımlayıcısı seçin ve sürüm numarasını ayarlayın

Paket tanımlayıcısı ve sürüm numarası, pakette yer alan tam kodu benzersiz olarak tanımlar.

Paket tanımlayıcısını oluşturmak için şu en iyi yöntemleri izleyin:

  • Tanımlayıcı, nuget.org ve paketi barındıran diğer tüm konumlarda benzersiz olmalıdır. Çakışmaları önlemek için iyi bir desen, tanımlayıcının ilk parçası olarak şirketinizin adını kullanmaktır.

  • Nokta gösterimini kullanarak .NET ad alanı benzeri bir adlandırma kuralını izleyin. Örneğin Contoso.Utility.UsefulStuff veya Contoso-Utility-UsefulStuff yerine Contoso_Utility_UsefulStuff kullanın. Paket tanımlayıcısını kodun kullandığı ad alanıyla eşleştirdiğinizde tüketiciler için de yararlı olur.

  • Başka bir paketin nasıl kullanılacağını gösteren bir örnek kod paketi oluşturursanız, içinde olduğu gibi .Sampletanımlayıcıya ekleyinContoso.Utility.UsefulStuff.Sample.

    Örnek paketin özgün pakete bağımlılığı vardır. Örnek paketi oluşturduğunuzda, <IncludeAssets> değerini contentFiles ile ekleyin. İçerik klasöründe, örnek kodu \Samples\identifier< adlı \Samples\>Contoso.Utility.UsefulStuff.Sample gibi bir klasörde düzenleyin.

Paket sürümünü ayarlamak için şu en iyi yöntemleri izleyin:

  • Genel olarak, paket sürümünü proje veya derleme sürümüyle eşleşecek şekilde ayarlayın, ancak bu kesinlikle gerekli değildir. Bir paketi tek bir derlemeyle sınırladığınızda sürümü eşleştirmek basittir. NuGet, derleme sürümleriyle değil bağımlılıkları çözerken paket sürümleriyle ilgilenir.

  • Standart olmayan bir sürüm düzeni kullanıyorsanız, Paket sürümü oluşturma bölümünde açıklandığı gibi NuGet sürüm oluşturma kurallarını dikkate aldığınızdan emin olun. NuGet çoğunlukla Semantik Sürüm Oluşturma 2.0.0 ile uyumludur.

Uyarı

Bağımlılık çözümlemesi hakkında daha fazla bilgi için bkz. PackageReference ile bağımlılık çözümleme. Sürüm oluşturma işlemini anlamanıza yardımcı olabilecek bilgiler için şu blog gönderileri dizisine bakın:

Paket için projeyi yapılandır

SDK stilindeki projeler için ek yapılandırma gerekmez.

SDK stili olmayan projelerin en az bir paketin yüklü olması gerekir (packages.configdeğil PackageReference aracılığıyla) veya projenin açıkça NuGet'e projeyi özelliği aracılığıyla PackageReference projesi olarak işlemesi için talimat vermeleri RestoreProjectStyle gerekir.

Visual Studio 2022 ve önceki sürümlerde yerleşik paket olmadığından NuGet.Build.Tasks.Pack paketini de yüklemeniz gerekir. Visual Studio 2026 veya sonraki bir sürüme yükseltirken, yeni özelliklerden ve hata düzeltmelerinden yararlanabilmeniz için paketi kaldırmanızı öneririz.

  1. Proje dosyasını düzenleyin.

    NuGet'e projeyi, içinde yüklü paket bulunmayan bir PackageReference olarak değerlendirmesi gerektiğini açıkça belirtmek istiyorsanız, <PropertyGroup> deyimi bulunmayan bir Condition öğesi bulun veya ekleyin ve şunları ekleyin:

    <PropertyGroup>
  <!-- other properties -->
  <RestoreProjectStyle>PackageReference</RestoreProjectStyle>
  <!-- more properties are allowed -->
</PropertyGroup>

    Visual Studio 2022 veya önceki bir sürümünü kullanıyorsanız, öğesinin <PropertyGroup> arkasına aşağıdakileri ekleyin:

    <ItemGroup>
  <!-- ... -->
  <PackageReference Include="NuGet.Build.Tasks.Pack" Version="6.14.0" PrivateAssets="all" />
  <!-- ... -->
</ItemGroup>

    Uyarı

    Bu paketin kullanılabilir en son sürümünü kullanmayı göz önünde bulundurun.

  2. Bir Geliştirici komut istemi açın ( Arama kutusuna Geliştirici komut istemi yazın).

    MsBuild için gerekli tüm yollarla yapılandırılmış olacağından, Visual Studio için Geliştirici Komut İstemi'ni genellikle Başlat Menüsünden başlatmak istersiniz.

  3. Proje dosyasını içeren klasöre geçin ve NuGet.Build.Tasks.Pack paketini geri yüklemek için aşağıdaki komutu yazın.

    # Uses the project file in the current folder by default
msbuild -t:restore

    MSBuild çıkışının derlemenin başarıyla tamamlandığını gösterdiğinden emin olun.

msbuild -t:pack komutunu çalıştırın

Projeden bir NuGet paketi ( .nupkg dosya) oluşturmak için, projeyi otomatik olarak da oluşturan komutunu çalıştırın msbuild -t:pack :

Visual Studio için Geliştirici komut istemine aşağıdaki komutu yazın:

# Uses the project file in the current folder by default
msbuild -t:pack

Çıkış, .nupkg dosyasının yolunu gösterir.

Microsoft (R) Build Engine version 16.1.76+g14b0a930a7 for .NET Framework
Copyright (C) Microsoft Corporation. All rights reserved.

Build started 8/5/2019 3:09:15 PM.
Project "C:\Users\username\source\repos\ClassLib_DotNetStandard\ClassLib_DotNetStandard.csproj" on node 1 (pack target(s)).
GenerateTargetFrameworkMonikerAttribute:
Skipping target "GenerateTargetFrameworkMonikerAttribute" because all output files are up-to-date with respect to the input files.
CoreCompile:
  ...
CopyFilesToOutputDirectory:
  Copying file from "C:\Users\username\source\repos\ClassLib_DotNetStandard\obj\Debug\netstandard2.0\ClassLib_DotNetStandard.dll" to "C:\Use
  rs\username\source\repos\ClassLib_DotNetStandard\bin\Debug\netstandard2.0\ClassLib_DotNetStandard.dll".
  ClassLib_DotNetStandard -> C:\Users\username\source\repos\ClassLib_DotNetStandard\bin\Debug\netstandard2.0\ClassLib_DotNetStandard.dll
  Copying file from "C:\Users\username\source\repos\ClassLib_DotNetStandard\obj\Debug\netstandard2.0\ClassLib_DotNetStandard.pdb" to "C:\Use
  rs\username\source\repos\ClassLib_DotNetStandard\bin\Debug\netstandard2.0\ClassLib_DotNetStandard.pdb".
GenerateNuspec:
  Successfully created package 'C:\Users\username\source\repos\ClassLib_DotNetStandard\bin\Debug\AppLogger.1.0.0.nupkg'.
Done Building Project "C:\Users\username\source\repos\ClassLib_DotNetStandard\ClassLib_DotNetStandard.csproj" (pack target(s)).

Build succeeded.
    0 Warning(s)
    0 Error(s)

Time Elapsed 00:00:01.21

Derleme sırasında paketi otomatik olarak oluşturma

Projeyi oluştururken veya geri yüklerken otomatik olarak çalıştırmak msbuild -t:pack için içindeki proje dosyanıza <PropertyGroup>aşağıdaki satırı ekleyin:

<GeneratePackageOnBuild>true</GeneratePackageOnBuild>

msbuild -t:pack'ü bir çözümde çalıştırdığınızda, bu, özellik olarak <IsPackable>true ayarlanmış paketlenebilir çözümdeki tüm projeleri paketler.

Uyarı

Paketi otomatik olarak oluşturduğunuzda, paket oluşturma süresi projenizin derleme süresini artırır.

Paket yüklemesini test et

Bir paketi yayımlamadan önce, genellikle bir paketi projeye yükleme işlemini test etmek istersiniz. Testler, mutlaka dosyaların projedeki doğru yerlerine vardığından emin olur.

Normal paket yükleme adımlarını kullanarak Visual Studio'da veya komut satırında yüklemeleri el ile test edebilirsiniz.

Önemli

Paketler sabittir. Bir sorunu düzeltirseniz paketin içeriğini değiştirin ve paketi yeniden paketleyin; yeniden test ettiğinizde, genel paketler klasörünüzü temizleyene kadar paketin eski sürümünü kullanmaya devam edersiniz. Bu özellikle her derlemede benzersiz bir yayın öncesi etiketi kullanmayan paketleri test ederken geçerlidir.

Sonraki Adımlar

Dosya olan .nupkg bir paket oluşturduktan sonra, paketi Paket Yayımlama bölümünde açıklandığı gibi istediğiniz galeride yayımlayabilirsiniz.

Ayrıca paketinizin özelliklerini genişletmek veya aşağıdaki konularda açıklandığı gibi başka senaryoları desteklemek isteyebilirsiniz:

Son olarak, dikkat etmeniz gereken ek paket türleri vardır:

  • Last updated on