MSBuild kullanarak NuGet paketi oluşturma

  • Makale

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 msbuild ile dotnet CLI aracılığıyla MSBuild 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 stilindeki PackageReference projeleri için proje bağımlılıklarına NuGet.Build.Tasks.Pack paketini eklemeniz gerekir. MSBuild paketi hedefleri hakkında ayrıntılı bilgi için bkz . NuGet paketi ve MSBuild hedefleri olarak geri yükleme.

bir paket oluşturan komut, msbuild -t:packiş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 -Suffix yayı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ögesini seçin. 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'da 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>

MSBuild paketi hedefleri, Bağımlılık varlıklarını denetleme ve PackageTagsNuGet meta veri özelliklerinde açıklandığı gibi , ve gibi TitlePackageDescriptionisteğe bağlı özellikleri de ayarlayabilirsiniz.

Not

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. Ve <ExcludeAssets> özniteliklerini kullanarak <IncludeAssets> bağımlılıklardan varlıkları doğrudan pakette ortaya çıkarabilmek de 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 dosyasından veya $description .nuspec dosyasındaki dosyasından çeker<Description>.

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

<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 konumlar arasında 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, veya Contoso_Utility_UsefulStuffyerine Contoso-Utility-UsefulStuff kullanınContoso.Utility.UsefulStuff. 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 Contoso.Utility.UsefulStuff.Sampletanımlayıcıya ekleyin.Sample.

    Örnek paketin özgün pakete bağımlılığı vardır. Örnek paketi oluşturduğunuzda değeriyle ekleyin <IncludeAssets>contentFiles . İç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.

Not

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:

NuGet.Build.Tasks.Pack paketini ekleme

MSBuild'i SDK stili olmayan bir proje ve PackageReference ile kullanıyorsanız, projenize NuGet.Build.Tasks.Pack paketini ekleyin.

  1. Proje dosyasını açın ve öğesinin arkasına <PropertyGroup> aşağıdakileri ekleyin:

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

    Not

    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ılacağı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 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ış, dosyanın yolunu .nupkg 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

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

Bir çözümde çalıştırdığınızda msbuild -t:pack , bu paketlenebilir çözümdeki tüm projeleri paketler (<IsPackable> özellik olarak trueayarlanır).

Not

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: