Snabbstart: Skapa och publicera ett paket med Visual Studio (.NET Framework, Windows)

Med Microsoft Visual Studio kan du skapa ett NuGet-paket från ett .NET Framework-klassbibliotek och sedan publicera det till nuget.org med hjälp av NuGet CLI-verktyget.

Snabbstarten är endast avsedd för Windows användare. Om du använder Visual Studio för Mac kan du istället se dotnet CLI-verktyg.

Förutsättningar

• Installera Visual Studio 2022 för Windows med valfri . NET-relaterad arbetsbelastning.

  Du kan installera 2022 Community Edition kostnadsfritt från visualstudio.microsoft.com eller använda Professional- eller Enterprise-utgåvan.

  Visual Studio 2017 och senare innehåller automatiskt NuGet-funktioner när en .NET arbetsbelastning installeras.

• Registrera dig för ett kostnadsfritt konto på nuget.org om du inte redan har ett konto. Du måste registrera och bekräfta kontot innan du kan ladda upp ett NuGet-paket.

• Installera NuGet CLI genom att ladda ned det från nuget.org. Lägg till nuget.exe-filen i en lämplig mapp och lägg till den mappen i path-miljövariabeln.

Skapa ett klassbiblioteksprojekt

Följ dessa steg för att skapa ett klassbiblioteksprojekt:

1. I Visual Studio väljer du File>Ny>Projekt.

2. I fönstret Skapa ett nytt projekt väljer du C#, Windows och Library i listrutorna.

3. I den resulterande listan över projektmallar väljer du Class Library (.NET Framework) och väljer sedan Nästa.

4. I fönstret Konfigurera din nya project anger du AppLogger för namnet Project och väljer sedan Create.

5. För att säkerställa att projektet har skapats korrekt väljer du Skapa>bygglösning. DLL:en finns i mappen Felsökning (eller Släpp om du skapar den konfigurationen i stället).

6. (Valfritt) För den här snabbstarten behöver du inte skriva någon ytterligare kod för NuGet-paketet eftersom mallklassbiblioteket räcker för att skapa ett paket. Men om du vill ha en funktionskod för det här exempelpaketet inkluderar du följande kod:

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

   I ett verkligt NuGet-paket skulle du förmodligen implementera många användbara funktioner som andra kan skapa program med. Du kan också ange målramverken. Ett exempel finns i UWP.

Konfigurera projektegenskaper för paketet

Ett NuGet-paket innehåller ett manifest (en .nuspec fil) som innehåller relevanta metadata, till exempel paketidentifierare, versionsnummer, beskrivning med mera. Vissa av dessa metadata kan hämtas direkt från projektegenskaperna, vilket undviker att behöva uppdatera dem separat i både projektet och manifestet. Följande steg beskriver hur du anger tillämpliga egenskaper:

1. Välj Project > Properties och välj sedan fliken Application.

2. För Sammansättningsnamn ger du ditt paket en unik identifierare. Om du försöker publicera ett paket med ett namn som redan finns visas ett fel.

   Important

   Du måste ge paketet en identifierare som är unik för nuget.org eller vilken värd du använder. Annars uppstår ett fel. För den här snabbstarten rekommenderar vi att du inkluderar Exempel eller Test i namnet eftersom publiceringssteget gör paketet offentligt synligt.

3. Välj Sammansättningsinformation, som visar en dialogruta där du kan ange andra egenskaper som ingår i manifestet (se Ersättningstoken). De vanligaste fälten är Title, Description, Company, Copyright och Assembly version. Eftersom de här egenskaperna visas med ditt paket på en värd som nuget.org när du har publicerat det kontrollerar du att de är helt beskrivande.

   

4. (Valfritt) Om du vill se och redigera egenskaperna direkt öppnar du filen Properties/AssemblyInfo.cs i project genom att välja Project>Edit Project File.

5. När du har angett de här egenskaperna, ange den aktiva lösningskonfigurationen Active i Build>Configuration Manager till Release och bygg om projektet för att skapa den uppdaterade DLL:en.

Generera det första manifestet

När du har angett projektegenskaperna och skapat DLL:n kan du nu generera en första .nuspec-fil från projektet. Det här steget innehåller relevanta ersättningstoken för att hämta information från projektfilen.

Kör nuget spec bara en gång för att generera det första manifestet. Om du uppdaterar paketet ändrar du antingen värden i projektet eller redigerar manifestet direkt:

1. Med projektet öppet i Solution Explorer, öppna en kommandotolk genom att välja Tools>Command Line>Developer Command Prompt.

   Kommandotolken öppnas i projektkatalogen AppLogger.csproj där filen finns.

2. Kör följande kommando: nuget spec AppLogger.csproj.

   NuGet skapar ett manifest som matchar namnet på projektet, i det här fallet AppLogger.nuspec. Det innehåller även utbytestoken i manifestet.

3. Öppna AppLogger.nuspec i en textredigerare för att undersöka innehållet, vilket liknar följande kod:

   <?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>
   

Redigera manifestet

1. Redigera följande egenskaper innan du fortsätter. Annars uppstår ett fel om du försöker skapa ett NuGet-paket med standardvärdena i .nuspec filen. Information om dessa egenskaper finns i Valfria metadataelement:

   • licenseUrl
   • projectUrl
   • releaseNotes
   • tags

