Najlepsze rozwiązania dotyczące tworzenia pakietów
Te wskazówki mają na celu zapewnienie autorom pakietów NuGet lekkiego odwołania do tworzenia i publikowania pakietów wysokiej jakości. Koncentruje się przede wszystkim na najlepszych rozwiązaniach specyficznych dla pakietu, takich jak metadane i pakowanie. Aby uzyskać bardziej szczegółowe sugestie dotyczące tworzenia bibliotek wysokiej jakości, zobacz wskazówki dotyczące bibliotek open source platformy .NET.
Typy zaleceń
W każdym artykule przedstawiono cztery typy zaleceń: Wykonaj, Rozważ, Unikaj i Nie. Typ zalecenia wskazuje, jak ściśle należy postępować zgodnie z zaleceniami.
Prawie zawsze należy postępować zgodnie z zaleceniem Wykonaj . Na przykład:
✔️ Do dołącz krótki opis pakietu, który opisuje, co to jest.
Z drugiej strony należy rozważyć stosowanie zaleceń, ale istnieją uzasadnione wyjątki od reguły:
✔️ ROZWAŻ wybranie nazwy pakietu NuGet z prefiksem spełniającym kryteria rezerwacji prefiksu NuGet.
Unikaj rekomendacji, które zazwyczaj nie są dobrym pomysłem, ale łamanie reguły czasami ma sens:
❌ UNIKAJ odwołań pakietów NuGet, które wymagają dokładnej wersji.
I wreszcie, Nie rekomendacje wskazują coś, czego prawie nigdy nie należy robić:
❌ NIE UŻYWAJ LicenseUrl właściwości metadanych.
Tworzenie pakietu NuGet
Najnowszym zalecanym sposobem tworzenia pakietu NuGet jest projekt w stylu zestawu SDK. Właściwości projektu w stylu zestawu SDK, w tym struktury docelowej i metadanych pakietu, są definiowane w pliku projektu.
Utwórz pakiet na podstawie projektu w stylu zestawu SDK, definiując wymagane właściwości i pakowania w programie Visual Studio lub interfejsie wiersza polecenia dotnet.
✔️ UTWÓRZ projekt w stylu zestawu SDK i utwórz pakiet (pakiet) przy użyciu programu Visual Studio lub interfejsu wiersza polecenia dotnet.
Aby uzyskać bardziej szczegółowe wskazówki dotyczące tworzenia pakietów, w tym niezbędne narzędzia klienckie, przykład pliku projektu i polecenia, zobacz Tworzenie pakietu NuGet przy użyciu interfejsu wiersza polecenia dotnet.
Aby ułatwić podjęcie decyzji, które platformy .NET mają być docelowe, zapoznaj się z naszymi najnowszymi wskazówkami dotyczącymi określania docelowych platform międzyplatformowych.
Metadane pakietu
Metadane są podstawowym składnikiem dowolnego pakietu NuGet. Jakość metadanych może znacząco wpływać na możliwość odnajdywania, użyteczność i wiarygodność pakietu.
W programie Visual Studio zalecanym sposobem określenia metadanych pakietu jest przejście do pozycji Project [Project Name] Properties Package (Projekt [Nazwa projektu > ] Pakiet właściwości > ).
Elementy metadanych pakietu można również określić bezpośrednio w pliku projektu.
Poniżej przedstawiono mapowanie tabeli i opisywanie dostępnych elementów metadanych pakietu:
| Nazwa właściwości programu Visual Studio | Plik projektu/ nazwa właściwości MSBuild | Nazwa właściwości Nuspec | opis |
|---|---|---|---|
Package id |
PackageId |
id |
Nazwa lub identyfikator pakietu. |
Package version |
PackageVersion |
version |
Wersja pakietu NuGet. |
Authors |
Authors |
authors |
Rozdzielona przecinkami lista autorów pakietów, często używających "ładnej nazwy" osoby lub organizacji. |
Description |
Description |
description |
Opis pakietu. |
Copyright |
Copyright |
copyright |
Szczegóły praw autorskich dla pakietu. |
Project URL |
PackageProjectUrl |
projectUrl |
Adres URL strony głównej projektu. |
Icon File |
PackageIcon |
icon |
Ścieżka do pliku obrazu ikony pakietu. |
README |
PackageReadmeFile |
readme |
Ścieżka do pliku markdown README pakietu. |
Repository URL |
RepositoryUrl |
repository url |
Adres URL do repozytorium, z którego utworzono pakiet. |
Repository type |
RepositoryType |
repository type |
Typ repozytorium, na który wskazuje adres URL repozytorium (tj. "git"). |
Tags |
PackageTags |
tags |
Rozdzielana spacjami lista tagów i słów kluczowych opisujących pakiet. Tagi są używane podczas wyszukiwania pakietów. |
Release notes |
PackageReleaseNotes |
releaseNotes |
Opis zmian wprowadzonych w tej wersji pakietu. |
Licensing - Expression |
PackageLicenseExpression |
license type="expression" |
Wyrażenie licencji SPDX. |
Licensing - File |
PackageLicenseFile |
license type="file" |
Ścieżka do niestandardowego pliku licencji. |
Identyfikator pakietu
Jeśli publikujesz zupełnie nowy pakiet:
✔️ WYBIERZ identyfikator pakietu, który jest unikatowy i wyraźnie rozróżniany od istniejących pakietów w NuGet.org.
Możesz sprawdzić, czy identyfikator pakietu jest unikatowy i inny, wyszukując identyfikator na NuGet.org lub sprawdzając, czy istnieje następujący link: https://www.nuget.org/packages/<nazwa> pakietu.
✔️ ROZWAŻ wybranie nazwy pakietu NuGet z prefiksem spełniającym kryteria rezerwacji prefiksu NuGet.
Rezerwowanie identyfikatora prefiksu dla pakietu umożliwi uzyskanie zweryfikowanego znacznika wyboru:
Zapoznaj się z dokumentami rezerwacji prefiksu identyfikatora pakietu, aby dowiedzieć się więcej.
Wersja pakietu
✔️ ROZWAŻ użycie narzędzia SemVer do wersji pakietu NuGet.
Zasadniczo oznacza to użycie formatu Major.Minor.Patch[-prerelease].
✔️ Czy opublikować pakiet jako pakiet wstępny, jeśli nie jest stabilny lub jest w wersji zapoznawczej.
Aby uzyskać bardziej zaawansowane wskazówki, zobacz przewodnik obsługi wersji biblioteki .NET.
Autorzy
✔️ CZY użyć pola autora dla swojej organizacji "ładna nazwa".
Jeśli na przykład moja nazwa użytkownika NuGet.org to "jdoe", użycie pola "Jane Doe" może pomóc konsumentom rozpoznać mnie jako autora. Jeśli nazwa użytkownika NuGet.org mojej organizacji to "ContosoToolkit", użycie "Contoso Corporation" może być bardziej rozpoznawalne i inspirować więcej zaufania konsumentów.
opis
✔️ Aby opisać pakiet, dołącz krótki opis (maksymalnie 4000 znaków).
Opisy pakietów są jednym z najbardziej widocznych pól widocznych w wyszukiwaniu NuGet i prawdopodobnie będzie to pierwsza rzecz, na którą potencjalni konsumenci patrzą, aby ustalić, czy pakiet jest odpowiedni dla nich.
Prawo autorskie
✔️ DO dodaj powiadomienie o prawach autorskich do pakietu z "Copyright (c) <name/company><year>".
Powiadomienie o prawach autorskich zasadniczo wskazuje, że nie można skopiować twojej pracy bez zgody użytkownika. Uwzględnienie powiadomienia o prawach autorskich w pakiecie jest łatwe i nie zaszkodzi!
Przykład: Copyright (c) Contoso 2020
Adres URL projektu
✔️ Czy dołączyć link do skojarzonego projektu, repozytorium lub witryny internetowej firmy.
Witryna projektu powinna mieć wszystkie elementy, które użytkownicy muszą wiedzieć o pakiecie i prawdopodobnie będą szukać dokumentacji.
Ikona
✔️ ROZWAŻ dołączenie ikony z pakietem , aby ułatwić wizualne odróżnienie go. Jest to stosunkowo mały dodatek, który może poprawić postrzeganie jakości pakietów.
Ikony mogą być specyficzne dla poszczególnych pakietów lub być logo marki.
✔️ Do użyj obrazu 128x128 i ma przezroczyste tło (PNG), aby uzyskać najlepsze wyniki wyświetlania.
Narzędzie NuGet automatycznie skaluje obraz do klienta, na który jest wyświetlany.
❌ NIE używaj przestarzałej IconUrl właściwości metadanych.
Plik README
✔️ DODAJ plik markdown README, który zawiera omówienie działania pakietu i sposobu rozpoczęcia pracy.
Pakiet README znacznie poprawi postrzeganie jakości pakietu, a także nowego dołączania użytkowników. Rozważ również wyświetlenie podglądu pliku README przed jego przekazaniem. Aby uzyskać więcej informacji, zobacz , jak dołączyć plik README do pakietu NuGet.
Typ i adres URL repozytorium
✔️ ROZWAŻ skonfigurowanie linku źródłowego, aby automatycznie dodać metadane kontroli źródła do pakietu NuGet i ułatwić debugowanie biblioteki.
Link źródłowy automatycznie dodaje
Repository URLmetadane pakietu iRepository Typedo tych metadanych. Dodaje również określone zatwierdzenie skojarzone z wersją pakietu.
Tagi
✔️ Aby zwiększyć możliwości odnajdywania, dołącz kilka tagów z kluczowymi terminami związanymi z pakietem.
Tagi są brane pod uwagę w algorytmie wyszukiwania NuGet.org i są szczególnie przydatne w przypadku terminów, które nie znajdują się w identyfikatorze pakietu, ale są istotne.
Jeśli na przykład opublikowano pakiet w celu rejestrowania ciągów w konsoli, dołączę: "rejestrowanie, dziennik, konsola, ciąg, dane wyjściowe"
Informacje o wersji
✔️ Dołącz informacje o wersji z każdą aktualizacją opisującą wprowadzone zmiany.
Chociaż nie ma określonego formatu wymaganego dla informacji o wersji, zalecamy uwzględnienie następujących funkcji:
- Zmiany powodujące niezgodność
- Nowe funkcje
- Poprawki błędów
Jeśli już śledzisz informacje o wersji lub dziennik zmian w repozytorium, możesz również dołączyć link do odpowiedniego pliku.
Licencjonowanie
✔️ Do dołącz wyrażenie licencji lub plik licencji w pakiecie.
Ważne
Projekt bez licencji domyślnie korzysta z wyłącznych praw autorskich, co oznacza, że nie udzielono nikomu uprawnień do korzystania z projektu.
❌ NIE używaj przestarzałej LicenseUrl właściwości metadanych.
Przedstawia to niejednoznaczność prawną, ponieważ zmiany licencji w adresie URL będą wstecznie zmieniać wyświetlaną licencję dla poprzednich wersji pakietu.
Jeśli pakiet jest open source
✔️ CZY wybrać licencję typu open source, aby utworzyć pakiet open source.
"Licencje typu open source to licencje zgodne z definicją typu open source — krótko mówiąc, umożliwiają bezpłatne używanie, modyfikowanie i udostępnianie oprogramowania". - Inicjatywa open source. Aby dowiedzieć się więcej o oprogramowaniu typu open source i inicjatywie open source, zapoznaj się z tematem https://opensource.org/.
✔️ ROZWAŻ uwzględnienie wyrażenia licencji w pakiecie.
Wyrażenia licencji są najjjaśniejsze i bardziej oczywiste dla konsumentów, jeśli mogą korzystać z pakietu lub czy licencja uległa zmianie.
Uwaga
NuGet.org akceptuje tylko wyrażenia licencji dla licencji zatwierdzonych przez inicjatywę open source lub Free Software Foundation.
Jeśli pakiet nie jest open source
✔️ DO dołącz plik licencji w pakiecie.
Do pakietu można dodać dowolny plik licencji (.txt lub md), w tym licencje niestandardowe.