Odwołanie do pliku nuspec

  • Artykuł

.nuspec Plik jest manifestem XML zawierającym metadane pakietu. Ten manifest służy zarówno do kompilowania pakietu, jak i do dostarczania informacji konsumentom. Manifest jest zawsze dołączany do pakietu.

W tym temacie:

Zgodność typu projektu

  • nuget.exe pack Należy używać z .nuspec programem dla projektów w stylu innych niż SDK, które korzystają z programu packages.config.

  • Plik .nuspec nie jest wymagany do tworzenia pakietów dla projektów w stylu zestawu SDK (zazwyczaj projektów .NET Core i .NET Standard korzystających z atrybutu zestawu SDK). (Pamiętaj, że .nuspec element jest generowany podczas tworzenia pakietu).

    Jeśli tworzysz pakiet przy użyciu polecenia dotnet.exe pack lub msbuild pack target, zalecamy dołączenie wszystkich właściwości , które zazwyczaj znajdują się w .nuspec pliku w pliku projektu. Można jednak zamiast tego użyć pliku do spakowania przy użyciu polecenia dotnet.exe lub msbuild pack target..nuspec

  • W przypadku projektów migrowanych z packages.config do packageReference .nuspecplik nie jest wymagany do utworzenia pakietu. Zamiast tego użyj polecenia msbuild -t:pack.

Formularz ogólny i schemat

Bieżący nuspec.xsd plik schematu można znaleźć w repozytorium GitHub NuGet.

W tym schemacie .nuspec plik ma następującą ogólną formę:

<?xml version="1.0" encoding="utf-8"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
    <metadata>
        <!-- Required elements-->
        <id></id>
        <version></version>
        <description></description>
        <authors></authors>

        <!-- Optional elements -->
        <!-- ... -->
    </metadata>
    <!-- Optional 'files' node -->
</package>

Aby uzyskać wyraźną wizualną reprezentację schematu, otwórz plik schematu w programie Visual Studio w trybie projektowania i kliknij link Eksplorator schematu XML. Alternatywnie otwórz plik jako kod, kliknij prawym przyciskiem myszy w edytorze i wybierz polecenie Pokaż Eksplorator schematu XML. Tak czy inaczej można uzyskać widok podobny do poniższego (po rozwinięciu w większości):

Visual Studio Schema Explorer with nuspec.xsd open

Wszystkie nazwy elementów XML w pliku nuspec są uwzględniane wielkości liter, tak jak w przypadku kodu XML w ogóle. Na przykład użycie elementu <description> metadanych jest poprawne i <Description> nie jest poprawne. Prawidłowa wielkość liter dla każdej nazwy elementu jest udokumentowana poniżej.

Wymagane elementy metadanych

Mimo że poniższe elementy są minimalnymi wymaganiami dotyczącymi pakietu, należy rozważyć dodanie opcjonalnych elementów metadanych, aby poprawić ogólne środowisko, które deweloperzy mają z pakietem.

Te elementy muszą znajdować się w elemecie <metadata> .

identyfikator

Identyfikator pakietu bez uwzględniania wielkości liter, który musi być unikatowy w nuget.org lub w dowolnej galerii, w której znajduje się pakiet. Identyfikatory mogą nie zawierać spacji ani znaków, które nie są prawidłowe dla adresu URL, i zazwyczaj są zgodne z regułami przestrzeni nazw platformy .NET. Aby uzyskać wskazówki, zobacz Wybieranie unikatowego identyfikatora pakietu.

Podczas przekazywania pakietu do nuget.org id pole jest ograniczone do 128 znaków.

version

Wersja pakietu zgodna ze wzorcem major.minor.patch . Numery wersji mogą zawierać sufiks wersji wstępnej zgodnie z opisem w temacie Przechowywanie wersji pakietu.

Podczas przekazywania pakietu do nuget.org version pole jest ograniczone do 64 znaków.

opis

Opis pakietu dla wyświetlania interfejsu użytkownika.

Podczas przekazywania pakietu do nuget.org description pole jest ograniczone do 4000 znaków.

Autorów

Rozdzielona przecinkami lista autorów pakietów zgodna z nazwami profilów w nuget.org. Są one wyświetlane w galerii NuGet w nuget.org i są używane do krzyżowych pakietów przez tych samych autorów.

Podczas przekazywania pakietu do nuget.org authors pole jest ograniczone do 4000 znaków.

Opcjonalne elementy metadanych

Właścicieli

Ważne

właściciele są przestarzali. Zamiast tego użyj autorów.

Rozdzielona przecinkami lista twórców pakietów przy użyciu nazw profilów w nuget.org. Jest to często ta sama lista co w authorspliku i jest ignorowana podczas przekazywania pakietu do nuget.org. Zobacz Zarządzanie właścicielami pakietów w nuget.org.

projectUrl

Adres URL strony głównej pakietu, często wyświetlany w interfejsie użytkownika, a także nuget.org.

Podczas przekazywania pakietu do nuget.org projectUrl pole jest ograniczone do 4000 znaków.

licenseUrl

Ważne

licenseUrl jest przestarzały. Zamiast tego użyj licencji.

Adres URL licencji pakietu, często wyświetlany w interfejsach użytkownika, takich jak nuget.org.

Podczas przekazywania pakietu do nuget.org licenseUrl pole jest ograniczone do 4000 znaków.

license (licencja)

Obsługiwane w programie NuGet w wersji 4.9.0 lub nowszej

