Best practices voor het opstellen van softwarepakketten

2025-10-31

Deze richtlijnen zijn bedoeld om NuGet-pakketauteurs een lichtgewicht referentie te geven voor het maken en publiceren van hoogwaardige pakketten. Het richt zich voornamelijk op pakketspecifieke best practices, zoals metagegevens en verpakking. Zie de richtlijnen voor opensource-bibliotheken voor .NET voor uitgebreidere suggesties voor het bouwen van bibliotheken van hoge kwaliteit.

Typen aanbevelingen

Elk artikel bevat vier soorten aanbevelingen: Do, Consider, Avoid en Do not. Het type aanbeveling geeft aan hoe nauwkeurig deze moet worden gevolgd.

U moet bijna altijd een Do-aanbeveling volgen. Voorbeeld:

✔️ Neem een korte beschrijving op voor uw pakket waarin wordt beschreven waarvoor het is bedoeld.

Aan de andere kant moeten overweeg aanbevelingen in het algemeen worden gevolgd, maar er zijn legitieme uitzonderingen op de regel:

✔️ OVERWEEG om een NuGet-pakketnaam te kiezen met een voorvoegsel dat voldoet aan de reserveringscriteria voor nuGet-voorvoegsels.

Vermijd aanbevelingen over dingen die over het algemeen geen goed idee zijn, maar soms kan het breken van de regel zinvol zijn.

❌ VERMIJD NuGet-pakketverwijzingen die een exacte versie vragen.

En tot slot geven niet doen aanbevelingen aan wat u bijna nooit moet doen:

❌ Gebruik de LicenseUrl eigenschap metagegevens NIET.

Een NuGet-pakket maken

De meest recente aanbevolen manier om een NuGet-pakket te maken, is afkomstig van een SDK-project. Projecteigenschappen in SDK-stijl, waaronder doelframework en pakketmetagegevens, worden gedefinieerd in het projectbestand.

Maak een pakket op basis van uw SDK-project door de vereiste eigenschappen en verpakking in Visual Studio of de dotnet CLI te definiëren.

✔️ Maak een SDK-project en maak (pack) uw pakket met Visual Studio of de dotnet CLI.

Zie Een NuGet-pakket maken met behulp van de dotnet CLI voor meer gedetailleerde richtlijnen met betrekking tot het maken van pakketten, inclusief de benodigde clienthulpprogramma's, het voorbeeld van een projectbestand en opdrachten.

Raadpleeg onze nieuwste richtlijnen voor platformoverschrijdende doelen om te bepalen welke .NET Frameworks moeten worden gebruikt.

Pakketmetagegevens

Metagegevens zijn een fundamenteel onderdeel van elk NuGet-pakket. De kwaliteit van uw metagegevens kan enorm van invloed zijn op de vindbaarheid, bruikbaarheid en betrouwbaarheid van uw pakket.

In Visual Studio is de aanbevolen manier om pakketmetagegevens op te geven via Project > [Projectnaam] Eigenschappen > Pakket.

Elementen van pakketmetagegevens kunnen ook rechtstreeks in het projectbestand worden opgegeven.

Hieronder ziet u een tabeltoewijzing en een beschrijving van beschikbare metagegevenselementen voor pakketten:

