Quickstart: Een pakket maken en publiceren met behulp van Visual Studio (.NET Framework, Windows)

Met Microsoft Visual Studio kunt u een NuGet-pakket maken op basis van een .NET Framework-klassebibliotheek en het vervolgens publiceren naar nuget.org met behulp van het NuGet CLI-hulpprogramma.

De quickstart is alleen bedoeld voor Windows gebruikers. Als u Visual Studio voor Mac gebruikt, raadpleegt u in plaats daarvan dotnet CLI-hulpprogramma's.

Vereiste voorwaarden

• Installeer Visual Studio 2022 voor Windows met een .NET-gerelateerde workload.

  U kunt de communityversie 2022 gratis installeren vanuit visualstudio.microsoft.comof de Professional- of Enterprise-editie gebruiken.

  Visual Studio 2017 en hoger bevat automatisch NuGet-mogelijkheden wanneer een .NET workload is geïnstalleerd.

• Registreer u voor een gratis account op nuget.org als u er nog geen hebt. U moet het account registreren en bevestigen voordat u een NuGet-pakket kunt uploaden.

• Installeer de NuGet CLI door deze te downloaden van nuget.org. Voeg het bestandnuget.exe toe aan een geschikte map en voeg die map toe aan de omgevingsvariabele PATH.

Een klassebibliotheekproject maken

Voer de volgende stappen uit om een klassebibliotheekproject te maken:

1. Selecteer bestand>nieuw>project in Visual Studio.

2. Selecteer in het venster Maak een nieuw projectC#, Windows en Library in de vervolgkeuzelijsten.

3. Selecteer in de resulterende lijst met projectsjablonen Class Library (.NET Framework) en selecteer vervolgens Next.

4. Voer in het venster Configure your new projectAppLogger in voor de Project name en selecteer Create.

5. Selecteer Build Build>Solution om ervoor te zorgen dat het project correct is gemaakt. Het DLL-bestand bevindt zich in de map Foutopsporing (of Release als u die configuratie bouwt).

6. (Optioneel) Voor deze quickstart hoeft u geen extra code te schrijven voor het NuGet-pakket, omdat de sjabloonklassebibliotheek voldoende is om een pakket te maken. Als u echter een functionele code voor dit voorbeeldpakket wilt gebruiken, moet u de volgende code opnemen:

   namespace AppLogger
   {
       public class Logger
       {
           public void Log(string text)
           {
               Console.WriteLine(text);
           }
       }
   }
   

   In een echt NuGet-pakket zou u waarschijnlijk veel nuttige functies implementeren waarmee anderen toepassingen kunnen bouwen. U kunt ook de doelframeworks instellen. Zie UWP voor een voorbeeld.

Projecteigenschappen voor het pakket configureren

Een NuGet-pakket bevat een manifest (een .nuspec bestand), dat relevante metagegevens bevat, zoals de pakket-id, het versienummer, de beschrijving en meer. Sommige van deze metagegevens kunnen rechtstreeks worden opgehaald uit de projecteigenschappen, waardoor ze niet afzonderlijk moeten worden bijgewerkt in zowel het project als het manifest. In de volgende stappen wordt beschreven hoe u de toepasselijke eigenschappen instelt:

1. Selecteer Project > Eigenschappen en selecteer vervolgens het tabblad Applicatie.

2. Geef voor assemblynaam een unieke id op voor uw pakket. Als u probeert een pakket te publiceren met een naam die al bestaat, ziet u een fout.

   Belangrijk

   U moet het pakket een id geven die uniek is in nuget.org of welke host u ook gebruikt. Anders treedt er een fout op. Voor deze quickstart raden we u aan voorbeeld of test op te nemen in de naam, omdat het pakket openbaar zichtbaar is in de publicatiestap.

3. Selecteer Assembly-informatie, waarin een dialoogvenster wordt weergegeven waarin u andere eigenschappen kunt invoeren die in het manifest worden ingevoerd (zie Vervangingstokens). De meest gebruikte velden zijn Titel, Beschrijving, Bedrijf, Copyright en Assembly-versie. Omdat deze eigenschappen worden weergegeven met uw pakket op een host zoals nuget.org nadat u het hebt gepubliceerd, moet u ervoor zorgen dat ze volledig beschrijvend zijn.

   

4. (Optioneel) Als u de eigenschappen rechtstreeks wilt bekijken en bewerken, opent u het bestand Properties/AssemblyInfo.cs in de project door Project>Bewerken Project Bestand te selecteren.

