.NET Portability Analyzer

Nota

ApiPort è stato deprecato a favore dell'analisi binaria eseguita da .NET Upgrade Assistant. Il servizio back-end di ApiPort è stato arrestato, quindi per usare lo strumento è necessario usarlo offline. Per altre informazioni, vedere il file LEGGIMI di ApiPort.

È possibile fare in modo che le librerie in uso supportino architetture multi-piattaforma Si vuole vedere quanto lavoro è necessario per eseguire l'applicazione .NET Framework in .NET Core? .NET Portability Analyzer è uno strumento che analizza gli assembly e fornisce un report dettagliato sulle API .NET mancanti per le applicazioni o le librerie da trasferire nelle piattaforme .NET specificate. Portability Analyzer viene offerto come estensione di Visual Studio che consente di analizzare un assembly per progetto e come app console ApiPort che consente di analizzare gli assembly in base a file o directory specificati.

Dopo aver convertito il progetto in modo che usi come destinazione la nuova piattaforma, ad esempio .NET Core, è possibile usare l'Analizzatore della compatibilità della piattaforma basato su Roslyn per identificare le API che generano eccezioni PlatformNotSupportedException e altri problemi di compatibilità.

Destinazioni comuni

• .NET Core: ha una progettazione modulare, supporta l'installazione side-by-side ed è destinato a scenari multipiattaforma. L'installazione side-by-side consente di adottare nuove versioni di .NET Core senza interrompere altre app. Se l'obiettivo è di convertire l'app in .NET Core e supportare più piattaforme, questa è la destinazione consigliata.
• .NET Standard: include le API .NET Standard disponibili in tutte le implementazioni .NET. Se l'obiettivo è poter eseguire la libreria in tutte le piattaforme supportate da .NET, questa è la destinazione consigliata.
• ASP.NET Core: un framework Web moderno basato su .NET Core. Se l'obiettivo è di convertire l'app Web in .NET Core per supportare più piattaforme, questa è la destinazione consigliata.
• .NET Core + Estensioni di piattaforma: include le API .NET Core, oltre a Windows Compatibility Pack, che offre molte delle tecnologie disponibili in .NET Framework. Questa è una destinazione consigliata per la conversione dell'app da .NET Framework a .NET Core in Windows.
• .NET Standard + Estensioni di piattaforma: include le API .NET Standard, oltre a Windows Compatibility Pack, che offre molte delle tecnologie disponibili in .NET Framework. Questa è una destinazione consigliata per la conversione della libreria da .NET Framework a .NET Core in Windows.

Come usare .NET Portability Analyzer

Per iniziare a usare .NET Portability Analyzer in Visual Studio, è prima necessario scaricare l'estensione da Visual Studio Marketplace e installarla. Funziona nelle versioni Visual Studio 2017 e Visual Studio 2019.

Importante

.NET Portability Analyzer non è supportato in Visual Studio 2022.

Configurare Portability Analyzer in Visual Studio tramite Analizza>Impostazioni Portability Analyzer e selezionare le piattaforme di destinazione, ovvero le piattaforme o le versioni di .NET di cui si vogliono valutare i gap di portabilità rispetto alla piattaforma o alla versione con cui è compilato l'assembly corrente.

È anche possibile usare l'applicazione console ApiPort, scaricandola dal repository ApiPort. È possibile usare l'opzione di comando listTargets per visualizzare l'elenco di destinazioni disponibili e quindi selezionare le piattaforme di destinazione specificando l'opzione di comando -t o --target.

Visualizzazione a livello di soluzione

Un passaggio utile nell'analisi di una soluzione con molti progetti consiste nel visualizzare le dipendenze per comprendere quale subset di assembly dipende da elementi specifici. La raccomandazione generale consiste nell'applicare i risultati dell'analisi in un approccio bottom-up a partire dai nodi foglia in un grafico delle dipendenze.

