Sdílet prostřednictvím

Vytvoření balíčku pomocí rozhraní příkazového řádku nuget.exe

Bez ohledu na to, co váš balíček dělá nebo jaký kód obsahuje, použijete některý z nástrojů nuget.exe rozhraní příkazového řádku nebo dotnet.exek zabalení této funkce do komponenty, se kterou se dá sdílet a používat libovolný počet dalších vývojářů. Pokud chcete nainstalovat nástroje rozhraní příkazového řádku NuGet, přečtěte si téma Instalace klientských nástrojů NuGet. Všimněte si, že Visual Studio automaticky neobsahuje nástroj rozhraní příkazového řádku.

Technicky vzato je balíček NuGet jen soubor ZIP, který byl přejmenován s .nupkg příponou a jehož obsah odpovídá určitým konvencím. Toto téma popisuje podrobný proces vytvoření balíčku, který splňuje tyto konvence.

Balení začíná zkompilovaným kódem (sestaveními), symboly a/nebo jinými soubory, které chcete doručit jako balíček (viz Přehled a pracovní postup). Tento proces je nezávislý na kompilaci nebo jiném generování souborů, které do balíčku přecházejí, i když můžete načíst informace v souboru projektu, aby se kompilovaná sestavení a balíčky synchronizovaly.

Důležité

Toto téma se týká projektů jiných než SDK, obvykle jiných projektů než projektů .NET Core a .NET Standard pomocí sady Visual Studio 2017 a vyšších verzí a NuGetu 4.0 nebo novější.

Rozhodněte, která sestavení zabalit

Většina balíčků pro obecné účely obsahuje jedno nebo více sestavení, která můžou používat jiní vývojáři ve svých vlastních projektech.

  • Obecně je nejlepší mít jedno sestavení na balíček NuGet za předpokladu, že každé sestavení je nezávisle užitečné. Pokud máte například Utilities.dll, který závisí na Parser.dll a Parser.dll je užitečný samostatně, vytvořte pro každý z nich jeden balíček. To umožňuje vývojářům používat Parser.dll nezávisle na Utilities.dll.

  • Pokud se vaše knihovna skládá z více sestavení, která nejsou nezávislá, je v pořádku je zkombinovat do jednoho balíčku. V předchozím příkladu, pokud Parser.dll obsahuje kód, který používá pouze Utilities.dll, je v pořádku zachovat Parser.dll ve stejném balíčku.

  • Podobně pokud Utilities.dll závisí na Utilities.resources.dll, kde znovu druhý není užitečný samo o sobě, pak umístěte oba do stejného balíčku.

Prostředky jsou ve skutečnosti zvláštní případ. Když je balíček nainstalován do projektu, NuGet automaticky přidá odkazy na sestavení do knihoven DLL balíčku, s výjimkou těch, které jsou pojmenovány .resources.dll , protože se předpokládá, že jsou lokalizovaná satelitní sestavení (viz Vytváření lokalizovaných balíčků). Z tohoto důvodu nepoužívejte .resources.dll soubory, které jinak obsahují základní kód balíčku.

Pokud vaše knihovna obsahuje COM interop sestavení, postupujte podle dalších pokynů v tématu Vytváření balíčků s COM interop sestaveními.

Role a struktura souboru .nuspec

Jakmile víte, jaké soubory chcete zabalit, dalším krokem je vytvoření manifestu balíčku v .nuspec souboru XML.

Manifest:

  1. Popisuje obsah balíčku a je součástí balíčku.
  2. Řídí vytvoření balíčku a dává NuGet pokyn, jak balíček nainstalovat do projektu. Manifest například identifikuje další závislosti balíčků tak, aby NuGet mohl tyto závislosti nainstalovat také při instalaci hlavního balíčku.
  3. Obsahuje požadované i volitelné vlastnosti, jak je popsáno níže. Přesné podrobnosti, včetně dalších vlastností, které zde nejsou uvedeny, naleznete v odkazu .nuspec.

Požadované vlastnosti:

  • Identifikátor balíčku, který musí být jedinečný v galerii, která je hostitelem balíčku.
  • Konkrétní číslo verze ve formátu Major.Minor.Patch[-Suffix] kde -Suffix identifikuje předběžné verze
  • Název balíčku, který by se měl zobrazovat na hostiteli (například nuget.org)
  • Informace o autorovi a vlastníkovi
  • Dlouhý popis balíčku.