Wyrażenie licencji SPDX lub ścieżka do pliku licencji w pakiecie, często wyświetlane w interfejsach użytkownika, takich jak nuget.org. Jeśli licencjonujesz pakiet na podstawie wspólnej licencji, takiej jak MIT lub BSD-2-Clause, użyj skojarzonego identyfikatora licencji SPDX. Na przykład:

<license type="expression">MIT</license>

Uwaga

NuGet.org akceptuje tylko wyrażenia licencji zatwierdzone przez inicjatywę open source lub Free Software Foundation.

Jeśli pakiet jest licencjonowany na wiele typowych licencji, możesz określić licencję złożoną przy użyciu składni wyrażenia SPDX w wersji 2.0. Na przykład:

<license type="expression">BSD-2-Clause OR MIT</license>

Jeśli używasz licencji niestandardowej, która nie jest obsługiwana przez wyrażenia licencji, możesz spakować .txt plik lub .md z tekstem licencji. Na przykład:

<package>
  <metadata>
    ...
    <license type="file">LICENSE.txt</license>
    ...
  </metadata>
  <files>
    ...
    <file src="licenses\LICENSE.txt" target="" />
    ...
  </files>
</package>

W przypadku odpowiednika MSBuild zapoznaj się z dokumentem Pakowanie wyrażenia licencji lub pliku licencji.

Dokładna składnia wyrażeń licencji NuGet została opisana poniżej w abNF.

license-id            = <short form license identifier from https://spdx.org/spdx-specification-21-web-version#h.luq9dgcle9mo>

license-exception-id  = <short form license exception identifier from https://spdx.org/spdx-specification-21-web-version#h.ruv3yl8g6czd>

simple-expression = license-id / license-id”+”

compound-expression =  1*1(simple-expression /
                simple-expression "WITH" license-exception-id /
                compound-expression "AND" compound-expression /
                compound-expression "OR" compound-expression ) /                
                "(" compound-expression ")" )

license-expression =  1*1(simple-expression / compound-expression / UNLICENSED)

iconUrl

Ważne

iconUrl jest przestarzały. Zamiast tego użyj ikony.

Adres URL obrazu 128x128 z przezroczystym tłem do użycia jako ikona pakietu w wyświetlaczu interfejsu użytkownika. Upewnij się, że ten element zawiera bezpośredni adres URL obrazu, a nie adres URL strony internetowej zawierającej obraz. Aby na przykład użyć obrazu z usługi GitHub, użyj nieprzetworzonego adresu URL pliku, takiego jak username/repository/raw/<branch>/<logo.png>.><>https://github.com/<

Podczas przekazywania pakietu do nuget.org iconUrl pole jest ograniczone do 4000 znaków.

menu

Obsługiwane w pakietach NuGet 5.3.0 lub nowszych

Jest to ścieżka do pliku obrazu w pakiecie, często wyświetlana w interfejsach użytkownika, takich jak nuget.org jako ikona pakietu. Rozmiar pliku obrazu jest ograniczony do 1 MB. Obsługiwane formaty plików obejmują pliki JPEG i PNG. Zalecamy rozdzielczość obrazu 128x128.

Na przykład podczas tworzenia pakietu przy użyciu nuget.exe należy dodać następujące elementy do pakietu nuspec:

<package>
  <metadata>
    ...
    <icon>images\icon.png</icon>
    ...
  </metadata>
  <files>
    ...
    <file src="..\icon.png" target="images\" />
    ...
  </files>
</package>

Przykład nuspec ikona pakietu.

W przypadku odpowiednika MSBuild zapoznaj się z pozycją Pakowanie pliku obrazu ikony.

Napiwek

Aby zachować zgodność z poprzednimi wersjami z klientami i źródłami, które jeszcze nie obsługują iconprogramu , określ wartości i iconiconUrl. Program Visual Studio obsługuje icon pakiety pochodzące ze źródła opartego na folderach.

readme

Obsługiwane w programie NuGet 5.10.0 (wersja zapoznawcza 2 i nowsze)

Podczas pakowania pliku readme należy użyć readme elementu , aby określić ścieżkę pakietu względem katalogu głównego pakietu. Oprócz tego należy się upewnić, że plik znajduje się w pakiecie. Obsługiwane formaty plików obejmują tylko język Markdown (md).

Na przykład do pliku nuspec należy dodać następujące elementy, aby spakować plik readme z projektem:

<package>
  <metadata>
    ...
    <readme>docs\readme.md</readme>
    ...
  </metadata>
  <files>
    ...
    <file src="..\readme.md" target="docs\" />
    ...
  </files>
</package>

W przypadku odpowiednika MSBuild zapoznaj się z tematem Pakowanie pliku readme.

requireLicenseAcceptance

Wartość logiczna określająca, czy klient musi monitować użytkownika o zaakceptowanie licencji pakietu przed zainstalowaniem pakietu.

developmentDependency

(2.8+) Wartość logiczna określająca, czy pakiet jest oznaczony jako zależność tylko do programowania, która uniemożliwia dołączanie pakietu jako zależność w innych pakietach. W przypadku elementu PackageReference (NuGet 4.8 lub nowszego) ta flaga oznacza również, że wykluczy zasoby czasu kompilacji z kompilacji. Zobacz DevelopmentDependency support for PackageReference (Obsługa współzależności dla elementu PackageReference)

Podsumowanie

Ważne

summary jest przestarzały. Użycie w zamian parametru description.

Krótki opis pakietu dla wyświetlania interfejsu użytkownika. W przypadku pominięcia używana jest obcięta wersja description elementu .

Podczas przekazywania pakietu do nuget.org summary pole jest ograniczone do 4000 znaków.

