project.json i platforma UWP

Ważny

Ta zawartość jest przestarzała. Projekty powinny używać formatów PackageReference. Dowiedz się, jak migrować projekt project.json do elementu PackageReference. Program Visual Studio 2026 automatycznie migruje project.json w czasie ładowania rozwiązania. Zestaw .NET 10 SDK i NuGet.exe 7.0 nie obsługują projektów project.json.

W tym dokumencie opisano strukturę pakietu, która korzysta z funkcji w pakiecie NuGet 3+ (Visual Studio 2015 i nowszych). Właściwość minClientVersion w .nuspec może być użyta, aby określić, że funkcje opisane tutaj są wymagane, poprzez ustawienie jej na 3.1.

Dodawanie obsługi platformy UWP do istniejącego pakietu

Jeśli masz istniejący pakiet i chcesz dodać obsługę aplikacji platformy uniwersalnej Windows, nie musisz wdrażać formatu pakowania opisanego tutaj. Musisz przyjąć ten format tylko wtedy, gdy potrzebujesz opisanych przez nią funkcji i chcesz pracować tylko z klientami, którzy zostali zaktualizowani do wersji 3 lub nowszej klienta NuGet.

Już celuję w netcore45

Jeśli już celujesz w netcore45 i nie musisz wykorzystywać funkcji tutaj, to nie jest wymagana żadna akcja. Pakiety netcore45 mogą być używane w aplikacjach UWP.

Chcę korzystać z interfejsów API specyficznych dla systemu Windows 10

W takim przypadku musisz dodać do pakietu uap10.0 nazwę docelową platformy docelowej (TFM lub TxM). Utwórz nowy folder w pakiecie i dodaj zestaw, który został skompilowany w celu pracy z systemem Windows 10 w tym folderze.

Nie potrzebuję określonych interfejsów API systemu Windows 10, ale chcę nowych funkcji platformy .NET lub nie mam jeszcze netcore45.

W takim przypadku należy dodać dotnet TxM do pakietu. W przeciwieństwie do innych TxMs, dotnet nie oznacza powierzchni ani platformy. Oznacza to, że pakiet działa na dowolnej platformie, na której działają zależności. Podczas kompilowania pakietu za pomocą dotnet TxM prawdopodobnie będziesz mieć wiele zależności specyficznych dla txm w .nuspec, ponieważ trzeba zdefiniować zależne pakiety BCL, takie System.Text, System.Xmlitp. Lokalizacje, w których te zależności działają, definiują miejsce działania pakietu.

Jak sprawdzić zależności

Istnieją dwa sposoby na ustalenie, które zależności mają być wyświetlane na liście:

  1. Użyj narzędzia NuSpec Dependency Generator innej firmy. Narzędzie automatyzuje proces i aktualizuje plik .nuspec przy użyciu pakietów zależnych podczas kompilacji. Jest on dostępny za pośrednictwem pakietu NuGet NuSpec.ReferenceGenerator.

  2. (Trudna droga) Użyj ILDasm, aby przyjrzeć się .dll i zobaczyć, jakie zestawy są rzeczywiście potrzebne w czasie wykonywania. Następnie określ, z którego pakietu NuGet pochodzą poszczególne pakiety.

Zobacz temat project.json, aby uzyskać szczegółowe informacje na temat funkcji, które ułatwiają tworzenie pakietu obsługującego dotnet TxM.

Ważny

Jeśli pakiet jest przeznaczony do pracy z projektami PCL, zdecydowanie zalecamy utworzenie folderu dotnet, aby uniknąć ostrzeżeń i potencjalnych problemów ze zgodnością.

Struktura katalogu

Pakiety NuGet korzystające z tego formatu mają następujące dobrze znane zachowania i foldery:

Folder Zachowania
Budować Zawarte w tym folderze pliki docelowe i pliki props programu MSBuild są integrowane z projektem w inny sposób, ale poza tym nie ma żadnych innych zmian.
Narzędzia install.ps1 i uninstall.ps1 nie są uruchamiane. init.ps1 działa jak zawsze.
Zawartość Zawartość nie jest kopiowana automatycznie do projektu użytkownika. Obsługa dołączania zawartości w projekcie jest planowana na późniejszą wersję.
Lib W przypadku wielu pakietów lib działa tak samo jak w programie NuGet 2.x, ale z rozszerzonymi opcjami dotyczącymi nazw, których można używać w nim, i lepszą logiką wybierania poprawnego podfolderu podczas korzystania z pakietów. Jednak w połączeniu z reffolder lib zawiera zestawy, które implementują obszar powierzchni zdefiniowany przez zestawy w folderze ref.
Ref ref jest opcjonalnym folderem zawierającym zestawy platformy .NET definiujące interfejs publiczny (typy publiczne i metody), przeciwko którym można kompilować aplikacje. Zestawy w tym folderze mogą nie mieć implementacji. Są one używane wyłącznie do definiowania obszaru powierzchni dla kompilatora. Jeśli pakiet nie ma folderu ref, lib jest zarówno zestawem odniesienia, jak i zestawem implementacji.
Środowiska uruchomieniowe runtimes to opcjonalny folder zawierający kod specyficzny dla systemu operacyjnego, taki jak architektura procesora CPU i pliki binarne specyficzne dla systemu operacyjnego lub w inny sposób zależne od platformy.

