O .NET Portability Analyzer

Deseja fazer suas bibliotecas serem compatíveis com multiplataforma? Quer saber quanto trabalho é necessário para fazer seu aplicativo .NET Framework ser executado no .NET Core? O Analisador de Portabilidade do .NET é uma ferramenta que analisa assemblies e fornece um relatório detalhado sobre APIs .NET ausentes para que os aplicativos ou bibliotecas sejam portáteis em suas plataformas .NET de destino especificadas. O Analisador de Portabilidade é oferecido como uma Extensão do Visual Studio, que analisa assemblies por projeto, e como um aplicativo de console ApiPort, que analisa assemblies por arquivos ou diretório especificados.

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

Destinos comuns

• .NET Core: tem um design modular, é compatível com a instalação lado a lado e está direcionado a cenários de plataforma cruzada. A instalação lado a lado permite adotar novas versões do .NET Core sem interromper outros aplicativos. Se sua meta é portar seu aplicativo para o .NET Core e 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 sua meta é fazer sua biblioteca ser executada em todas as plataformas compatíveis com o .NET, esse é o destino recomendado.
• ASP.NET Core: uma estrutura da Web moderna desenvolvida com base no .NET Core. Se sua meta é portar seu aplicativo Web para o .NET Core para dar 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 oferece muitas das tecnologias disponíveis do .NET Framework. Esse é um destino recomendado para portar seu aplicativo do .NET Framework para o .NET Core no Windows.
• .NET Standard + Extensões de plataforma: inclui as APIs do .NET Standard, além do Pacote de Compatibilidade do Windows, que oferece muitas das tecnologias disponíveis do .NET Framework. Esse é um destino recomendado para portar sua biblioteca do .NET Framework para o .NET Core no Windows.

Como usar o Analisador de Portabilidade do .NET

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. Ele funciona nas versões 2017 e 2019 do Visual Studio.

É possível configurá-lo no Visual Studio acessando Analisar>Configurações do Analisador de Portabilidade e selecionando as Plataformas de Destino, que são as versões/plataformas do .NET para as quais você deseja avaliar as lacunas de portabilidade, comparando com a plataforma/versão com a qual seu assembly atual foi criado.

Também é possível usar o aplicativo de console ApiPort, baixando-o do repositório ApiPort. É 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.

Exibição de toda a 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 do quê. 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.

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:

Analisar portabilidade

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. Caso contrário, acesse o menu Analyze e selecione Analisar Portabilidade do Assembly. Em seguida, selecione o executável do seu projeto ou DLL.

Também é possível 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. 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 parâmetro -t:

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

Execute ApiPort.exe -? para obter mais ajuda.

É 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. Isso fará com que o relatório de portabilidade seja o mais relevante.

Exibir e interpretar o resultado da portabilidade

Apenas as APIs que não são compatíveis com uma Plataforma de Destino são exibidas no relatório. Após executar a análise no Visual Studio, você verá o link do arquivo do relatório de portabilidade do .NET aparecer. Se você usou o aplicativo de console ApiPort, o relatório de portabilidade do .NET é salvo como um arquivo no formato especificado. O padrão está em um arquivo Excel (.xlsx) em seu diretório atual.

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

Detalhes

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

• Tipo de destino: o tipo tem uma 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 reside.
• 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.
• Alterações recomendadas: a API ou a tecnologia recomendada para a qual alterar. No momento, esse campo está vazio ou desatualizado para muitas APIs. Devido ao grande número de APIs, é um grande desafio mantê-lo atualizado. Estamos examinando soluções alternativas para fornecer informações úteis aos clientes.

Assemblies Ausentes

Você pode encontrar uma seção Assemblies Ausentes em seu relatório. Esta seção contém uma lista dos assemblies que são referenciados pelos seus 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 no nível da API para ele. Se for uma biblioteca de terceiros, verifique se há uma versão mais recente que dá suporte à plataforma de destino e considere migrar para a versão mais recente. Por fim, seria esperado que essa lista incluísse todos os assemblies de terceiros do qual seu aplicativo depende que tivessem uma versão compatível com sua plataforma de destino.

Para mais informações sobre o Analisador de Portabilidade do .NET, consulte a Documentação do GitHub.