Odwołanie do pliku nuspec
.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:
- Formularz ogólny i schemat
- Tokeny zastępcze (w przypadku użycia z projektem programu Visual Studio)
- Zależności
- Jawne odwołania do zestawów
- Odwołania do zestawu struktury
- Dołączanie plików zestawów
- Dołączanie plików zawartości
- Przykładowe pliki nuspec
nuget.exe pack
Należy używać z.nuspec
programem dla projektów w stylu innych niż SDK, które korzystają z programupackages.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
lubmsbuild 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 poleceniadotnet.exe
lubmsbuild pack target
..nuspec
W przypadku projektów migrowanych z
packages.config
do packageReference.nuspec
plik nie jest wymagany do utworzenia pakietu. Zamiast tego użyj polecenia msbuild -t:pack.
nuspec.xsd
Plik schematu można znaleźć w repozytorium NuGet GitHub.
Należy pamiętać, że ten plik reprezentuje tylko najnowszy schemat pliku .nuspec
.
Nie istnieją oficjalnie opublikowane wersje i żadna wersja tego pliku nie odpowiada żadnej konkretnej wersji 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):
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.
Ważne
.nuspec
Chociaż plik zawiera odwołanie do schematu (xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd"
), zespół NuGet nigdy nie opublikował pliku schematu, który może być używany do automatycznej weryfikacji schematu.
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 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.
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 pakietu dla wyświetlania interfejsu użytkownika.
Podczas przekazywania pakietu do nuget.org description
pole jest ograniczone do 4000 znaków.
Rozdzielona przecinkami lista autorów pakietów.
Element authors
i owners
z pakietu nuspec są ignorowane podczas przekazywania pakietu do nuget.org. Aby ustawić własność pakietu na nuget.org, zobacz Zarządzanie właścicielami pakietów w nuget.org.
Ważne
właściciele są przestarzali. Zamiast tego użyj autorów.
Rozdzielona przecinkami lista właścicieli pakietów.
Element owners
z narzędzia nuspec jest ignorowany podczas przekazywania pakietu do nuget.org. Aby ustawić własność pakietu na nuget.org, zobacz Zarządzanie właścicielami pakietów w nuget.org.
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.
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.
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)
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.
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.
Porada
Aby zachować zgodność z poprzednimi wersjami z klientami i źródłami, które jeszcze nie obsługują icon
programu , określ wartości i icon
iconUrl
. Program Visual Studio obsługuje icon
pakiety pochodzące ze źródła opartego na folderach.
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.
Wartość logiczna określająca, czy klient musi monitować użytkownika o zaakceptowanie licencji pakietu przed zainstalowaniem pakietu.
(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)
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.
(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.
Identyfikator ustawień regionalnych pakietu. Zobacz Tworzenie zlokalizowanych pakietów.
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.
(3.3+) W przypadku wewnętrznego narzędzia NuGet użyj tylko.
Metadane repozytorium składające się z czterech atrybutów opcjonalnych: type
i url
(4.0+)oraz commit
branch
(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.
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.
(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.
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.
(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.
(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.
(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.
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.
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>
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>
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ą include polecenia . 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 spec
zależ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.csproj
i pobierz plik nuspec z wygenerowanego pliku nupkg . Ten plik nuspec zawiera 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>
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>
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>
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>
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.
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. |
cel | Ścieżka względna do folderu w pakiecie, w którym znajdują się pliki źródłowe, które muszą zaczynać się od lib , , content lub build tools . Zobacz Tworzenie pliku nuspec z katalogu roboczego opartego na konwencji. |
wykluczać | 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. |
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)
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.
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)
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. |
wykluczać | 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.
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
,any
lub 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/_._
<?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>
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>
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
- WindowsPhone —>
Microsoft.Devices.Sensors