Obiekty docelowe i pliki props programu MSBuild w pakietach

Pakiety NuGet mogą zawierać pliki .targets i .props, które są importowane do dowolnego projektu MSBuild zainstalowanego w pakiecie. W programie NuGet 2.x zostało to zrobione przez wstrzyknięcie instrukcji <Import> do pliku .csproj, w programie NuGet 3.0 nie ma określonej akcji "instalacja do projektu". Zamiast tego proces przywracania pakietu zapisuje dwa pliki [projectname].nuget.props i [projectname].NuGet.targets.

Program MSBuild wie, że szuka tych dwóch plików i automatycznie importuje je w pobliżu początku i pod koniec procesu kompilacji projektu. Zapewnia to bardzo podobne zachowanie do nuGet 2.x, ale z jedną istotną różnicą: nie ma gwarantowanej kolejności plików docelowych/props w tym przypadku. Jednak program MSBuild udostępnia sposoby porządkowenia obiektów docelowych za pomocą atrybutów BeforeTargets i AfterTargets definicji <Target> (zobacz Element docelowy (MSBuild).

Lib i Ref

Zachowanie folderu lib nie zmieniło się znacząco w programie NuGet w wersji 3. Jednak wszystkie zestawy muszą znajdować się w podfolderach nazwanych według TxM i nie można ich umieszczać bezpośrednio w folderze lib. TxM to nazwa platformy, dla którego dany zasób w pakiecie ma działać. Logicznym rozszerzeniem Monikerów platform docelowych (TFM) są przykładowo net45, net46, netcore50i dnxcore50, które wszystkie są przykładami TxMs (zobacz Platformy docelowe). TxM może odnosić się do struktury (TFM), a także innych obszarów powierzchni specyficznych dla platformy. Na przykład platforma UWP TxM (uap10.0) reprezentuje obszar powierzchni platformy .NET, a także obszar powierzchni systemu Windows dla aplikacji platformy UWP.

Przykładowa struktura lib:

lib
├───net40
│       MyLibrary.dll
└───wp81
        MyLibrary.dll

Folder lib zawiera zestawy używane w czasie wykonywania. Dla większości pakietów wystarczy folder w lib dla każdego z docelowych TxMs.

Ref

Czasami zdarza się, że podczas kompilacji należy używać innego zestawu (zestawy referencyjne platformy .NET wykonują to dzisiaj). W takich przypadkach użyj folderu najwyższego poziomu o nazwie ref (skrót od "Zestawy referencyjne").

Większość autorów pakietów nie wymaga folderu ref. Jest to przydatne w przypadku pakietów, które muszą zapewnić spójny obszar powierzchni do kompilacji i funkcji IntelliSense, ale następnie mają różne implementacje dla różnych TxMs. Największym przypadkiem użycia są pakiety System.*, które są produkowane w ramach dystrybucji platformy .NET Core na NuGet. Te pakiety mają różne implementacje, które są ujednolicone przez spójny zestaw zestawów ref.

Mechanicznie, zestawy zawarte w folderze ref są zestawami referencyjnymi przekazywanymi do kompilatora. Dla tych, którzy używali csc.exe są to zestawy, które przekazujemy do C# /reference opcji przełącznika.

Struktura folderu ref jest taka sama jak lib, na przykład:

└───MyImageProcessingLib
        ├───lib
        │   ├───net40
        │   │       MyImageProcessingLibrary.dll
        │   │
        │   ├───net451
        │   │       MyImageProcessingLibrary.dll
        │   │
        │   └───win81
        │           MyImageProcessingLibrary.dll
        │
        └───ref
            ├───net40
            │       MyImageProcessingLibrary.dll
            │
            └───portable-net451-win81
                    MyImageProcessingLibrary.dll

W tym przykładzie zestawy w katalogach ref byłyby identyczne.

Środowiska uruchomieniowe

Folder runtimes zawiera zestawy i biblioteki natywne wymagane do uruchamiania na określonych "środowiskach uruchomieniowych", które są ogólnie zdefiniowane przez architekturę systemu operacyjnego i procesora CPU. Te środowiska uruchomieniowe są identyfikowane przy użyciu identyfikatorów środowiska uruchomieniowego, takich jak win, win-x86, win7-x86, win8-64itp.

Natywne biblioteki pomocnicze do korzystania z interfejsów API specyficznych dla platformy

Poniższy przykład przedstawia pakiet, który ma wyłącznie zarządzaną implementację dla kilku platform, ale używa natywnych pomocników w systemie Windows 8, gdzie może wywoływać interfejsy API natywne specyficzne dla systemu Windows 8.

└───MyLibrary
        ├───lib
        │   └───net40
        │           MyLibrary.dll
        │
        └───runtimes
            ├───win8-x64
            │   ├───lib
            │   │   └───net40
            │   │           MyLibrary.dll
            │   │
            │   └───native
            │           MyNativeLibrary.dll
            │
            └───win8-x86
                ├───lib
                │   └───net40
                │           MyLibrary.dll
                │
                └───native
                        MyNativeLibrary.dll

Biorąc pod uwagę powyższy pakiet, występują następujące kwestie:

  • Kiedy nie używa się systemu Windows 8, wykorzystywany jest zestaw lib/net40/MyLibrary.dll.

  • Gdy w systemie Windows 8 używa się runtimes/win8-<architecture>/lib/MyLibrary.dll, a native/MyNativeHelper.dll jest kopiowana do danych wyjściowych kompilacji.

W powyższym przykładzie zestaw lib/net40 składa się wyłącznie z zarządzanego kodu, podczas gdy zestawy w folderze runtimes będą wykorzystywać p/invoke do natywnego zestawu pomocniczego w celu wywołania interfejsów API specyficznych dla Windows 8.

Wybierany jest tylko jeden folder lib, więc jeśli istnieje folder specyficzny dla środowiska uruchomieniowego, jest on wybierany zamiast folderu lib, który nie jest specyficzny dla środowiska uruchomieniowego. Folder natywny jest dodawczy, jeśli istnieje, jest kopiowany do wyników kompilacji.

Zarządzane opakowanie

Innym sposobem użycia środowisk uruchomieniowych jest dostarczenie pakietu, który jest wyłącznie powłoką zarządzaną dla natywnego zestawu. W tym scenariuszu utworzysz pakiet podobny do następującego:

└───MyLibrary
        └───runtimes
            ├───win8-x64
            │   ├───lib
            │   │   └───net451
            │   │           MyLibrary.dll
            │   │
            │   └───native
            │           MyImplementation.dll
            │
            └───win8-x86
                ├───lib
                │   └───net451
                │           MyLibrary.dll
                │
                └───native
                        MyImplementation.dll

W tym przypadku nie ma folderu najwyższego poziomu lib, ponieważ każda implementacja tego pakietu opiera się na odpowiednim zestawie natywnym. Jeśli zestaw zarządzany, MyLibrary.dll, byłby dokładnie taki sam w obu przypadkach, moglibyśmy umieścić go w folderze lib najwyższego poziomu. Jednak brak zestawu natywnego nie powoduje niepowodzenia w instalacji pakietu, jeśli ten został zainstalowany na platformie innej niż win-x86 lub win-x64. Wówczas biblioteka najwyższego poziomu byłaby używana, ale zestaw natywny nie zostałby skopiowany.

Tworzenie pakietów dla NuGet 2 i NuGet 3

Jeśli chcesz utworzyć pakiet, który może być używany przez projekty korzystające z packages.config, jak również pakietów korzystających z project.json, zastosuj się do następujących wytycznych:

  • Ref i środowiska uruchomieniowe działają tylko w systemie NuGet 3. Oba te elementy są ignorowane przez pakiet NuGet 2.

  • Nie można polegać na install.ps1 lub uninstall.ps1 do działania. Te pliki są wykonywane podczas korzystania z packages.config, ale są ignorowane za pomocą project.json. Pakiet musi być użyteczny bez konieczności ich uruchamiania. init.ps1 nadal działa w systemie NuGet 3.

  • Instalacja elementów docelowych i props jest inna, dlatego upewnij się, że pakiet działa zgodnie z oczekiwaniami na obu klientach.

  • Podkatalogi lib w NuGet 3 muszą spełniać standard TxM. Nie można umieszczać bibliotek w katalogu głównym folderu lib.

  • Zawartość nie jest kopiowana automatycznie za pomocą narzędzia NuGet 3. Użytkownicy pakietu mogą skopiować same pliki lub użyć narzędzia takiego jak moduł uruchamiający zadania w celu zautomatyzowania kopiowania plików.

  • Przekształcenia plików źródłowych i konfiguracji nie są uruchamiane przez pakiet NuGet 3.

Jeśli obsługujesz pakiet NuGet 2 i 3, minClientVersion powinien być najniższą wersją klienta NuGet 2, na którym działa pakiet. W przypadku istniejącego pakietu nie należy go zmieniać.

  • Last updated on