Jak przeprowadzić migrację Windows Forms klasycznej na platformę .NET 5

W tym artykule opisano sposób migrowania Windows Forms klasycznej z .NET Framework do programu .NET 5 lub nowszego. Zestaw SDK platformy .NET obejmuje obsługę Windows Forms aplikacji. Windows Forms to nadal tylko Windows i działa tylko na Windows.

Migrowanie aplikacji z programu .NET Framework do programu .NET 5 zwykle wymaga nowego pliku projektu. Program .NET 5 używa plików projektu w stylu zestawu SDK, .NET Framework zwykle używa starszego Visual Studio projektu. Jeśli kiedykolwiek otwarto plik Visual Studio w edytorze tekstów, wiesz, jak pełny jest. Projekty w stylu zestawu SDK są mniejsze i nie wymagają tylu wpisów, ile ma starszy format pliku projektu.

Aby dowiedzieć się więcej na temat programu .NET 5, zobacz Wprowadzenie do programu .NET.

Wypróbuj asystenta uaktualniania

Asystent uaktualniania .NET to narzędzie wiersza polecenia, które można uruchamiać w różnych .NET Framework aplikacji. Ma ona pomóc w uaktualnianiu aplikacji .NET Framework do programu .NET 5. Po uruchomieniu narzędzia w większości przypadków aplikacja będzie wymagać dodatkowego nakładu pracy w celu ukończenia migracji. Narzędzie obejmuje instalację analizatorów, które mogą pomóc w ukończeniu migracji.

Aby uzyskać więcej informacji, zobacz Uaktualnianie aplikacji WPF do platformy .NET 5 przy użyciu Asystenta uaktualniania platformy .NET.

Wymagania wstępne

Rozważyć

Podczas migrowania .NET Framework Windows Forms należy wziąć pod uwagę kilka rzeczy.

  1. Sprawdź, czy aplikacja jest dobrym kandydatem do migracji.

    Użyj analizatora przenośności .NET , aby określić, czy projekt zostanie zmigrowany do programu .NET 5. Jeśli w projekcie występują problemy z programem .NET 5, analizator pomaga je zidentyfikować. Narzędzie .NET Portability Analyzer można zainstalować jako rozszerzenie Visual Studio lub użyć z wiersza polecenia. Aby uzyskać więcej informacji, zobacz .NET Portability Analyzer.

  2. Używasz innej wersji usługi Windows Forms.

    Po wydano program .NET Core 3.0, Windows Forms został open source w GitHub. Kod dla Windows Forms dla programu .NET 5 jest widelecem .NET Framework Windows Forms kodu. Możliwe, że istnieją pewne różnice, a migracja aplikacji będzie trudna.

  3. Pakiet Windows zgodności może pomóc w migracji.

    Niektóre interfejsy API, które są .NET Framework w programie .NET Framework nie są dostępne na .NET 5. Pakiet Windows Compatibility Pack dodaje wiele z tych interfejsów API i może pomóc w Windows Forms aplikacji zgodnej z programem .NET 5.

  4. Zaktualizuj pakiety NuGet używane przez projekt.

    Zawsze dobrym rozwiązaniem jest użycie najnowszych wersji pakietów NuGet przed migracją. Jeśli aplikacja odwołuje się do jakichkolwiek NuGet, zaktualizuj je do najnowszej wersji. Upewnij się, że aplikacja została pomyślnie skompilowana. Po uaktualnieniu, jeśli występują błędy pakietu, obniż wersję pakietu do najnowszej wersji, która nie spowoduje przerwania kodu.

Kopii zapasowej projektów

Pierwszym krokiem do migracji projektu jest schowanie kopii zapasowej projektu. Jeśli coś pójdzie nie tak, możesz przywrócić kod do pierwotnego stanu, przywracając kopię zapasową. Nie należy polegać na narzędziach, takich jak .NET Portability Analyzer, w celu tworzenia kopii zapasowej projektu, nawet jeśli się wydaje. Najlepiej jest osobiście utworzyć kopię oryginalnego projektu.

Pakiety NuGet

Jeśli projekt odwołuje się do NuGet, prawdopodobnie masz plik packages.config w folderze projektu. W projektach w stylu zestawu SDK NuGet odwołania do pakietu są konfigurowane w pliku projektu. Visual Studio projektu można opcjonalnie zdefiniować NuGet pakietów w pliku projektu. .NET 5 nie używapackages.configdla NuGet pakietów. NuGet odwołania do pakietu muszą zostać zmigrowane do pliku projektu przed migracją.

