Yeni Nuget paketi oluşturma, .NET Geliştiricilerinin sıklıkla kullandığı nuget paket yöneticisinden herkes en az bir paket indirip kullanmıştır diye düşünüyorum kimimiz belkide paketler olmadan geliştirme yapamayacak kadar alışkanlık dahi edinmiş olabiliriz 🙂 neyse asıl konumuz biz nuget paketi oluşturmak ve yayınlamak istersek bunu nasıl yapabileceğimizi ve neler yapmamız gerektiğini göreceğiz bu makalede.
Yeni NuGet Paketi Nasıl Oluşturulur?
Nuget paket oluşturma adımlarına geçmeden önce ortamımızı hazır hale getirelim ilk yapmamız gereken nuget işlemleri için nuget.exe‘ye sahip olmamız gerekiyor bunun için nuget.org adresinden nuget.exe dosyasını indirebilirsiniz.
Nuget.exe dosyasını indirdikten sonra bunu paketini oluşturacağımız .net projesinin olduğu yere atıyoruz yani .csproj uzantılı dosya ile aynı konuma atıyoruz(Böylesinin daha pratik olduğunu düşünüyorum farklı bir yolda yer alan nuget.exe’nizide kullanabilirsiniz).
.nuspec Dosyası Oluşturma
.nuspec uzantılı tanım dosyası sayesinde nuget paketi oluşturabileceğiz.
Yeni bir .nuspec tanım dosyası oluşturmak için alttaki spec komutu projenin olduğu yerde çalıştırın.
.nuspec uzantılı dosyayı notepad yada herhangi bir kod editöründen(vscode, brackets, notepad++ v.b.) açabilirsiniz.
Proje İçin .nuspec Dosyası Oluşturma
Eğer nuget’a yayınlayacağınız bir dll ise yada diğer bir deyişle bir projeyi nuget paketi olarak çıktı alacaksınız. Alttaki parafraftan okumaya devam edip .nuspec dosya içeriğine bakabilirsiniz ama eğer bir javascript dosyası, css dosyası yada diğer türdeki dosyalar için bir nuget paketi oluşturmak isterseniz bir sonraki “Dosya(lar) için .nuspec dosyası oluşturma” başlığına bakabilirsiniz.
.nuspec uzantılı dosya içerisinde yer alan $id$, $version$, $title$, $author$ değerleri Projenizin Properties > Application tabında yer alan Assembly Imformation adındaki button’a tıkladığınızda karşınıza çıkan ekrandaki değerler ile değiştirilmektedir ayrıca bu ekrandaki değerlere AssemplyImformation.cs dosyası içerindende ulaşabilirsiniz. Şimdide .nuspec uzantılı varsayılan olarak oluşturulan dosya içeriğine bakalım.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 | <?xml version="1.0"?> <package xmlns="http://schemas.microsoft.com/packaging/2011/08/nuspec.xsd"> <metadata> <id>$id$</id> <version>$version$</version> <title>$title$</title> <authors>$author$</authors> <owners>$author$</owners> <licenseUrl>http://LICENSE_URL_HERE_OR_DELETE_THIS_LINE</licenseUrl> <projectUrl>http://PROJECT_URL_HERE_OR_DELETE_THIS_LINE</projectUrl> <iconUrl>http://ICON_URL_HERE_OR_DELETE_THIS_LINE</iconUrl> <requireLicenseAcceptance>false</requireLicenseAcceptance> <description>$description$</description> <releaseNotes>Summary of changes made in this release of the package.</releaseNotes> <copyright>Copyright 2017</copyright> <tags>Tag1 Tag2</tags> </metadata> </package> |
Bundan sonraki anlatımlarımıza Foo.csproj adlı projemizin olduğunu varsayıp bu dosya üzerinden örneklerle gideceğiz.
Dosya(lar) İçin .nuspec Dosyası Oluşturma
Üstteki nuspec dosyasından farklı olarak files adında bir tag açılacak ve bu tag’in 2 farklı attribute’ü kullanılarak gerekli dosya tanımlamalarınız ile dosyalardan oluşan nuget paketini oluşturabilirsiniz.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 | <?xml version="1.0"?> <package xmlns="http://schemas.microsoft.com/packaging/2011/08/nuspec.xsd"> <metadata> <id>$id$</id> <version>$version$</version> <title>$title$</title> <authors>$author$</authors> <owners>$author$</owners> <licenseUrl>http://LICENSE_URL_HERE_OR_DELETE_THIS_LINE</licenseUrl> <projectUrl>http://PROJECT_URL_HERE_OR_DELETE_THIS_LINE</projectUrl> <iconUrl>http://ICON_URL_HERE_OR_DELETE_THIS_LINE</iconUrl> <requireLicenseAcceptance>false</requireLicenseAcceptance> <description>$description$</description> <releaseNotes>Summary of changes made in this release of the package.</releaseNotes> <copyright>Copyright 2017</copyright> <tags>Tag1 Tag2</tags> </metadata> <files> <file src="file.d.ts" target="scripts\typings\FolderName\file.d.ts" /> </files> </package> |
Üstteki kodda işaretli olan files etiketi içerisinde tanımlı olan file etiketinde yer alan 2 attribute şu anlama geliyor src attribute’ü ile nuget paketine dahil edilecek dosyaları temsil ediyor target attribute’ü ise nuget’den paket yüklendiğinde projenin hangi kısmına yükleneceği belirleniyor. Genellikle Typescript DefinitelyTypes‘lar scripts\typings\FolderName\file.d.ts şeklinde kaydedildiği için bu şekilde bir target tanımı görüyorsunuz ama sizin dahil ettiğiniz dosya css ise target değeri değişecektir veya javascript kütüphanesi ise yine target değeri değişecektir buna dikkat edilmesi gerekiyor hangi dosya türleri .net projelerinde hangi klasör altında yer alıyorsa bu şekilde standart bir yol izleyerek paketinizi yükleyecek olan kullanıcının standart dosya hiyerarşisini karıştırmamış olursunuz.
Dependency Yönetimi
Eğer nuget paketi oluşturmak için kullanacağınız yapınızın farklı yapılara bağımlılığı varsa o zaman .nuspec uzantılı dosya içerisinde bu bağımlılıkları belirtmelisinizki kullanıcı sizin nuget paketinizi yüklemeye çalıştığında eğer bağımlılığınız olan paket kullanıcıda yoksa öncelikle onun yüklenmesi ardından sizin paketinizin yüklenmesi sağlanır.
Bağımlılıkları yönetmek için yapmanız gereken .nuspec dsoayası içerisinde metada etiketleri arasına dependencies etiketini eklemelisiniz örnek dependency tanımı için alttaki koda gözatabilirsiniz.
1 2 3 4 | <dependencies> <dependency id="PackageA" version="1.1.0" /> <dependency id="PackageB" version="[1,2)" /> </dependencies> |
Üstteki dependency etiketlerinde yer alan id attribute’üne verilecek değer sizin nuget paketi kurarken kullanmış olduğunuz id ile aynıdır. Örnek nuget install Sendloop dediğinizde burada paketin id’si Sendloop‘dur. Version özelliğinde kullanabileceğiniz birçok pattern bulunmaktadır bu pattern’lere alttaki tablodan açıklamaları ile ulaşabilirsiniz.
| Tanım | Uygulanma Kuralı | Açıklama |
|---|---|---|
| 1.0 | 1.0 ≤ x | Minimum versiyon, dahil |
| (1.0,) | 1.0 < x | Minimum versiyon, dahil değil |
| [1.0] | x == 1.0 | Tam sürüm eşleştirmesi |
| (,1.0] | x ≤ 1.0 | Maksimum versiyon, dahil |
| (,1.0) | x < 1.0 | Maksimum versiyon, dahil değil |
| 1.0,2.0] | 1.0 ≤ x ≤ 2.0 | Belli aralıktaki versiyonlar, dahil |
| 1.0,2.0) | 1.0 < x < 2.0 | Belli aralıktaki versiyonlar, dahil değil |
| [1.0,2.0) | 1.0 ≤ x < 2.0 | Minimum ile maksimum arasındaki versiyonlar bir üstteki tanımdan tek farkı minimum sürüm dahil edilmiş ama maksimum sürüm dahil değil. |
| (1.0) | Geçersiz | Geçersiz bir tanımdır. |
Nuget Paketi Oluşturma
Proje için nuget Paketi oluşturma
Normalde nuget paketini direk olarak .csproj uzantılı dosya üzerinden oluşturmaya çalıştığımızda Debug configuration’u üzerinden paket oluşturulacaktır ama biz Release configuration’u üzerinden oluşturmak istersek o zaman alttaki şekilde bir kod kullanabiliriz.
Üstteki komut başarılı bir şekilde çalıştıktan sonra Foo.1.0.0.0.nupkg adında bir dosya üretilecektir.
Dosya(lar) için nuget paketi oluşturma
.nuspec nuget paket tanım dosyasının olduğu yolda alttaki komutunuzu çalıştırırsanız yine proje paketi oluşturma kısmına olduğu gibi .nupkg uzantılı upload’a hazır bir nuget paket dosyası almış olacaksınız.
Paketi Yayınlama
Paketi yayınlamak isterseniz https://www.nuget.org/packages/manage/upload adresini yada nuget.exe dosyasını CLI(Command Line Interface)‘de kullanabilirsiniz.
Eğer https://www.nuget.org/packages/manage/upload adresinden paketi yayınlamak isterseniz. Ücretsiz nuget.org hesabı oluşturun yada hesabınız varsa nuget hesabınız ile giriş yapın ve menüde Upload Package linkine tıklayıp upload sayfasından .nupkg uzantılı paketinizi upload edip yayınlayabilirsiniz.
Eğer paketi yayınlama işini CLI ile halletmek isterseniz Api Key‘e sahip olmalısınız nuget.org Api Key‘ini almak için nuget.org adresinden giriş yaptıktan sonra sağ üstteki kullanıcı adına tıklayıp API Keys altına yer alan New Api Key butonuna tıklayın ve ardından sırasıyla gerekli alanları girin alanlar ile ilgili bilgilere alttaki tablodan ulaşabilirsiniz.
| Alan Adı | Açıklama |
| Key Name | Oluşturacağız key için bir isim verin. |
| Expires In | Oluşturacağız key’in geçerlilik süresini girin. |
| Select Scopes | Oluşturacağınız key’in yapacağız işlem alanlarını belirleyebiliyorsunuz. Push radio butonunu seçerseniz yayınlama işlemi yapabilirsiniz Push radio butonunu seçtiğinize 2 seçenek çıkıyor Push new packages and package versions bu seçeneği seçerseniz yeni paket ve pakete ait sonraki versiyonları yayınlayablirsiniz. Eğer Push only new package versions seçeneğini seçerseniz o zaman sadece varolan pakete ait yeni versiyonları yayınlama işlemlerini yapabilirsiniz. |
| Select Packages | Glob Pattern: * karakteri ile tüm paketler üzerinden bu api key ile işlem yapabilirsiniz. Alpha.* şeklinde bir pattern kullanırsanız buda Alpha. ile başlayan paketleriniz üzerinde ilgili api key üzerinden işlem yapılabileceğini belirtiyorsunuz. Avaible Packages: Bu kısımdan manuel olarak hangi paketleriniz için ilgili api key ile işlem yapılabileceğini seçebilirsiniz. |
Key Oluşturma Demosu
Tablodaki alanları kendinize göre seçtikten ve girişleri yaptıktan sonra oluşturduğunuz key’i alıp alttaki gibi push kodunu ve diğer api-key gerektiren kodu kullabilirsiniz.
Yeni Versiyon Çıkarıp Yayınlama
Makalede buraya kadarki kısımda yeni oluşturulmuş bir paketin nasıl yayınlanabileceğini gösterdik fakat yayınladığımız bir paket için yeni bir sürüm yayınlamak istediğimizde ne yapacağız?
Bunun için yapılması gereken iki önemli şey var ilk yayınladığınız paketin sürümünün 1.0.0 olduğunu varsayalım ve paket üzerinde değişiklik yaptığınızı varsayıp paketi tekrar yayınlamak istediniz bu durumda yayınlama işleminde aynı sürümle yayınlanamayacağı ile ilgili bir hata alacaksınız bunun için yapmanız gereken ilk yayınlamadan sonraki her yayınlama işlemi öncesinde versiyon arttırma işlemini gerçekleştirmelisiniz.
Versiyon arttırma işlemini isterseniz .nuspec dosyası üzerinden $id$ kısmına manuel olarak girip gerçekleştirebilirsiniz istersenizde makalenin önceki kısımlarında Assembly Informartion diye bir kısımdan bahsetmiştim bu kısımdan yönetebilirsiniz.
Versiyonlama Yapısı
Versiyonlama için kabul görmüş standartlardan olan major-minor-patch yapısını kullanabilirsiniz ben bu yapıyı kullanıyorum ama kimisi bu yapıyı tarihsel olarak kurgulayıp kullanabiliyor örnek YYYY-MM-DD tarih formatını major-minor-patch yapısına uyarlayarak kullanılabiliyor ayrıca bu yapıya bazı kaynaklarda major-minor-build’de denebiliyor. Ben major minor-path diye versiyonlama yapısından bahsettim ama Assembly Information penceresinden baktığınızda 4 kutu olduğunu göreceksiniz buda major-minor-revision-build versiyonlama yapısınıda desteklediğini gösteriyor fakat siz son kutuyu kullanmadığınız zaman otomatik olarak versiyonlamayı 3 basamak olarak gerçekleştiriyor.
Şimdi versiyonlama yapısını neye göre yapmalıyız ne yaptığımız zaman hangi alanı arttırmalıyız gibi sorulara major-minor-revision-build yapısı üzerinden örnek verelim ayrıca bu örneği isterseniz major-minor-patch içinde kullanabilirsiniz. major-minor-revision-build versiyonlama yapısındaki tüm adımları neye göre arttıracağımızı alttaki açıklamalarda görebilirsiniz.
- Major: Uygulamanızda büyük ve önemli değişiklikler olduğunda.
- Minor: Uygulamanızda orta halli önemli değişiklikler olduğunda.
- Revision: Her hangi bir ufak değişiklik yada bug çözümünde.
- Build: Normalde bu alan uygulamanızın her build edilme aşamasında otomatik artan bir değer olması gerekiyor(Bu kısımdan dolayı ben major-minor-patch yapısını kullanmayı daha uygun buluyorum).
Eğer bu süreçleri manuel değilde bir arayüz yardımıyla yapmak istiyorsanız
https://github.com/NuGetPackageExplorer/NuGetPackageExplorermasaüstü yazılımını güvenle kullanabilirsiniz.
NuGet ile ilgili daha farklı bir bilgiye ihtiyacınız varsa kaynaklar kısmındaki https://docs.microsoft.com/en-us/nuget/ adresini ziyaret edip dökümandan faydalanabilirsiniz. Bu makalede Yeni Nuget Paketi nasıl oluşturulur ve Yeni Nuget Paketi’ni nasıl nuget.org’da yayınlayabiliriz bu gibi konulara değindik.
Kaynaklar
- https://docs.microsoft.com/tr-tr/nuget/
