nuget.exe CLI kullanarak paket oluşturma

Paketinizin ne yaptığı veya hangi kodu içerdiği fark etmez, cli araçlarından nuget.exe dotnet.exebirini veya kullanarak bu işlevselliği herhangi bir sayıda diğer geliştiriciyle paylaşılabilen ve kullanılabilecek bir bileşende paketleyebilirsiniz. NuGet CLI araçlarını yüklemek için bkz . NuGet istemci araçlarını yükleme. Visual Studio'da otomatik olarak bir CLI aracı olmadığını unutmayın.

• GENELLIKLE .NET Framework projeleri olan SDK stili olmayan projelerde paket oluşturmak için bu makalede açıklanan adımları izleyin. Visual Studio ve nuget.exe CLI kullanarak adım adım yönergeler için bkz . .NET Framework paketi oluşturma ve yayımlama.

• SDK stili biçimini kullanan .NET Core ve .NET Standard projeleri ve diğer SDK stilindeki projeler için bkz. dotnet CLI kullanarak NuGet paketi oluşturma.

• 'den packages.config PackageReference'a geçirilen projeler için msbuild -t:pack kullanın.

Teknik olarak, NuGet paketi yalnızca uzantıyla yeniden adlandırılan ve içeriği belirli kurallarla .nupkg eşleşen bir ZIP dosyasıdır. Bu konu başlığında, bu kuralları karşılayan bir paket oluşturma işlemi ayrıntılı olarak açıklanmaktadır.

Paketleme, paket olarak teslim etmek istediğiniz derlenmiş kod (derlemeler), simgeler ve/veya diğer dosyalarla başlar (bkz . Genel bakış ve iş akışı). Bu işlem, pakete giden dosyaları derlemeden veya başka bir şekilde oluşturmaktan bağımsızdır, ancak derlenmiş derlemeleri ve paketleri eşitlenmiş durumda tutmak için proje dosyasındaki bilgilerden çizim yapabilirsiniz.

Hangi derlemelerin paketlendiğine karar verme

Genel amaçlı paketlerin çoğu, diğer geliştiricilerin kendi projelerinde kullanabileceği bir veya daha fazla derleme içerir.

• Genel olarak, her derlemenin bağımsız olarak yararlı olması koşuluyla NuGet paketi başına bir derlemeye sahip olmak en iyisidir. Örneğin, öğesine bağımlı Parser.dllolan ve Parser.dll kendi başına yararlı olan bir Utilities.dll paketiniz varsa, her biri için bir paket oluşturun. Bunun yapılması, geliştiricilerin uygulamasından Utilities.dllbağımsız olarak kullanmasına Parser.dll olanak tanır.

• Kitaplığınız bağımsız olarak yararlı olmayan birden çok derlemeden oluşuyorsa, bunları tek bir pakette birleştirmek normaldir. Önceki örneği kullanarak, Parser.dll yalnızca tarafından Utilities.dllkullanılan kodu içeriyorsa, aynı pakette tutmanız Parser.dll sorun olmaz.

• Benzer şekilde, yine ikincisinin kendi başına yararlı olmadığı öğesine bağlıysa Utilities.dll Utilities.resources.dll, her ikisini de aynı pakete koyun.

Kaynaklar aslında özel bir durum. Bir paket projeye yüklendiğinde NuGet, yerelleştirilmiş uydu derlemeleri olduğu varsayıldığından adlandırılmış olanlar hariç olmak üzere paketin DLL'lerine otomatik olarak derleme başvuruları ekler (bkz. Yerelleştirilmiş paketler oluşturma)..resources.dll Bu nedenle, aksi takdirde temel paket kodu içeren dosyalar için kullanmaktan .resources.dll kaçının.

Kitaplığınız COM birlikte çalışma derlemeleri içeriyorsa, COM birlikte çalışma derlemeleri ile paket oluşturma konusunda ek yönergeleri izleyin.

.nuspec dosyasının rolü ve yapısı

Hangi dosyaları paketlemek istediğinizi öğrendikte, sonraki adım XML dosyasında paket bildirimi .nuspec oluşturmaktır.

Bildirim:

1. Paketin içeriğini açıklar ve pakete dahil edilir.
2. Hem paketin oluşturulmasını hem de NuGet'e paketin bir projeye nasıl yükleneceğini belirtir. Örneğin bildirim, ana paket yüklendiğinde NuGet'in de bu bağımlılıkları yükleyebileceği diğer paket bağımlılıklarını tanımlar.
3. Aşağıda açıklandığı gibi hem gerekli hem de isteğe bağlı özellikleri içerir. Burada belirtilmeyen diğer özellikler de dahil olmak üzere tam ayrıntılar için .nuspec başvurusuna bakın.

Gerekli özellikler:

• Paketi barındıran galeride benzersiz olması gereken paket tanımlayıcısı.
• Major.Minor.Patch[-Suffix] biçimindeki belirli bir sürüm numarası; burada -Suffix yayın öncesi sürümleri tanımlar
• Konakta görünmesi gereken paket başlığı (nuget.org gibi)
• Yazar ve sahip bilgileri.
• Paketin uzun açıklaması.

Yaygın isteğe bağlı özellikler:

• Sürüm notları
• Telif hakkı bilgileri
• Visual Studio'da Paket Yöneticisi kullanıcı arabirimi için kısa bir açıklama
• Yerel ayar kimliği
• Proje URL'si
• İfade veya dosya olarak lisans (licenseUrlkullanım dışı bırakıldı, bunun yerine nuspec meta veri öğesini kullanınlicense)
• Simge dosyası (iconUrlkullanım dışı bırakıldı, bunun yerine nuspec meta veri öğesi kullanicon)
• Bağımlılıkların ve başvuruların listesi
• Galeri aramalarına yardımcı olan etiketler

Aşağıda, özellikleri açıklayan açıklamalar içeren tipik (ancak kurgusal) .nuspec bir dosya verilmiştir:

<?xml version="1.0"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
    <metadata>
        <!-- Identifier that must be unique within the hosting gallery -->
        <id>Contoso.Utility.UsefulStuff</id>

        <!-- Package version number that is used when resolving dependencies -->
        <version>1.8.3</version>

        <!-- Authors contain text that appears directly on the gallery -->
        <authors>Dejana Tesic, Rajeev Dey</authors>

        <!-- 
            Owners are typically nuget.org identities that allow gallery
            users to easily find other packages by the same owners.  
        -->
        <owners>dejanatc, rjdey</owners>
        
         <!-- Project URL provides a link for the gallery -->
        <projectUrl>http://github.com/contoso/UsefulStuff</projectUrl>

         <!-- License information is displayed on the gallery -->
        <license type="expression">Apache-2.0</license>
        

        <!-- Icon is used in Visual Studio's package manager UI -->
        <icon>icon.png</icon>

        <!-- 
            If true, this value prompts the user to accept the license when
            installing the package. 
        -->
        <requireLicenseAcceptance>false</requireLicenseAcceptance>

        <!-- Any details about this particular release -->
        <releaseNotes>Bug fixes and performance improvements</releaseNotes>

        <!-- 
            The description can be used in package manager UI. Note that the
            nuget.org gallery uses information you add in the portal. 
        -->
        <description>Core utility functions for web applications</description>

        <!-- Copyright information -->
        <copyright>Copyright ©2016 Contoso Corporation</copyright>

        <!-- Tags appear in the gallery and can be used for tag searches -->
        <tags>web utility http json url parsing</tags>

        <!-- Dependencies are automatically installed when the package is installed -->
        <dependencies>
            <dependency id="Newtonsoft.Json" version="9.0" />
        </dependencies>
    </metadata>

    <!-- A readme.txt to display when the package is installed -->
    <files>
        <file src="readme.txt" target="" />
        <file src="icon.png" target="" />
    </files>
</package>

Bağımlılıkları bildirme ve sürüm numaralarını belirtme hakkında ayrıntılı bilgi için bkz . packages.config ve Package versioning. Ayrıca öğesindeki ve exclude özniteliklerini kullanarak include bağımlılıklardaki varlıkları doğrudan pakette dependency ortaya çıkarabilmek de mümkündür. Bkz . .nuspec Başvurusu - Bağımlılıklar.

