The .NET Portability Analyzer

Kommentar

API-porten har blivit inaktuell till förmån för binär analys av .NET Upgrade Assistant. Serverdelstjänsten för API-porten har stängts av, så om du vill använda verktyget måste du använda den offline. Mer information finns i .NET API Port README.

Vill du göra så att dina bibliotek stöder flera plattformar? Vill du se hur mycket arbete som krävs för att få .NET Framework-programmet att köras på .NET Core? .NET Portability Analyzer är ett verktyg som analyserar sammansättningar och tillhandahåller en detaljerad rapport om .NET-API:er som saknas för att programmen eller biblioteken ska vara portabla på dina angivna .NET-plattformar. Portability Analyzer erbjuds som ett Visual Studio-tillägg, som analyserar en sammansättning per projekt och som en ApiPort-konsolapp, som analyserar sammansättningar efter angivna filer eller kataloger.

När du har konverterat projektet till att rikta in dig på den nya plattformen, till exempel .NET Core, kan du använda den Roslyn-baserade analysatorn för plattformskompatibilitet för att identifiera API:er som utlöser PlatformNotSupportedException undantag och andra kompatibilitetsproblem.

Vanliga mål

• .NET Core: Har en modulär design, stöder installation sida vid sida och är inriktad på plattformsoberoende scenarier. Med en separat installation kan du använda nya .NET Core-versioner utan att bryta andra appar. Om målet är att porta din app till .NET Core och stödja flera plattformar är detta det rekommenderade målet.
• .NET Standard: Innehåller .NET Standard API:er som är tillgängliga för alla .NET-implementeringar. Om målet är att få biblioteket att köras på alla .NET-plattformar som stöds rekommenderas detta mål.
• ASP.NET Core: Ett modernt webbramverk som bygger på .NET Core. Om målet är att porta webbappen till .NET Core för att stödja flera plattformar är detta det rekommenderade målet.
• .NET Core + Platform Extensions: Innehåller .NET Core-API:er utöver Windows Compatibility Pack, som tillhandahåller många av de tillgängliga .NET Framework-teknikerna. Detta är ett rekommenderat mål för att portera din app från .NET Framework till .NET Core i Windows.
• .NET Standard + Platform Extensions: Innehåller .NET Standard API:er utöver Windows Compatibility Pack, som tillhandahåller många av de tillgängliga .NET Framework-teknikerna. Detta är ett rekommenderat mål för att portera biblioteket från .NET Framework till .NET Core i Windows.

Så här använder du .NET Portability Analyzer

För att börja använda .NET Portability Analyzer i Visual Studio måste du först ladda ned och installera tillägget från Visual Studio Marketplace. Det fungerar på Visual Studio 2017- och Visual Studio 2019-versioner.

Viktigt!

.NET Portability Analyzer stöds inte i Visual Studio 2022.

Konfigurera den i Visual Studio via Analysera>portabilitetsanalys Inställningar och välj dina målplattformar, som är de .NET-plattformar/versioner som du vill utvärdera portabilitetsluckorna jämfört med den plattform/version som din nuvarande sammansättning har skapats med.

Du kan också använda ApiPort-konsolprogrammet och ladda ned det från ApiPort-lagringsplatsen. Du kan använda listTargets kommandoalternativet för att visa den tillgängliga mållistan och sedan välja målplattformar genom att -t ange eller --target kommandoalternativ.

Lösningsöversikt

Ett användbart steg för att analysera en lösning med många projekt är att visualisera beroendena för att förstå vilka delmängder av sammansättningar som är beroende av vad. Den allmänna rekommendationen är att tillämpa resultatet av analysen i en bottom-up-metod som börjar med lövnoderna i ett beroendediagram.

Om du vill hämta detta kan du köra följande kommando:

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

Ett resultat av detta skulle se ut så här när det öppnas i Visual Studio:

Analysera portabilitet

Om du vill analysera hela projektet i Visual Studio högerklickar du på projektet i Solution Explorer och väljer Analysera sammansättningsportabilitet. Annars går du till menyn Analysera och väljer Analysera sammansättningsportabilitet. Därifrån väljer du projektets körbara filnamn eller DLL.

Du kan också använda ApiPort-konsolappen.

Skriv följande kommando för att analysera den aktuella katalogen:

ApiPort.exe analyze -f .

Om du vill analysera en specifik lista över .dll filer skriver du följande kommando:

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

Använd parametern för att rikta in dig på -t en viss version:

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

Kör ApiPort.exe -? för att få mer hjälp.

Vi rekommenderar att du inkluderar alla relaterade exe- och dll-filer som du äger och vill porta och exkluderar de filer som appen är beroende av, men du äger inte och kan inte porta. Detta ger dig den mest relevanta portabilitetsrapporten.

Visa och tolka portabilitetsresultat

Endast API:er som inte stöds av en målplattform visas i rapporten. När du har kört analysen i Visual Studio visas fillänken för .NET-portabilitetsrapporten. Om du använde ApiPort-konsolappen sparas .NET-portabilitetsrapporten som en fil i det format som du angav. Standardvärdet finns i en Excel-fil (.xlsx) i den aktuella katalogen.

Sammanfattning av portabilitet

Avsnittet Portabilitetssammanfattning i rapporten visar portabilitetsprocenten för varje sammansättning som ingår i körningen. I föregående exempel är 71,24 % av de .NET Framework-API:er som används i svcutil appen tillgängliga i .NET Core + Platform Extensions. Om du kör verktyget .NET Portability Analyzer mot flera sammansättningar bör varje sammansättning ha en rad i rapporten Portabilitetssammanfattning.

Details

I avsnittet Information i rapporten visas de API:er som saknas i någon av de valda målplattformarna.

• Måltyp: typen saknar API från en målplattform
• Målmedlem: metoden saknas från en målplattform
• Sammansättningsnamn: den .NET Framework-sammansättning som det saknade API:et finns i.
• Var och en av de valda målplattformarna är en kolumn, till exempel värdet ".NET Core": "Stöds inte" innebär att API:et inte stöds på den här målplattformen.
• Rekommenderade ändringar: det rekommenderade API:et eller tekniken att ändra till. För närvarande är det här fältet tomt eller inaktuellt för många API:er. På grund av det stora antalet API:er har vi en betydande utmaning att hålla det uppdaterat. Vi tittar på alternativa lösningar för att ge användbar information till kunder.

Sammansättningar saknas

Du kan hitta avsnittet Saknade sammansättningar i rapporten. Det här avsnittet innehåller en lista över sammansättningar som refereras av dina analyserade sammansättningar och som inte har analyserats. Om det är en sammansättning som du äger inkluderar du den i API-portabilitetsanalyskörningen så att du kan få en detaljerad portabilitetsrapport på API-nivå för den. Om det är ett bibliotek från tredje part kontrollerar du om det finns en nyare version som stöder målplattformen och överväg att flytta till den nyare versionen. Så småningom bör listan innehålla alla sammansättningar från tredje part som din app är beroende av som har en version som stöder din målplattform.

Mer information om .NET Portability Analyzer finns i GitHub-dokumentationen.