Per recuperare queste informazioni, è possibile eseguire il comando seguente:

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

Il risultato sarà simile al seguente all'apertura in Visual Studio:

Analizzare la portabilità

Per analizzare l'intero progetto in Visual Studio, fare clic con il pulsante destro del mouse sul progetto in Esplora soluzioni e selezionare Analyze Assembly Portability (Analizza portabilità dell'assembly). In caso contrario, accedere al menu Analizza e selezionare Analyze Assembly Portability (Analizza portabilità assembly). Da qui selezionare il file eseguibile o DLL del progetto.

È anche possibile usare l'app console ApiPort.

Digitare il comando seguente per analizzare la directory corrente:

ApiPort.exe analyze -f .

Per analizzare un elenco specifico di file con estensione dll, digitare il comando seguente:

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

Per specificare come destinazione una versione specifica, usare il parametro -t:

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

Per altre informazioni, eseguire il comando ApiPort.exe -?.

È consigliabile includere tutti i file con estensione exe e dll correlati disponibili che si vogliono convertire, escludendo i file da cui l'app dipende, ma di cui non si ha la proprietà e che non si è in grado di convertire. Questa operazione consentirà di ottenere il report di portabilità più pertinente possibile.

Visualizzare e interpretare i risultati di portabilità

Nel report sono visualizzate solo le API non supportate da una piattaforma di destinazione. Dopo aver eseguito l'analisi in Visual Studio, si vedrà comparire il collegamento al file del report sulla portabilità .NET. Se è stata usata l'app console ApiPort, il report sulla portabilità .NET è stato salvato in un file nel formato specificato. Il valore predefinito corrisponde a un file di Excel (xlsx) nella directory corrente.

Riepilogo della portabilità

La sezione Portability Summary (Riepilogo della portabilità) del report indica la percentuale di portabilità per ogni assembly incluso nell'esecuzione. Nell'esempio precedente, il 71,24% delle API .NET Framework usate nell'app svcutil sono disponibili in .NET Core + Estensioni della piattaforma. Se si esegue lo strumento .NET Portability Analyzer per più assembly, per ognuno di questi deve essere presente una riga nel report di riepilogo della portabilità.

Dettagli

Nella sezione Details del report sono elencate le API mancanti da una delle Targeted Platforms selezionate.

• Target type (Tipo di destinazione): per il tipo manca un'API da una piattaforma di destinazione
• Target member (Membro di destinazione): il metodo manca da una piattaforma di destinazione
• Assembly name (Nome dell'assembly): assembly .NET Framework in cui deve trovarsi l'API mancante.
• Ogni piattaforma di destinazione selezionata è una colonna, ad esempio ".NET Core": il valore "Not supported" indica che l'API non è supportata in questa piattaforma di destinazione.
• Recommended Changes: l'API o la tecnologia consigliata a cui passare. Questo campo è attualmente vuoto o non aggiornato per molte API. A causa del numero elevato di API, risulta decisamente difficile mantenerlo aggiornato. È in corso l'esame di soluzioni alternative che consentano di offrire informazioni utili ai clienti.

Assembly mancanti

Nel report può essere presente la sezione Missing Assemblies (Assembly mancanti). Questa sezione contiene un elenco di assembly a cui fanno riferimento gli assembly analizzati e che non sono stati analizzati. Se si tratta di assembly di cui si ha la proprietà, includerli nell'esecuzione dell'API Portability Analyzer (ApiPort) per ottenere un report dettagliato sulla portabilità a livello di API. Se si tratta di una libreria di terze parti, verificare se è presente una versione più recente che supporta la piattaforma di destinazione e prendere in considerazione il passaggio alla versione più recente. L'elenco dovrebbe col tempo includere tutti gli assembly di terze parti da cui dipende l'app con una versione che supporta la piattaforma di destinazione.

Per altre informazioni su .NET Portability Analyzer, vedere la documentazione di GitHub.