5. Nadat u deze eigenschappen hebt ingesteld, stel de configuratie van de Active solution configuration in Build>Configuration Manager in op Release en bouw het project opnieuw om de bijgewerkte DLL te genereren.

Het oorspronkelijke manifest genereren

Nadat u de projecteigenschappen hebt ingesteld en het DLL-bestand hebt gemaakt, kunt u nu een oorspronkelijk .nuspec-bestand van het project genereren. Deze stap bevat de relevante vervangingstokens om informatie uit het projectbestand te halen.

Voer nuget spec slechts één keer uit om het oorspronkelijke manifest te genereren. Als u het pakket bijwerkt, wijzigt u waarden in uw project of bewerkt u het manifest rechtstreeks:

1. Open uw project in Solution Explorer door een opdrachtprompt te selecteren door Tools>Opdrachtregel>Ontwikkelingsopdrachtprompt te selecteren.

   De opdrachtprompt wordt geopend in de projectmap waarin het AppLogger.csproj bestand zich bevindt.

2. Voer de volgende opdracht uit: nuget spec AppLogger.csproj.

   NuGet maakt een manifest dat overeenkomt met de naam van het project, in dit geval AppLogger.nuspec. Het bevat ook plaatstokens voor vervanging in het manifest.

3. Open AppLogger.nuspec in een teksteditor om de inhoud ervan te onderzoeken, die vergelijkbaar is met de volgende code:

   <?xml version="1.0"?>
   <package >
     <metadata>
       <id>Package</id>
       <version>1.0.0</version>
       <authors>Your username</authors>
       <owners>Your username</owners>
       <license type="expression">MIT</license>
       <!-- <icon>icon.png</icon> -->
       <projectUrl>http://PROJECT_URL_HERE_OR_DELETE_THIS_LINE</projectUrl>
       <requireLicenseAcceptance>false</requireLicenseAcceptance>
       <description>Package description</description>
       <releaseNotes>Summary of changes made in this release of the package.</releaseNotes>
       <copyright>Copyright 2022</copyright>
       <tags>Tag1 Tag2</tags>
     </metadata>
   </package>
   

Het manifest bewerken

1. Bewerk de volgende eigenschappen voordat u doorgaat. Als u anders probeert een NuGet-pakket te maken met de standaardwaarden in uw .nuspec bestand, treedt er een fout op. Zie Optionele metagegevenselementen voor meer informatie over deze eigenschappen:

   • licenseUrl
   • projectUrl
   • releaseNotes
   • etiketten

2. Voor pakketten die zijn gebouwd voor openbaar gebruik, moet u speciale aandacht besteden aan de eigenschap Tags , omdat tags anderen helpen uw pakket te vinden en te begrijpen wat het doet.

3. U kunt op dit moment ook andere elementen toevoegen aan het manifest, zoals beschreven in de verwijzing naar het nuspec-bestand.

4. Sla het bestand op voordat u doorgaat.

Voer de opdracht Pack uit

1. Open uw project in Solution Explorer door een opdrachtprompt te selecteren door Tools>Opdrachtregel>Ontwikkelingsopdrachtprompt te selecteren.

   De opdrachtprompt wordt geopend in de projectmap.

2. Voer de volgende opdracht uit: nuget pack.

   NuGet genereert een .nupkg-bestand in de vorm van identifier.version.nupkg in de huidige map.

Het pakket publiceren

Nadat u een .nupkg-bestand hebt gemaakt, publiceert u het naar nuget.org met behulp van de NuGet CLI met een API-sleutel die is verkregen uit nuget.org. Voor nuget.org moet u 4.1.0 of hoger gebruiken nuget.exe .

Als u uw pakket wilt testen en valideren voordat u het publiceert in een openbare galerie, kunt u het uploaden naar een testomgeving, zoals int.nugettest.org in plaats van nuget.org. Houd er rekening mee dat pakketten die zijn geüpload naar int.nugettest.org mogelijk niet behouden blijven.

Uw API-sleutel verkrijgen

1. Meld u aan bij uw nuget.org-account of maak een account als u er nog geen hebt.

2. Selecteer uw gebruikersnaam in de rechterbovenhoek en selecteer vervolgens API-sleutels.

3. Selecteer Maken en voer een naam in voor uw sleutel.

4. Selecteer onder Bereiken selecteren, Push.

5. Voer onder Pakketten selecteren voor Glob-patroon een sterretje (*) in.

6. Klik op Creëren.

7. Selecteer Kopiëren om de nieuwe sleutel te kopiëren.

   

