Aracılığıyla paylaş

En iyi paket yazma yöntemleri

  • Makale

Bu kılavuz, NuGet paket yazarlarına yüksek kaliteli paketler oluşturmak ve yayımlamak için basit bir başvuru sağlamak için tasarlanmıştır. Öncelikle meta veriler ve paketleme gibi pakete özgü en iyi yöntemlere odaklanır. Yüksek kaliteli kitaplıklar oluşturmaya yönelik daha ayrıntılı öneriler için .NET Açık kaynak kitaplık kılavuzuna bakın.

Öneri türleri

Her makalede dört tür öneri sunulur: Do, Consider, Avoid ve Do not. Öneri türü, önerinin ne kadar yakından izlenmesi gerektiğini gösterir.

Neredeyse her zaman bir Do önerisine uymanız gerekir. Örneğin:

✔️ DO, paketinizin ne için olduğunu açıklayan kısa bir açıklama içerir.

Öte yandan, Önerilere genel olarak uyulmalıdır, ancak kuralda geçerli özel durumlar vardır:

✔️ NuGet'in ön ek ayırma ölçütlerini karşılayan bir ön ek içeren bir NuGet paket adı seçmeyi göz önünde bulundurun.

Önerilerden kaçının , genellikle iyi bir fikir olmayan şeylerden bahsedin, ancak kuralın çiğnenmesi bazen mantıklı olabilir:

❌ Tam sürüm gerektiren NuGet paket başvurularından KAÇıNıN.

Ve son olarak, Öneriler neredeyse hiçbir zaman yapmanız gereken bir şeyi belirtmeyin:

❌ Meta veri özelliğini KULLANMAYIN LicenseUrl .

NuGet paketi oluşturma

NuGet paketi oluşturmanın en son önerilen yolu SDK stilinde bir projedir. Hedef çerçeve ve paket meta verileri de dahil olmak üzere SDK stili proje özellikleri proje dosyasında tanımlanır.

Visual Studio'da veya dotnet CLI'da gerekli özellikleri tanımlayıp paketleyerek SDK stili projenizden bir paket oluşturun.

✔️ DO, SDK stilinde bir proje oluşturun ve Visual Studio veya dotnet CLI kullanarak paketinizi oluşturun (paketleyin).

Gerekli istemci araçları, proje dosyası örneği ve komutları dahil olmak üzere paket oluşturma hakkında daha ayrıntılı yönergeler için bkz . dotnet CLI kullanarak NuGet paketi oluşturma.

Hangi .NET çerçevelerinin hedeflenmesi gerektiğine karar vermenize yardımcı olmak için platformlar arası hedeflemeye yönelik en son kılavuzumuza bakın.

Paket meta verileri

Meta veriler, herhangi bir NuGet paketinin temel bileşenidir. Meta verilerinizin kalitesi paketinizin bulunabilirliğini, kullanılabilirliğini ve güvenilirliğini büyük ölçüde etkileyebilir.

Visual Studio'da, paket meta verilerini belirtmenin önerilen yolu Project > [Project Name] Özellikler > Paketi'ne gitmektir.

Paket meta veri öğeleri doğrudan proje dosyasında da belirtilebilir.

Aşağıda bir tablo eşlemesi ve kullanılabilir paket meta veri öğelerini açıklama vardır:

Visual Studio özellik adı Proje dosyası/ MSBuild özellik adı Nuspec özellik adı Açıklama
Package id PackageId id Paket adı veya tanımlayıcısı.
Package version PackageVersion version NuGet paket sürümü.
Authors Authors authors Genellikle kişinin veya kuruluşun "güzel adını" kullanan paket yazarlarının virgülle ayrılmış listesi.
Description Description description Paketin açıklaması.
Copyright Copyright copyright Paket için telif hakkı ayrıntıları.
Project URL PackageProjectUrl projectUrl Proje giriş sayfasının URL'si.
Icon File PackageIcon icon Paket simgesi görüntü dosyasının yolu.
README PackageReadmeFile readme Paket README markdown dosyasının yolu.
Repository URL RepositoryUrl repository url Paketin oluşturulduğu deponun URL'si.
Repository type RepositoryType repository type Depo URL'sinin işaret olduğu depo türü (yani "git").
Tags PackageTags tags Paketi açıklayan, boşlukla ayrılmış etiketler ve anahtar sözcükler listesi. Etiketler, paketler aranırken kullanılır.
Release notes PackageReleaseNotes releaseNotes Paketin bu sürümünde yapılan değişikliklerin açıklaması.
Licensing - Expression PackageLicenseExpression license type="expression" SPDX lisans ifadesi.
Licensing - File PackageLicenseFile license type="file" Özel lisans dosyasının yolu.