Naam van Visual Studio-eigenschap	Projectbestand/ MSBuild-eigenschapsnaam	Naam van nuspec-eigenschap	Description
`Package id`	`PackageId`	`id`	De pakketnaam of identificatie.
`Package version`	`PackageVersion`	`version`	NuGet-pakketversie.
`Authors`	`Authors`	`authors`	Een door komma's gescheiden lijst met pakketauteurs, vaak met behulp van de 'mooie naam' van de persoon of een organisatie.
`Description`	`Description`	`description`	Een beschrijving van het pakket.
`Copyright`	`Copyright`	`copyright`	Copyrightgegevens voor het pakket.
`Project URL`	`PackageProjectUrl`	`projectUrl`	Een URL voor de startpagina van het project.
`Icon File`	`PackageIcon`	`icon`	Pad naar het afbeeldingsbestand van het pakketpictogram.
`README`	`PackageReadmeFile`	`readme`	Pad naar het README Markdown-bestand van het pakket.
`Repository URL`	`RepositoryUrl`	`repository url`	URL naar de opslagplaats waaruit het pakket is gebouwd.
`Repository type`	`RepositoryType`	`repository type`	Het type opslagplaats waarnaar de URL van de opslagplaats verwijst (bijvoorbeeld 'git').
`Tags`	`PackageTags`	`tags`	Een door spaties gescheiden lijst met tags en trefwoorden die het pakket beschrijven. Tags worden gebruikt bij het zoeken naar pakketten.
`Release notes`	`PackageReleaseNotes`	`releaseNotes`	Een beschrijving van de wijzigingen die in deze versie van het pakket zijn aangebracht.
`Licensing - Expression`	`PackageLicenseExpression`	`license type="expression"`	Een SPDX-licentie-expressie.
`Licensing - File`	`PackageLicenseFile`	`license type="file"`	Pad naar een aangepast licentiebestand.

Pakket-ID

Als u een volledig nieuw pakket publiceert:

✔️ Kies een pakket-id die uniek is en duidelijk is onderscheiden van bestaande pakketten op NuGet.org.

U kunt controleren of een pakket-id uniek en verschillend is door te zoeken naar de id op NuGet.org of door te controleren of de volgende koppeling bestaat: https://www.nuget.org/packages/<pakketnaam>.

✔️ OVERWEEG om een NuGet-pakketnaam te kiezen met een voorvoegsel dat voldoet aan de reserveringscriteria voor nuGet-voorvoegsels.

Als u de prefix-ID voor uw pakket reserveert, krijgt u de geverifieerde badge:

Bekijk de documentatie over pakket-ID voorvoegselreserveringen voor meer informatie.

Pakketversie

✔️ OVERWEEG om SemVer te gebruiken om uw NuGet-pakket te versien.

Dit betekent in wezen dat u de indeling Major.Minor.Patch[-prerelease] gebruikt.

✔️ Publiceer een pakket als een pre-releasepakket als het niet stabiel of een preview-versie is.

Zie de handleiding voor .NET-bibliotheekversiebeheer voor meer geavanceerde richtlijnen.

Auteurs

✔️ Gebruik het veld Auteur voor de 'mooie naam' van uw of uw organisatie.

Als mijn NuGet.org gebruikersnaam bijvoorbeeld 'jdoe' is, kan het gebruik van 'Jane Doe' voor het auteursveld consumenten helpen mij te herkennen als auteur. Als de NuGet.org gebruikersnaam van mijn organisatie 'ContosoToolkit' is, kan het gebruik van Contoso Corporation herkenbaarder zijn en meer consumentenvertrouwen inspireren.

Description

✔️ Neem een korte beschrijving (maximaal 4000 tekens) op om uw pakket te beschrijven.

Pakketbeschrijvingen zijn een van de meest prominente velden die worden weergegeven in NuGet-zoekopdracht en zullen waarschijnlijk het eerste zijn waar potentiële consumenten naar kijken om te bepalen of een pakket geschikt is voor hen.

Auteursrecht

✔️ Voeg een copyrightmelding toe aan uw pakket met 'Copyright (c) <name/company><year>'.

Een copyrightmelding geeft in wezen aan dat uw werk niet kan worden gekopieerd zonder uw toestemming. Het opnemen van een copyrightmelding in uw pakket is eenvoudig en zal geen kwaad doen!

Voorbeeld: Copyright (c) Contoso 2020

Project-URL

✔️ Neem een koppeling op naar een gekoppeld project, opslagplaats of bedrijfswebsite.