releaseNotes

(1,5+) Opis zmian wprowadzonych w tej wersji pakietu, często używany w interfejsie użytkownika, takich jak karta Aktualizacje programu Visual Studio Menedżer pakietów zamiast opisu pakietu.

Podczas przekazywania pakietu do nuget.org releaseNotes pole jest ograniczone do 35 000 znaków.

(1,5+) Szczegóły praw autorskich dla pakietu.

Podczas przekazywania pakietu do nuget.org copyright pole jest ograniczone do 4000 znaków.

język

Identyfikator ustawień regionalnych pakietu. Zobacz Tworzenie zlokalizowanych pakietów.

tags

Rozdzielana spacjami lista tagów i słów kluczowych, które opisują pakiet i ułatwiają odnajdywanie pakietów za pośrednictwem wyszukiwania i filtrowania.

Podczas przekazywania pakietu do nuget.org tags pole jest ograniczone do 4000 znaków.

Sprawne

(3.3+) W przypadku wewnętrznego narzędzia NuGet użyj tylko.

repozytorium

Metadane repozytorium składające się z czterech atrybutów opcjonalnych: type iurl (4.0+)oraz commitbranch(4.6+). Te atrybuty umożliwiają mapowanie elementu .nupkg do repozytorium, które go skompiluje, z możliwością uzyskania tak szczegółowej, jak nazwa pojedynczej gałęzi i / lub zatwierdzenie skrótu SHA-1, który skompilował pakiet. Powinien to być publicznie dostępny adres URL, który może być wywoływany bezpośrednio przez oprogramowanie kontroli wersji. Nie powinna być stroną HTML, ponieważ jest przeznaczona dla komputera. Aby połączyć się ze stroną projektu, użyj projectUrl pola , zamiast tego.

Na przykład:

<?xml version="1.0"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
    <metadata>
        ...
        <repository type="git" url="https://github.com/NuGet/NuGet.Client.git" branch="dev" commit="e1c65e4524cd70ee6e22abe33e6cb6ec73938cb3" />
        ...
    </metadata>
</package>

Podczas przekazywania pakietu do nuget.org type atrybut jest ograniczony do 100 znaków, a url atrybut jest ograniczony do 4000 znaków.

title

Przyjazny dla człowieka tytuł pakietu, który może być używany w niektórych wyświetlaczach interfejsu użytkownika. (nuget.org i Menedżer pakietów w programie Visual Studio nie pokazują tytułu)

Podczas przekazywania pakietu do nuget.org pole jest ograniczone do 256 znaków, title ale nie jest używane do celów wyświetlania.

Elementy kolekcji

packageTypes

(3,5+) Kolekcja zera lub większej liczby <packageType> elementów określających typ pakietu, jeśli jest inny niż tradycyjny pakiet zależności. Każdy parametr packageType ma atrybuty nazwy i wersji. Zobacz Ustawianie typu pakietu.

zależności

Kolekcja zera lub większej liczby <dependency> elementów określających zależności dla pakietu. Każda zależność ma atrybuty id, version, include (3.x+) i exclude (3.x+). Zobacz zależności poniżej.

frameworkAssemblies

(1.2+) Kolekcja zera lub większej liczby <frameworkAssembly> elementów identyfikujących odwołania do zestawu .NET Framework wymagane przez ten pakiet, co gwarantuje, że odwołania są dodawane do projektów korzystających z pakietu. Każda strukturaAssembly ma atrybuty assemblyName i targetFramework . Zobacz Określanie odwołań do zestawu platformy GAC poniżej.

odwołania

(1,5+) Kolekcja zera lub większej liczby <reference> elementów nazewnictwa zestawów w folderze pakietu lib , które są dodawane jako odwołania do projektu. Każde odwołanie ma atrybut pliku . <references> może również zawierać <group> element z atrybutem targetFramework , który następnie zawiera <reference> elementy. W przypadku pominięcia wszystkie odwołania do elementu lib są uwzględniane. Zobacz Określanie jawnych odwołań do zestawów poniżej.

contentFiles

(3.3+) Kolekcja <files> elementów identyfikujących pliki zawartości do uwzględnienia w projekcie korzystającym. Te pliki są określane z zestawem atrybutów opisujących sposób ich użycia w systemie projektu. Zobacz Określanie plików do uwzględnienia w pakiecie poniżej.

files

Węzeł <package> może zawierać <files> węzeł jako element równorzędny do <metadata>elementu i <contentFiles> element podrzędny w obszarze <metadata>, aby określić, które pliki zestawów i zawartości mają zostać uwzględnione w pakiecie. Aby uzyskać szczegółowe informacje, zobacz Dołączanie plików zestawów i Dołączanie plików zawartości w dalszej części tego tematu.

atrybuty metadanych

minClientVersion

Określa minimalną wersję klienta NuGet, który może zainstalować ten pakiet, wymuszany przez nuget.exe i program Visual Studio Menedżer pakietów. Jest to używane za każdym razem, gdy pakiet zależy od określonych funkcji .nuspec pliku, które zostały dodane w określonej wersji klienta NuGet. Na przykład pakiet używający atrybutu developmentDependency powinien określać wartość "2.8" dla elementu minClientVersion. Podobnie pakiet używający contentFiles elementu (zobacz następną sekcję) powinien mieć wartość minClientVersion "3.3". Należy również pamiętać, że ponieważ klienci NuGet wcześniejsze niż 2.5 nie rozpoznają tej flagi, zawsze odmawiają zainstalowania pakietu niezależnie od tego, co minClientVersion zawiera.

