Como migrar um aplicativo de área de trabalho Windows Forms para o .NET 5How to migrate a Windows Forms desktop app to .NET 5

Este artigo descreve como migrar um aplicativo de área de trabalho Windows Forms do .NET Framework para o .NET 5 ou posterior.This article describes how to migrate a Windows Forms desktop app from .NET Framework to .NET 5 or later. O SDK do .NET inclui suporte para aplicativos Windows Forms.The .NET SDK includes support for Windows Forms applications. O Windows Forms ainda é uma estrutura somente do Windows e só é executado nessa plataforma.Windows Forms is still a Windows-only framework and only runs on Windows.

Migrar seu aplicativo do .NET Framework para o .NET 5 geralmente requer um novo arquivo de projeto.Migrating your app from .NET Framework to .NET 5 generally requires a new project file. O .NET 5 usa arquivos de projeto no estilo SDK, enquanto .NET Framework normalmente usa o arquivo de projeto do Visual Studio mais antigo..NET 5 uses SDK-style project files while .NET Framework typically uses the older Visual Studio project file. Se você já abriu um arquivo de projeto do Visual Studio em um editor de texto, saberá como ele é mais detalhado.If you've ever opened a Visual Studio project file in a text editor, you know how verbose it is. Os projetos de estilo SDK são menores e não exigem tantas entradas quanto o formato de arquivo de projeto mais antigo.SDK-style projects are smaller and don't require as many entries as the older project file format does.

Para saber mais sobre o .NET 5, consulte introdução ao .net.To learn more about .NET 5, see Introduction to .NET.

Pré-requisitosPrerequisites

ConsideraçõesConsider

Ao migrar um aplicativo .NET Framework Windows Forms, há algumas coisas que você deve considerar.When migrating a .NET Framework Windows Forms application, there are a few things you must consider.

  1. Verifique se o seu aplicativo é um bom candidato para a migração.Check that your application is a good candidate for migration.

    Use o .net Portability Analyzer para determinar se o seu projeto será migrado para o .NET 5.Use the .NET Portability Analyzer to determine if your project will migrate to .NET 5. Se o seu projeto tiver problemas com o .NET 5, o analisador o ajudará a identificar esses problemas.If your project has issues with .NET 5, the analyzer helps you identify those problems. A ferramenta do analisador de portabilidade .NET pode ser instalada como uma extensão do Visual Studio ou usada na linha de comando.The .NET Portability Analyzer tool can be installed as a Visual Studio extension or used from the command line. Para obter mais informações, consulte Analisador de Portabilidade do .NET.For more information, see .NET Portability Analyzer.

  2. Você está usando uma versão diferente do Windows Forms.You're using a different version of Windows Forms.

    Quando o .NET Core 3,0 foi lançado, Windows Forms tornou -se aberto no GitHub.When .NET Core 3.0 was released, Windows Forms went open source on GitHub. O código para Windows Forms para .NET 5 é uma bifurcação da base de código .NET Framework Windows Forms.The code for Windows Forms for .NET 5 is a fork of the .NET Framework Windows Forms codebase. É possível haver algumas diferenças e seu aplicativo será difícil de migrar.It's possible some differences exist and your app will be difficult to migrate.

  3. O Pacote de Compatibilidade do Windows pode ajudar você na migração.The Windows Compatibility Pack may help you migrate.

    Algumas APIs que estão disponíveis no .NET Framework não estão disponíveis no .NET 5.Some APIs that are available in .NET Framework aren't available in .NET 5. O pacote de compatibilidade do Windows adiciona muitas dessas APIs e pode ajudar seu Windows Forms aplicativo se tornar compatível com o .NET 5.The Windows Compatibility Pack adds many of these APIs and may help your Windows Forms app become compatible with .NET 5.

  4. Atualize os pacotes do NuGet usados pelo seu projeto.Update the NuGet packages used by your project.

    É sempre uma boa prática usar as versões mais recentes dos pacotes do NuGet antes de qualquer migração.It's always a good practice to use the latest versions of NuGet packages before any migration. Se seu aplicativo faz referência a pacotes do NuGet, atualize-os para a versão mais recente.If your application is referencing any NuGet packages, update them to the latest version. Certifique-se de que seu aplicativo foi compilado com êxito.Ensure your application builds successfully. Após a atualização, se houver erros de pacote, faça downgrade do pacote para a versão mais recente que não interrompa seu código.After upgrading, if there are any package errors, downgrade the package to the latest version that doesn't break your code.

Fazer backup de seus projetosBack up your projects