Bildirim, ondan oluşturulan pakete eklendiğinden, mevcut paketleri inceleyerek istediğiniz sayıda ek örnek bulabilirsiniz. İyi bir kaynak, bilgisayarınızdaki genel paketler klasörüdür ve konumu aşağıdaki komut tarafından döndürülür:

nuget locals -list global-packages

Herhangi bir package\version klasörüne gidin, dosyayı bir .zip dosyaya kopyalayın.nupkg, sonra bu .zip dosyayı açın ve içindekini .nuspec inceleyin.

.nuspec dosyasını oluşturma

Tam bildirim oluşturma işlemi genellikle aşağıdaki yöntemlerden biri aracılığıyla oluşturulan temel .nuspec bir dosyayla başlar:

• Kural tabanlı çalışma dizini
• Derleme DLL'i
• Visual Studio projesi
• Varsayılan değerlere sahip yeni dosya

Ardından dosyayı el ile düzenleyerek son pakette istediğiniz içeriği tam olarak açıklarsınız.

Kural tabanlı çalışma dizininden

NuGet paketi yalnızca uzantıyla .nupkg yeniden adlandırılan bir ZIP dosyası olduğundan, genellikle yerel dosya sisteminizde istediğiniz klasör yapısını oluşturmak ve ardından dosyayı doğrudan bu yapıdan oluşturmak .nuspec en kolayıdır. Komut nuget pack daha sonra bu klasör yapısındaki tüm dosyaları otomatik olarak ekler (ile .başlayan tüm klasörler hariç), özel dosyaları aynı yapıda tutmanızı sağlar.

Bu yaklaşımın avantajı, bildirimde pakete hangi dosyaları eklemek istediğinizi belirtmenizin gerekmeyecek olmasıdır (bu konunun ilerleyen bölümlerinde açıklandığı gibi). Derleme işleminizin pakete giren tam klasör yapısını oluşturmasını sağlayabilir ve aksi takdirde projenin parçası olmayabilecek diğer dosyaları kolayca ekleyebilirsiniz:

• Hedef projeye eklenmesi gereken içerik ve kaynak kodu.
• PowerShell komut dosyaları
• Projedeki mevcut yapılandırma ve kaynak kodu dosyalarına dönüştürmeler.

Klasör kuralları aşağıdaki gibidir:

Klasör yapınız herhangi bir sayıda hedef çerçeve için herhangi bir sayıda derleme içerebileceğinden, birden çok çerçeveyi destekleyen paketler oluşturulurken bu yöntem gereklidir.

Her durumda, istenen klasör yapısını oluşturduktan sonra, dosyayı oluşturmak .nuspec için bu klasörde aşağıdaki komutu çalıştırın:

nuget spec

Yine oluşturulan .nuspec klasör yapısındaki dosyalara açık başvuru içermiyor. NuGet, paket oluşturulduğunda tüm dosyaları otomatik olarak içerir. Ancak yine de bildirimin diğer bölümlerinde yer tutucu değerlerini düzenlemeniz gerekir.

Derleme DLL'sinden

Bir derlemeden paket oluşturma basit durumunda, aşağıdaki komutu kullanarak derlemedeki meta verilerden bir .nuspec dosya oluşturabilirsiniz:

nuget spec <assembly-name>.dll

Bu formun kullanılması bildirimdeki birkaç yer tutucuyu derlemedeki belirli değerlerle değiştirir. Örneğin, <id> özelliği derleme adına ayarlanır ve <version> derleme sürümüne ayarlanır. Ancak bildirimdeki diğer özellikler, derlemede eşleşen değerlere sahip değildir ve bu nedenle yine de yer tutucular içerir.

Visual Studio projesinden

.nuspec Bir veya .vbproj dosyasından .csproj oluşturmak kullanışlıdır çünkü bu projeye yüklenmiş olan diğer paketlere otomatik olarak bağımlılık olarak başvurulur. Proje dosyasıyla aynı klasörde aşağıdaki komutu kullanmanız yeterlidir:

