O .NET Portability AnalyzerThe .NET Portability Analyzer

Deseja fazer suas bibliotecas serem compatíveis com multiplataforma?Want to make your libraries support multi-platform? Deseja ver quanto trabalho é necessário para fazer seu .NET Framework aplicativo ser executado no .NET Core?Want to see how much work is required to make your .NET Framework application run on .NET Core? O .net Portability Analyzer é uma ferramenta que analisa os assemblies e fornece um relatório detalhado sobre as APIs do .NET que estão faltando para que os aplicativos ou bibliotecas sejam portáteis em suas plataformas .net de destino especificadas.The .NET Portability Analyzer is a tool that analyzes assemblies and provides a detailed report on .NET APIs that are missing for the applications or libraries to be portable on your specified targeted .NET platforms. O analisador de portabilidade é oferecido como uma extensão do Visual Studio, que analisa um assembly por projeto e como um aplicativo de console ApiPort, que analisa os assemblies por arquivos ou diretórios especificados.The Portability Analyzer is offered as a Visual Studio Extension, which analyzes one assembly per project, and as a ApiPort console app, which analyzes assemblies by specified files or directory.

Depois de converter seu projeto para direcionar a nova plataforma, como o .NET Core, você pode usar a ferramenta Analisador de API baseada em Roslyn para identificar as APIs que geram PlatformNotSupportedException exceções e outros problemas de compatibilidade.Once you've converted your project to target the new platform, like .NET Core, you can use the Roslyn-based API Analyzer tool to identify APIs throwing PlatformNotSupportedException exceptions and other compatibility issues.

Destinos comunsCommon targets

  • .NET Core: tem um design modular, dá suporte à instalação lado a lado e tem como alvo cenários de plataforma cruzada..NET Core: Has a modular design, supports side-by-side installation, and targets cross-platform scenarios. A instalação lado a lado permite que você adote novas versões do .NET Core sem interromper outros aplicativos.Side-by-side installation allows you to adopt new .NET Core versions without breaking other apps. Se seu objetivo é portar seu aplicativo para o .NET Core e oferecer suporte a várias plataformas, esse é o destino recomendado.If your goal is to port your app to .NET Core and support multiple platforms, this is the recommended target.
  • . Net Standard: inclui as APIs de .net Standard disponíveis em todas as implementações do .net..NET Standard: Includes the .NET Standard APIs available on all .NET implementations. Se seu objetivo é fazer com que sua biblioteca seja executada em todas as plataformas com suporte do .NET, esse é o destino recomendado.If your goal is to make your library run on all .NET supported platforms, this is recommended target.
  • ASP.NET Core: uma estrutura da Web moderna criada no .NET Core.ASP.NET Core: A modern web-framework built on .NET Core. Se sua meta é portar seu aplicativo Web para o .NET Core para dar suporte a várias plataformas, esse é o destino recomendado.If your goal is to port your web app to .NET Core to support multiple platforms, this is the recommended target.
  • Extensões de plataforma.NET Core +: inclui as APIs do .NET Core, além do pacote de compatibilidade do Windows, que fornece muitas das .NET Framework tecnologias disponíveis..NET Core + Platform Extensions: Includes the .NET Core APIs in addition to the Windows Compatibility Pack, which provides many of the .NET Framework available technologies. Esse é um destino recomendado para portar seu aplicativo do .NET Framework para o .NET Core no Windows.This is a recommended target for porting your app from .NET Framework to .NET Core on Windows.
  • .NET Standard + extensões de plataforma: inclui as APIs de .net Standard além do pacote de compatibilidade do Windows, que fornece muitas das .NET Framework tecnologias disponíveis..NET Standard + Platform Extensions: Includes the .NET Standard APIs in addition to the Windows Compatibility Pack, which provides many of the .NET Framework available technologies. Esse é um destino recomendado para portar sua biblioteca do .NET Framework para o .NET Core no Windows.This is a recommended target for porting your library from .NET Framework to .NET Core on Windows.

Como usar o Analisador de Portabilidade do .NETHow to use the .NET Portability Analyzer