A primeira etapa para migrar um projeto é fazer backup de seu projeto!The first step to migrating a project is to back up your project! Se algo der errado, você poderá restaurar seu código para seu estado original restaurando o backup.If something goes wrong, you can restore your code to its original state by restoring your backup. Não confie em ferramentas como o .NET Portability Analyzer para fazer backup de seu projeto, mesmo que eles pareçam.Don't rely on tools such as the .NET Portability Analyzer to back up your project, even if they seem to. É melhor criar uma cópia do projeto original de forma pessoal.It's best to personally create a copy of the original project.

Pacotes NuGetNuGet packages

Se o seu projeto estiver fazendo referência a pacotes NuGet, você provavelmente terá um arquivo packages.config na pasta do projeto.If your project is referencing NuGet packages, you probably have a packages.config file in your project folder. Com os projetos em estilo SDK, as referências de pacote NuGet são configuradas no arquivo de projeto.With SDK-style projects, NuGet package references are configured in the project file. Os arquivos de projeto do Visual Studio podem opcionalmente definir pacotes NuGet no arquivo de projeto.Visual Studio project files can optionally define NuGet packages in the project file too. O .NET 5 não usa packages.config para pacotes NuGet..NET 5 doesn't use packages.config for NuGet packages. As referências de pacote NuGet devem ser migradas para o arquivo de projeto antes da migração.NuGet package references must be migrated into the project file before migration.

Para migrar o arquivo de packages.config , execute as seguintes etapas:To migrate the packages.config file, do the following steps:

  1. No Gerenciador de soluções, localize o projeto que você está migrando.In Solution explorer, find the project you're migrating.
  2. Clique com o botão direito do mouse em packages.config > migrar packages.config para PackageReference.Right-click on packages.config > Migrate packages.config to PackageReference.
  3. Selecione todos os pacotes de nível superior.Select all of the top-level packages.

Um relatório de compilação é gerado para informá-lo sobre quaisquer problemas de migração dos pacotes NuGet.A build report is generated to let you know of any issues migrating the NuGet packages.

Arquivo de projetoProject file

A próxima etapa na migração do aplicativo é converter o arquivo de projeto.The next step in migrating your app is converting the project file. Como mencionado anteriormente, o .NET 5 usa arquivos de projeto no estilo SDK e não carregará os arquivos de projeto do Visual Studio que o .NET Framework usa.As previously stated, .NET 5 uses SDK-style project files and won't load the Visual Studio project files that .NET Framework uses. No entanto, há a possibilidade de que você já esteja usando projetos em estilo SDK.However, there's the possibility that you're already using SDK-style projects. Você pode identificar facilmente a diferença no Visual Studio.You can easily spot the difference in Visual Studio. Clique com o botão direito do mouse no arquivo de projeto no Gerenciador de soluções e procure a opção de menu Editar arquivo de projeto .Right-click on the project file in Solution explorer and look for the Edit Project File menu option. Se esse item de menu estiver ausente, você estará usando o antigo formato de projeto do Visual Studio e precisará fazer a atualização.If this menu item is missing, you're using the old Visual Studio project format and need to upgrade.

Converta cada projeto em sua solução.Convert each project in your solution. Se você estiver usando o aplicativo de exemplo referenciado anteriormente, os projetos MatchingGame e MatchingGame. Logic seriam convertidos.If you're using the sample app previously referenced, both the MatchingGame and MatchingGame.Logic projects would be converted.

Para converter um projeto, execute as seguintes etapas:To convert a project, do the following steps:

  1. No Gerenciador de soluções, localize o projeto que você está migrando.In Solution explorer, find the project you're migrating.

  2. Clique com o botão direito do mouse no projeto e selecione descarregar projeto.Right-click on the project and select Unload Project.

  3. Clique com o botão direito do mouse no projeto e selecione Editar arquivo de projeto.Right-click on the project and select Edit Project File.

  4. Copie e cole o XML do projeto em um editor de texto.Copy-and-paste the project XML into a text editor. Você desejará uma cópia para que seja fácil mover o conteúdo para o novo projeto.You'll want a copy so that it's easy to move content into the new project.

  5. Apague o conteúdo do arquivo e cole o seguinte XML:Erase the content of the file and paste the following XML:

    <Project Sdk="Microsoft.NET.Sdk">
    
      <PropertyGroup>
        <OutputType>WinExe</OutputType>
        <TargetFramework>net5.0-windows</TargetFramework>
        <UseWindowsForms>true</UseWindowsForms>
        <GenerateAssemblyInfo>false</GenerateAssemblyInfo>
      </PropertyGroup>
    
    </Project>
    

    Importante

    As bibliotecas não precisam definir uma <OutputType> configuração.Libraries don't need to define an <OutputType> setting. Remova essa entrada se você estiver atualizando um projeto de biblioteca.Remove that entry if you're upgrading a library project.

