De .NET Portability Analyzer

Notitie

API-poort is afgeschaft ten gunste van binaire analyse door de .NET Upgrade Assistant. De back-endservice van DE API-poort is afgesloten, dus als u het hulpprogramma wilt gebruiken, moet u deze offline gebruiken. Zie .NET API Port README voor meer informatie.

Wilt u ervoor zorgen dat uw bibliotheken ondersteuning bieden voor meerdere platforms? Wilt u zien hoeveel werk er nodig is om uw .NET Framework-toepassing uit te voeren op .NET Core? . NET Portability Analyzer is een hulpprogramma dat assembly's analyseert en een gedetailleerd rapport biedt over .NET-API's die ontbreken voor de toepassingen of bibliotheken die kunnen worden overdraagbaar op de opgegeven doelplatforms van .NET. Portability Analyzer wordt aangeboden als een Visual Studio-extensie, waarmee één assembly per project wordt geanalyseerd en als een ApiPort-console-app, waarmee assembly's worden geanalyseerd op basis van opgegeven bestanden of map.

Zodra u uw project hebt geconverteerd naar het nieuwe platform, zoals .NET Core, kunt u de op Roslyn gebaseerde platformcompatibiliteitsanalyse gebruiken om API's te identificeren die uitzonderingen en andere compatibiliteitsproblemen genereren PlatformNotSupportedException .

Algemene doelen

• .NET Core: heeft een modulair ontwerp, ondersteunt side-by-side installatie en is gericht op platformoverschrijdende scenario's. Met side-by-side-installatie kunt u nieuwe .NET Core-versies gebruiken zonder dat u andere apps hoeft te breken. Als u uw app wilt overzetten naar .NET Core en meerdere platforms wilt ondersteunen, is dit het aanbevolen doel.
• .NET Standard: bevat de .NET Standard-API's die beschikbaar zijn voor alle .NET-implementaties. Als u ervoor wilt zorgen dat uw bibliotheek wordt uitgevoerd op alle .NET-ondersteunde platforms, wordt dit aanbevolen.
• ASP.NET Core: een modern webframework dat is gebouwd op .NET Core. Als u uw web-app wilt overzetten naar .NET Core om meerdere platforms te ondersteunen, is dit het aanbevolen doel.
• .NET Core + Platform Extensions: Bevat de .NET Core-API's naast het Windows-compatibiliteitspakket, dat veel van de beschikbare .NET Framework-technologieën biedt. Dit is een aanbevolen doel voor het overzetten van uw app van .NET Framework naar .NET Core in Windows.
• .NET Standard + Platform Extensions: Bevat de .NET Standard-API's naast het Windows-compatibiliteitspakket, dat veel van de beschikbare .NET Framework-technologieën biedt. Dit is een aanbevolen doel voor het overzetten van uw bibliotheek van .NET Framework naar .NET Core in Windows.

.NET Portability Analyzer gebruiken

Als u de .NET Portability Analyzer in Visual Studio wilt gaan gebruiken, moet u eerst de extensie downloaden en installeren vanuit Visual Studio Marketplace. Het werkt in versies van Visual Studio 2017 en Visual Studio 2019.

Belangrijk

De .NET Portability Analyzer wordt niet ondersteund in Visual Studio 2022.

Configureer deze in Visual Studio via Analyze>Portability Analyzer Instellingen en selecteer uw doelplatforms. Dit zijn de .NET-platformen/versies waarmee u de draagbaarheidsverschillen wilt evalueren, vergeleken met het platform/de versie waarmee uw huidige assembly is gebouwd.

U kunt ook de ApiPort-consoletoepassing gebruiken en deze downloaden uit de ApiPort-opslagplaats. U kunt de opdrachtoptie gebruiken listTargets om de beschikbare doellijst weer te geven en vervolgens doelplatformen te kiezen door een opdrachtoptie op te -t geven of --target te selecteren.

Oplossingsbrede weergave

Een handige stap bij het analyseren van een oplossing met veel projecten is het visualiseren van de afhankelijkheden om te begrijpen welke subset van assembly's afhankelijk is van wat. De algemene aanbeveling is om de resultaten van de analyse toe te passen in een bottom-up benadering die begint met de leaf-knooppunten in een afhankelijkheidsgrafiek.

U kunt deze opdracht ophalen door de volgende opdracht uit te voeren:

ApiPort.exe analyze -r DGML -f [directory or file]

Een resultaat hiervan ziet er als volgt uit wanneer deze wordt geopend in Visual Studio:

Draagbaarheid analyseren

Als u uw hele project in Visual Studio wilt analyseren, klikt u met de rechtermuisknop op uw project in Solution Explorer en selecteert u De draagbaarheid van de assembly analyseren. Anders gaat u naar het menu Analyseren en selecteert u De draagbaarheid van de assembly analyseren. Selecteer daar het uitvoerbare bestand of dll-bestand van uw project.

U kunt ook de ApiPort-console-app gebruiken.

Typ de volgende opdracht om de huidige map te analyseren:

ApiPort.exe analyze -f .

Als u een specifieke lijst met .dll bestanden wilt analyseren, typt u de volgende opdracht:

ApiPort.exe analyze -f first.dll -f second.dll -f third.dll

Als u een specifieke versie wilt gebruiken, gebruikt u de -t parameter:

ApiPort.exe analyze -t ".NET, Version=5.0" -f .

Voer uit ApiPort.exe -? om meer hulp te krijgen.

Het wordt aanbevolen om alle gerelateerde exe- en DLL-bestanden op te nemen die u bezit en die u wilt overzetten, en de bestanden uit te sluiten waarop uw app afhankelijk is, maar u niet de eigenaar bent en niet kunt overzetten. Hiermee krijgt u het meest relevante rapport over portabiliteit.

Portabiliteitsresultaat weergeven en interpreteren

Alleen API's die niet worden ondersteund door een doelplatform, worden weergegeven in het rapport. Nadat u de analyse in Visual Studio hebt uitgevoerd, wordt de bestandskoppeling voor het .NET Portability-rapport weergegeven. Als u de ApiPort-console-app hebt gebruikt, wordt uw .NET Portability-rapport opgeslagen als een bestand in de opgegeven indeling. De standaardwaarde bevindt zich in een Excel-bestand (.xlsx) in uw huidige map.

Overzicht van draagbaarheid

In de sectie Overdraagbaarheidsoverzicht van het rapport wordt het portabiliteitspercentage weergegeven voor elke assembly die in de uitvoering is opgenomen. In het vorige voorbeeld zijn 71,24% van de .NET Framework-API's die in de svcutil app worden gebruikt, beschikbaar in .NET Core + Platform Extensions. Als u het hulpprogramma .NET Portability Analyzer uitvoert op meerdere assembly's, moet elke assembly een rij hebben in het rapport Overzicht van draagbaarheid.

DETAILS

In de sectie Details van het rapport worden de API's vermeld die ontbreken in een van de geselecteerde doelplatforms.

• Doeltype: het type heeft ontbrekende API van een doelplatform
• Doellid: de methode ontbreekt in een doelplatform
• Assemblynaam: de .NET Framework-assembly waarin de ontbrekende API zich bevindt.
• Elk van de geselecteerde doelplatforms is één kolom, zoals .NET Core: 'Niet ondersteund', betekent dat de API niet wordt ondersteund op dit doelplatform.
• Aanbevolen wijzigingen: de aanbevolen API of technologie die moet worden gewijzigd. Dit veld is momenteel leeg of verouderd voor veel API's. Vanwege het grote aantal API's hebben we een aanzienlijke uitdaging om deze up-to-date te houden. We kijken naar alternatieve oplossingen om nuttige informatie te bieden aan klanten.

Ontbrekende assembly's

Mogelijk vindt u een sectie Ontbrekende assembly's in uw rapport. Deze sectie bevat een lijst met assembly's waarnaar wordt verwezen door uw geanalyseerde assembly's en die niet zijn geanalyseerd. Als het een assembly is die u bezit, neemt u deze op in de uitvoering van de API portability analyzer, zodat u een gedetailleerd rapport over portabiliteit op API-niveau kunt krijgen. Als het een bibliotheek van derden is, controleert u of er een nieuwere versie is die ondersteuning biedt voor uw doelplatform en overweeg om over te stappen naar de nieuwere versie. Uiteindelijk moet de lijst alle assembly's van derden bevatten die afhankelijk zijn van die versie die uw doelplatform ondersteunt.

Ga naar de GitHub-documentatie voor meer informatie over .NET Portability Analyzer.