<?xml version="1.0" encoding="utf-8"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
    <metadata minClientVersion="100.0.0.1">
        <id>dasdas</id>
        <version>2.0.0</version>
        <title />
        <authors>dsadas</authors>
        <owners />
        <requireLicenseAcceptance>false</requireLicenseAcceptance>
        <description>My package description.</description>
    </metadata>
    <files>
        <file src="content\one.txt" target="content\one.txt" />
    </files>
</package>

Tokeny zastępcze

Podczas tworzenia pakietu nuget pack polecenie zastępuje tokeny $-delimited w .nuspec węzłach pliku i <files> wartościami pochodzącymi z pliku <metadata> lub pack przełącznika -properties polecenia.

W wierszu polecenia należy określić wartości tokenu za pomocą nuget pack -properties <name>=<value>;<name>=<value>polecenia . Można na przykład użyć tokenu, takiego jak $owners$ i $desc$ w elempcie .nuspec i, i podać wartości w czasie pakowania w następujący sposób:

nuget pack MyProject.csproj -properties
    owners=janedoe,harikm,kimo,xiaop;desc="Awesome app logger utility"

Aby użyć wartości z projektu, określ tokeny opisane w poniższej tabeli (AssemblyInfo odnosi się do pliku w pliku, Properties takiego jak AssemblyInfo.cs lub AssemblyInfo.vb).

Aby użyć tych tokenów, uruchom polecenie nuget pack z plikiem projektu, a nie tylko ..nuspec Na przykład w przypadku użycia następującego polecenia $id$ tokeny i $version$ w .nuspec pliku są zastępowane wartościami i AssemblyVersion projektuAssemblyName:

nuget pack MyProject.csproj

Zazwyczaj, gdy masz projekt, należy utworzyć .nuspec początkowo przy użyciu nuget spec MyProject.csproj polecenia , który automatycznie zawiera niektóre z tych standardowych tokenów. Jeśli jednak projekt nie ma wartości wymaganych .nuspec elementów, zakończy nuget pack się niepowodzeniem. Ponadto, jeśli zmienisz wartości projektu, pamiętaj, aby ponownie skompilować przed utworzeniem pakietu; można to zrobić wygodnie za pomocą przełącznika build polecenia pakietu.

Z wyjątkiem $configuration$wartości w projekcie są używane w preferencjach do dowolnego przypisanego do tego samego tokenu w wierszu polecenia.

Token Źródło wartości Wartość
$id$ Plik projektu AssemblyName (tytuł) z pliku projektu
$version$ Assemblyinfo AssemblyInformationalVersion, jeśli istnieje, w przeciwnym razie AssemblyVersion
$author$ Assemblyinfo AssemblyCompany
$title$ Assemblyinfo AssemblyTitle
$description$ Assemblyinfo Opis zestawu
$copyright$ Assemblyinfo AssemblyCopyright
$configuration$ Biblioteka DLL zestawu Konfiguracja używana do kompilowania zestawu, domyślnie do debugowania. Pamiętaj, że aby utworzyć pakiet przy użyciu konfiguracji wydania, zawsze należy użyć -properties Configuration=Release w wierszu polecenia.

Tokeny mogą również służyć do rozpoznawania ścieżek podczas dołączania plików zestawów i plików zawartości. Tokeny mają takie same nazwy jak właściwości programu MSBuild, dzięki czemu można wybrać pliki, które mają być uwzględniane w zależności od bieżącej konfiguracji kompilacji. Jeśli na przykład użyjesz następujących tokenów w .nuspec pliku:

<files>
    <file src="bin\$configuration$\$id$.pdb" target="lib\net40" />
</files>

I utworzysz zestaw, którego AssemblyName element ma LoggingLibrary konfigurację Release w programie MSBuild, wynikowe wiersze w .nuspec pliku w pakiecie są następujące:

<files>
    <file src="bin\Release\LoggingLibrary.pdb" target="lib\net40" />
</files>

Element Dependencies

Element <dependencies> w programie <metadata> zawiera dowolną liczbę <dependency> elementów identyfikujących inne pakiety, od których zależy pakiet najwyższego poziomu. Atrybuty dla każdego z nich <dependency> są następujące:

Atrybut opis
id (Wymagane) Identyfikator pakietu zależności, taki jak "EntityFramework" i "NUnit", czyli nazwa nuget.org pakietu wyświetlana na stronie pakietu.
version (Wymagane) Zakres wersji akceptowalnych jako zależność. Zobacz Przechowywanie wersji pakietów, aby uzyskać dokładną składnię. Wersje przestawne nie są obsługiwane.
include Rozdzielana przecinkami lista tagów dołączania/wykluczania (patrz poniżej) wskazująca zależność do uwzględnienia w pakiecie końcowym. Domyślna wartość to all.
wykluczanie Rozdzielana przecinkami lista tagów dołączania/wykluczania (patrz poniżej) wskazująca zależność do wykluczenia w pakiecie końcowym. Wartość domyślna to build,analyzers , która może być zastępowana. Ale content/ ContentFiles są również niejawnie wykluczone w końcowym pakiecie, który nie może być nadmiernie napisany. Tagi określone z pierwszeństwem exclude przed tymi określonymi za pomocą includepolecenia . Na przykład kod include="runtime, compile" exclude="compile" jest taki sam jak kod include="runtime".

Podczas przekazywania pakietu do nuget.org atrybut każdej zależności id jest ograniczony do 128 znaków, a version atrybut jest ograniczony do 256 znaków.