Esse XML fornece a estrutura básica do projeto.This XML gives you the basic structure of the project. No entanto, ele não contém nenhuma das configurações do arquivo de projeto antigo.However, it doesn't contain any of the settings from the old project file. Usando as informações antigas do projeto que você copiou anteriormente para um editor de texto, execute as seguintes etapas:Using the old project information you previously copied to a text editor, do the following steps:

  1. Copie os seguintes elementos do arquivo de projeto antigo para o <PropertyGroup> elemento no novo arquivo de projeto:Copy the following elements from the old project file into the <PropertyGroup> element in the new project file:

    • <RootNamespace>
    • <AssemblyName>

    O arquivo de projeto deve ser semelhante ao seguinte XML:Your project file should look similar to the following XML:

    <Project Sdk="Microsoft.NET.Sdk">
    
      <PropertyGroup>
        <OutputType>WinExe</OutputType>
        <TargetFramework>net5.0-windows</TargetFramework>
        <UseWindowsForms>true</UseWindowsForms>
        <GenerateAssemblyInfo>false</GenerateAssemblyInfo>
    
        <RootNamespace>MatchingGame</RootNamespace>
        <AssemblyName>MatchingGame</AssemblyName>
      </PropertyGroup>
    
    </Project>
    
  2. Copie os <ItemGroup> elementos do arquivo de projeto antigo que contém <ProjectReference> ou <PackageReference> para o novo arquivo após a </PropertyGroup> marca de fechamento.Copy the <ItemGroup> elements from the old project file that contain <ProjectReference> or <PackageReference> into the new file after the </PropertyGroup> closing tag.

    O arquivo de projeto deve ser semelhante ao seguinte XML:Your project file should look similar to the following XML:

    <Project Sdk="Microsoft.NET.Sdk">
    
      <PropertyGroup>
        (contains settings previously described)
      </PropertyGroup>
    
      <ItemGroup>
        <ProjectReference Include="..\MatchingGame.Logic\MatchingGame.Logic.csproj">
          <Project>{36b3e6e2-a9ae-4924-89ae-7f0120ce08bd}</Project>
          <Name>MatchingGame.Logic</Name>
        </ProjectReference>
      </ItemGroup>
      <ItemGroup>
        <PackageReference Include="MetroFramework">
          <Version>1.2.0.3</Version>
        </PackageReference>
      </ItemGroup>
    
    </Project>
    

    Os <ProjectReference> elementos não precisam dos <Project> <Name> filhos e, portanto, você pode remover essas configurações:The <ProjectReference> elements don't need the <Project> and <Name> children, so you can remove those settings:

    <ItemGroup>
      <ProjectReference Include="..\MatchingGame.Logic\MatchingGame.Logic.csproj" />
    </ItemGroup>
    

Recursos e configuraçõesResources and settings

Uma coisa a ser observada sobre a diferença entre .NET Framework projetos e os projetos no estilo SDK usados pelo .NET 5 é que .NET Framework projetos usam um modelo de aceitação para arquivos de código.One thing to note about the difference between .NET Framework projects and the SDK-style projects used by .NET 5 is that .NET Framework projects use an opt-in model for code files. Qualquer arquivo de código que você queira compilar precisa ser explicitamente definido em seu arquivo de projeto.Any code file you want to compile needs to be explicitly defined in your project file. Os projetos no estilo SDK são invertidos; eles assumem como padrão o comportamento de recusa: todos os arquivos de código iniciados no diretório do projeto e abaixo são incluídos automaticamente no seu projeto.SDK-style projects are reverse, they default to opt-out behavior: All code files starting from the project's directory and below are automatically included in your project. Você não precisará migrar essas entradas se elas forem simples e sem configurações.You don't need to migrate these entries if they are simple and without settings. Isso é o mesmo para outros arquivos comuns, como resx.This is the same for other common files such as resx.

Windows Forms projetos também incluem arquivos específicos de projeto do Windows Form, como Properties/Settings. Settings e Properties/Resources. resx.Windows Forms projects also include Windows Form project specific files, such as Properties/Settings.settings and Properties/Resources.resx. Esses arquivos podem precisar ser migrados. eles são declarados em seu projeto original.These files may need to be migrated they are declared in your original project.

