Analisar suas dependências para o código de porta de .NET Framework para .NET

  • Artigo

Para identificar as dependências de terceiros sem suporte em seu projeto, primeiro você deve entender suas dependências. As dependências externas são os pacotes NuGet ou arquivos .dll que você faz referência em seu projeto, mas que você não compila.

A portabilidade do código para o .NET Standard 2.0 ou abaixo garante que ele possa ser usado com .NET Framework e .NET. No entanto, se você não precisar usar a biblioteca com .NET Framework, considere direcionar a versão mais recente do .NET.

Migrar seus pacotes NuGet para PackageReference

O .NET não pode usar o arquivo packages.config para referências do NuGet. O .NET e o .NET Framework podem usar PackageReference para especificar dependências de pacote. Se você estiver usando packages.config para especificar seus pacotes em seu projeto, converta-os no formato PackageReference.

Para saber como migrar, consulte o artigo Migrar de packages.config para PackageReference.

Atualizar seus pacotes NuGet

Depois de migrar seu projeto para o formato PackageReference, verifique se os pacotes são compatíveis com o .NET.

Primeiro, atualize seus pacotes para a versão mais recente que puder. Isso pode ser feito com a interface do usuário do Gerenciador de pacotes do NuGet no Visual Studio. É provável que as versões mais recentes das dependências do pacote já sejam compatíveis com o .NET Core.

Analisar as dependências do pacote

Se você ainda não verificou se as dependências do seu pacote convertido e atualizado funcionam no .NET Core, existem duas maneiras de alcançar isso:

Usar o nuget.org

Você pode ver os Monikers de Estrutura de Destino (TFMs) que são compatíveis com cada pacote em nuget.org, na seção Dependências da página do pacote.

Embora o uso do site seja um método mais fácil para verificar a compatibilidade, as informações de Dependências não estão disponíveis no site para todos os pacotes.

Usar o Explorador de Pacotes do NuGet

Um pacote NuGet é um conjunto de pastas que contêm assemblies específicos de plataforma. Verifique se há uma pasta que contém um assembly compatível dentro do pacote.

A maneira mais fácil de inspecionar a pastas do pacote NuGet é usar a ferramenta Explorador de Pacotes NuGet. Depois da instalação, use as seguintes etapas para ver os nomes de pasta:

  1. Abra o Explorador de Pacotes NuGet.
  2. Clique em Abrir pacote de feed online.
  3. Pesquise o nome do pacote.
  4. Selecione o nome do pacote nos resultados da pesquisa e clique em abrir.
  5. Expanda a pasta lib no lado direito e observe os nomes de pasta.

Procure uma pasta com nomes usando um dos seguintes padrões: netstandardX.Y, netX.You netcoreappX.Y.

Esses valores são os TFMs (Monikers de Estrutura de Destino) que são mapeados para versões do .NET Standard,.NET e .NET Core, que são todos compatíveis com o .NET.

Importante

Ao examinar os TFMs compatíveis com um pacote, observe que um TFM diferente de netstandard* direciona uma implementação específica do .NET, como .NET 5, .NET Core ou .NET Framework. A partir do .NET 5, o TFM net* (sem uma designação de sistema operacional) substitui efetivamente netstandard* como um destino portátil. Por exemplo, net5.0 tem como alvo a superfície da API do .NET 5 e é amigável entre plataformas, mas net5.0-windows tem como alvo a superfície da API do .NET 5, conforme implementado no sistema operacional Windows.

Modo de compatibilidade do .NET framework

Depois de analisar os pacotes do NuGet, você pode chegar à conclusão de que eles se destinam apenas ao .NET Framework.

O modo de compatibilidade do .NET Framework foi introduzido a partir do .NET Standard 2.0. Esse modo de compatibilidade permite que os projetos do .NET Standard e do .NET Core referenciem bibliotecas do .NET Framework. Fazer referência a bibliotecas do .NET Framework não funciona para todos os projetos, como nos casos em que a biblioteca usa APIs do WPF (Windows Presentation Foundation), mas isso desbloqueia muitos cenários de portabilidade.

Ao fazer referência a pacotes NuGet que se destinam ao .NET Framework em seu projeto, como Huitian.PowerCollections, você receberá um aviso de fallback do pacote (NU1701) semelhante ao exemplo a seguir:

NU1701: Package ‘Huitian.PowerCollections 1.0.0’ was restored using ‘.NETFramework,Version=v4.6.1’ instead of the project target framework ‘.NETStandard,Version=v2.0’. This package may not be fully compatible with your project.

Esse aviso será exibido quando você adicionar o pacote e sempre que você compilar, para que você não se esqueça de testar o pacote com o projeto. Se o projeto funcionar como esperado, você pode suprimir esse aviso, editando as propriedades do pacote no Visual Studio ou editando manualmente o arquivo de projeto em seu editor de código favorito.

Para suprimir o aviso editando o arquivo de projeto, localize a entrada PackageReference do pacote em que você deseja suprimir o aviso e adicione o atributo NoWarn. O atributo NoWarn aceita uma lista separada por vírgulas de todas as IDs de aviso. O exemplo a seguir mostra como suprimir o aviso NU1701 do pacote Huitian.PowerCollections por meio da edição manual do arquivo de projeto:

<ItemGroup>
  <PackageReference Include="Huitian.PowerCollections" Version="1.0.0" NoWarn="NU1701" />
</ItemGroup>

Para obter mais informações sobre como suprimir avisos do compilador no Visual Studio, consulte Suprimir avisos de pacotes NuGet.

Se os pacotes NuGet não forem executados no .NET

Há algumas coisas que você pode fazer se um pacote NuGet do qual você depende não for executado no .NET Core:

  • Se o projeto for um software livre e estiver hospedado em algum lugar como o GitHub, você poderá entrar em contato diretamente com os desenvolvedores.
  • Você pode contatar o autor diretamente em nuget.org procurando o pacote e clicando em Contact Owners (Entre em contato com os proprietários) no lado esquerdo da página do pacote.
  • Você pode pesquisar outro pacote que seja executado no .NET Core e realize a mesma tarefa que o pacote que você estava usando.
  • Você pode tentar escrever por conta própria o código do que o pacote estava fazendo.
  • Você pode eliminar a dependência do pacote alterando a funcionalidade do aplicativo, pelo menos até que uma versão compatível do pacote fique disponível.

Lembre-se que os mantenedores de projetos de software livre e os editores de pacote NuGet geralmente são voluntários. Elas contribuem porque se importam com um determinado domínio, fazem-no gratuitamente e geralmente têm um trabalho diferente durante dia. Lembre-se disso ao entrar em contato com eles para solicitar suporte para o .NET Core.

Se você não puder resolver o problema com nenhuma dessas opções, talvez seja necessário realizar a portabilidade para o .NET Core posteriormente.

A equipe do .NET gostaria de saber quais bibliotecas são as mais importantes para compatibilidade com o .NET Core. Você pode enviar um email para dotnet@microsoft.com, informando sobre as bibliotecas que você deseja usar.

Analisar dependências não NuGet

Você pode ter uma dependência que não seja um pacote NuGet, tal como uma DLL no sistema de arquivos. Você pode determinar a portabilidade dessa dependência usando a funcionalidade de análise binária do Assistente de Atualização do .NET.

Próximas etapas