Běžné volitelné vlastnosti:

Následuje typický (ale fiktivní) .nuspec soubor s komentáři popisujícími vlastnosti:

<?xml version="1.0"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
    <metadata>
        <!-- Identifier that must be unique within the hosting gallery -->
        <id>Contoso.Utility.UsefulStuff</id>

        <!-- Package version number that is used when resolving dependencies -->
        <version>1.8.3</version>

        <!-- Authors contain text that appears directly on the gallery -->
        <authors>Dejana Tesic, Rajeev Dey</authors>

        <!-- 
            Owners are typically nuget.org identities that allow gallery
            users to easily find other packages by the same owners.  
        -->
        <owners>dejanatc, rjdey</owners>
        
         <!-- Project URL provides a link for the gallery -->
        <projectUrl>http://github.com/contoso/UsefulStuff</projectUrl>

         <!-- License information is displayed on the gallery -->
        <license type="expression">Apache-2.0</license>
        

        <!-- Icon is used in Visual Studio's package manager UI -->
        <icon>icon.png</icon>

        <!-- 
            If true, this value prompts the user to accept the license when
            installing the package. 
        -->
        <requireLicenseAcceptance>false</requireLicenseAcceptance>

        <!-- Any details about this particular release -->
        <releaseNotes>Bug fixes and performance improvements</releaseNotes>

        <!-- 
            The description can be used in package manager UI. Note that the
            nuget.org gallery uses information you add in the portal. 
        -->
        <description>Core utility functions for web applications</description>

        <!-- Copyright information -->
        <copyright>Copyright ©2016 Contoso Corporation</copyright>

        <!-- Tags appear in the gallery and can be used for tag searches -->
        <tags>web utility http json url parsing</tags>

        <!-- Dependencies are automatically installed when the package is installed -->
        <dependencies>
            <dependency id="Newtonsoft.Json" version="9.0" />
        </dependencies>
    </metadata>

    <!-- A readme.txt to display when the package is installed -->
    <files>
        <file src="readme.txt" target="" />
        <file src="icon.png" target="" />
    </files>
</package>

Podrobnosti o deklarování závislostí a zadávání čísel verzí najdete v tématu packages.config a správa verzí balíčků. Je také možné zpřístupnit prostředky z balíčku přímo pomocí atributů include a exclude na elementu dependency. Viz referenční informace k souboru .nuspec – závislosti.

Vzhledem k tomu, že manifest je součástí balíčku vytvořeného z něj, můžete najít libovolný počet dalších příkladů prozkoumáním existujících balíčků. Dobrým zdrojem je složka global-packages ve vašem počítači, jejíž umístění vrátí následující příkaz:

nuget locals -list global-packages

Přejděte do libovolné složky package\version , zkopírujte .nupkg soubor do .zip souboru, otevřete ho .zip a prozkoumejte ho .nuspec .

Poznámka:

Při vytváření .nuspec projektu sady Visual Studio obsahuje manifest tokeny, které jsou při sestavení balíčku nahrazeny informacemi z projektu. Viz Vytvoření souboru .nuspec z projektu sady Visual Studio.

Vytvoření souboru .nuspec

Vytvoření kompletního manifestu obvykle začíná základním .nuspec souborem vygenerovaným některou z následujících metod:

Soubor pak upravíte ručně tak, aby popsal přesný obsah, který chcete mít v posledním balíčku.

Důležité

Vygenerované .nuspec soubory obsahují zástupné symboly, které je nutné před vytvořením balíčku pomocí nuget pack příkazu upravit. Tento příkaz selže, pokud .nuspec obsahuje nějaké zástupné symboly.

Z pracovního adresáře založeného na konvencích

Vzhledem k tomu, že balíček NuGet je jen soubor ZIP, který je přejmenován s .nupkg příponou, je často nejjednodušší vytvořit strukturu složek, kterou chcete mít v místním systému souborů, a pak soubor vytvořit .nuspec přímo z této struktury. Příkaz nuget pack pak automaticky přidá všechny soubory v této struktuře složek (s výjimkou všech složek, které začínají ., což vám umožní zachovat soukromé soubory ve stejné struktuře).

