Omówienie przenoszenia z programu .NET Framework do platformy .NET

2025-06-03

Ten artykuł zawiera omówienie elementów, które należy wziąć pod uwagę podczas przenoszenia kodu z programu .NET Framework do platformy .NET (wcześniej o nazwie .NET Core). Przenoszenie do platformy .NET z programu .NET Framework jest stosunkowo proste w przypadku wielu projektów. Złożoność projektów określa, ile pracy należy wykonać po początkowej migracji plików projektu.

Projekty, w których model aplikacji jest dostępny na platformie .NET, takie jak biblioteki, aplikacje konsolowe i aplikacje klasyczne, zwykle wymagają niewielkiej zmiany. Projekty wymagające nowego modelu aplikacji, takie jak przejście do ASP.NET Core z ASP.NET, wymagają większej ilości pracy. Wiele wzorców ze starego modelu aplikacji ma odpowiedniki, których można użyć podczas konwersji.

Technologie pulpitu systemu Windows

Wiele aplikacji utworzonych dla programu .NET Framework korzysta z technologii klasycznej, takiej jak Windows Forms lub Windows Presentation Foundation (WPF). Zarówno Windows Forms, jak i WPF są dostępne na platformie .NET, ale pozostają technologiami tylko dla systemu Windows.

Przed migracją aplikacji Windows Forms lub WPF należy wziąć pod uwagę następujące zależności:

Pliki projektu dla platformy .NET używają innego formatu niż .NET Framework.
Projekt może używać interfejsu API, który nie jest dostępny na platformie .NET.
Kontrolki i biblioteki innych firm mogły nie zostać przeniesione do platformy .NET i pozostaną dostępne tylko dla programu .NET Framework.
Projekt korzysta z technologii, która nie jest już dostępna na platformie .NET.

Platforma .NET korzysta z wersji open source formularzy systemu Windows i WPF oraz zawiera ulepszenia w programie .NET Framework.

Aby uzyskać samouczki dotyczące migrowania aplikacji klasycznej na platformę .NET, zobacz jeden z następujących artykułów:

Interfejsy API specyficzne dla systemu Windows

Aplikacje mogą nadal obsługiwać biblioteki natywne P/Invoke na platformach obsługiwanych przez platformę .NET. Ta technologia nie jest ograniczona do systemu Windows. Jeśli jednak biblioteka, do której się odwołujesz, jest specyficzna dla systemu Windows, na przykład user32.dll lub kernel32.dll, kod działa tylko w systemie Windows. Dla każdej platformy, w której aplikacja ma być uruchamiana, musisz znaleźć wersje specyficzne dla platformy lub ustawić kod na tyle ogólny, aby był uruchamiany na wszystkich platformach.

Podczas przenoszenia aplikacji z programu .NET Framework do platformy .NET aplikacja prawdopodobnie użyła biblioteki udostępnionej przez program .NET Framework. Wiele interfejsów API, które były dostępne w programie .NET Framework, nie zostało portowanych do platformy .NET, ponieważ polegały na technologii specyficznej dla systemu Windows, takiej jak rejestr systemu Windows lub model rysunku GDI+.

Pakiet zgodności systemu Windows udostępnia dużą część powierzchni interfejsu API programu .NET Framework na platformie .NET i jest dostarczany za pośrednictwem pakietu NuGet Microsoft.Windows.Compatibility.

Aby uzyskać więcej informacji, zobacz Użyj Windows Compatibility Pack, aby przenieść kod do .NET.

Tryb zgodności programu .NET Framework