Uw projectsite moet alles hebben wat gebruikers moeten weten over uw pakket en zijn waarschijnlijk waar gebruikers naar documentatie zoeken.

Icon

✔️ OVERWEEG een pictogram met uw pakket op te nemen om het visueel te onderscheiden. Het is een relatief kleine toevoeging die de perceptie van pakketkwaliteit kan verbeteren.

Pictogrammen kunnen specifiek zijn voor afzonderlijke pakketten of een merklogo zijn.

✔️ GEBRUIK een afbeelding van 128x128 en heeft een transparante achtergrond (PNG) voor het beste weergeven van resultaten.

NuGet schaalt uw afbeelding automatisch naar de client waarop deze wordt weergegeven.

❌ GEBRUIK DE afgeschafte IconUrl eigenschap voor metagegevens NIET.

LEESMIJ

✔️ VOEG EEN README Markdown-bestand toe dat een overzicht biedt van wat uw pakket doet en hoe u aan de slag kunt gaan.

Een README in uw pakket verbetert de kwaliteitsperceptie van uw pakket aanzienlijk en de onboarding van nieuwe gebruikers. Overweeg ook uw LEESMIJ te bekijken voordat u deze uploadt. Zie hoe u een README-bestand in uw NuGet-pakket opneemt voor meer informatie.

Type opslagplaats en URL

✔️ OVERWEEG om Bronkoppeling in te stellen om automatisch metagegevens van broncodebeheer toe te voegen aan uw NuGet-pakket en om fouten in uw bibliotheek gemakkelijker op te sporen.

Bronkoppeling voegt Repository URL en Repository Type automatisch toe aan de metagegevens van het pakket. Ook wordt de specifieke doorvoer toegevoegd die is gekoppeld aan uw pakketversie.

Opmerkingen bij de uitgave

✔️ Neem releaseopmerkingen op bij elke update waarin wordt beschreven welke wijzigingen zijn aangebracht.

Hoewel er geen specifieke indeling is vereist voor releaseopmerkingen, raden we u aan het volgende op te geven:

Brekende wijzigingen

Nieuwe functies

Fouten opgelost

Als u al opmerkingen bij de release of een wijzigingslogboek in uw opslagplaats bijhoudt, kunt u ook een koppeling naar het relevante bestand opnemen.

Licensing

✔️ Neem een licentie-expressie of licentiebestand op in uw pakket.

Belangrijk

Een project zonder licentie is standaard ingesteld op exclusief auteursrecht, wat betekent dat u niemand toestemming hebt gegeven om uw project te gebruiken.

❌ GEBRUIK DE afgeschafte LicenseUrl eigenschap voor metagegevens NIET.

Dit geeft juridische dubbelzinnigheid als licentiewijzigingen op de URL met terugwerkende kracht de weergegeven licentie voor eerdere pakketversies wijzigen.

Als uw pakket open source is

✔️ KIES EEN opensource-licentie om uw pakket open source te maken.

'Opensource-licenties zijn licenties die voldoen aan de Open Source-definitie, kortom: ze zorgen ervoor dat software vrij kan worden gebruikt, gewijzigd en gedeeld. ' - Open Source Initiative. Zie https://opensource.org/voor meer informatie over opensource-software en het Open Source Initiative.

✔️ OVERWEEG een licentie-expressie op te nemen in uw pakket.

Licentie-expressies worden het duidelijkst weergegeven en maken het duidelijker voor consumenten als ze uw pakket kunnen gebruiken of als de licentie is gewijzigd.

Opmerking

NuGet.org accepteert alleen licentie-expressies voor licenties die zijn goedgekeurd door het Open Source Initiative of de Free Software Foundation.

Als uw pakket niet open source is

✔️ Neem een licentiebestand op in uw pakket.

Elk licentiebestand (.txt of .md) kan worden toegevoegd aan uw pakket, inclusief niet-standaardlicenties.

Feedback

Is deze pagina nuttig?