O Analisador de Portabilidade .NET

Nota

A porta da API foi preterida em favor da análise binária pelo Assistente de Atualização do .NET. O serviço de back-end da API Port foi encerrado, portanto, para usar a ferramenta, você deve usá-la offline. Para obter mais informações, consulte Leiame da porta da API do .NET.

Quer fazer com que as suas bibliotecas suportem multiplataforma? Quer ver quanto trabalho é necessário para fazer seu aplicativo .NET Framework ser executado no .NET Core? O .NET Portability Analyzer é uma ferramenta que analisa assemblies e fornece um relatório detalhado sobre APIs .NET que estão faltando para que os aplicativos ou bibliotecas sejam portáteis em suas plataformas .NET de destino especificadas. O Portability Analyzer é oferecido como uma extensão do Visual Studio, que analisa um assembly por projeto, e como um aplicativo de console ApiPort, que analisa assemblies por arquivos ou diretórios especificados.

Depois de converter seu projeto para direcionar a nova plataforma, como o .NET Core, você pode usar o analisador de compatibilidade de plataforma baseado em Roslyn para identificar APIs que geram PlatformNotSupportedException exceções e outros problemas de compatibilidade.

Objetivos comuns

• .NET Core: tem um design modular, suporta instalação lado a lado e destina-se a cenários de plataforma cruzada. A instalação lado a lado permite que você adote novas versões do .NET Core sem quebrar outros aplicativos. Se o seu objetivo é portar seu aplicativo para o .NET Core e oferecer suporte a várias plataformas, esse é o destino recomendado.
• .NET Standard: Inclui as APIs do .NET Standard disponíveis em todas as implementações do .NET. Se o seu objetivo é fazer com que sua biblioteca seja executada em todas as plataformas com suporte do .NET, esse é o destino recomendado.
• ASP.NET Core: Uma estrutura da Web moderna construída no .NET Core. Se o seu objetivo é portar seu aplicativo Web para o .NET Core para oferecer suporte a várias plataformas, esse é o destino recomendado.
• .NET Core + Extensões de Plataforma: Inclui as APIs do .NET Core, além do Pacote de Compatibilidade do Windows, que fornece muitas das tecnologias disponíveis do .NET Framework. Este é um destino recomendado para portar seu aplicativo do .NET Framework para o .NET Core no Windows.
• .NET Standard + Platform Extensions: Inclui as APIs do .NET Standard além do Pacote de Compatibilidade do Windows, que fornece muitas das tecnologias disponíveis do .NET Framework. Este é um destino recomendado para portar sua biblioteca do .NET Framework para o .NET Core no Windows.

Como usar o .NET Portability Analyzer

Para começar a usar o .NET Portability Analyzer no Visual Studio, primeiro você precisa baixar e instalar a extensão do Visual Studio Marketplace. Ele funciona nas versões Visual Studio 2017 e Visual Studio 2019.

Importante

O .NET Portability Analyzer não é suportado no Visual Studio 2022.

Configure-o no Visual Studio por meio de Analyze>Portability Analyzer Settings e selecione suas Plataformas de Destino, que são as plataformas/versões .NET que você deseja avaliar as lacunas de portabilidade em comparação com a plataforma/versão com a qual seu assembly atual foi criado.

Você também pode usar o aplicativo de console ApiPort, baixá-lo do repositório ApiPort. Você pode usar listTargets a opção de comando para exibir a lista de destino disponível e, em seguida, escolher plataformas de destino especificando -t ou --target opção de comando.

Visão ampla da solução

Uma etapa útil na análise de uma solução com muitos projetos seria visualizar as dependências para entender qual subconjunto de assemblies depende de quê. A recomendação geral é aplicar os resultados da análise numa abordagem ascendente, começando com os nós foliares num gráfico de dependência.

Para recuperar isso, você pode executar o seguinte comando:

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

Um resultado disso seria semelhante ao seguinte quando aberto no Visual Studio:

Analise a portabilidade

Para analisar todo o seu projeto no Visual Studio, clique com o botão direito do mouse em seu projeto no Gerenciador de Soluções e selecione Analisar Portabilidade de Assembly. Caso contrário, vá para o menu Analisar e selecione Analisar Portabilidade de Montagem. A partir daí, selecione o executável ou a DLL do seu projeto.

Você também pode usar o aplicativo de console ApiPort.

Digite o seguinte comando para analisar o diretório atual:

ApiPort.exe analyze -f .

Para analisar uma lista específica de arquivos de .dll, digite o seguinte comando:

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

Para direcionar uma versão específica, use o -t parâmetro:

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

Corra ApiPort.exe -? para obter mais ajuda.

É recomendável que você inclua todos os arquivos exe e dll relacionados que você possui e deseja portar e exclua os arquivos dos quais seu aplicativo depende, mas você não possui e não pode portar. Isso lhe dará o relatório de portabilidade mais relevante.

Visualizar e interpretar o resultado da portabilidade

Somente as APIs que não são suportadas por uma plataforma de destino aparecem no relatório. Depois de executar a análise no Visual Studio, você verá o link do arquivo de relatório de portabilidade do .NET aparece. Se você usou o aplicativo de console ApiPort, seu relatório de Portabilidade .NET será salvo como um arquivo no formato especificado. O padrão está em um arquivo do Excel (.xlsx) no diretório atual.

Resumo da portabilidade

A seção Resumo de Portabilidade do relatório mostra a porcentagem de portabilidade para cada assembly incluído na execução. No exemplo anterior, 71,24% das APIs do .NET Framework usadas no svcutil aplicativo estão disponíveis no .NET Core + Platform Extensions. Se você executar a ferramenta .NET Portability Analyzer em vários assemblies, cada assembly deverá ter uma linha no relatório Resumo da Portabilidade.

Detalhes

A seção Detalhes do relatório lista as APIs ausentes em qualquer uma das Plataformas de Destino selecionadas.

• Tipo de destino: o tipo tem API ausente de uma plataforma de destino
• Membro de destino: o método está ausente de uma plataforma de destino
• Nome do assembly: o assembly do .NET Framework no qual a API ausente vive.
• Cada uma das Plataformas de Destino selecionadas é uma coluna, como ".NET Core": o valor "Não suportado" significa que a API não é suportada nesta Plataforma de Destino.
• Alterações recomendadas: a API ou tecnologia recomendada para a qual mudar. Atualmente, esse campo está vazio ou desatualizado para muitas APIs. Devido ao grande número de APIs, temos um desafio significativo para mantê-lo atualizado. Estamos procurando soluções alternativas para fornecer informações úteis aos clientes.

Montagens ausentes

Você pode encontrar uma seção Montagens ausentes em seu relatório. Esta seção contém uma lista de assemblies que são referenciados pelos assemblies analisados e não foram analisados. Se for um assembly de sua propriedade, inclua-o na execução do analisador de portabilidade de API para que você possa obter um relatório de portabilidade detalhado em nível de API para ele. Se for uma biblioteca de terceiros, verifique se há uma versão mais recente que suporte sua plataforma de destino e considere mudar para a versão mais recente. Eventualmente, a lista deve incluir todos os assemblies de terceiros dos quais seu aplicativo depende que têm uma versão que suporte sua plataforma de destino.

Para obter mais informações sobre o .NET Portability Analyzer, visite a documentação do GitHub.