Paket Kimliği

Tamamen yeni bir paket yayımlıyorsanız:

✔️ DO, NuGet.org'daki mevcut paketlerden benzersiz ve net bir şekilde ayırt edilen bir paket kimliği seçin.

NuGet.org üzerinde kimlik arayarak veya şu bağlantının mevcut olup olmadığını denetleyerek paket kimliğinin benzersiz ve farklı olup olmadığını dekleyebilirsiniz: https://www.nuget.org/packages/<paket adı>.

✔️ NuGet'in ön ek ayırma ölçütlerini karşılayan bir ön ek içeren bir NuGet paket adı seçmeyi göz önünde bulundurun.

Paketinizin ön ek kimliğini ayırmanız, doğrulanmış onay işaretini almanıza olanak verir: image

Daha fazla bilgi edinmek için Paket Kimliği ön eki rezervasyon belgelerine göz atın.

Paket Sürümü

✔️ NuGet paketinizi sürüme eklemek için SemVer kullanmayı göz önünde bulundurun.

Temel olarak, bu Major.Minor.Patch[-prerelease] biçiminin kullanılması anlamına gelir.

✔️ Bir paketi kararlı değilse veya önizlemede yayın öncesi paket olarak yayımlayın.

Daha gelişmiş yönergeler için .NET kitaplığı sürüm oluşturma kılavuzuna bakın.

Yazarlar

✔️ DO, sizin veya kuruluşunuzun "güzel adı" için yazar alanını kullanın.

Örneğin, NuGet.org kullanıcı adım "jdoe" ise yazar alanı için "Jane Doe" kullanmak tüketicilerin beni yazar olarak tanımasını sağlayabilir. Kuruluşumun NuGet.org kullanıcı adı "ContosoToolkit" ise "Contoso Corporation" kullanmak daha tanınabilir ve daha fazla tüketici güvenini teşvik edebilir.

Açıklama

✔️ DO, paketinizi açıklamak için kısa bir açıklama (en fazla 4000 karakter) içerir.

Paket açıklamaları, NuGet aramasında ortaya çıkan en önemli alanlardan biridir ve potansiyel tüketicilerin bir paketin kendileri için uygun olup olmadığını belirlemek için ilk baktığı şey büyük olasılıkla olacaktır.

✔️ DO, paketinize "Telif hakkı (c) <adı/şirket><yılı>" ile bir telif hakkı bildirimi ekleyin.

Telif hakkı bildirimi temelde çalışmanızın izniniz olmadan kopyalanamayacağını belirtir. Paketinize bir telif hakkı bildirimi dahil etmek kolaydır ve hiçbir zarar vermez!

Örnek: Telif Hakkı (c) Contoso 2020

Proje URL'si

✔️ DO, ilişkili bir projeye, depoya veya şirket web sitesine bağlantı içerir.

Proje sitenizde kullanıcıların paketiniz hakkında bilmesi gereken her şey bulunmalıdır ve büyük olasılıkla kullanıcıların belgeleri arayabileceği yer olacaktır.

Simge

✔️ Görsel olarak ayırt edilmesine yardımcı olmak için paketinize bir simge eklemeyi göz önünde bulundurun. Paket kalitesi algısını geliştirebilecek nispeten küçük bir eklemedir.

Simgeler tek tek paketlere özgü olabilir veya bir marka logosu olabilir.

✔️ DO, 128x128 olan ve en iyi sonuçları görüntülemek için saydam arka plana (PNG) sahip bir görüntü kullanın.