Tryb zgodności programu .NET Framework został wprowadzony w programie .NET Standard 2.0. Tryb zgodności umożliwia projektom platformy .NET Standard i .NET odwołanie do bibliotek programu .NET Framework tak, jakby zostały skompilowane dla platformy docelowej projektu. Jednak niektóre implementacje platformy .NET mogą obsługiwać większy fragment programu .NET Framework niż inne. Na przykład platforma .NET Core 3.0 rozszerza tryb zgodności programu .NET Framework na windows Forms i WPF. Odwoływanie się do bibliotek programu .NET Framework nie działa we wszystkich projektach, takich jak jeśli biblioteka korzysta z interfejsów API WPF, ale powoduje odblokowanie wielu scenariuszy przenoszenia. Aby uzyskać więcej informacji, zobacz sekcję Analizuj zależności w celu przeniesienia kodu z programu .NET Framework do .NET.

Odwoływanie się do bibliotek programu .NET Framework nie działa we wszystkich przypadkach, ponieważ zależy to od tego, które interfejsy API programu .NET Framework były używane i czy te interfejsy API są obsługiwane przez platformę docelową projektu. Ponadto niektóre interfejsy API programu .NET Framework będą działać tylko w systemie Windows. Tryb zgodności programu .NET Framework odblokuje wiele scenariuszy przenoszenia, ale należy przetestować projekty, aby upewnić się, że działają również w czasie wykonywania. Aby uzyskać więcej informacji, zobacz Analizowanie zależności w celu przeniesienia kodu z programu .NET Framework do.

Zmiany docelowego środowiska w projektach w stylu SDK

Jak wspomniano wcześniej, pliki projektu dla platformy .NET używają innego formatu niż .NET Framework, znanego jako format projektu w stylu zestawu SDK. Nawet jeśli nie przenosisz się z programu .NET Framework do platformy .NET, nadal należy uaktualnić plik projektu do najnowszego formatu. Sposób określania platformy docelowej różni się w projektach w stylu zestawu SDK. W programie .NET Framework <TargetFrameworkVersion> właściwość jest używana z pseudonimem określającym wersję programu .NET Framework. Na przykład program .NET Framework 4.7.2 wygląda podobnie do następującego fragmentu kodu:

<PropertyGroup>
  <TargetFrameworkVersion>v4.7.2</TargetFrameworkVersion>
</PropertyGroup>

Projekt w stylu zestawu SDK używa innej właściwości do identyfikowania docelowej platformy, właściwości <TargetFramework>. W przypadku docelowej wersji .NET Framework moniker rozpoczyna się od net i kończy się numerem wersji programu .NET Framework bez kropek. Na przykład moniker docelowy programu .NET Framework 4.7.2 to net472:

<PropertyGroup>
  <TargetFramework>net472</TargetFramework>
</PropertyGroup>

Aby uzyskać listę wszystkich obiektów docelowych, zobacz Platformy docelowe w projektach w stylu zestawu SDK.

Niedostępne technologie

Istnieje kilka technologii w programie .NET Framework, które nie istnieją na platformie .NET:

Domeny aplikacji

Tworzenie dodatkowych domen aplikacji nie jest obsługiwane. W przypadku izolacji kodu użyj oddzielnych procesów lub kontenerów jako alternatywy.
Komunikacja zdalna

Komunikacja zdalna jest używana do komunikacji między domenami aplikacji, które nie są już obsługiwane. W przypadku prostej komunikacji między procesami należy rozważyć mechanizmy komunikacji między procesami (IPC) jako alternatywę dla zdalnej komunikacji, taką jak klasa System.IO.Pipes lub klasa MemoryMappedFile. W przypadku bardziej złożonych scenariuszy należy rozważyć struktury, takie jak StreamJsonRpc lub ASP.NET Core (przy użyciu usług gRPC lub RESTful Web API).

Ponieważ komunikacja zdalna nie jest obsługiwana, wywołania do BeginInvoke() i EndInvoke() na obiektach delegowanych będą zgłaszać wyjątek PlatformNotSupportedException.
Zabezpieczenia dostępu kodu (CAS)