Aby przeprowadzić migracjępackages.config , wykonaj następujące czynności:

  1. W Eksploratorze rozwiązań znajdź migrowanie projektu.
  2. Kliknij prawym przyciskiem myszy pozycję packages.config>Migrate packages.config packageReference.
  3. Wybierz wszystkie pakiety najwyższego poziomu.

Zostanie wygenerowany raport kompilacji z informacjami o wszelkich problemach z migracją pakietów NuGet kompilacji.

Project plik

Następnym krokiem migracji aplikacji jest przekonwertowanie pliku projektu. Jak wspomniano wcześniej, program .NET 5 używa plików projektu w stylu zestawu SDK i nie będzie ładować Visual Studio projektu, które .NET Framework używane. Istnieje jednak możliwość, że już korzystasz z projektów w stylu zestawu SDK. Możesz łatwo dostrzec różnicę w Visual Studio. Kliknij prawym przyciskiem myszy plik projektu w Eksploratorze rozwiązań i poszukaj opcji menu Project Plik. Jeśli brakuje tego elementu menu, używasz starego formatu Visual Studio projektu i musisz go uaktualnić.

Przekonwertuj każdy projekt w rozwiązaniu. Jeśli używasz przykładowej aplikacji, do których wcześniej się odwołujesz, zostaną przekonwertowane projekty MatchingGame i MatchingGame.Logic .

Aby przekonwertować projekt, wykonaj następujące czynności:

  1. W Eksploratorze rozwiązań znajdź migrowanie projektu.

  2. Kliknij prawym przyciskiem myszy projekt i wybierz polecenie Unload Project (Zwolnij Project).

  3. Kliknij prawym przyciskiem myszy projekt i wybierz polecenie Edytuj Project plik.

  4. Skopiuj i wklej kod XML projektu do edytora tekstów. Potrzebujesz kopii, aby można było łatwo przenieść zawartość do nowego projektu.

  5. Wymazaj zawartość pliku i wklej następujący kod XML:

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

    Ważne

    Biblioteki nie muszą definiować <OutputType> ustawienia. Usuń ten wpis, jeśli uaktualniasz projekt biblioteki.

Ten kod XML zapewnia podstawową strukturę projektu. Jednak nie zawiera żadnych ustawień ze starego pliku projektu. Korzystając ze starych informacji o projekcie skopiowanych wcześniej do edytora tekstów, wykonaj następujące czynności:

  1. Skopiuj następujące elementy ze starego pliku projektu do elementu <PropertyGroup> w nowym pliku projektu:

    • <RootNamespace>
    • <AssemblyName>

    Plik projektu powinien wyglądać podobnie do następującego kodu 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. Skopiuj elementy <ItemGroup> ze starego pliku projektu, które zawierają plik lub <PackageReference><ProjectReference> do nowego pliku po tagu </PropertyGroup> zamykającym.

    Plik projektu powinien wyglądać podobnie do następującego kodu 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>
    

    Elementy <ProjectReference> i nie są potrzebne <Project><Name> , więc możesz usunąć te ustawienia:

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

Zasoby i ustawienia

Należy zwrócić uwagę na różnicę między projektami platformy .NET Framework a projektami w stylu zestawu SDK używanymi przez platformę .NET 5, że projekty platformy .NET Framework używają modelu zgody dla plików kodu. Każdy plik kodu, który chcesz skompilować, musi być jawnie zdefiniowany w pliku projektu. Projekty w stylu zestawu SDK są odwrotne— domyślnie zrezygnują z zachowania: wszystkie pliki kodu zaczynające się od katalogu projektu i poniżej są automatycznie uwzględniane w projekcie. Nie trzeba migrować tych wpisów, jeśli są one proste i nie wymagają ustawień. Jest to takie samo w przypadku innych typowych plików, takich jak resx.

Windows Forms mogą również odwoływać się do następujących plików:

  • Właściwości\Ustawienia.settings
  • Properties\Resources.resx
  • Properties\app.manifest

Projekt automatycznie odwołuje się do pliku app.manifest i nie trzeba nic specjalnego robić, aby go migrować.