Para começar a usar o Analisador de Portabilidade do .NET no Visual Studio, primeiro é necessário baixar e instalar a extensão do Visual Studio Marketplace.To begin using the .NET Portability Analyzer in Visual Studio, you first need to download and install the extension from the Visual Studio Marketplace. Ele funciona no Visual Studio 2017 e versões posteriores.It works on Visual Studio 2017 and later versions. Configure-o no Visual Studio usando > as configurações do analisador de portabilidade e selecione suas plataformas de destino, que são as plataformas .net/versões que você deseja avaliar as lacunas de portabilidade que são comparadas com a plataforma/versão com a qual seu assembly atual foi criado.Configure it in Visual Studio via Analyze > Portability Analyzer Settings and select your Target Platforms, which are the .NET platforms/versions that you want to evaluate the portability gaps comparing with the platform/version that your current assembly is built with.

Captura de tela do analisador de portabilidade.

Também é possível usar o aplicativo de console ApiPort, baixando-o do repositório ApiPort.You can also use the ApiPort console application, download it from ApiPort repository. É possível usar a opção de comando listTargets para exibir a lista de destino disponível e escolher as plataformas de destino especificando a opção de comando -t ou --target.You can use listTargets command option to display the available target list, then pick target platforms by specifying -t or --target command option.

Visão ampla da soluçãoSolution wide view

Uma etapa útil na análise de uma solução com muitos projetos seria Visualizar as dependências para entender qual subconjunto de assemblies dependem do que.A useful step in analyzing a solution with many projects would be to visualize the dependencies to understand which subset of assemblies depend on what. A recomendação geral é aplicar os resultados da análise em uma abordagem de baixo para cima, começando com os nós folha em um grafo de dependência.The general recommendation is to apply the results of the analysis in a bottom-up approach starting with the leaf nodes in a dependency graph.

Para recuperar isso, você pode executar o seguinte comando:To retrieve this, you may run the following command:

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

Um resultado disso seria semelhante ao seguinte quando aberto no Visual Studio:A result of this would look like the following when opened in Visual Studio:

Captura de tela da análise de DGML.

Analisar portabilidadeAnalyze portability

Para analisar todo o projeto no Visual Studio, clique com o botão direito do mouse no projeto no Gerenciador de Soluções e selecione Analisar Portabilidade do Assembly.To analyze your entire project in Visual Studio, right-click on your project in Solution Explorer and select Analyze Assembly Portability. Caso contrário, acesse o menu Analyze e selecione Analisar Portabilidade do Assembly.Otherwise, go to the Analyze menu and select Analyze Assembly Portability. A partir daí, selecione o executável ou a DLL do seu projeto.From there, select your project's executable or DLL.

Captura de tela do analisador de portabilidade do Gerenciador de Soluções.

Também é possível usar o aplicativo de console ApiPort.You can also use the ApiPort console app.

Digite o seguinte comando para analisar o diretório atual:Type the following command to analyze the current directory:

ApiPort.exe analyze -f .

Para analisar uma lista específica de arquivos. dll, digite o seguinte comando:To analyze a specific list of .dll files, type the following command:

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

Para direcionar uma versão específica, use o -t parâmetro:To target a specific version, use the -t parameter:

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

Execute ApiPort.exe -? para obter mais ajuda.Run ApiPort.exe -? to get more help.

É recomendável que você inclua todos os arquivos exe e dll relacionados que você tem e que deseje portar e exclua os arquivos do qual seu aplicativo depende, mas que você não tem e não pode portar.It is recommended that you include all the related exe and dll files that you own and want to port, and exclude the files that your app depends on, but you don't own and can't port. Isso fará com que o relatório de portabilidade seja o mais relevante.This will give you most relevant portability report.

Exibir e interpretar o resultado da portabilidadeView and interpret portability result

Apenas as APIs que não são compatíveis com uma Plataforma de Destino são exibidas no relatório.Only APIs that are unsupported by a Target Platform appear in the report. Após executar a análise no Visual Studio, você verá o link do arquivo do relatório de portabilidade do .NET aparecer.After running the analysis in Visual Studio, you'll see your .NET Portability report file link pops up. Se você usou o aplicativo de console ApiPort, o relatório de portabilidade do .NET é salvo como um arquivo no formato especificado.If you used the ApiPort console app, your .NET Portability report is saved as a file in the format you specified. O padrão está em um arquivo Excel (.xlsx) em seu diretório atual.The default is in an Excel file (.xlsx) in your current directory.