CAS to technika izolacji wspierana przez platformę .NET Framework, ale przestarzała w wersji 4.0 platformy .NET Framework. Został zastąpiony przez transparentność bezpieczeństwa i nie jest obsługiwany w .NET. Zamiast tego należy używać granic zabezpieczeń udostępnianych przez system operacyjny, takich jak wirtualizacja, kontenery lub konta użytkowników.
Przejrzystość zabezpieczeń

Podobnie jak w przypadku CAS, technika piaskownicy przezroczystości zabezpieczeń nie jest już zalecana dla aplikacji .NET Framework i nie jest obsługiwana w platformie .NET. Zamiast tego należy używać granic zabezpieczeń udostępnianych przez system operacyjny, takich jak wirtualizacja, kontenery lub konta użytkowników.
System.EnterpriseServices

System.EnterpriseServices (COM+) nie jest obsługiwany na platformie .NET.
Windows Workflow Foundation (WF)

Platforma WF nie jest obsługiwana na platformie .NET. Aby uzyskać alternatywę, zobacz CoreWF.

Aby uzyskać więcej informacji na temat tych nieobsługiwanych technologii, zobacz Technologie .NET Framework niedostępne na platformie .NET 6+.

Wieloplatformowy

Platforma .NET (wcześniej znana jako .NET Core) została zaprojektowana pod kątem wielu platform. Jeśli kod nie zależy od technologii specyficznych dla systemu Windows, może działać na innych platformach, takich jak macOS, Linux i Android. Taki kod zawiera typy projektów, takie jak:

Biblioteki
Narzędzia oparte na konsoli
Automatyzacja
witryny ASP.NET

.NET Framework jest składnikiem tylko dla systemu Windows. Gdy kod korzysta z technologii lub interfejsów API specyficznych dla systemu Windows, takich jak Windows Forms i WPF, kod nadal może działać na platformie .NET, ale nie jest uruchamiany w innych systemach operacyjnych.

Możliwe, że biblioteka lub aplikacja oparta na konsoli może być używana międzyplatformowo bez konieczności zmieniania się. Podczas przenoszenia do platformy .NET warto wziąć to pod uwagę i przetestować aplikację na innych platformach.

Przyszłość platformy .NET Standard

.NET Standard to formalna specyfikacja interfejsów API platformy .NET, które są dostępne w wielu implementacjach platformy .NET. Motywacją platformy .NET Standard było ustanowienie większej jednolitości w ekosystemie platformy .NET. Począwszy od platformy .NET 5, przyjęto inne podejście do ustanawiania jednolitości, a to nowe podejście eliminuje konieczność korzystania z platformy .NET Standard w wielu scenariuszach. Aby uzyskać więcej informacji, zobacz .NET 5+ i .NET Standard.

Platforma .NET Standard 2.0 była ostatnią wersją do obsługi programu .NET Framework.

Narzędzia ułatwiające przenoszenie

Zamiast ręcznie przenosić aplikację z programu .NET Framework do platformy .NET, możesz użyć różnych narzędzi, aby zautomatyzować niektóre aspekty migracji. Przenoszenie złożonego projektu jest w sobie złożonym procesem. Narzędzia mogą pomóc w tej podróży.

Nawet jeśli używasz narzędzia do przenoszenia aplikacji, zapoznaj się z sekcją Zagadnienia dotyczące przenoszenia w tym artykule.

Asystent uaktualniania platformy .NET

Asystent uaktualniania platformy .NET to narzędzie wiersza polecenia, które można uruchamiać w różnych rodzajach aplikacji .NET Framework. Ma ona na celu pomoc w uaktualnianiu aplikacji .NET Framework do platformy .NET. Po uruchomieniu narzędzia w większości przypadków aplikacja będzie wymagać większego nakładu pracy w celu ukończenia migracji. Narzędzie zawiera instalację analizatorów, które mogą pomóc w zakończeniu migracji. To narzędzie działa na następujących typach aplikacji .NET Framework:

Formularze systemu Windows
WPF (Windows Presentation Foundation)
ASP.NET MVC
Konsola
Biblioteki klas