Scoping biedt een manier om afzonderlijke API-sleutels te maken voor verschillende doeleinden. Elke sleutel heeft een verloopperiode, en u kunt de sleutel beperken tot specifieke pakketten of glob-patronen. U kunt ook elke sleutel opgeven voor specifieke bewerkingen: nieuwe pakketten en pakketversies pushen, alleen nieuwe pakketversies pushen of de lijst opheffen.

Door middel van scoping kunt u API-sleutels maken voor verschillende personen die pakketten voor uw organisatie beheren, zodat ze alleen de machtigingen hebben die ze nodig hebben.

Zie voor meer informatie Gescope API-sleutels.

Publiceren met de NuGet CLI

Het gebruik van de NuGet CLI (nuget.exe) is een alternatief voor het gebruik van de .NET CLI:

1. Open een opdrachtprompt en ga naar de map met het .nupkg-bestand .

2. Voer de volgende opdracht uit. Vervang <de bestandsnaam van het pakket> door de bestandsnaam van uw pakket en vervang <de api-sleutelwaarde> door uw API-sleutel. De bestandsnaam van het pakket is een samenvoeging van uw pakket-id en versienummer met de extensie .nupkg . Bijvoorbeeld AppLogger.1.0.0.nupkg:

   nuget push <package filename> <api key value> -Source https://api.nuget.org/v3/index.json
   

   Het resultaat van het publicatieproces wordt als volgt weergegeven:

   Pushing <package filename> to 'https://www.nuget.org/api/v2/package'...
       PUT https://www.nuget.org/api/v2/package/
       Created https://www.nuget.org/api/v2/package/ 6829ms
   Your package was pushed.
   

Zie nuget push voor meer informatie.

Publicatiefouten

Wanneer u de push opdracht uitvoert, treedt er soms een fout op. Er kan bijvoorbeeld een fout optreden in de volgende situaties:

• Uw API-sleutel is ongeldig of verlopen.
• U probeert een pakket te publiceren met een id die al bestaat op de host.
• U kunt wijzigingen aanbrengen in een gepubliceerd pakket, maar vergeet het versienummer bij te werken voordat u het opnieuw probeert te publiceren.

Het foutbericht geeft doorgaans de bron van het probleem aan.

Stel dat de id Contoso.App.Logger.Test bestaat op nuget.org. Als u probeert een pakket met die id te publiceren, krijgt u de volgende fout:

Response status code does not indicate success: 403 (The specified API key is invalid, has expired, or does not have permission to access the specified package.).

Als u deze situatie wilt oplossen, controleert u het bereik, de vervaldatum en de waarde van uw API-sleutel. Als de sleutel geldig is, geeft de fout aan dat de pakket-id al bestaat op de host. U kunt het probleem oplossen door de pakket-id te wijzigen in uniek, het project opnieuw te bouwen, het .nupkg-bestand opnieuw te maken en de opdracht opnieuw uit te push voeren.

Het gepubliceerde pakket beheren

Wanneer uw pakket is gepubliceerd, ontvangt u een bevestigingsmail. Als u het gepubliceerde pakket wilt zien, gaat u naar nuget.org, selecteert u uw gebruikersnaam in de rechterbovenhoek en selecteert u Vervolgens Pakketten beheren.

Nu uw NuGet-pakket is gepubliceerd op nuget.org, kunnen andere ontwikkelaars het in hun projecten gebruiken.

Als u een pakket maakt dat niet nuttig is (zoals dit voorbeeldpakket uit een lege klassebibliotheek), of als u niet wilt dat het pakket zichtbaar is, kunt u het pakket opheffen om het te verbergen in zoekresultaten:

1. Nadat het pakket wordt weergegeven onder Gepubliceerde pakketten op de pagina Pakketten beheren , selecteert u het potloodpictogram naast de pakketvermelding.

   

2. Op de volgende pagina selecteert u Vermelding, schakelt u het selectievakje Lijst in zoekresultaten uit en selecteert u Opslaan.

   

Het pakket wordt nu weergegeven onder Niet-vermelde pakketten in Pakketten beheren en wordt niet meer weergegeven in zoekresultaten.

Volgende stappen 

Gefeliciteerd met het maken van een NuGet-pakket met behulp van het Visual Studio .NET Framework. Ga naar het volgende artikel voor meer informatie over het maken van een NuGet-pakket met de NuGet CLI.

Zie de volgende artikelen voor meer informatie die NuGet te bieden heeft:

• Een pakket publiceren
• Een prerelease-pakket bouwen
• Ondersteuning voor meerdere doelframeworks
• Pakketversiebeheer
• Een gelokaliseerd pakket maken