Výhodou tohoto přístupu je, že v manifestu nemusíte zadávat soubory, které chcete zahrnout do balíčku (jak je vysvětleno dále v tomto tématu). Proces sestavení může jednoduše vytvořit přesnou strukturu složek, která přejde do balíčku, a můžete snadno zahrnout další soubory, které nemusí být součástí projektu, jinak:

  • Obsah a zdrojový kód, který by se měl vložit do cílového projektu.
  • Skripty PowerShellu
  • Transformace na existující soubory konfigurace a zdrojového kódu v projektu

Konvence pojmenování složek jsou následující:

Složka Description Akce při instalaci balíčku
(root) Umístění pro readme.txt Visual Studio při instalaci balíčku zobrazí v kořenovém adresáři balíčku soubor readme.txt.
lib/{tfm} Soubory sestavení (.dll), dokumentace (.xml) a symbolu (.pdb) pro daný moniker cílové architektury (TFM) Sestavení se přidávají jako odkazy pro kompilaci i běhové prostředí, .xml a .pdb jsou zkopírovány do složek projektu. Viz Podpora více cílových rámců pro vytvoření podsložek specifických pro jednotlivé cílové rámce.
ref/{tfm} Soubory sestavení (.dll) a symbolů (.pdb) pro daný Target Framework Moniker (TFM) Sestavení jsou přidána jako odkazy pouze pro čas kompilace; Takže do složky bin projektu se nic nekopíruje.
moduly runtime Sestavení specifické pro architekturu (.dll), symbol (.pdb) a soubory nativních prostředků (.pri) Sestavení jsou přidána jako odkazy pouze pro modul runtime; ostatní soubory se zkopírují do složek projektu. Vždy by mělo existovat odpovídající sestavení specifické pro TFM AnyCPU ve /ref/{tfm} složce, aby bylo možné poskytnout odpovídající sestavení času kompilace. Viz Podpora více cílových architektur.
obsah Libovolné soubory Obsah se zkopíruje do kořenového adresáře projektu. Složku obsahu si můžete představit jako kořen cílové aplikace, která balíček nakonec využívá. Pokud chcete, aby balíček přidal obrázek do složky /images aplikace, umístěte ho do složky obsahu/obrázků balíčku.
build (3.x+) MSBuild .targets a .props soubory Automaticky se vloží do projektu.
buildMultiTargeting (4.0+) MSBuild .targets a .props soubory pro cílení na různé frameworky Automaticky se vloží do projektu.
buildTransitive (5.0+) MSBuild .targets a .props soubory, které se přenášejí transitivně do jakéhokoliv přijímajícího projektu. Podívejte se na stránku funkce . Automaticky se vloží do projektu.
nářadí Skripty a programy PowerShellu přístupné z konzoly Správce balíčků Složka tools je přidána do proměnné prostředí PATH pouze pro konzolu Správce balíčků (zejména ne do proměnné PATH nastavené pro MSBuild při sestavování projektu).

Vzhledem k tomu, že struktura složek může obsahovat libovolný počet sestavení pro libovolný počet cílových architektur, je tato metoda nutná při vytváření balíčků, které podporují více architektur.

V každém případě po vytvoření požadované struktury složek spusťte v této složce .nuspec následující příkaz:

nuget spec

Vygenerovaný .nuspec soubor opět neobsahuje žádné explicitní odkazy na soubory ve struktuře složek. NuGet automaticky zahrne všechny soubory při vytvoření balíčku. Stále ale potřebujete upravit zástupné hodnoty v jiných částech manifestu.

Ze sestavovací knihovny DLL

V jednoduchém případě vytvoření balíčku ze sestavení můžete vygenerovat .nuspec soubor z metadat v sestavení pomocí následujícího příkazu:

nuget spec <assembly-name>.dll

Použití tohoto formuláře nahrazuje několik zástupných symbolů v manifestu konkrétními hodnotami ze sestavení. Například, vlastnost <id> je nastavena na název sestavení a <version> je nastavena na verzi sestavení. Jiné vlastnosti manifestu však nemají odpovídající hodnoty v sestavení, a proto stále obsahují zástupné symboly.

