O .NET Portability Analyzer

Importante

A porta da API foi preterida em favor da análise binária com a ferramenta .NET Upgrade Assistant . O serviço de back-end da Porta de API foi desligado; portanto, para usar a ferramenta, você deve estar offline. Para obter mais informações, confira LEIA-ME da Porta da API do .NET.

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 é um aplicativo de console 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: tem um design modular, dá suporte à instalação lado a lado e direciona cenários multiplataforma. A instalação lado a lado permite que você adote novas versões do .NET sem interromper outros aplicativos. Se sua meta for portar seu aplicativo para o .NET e dar 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.
• ASP.NET Core: uma estrutura da Web moderna criada no .NET. Se sua meta é portar seu aplicativo Web para o .NET (Core) para dar suporte a várias plataformas, esse é o destino recomendado.
• Extensões da plataforma .NET + : inclui as APIs do .NET, além do Pacote de Compatibilidade do Windows, que fornece muitas das tecnologias específicas do .NET Framework do Windows.
• Extensões de plataforma do .NET Standard + : inclui as APIs do .NET Standard, além do Pacote de Compatibilidade do Windows, que fornece muitas das tecnologias específicas do .NET Framework do Windows.

Como usar o Analisador de Portabilidade do .NET

Para começar a usar o Analisador de Portabilidade do .NET no Visual Studio, primeiro você precisa clonar e compilar o projeto dotnet-apiport. Ele funciona nas versões 2017 e 2019 do Visual Studio.

Importante

Não há suporte para o Analisador de Portabilidade do .NET no Visual Studio 2022.

Visão abrangente da solução

Uma etapa útil na análise de uma solução com muitos projetos é 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, execute 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

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

ApiPort.exe analyze -f .

Para analisar uma lista específica de arquivos .dll, insira 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ê possui e deseja portar, e excluir os arquivos dos quais seu aplicativo depende, mas que você não possui 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. Seu 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 da 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 desafio significativo mantê-la atualizada.

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.

Consulte também

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