# Use in a folder containing a project file <project-name>.csproj or <project-name>.vbproj
nuget spec

Sonuçta elde edilen <project-name>.nuspec dosya, önceden yüklenmiş olan diğer paketlere başvurular da dahil olmak üzere paketleme zamanında projedeki değerlerle değiştirilen belirteçleri içerir.

.nuspec dosyasına eklenecek paket bağımlılıklarınız varsa, bunun yerine kullanın nuget packve oluşturulan .nupkg dosyasının içinden .nuspec dosyasını alın. Örneğin, aşağıdaki komutu kullanın.

# Use in a folder containing a project file <project-name>.csproj or <project-name>.vbproj
nuget pack myproject.csproj

Belirteç, proje özelliğinin her iki tarafındaki simgelerle $ sınırlandırılır. Örneğin, <id> bildirimde bu şekilde oluşturulan değer genellikle aşağıdaki gibi görünür:

<id>$id$</id>

Bu belirteç, paketleme zamanında proje dosyasındaki değerle AssemblyName değiştirilir. Proje değerlerinin belirteçlerle tam eşlemesi için .nuspec Değiştirme Belirteçleri başvurusuna bakın.

Belirteçler, projeyi güncelleştirirken içindeki .nuspec sürüm numarası gibi önemli değerleri güncelleştirme gereksiniminden kurtulabilirsiniz. (İsterseniz belirteçleri değişmez değerlerle değiştirebilirsiniz).

Visual Studio projesinde çalışırken daha sonra .nupkg dosyasını oluşturmak için nuget paketini çalıştırma bölümünde açıklandığı gibi birkaç ek paketleme seçeneği olduğunu unutmayın.

Çözüm düzeyinde paketler

Yalnızca NuGet 2.x. NuGet 3.0+ ile kullanılamaz.

NuGet 2.x, Paket Yöneticisi Konsolu için araçlar veya ek komutlar (klasörün içeriğitools) yükleyen ancak çözümdeki herhangi bir proje için başvuru, içerik veya özelleştirme eklemeyen çözüm düzeyinde bir paket fikrine destek oldu. Bu tür paketler doğrudan lib, contentveya build klasörlerinde dosya içermez ve bağımlılıklarının hiçbirinde ilgili lib, contentveya build klasörlerinde dosya yoktur.

NuGet, projenin dosyası yerine packages.config klasördeki bir packages.config dosyada .nuget yüklü çözüm düzeyinde paketleri izler.

Varsayılan değerlere sahip yeni dosya

Aşağıdaki komut, uygun dosya yapısıyla başlamanızı sağlayan yer tutucularla bir varsayılan bildirim oluşturur:

nuget spec [<package-name>]

Paket adını atlarsanız<, sonuçta elde edilen dosya olurPackage.nuspec.> gibi Contoso.Utility.UsefulStuffbir ad sağlarsanız, dosya olur Contoso.Utility.UsefulStuff.nuspec.

Sonuçta .nuspec gibi değerler için yer tutucular projectUrlbulunur. Son .nupkg dosyayı oluşturmak için kullanmadan önce dosyayı düzenlemeyi unutmayın.

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

Paket tanımlayıcısı (<id> öğesi) ve sürüm numarası (<version> öğesi) bildirimdeki en önemli iki değerdir çünkü pakette yer alan kodu tam olarak tanımlarlar.

Paket tanımlayıcısı için en iyi yöntemler:

• Benzersizlik: Tanımlayıcı, nuget.org veya paketi barındıran galeriler arasında benzersiz olmalıdır. Tanımlayıcıya karar vermeden önce, geçerli galeride arama yaparak adın zaten kullanımda olup olmadığını denetleyin. Çakışmaları önlemek için, şirketinizin adını tanımlayıcının ilk parçası olarak kullanmak iyi bir desendir; örneğin Contoso..
• Ad alanı benzeri adlar: Kısa çizgi yerine nokta gösterimi kullanarak .NET'teki ad alanlarına benzer bir desen izleyin. Örneğin, veya Contoso_Utility_UsefulStuffyerine Contoso-Utility-UsefulStuff kullanınContoso.Utility.UsefulStuff. Tüketiciler, paket tanımlayıcısı kodda kullanılan ad alanlarıyla eşleştiğinde de yararlı olur.
• Örnek Paketler: Başka bir paketin nasıl kullanılacağını gösteren bir örnek kod paketi oluşturursanız, içinde olduğu gibi tanımlayıcıya bir sonek olarak Contoso.Utility.UsefulStuff.Sampleekleyin.Sample. (Örnek paketin elbette diğer pakete bağımlılığı olacaktır.) Örnek paket oluştururken, daha önce açıklanan kural tabanlı çalışma dizini yöntemini kullanın. content klasöründe, örnek kodu içinde olarak \Samples\Contoso.Utility.UsefulStuff.Sampleadlandırılan \Samples\<identifier> bir klasörde düzenleyin.

Paket sürümü için en iyi yöntemler:

• Genel olarak, paketin sürümünü kitaplıkla eşleşecek şekilde ayarlayın, ancak bu kesinlikle gerekli değildir. Bu, daha önce Paketlenmesi gereken derlemelere karar verme bölümünde açıklandığı gibi bir paketi tek bir derlemeyle sınırlandırdığınızda basit bir konudur. Genel olarak, NuGet'in derleme sürümleriyle değil bağımlılıkları çözerken paket sürümleriyle uğraştığını unutmayın.
• Standart olmayan bir sürüm şeması kullanırken, 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.

Aşağıdaki kısa blog gönderileri dizisi, sürüm oluşturma işlemini anlamanıza da yardımcı olur:

• Bölüm 1: DLL Cehennemi'ne Alma
• Bölüm 2: Çekirdek algoritması
• Bölüm 3: Bağlama Yeniden Yönlendirmeleri Aracılığıyla Birleştirme

Benioku ve diğer dosyaları ekleme

Pakete eklenecek dosyaları doğrudan belirtmek için dosyada .nuspec etiketini izleyen <metadata> düğümü kullanın:<files>

<?xml version="1.0"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
    <metadata>
    <!-- ... -->
    </metadata>
    <files>
        <!-- Add a readme -->
        <file src="readme.txt" target="" />

        <!-- Add files from an arbitrary folder that's not necessarily in the project -->
        <file src="..\..\SomeRoot\**\*.*" target="" />
    </files>
</package>

Paket köküne adlı readme.txt bir dosya eklediğinizde Visual Studio, paketi doğrudan yükledikten hemen sonra bu dosyanın içeriğini düz metin olarak görüntüler. (Bağımlılık olarak yüklenen paketler için Benioku dosyaları görüntülenmez). Örneğin, HtmlAgilityPack paketi için benioku şu şekilde görünür:

MsBuild props ve hedeflerini bir pakete ekleme

Bazı durumlarda, paketinizi kullanan projelere özel derleme hedefleri veya özellikler eklemek isteyebilirsiniz; örneğin derleme sırasında özel bir araç veya işlem çalıştırma. NuGet paketlerinde MSBuild props ve hedefleri hakkında daha fazla bilgi edinebilirsiniz

Projenin derleme klasörleri içinde veya <package_id>.props (gibiContoso.Utility.UsefulStuff.targets) oluşturun<package_id>.targets.

Ardından dosyada .nuspec , düğümdeki şu dosyalara başvurduysanız <files> emin olun:

<?xml version="1.0"?>
<package >
    <metadata minClientVersion="2.5">
    <!-- ... -->
    </metadata>
    <files>
        <!-- Include everything in \build -->
        <file src="build\**" target="build" />

        <!-- Other files -->
        <!-- ... -->
    </files>
</package>

Paketler projeye eklendiğinde NuGet otomatik olarak bu prop'ları ve hedefleri içerir.

.nupkg dosyasını oluşturmak için nuget paketini çalıştırın

Bir derlemeyi veya kural tabanlı çalışma dizinini kullanırken, öğesini kendi dosya adınızla değiştirerek <project-name> dosyanızla .nuspec çalıştırarak nuget pack bir paket oluşturun:

nuget pack <project-name>.nuspec

Visual Studio projesi kullanırken proje dosyanızla komutunu çalıştırın nuget pack ; bu dosya proje dosyasını otomatik olarak yükler ve proje .nuspec dosyasındaki değerleri kullanarak içindeki belirteçleri değiştirir:

nuget pack <project-name>.csproj

Her durumda, nuget pack veya .hggibi .git bir nokta ile başlayan klasörleri hariç tutar.

NuGet, dosyada düzeltme gerektiren, bildirimdeki .nuspec yer tutucu değerlerini değiştirmeyi unutma gibi hatalar olup olmadığını belirtir.

Başarılı olduktan sonranuget pack, Paket Yayımlama bölümünde açıklandığı gibi uygun bir galeride yayımlayabileceğiniz bir dosyanız olur.nupkg.

Ek seçenekler

Dosyaları dışlamak, bildirimdeki sürüm numarasını geçersiz kılmak ve diğer özelliklerin yanı sıra çıkış klasörünü değiştirmek için ile nuget pack çeşitli komut satırı anahtarları kullanabilirsiniz. Tam liste için paket komutu başvurusuna bakın.

Visual Studio projeleriyle ortak olan birkaç seçenek şunlardır:

• Başvuruda bulunan projeler: Proje diğer projelere başvuruda bulunuyorsa, şu seçeneği kullanarak -IncludeReferencedProjects başvuruda bulunan projeleri paketin bir parçası olarak veya bağımlılıklar olarak ekleyebilirsiniz:

  nuget pack MyProject.csproj -IncludeReferencedProjects
  

  Bu ekleme işlemi özyinelemeli olduğundan, B ve C projelerine başvuruda bulunursa ve bu projeler D, E ve F'ye başvurursa MyProject.csproj , B, C, D, E ve F'deki dosyalar pakete eklenir.

  Başvuruda bulunılan bir proje kendine ait bir .nuspec dosya içeriyorsa, NuGet bu başvuruda bulunılan projeyi bağımlılık olarak ekler. Bu projeyi ayrı ayrı paketlemeniz ve yayımlamanız gerekir.

• Derleme yapılandırması: NuGet varsayılan olarak proje dosyasındaki varsayılan derleme yapılandırma kümesini kullanır ve genellikle Hata Ayıkla'yı kullanır. Dosyaları Release gibi farklı bir derleme yapılandırmasından paketlemek için şu yapılandırmayı kullanın-properties:

  nuget pack MyProject.csproj -properties Configuration=Release
  

• Simgeler: Tüketicilerin hata ayıklayıcıda paket kodunuzda adım adım ilerleyebilmesini sağlayan simgeler eklemek için şu -Symbols seçeneği kullanın:

  nuget pack MyProject.csproj -symbols
  

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.

Otomatik test için temel süreç aşağıdaki gibidir:

1. .nupkg Dosyayı yerel bir klasöre kopyalayın.
2. komutunu kullanarak nuget sources add -name <name> -source <path> klasörü paket kaynaklarınıza ekleyin (bkz . nuget kaynakları). Bu yerel kaynağı belirli bir bilgisayarda yalnızca bir kez ayarlamanız gerektiğini unutmayın.
3. bu kaynaktan nuget install <packageID> -source <name> paketi yükleyin; burada <name> kaynağınızın adı ile belirtilen nuget sourcesşekilde eşleşir. Kaynağın belirtilmesi, paketin yalnızca bu kaynaktan yüklenmesini sağlar.
4. Dosyaların doğru yüklenip yüklenmediğini denetlemek için dosya sisteminizi inceleyin.

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:

• Paket sürümü oluşturma
• Birden çok hedef çerçeveyi destekleme
• Kaynak ve yapılandırma dosyalarının dönüşümleri
• Yerelleştirme
• Yayın öncesi sürümler
• Paket türünü ayarlama
• COM birlikte çalışma derlemeleri ile paketler oluşturma

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

• Yerel Paketler
• Sembol Paketleri