Z projektu sady Visual Studio

Vytvoření .nuspec ze souboru .csproj nebo .vbproj je výhodné, protože ostatní balíčky nainstalované do tohoto projektu jsou automaticky považovány za závislosti. Jednoduše použijte následující příkaz ve stejné složce jako soubor projektu:

# Use in a folder containing a project file <project-name>.csproj or <project-name>.vbproj
nuget spec

Výsledný <project-name>.nuspec soubor obsahuje tokeny, které jsou v době balení nahrazeny hodnotami z projektu, včetně odkazů na všechny ostatní balíčky, které již byly nainstalovány.

Pokud máte závislosti balíčků k zahrnutí do .nuspec, místo toho použijte nuget pack, a získejte soubor .nuspec z vygenerovaného souboru .nupkg. Použijte například následující příkaz.

# Use in a folder containing a project file <project-name>.csproj or <project-name>.vbproj
nuget pack myproject.csproj

Token je odděleny $ symboly na obou stranách atributu projektu. Například <id> hodnota v manifestu vygenerovaná tímto způsobem se obvykle zobrazuje takto:

<id>$id$</id>

Tento token se v době balení nahradí AssemblyName hodnotou souboru projektu. Přesné mapování hodnot projektu na .nuspec tokeny najdete v referenčních informacích k náhradním tokenům.

Tokeny vás zbavují nutnosti aktualizovat klíčové hodnoty, jako je číslo verze, při aktualizaci projektu pomocí .nuspec. (Tokeny můžete kdykoli nahradit literálními hodnotami).

Všimněte si, že při práci s projektem Visual Studio je k dispozici několik dalších možností balíčkování, jak je uvedeno ve Spuštění příkazu nuget pack pro vygenerování souboru .nupkg.

Balíčky na úrovni řešení

Pouze NuGet 2.x Není k dispozici v NuGetu 3.0 nebo novějším.

NuGet 2.x podporoval koncept balíčku na úrovni řešení, který instaluje nástroje nebo další příkazy pro konzolu Správce balíčků (obsah tools složky), ale nepřidává odkazy, obsah ani sestavení přizpůsobení do žádných projektů v řešení. Tyto balíčky neobsahují žádné soubory v jejich přímých lib, content, nebo build složkách a žádná z jejich závislostí neobsahuje soubory v příslušných lib, content, nebo build složkách.

NuGet sleduje nainstalované balíčky na úrovni řešení v packages.config souboru ve .nuget složce, nikoli v souboru projektu packages.config .

Nový soubor s výchozími hodnotami

Následující příkaz vytvoří výchozí manifest se zástupnými symboly, což zajistí, že začnete se správnou strukturou souborů:

nuget spec [<package-name>]

Pokud vynecháte <název> balíčku, výsledný soubor je Package.nuspec. Pokud zadáte název, například Contoso.Utility.UsefulStuff, soubor je Contoso.Utility.UsefulStuff.nuspec.

Výsledná hodnota .nuspec obsahuje zástupné symboly pro hodnoty, jako je například projectUrl. Než ho použijete k vytvoření konečného .nupkg souboru, nezapomeňte ho upravit.

Zvolte jedinečný identifikátor balíčku a nastavte číslo verze.

Identifikátor balíčku (<id> element) a číslo verze (<version> element) jsou dvě nejdůležitější hodnoty v manifestu, protože jednoznačně identifikují přesný kód obsažený v balíčku.

Osvědčené postupy pro identifikátor balíčku:

  • Jedinečnost: Identifikátor musí být jedinečný v rámci nuget.org nebo jakékoli galerie, která balíček hostuje. Než se rozhodnete o identifikátoru, vyhledejte příslušnou galerii a zkontrolujte, jestli se název už používá. Aby nedocházelo ke konfliktům, dobrým vzorem je použít název vaší společnosti jako první část identifikátoru, například Contoso..
  • Názvy podobné oboru názvů: Postupujte podle vzoru podobného oborům názvů v .NET pomocí zápisu tečky místo pomlček. Použijte například Contoso.Utility.UsefulStuff místo Contoso-Utility-UsefulStuff nebo Contoso_Utility_UsefulStuff. Příjemci také zjistí, že identifikátor balíčku odpovídá oborům názvů použitým v kódu.
  • Ukázkové balíčky: Pokud vytvoříte balíček vzorového kódu, který ukazuje, jak použít jiný balíček, připojte .Sample jako příponu k identifikátoru, jako v Contoso.Utility.UsefulStuff.Sample. (Ukázkový balíček by samozřejmě měl závislost na druhém balíčku.) Při vytváření ukázkového balíčku použijte metodu pracovního adresáře založenou na konvenci popsanou výše. Ve složce content uspořádejte vzorový kód do složky nazvané \Samples\<identifier> jako ve \Samples\Contoso.Utility.UsefulStuff.Sample.

