Visão geral da portabilidade do .NET Framework para o .NET CoreOverview of porting from .NET Framework to .NET Core

Você pode ter um código que atualmente é executado no .NET Framework que você está interessado em portar para o .NET Core.You might have code that currently runs on the .NET Framework that you're interested in porting to .NET Core. Esse artigo fornece:This article provides:

  • Uma visão geral do processo de portabilidade.An overview of the porting process.
  • Uma lista de ferramentas que você pode achar útil quando está portando seu código para o .NET Core.A list of tools that you may find helpful when you're porting your code to .NET Core.

Visão geral do processo de portabilidadeOverview of the porting process

Portar para o .NET Core (ou .NET Standard) de .NET Framework para muitos projetos é relativamente simples.Porting to .NET Core (or .NET Standard) from .NET Framework for many projects is relatively straight forward. Há várias alterações que são necessárias, mas muitas delas seguem os padrões descritos abaixo.There are a number of changes that are required, but many of them follow the patterns outlined below. Os projetos em que o modelo de aplicativo está disponível no .NET Core (como bibliotecas, aplicativos de console e aplicativos de área de trabalho) geralmente exigem pouca alteração.Projects where the app-model is available in .NET Core (such as libraries, console apps, and desktop applications) usually require little changes. Os projetos que exigem um novo modelo de aplicativo, como a mudança para ASP.NET Core de ASP.NET, exigem um pouco mais de trabalho, mas muitos padrões têm analogias que podem ser usadas durante a conversão.Projects that require a new app model, such as moving to ASP.NET Core from ASP.NET, require a bit more work, but many patterns have analogs that can be used during the conversion. Este documento deve ajudar a identificar as principais estratégias que foram empregadas pelos usuários para converter com êxito suas bases de código para o destino .NET Standard ou o .NET Core e abordarão a conversão em dois níveis: toda a solução e o projeto específico.This document should help with identifying the main strategies that have been employed by users to successfully convert their code bases to target .NET Standard or .NET Core and will address the conversion at two levels: solution-wide and project specific. Consulte os links na parte inferior para obter instruções sobre conversões específicas de modelo de aplicativo.See the links at the bottom for directions on app-model specific conversions.

Recomendamos que você use o processo a seguir ao portar seu projeto para o .NET Core.We recommend you use the following process when porting your project to .NET Core. Cada uma dessas etapas introduz possíveis locais para alterações de comportamento, portanto, certifique-se de testar adequadamente sua biblioteca ou aplicativo antes de continuar em etapas posteriores.Each of these steps introduces potential places for behavior changes, so ensure that you adequately test your library or application before continuing on to later steps. As primeiras etapas são preparar seu projeto para um comutador para .NET Standard ou para o .NET Core.The first steps are to get your project ready for a switch to .NET Standard or .NET Core. Se você tiver testes de unidade, será melhor convertê-los primeiro para que você possa continuar testando as alterações no produto em que está trabalhando.If you have unit tests, it's best to convert them first so that you can continue testing changes in the product you're working on. Como a portabilidade para o .NET Core é uma alteração significativa na base de código, é altamente recomendável portar seus projetos de teste para que você possa executar testes à medida que você portar seu código.Because porting to .NET Core is such a significant change to your codebase, it's highly recommended to port your test projects so that you can run tests as you port your code over. MSTest, xUnit e NUnit funcionam no .NET Core.MSTest, xUnit, and NUnit all work on .NET Core.

IntroduçãoGetting started

As ferramentas a seguir serão usadas em todo o processo:The following tools will be used throughout the process:

Portando uma soluçãoPorting a solution

Quando há vários projetos em uma solução, a portabilidade pode parecer mais complicada porque você deve tratar projetos em uma ordem específica.When there are multiple projects in a solution, the porting can seem more complicated because you must address projects in a specific order. O processo de conversão deve ser uma abordagem de baixo para cima, em que os projetos sem dependências em outros projetos na solução são convertidos primeiro e continuam em toda a solução.The conversion process should be a bottom-up approach, where the projects with no dependencies on other projects in the solution are converted first, and continue up through the whole solution.

Para identificar a ordem em que os projetos devem ser migrados, você pode usar as seguintes ferramentas:In order to identify the order projects should be migrated, you can use the following tools:

  • Os diagramas de dependência no Visual Studio podem criar um grafo direcionado do código em uma solução.Dependency Diagrams in Visual Studio can create a directed graph of the code in a solution.
  • Execute msbuild _SolutionPath_ /t:GenerateRestoreGraphFile /p:RestoreGraphOutputPath=graph.dg.json para gerar um documento JSON que inclui a lista de referências do projeto.Run msbuild _SolutionPath_ /t:GenerateRestoreGraphFile /p:RestoreGraphOutputPath=graph.dg.json to generate a json document that includes list of project references.

Etapas por projetoPer project steps

