Obsługa wielu wersji platformy .NET

Artykuł
10/18/2023

Wiele bibliotek jest przeznaczonych dla określonej wersji programu .NET Framework. Na przykład możesz mieć jedną wersję biblioteki specyficzną dla platformy UWP i inną wersję, która korzysta z funkcji w programie .NET Framework 4.6. Aby to uwzględnić, pakiet NuGet obsługuje umieszczanie wielu wersji tej samej biblioteki w jednym pakiecie.

W tym artykule opisano układ pakietu NuGet, niezależnie od tego, jak są tworzone pakiety lub zestawy (czyli układ jest taki sam, niezależnie od tego, czy jest używanych wiele plików csproj w stylu innym niż SDK i niestandardowy plik nuspec, czy jeden wielokierunkowy zestaw SDK w stylu csproj). W przypadku projektu w stylu zestawu SDK docelowe pakiety NuGet wiedzą, jak pakiet musi być ułożone i automatyzuje umieszczanie zestawów w odpowiednich folderach lib i tworzenie grup zależności dla każdej platformy docelowej (TFM). Aby uzyskać szczegółowe instrukcje, zobacz Obsługa wielu wersji programu .NET Framework w pliku projektu.

Należy ręcznie określić pakiet zgodnie z opisem w tym artykule podczas korzystania z metody katalogów roboczych opartych na konwencji opisanej w temacie Tworzenie pakietu. W przypadku projektu w stylu zestawu SDK zalecana jest metoda zautomatyzowana, ale możesz również ręcznie rozłożyć pakiet zgodnie z opisem w tym artykule.

Struktura folderów wersji platformy

Podczas tworzenia pakietu zawierającego tylko jedną wersję biblioteki lub wielu platform docelowych zawsze należy tworzyć podfoldery lib przy użyciu różnych nazw struktur z uwzględnieniem wielkości liter z następującą konwencją:

lib\{framework name}[{version}]

Aby uzyskać pełną listę obsługiwanych nazw, zobacz dokumentację platform docelowych.

Nigdy nie należy mieć wersji biblioteki, która nie jest specyficzna dla struktury i umieszczona bezpośrednio w folderze głównym lib . (Ta funkcja była obsługiwana tylko w programie packages.config). Dzięki temu biblioteka będzie zgodna z dowolną strukturą docelową i pozwoliłaby na jej zainstalowanie w dowolnym miejscu, co prawdopodobnie spowodowało nieoczekiwane błędy środowiska uruchomieniowego. Dodawanie zestawów w folderze głównym (takim jak ) lub podfolderów (takich jak lib\abc.dlllib\abc\abc.dll) zostało wycofane i jest ignorowane podczas korzystania z formatu PackagesReference.

Na przykład następująca struktura folderów obsługuje cztery wersje zestawu specyficzne dla platformy:

\lib
    \net46
        \MyAssembly.dll
    \net461
        \MyAssembly.dll
    \uap
        \MyAssembly.dll
    \netcore
        \MyAssembly.dll

Aby łatwo dołączyć wszystkie te pliki podczas kompilowania pakietu, użyj cyklicznego symbolu wieloznakowego ** w <files> sekcji elementu .nuspec:

<files>
    <file src="lib\**" target="lib/{framework name}[{version}]" />
</files>

Foldery specyficzne dla architektury

Jeśli masz zestawy specyficzne dla architektury, czyli oddzielne zestawy przeznaczone dla usługi ARM, x86 i x64, należy umieścić je w folderze o nazwie w podfolderach o nazwie runtimes{platform}-{architecture}\lib\{framework} lub {platform}-{architecture}\native. Na przykład następująca struktura folderów będzie obsługiwać zarówno natywne, jak i zarządzane biblioteki DLL przeznaczone dla systemu Windows 10 i platformy uap10.0 :

\runtimes
    \win10-arm
        \native
        \lib\uap10.0
    \win10-x86
        \native
        \lib\uap10.0
    \win10-x64
        \native
        \lib\uap10.0

Te zestawy będą dostępne tylko w czasie wykonywania, więc jeśli chcesz podać odpowiedni zestaw czasu kompilacji, a następnie mieć AnyCPU zestaw w /ref/{tfm} folderze.

Należy pamiętać, że program NuGet zawsze wybiera te zasoby kompilowania lub środowiska uruchomieniowego z jednego folderu, więc jeśli istnieją pewne zgodne zasoby, /ref/lib wówczas zostaną zignorowane w celu dodania zestawów czasu kompilacji. Podobnie, jeśli istnieją pewne zgodne zasoby z /runtimes tego czasu, również /lib zostaną zignorowane dla środowiska uruchomieniowego.

Zobacz Tworzenie pakietów platformy UWP, aby zapoznać się z przykładem odwoływania się do tych plików w .nuspec manifeście.

Zobacz również artykuł Pakowanie składnika aplikacji ze sklepu Windows za pomocą narzędzia NuGet

Dopasowywanie wersji zestawu i platformy docelowej w projekcie

Gdy program NuGet instaluje pakiet zawierający wiele wersji zestawu, próbuje dopasować nazwę platformy zestawu do platformy z docelową strukturą projektu.

Jeśli dopasowanie nie zostanie znalezione, pakiet NuGet kopiuje zestaw dla najwyższej wersji, która jest mniejsza lub równa strukturze docelowej projektu, jeśli jest dostępna. Jeśli nie znaleziono zgodnego zestawu, narzędzie NuGet zwraca odpowiedni komunikat o błędzie.