Copie essas entradas do arquivo de projeto antigo em um <ItemGroup> elemento no novo projeto.Copy those entries from the old project file into an <ItemGroup> element in the new project. Depois de copiar as entradas, altere todos os <Compile Include="value"> elementos para, em vez disso, use o Update atributo em vez de Include .After you copy the entries, change all <Compile Include="value"> elements to instead use the Update attribute instead of Include.

  • Importe a configuração do arquivo Settings. Settings .Import the configuration for the Settings.settings file.

    <ItemGroup>
      <None Include="Properties\Settings.settings">
        <Generator>SettingsSingleFileGenerator</Generator>
        <LastGenOutput>Settings.Designer.cs</LastGenOutput>
      </None>
      <Compile Update="Properties\Settings.Designer.cs">
        <AutoGen>True</AutoGen>
        <DependentUpon>Settings.settings</DependentUpon>
        <DesignTimeSharedInput>True</DesignTimeSharedInput>
      </Compile>
    </ItemGroup>
    

    Observe que a entrada Properties\Settings.Settings permaneceu Include .Notice that the Properties\Settings.settings entry remained Include. O projeto não inclui automaticamente os arquivos de configuração .The project doesn't automatically include settings files.

    Importante

    Os projetos de Visual Basic normalmente usam a pasta meu projeto enquanto projetos C# normalmente usam as Propriedades de pasta para o arquivo de configurações de projeto padrão.Visual Basic projects typically use the folder My Project while C# projects typically use the folder Properties for the default project settings file.

  • Importe a configuração para qualquer arquivo resx , como o arquivo Properties/Resources. resx .Import the configuration for any resx file, such as the properties/Resources.resx file. Observe que o Include atributo foi definido como Update no <Compile> elemento e <EmbeddedResource> e <SubType> foi removido de <EmbeddedResource> :Notice that the Include attribute was set to Update on the <Compile> and <EmbeddedResource> element, and <SubType> was removed from <EmbeddedResource>:

    <ItemGroup>
      <EmbeddedResource Update="Properties\Resources.resx">
        <Generator>ResXFileCodeGenerator</Generator>
        <LastGenOutput>Resources.Designer.cs</LastGenOutput>
      </EmbeddedResource>
      <Compile Update="Properties\Resources.Designer.cs">
        <AutoGen>True</AutoGen>
        <DependentUpon>Resources.resx</DependentUpon>
        <DesignTime>True</DesignTime>
      </Compile>
    </ItemGroup>
    

    Importante

    Os projetos de Visual Basic normalmente usam a pasta meu projeto enquanto projetos C# normalmente usam as Propriedades de pasta para o arquivo de recurso de projeto padrão.Visual Basic projects typically use the folder My Project while C# projects typically use the folder Properties for the default project resource file.

Visual BasicVisual Basic

Visual Basic projetos de idioma exigem configuração adicional.Visual Basic language projects require extra configuration.

  1. Importe a configuração do arquivo de configuração My Project\Application.MyApp .Import the configuration file My Project\Application.myapp setting. Observe que o <Compile> elemento usa o Update atributo em vez do Include atributo.Notice that the <Compile> element uses the Update attribute instead of the Include attribute.

    <ItemGroup>
      <None Include="My Project\Application.myapp">
        <Generator>MyApplicationCodeGenerator</Generator>
        <LastGenOutput>Application.Designer.vb</LastGenOutput>
      </None>
      <Compile Update="My Project\Application.Designer.vb">
        <AutoGen>True</AutoGen>
        <DependentUpon>Application.myapp</DependentUpon>
        <DesignTime>True</DesignTime>
      </Compile>
    </ItemGroup>
    
  2. Adicione a <MyType>WindowsForms</MyType> configuração ao <PropertyGroup> elemento:Add the <MyType>WindowsForms</MyType> setting to the <PropertyGroup> element:

    <PropertyGroup>
      (contains settings previously described)
    
      <MyType>WindowsForms</MyType>
    </PropertyGroup>
    

    Essa configuração importa os My membros do namespace Visual Basic os programadores estão familiarizados com o.This setting imports the My namespace members Visual Basic programmers are familiar with.

  3. Importe os namespaces definidos pelo seu projeto.Import the namespaces defined by your project.

    Visual Basic projetos podem importar automaticamente namespaces para cada arquivo de código.Visual Basic projects can automatically import namespaces into every code file. Copie os <ItemGroup> elementos do arquivo de projeto antigo que contém <Import> para o novo arquivo após a </PropertyGroup> marca de fechamento.Copy the <ItemGroup> elements from the old project file that contain <Import> into the new file after the </PropertyGroup> closing tag.

    <ItemGroup>
      <Import Include="Microsoft.VisualBasic" />
      <Import Include="System" />
      <Import Include="System.Collections" />
      <Import Include="System.Collections.Generic" />
      <Import Include="System.Data" />
      <Import Include="System.Drawing" />
      <Import Include="System.Diagnostics" />
      <Import Include="System.Windows.Forms" />
      <Import Include="System.Linq" />
      <Import Include="System.Xml.Linq" />
      <Import Include="System.Threading.Tasks" />
    </ItemGroup>
    

    Se você não encontrar instruções ou se não for possível <Import> compilar o projeto, certifique-se de que pelo menos tenha as seguintes <Import> instruções definidas em seu projeto:If you can't find any <Import> statements, or your project fails to compile, make sure you at least have the following <Import> statements defined in your project:

    <ItemGroup>
      <Import Include="System.Data" />
      <Import Include="System.Drawing" />
      <Import Include="System.Windows.Forms" />
    </ItemGroup>
    
  4. No projeto original, copie as <Option*> configurações e <StartupObject> para o <PropertyGroup> elemento:From the original project, copy the <Option*> and <StartupObject> settings to the <PropertyGroup> element:

    <PropertyGroup>
      (contains settings previously described)
    
      <OptionExplicit>On</OptionExplicit>
      <OptionCompare>Binary</OptionCompare>
      <OptionStrict>Off</OptionStrict>
      <OptionInfer>On</OptionInfer>
      <StartupObject>MatchingGame.My.MyApplication</StartupObject>
    </PropertyGroup>
    

