Osvědčené postupy vytváření balíčků

  • Článek

Cílem těchto pokynů je poskytnout autorům balíčků NuGet jednoduchý odkaz na vytváření a publikování vysoce kvalitních balíčků. Zaměřuje se především na osvědčené postupy specifické pro balíčky, jako jsou metadata a balení. Podrobnější návrhy pro vytváření vysoce kvalitních knihoven najdete v pokynech k opensourcové knihovně .NET.

Typy doporučení

Každý článek obsahuje čtyři typy doporučení: Do, Zvažte, Vyhněte se a Ne. Typ doporučení označuje, jak přesně se má dodržovat.

Téměř vždy byste měli postupovat podle doporučení Provádět. Příklad:

✔️ Do include a short description for your package that describes what it's it's.

Na druhou stranu zvažte doporučení, která by měla být obecně dodržena, ale existují oprávněné výjimky pravidla:

✔️ ZVAŽTE výběr názvu balíčku NuGet s předponou, která splňuje kritéria rezervace předpony NuGetu.

Vyhněte se doporučením zmínit věci, které obecně nejsou vhodné, ale porušení pravidla někdy dává smysl:

❌ Vyhněte se odkazům na balíčky NuGet, které vyžadují přesnou verzi.

A nakonec doporučení nenaznačují něco, co byste téměř nikdy neměli dělat:

❌ NEPOUŽÍVEJTE LicenseUrl vlastnost metadat.

Vytvoření balíčku NuGet

Nejnovější doporučený způsob, jak vytvořit balíček NuGet, je z projektu ve stylu sady SDK. Vlastnosti projektu ve stylu sady SDK, včetně cílové architektury a metadat balíčku, jsou definovány v souboru projektu.

Vytvořte balíček z projektu ve stylu sady SDK definováním požadovaných vlastností a balením v sadě Visual Studio nebo rozhraní příkazového řádku dotnet.

✔️ Vytvořte projekt ve stylu sady SDK a pomocí sady Visual Studio nebo rozhraní příkazového řádku dotnet vytvořte balíček (balíček).

Podrobnější pokyny týkající se vytváření balíčků, včetně potřebných klientských nástrojů, příkladu souboru projektu a příkazů, najdete v tématu Vytvoření balíčku NuGet pomocí rozhraní příkazového řádku dotnet.

Pokud chcete pomoct se rozhodnout, které architektury .NET se mají cílit, podívejte se na naše nejnovější pokyny pro cílení na různé platformy.

Metadata balíčků

Metadata jsou základní komponentou libovolného balíčku NuGet. Kvalita metadat může výrazně ovlivnit zjistitelnost, použitelnost a důvěryhodnost balíčku.

V sadě Visual Studio doporučujeme zadat metadata balíčku tak, že přejdete do balíčku vlastností > Projektu [Název projektu > ].

Prvky metadat balíčku lze také zadat přímo v souboru projektu.

Níže je uvedeno mapování tabulky a popis dostupných prvků metadat balíčku:

Název vlastnosti sady Visual Studio Soubor projektu / název vlastnosti MSBuild Název vlastnosti Nuspec Popis
Package id PackageId id Název nebo identifikátor balíčku.
Package version PackageVersion version Verze balíčku NuGet
Authors Authors authors Seznam autorů balíčků oddělený čárkami, často používající "hezký název" jednotlivce nebo organizace.
Description Description description Popis balíčku.
Copyright Copyright copyright Podrobnosti o autorských právech pro balíček.
Project URL PackageProjectUrl projectUrl Adresa URL domovské stránky projektu.
Icon File PackageIcon icon Cesta k souboru obrázku ikony balíčku
README PackageReadmeFile readme Cesta k souboru markdownu README balíčku
Repository URL RepositoryUrl repository url Adresa URL úložiště, ze kterého byl balíček sestaven.
Repository type RepositoryType repository type Typ úložiště, na které adresa URL úložiště ukazuje (tj. git).
Tags PackageTags tags Seznam značek a klíčových slov oddělených mezerami, které popisují balíček. Značky se používají při hledání balíčků.
Release notes PackageReleaseNotes releaseNotes Popis změn provedených v této verzi balíčku
Licensing - Expression PackageLicenseExpression license type="expression" Výraz licence SPDX.
Licensing - File PackageLicenseFile license type="file" Cesta k vlastnímu licenčnímu souboru

ID balíčku

Pokud publikujete zcela nový balíček:

✔️ Zvolte ID balíčku, které je jedinečné a jasně odlišné od existujících balíčků v NuGet.org.

Id balíčku můžete zkontrolovat tak, že vyhledáte ID na NuGet.org nebo zkontrolujete, jestli existuje následující odkaz: https://www.nuget.org/packages/<název> balíčku.

✔️ ZVAŽTE výběr názvu balíčku NuGet s předponou, která splňuje kritéria rezervace předpony NuGetu.

Rezervace ID předpony pro váš balíček vám umožní získat ověřenou značku zaškrtnutí: image

Další informace najdete v dokumentaci k rezervaci předpony ID balíčku.

Verze balíčku

✔️ ZVAŽTE použití SemVer k verzi balíčku NuGet.

V podstatě to znamená použití formátu Major.Minor.Patch[-prerelease].

