Ondersteuning voor meerdere .NET-versies

Veel bibliotheken richten zich op een specifieke versie van .NET Framework. U hebt bijvoorbeeld één versie van uw bibliotheek die specifiek is voor UWP en een andere versie die gebruikmaakt van functies in .NET Framework 4.6. Om dit mogelijk te maken, ondersteunt NuGet het plaatsen van meerdere versies van dezelfde bibliotheek in één pakket.

In dit artikel wordt de indeling van een NuGet-pakket beschreven, ongeacht hoe het pakket of de assembly's worden gebouwd (dat wil zeggen, de indeling is hetzelfde, of u nu meerdere niet-SDK-stijl .csproj bestanden en een aangepast .nuspec bestand gebruikt, of een enkel multi-targeted SDK-stijl .csproj). Voor een SDK-stijl project weet NuGet-packdoelen hoe het pakket moet worden ingedeeld en automatiseert het plaatsen van de assemblies in de juiste lib-mappen en het creëren van afhankelijkheidsgroepen voor elk doelframework (TFM). Zie Ondersteuning voor meerdere .NET Framework-versies in uw projectbestand voor gedetailleerde instructies.

U moet het pakket handmatig opmaken zoals beschreven in dit artikel wanneer u de op conventie gebaseerde werkmapmethode gebruikt die wordt beschreven in Een pakket maken. Voor een SDK-project wordt de geautomatiseerde methode aanbevolen, maar u kunt er ook voor kiezen om het pakket handmatig in te delen zoals beschreven in dit artikel.

Structuur van de map voor frameworkversies

Wanneer u een pakket bouwt dat slechts één versie van een bibliotheek bevat of meerdere frameworks target, maakt u altijd submappen onder lib met verschillende hoofdlettergevoelige frameworknamen volgens de volgende conventie:

lib\{framework name}[{version}]

Zie de Doelframeworks-referentie voor een volledige lijst van ondersteunde namen.

U moet nooit een versie van de bibliotheek hebben die niet specifiek is voor een framework en die rechtstreeks in de hoofdmap lib wordt geplaatst. (Deze mogelijkheid is alleen ondersteund met packages.config). Als u dit doet, wordt de bibliotheek compatibel met elk doelframework en kan deze overal worden geïnstalleerd, wat waarschijnlijk leidt tot onverwachte runtimefouten. Het toevoegen van assembly's in de hoofdmap (zoals lib\abc.dll) of submappen (zoals lib\abc\abc.dll) is afgeschaft en wordt genegeerd wanneer u de PackagesReference-indeling gebruikt.

De volgende mapstructuur ondersteunt bijvoorbeeld vier versies van een assembly die frameworkspecifiek zijn:

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

Gebruik een recursief ** jokerteken in de <files> sectie van uw .nuspec om eenvoudig alle bestanden op te nemen bij het bouwen van het pakket.

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

Architectuurspecifieke mappen

Als u architectuurspecifieke assembly's hebt, dat wil gezegd, afzonderlijke assembly's die gericht zijn op ARM, x86 en x64, moet u deze in een map plaatsen met de naam runtimes submappen met de naam {platform}-{architecture}\lib\{framework} of {platform}-{architecture}\native. De volgende mapstructuur is bijvoorbeeld geschikt voor zowel systeemeigen als beheerde DLL's die gericht zijn op Windows 10 en het uap10.0 framework:

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

Deze assembly's zijn alleen beschikbaar tijdens runtime, dus als u ook de bijbehorende compileertijdassembly wilt opgeven, moet u de assembly in AnyCPU de map hebben/ref/{tfm}.

Houd er rekening mee dat NuGet deze compilatie- of runtime-assets altijd uit één map kiest. Dus als er enkele compatibele assets zijn van `/ref`, dan wordt `/lib` genegeerd om compileertijdassembly's toe te voegen. Als er enkele compatibele assets van /runtimes zijn, dan zal /lib ook genegeerd worden tijdens runtime.

Zie UWP-pakketten maken voor een voorbeeld van het verwijzen naar deze bestanden in het .nuspec manifest.

Zie Ook een Windows Store-app-onderdeel verpakken met NuGet

Vergelijken van assembly-versies en het target-framework binnen een project

Wanneer NuGet een pakket met meerdere assemblyversies installeert, wordt geprobeerd de frameworknaam van de assembly te koppelen aan het doelframework van het project.