Recomendamos que você use o seguinte processo ao portar seu projeto para o .NET Core:We recommend you use the following process when porting your project to .NET Core:

  1. Converta todas as packages.config suas dependências para o formato PackageReference com a ferramenta de conversão no Visual Studio.Convert all of your packages.config dependencies to the PackageReference format with the conversion tool in Visual Studio.

    Esta etapa envolve a conversão de suas dependências packages.config do formato herdado.This step involves converting your dependencies from the legacy packages.config format. packages.configNão funciona no .NET Core, portanto, essa conversão será necessária se você tiver dependências de pacote.packages.config doesn't work on .NET Core, so this conversion is required if you have package dependencies. Ele também requer apenas as dependências que você está usando diretamente em um projeto, o que facilita mais as etapas, reduzindo o número de dependências que você deve gerenciar.It also only requires the dependencies you are directly using in a project, which makes later steps easier by reducing the number of dependencies you must manage.

  2. Converta o arquivo de projeto para a nova estrutura de arquivos em estilo SDK.Convert your project file to the new SDK-style files structure. Você pode criar novos projetos para o .NET Core e copiar sobre os arquivos de origem, ou tentar converter o arquivo de projeto existente com uma ferramenta.You can create new projects for .NET Core and copy over source files, or attempt to convert your existing project file with a tool.

    O .NET Core usa um formato de arquivo de projeto simplificado (e diferente) do que o .NET Framework..NET Core uses a simplified (and different) project file format than .NET Framework. Você precisará converter os arquivos de projeto nesse formato para continuar.You'll need to convert your project files into this format to continue. Este estilo de projeto permite que você também direcione .NET Framework, que neste ponto você ainda desejará direcionar.This project style allows you to also target .NET Framework, which at this point you'll still want to target.

    Você pode tentar portar soluções menores ou projetos individuais em uma operação para o formato de arquivo de projeto do .NET Core com a ferramenta dotnet try-Convert .You can attempt to port smaller solutions or individual projects in one operation to the .NET Core project file format with the dotnet try-convert tool. dotnet try-convertNão tem garantia de funcionar para todos os seus projetos e pode causar alterações sutis no comportamento que você dependou.dotnet try-convert is not guaranteed to work for all your projects, and it may cause subtle changes in behavior that you depended on. Use-o como um ponto de partida que automatize as coisas básicas que podem ser automatizadas.Use it as a starting point that automates the basic things that can be automated. Não é uma solução garantida para migrar um projeto, pois há muitas diferenças nos destinos usados pelos projetos de estilo do SDK em comparação com os arquivos de projeto de estilo antigo.It isn't a guaranteed solution to migrating a project, as there are many differences in the targets used by the SDK style projects compared to the old-style project files.

  3. Redirecione todos os projetos que você deseja que a porta direcione .NET Framework 4.7.2 ou superior.Retarget all projects you wish to port to target .NET Framework 4.7.2 or higher.

    Essa etapa garante que você possa usar alternativas de API para destinos específicos do .NET Framework quando o .NET Core não oferecer suporte a determinada API.This step ensures that you can use API alternatives for .NET Framework-specific targets when .NET Core doesn't support a particular API.

  4. Atualize todas as dependências para a versão mais recente.Update all dependencies to the latest version. Os projetos podem estar usando versões mais antigas de bibliotecas que podem não ter suporte .NET Standard.Projects may be using older versions of libraries that may not have .NET Standard support. No entanto, as versões posteriores podem dar suporte a ela com um comutador simples.However, later versions may support it with a simple switch. Isso pode exigir alterações de código se houver alterações significativas nas bibliotecas.This may require code changes if there are breaking changes in libraries.

  5. Use o .net Portability Analyzer para analisar seus assemblies e ver se eles são portáteis para o .NET Core.Use the .NET Portability Analyzer to analyze your assemblies and see if they're portable to .NET Core.

    A ferramenta Analisador de portabilidade .NET analisa seus assemblies compilados e gera um relatório.The .NET Portability Analyzer tool analyzes your compiled assemblies and generates a report. Este relatório mostra um resumo de portabilidade de alto nível e uma análise de cada API que você está usando e que não está disponível no núcleo da rede.This report shows a high-level portability summary and a breakdown of each API you're using that isn't available on NET Core. Ao usar a ferramenta, envie apenas o projeto individual que você está convertendo para se concentrar nas alterações da API que são potencialmente necessárias.While using the tool, only submit the individual project you are converting to focus on the API changes that are potentially needed. Muitas das APIs têm disponibilidade equivalente no .NET Core, para a qual você vai querer alternar.Many of the APIs have equivalent availability in .NET Core, which you'll want to switch to.

    Ao ler os relatórios gerados pelo analisador, as informações importantes são as APIs reais que estão sendo usadas e não necessariamente a porcentagem de suporte para a plataforma de destino.While reading the reports generated by the analyzer, the important information is the actual APIs that are being used and not necessarily the percentage of support for the target platform. Muitas APIs têm opções equivalentes no .NET Standard/Core e, portanto, entender os cenários de que sua biblioteca ou aplicativo precisa para a API ajudará a determinar a implicação da portabilidade.Many APIs have equivalent options in .NET Standard/Core, and so understanding the scenarios your library or application needs the API for will help determine the implication for portability.

    Há alguns casos em que as APIs não são equivalentes e você precisará fazer algumas diretivas de pré-processador do compilador (ou seja #if NET45,) para o caso especial das plataformas.There are some cases where APIs are not equivalent and you'll need to do some compiler preprocessor directives (that is, #if NET45) to special case the platforms. Neste ponto, seu projeto ainda será direcionado .NET Framework.At this point, your project will still be targeting .NET Framework. Para cada um desses casos de destino, é recomendável usar condicionais bem conhecidos que podem ser compreendidos como um cenário.For each of these targeted cases, it is recommended to use well-known conditionals that can be understood as a scenario. Por exemplo, o suporte a AppDomain no .NET Core é limitado, mas para o cenário de carregamento e descarregamento de assemblies, há uma nova API que não está disponível no .NET Core.For example, AppDomain support in .NET Core is limited, but for the scenario of loading and unloading assemblies, there is a new API that's not available in .NET Core. Uma maneira comum de lidar com isso no código seria algo assim:A common way to handle this in code would be something like this:

    #if FEATURE_APPDOMAIN_LOADING
    // Code that uses appdomains
    #elif FEATURE_ASSEMBLY_LOAD_CONTEXT
    // Code that uses assembly load context
    #else
    #error Unsupported platform
    #endif
    
  6. Instale o .NET API Analyzer em seus projetos para identificar as APIs que PlatformNotSupportedException lançam em algumas plataformas e outros problemas de compatibilidade em potencial.Install the .NET API analyzer into your projects to identify APIs that throw PlatformNotSupportedException on some platforms and some other potential compatibility issues.

    Essa ferramenta é semelhante ao analisador de portabilidade, mas em vez de analisar se o código pode ser criado no .NET Core, ele analisa se você está usando uma API de uma forma que PlatformNotSupportedException gerará um em tempo de execução.This tool is similar to the portability analyzer, but instead of analyzing if code can build on .NET Core, it analyzes whether you're using an API in a way that will throw a PlatformNotSupportedException at run time. Embora isso não seja comum se você estiver mudando de .NET Framework 4.7.2 ou superior, é bom verificar.Although this isn't common if you're moving from .NET Framework 4.7.2 or higher, it's good to check. Para obter mais informações sobre APIs que lançam exceções no .NET Core, consulte APIs que sempre lançam exceções no .NET Core.For more information about APIs that throw exceptions on .NET Core, see APIs that always throw exceptions on .NET Core.

  7. Neste ponto, você pode mudar para direcionar o .NET Core (geralmente para aplicativos) ou .NET Standard (para bibliotecas).At this point, you can switch to targeting .NET Core (generally for applications) or .NET Standard (for libraries).

    A escolha entre o .NET Core e o .NET Standard é amplamente dependente de onde o projeto será executado.The choice between .NET Core and .NET Standard is largely dependent on where the project will be run. Se for uma biblioteca que será consumida por outros aplicativos ou distribuída via NuGet, a preferência geralmente será direcionada .NET Standard.If it is a library that will be consumed by other applications or distributed via NuGet, the preference is usually to target .NET Standard. No entanto, pode haver APIs que só estão disponíveis no .NET Core para fins de desempenho ou outros motivos; Se esse for o caso, o .NET Core deve ser direcionado com uma compilação potencialmente .NET Standard disponível, bem como desempenho ou funcionalidade reduzidos.However, there may be APIs that are only available on .NET Core for performance or other reasons; if that's the case, .NET Core should be targeted with potentially a .NET Standard build available as well with reduced performance or functionality. Ao direcionar .NET Standard, o projeto estará pronto para ser executado em novas plataformas (como Webassembly).By targeting .NET Standard, the project will be ready to run on new platforms (such as WebAssembly). Se o projeto tiver dependências em estruturas de aplicativo específicas (como ASP.NET Core), o destino será limitado pelo que as dependências dão suporte.If the project has dependencies on specific app frameworks (such as ASP.NET Core), then the target will be limited by what the dependencies support.

    Se não houver diretivas de pré-processador para o código de compilação condicional para .NET Framework ou .NET Standard, isso será tão simples quanto encontrar o seguinte no arquivo de projeto:If there are no preprocessor directives to conditional compile code for .NET Framework or .NET Standard, this will be as simple as finding the following in the project file:

    <TargetFramework>net472</TargetFramework>
    

    e alterne para a estrutura desejada.and switch it to the desired framework. Para o .NET Core 3,1, isso seria:For .NET Core 3.1, this would be:

    <TargetFramework>netcoreapp3.1</TargetFramework>
    

    No entanto, se esta for uma biblioteca para a qual você deseja continuar a dar suporte a compilações específicas de .NET Framework, você pode fazer vários destinos substituindo-o pelo seguinte:However, if this is a library for which you want to continue supporting .NET Framework-specific builds, you can multi-target by replacing it with the following:

    <TargetFrameworks>net472;netstandard2.0</TargetFrameworks>
    

    Se você estiver usando APIs específicas do Windows (como o acesso ao registro), instale o pacote de compatibilidade do Windows.If you're using Windows-specific APIs (such as registry access), install the Windows Compatibility Pack.

Próximas etapasNext steps