Tag Dołączanie/wykluczanie Foldery, których dotyczy problem z obiektem docelowym
contentFiles Zawartość
środowisko uruchomieniowe Środowisko uruchomieniowe, zasoby i strukturaAssemblies
kompilowanie Lib
build build (rekwizyty i obiekty docelowe programu MSBuild)
natywne natywne
Brak Brak folderów
wszystkie Wszystkie foldery

Na przykład następujące wiersze wskazują zależności od PackageA wersji 1.1.0 lub nowszej oraz PackageB wersji 1.x.

<dependencies>
    <dependency id="PackageA" version="1.1.0" />
    <dependency id="PackageB" version="[1,2)" />
</dependencies>

Poniższe wiersze wskazują zależności od tych samych pakietów, ale określ, aby uwzględnić contentFiles foldery PackageA i build i oraz wszystkie elementy, ale native foldery i compile "PackageB

<dependencies>
    <dependency id="PackageA" version="1.1.0" include="contentFiles, build" />
    <dependency id="PackageB" version="[1,2)" exclude="native, compile" />
</dependencies>

Ważne

Podczas tworzenia elementu .nuspec na podstawie projektu przy użyciu programu nuget speczależności, które istnieją w tym projekcie, nie są automatycznie uwzględniane w pliku wynikowym .nuspec . Zamiast tego użyj polecenia nuget pack myproject.csproji pobierz plik nuspec z wygenerowanego pliku nupkg . Ten plik nuspec zawiera zależności.

Grupy zależności

Wersja 2.0 lub nowsza

Alternatywą dla pojedynczej płaskiej listy zależności można określić zgodnie z profilem struktury projektu docelowego przy użyciu <group> elementów w programie <dependencies>.

Każda grupa ma atrybut o nazwie targetFramework i zawiera zero lub więcej <dependency> elementów. Te zależności są instalowane razem, gdy platforma docelowa jest zgodna z profilem struktury projektu.

Element <group> bez atrybutu targetFramework jest używany jako domyślna lub rezerwowa lista zależności. Aby uzyskać dokładne identyfikatory platform, zobacz Platformy docelowe.

Ważne

Format grupy nie może być mieszany z płaską listą.

Uwaga

Format programu Target Framework Moniker (TFM) używany w lib/ref folderze różni się w porównaniu z programem TFM używanym w programie dependency groups. Jeśli struktury docelowe zadeklarowane w folderze dependencies group i lib/ref nie mają dokładnych .nuspec dopasowań pack , polecenie zgłosi ostrzeżenie NuGet NU5128.

W poniższym przykładzie przedstawiono różne odmiany <group> elementu:

<dependencies>
    <group>
        <dependency id="RouteMagic" version="1.1.0" />
    </group>

    <group targetFramework=".NETFramework4.7.2">
        <dependency id="jQuery" version="1.6.2" />
        <dependency id="WebActivator" version="1.4.4" />
    </group>

    <group targetFramework="netcoreapp3.1">
    </group>
</dependencies>

Jawne odwołania do zestawów

Element <references> jest używany przez projekty za pomocą polecenia packages.config do jawnego określenia zestawów, do których powinien się odwoływać projekt docelowy podczas korzystania z pakietu. Jawne odwołania są zwykle używane do zestawów tylko w czasie projektowania. Aby uzyskać więcej informacji, zobacz stronę dotyczącą wybierania zestawów, do których odwołuje się projekty , aby uzyskać więcej informacji.

Na przykład następujący <references> element instruuje NuGet, aby dodać odwołania tylko xunit.dll do pakietu, a xunit.extensions.dll nawet jeśli w pakiecie znajdują się dodatkowe zestawy:

<references>
    <reference file="xunit.dll" />
    <reference file="xunit.extensions.dll" />
</references>

Grupy referencyjne

Alternatywą dla pojedynczej płaskiej listy odwołania można określić zgodnie z profilem struktury projektu docelowego przy użyciu <group> elementów w programie <references>.

Każda grupa ma atrybut o nazwie targetFramework i zawiera zero lub więcej <reference> elementów. Odwołania te są dodawane do projektu, gdy platforma docelowa jest zgodna z profilem struktury projektu.

Element <group> bez atrybutu targetFramework jest używany jako domyślna lub rezerwowa lista odwołań. Aby uzyskać dokładne identyfikatory platform, zobacz Platformy docelowe.

Ważne

Format grupy nie może być mieszany z płaską listą.

W poniższym przykładzie przedstawiono różne odmiany <group> elementu:

<references>
    <group>
        <reference file="a.dll" />
    </group>

    <group targetFramework="net45">
        <reference file="b45.dll" />
    </group>

    <group targetFramework="netcore45">
        <reference file="bcore45.dll" />
    </group>
</references>

Odwołania do zestawu struktury

Zestawy struktury to te, które są częścią platformy .NET Framework i powinny już znajdować się w globalnej pamięci podręcznej zestawów (GAC) dla danej maszyny. Identyfikując te zestawy w elemencie <frameworkAssemblies> , pakiet może upewnić się, że wymagane odwołania są dodawane do projektu w przypadku, gdy projekt nie ma już takich odwołań. Takie zestawy, oczywiście, nie są zawarte bezpośrednio w pakiecie.

Element <frameworkAssemblies> zawiera zero lub więcej <frameworkAssembly> elementów, z których każdy określa następujące atrybuty:

Atrybut opis
Assemblyname (Wymagane) W pełni kwalifikowana nazwa zestawu.
targetFramework (Opcjonalnie) Określa platformę docelową, do której ma zastosowanie to odwołanie. Jeśli pominięto, wskazuje, że odwołanie dotyczy wszystkich struktur. Aby uzyskać dokładne identyfikatory platform, zobacz Platformy docelowe.

W poniższym przykładzie przedstawiono odwołanie do System.Net wszystkich platform docelowych oraz odwołanie tylko do System.ServiceModel programu .NET Framework 4.0:

<frameworkAssemblies>
    <frameworkAssembly assemblyName="System.Net"  />

    <frameworkAssembly assemblyName="System.ServiceModel" targetFramework="net40" />
</frameworkAssemblies>

Dołączanie plików zestawów

Jeśli przestrzegasz konwencji opisanych w temacie Tworzenie pakietu, nie musisz jawnie określać listy plików w .nuspec pliku. Polecenie nuget pack automatycznie pobiera niezbędne pliki.

Ważne

Po zainstalowaniu pakietu w projekcie nuGet automatycznie dodaje odwołania do zestawów do bibliotek DLL pakietu, z wyłączeniem tych, które są nazwane.resources.dll, ponieważ zakłada się, że mają być zlokalizowane zestawy satelitarne. Z tego powodu należy unikać używania .resources.dll plików, które w przeciwnym razie zawierają podstawowy kod pakietu.

Aby pominąć to zachowanie automatyczne i jawnie kontrolować, które pliki są zawarte w pakiecie, umieść <files> element jako element podrzędny <package> (i element równorzędny <metadata>), identyfikując każdy plik z oddzielnym <file> elementem. Na przykład:

<files>
    <file src="bin\Debug\*.dll" target="lib" />
    <file src="bin\Debug\*.pdb" target="lib" />
    <file src="tools\**\*.*" exclude="**\*.log" />
</files>

W przypadku pakietów NuGet 2.x i starszych oraz projektów korzystających z programu packages.config<files> element jest również używany do dołączania niezmiennych plików zawartości podczas instalowania pakietu. W przypadku pakietu NuGet 3.3 lub nowszego i projektu PackageReference <contentFiles> element jest używany zamiast tego. Aby uzyskać szczegółowe informacje, zobacz Dołączanie plików zawartości poniżej.

Atrybuty elementu pliku

Każdy <file> element określa następujące atrybuty:

Atrybut opis
Src Lokalizacja pliku lub plików do uwzględnienia, z zastrzeżeniem exclude wykluczeń określonych przez atrybut. Ścieżka jest względna względem .nuspec pliku, chyba że określono ścieżkę bezwzględną. Symbol * wieloznaczny jest dozwolony, a podwójny symbol wieloznaczny ** oznacza przeszukiwanie folderów cyklicznych.
Docelowego Ścieżka względna do folderu w pakiecie, w którym znajdują się pliki źródłowe, które muszą zaczynać się od lib, , contentlub buildtools. Zobacz Tworzenie pliku nuspec z katalogu roboczego opartego na konwencji.
Wykluczyć Rozdzielana średnikami lista plików lub wzorców plików do wykluczenia z src lokalizacji. Symbol * wieloznaczny jest dozwolony, a podwójny symbol wieloznaczny ** oznacza przeszukiwanie folderów cyklicznych.

Przykłady

Pojedynczy zestaw

Source file:
    library.dll

.nuspec entry:
    <file src="library.dll" target="lib" />

Packaged result:
    lib\library.dll

Pojedynczy zestaw specyficzny dla platformy docelowej

Source file:
    library.dll

.nuspec entry:
    <file src="assemblies\net40\library.dll" target="lib\net40" />

Packaged result:
    lib\net40\library.dll

Zestaw bibliotek DLL korzystających z symboli wieloznacznych

Source files:
    bin\release\libraryA.dll
    bin\release\libraryB.dll

.nuspec entry:
    <file src="bin\release\*.dll" target="lib" />

Packaged result:
    lib\libraryA.dll
    lib\libraryB.dll

Biblioteki DLL dla różnych struktur

Source files:
    lib\net40\library.dll
    lib\net20\library.dll

.nuspec entry (using ** recursive search):
    <file src="lib\**" target="lib" />

Packaged result:
    lib\net40\library.dll
    lib\net20\library.dll

Wykluczanie plików

Source files:
    \tools\fileA.bak
    \tools\fileB.bak
    \tools\fileA.log
    \tools\build\fileB.log

.nuspec entries:
    <file src="tools\*.*" target="tools" exclude="tools\*.bak" />
    <file src="tools\**\*.*" target="tools" exclude="**\*.log" />

Package result:
    (no files)

Dołączanie plików zawartości

Pliki zawartości to pliki niezmienne, które pakiet musi zawierać w projekcie. Nie są one niezmienne, nie mają być modyfikowane przez projekt zużywany. Przykładowe pliki zawartości obejmują:

  • Obrazy osadzone jako zasoby
  • Pliki źródłowe, które są już skompilowane
  • Skrypty, które należy dołączyć do danych wyjściowych kompilacji projektu
  • Pliki konfiguracji pakietu, które muszą być uwzględnione w projekcie, ale nie wymagają żadnych zmian specyficznych dla projektu

Pliki zawartości są dołączane do pakietu przy użyciu <files> elementu, określając content folder w atrybucie target . Jednak takie pliki są ignorowane, gdy pakiet jest zainstalowany w projekcie przy użyciu funkcji PackageReference, która zamiast tego używa <contentFiles> elementu .

Aby uzyskać maksymalną zgodność z projektami korzystającymi z projektów, pakiet najlepiej określa pliki zawartości w obu elementach.