Als er geen overeenkomst wordt gevonden, kopieert NuGet de assembly naar de hoogste versie die kleiner is dan of gelijk is aan het doelframework van het project, indien beschikbaar. Als er geen compatibele assembly wordt gevonden, retourneert NuGet een geschikt foutbericht.

Denk bijvoorbeeld aan de volgende mapstructuur in een pakket:

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

Wanneer u dit pakket installeert in een project dat is gericht op .NET Framework 4.6, installeert NuGet de assembly in de net45 map, omdat dat de hoogst beschikbare versie is die kleiner is dan of gelijk is aan 4.6.

Als het project is gericht op .NET Framework 4.6.1, installeert NuGet daarentegen de assembly in de net461 map.

Als het project gericht is op .NET Framework 4.0 en eerder, geeft NuGet een passende foutmelding dat de compatibele assembly niet gevonden kan worden.

Assemblies groeperen volgens frameworkversie

NuGet kopieert assembly's uit slechts één bibliotheekmap in het pakket. Stel dat een pakket de volgende mapstructuur heeft:

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

Wanneer het pakket is geïnstalleerd in een project dat is gericht op .NET Framework 4.5, MyAssembly.dll (v2.0), is de enige assembly geïnstalleerd. MyAssembly.Core.dll (v1.0) is niet geïnstalleerd omdat deze niet wordt vermeld in de net45 map. NuGet gedraagt zich op deze manier omdat MyAssembly.Core.dll mogelijk is samengevoegd in versie 2.0 van MyAssembly.dll.

Als u wilt MyAssembly.Core.dll worden geïnstalleerd voor .NET Framework 4.5, plaatst u een kopie in de net45 map.

Groeperen van assemblies op frameworkprofiel

NuGet ondersteunt ook het instellen van een specifiek frameworkprofiel door een streepje en de profielnaam toe te voegen aan het einde van de map.

lib{framework name}-{profile}

De ondersteunde profielen zijn als volgt:

• client: Clientprofiel
• full: Volledig profiel
• wp:Windows Phone
• cf: Compact Framework

Afhankelijkheden declareren (geavanceerd)

Wanneer u een projectbestand inpakt, probeert NuGet automatisch de afhankelijkheden van het project te genereren. De informatie in deze sectie over het gebruik van een .nuspec-bestand om afhankelijkheden te declareren, is doorgaans alleen nodig voor geavanceerde scenario's.

(Versie 2.0+) U kunt pakketafhankelijkheden declareren in de .nuspec die overeenkomt met het doelframework van het doelproject met behulp van <group> elementen in het <dependencies> element. Zie het element Afhankelijkheden voor meer informatie.

Elke groep heeft een kenmerk met de naam targetFramework en bevat nul of meer <dependency> elementen. Deze afhankelijkheden worden samen geïnstalleerd wanneer het doelframework compatibel is met het frameworkprofiel van het project. Zie Doelframeworks voor de exacte framework-id's.

U wordt aangeraden één groep per Target Framework Moniker (TFM) te gebruiken voor bestanden in de lib/ - en ref/ -mappen.

In het volgende voorbeeld ziet u verschillende variaties van het <group> element:

<dependencies>

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

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

</dependencies>

Bepalen welk NuGet-doel moet worden gebruikt

Wanneer u bibliotheken inpakt die gericht zijn op de Portable Class Library, kan het lastig zijn om te bepalen welk NuGet-doel u moet gebruiken in uw mapnamen en .nuspec -bestand, met name als u alleen een subset van de PCL wilt gebruiken. De volgende externe resources helpen u hierbij:

• Framework-profielen in .NET (stephencleary.com)
• Portable Class Library-profielen (plnkr.co): Tabelinventaratie van PCL-profielen en hun equivalente NuGet-doelen
• Hulpprogramma voor portable Class Library-profielen (github.com): opdrachtregelprogramma voor het bepalen van PCL-profielen die beschikbaar zijn op uw systeem

Inhoudsbestanden en PowerShell-scripts

Met packages.configkunnen inhoudsbestanden en PowerShell-scripts worden gegroepeerd op doelframework met behulp van dezelfde mapconventie in de content en tools mappen. Voorbeeld:

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

Als een frameworkmap leeg blijft, voegt NuGet geen assemblyverwijzingen of inhoudsbestanden toe of voert u de PowerShell-scripts voor dat framework uit.