Resumo de PortabilidadePortability Summary

Captura de tela do Resumo de portabilidade.

A seção Resumo de Portabilidade do relatório mostra o percentual de portabilidade para cada assembly incluído na execução.The Portability Summary section of the report shows the portability percentage for each assembly included in the run. No exemplo anterior, 71,24% das APIs do .NET Framework usadas no aplicativo svcutil estão disponíveis no .NET Core + Extensões de plataforma.In the previous example, 71.24% of the .NET Framework APIs used in the svcutil app are available in .NET Core + Platform Extensions. Se você executar a ferramenta Analisador de Portabilidade do .NET em vários assemblies, cada um deles deverá ter uma linha no relatório Resumo de Portabilidade.If you run the .NET Portability Analyzer tool against multiple assemblies, each assembly should have a row in the Portability Summary report.

DetalhesDetails

Captura de tela dos detalhes de portabilidade.

A seção de detalhes do relatório lista as APIs ausentes em qualquer uma das plataformas de destino selecionadas.The Details section of the report lists the APIs missing from any of the selected Targeted Platforms.

  • Tipo de destino: o tipo tem uma API ausente de uma Plataforma de DestinoTarget type: the type has missing API from a Target Platform
  • Membro de destino: o método está ausente de uma Plataforma de DestinoTarget member: the method is missing from a Target Platform
  • Nome do assembly: o assembly do .NET Framework no qual a API ausente reside.Assembly name: the .NET Framework assembly that the missing API lives in.
  • Cada uma das plataformas de destino selecionadas é uma coluna, como ".NET Core": o valor "sem suporte" significa que a API não tem suporte nesta plataforma de destino.Each of the selected Target Platforms is one column, such as ".NET Core": "Not supported" value means the API is not supported on this Target Platform.
  • Alterações recomendadas: a API ou a tecnologia recomendada para alterar.Recommended Changes: the recommended API or technology to change to. Atualmente, esse campo está vazio ou desatualizado para muitas APIs.Currently, this field is empty or out of date for many APIs. Devido ao grande número de APIs, temos um desafio significativo para mantê-lo atualizado.Due to the large number of APIs, we have a significant challenge to keep it up to date. Estamos examinando soluções alternativas para fornecer informações úteis aos clientes.We're looking at alternative solutions to provide helpful information to customers.

Assemblies AusentesMissing Assemblies

Captura de tela de assemblies ausentes.

Você pode encontrar uma seção Assemblies Ausentes em seu relatório.You may find a Missing Assemblies section in your report. Esta seção contém uma lista de assemblies que são referenciados por seus assemblies analisados e não foram analisados.This section contains a list of assemblies that are referenced by your analyzed assemblies and were not analyzed. Se for um assembly que você possui, inclua-o na execução do analisador de portabilidade de API para que você possa obter um relatório detalhado de portabilidade no nível de API para ele.If it's an assembly that you own, include it in the API portability analyzer run so that you can get a detailed, API-level portability report for it. Se for uma biblioteca de terceiros, verifique se há uma versão mais recente que dê suporte à sua plataforma de destino e considere mover para a versão mais recente.If it's a third-party library, check if there is a newer version that supports your target platform, and consider moving to the newer version. Eventualmente, a lista deve incluir todos os assemblies de terceiros dos quais seu aplicativo depende que tenham uma versão que dê suporte à sua plataforma de destino.Eventually, the list should include all the third-party assemblies that your app depends on that have a version supporting your target platform.

Para obter mais informações sobre o Analisador de Portabilidade do .NET, acesse a documentação do GitHub e assista ao vídeo A Brief Look at the .NET Portability Analyzer (Uma análise breve do Analisador de Portabilidade do .NET) do Channel 9.For more information on the .NET Portability Analyzer, visit the GitHub documentation and A Brief Look at the .NET Portability Analyzer Channel 9 video.