Osvědčené postupy pro verzi balíčku:

  • Obecně platí, že nastavte verzi balíčku tak, aby odpovídala knihovně, i když to není nezbytně nutné. Jedná se o jednoduchou záležitost, pokud omezíte balíček na jedno sestavení, jak je popsáno výše v rozhodování o sestaveních, která se mají zabalit. Obecně mějte na paměti, že NuGet se zabývá verzemi balíčků při řešení závislostí, nikoli verzemi sestavení.
  • Při použití nestandardního schématu verzí nezapomeňte zvážit pravidla správy verzí NuGet, jak je vysvětleno ve správě verzí balíčků.

Následující série krátkých blogových příspěvků je také užitečná pro pochopení správy verzí:

Přidání souboru readme a dalších souborů

Pokud chcete přímo zadat soubory, které se mají zahrnout do balíčku, použijte <files> uzel v .nuspec souboru, který následuje za značkou <metadata> :

<?xml version="1.0"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
    <metadata>
    <!-- ... -->
    </metadata>
    <files>
        <!-- Add a readme -->
        <file src="readme.txt" target="" />

        <!-- Add files from an arbitrary folder that's not necessarily in the project -->
        <file src="..\..\SomeRoot\**\*.*" target="" />
    </files>
</package>

Návod

Při použití přístupu k pracovnímu adresáři založenému na konvencích můžete umístit readme.txt do kořenového adresáře balíčku a do jiného content obsahu ve složce. V manifestu nejsou potřeba žádné <file> prvky.

Když zahrnete soubor s názvem readme.txt v kořenovém adresáři balíčku, Visual Studio zobrazí obsah tohoto souboru jako prostý text hned po instalaci balíčku. (Soubory Readme se nezobrazují pro balíčky nainstalované jako závislosti). Tady je příklad, jak se zobrazí soubor readme pro balíček HtmlAgilityPack:

Zobrazení souboru readme pro balíček NuGet při instalaci

Poznámka:

Pokud do souboru zahrnete prázdný <files> uzel .nuspec , NuGet neobsahuje žádný jiný obsah v balíčku kromě toho, co je ve lib složce.

Zahrnutí props a cíle MSBuild do balíčku

V některých případech můžete chtít přidat vlastní cíle sestavení nebo vlastnosti v projektech, které využívají váš balíček, například spuštění vlastního nástroje nebo procesu během sestavování. Další informace o rekvizitách a cílech MSBuild v balíčcích NuGet

Vytvořte <package_id>.targets nebo <package_id>.props (například Contoso.Utility.UsefulStuff.targets) ve složkách sestavení projektu.

Pak v .nuspec souboru nezapomeňte odkazovat na tyto soubory v <files> uzlu:

<?xml version="1.0"?>
<package >
    <metadata minClientVersion="2.5">
    <!-- ... -->
    </metadata>
    <files>
        <!-- Include everything in \build -->
        <file src="build\**" target="build" />

        <!-- Other files -->
        <!-- ... -->
    </files>
</package>

Když se balíčky přidají do projektu, NuGet automaticky zahrne tyto vlastnosti a cílové soubory.

Spuštěním balíčku NuGet vygenerujte soubor .nupkg.

Při použití sestavení nebo pracovního adresáře založeného na konvenci vytvořte balíček spuštěním nuget pack se .nuspec souborem a nahraďte <project-name> konkrétním názvem souboru:

nuget pack <project-name>.nuspec

