The .NET Portability Analyzer

  • Artikel
  • 5 minuter för att läsa

Anteckning

Vi håller på att föråldrade API-portar för att integrera binär analys direkt i .NET Upgrade Assistant. Under de kommande månaderna kommer vi att stänga av serverdelstjänsten för API-port, vilket kräver att verktyget används offline. Mer information finns i GitHub: .NET API Port repository.*

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 riktade .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 genererar PlatformNotSupportedException undantag och andra kompatibilitetsproblem.

Vanliga mål

  • .NET Core: Har en modulär design, har stöd för sida-vid-sida-installation och är inriktad på plattformsoberoende scenarier. Med installation sida vid sida kan du använda nya .NET Core-versioner utan att bryta andra appar. Om målet är att portera 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 plattformar som stöds av .NET rekommenderas det här målet.
  • ASP.NET Core: Ett modernt webbramverk som bygger på .NET Core. Om målet är att portera din webbapp 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 .NET Framework tillgängliga teknikerna. Det här ä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 innehåller många av de .NET Framework tillgängliga teknikerna. Det här ä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>inställningar för portabilitetsanalys 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 den aktuella sammansättningen har skapats med.

Skärmbild av analysverktyg för portabilitet.

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 kommandoalternativet.

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]

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

Skärmbild av DGML-analys.

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.

Skärmbild av Portability Analyzer från Solution Explorer.

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 portera och exkludera de filer som appen är beroende av, men du äger inte och kan inte portera. 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. Standardinställningen finns i en Excel-fil (.xlsx) i den aktuella katalogen.

Sammanfattning av portabilitet

Skärmbild av sammanfattningen 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.

Information

Skärmbild av portabilitetsinformationen.

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 ".NET Core": Värdet "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 som ska ändras 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 stor utmaning att hålla det uppdaterat. Vi tittar på alternativa lösningar för att ge användbar information till kunderna.

Sammansättningar saknas

Skärmbild av sammansättningar som 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 inte har analyserats. Om det är en sammansättning som du äger kan du ta med den i API Portability Analyzer-kö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äger att flytta till den nyare versionen. Så småningom bör listan innehålla alla sammansättningar från tredje part som appen är beroende av och som har en version som stöder målplattformen.

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