Wszystkie pliki *.resxi *.settings w folderze Właściwości należy zmigrować w projekcie. Skopiuj te wpisy ze starego pliku projektu do elementu <ItemGroup> w nowym projekcie. Po skopiowaniu wpisów zmień wszystkie <Compile Include="value"> elementy tak, aby zamiast atrybutu Update używały atrybutu Include.

  • Zaimportuj konfigurację Ustawienia.settings.

    <ItemGroup>
      <None Update="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>
    

    Ważne

    Visual Basic projektów zwykle używają folderu My Project, podczas gdy projekty języka C# zwykle używają folderu Właściwości domyślnego pliku ustawień projektu.

  • Zaimportuj konfigurację dla dowolnego pliku resx , takiego jak properties\Resources.resx . Zwróć uwagę, że Include atrybut został ustawiony na Update wartość w <Compile> elemencie i <EmbeddedResource> i <SubType> został usunięty z elementu <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>
    

    Ważne

    Visual Basic projektów zwykle używają folderu My Project, podczas gdy projekty języka C# zwykle używają folderu Właściwości domyślnego pliku zasobów projektu.

Visual Basic

Visual Basic projektów językowych wymagają dodatkowej konfiguracji.

  1. Zaimportuj plik konfiguracji Mój Project\Application.myapp. Zwróć uwagę, że <Compile> element używa Update atrybutu zamiast Include atrybutu .

    <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. Dodaj ustawienie <MyType>WindowsForms</MyType> do <PropertyGroup> elementu :

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

    To ustawienie importuje elementy My członkowskie przestrzeni nazw Visual Basic znajomy programiści.

  3. Zaimportuj przestrzenie nazw zdefiniowane w projekcie.

    Visual Basic mogą automatycznie importować przestrzenie nazw do każdego pliku kodu. Skopiuj elementy <ItemGroup> ze starego pliku projektu, które zawierają element <Import> do nowego pliku po tagu </PropertyGroup> zamykającym.

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

    Jeśli nie możesz znaleźć żadnych <Import> instrukcji lub kompilacja projektu nie powiedzie się, upewnij się, <Import> że w projekcie zdefiniowano co najmniej następujące instrukcje:

    <ItemGroup>
      <Import Include="System.Data" />
      <Import Include="System.Drawing" />
      <Import Include="System.Windows.Forms" />
    </ItemGroup>
    
  4. Z oryginalnego projektu skopiuj ustawienia <Option*> i <StartupObject> do <PropertyGroup> elementu :

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

Załaduj ponownie projekt

Po przekonwertowaniu projektu na nowy format w stylu zestawu SDK załaduj ponownie projekt w Visual Studio:

  1. W Eksplorator rozwiązań znajdź przekonwertowany projekt.

  2. Kliknij prawym przyciskiem myszy projekt i wybierz polecenie Załaduj ponownie Project.

    Jeśli nie można załadować projektu, być może wprowadzono błąd w pliku XML projektu. Otwórz plik projektu do edycji i spróbuj zidentyfikować i naprawić błąd. Jeśli nie możesz znaleźć błędu, spróbuj od początku.

Edytuj App.config

Jeśli aplikacja ma plik App.config , usuń <supportedRuntime> element :

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

Istnieje kilka rzeczy, które należy wziąć pod uwagę w App.config pliku. Plik App.config w .NET Framework był używany nie tylko do konfigurowania aplikacji, ale także do konfigurowania ustawień i zachowania środowiska uruchomieniowego, takich jak rejestrowanie. Plik App.config na platformie .NET 5+ (i .NET Core) nie jest już używany do konfigurowania środowiska uruchomieniowego. Jeśli plik App.config zawiera te sekcje, nie będą przestrzegane.

Dodawanie pakietu zgodności

Jeśli plik projektu jest ładowany poprawnie, ale kompilacja nie powiedzie się dla projektu i występują błędy podobne do następujących:

  • Nie można odnaleźć typu lub <przestrzeni nazw>
  • Nazwa, <która nie> istnieje w bieżącym kontekście, nie istnieje

Może być konieczne dodanie Microsoft.Windows.Compatibility pakietu do aplikacji. Ten pakiet dodaje około 21 000 interfejsów API .NET z .NET Framework, System.Configuration.ConfigurationManager takich jak klasa i interfejsy API do interakcji z Windows Registry. Dodaj pakiet Microsoft.Windows.Compatibility.

Edytuj plik projektu i dodaj następujący <ItemGroup> element:

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

Testowanie aplikacji

Po zakończeniu migracji aplikacji przetestuj ją.

Następne kroki