NuGet, görüntünüzü otomatik olarak görüntülendiği istemciye ölçeklendirir.

❌ Kullanım dışı meta IconUrl veri özelliğini KULLANMAYIN.

BENİOKU

✔️ DO , paketinizin ne yaptığı ve nasıl başlatıldığını gösteren bir README markdown dosyası ekleyin.

README paketi, paketinizin kalite algısını ve yeni kullanıcı eklemesini önemli ölçüde geliştirecektir. Ayrıca, karşıya yüklemeden önce README'nizin önizlemesini de gözden geçirmeyi göz önünde bulundurun! Daha fazla ayrıntı için NuGet paketinize README dosyası eklemeyi öğrenin.

Depo Türü ve URL

✔️ NuGet paketinize otomatik olarak kaynak denetimi meta verileri eklemek ve kitaplığınızın hata ayıklamasını kolaylaştırmak için Kaynak Bağlantı'nın ayarlanmasını göz önünde bulundurun.

Kaynak Bağlantı, paket meta verilerine otomatik olarak ve Repository Type eklerRepository URL. Ayrıca paket sürümünüzle ilişkili belirli işlemeyi de ekler.

Etiketler

✔️ DO, bulunabilirliği geliştirmek için paketinizle ilgili önemli terimlere sahip çeşitli etiketler içerir.

Etiketler NuGet.org'un arama algoritmasında dikkate alınır ve özellikle Paket Kimliği'nde olmayan ancak ilgili terimler için yararlıdır.

Örneğin, dizeleri konsolda günlüğe kaydetmek için bir paket yayımladıysam şunları eklerim: "günlük, günlük, konsol, dize, çıkış"

Sürüm notları

✔️ DO, hangi değişikliklerin yapıldığını açıklayan her güncelleştirmeye sürüm notları ekler.

Sürüm notları için belirli bir biçim gerekli olmasa da şunların dahil olmasını öneririz:

  1. Hataya neden olan değişiklikler
  2. Yeni özellikler
  3. Hata düzeltmeleri

Sürüm notlarını veya deponuzdaki bir değişiklik günlüğü zaten izlediyseniz, ilgili dosyanın bağlantısını da ekleyebilirsiniz.

Lisanslama

✔️ DO paketinize bir lisans ifadesi veya lisans dosyası ekleyin.

Önemli

Lisansı olmayan bir proje varsayılan olarak özel telif hakkıdır; başka bir deyişle, projenizi kullanmak için kimseye izin vermemişsinizdir.

❌ Kullanım dışı meta LicenseUrl veri özelliğini KULLANMAYIN.

URL'deki lisans değişiklikleri önceki paket sürümleri için görüntülenen lisansı geriye dönük olarak değiştireceği için bu durum yasal belirsizlik sunar.

Paketiniz açık kaynak

✔️ DO, paketinizi açık kaynak yapmak için bir açık kaynak lisansı seçin.

"Açık kaynak lisansları, Açık Kaynak Tanımına uygun lisanslardır; kısaca yazılımın serbestçe kullanılmasına, değiştirilmesine ve paylaşılmasına izin verir." - Açık Kaynak Girişimi. açık kaynak yazılımı ve Açık Kaynak Girişimi hakkında daha fazla bilgi edinmek için bkzhttps://opensource.org/. .

✔️ Paketinize bir lisans ifadesi eklemeyi GÖZ ÖNÜNDE BULUNDURUN.

Lisans ifadeleri en net şekilde ortaya çıkar ve paketinizi kullanabilecekleri veya lisansın değiştirilip değiştirilmediğini tüketiciler için daha belirgin hale getirir.

Not

NuGet.org yalnızca Açık Kaynak Girişimi veya Özgür Yazılım Vakfı tarafından onaylanan lisanslar için lisans ifadelerini kabul eder.

Paketiniz açık kaynak

✔️ DO paketinize bir lisans dosyası ekleyin.

Standart olmayan lisanslar dahil olmak üzere paketinize herhangi bir lisans dosyası (.txt veya .md) eklenebilir.