Rozważmy na przykład następującą strukturę folderów w pakiecie:

\lib
    \net45
        \MyAssembly.dll
    \net461
        \MyAssembly.dll

Podczas instalowania tego pakietu w projekcie przeznaczonym dla programu .NET Framework 4.6 program NuGet instaluje zestaw w net45 folderze, ponieważ jest to najwyższa dostępna wersja, która jest mniejsza lub równa 4.6.

Jeśli projekt jest przeznaczony dla programu .NET Framework 4.6.1, z drugiej strony program NuGet instaluje zestaw w folderze net461 .

Jeśli projekt jest przeznaczony dla platformy .NET Framework 4.0 lub starszej, program NuGet zgłasza odpowiedni komunikat o błędzie, aby nie znaleźć zgodnego zestawu.

Grupowanie zestawów według wersji platformy

Narzędzie NuGet kopiuje zestawy tylko z jednego folderu biblioteki w pakiecie. Załóżmy na przykład, że pakiet ma następującą strukturę folderów:

\lib
    \net40
        \MyAssembly.dll (v1.0)
        \MyAssembly.Core.dll (v1.0)
    \net45
        \MyAssembly.dll (v2.0)

Po zainstalowaniu pakietu w projekcie przeznaczonym dla programu .NET Framework 4.5 MyAssembly.dll (wersja 2.0) jest jedynym zainstalowanym zestawem. MyAssembly.Core.dll (wersja 1.0) nie jest zainstalowana, ponieważ nie znajduje się na liście w folderze net45 . Narzędzie NuGet zachowuje się w ten sposób, ponieważ MyAssembly.Core.dll mogło zostać scalone z wersją 2.0 programu MyAssembly.dll.

Jeśli chcesz MyAssembly.Core.dll zainstalować program .NET Framework 4.5, umieść kopię w folderze net45 .

Grupowanie zestawów według profilu struktury

Pakiet NuGet obsługuje również kierowanie określonego profilu platformy przez dołączenie kreski i nazwy profilu na końcu folderu.

lib{nazwa platformy}-{profil}

Obsługiwane profile są następujące:

client: Profil klienta
full: Pełny profil
wp: Windows Telefon
cf: Compact Framework

Deklarowanie zależności (zaawansowane)

Podczas pakowania pliku projektu NuGet próbuje automatycznie wygenerować zależności z projektu. Informacje przedstawione w tej sekcji dotyczące używania pliku nuspec do deklarowania zależności są zwykle niezbędne tylko w przypadku zaawansowanych scenariuszy.

(Wersja 2.0 lub nowsza) Zależności pakietów można zadeklarować w elemencie .nuspec odpowiadającym strukturze docelowej projektu docelowego przy użyciu <group> elementów w elemencie <dependencies> . Aby uzyskać więcej informacji, zobacz element dependencies (Zależności).

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. Aby uzyskać dokładne identyfikatory platform, zobacz Platformy docelowe.

Zalecamy używanie jednej grupy na docelową strukturę Moniker (TFM) dla plików w folderach lib/ i ref/ .

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

<dependencies>

    <group targetFramework="net472">
        <dependency id="jQuery" version="1.10.2" />
        <dependency id="WebActivatorEx" version="2.2.0" />
    </group>

    <group targetFramework="net20">
    </group>

</dependencies>

Określanie, który element docelowy NuGet ma być używany

Podczas tworzenia pakietów bibliotek przeznaczonych dla przenośnej biblioteki klas może to być trudne, aby określić, który element docelowy NuGet należy użyć w nazwach folderów i .nuspec pliku, szczególnie w przypadku określania wartości docelowej tylko podzestawu PCL. Następujące zasoby zewnętrzne pomogą Ci w tym:

Profile struktury na platformie .NET (stephencleary.com)
Profile biblioteki klas przenośnych (plnkr.co): tabela wyliczania profilów PCL i ich równoważnych elementów docelowych NuGet
Narzędzie profilów biblioteki klas przenośnych (github.com): narzędzie wiersza polecenia do określania profilów PCL dostępnych w systemie

Pliki zawartości i skrypty programu PowerShell

Ostrzeżenie

Pliki zawartości modyfikowalnej i wykonywanie skryptu są dostępne tylko w packages.config formacie; są przestarzałe ze wszystkimi innymi formatami i nie powinny być używane w przypadku żadnych nowych pakietów.

Za pomocą packages.configpolecenia pliki zawartości i skrypty programu PowerShell można grupować według platformy docelowej przy użyciu tej samej konwencji folderów wewnątrz content folderów i tools . Na przykład:

\content
    \net46
        \MyContent.txt
    \net461
        \MyContent461.txt
    \uap
        \MyUWPContent.html
    \netcore
\tools
    init.ps1
    \net46
        install.ps1
        uninstall.ps1
    \uap
        install.ps1
        uninstall.ps1

Jeśli folder struktury pozostanie pusty, pakiet NuGet nie dodaje odwołań do zestawów ani plików zawartości ani nie uruchamia skryptów programu PowerShell dla tej platformy.

Uwaga

Ponieważ init.ps1 jest wykonywany na poziomie rozwiązania i nie jest zależny od projektu, należy go umieścić bezpośrednio w folderze tools . Jest on ignorowany, jeśli znajduje się w folderze struktury.

Udostępnij za pośrednictwem