✔️ Publikujte balíček jako předběžný balíček , pokud není stabilní nebo je ve verzi Preview.

Podrobnější pokyny najdete v průvodci správa verzí knihovny .NET.

Autoři

✔️ Použijte pole autora pro "hezký název" vaší organizace.

Pokud je například moje NuGet.org uživatelské jméno "jdoe", může použití Jane Doe pro pole autora pomoct uživatelům rozpoznat mě jako autora. Pokud je uživatelské jméno organizace NuGet.org "ContosoToolkit", může být použití společnosti Contoso Corporation rozpoznatelné a inspirovat větší důvěru spotřebitelů.

Popis

✔️ Do zadejte krátký popis (až 4 000 znaků), který popisuje váš balíček.

Popisy balíčků jsou jedním z nejvýraznějších polí, která se objeví ve vyhledávání NuGet, a pravděpodobně to bude první věc, na kterou se potenciální spotřebitelé podívá, jestli je pro ně balíček správný.

✔️ Do balíčku přidejte oznámení o autorských právech s textem "Copyright (c) <name /company><year>".

Oznámení o autorských právech v podstatě znamená, že vaši práci nelze kopírovat bez vašeho svolení. Zahrnutí oznámení o autorských právech do balíčku je snadné a neuškodí!

Příklad: Copyright (c) Contoso 2020

Adresa URL projektu

✔️ Do include a link to an associated project, repository, or company website.

Váš projektový web by měl obsahovat všechno, co uživatelé potřebují vědět o vašem balíčku, a bude pravděpodobně místem, kde uživatelé hledají dokumentaci.

Ikona

✔️ ZVAŽTE zahrnutí ikony do balíčku , abyste ji vizuálně odlišili. Jedná se o relativně malý doplněk, který může zlepšit vnímání kvality balíčku.

Ikony můžou být specifické pro jednotlivé balíčky nebo logo značky.

✔️ Použijte obrázek, který je 128 × 128 a má průhledné pozadí (PNG) pro nejlepší zobrazení výsledků.

NuGet automaticky škáluje vaši image na klienta, na kterém se zobrazuje.

❌ NEPOUŽÍVEJTE zastaralou IconUrl vlastnost metadat.

Soubor Readme

✔️ Přidejte soubor markdownu README, který poskytuje přehled toho, co váš balíček dělá a jak začít.

Soubor README balíčku výrazně zlepší vnímání kvality balíčku i nové registrace uživatelů. Než soubor nahrajete, zvažte také náhled souboru README . Další podrobnosti najdete v tom, jak do balíčku NuGet zahrnout soubor README.

Typ úložiště a adresa URL

✔️ ZVAŽTE nastavení zdrojového odkazu pro automatické přidání metadat správy zdrojového kódu do balíčku NuGet a usnadnění ladění knihovny.

Odkaz na zdroj automaticky přidá Repository URL metadata balíčku a Repository Type do jeho metadat. Přidá také konkrétní potvrzení přidružené k vaší verzi balíčku.

Značky

✔️ Do include několik značek with key terms related to your package to enhance discoverability.

Značky se zohledňují ve vyhledávacím algoritmu NuGet.org a jsou užitečné zejména pro výrazy, které nejsou v ID balíčku, ale jsou relevantní.

Pokud jsem například publikoval(a) balíček pro protokolování řetězců do konzoly, zahrnoval bych: "logging, log, console, string, output" (protokolování, protokol, konzola, řetězec, výstup).

Poznámky k verzi

✔️ Do include release notes with each update popis what changes were made.

I když pro poznámky k verzi není nutný žádný konkrétní formát, doporučujeme:

  1. Změny způsobující chyby
  2. Nové funkce
  3. Opravy chyb

Pokud už poznámky k verzi nebo protokol změn v úložišti sledujete, můžete také přidat odkaz na příslušný soubor.

Licencování

✔️ Do balíčku zahrňte licenční výraz nebo soubor licence.

Důležité

Projekt bez licence má výchozí výhradní autorská práva, což znamená, že jste nikomu neudělili oprávnění k používání vašeho projektu.

❌ NEPOUŽÍVEJTE zastaralou LicenseUrl vlastnost metadat.

To představuje právní nejednoznačnost, protože změny licencí na adrese URL zpětně změní zobrazenou licenci pro předchozí verze balíčků.

Pokud je váš balíček open source

✔️ Zvolte opensourcovou licenci , aby byl balíček opensourcový.

"Open source licence jsou licence, které splňují definici Open Source – stručně řečeno umožňují volně používat, upravovat a sdílet software." - Open Source Initiative. Další informace o opensourcovém softwaru a open source iniciativě najdete v tématu https://opensource.org/.

✔️ ZVAŽTE zahrnutí licenčního výrazu do balíčku.

Licenční výrazy se zobrazí nejjasněji a uživatelům to zviditelní, pokud můžou balíček používat nebo pokud se licence změnila.

Poznámka:

NuGet.org přijímá pouze licenční výrazy pro licence schválené Open Source Initiative nebo Free Software Foundation.

Pokud balíček není open source

✔️ Do balíčku zahrňte licenční soubor.

Do balíčku můžete přidat libovolný licenční soubor (.txt nebo .md), včetně nestandardních licencí.