Używanie elementu files dla plików zawartości

W przypadku plików zawartości po prostu użyj tego samego formatu co w przypadku plików zestawów, ale określ content jako folder podstawowy w atrybucie target , jak pokazano w poniższych przykładach.

Podstawowe pliki zawartości

Source files:
    css\mobile\style1.css
    css\mobile\style2.css

.nuspec entry:
    <file src="css\mobile\*.css" target="content\css\mobile" />

Packaged result:
    content\css\mobile\style1.css
    content\css\mobile\style2.css

Pliki zawartości ze strukturą katalogu

Source files:
    css\mobile\style.css
    css\mobile\wp7\style.css
    css\browser\style.css

.nuspec entry:
    <file src="css\**\*.css" target="content\css" />

Packaged result:
    content\css\mobile\style.css
    content\css\mobile\wp7\style.css
    content\css\browser\style.css

Plik zawartości specyficzny dla platformy docelowej

Source file:
    css\cool\style.css

.nuspec entry
    <file src="css\cool\style.css" target="Content" />

Packaged result:
    content\style.css

Plik zawartości skopiowany do folderu z kropką w nazwie

W takim przypadku program NuGet widzi, że rozszerzenie w target pliku nie pasuje do rozszerzenia w src pliku i w ten sposób traktuje tę część nazwy w target folderze:

Source file:
    images\picture.png

.nuspec entry:
    <file src="images\picture.png" target="Content\images\package.icons" />

Packaged result:
    content\images\package.icons\picture.png

Pliki zawartości bez rozszerzeń

Aby dołączyć pliki bez rozszerzenia, użyj * symboli wieloznacznych lub ** :

Source file:
    flags\installed

.nuspec entry:
    <file src="flags\**" target="flags" />

Packaged result:
    flags\installed

Pliki zawartości ze ścieżką głęboką i obiektem docelowym

W tym przypadku, ponieważ rozszerzenia plików źródłowego i docelowego są zgodne, NuGet zakłada, że element docelowy jest nazwą pliku, a nie folderem:

Source file:
    css\cool\style.css

.nuspec entry:
    <file src="css\cool\style.css" target="Content\css\cool" />
    or:
    <file src="css\cool\style.css" target="Content\css\cool\style.css" />

Packaged result:
    content\css\cool\style.css

Zmiana nazwy pliku zawartości w pakiecie

Source file:
    ie\css\style.css

.nuspec entry:
    <file src="ie\css\style.css" target="Content\css\ie.css" />

Packaged result:
    content\css\ie.css

Wykluczanie plików

Source file:
    docs\*.txt (multiple files)

.nuspec entry:
    <file src="docs\*.txt" target="content\docs" exclude="docs\admin.txt" />
    or
    <file src="*.txt" target="content\docs" exclude="admin.txt;log.txt" />

Packaged result:
    All .txt files from docs except admin.txt (first example)
    All .txt files from docs except admin.txt and log.txt (second example)

Używanie elementu contentFiles dla plików zawartości

NuGet 4.0+ z funkcją PackageReference

Domyślnie pakiet umieszcza zawartość w contentFiles folderze (patrz poniżej) i nuget pack uwzględnia wszystkie pliki w tym folderze przy użyciu atrybutów domyślnych. W takim przypadku nie jest konieczne uwzględnienie węzła contentFiles w .nuspec ogóle.

Aby kontrolować, które pliki są zawarte, <contentFiles> element określa jest kolekcją <files> elementów, które identyfikują dokładne pliki dołączane.

Te pliki są określane za pomocą zestawu atrybutów opisujących sposób ich użycia w systemie projektu:

Atrybut opis
include (Wymagane) Lokalizacja pliku lub plików do uwzględnienia, z zastrzeżeniem exclude wykluczeń określonych przez atrybut. Ścieżka jest względna względem contentFiles folderu, chyba że określono ścieżkę bezwzględną. Symbol * wieloznaczny jest dozwolony, a podwójny symbol wieloznaczny ** oznacza przeszukiwanie folderów cyklicznych.
Wykluczyć Rozdzielana średnikami lista plików lub wzorców plików do wykluczenia z src lokalizacji. Symbol * wieloznaczny jest dozwolony, a podwójny symbol wieloznaczny ** oznacza przeszukiwanie folderów cyklicznych.
buildAction Akcja kompilacji, która ma zostać przypisana do elementu zawartości dla programu MSBuild, na przykład Content, None, Embedded Resource, itp Compile. Wartość domyślna to Compile.
copyToOutput Wartość logiczna wskazująca, czy skopiować elementy zawartości do folderu wyjściowego kompilacji (lub publikowania). Wartością domyślną jest false.
Spłaszczyć Wartość logiczna wskazująca, czy skopiować elementy zawartości do pojedynczego folderu w danych wyjściowych kompilacji (true), czy zachować strukturę folderów w pakiecie (false). Ta flaga działa tylko wtedy, gdy flaga copyToOutput jest ustawiona na true. Wartością domyślną jest false.

Podczas instalowania pakietu nuGet stosuje elementy podrzędne <contentFiles> od góry do dołu. Jeśli wiele wpisów jest zgodnych z tym samym plikiem, zostaną zastosowane wszystkie wpisy. Najbardziej górny wpis zastępuje dolne wpisy, jeśli występuje konflikt dla tego samego atrybutu.

Struktura folderów pakietów

Projekt pakietu powinien strukturę zawartości przy użyciu następującego wzorca:

/contentFiles/{codeLanguage}/{TxM}/{any?}
  • codeLanguages może to być cs, vb, fs, anylub małe litery równoważne danym $(ProjectLanguage)
  • TxM to dowolny legalny pseudonim platformy docelowej, który obsługuje NuGet (zobacz Platformy docelowe).
  • Na końcu tej składni może zostać dołączona dowolna struktura folderów.

Na przykład:

Language- and framework-agnostic:
    /contentFiles/any/any/config.xml

net45 content for all languages
    /contentFiles/any/net45/config.xml

C#-specific content for net45 and up
    /contentFiles/cs/net45/sample.cs

Puste foldery mogą służyć . do rezygnacji z udostępniania zawartości dla niektórych kombinacji języka i TxM, na przykład:

/contentFiles/vb/any/code.vb
/contentFiles/cs/any/.

Przykładowa sekcja contentFiles

<?xml version="1.0" encoding="utf-8"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
    <metadata>
        ...
        <contentFiles>
            <!-- Embed image resources -->
            <files include="any/any/images/dnf.png" buildAction="EmbeddedResource" />
            <files include="any/any/images/ui.png" buildAction="EmbeddedResource" />

            <!-- Embed all image resources under contentFiles/cs/ -->
            <files include="cs/**/*.png" buildAction="EmbeddedResource" />

            <!-- Copy config.xml to the root of the output folder -->
            <files include="cs/uap/config/config.xml" buildAction="None" copyToOutput="true" flatten="true" />

            <!-- Copy run.cmd to the output folder and keep the directory structure -->
            <files include="cs/commands/run.cmd" buildAction="None" copyToOutput="true" flatten="false" />

            <!-- Include everything in the scripts folder except exe files -->
            <files include="cs/net45/scripts/*" exclude="**/*.exe"  buildAction="None" copyToOutput="true" />
        </contentFiles>
        </metadata>
</package>

Grupy referencyjne platformy

Wersja 5.1 lub nowsza tylko wih PackageReference

Odwołania do platformy to koncepcja platformy .NET Core reprezentująca struktury udostępnione, takie jak WPF lub Windows Forms. Określając platformę udostępnioną, pakiet gwarantuje, że wszystkie jego zależności struktury zostaną uwzględnione w projekcie odwołującym się.

Każdy <group> element wymaga atrybutu targetFramework i zero lub więcej <frameworkReference> elementów.

W poniższym przykładzie przedstawiono pakiet nuspec wygenerowany dla projektu WPF platformy .NET Core. Należy pamiętać, że tworzenie pakietów nuspecs zawierających odwołania do struktury nie jest zalecane. Rozważ użycie pakietu targets , który automatycznie wywnioskuje je z projektu.

<package xmlns="http://schemas.microsoft.com/packaging/2012/06/nuspec.xsd">
  <metadata>
    <dependencies>
      <group targetFramework=".NETCoreApp3.1" />
    </dependencies>
    <frameworkReferences>
      <group targetFramework=".NETCoreApp3.1">
        <frameworkReference name="Microsoft.WindowsDesktop.App.WPF" />
      </group>
    </frameworkReferences>
  </metadata>
</package>

Przykładowe pliki nuspec

Prosty, .nuspec który nie określa zależności ani plików

<?xml version="1.0" encoding="utf-8"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
    <metadata>
        <id>sample</id>
        <version>1.2.3</version>
        <authors>Kim Abercrombie, Franck Halmaert</authors>
        <description>Sample exists only to show a sample .nuspec file.</description>
        <language>en-US</language>
        <projectUrl>http://xunit.codeplex.com/</projectUrl>
        <license type="expression">MIT</license>
    </metadata>
</package>

Element .nuspec z zależnościami

<?xml version="1.0" encoding="utf-8"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
    <metadata>
        <id>sample</id>
        <version>1.0.0</version>
        <authors>Microsoft</authors>
        <dependencies>
            <dependency id="another-package" version="3.0.0" />
            <dependency id="yet-another-package" version="1.0.0" />
        </dependencies>
    </metadata>
</package>

A .nuspec z plikami

<?xml version="1.0"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
    <metadata>
        <id>routedebugger</id>
        <version>1.0.0</version>
        <authors>Jay Hamlin</authors>
        <requireLicenseAcceptance>false</requireLicenseAcceptance>
        <description>Route Debugger is a little utility I wrote...</description>
    </metadata>
    <files>
        <file src="bin\Debug\*.dll" target="lib" />
    </files>
</package>

Element .nuspec z zestawami struktur

<?xml version="1.0"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
    <metadata>
        <id>PackageWithGacReferences</id>
        <version>1.0</version>
        <authors>Author here</authors>
        <requireLicenseAcceptance>false</requireLicenseAcceptance>
        <description>
            A package that has framework assemblyReferences depending
            on the target framework.
        </description>
        <frameworkAssemblies>
            <frameworkAssembly assemblyName="System.Web" targetFramework="net40" />
            <frameworkAssembly assemblyName="System.Net" targetFramework="net40-client, net40" />
            <frameworkAssembly assemblyName="Microsoft.Devices.Sensors" targetFramework="sl4-wp" />
            <frameworkAssembly assemblyName="System.Json" targetFramework="sl3" />
        </frameworkAssemblies>
    </metadata>
</package>

W tym przykładzie dla określonych celów projektu są zainstalowane następujące elementy:

  • . NET4 ->System.Web, System.Net
  • . Profil klienta NET4 —>System.Net
  • Silverlight 3 —>System.Json
  • Windows Telefon —>Microsoft.Devices.Sensors