Při použití projektu sady Visual Studio spusťte nuget pack s vaším souborem projektu, což automaticky načte soubor .nuspec a nahradí všechny tokeny díky hodnotám v souboru projektu.

nuget pack <project-name>.csproj

Poznámka:

Použití souboru projektu přímo je nezbytné pro nahrazení tokenu, protože projekt je zdrojem hodnot tokenu. K nahrazení tokenu nedojde, pokud použijete nuget pack s .nuspec souborem.

Ve všech případech vyloučí složky začínající tečkou, například .git nebo .hg.

NuGet označuje, jestli jsou v souboru .nuspec nějaké chyby, které je potřeba opravit, například zapomenutí na změnu zástupných hodnot v manifestu.

Po nuget pack úspěšném dokončení máte .nupkg soubor, který můžete publikovat do vhodné galerie, jak je popsáno v části Publikování balíčku.

Návod

Užitečný způsob, jak balíček po vytvoření prozkoumat, je otevřít ho v nástroji Průzkumník balíčků . Tím získáte grafické zobrazení obsahu balíčku a jeho manifestu. Výsledný .nupkg soubor můžete také přejmenovat na .zip soubor a prozkoumat jeho obsah přímo.

Další možnosti

Pomocí různých přepínačů nuget pack příkazového řádku můžete vyloučit soubory, přepsat číslo verze v manifestu a změnit výstupní složku mimo jiné. Úplný seznam najdete v referenčních informacích k příkazům balíčku.

Následující možnosti jsou některé společné s projekty sady Visual Studio:

  • Odkazované projekty: Pokud projekt odkazuje na jiné projekty, můžete odkazované projekty přidat jako součást balíčku nebo jako závislosti pomocí -IncludeReferencedProjects možnosti:

    nuget pack MyProject.csproj -IncludeReferencedProjects

    Tento proces zahrnutí je rekurzivní, takže pokud MyProject.csproj odkazuje na projekty B a C a tyto projekty odkazují na D, E a F, pak soubory z B, C, D, E a F jsou zahrnuty do balíčku.

    Pokud odkazovaný projekt obsahuje .nuspec vlastní soubor, nuGet přidá tento odkazovaný projekt jako závislost. Tento projekt je potřeba zabalit a publikovat samostatně.

  • Konfigurace sestavení: Ve výchozím nastavení používá NuGet výchozí sadu konfigurace sestavení v souboru projektu, obvykle Debug. Pokud chcete zabalit soubory z jiné konfigurace sestavení, například Release, použijte možnost -properties s konfigurací:

    nuget pack MyProject.csproj -properties Configuration=Release

  • Symboly: Chcete-li zahrnout symboly, které umožňují uživatelům procházet kód balíčku v ladicím programu, použijte možnost -Symbols.

    nuget pack MyProject.csproj -symbols

Instalace testovacího balíčku

Před publikováním balíčku obvykle chcete otestovat proces instalace balíčku do projektu. Testy zajišťují, aby všechny soubory nutně skončily na jejich správných místech v projektu.

Instalace můžete testovat ručně v sadě Visual Studio nebo na příkazovém řádku pomocí běžných kroků instalace balíčku.

Pro automatizované testování je základní proces následující:

  1. .nupkg Zkopírujte soubor do místní složky.
  2. Přidejte složku do zdrojů balíčků pomocí nuget sources add -name <name> -source <path> příkazu (viz zdroje NuGet). Všimněte si, že tento místní zdroj potřebujete nastavit pouze jednou na libovolném daném počítači.
  3. Nainstalujte balíček z daného zdroje pomocí nuget install <packageID> -source <name>, kde <name> odpovídá názvu vašeho zdroje, jak je nuget sources uvedeno. Zadáním zdroje zajistíte, že se balíček nainstaluje ze samotného zdroje.
  4. Zkontrolujte systém souborů a zkontrolujte, jestli jsou soubory správně nainstalované.

Další kroky

Jakmile vytvoříte balíček, což je .nupkg soubor, můžete ho publikovat do galerie podle svého výběru, jak je popsáno v tématu Publikování balíčku.

Můžete také chtít rozšířit možnosti balíčku nebo jinak podporovat další scénáře popsané v následujících tématech:

A konečně existují další typy balíčků, o které je potřeba vědět:

  • Last updated on