Recarregar o projetoReload the project

Depois de converter um projeto para o novo formato de estilo de SDK, recarregue o projeto no Visual Studio:After you convert a project to the new SDK-style format, reload the project in Visual Studio:

  1. Em Gerenciador de soluções, localize o projeto que você converteu.In Solution Explorer, find the project you converted.

  2. Clique com o botão direito do mouse no projeto e selecione recarregar projeto.Right-click on the project and select Reload Project.

    Se o projeto não for carregado, você poderá ter introduzido um erro no XML do projeto.If the project fails to load, you may have introduced a mistake in the XML of the project. Abra o arquivo de projeto para edição e tente identificar e corrigir o erro.Open the project file for editing and try to identify and fix the mistake. Se você não encontrar um erro, tente começar novamente.If you can't find a mistake, try starting over.

Editar App.configEdit App.config

Se seu aplicativo tiver um arquivo de App.config , remova o <supportedRuntime> elemento:If your app has an App.config file, remove the <supportedRuntime> element:

<supportedRuntime version="v4.0" sku=".NETFramework,Version=v4.5" />

Há algumas coisas que você deve considerar com o arquivo de App.config .There are some things you should consider with the App.config file. O arquivo de App.config no .NET Framework foi usado não apenas para configurar o aplicativo, mas para definir configurações e comportamento de tempo de execução, como registro em log.The App.config file in .NET Framework was used not only to configure the app, but to configure runtime settings and behavior, such as logging. O arquivo de App.config no .NET 5 + (e no .NET Core) não é mais usado para a configuração de tempo de execução.The App.config file in .NET 5+ (and .NET Core) is no longer used for runtime configuration. Se o arquivo de App.config tiver essas seções, elas não serão respeitadas.If your App.config file has these sections, they won't be respected.

Adicionar o pacote de compatibilidadeAdd the compatibility package

Se o arquivo de projeto estiver sendo carregado corretamente, mas a compilação falhar para seu projeto e você receberá erros semelhantes ao seguinte:If your project file is loading correctly, but compilation fails for your project and you receive errors similar to the following:

  • Não foi possível encontrar o tipo ou o namespace <some name>The type or namespace <some name> could not be found
  • O nome não <some name> existe no contexto atualThe name <some name> does not exist in the current context

Talvez seja necessário adicionar o Microsoft.Windows.Compatibility pacote ao seu aplicativo.You may need to add the Microsoft.Windows.Compatibility package to your app. Esse pacote adiciona ~ 21.000 APIs .NET de .NET Framework, como a System.Configuration.ConfigurationManager classe e as APIs para interagir com o registro do Windows.This package adds ~21,000 .NET APIs from .NET Framework, such as the System.Configuration.ConfigurationManager class and APIs for interacting with the Windows Registry. Adicione o pacote Microsoft.Windows.Compatibility.Add the Microsoft.Windows.Compatibility package.

Edite o arquivo de projeto e adicione o seguinte <ItemGroup> elemento:Edit your project file and add the following <ItemGroup> element:

<ItemGroup>
  <PackageReference Include="Microsoft.Windows.Compatibility" Version="5.0.0" />
</ItemGroup>

Testar seu aplicativoTest your app

Depois de concluir a migração de seu aplicativo, teste-o!After you've finished migrating your app, test it!

Próximas etapasNext steps