To narzędzie używa innych narzędzi wymienionych w tym artykule, takich jak try-convert, i prowadzi proces migracji. Aby uzyskać więcej informacji na temat narzędzia, zobacz Omówienie Asystenta uaktualniania platformy .NET.

`try-convert`

Narzędzie try-convert to narzędzie globalne platformy .NET, które umożliwia konwertowanie projektu lub całego rozwiązania na zestaw .NET SDK, w tym przenoszenie aplikacji klasycznych na platformę .NET. Jednak to narzędzie nie jest zalecane, jeśli projekt ma skomplikowany proces kompilacji, taki jak niestandardowe zadania, obiekty docelowe lub importy.

Aby uzyskać więcej informacji, zobacz try-convert repozytorium GitHub.

Analizator zgodności platformy

Analizator zgodności platformy sprawdza, czy używasz interfejsu API, który zgłasza PlatformNotSupportedException podczas działania. Chociaż znalezienie jednego z tych interfejsów API jest mało prawdopodobne, jeśli przechodzisz z programu .NET Framework 4.7.2 lub nowszego, warto to sprawdzić. Aby uzyskać więcej informacji na temat interfejsów API, które zgłaszają wyjątki na platformie .NET, zobacz Interfejsy API, które zawsze zgłaszają wyjątki na platformie .NET Core.

Aby uzyskać więcej informacji, zobacz Analizator zgodności platformy.

Zagadnienia dotyczące przenoszenia

Podczas przenoszenia aplikacji na platformę .NET należy wziąć pod uwagę następujące sugestie:

✔️ ROZWAŻ użycie Asystenta uaktualniania platformy .NET do migrowania projektów. Mimo że to narzędzie jest w wersji zapoznawczej, automatyzuje większość ręcznych kroków opisanych w tym artykule i zapewnia doskonały punkt wyjścia do kontynuowania ścieżki migracji.

✔️ Najpierw rozważ zbadanie zależności. Zależności muszą być przeznaczone dla platformy .NET, .NET Standard lub .NET Core.

✔️ Przeprowadź migrację z pliku packages.config NuGet do PackageReference ustawień w pliku projektu. Użyj programu Visual Studio, aby przekonwertować package.config plik.

✔️ ROZWAŻ uaktualnienie do najnowszego formatu pliku projektu, nawet jeśli nie możesz jeszcze prze portować aplikacji. Projekty .NET Framework używają nieaktualnego formatu projektu. Mimo że najnowszy format projektu, znany jako projekty w stylu zestawu SDK, został utworzony dla platformy .NET Core i nie tylko, format działa również z programem .NET Framework. Posiadanie pliku projektu w najnowszym formacie daje dobrą podstawę do przenoszenia aplikacji w przyszłości.

✔️ Zmień docelową wersję swojego projektu .NET Framework na co najmniej .NET Framework 4.7.2. Zapewnia to dostępność najnowszych alternatyw interfejsów API w przypadkach, w których platforma .NET Standard nie obsługuje istniejących interfejsów API.

✔️ ROZWAŻENIE użycie platformy .NET 8, która jest wersją z długoterminowym wsparciem (LTS).

✔️ Należy wykorzystać .NET 6+ w projektach Windows Forms i WPF. Platforma .NET 6 i nowsze wersje zawierają wiele ulepszeń dla aplikacji klasycznych.

✔️ ROZWAŻ użycie platformy .NET Standard 2.0, jeśli migrujesz bibliotekę, która może być również używana z projektami programu .NET Framework. Możesz również wieloplatformowo docelować swoją bibliotekę, aby działała zarówno na .NET Framework, jak i na .NET Standard.

✔️ Dodaj odwołanie do pakietu NuGet Microsoft.Windows.Compatibility, jeśli po migracji pojawią się błędy związane z brakiem interfejsów API. Duża część powierzchni interfejsu API programu .NET Framework jest dostępna dla platformy .NET za pośrednictwem pakietu NuGet.