2. För paket som skapats för offentlig förbrukning bör du vara särskilt uppmärksam på egenskapen Taggar , eftersom taggar hjälper andra att hitta ditt paket och förstå vad det gör.

3. Du kan också lägga till andra element i manifestet just nu, enligt beskrivningen i .nuspec-filreferensen.

4. Spara filen innan du fortsätter.

Kör packkommandot

1. Med projektet öppet i Solution Explorer, öppna en kommandotolk genom att välja Tools>Command Line>Developer Command Prompt.

   Kommandotolken öppnas i projektkatalogen.

2. Kör följande kommando: nuget pack.

   NuGet genererar en .nupkg-fil i form av identifier.version.nupkg i den aktuella mappen.

Publicera paketet

När du har skapat en .nupkg-fil publicerar du den till nuget.org med hjälp av NuGet CLI med en API-nyckel som hämtats från nuget.org. För nuget.org måste du använda nuget.exe 4.1.0 eller senare.

Om du vill testa och validera paketet innan du publicerar det i ett offentligt galleri kan du ladda upp det till en testmiljö som int.nugettest.org i stället för nuget.org. Observera att paket som laddats upp till int.nugettest.org kanske inte bevaras.

Hämta din API-nyckel

1. Logga in på ditt nuget.org konto eller skapa ett konto om du inte redan har ett.

2. I det övre högra hörnet väljer du ditt användarnamn och sedan API-nycklar.

3. Välj Skapa och ange sedan ett namn för nyckeln.

4. Under Välj omfång väljer du Push.

5. Under Välj paket för Glob Pattern anger du en asterisk (*).

6. Välj Skapa.

7. Välj Kopiera för att kopiera den nya nyckeln.

   

Scope är ett sätt att skapa separata API-nycklar för olika syften. Varje nyckel har en tidsram för förfallotid och du kan omfångsbegränsa nyckeln till specifika paket eller globmönster. Du kan också omfångsbegränsa varje nyckel till specifika åtgärder: Push-överföra nya paket och paketversioner, push-överföra endast nya paketversioner eller ta bort listan.

Genom omfång kan du skapa API-nycklar för olika personer som hanterar paket för din organisation så att de bara har de behörigheter de behöver.

Mer information finns i Omfångs-API-nycklar.

Publicera med NuGet CLI

Att använda NuGet CLI (nuget.exe) är ett alternativ till att använda .NET CLI:

1. Öppna en kommandotolk och ändra till mappen som innehåller .nupkg-filen .

2. Kör följande kommando. Ersätt <paketfilnamnet> med paketets filnamn och ersätt <api-nyckelvärdet> med DIN API-nyckel. Paketfilnamnet är en sammanlänkning av ditt paket-ID och versionsnummer med filnamnstillägget .nupkg . Till exempel AppLogger.1.0.0.nupkg:

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

   Resultatet av publiceringsprocessen visas på följande sätt:

   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.
   

Mer information finns i nuget push.

Publicera fel

När du kör push kommandot uppstår ibland ett fel. Du kan till exempel få ett fel i följande situationer:

• DIN API-nyckel är ogiltig eller har upphört att gälla.
• Du försöker ladda upp ett paket som har en identifierare som redan finns på värdtjänsten.
• Du gör ändringar i ett publicerat paket, men du glömmer att uppdatera versionsnumret innan du försöker publicera det igen.

Felmeddelandet anger vanligtvis orsaken till problemet.

Anta till exempel att identifieraren Contoso.App.Logger.Test finns på nuget.org. Om du försöker publicera ett paket med identifieraren får du följande fel:

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.).

Om du vill hantera den här situationen kontrollerar du omfånget, förfallodatumet och värdet för din API-nyckel. Om nyckeln är giltig anger felet att paketidentifieraren redan finns på värden. Du kan lösa problemet genom att ändra paketidentifieraren så att den är unik, återskapa projektet, återskapa .nupkg-filen och försöka med kommandot igen push .

Hantera det publicerade paketet

När paketet har publicerats får du ett e-postmeddelande med bekräftelse. Om du vill se det publicerade paketet går du till nuget.org, väljer ditt användarnamn i det övre högra hörnet och väljer sedan Hantera paket.

Nu när NuGet-paketet har publicerats på nuget.org kan andra utvecklare använda det i sina projekt.

Om du skapar ett paket som inte är användbart (till exempel det här exempelpaketet från ett tomt klassbibliotek) eller om du inte vill att paketet ska visas kan du avlista paketet för att dölja det från sökresultat:

1. När paketet visas under Publicerade paket på sidan Hantera paket väljer du pennikonen bredvid paketlistan.

   

2. På nästa sida väljer du Lista, avmarkerar kryssrutan Lista i sökresultat och väljer sedan Spara.

   

Paketet visas nu under Ej listade paket i Hantera paket och visas inte längre i sökresultat.

Nästa steg

Grattis till att du har skapat ett NuGet-paket med hjälp av Visual Studio .NET Framework. Gå vidare till nästa artikel för att lära dig hur du skapar ett NuGet-paket med NuGet CLI.

Mer information om vad NuGet har att erbjuda finns i följande artiklar:

• Publicera ett paket
• Skapa ett förhandsversionspaket
• Stöd för flera målramverk
• Paketversionshantering
• Skapa ett lokaliserat paket