Notatka
Dostęp do tej strony wymaga autoryzacji. Może spróbować zalogować się lub zmienić katalogi.
Dostęp do tej strony wymaga autoryzacji. Możesz spróbować zmienić katalogi.
Platforma UWP nie jest już aktywnie opracowywana. WinUI 3 i Zestaw SDK do aplikacji systemu Windows są jego następcami — a narzędzia sztucznej inteligencji mogą zautomatyzować większość migracji. Głównym wyzwaniem jest to, że modele sztucznej inteligencji zostały przeszkolone na lata próbek platformy UWP, więc bez wskazówek odtwarzają wzorce, z których próbujesz odejść. Ta strona zapewnia agentowi kontekst potrzebny do prawidłowego działania.
Instalowanie wtyczki agenta WinUI
Umiejętność winui-uwp-migration automatycznie obsługuje typowe zamiany:
gh copilot plugin install winui@awesome-copilot
Aby uzyskać szczegółowe informacje, zobacz wtyczkę agenta WinUI .
Tabela podstawiania interfejsu API
Poniższe tabele przedstawiają podsumowanie najczęstszych zamienników interfejsu API. Aby uzyskać pełne, szczegółowe mapowanie — w tym składowe, właściwości i rzadziej używane interfejsy API — zobacz Mapowanie interfejsów API i bibliotek UWP na zestaw Zestaw SDK do aplikacji systemu Windows.
Important
x:Bind domyślnie działa w trybie OneTime. W przeciwieństwie do {Binding} (które domyślnie przyjmuje wartość OneWay), x:Bind jest obliczane tylko raz, chyba że określisz Mode=OneWay lub Mode=TwoWay. Podczas migracji przejrzyj wszystkie wyrażenia x:Bind, które są wiązane z właściwościami zmieniającymi się w czasie wykonywania — brak Mode=OneWay powoduje błędy „interfejs użytkownika się nie aktualizuje”, które są niewidoczne na etapie kompilacji.
Przestrzenie nazw
| platforma UWP | WinUI 3 |
|---|---|
Windows.UI.Xaml.* |
Microsoft.UI.Xaml.* |
Windows.UI.Xaml.Controls.* |
Microsoft.UI.Xaml.Controls.* |
Windows.UI.Xaml.Media.* |
Microsoft.UI.Xaml.Media.* |
Windows.UI.Composition |
Microsoft.UI.Composition |
Wątkowanie
| platforma UWP | WinUI 3 |
|---|---|
CoreDispatcher |
DispatcherQueue |
Dispatcher.RunAsync(...) |
DispatcherQueue.TryEnqueue(...) |
CoreApplication.MainView.CoreWindow.Dispatcher |
this.DispatcherQueue (z elementu Window lub Page) |
Windowing
| platforma UWP | WinUI 3 |
|---|---|
ApplicationView |
AppWindow |
ApplicationView.GetForCurrentView() |
AppWindow.GetFromWindowId(...) |
ApplicationViewTitleBar |
AppWindowTitleBar |
CoreWindow |
Microsoft.UI.Xaml.Window |
SystemNavigationManager |
Przycisk Wstecz za pośrednictwem AppWindowTitleBar |
Okna dialogowe i selektory
| platforma UWP | WinUI 3 |
|---|---|
MessageDialog |
ContentDialog (zestaw XamlRoot) |
FileOpenPicker |
FileOpenPicker + InitializeWithWindow |
FileSavePicker |
FileSavePicker + InitializeWithWindow |
FolderPicker |
FolderPicker + InitializeWithWindow |
Important
Pickery wymagają użycia InitializeWithWindow przed wywołaniem PickSingleFileAsync (lub podobnego):
var hwnd = WinRT.Interop.WindowNative.GetWindowHandle(App.MainWindow);
WinRT.Interop.InitializeWithWindow.Initialize(picker, hwnd);
Element ContentDialog wymaga XamlRoot (a nie InitializeWithWindow):
var dialog = new ContentDialog { XamlRoot = this.Content.XamlRoot, ... };
await dialog.ShowAsync();
Notifications
| platforma UWP | WinUI 3 |
|---|---|
Windows.UI.Notifications.ToastNotificationManager |
Microsoft.Windows.AppNotifications.AppNotificationManager |
Windows.UI.Notifications.BadgeUpdateManager |
Microsoft.Windows.BadgeNotifications.BadgeNotificationManager |
Windows.UI.Notifications.TileUpdateManager |
Kafelki są przestarzałe — użyj powiadomień lub widżetów |
Sieć i protokół HTTP
| platforma UWP | WinUI 3 (zalecane) |
|---|---|
Windows.Web.Http.HttpClient |
System.Net.Http.HttpClient (wersja przenośna, niewymagająca zależności od WinRT) |
Windows.Web.Syndication.SyndicationClient |
System.ServiceModel.Syndication.SyndicationFeed + HttpClient |
Windows.Web.AtomPub.AtomPubClient |
System.ServiceModel.Syndication lub bezpośredni protokół HTTP |
Note
Interfejsy API HTTP WinRT (Windows.Web.Http) nadal działają w aplikacjach pakietowanych WinUI 3, ale ze względu na przenośność, łatwiejsze debugowanie i szersze wsparcie ekosystemu (oprogramowanie pośredniczące, DI, mockowanie) zalecane są odpowiedniki .NET.
Navigation
| platforma UWP | WinUI 3 |
|---|---|
Frame.Navigate(typeof(MyPage)) |
Frame.Navigate(typeof(MyPage)) — bez zmian |
SystemNavigationManager.BackRequested |
Obsłuż za pomocą NavigationView lub AppWindow |
Windows.UI.Core.Preview.SystemNavigationManagerPreview |
zdarzenie AppWindow.Closing |
Note
Niestandardowa nawigacja typu hamburger (SplitView + NavMenuListView): W wielu przykładach UWP zaimplementowano nawigację przy użyciu niestandardowego AppShell.xaml z SplitView oraz ręcznie napisanej kontrolki NavMenuListView (~500+ wierszy). W WinUI 3 zastąp cały ten wzorzec elementem NavigationView, który zapewnia ten sam UX dzięki wbudowanym ułatwieniom dostępu, adaptacyjnemu zachowaniu i obsłudze przycisku Wstecz. Jest to zazwyczaj 80% redukcji kodu.
Wzorce MVVM
| Platforma UWP (typowe implementacje niestandardowe) | WinUI 3 (zalecane) |
|---|---|
Niestandardowe BindableBase / ObservableObject |
CommunityToolkit.Mvvm.ComponentModel.ObservableObject |
Niestandardowe DelegateCommand / RelayCommand |
CommunityToolkit.Mvvm.Input.RelayCommand |
Ręczny SetProperty + OnPropertyChanged |
[ObservableProperty] generator kodu źródłowego |
Zwyczaj INavigationService |
Wbudowane Frame.Navigate + NavigationView |
Wskazówka
Pakiet NuGet CommunityToolkit.Mvvm jest zalecaną podstawą MVVM dla aplikacji WinUI 3. Zastępuje ręcznie tworzone klasy bazowe sprawdzonymi odpowiednikami generowanymi na podstawie kodu źródłowego, co eliminuje setki linii powtarzalnego kodu.
dotnet add package CommunityToolkit.Mvvm
Cykl życia aplikacji
| platforma UWP | WinUI 3 |
|---|---|
Application.Current.Suspending |
Microsoft.Windows.AppLifecycle (wymaga zmian architektury — zobacz uwaga) |
Application.Current.Resuming |
AppInstance.GetCurrent().Activated (patrz uwaga) |
BackgroundTaskBuilder |
Zadania w tle Zestaw SDK do aplikacji systemu Windows |
Note
Migracja cyklu życia aplikacji WinUI 3 nie jest prostą zamianą nazw interfejsu API. W Zestaw SDK do aplikacji systemu Windows jest używany inny model aktywacji i zawieszenia. Traktuj kod cyklu życia jako wymagający dedykowanego ponownego zapisywania, a nie automatycznego zastępowania. Zobacz dokumentację cyklu życia Zestaw SDK do aplikacji systemu Windows aby zapoznać się z pełnym modelem.
Ustawienia i pamięć
| platforma UWP | WinUI 3 (spakowane) | WinUI 3 (rozpakowany) |
|---|---|---|
ApplicationData.Current.LocalSettings |
Niezmienione | ❌ Throws — brak tożsamości pakietu |
ApplicationData.Current.LocalFolder |
Niezmienione | ❌ Throws — brak tożsamości pakietu |
Windows.Storage.KnownFolders |
Niezmienione | ❌ Throws — brak tożsamości pakietu |
Warning
Aplikacje bez pakietu nie mogą używać ApplicationData.Current — powoduje to wyjątek w czasie wykonywania, ponieważ aplikacja nie ma tożsamości pakietu. Zamiast tego użyj standardowych interfejsów API plików .NET:
var appData = Path.Combine(
Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData),
"YourAppName");
Directory.CreateDirectory(appData);
var json = JsonSerializer.Serialize(data);
await File.WriteAllTextAsync(Path.Combine(appData, "settings.json"), json);
Note
Jeśli aplikacja UWP używała DataContractSerializer z [DataMember]/[IgnoreDataMember], rozważ migrację do System.Text.Json (szybsza, mniejsza, z obsługą generatorów kodu źródłowego). Mapowanie atrybutów to:
-
[DataMember][JsonPropertyName("name")]→ (lub po prostu użyj bezpośrednio nazw właściwości) -
[IgnoreDataMember]→[JsonIgnore] -
[DataContract]→ Żaden odpowiednik nie jest potrzebny (System.Text.Json domyślnie serializuje właściwości publiczne)
API, które się nie zmienia
Windows.Devices.*, Windows.Media.*, Windows.UI.ViewManagement.UISettings, Windows.UI.Color, a większość interfejsów API WinRT poza przestrzenią nazw XAML pozostaje niezmieniona.
Kontrolki bez bezpośredniego odpowiednika
Niektóre kontrolki platformy UWP nie istnieją w systemie WinUI 3. Wybierz zamianę w zależności od scenariusza:
| Kontrolka UWP | Zamiennik WinUI 3 | Notatki |
|---|---|---|
Pivot |
TabView, NavigationView (tryb górny) lub RadioButtons + widoczność |
W przypadku 2–3 stałych kart najprostszym rozwiązaniem jest RadioButtons z przełączaniem widoczności. W przypadku kart dynamicznych/zamykanych użyj polecenia TabView. |
RadialController |
Współdziałanie WinRT z uchwytem okna |
RadialController.CreateForCurrentView() nie ma bezpośredniego odpowiednika. Użyj RadialControllerInterop z GetForWindow(hwnd). |
SystemNavigationManager |
Niestandardowy przycisk Wstecz lub NavigationView.IsBackEnabled |
SystemNavigationManager.GetForCurrentView() nie istnieje. Dodaj własny przycisk Wstecz lub użyj NavigationViewwbudowanego przycisku Wstecz. |
Ink, Win2D i drukowanie
Te podsystemy wymagają określonych kroków migracji poza zmianami przestrzeni nazw.
Windows Ink
WinUI obejmuje InkCanvas, InkToolbar i InkPresenter jako eksperymentalne interfejsy API w eksperymentalnych wersjach Zestaw SDK do aplikacji systemu Windows. Stabilne wersje nie zawierają ich. Aby uzyskać informacje na temat konfiguracji, dostosowywania paska narzędzi i znanych ograniczeń, zobacz Kontrolki pisma odręcznego cyfrowego dla aplikacji WinUI.
W wersjach eksperymentalnych kontrolki i typy, które przetwarzają wprowadzanie pisma odręcznego, znajdują się w Microsoft.UI.Xaml.Controls. Atrybuty pociągnięć i rysunku pozostają w Windows.UI.Input.Inking:
| platforma UWP | WinUI 3 (wersje eksperymentalne) |
|---|---|
Windows.UI.Xaml.Controls.InkCanvas, InkToolbari inne InkToolbar* typy |
Microsoft.UI.Xaml.Controls, nazwy tego samego typu. Niektórzy członkowie różnią się. |
Windows.UI.Input.Inking.InkPresenter, InkStrokeContainer, InkSynchronizer, InkInputRightDragAction, InkInputConfiguration, InkStrokesCollectedEventArgs, InkUnprocessedInput, InkInputProcessingConfiguration, InkInputProcessingMode, InkHighContrastAdjustment, InkStrokeInput, InkStrokesErasedEventArgs |
Microsoft.UI.Xaml.Controls, takie same nazwy typów. Niektórzy członkowie różnią się. |
Windows.UI.Input.Inking.InkStroke, InkDrawingAttributes, InkPoint, InkStrokeBuilder, InkPersistenceFormat, PenTipShape |
Bez zmian |
Windows.UI.Core.CoreInputDeviceTypes |
Bez zmian |
Każdy typ platformy UWP w pierwszych dwóch wierszach ma odpowiednik o tej samej nazwie, ale Zestaw SDK do aplikacji systemu Windows 2.5.4-eksperymentalny nie zawiera wszystkich ich składowych:
-
InkStrokeContainernie ma publicznego konstruktora iInkPresenter.StrokeContainerjest tylko do odczytu. Aby przełączać się między zestawami pociągnięć, zapisz każdy zestaw za pomocąSaveAsynci przywróć go za pomocąLoadAsync, która zastępuje bieżące pociągnięcia. -
SaveAsynciLoadAsynczwracająIAsyncActionwartość, więc nie zgłaszają postępu, aSaveAsyncnie zwraca liczby bajtów, które zapisał. -
InkStrokeContainer.GetRecognitionResults,InkStrokeContainer.UpdateRecognitionResultsiInkInputConfiguration.IsPenHapticFeedbackEnablednie są dostępne. -
InkToolbarRulerButton.Ruleri zdarzenieInkToolbar.IsRulerButtonCheckedChangednie są dostępne. Platforma UWP oznaczyłaInkToolbarRulerButtonjako przestarzałe na rzeczInkToolbarStencilButton, więc zamiast tego użyj przycisku wzornika i zdarzeniaInkToolbar.IsStencilButtonCheckedChanged.
Zestaw SDK do aplikacji systemu Windows 2.4.1-eksperymentalny dodał interfejsy API gumki, takie jak InkToolbarEraserKind i InkToolbarEraserButton.SelectedEraser, które usunięto w wersji 2.5.4-eksperymentalnej. Nigdy nie były częścią platformy UWP, więc nie dodawaj ich do zmigrowanego kodu. Aby uzyskać pełną listę, zobacz Zmiany z wersji 2.4.1-eksperymentalnej.
Ponieważ typy, takie jak InkPresenter i InkStrokeContainer, istnieją w obu przestrzeniach nazw, importowanie zarówno Windows.UI.Input.Inking, jak i Microsoft.UI.Xaml.Controls powoduje błąd CS0104 podczas używania tych nazw. Zaimportuj Microsoft.UI.Xaml.Controlsi dodaj dyrektywy aliasu dla używanych Windows.UI.Input.Inking typów:
using Microsoft.UI.Xaml.Controls;
using InkDrawingAttributes = Windows.UI.Input.Inking.InkDrawingAttributes;
using InkStroke = Windows.UI.Input.Inking.InkStroke;
InkStrokeContainer.SaveAsync zapisuje do obiektu IOutputStream i LoadAsync odczytuje z obiektu IInputStream. Aby użyć strumieni plików System.IO, przekonwertuj je za pomocą AsOutputStream i AsInputStream. Plik musi używać using System;, aby oczekiwać na te metody środowisko wykonawcze systemu Windows, wraz z using System.IO; i using Windows.Storage.Streams;:
// Save ink strokes to a file.
using (FileStream fileStream = File.Create(filePath))
using (IOutputStream output = fileStream.AsOutputStream())
{
await inkStrokeContainer.SaveAsync(output);
await output.FlushAsync();
}
// Load ink strokes from a file.
using (FileStream fileStream = File.OpenRead(filePath))
using (IInputStream input = fileStream.AsInputStream())
{
await inkStrokeContainer.LoadAsync(input);
}
Możesz nadal łączyć pasek narzędzi z obszarem roboczym za pomocą InkToolbar.TargetInkCanvas, lub ustawić TargetInkPresenter, aby połączyć go bezpośrednio z elementem InkPresenter. Aby dodać własne narzędzia do paska narzędzi, użyj elementów InkToolbarCustomToolButton i InkToolbarCustomToggleButton, jak pokazano w Dostosowywanie paska narzędzi pisma odręcznego. Przed migracją zapoznaj się ze znanymi ograniczeniami, takimi jak zgłoszone problemy z linijkami i wzornikami kątomierza.
Jeśli aplikacja musi używać stabilnej wersji, nie ma wbudowanej kontrolki obsługi pisma odręcznego, do której można przeprowadzić migrację. Renderuj pociągnięcia za pomocą Win2D i samodzielnie obsłuż dane wejściowe wskaźnika lub użyj biblioteki do obsługi pisma odręcznego innej firmy. Aby zastąpić element InkToolbar, użyj CommandBar z elementami AppBarToggleButton.
Win2D
Nazwa pakietu Win2D została zmieniona, ale powierzchnia interfejsu API jest identyczna:
| platforma UWP | WinUI 3 |
|---|---|
Win2D.uwp (NuGet) |
Microsoft.Graphics.Win2D (NuGet) |
Wszystkie Microsoft.Graphics.Canvas.* interfejsy API (CanvasDevice, CanvasBitmap, CanvasRenderTarget, DrawInk) działają w taki sam sposób. Tylko odwołanie do pakietu NuGet wymaga aktualizacji.
Drukowanie
Drukowanie platformy UWP używa funkcji PrintManager.GetForCurrentView(). WinUI 3 wymaga współdziałania z uchwytem okna:
// UWP
var printManager = PrintManager.GetForCurrentView();
printManager.PrintTaskRequested += OnPrintTaskRequested;
await PrintManager.ShowPrintUIAsync();
// WinUI 3 — must pass window handle
var hwnd = WinRT.Interop.WindowNative.GetWindowHandle(App.MainWindow);
var printManager = PrintManagerInterop.GetForWindow(hwnd);
printManager.PrintTaskRequested += OnPrintTaskRequested;
await PrintManagerInterop.ShowPrintUIForWindowAsync(hwnd);
Interfejsy API renderowania PrintDocument (Paginate, GetPreviewPage, AddPages) pozostają bez zmian.
Important
Jeśli pominięto uchwyt okna, PrintManagerInterop.GetForWindow zwraca wartość COMException. Jest to ten sam wzorzec interoperacyjności co FileOpenPicker — każdy interfejs API, który używał GetForCurrentView() w środowisku UWP, wymaga uchwytu okna w WinUI 3.
Monit startowy
I'm migrating a UWP app to WinUI 3 using the Windows App SDK.
Apply these substitutions:
- Windows.UI.Xaml.* → Microsoft.UI.Xaml.*
- CoreDispatcher / Dispatcher.RunAsync → DispatcherQueue.TryEnqueue
- ApplicationView → AppWindow + AppWindowTitleBar
- CoreWindow → Microsoft.UI.Xaml.Window
- MessageDialog → ContentDialog (set XamlRoot, not InitializeWithWindow)
- FileOpenPicker / FileSavePicker / FolderPicker → add InitializeWithWindow
- Windows.UI.Notifications → Microsoft.Windows.AppNotifications
- SystemNavigationManager.BackRequested → NavigationView back handling
- Pivot → TabView, NavigationView (top mode), or RadioButtons (no direct equivalent)
- InkCanvas, InkToolbar, InkPresenter, InkStrokeContainer, and the other ink input types → Microsoft.UI.Xaml.Controls (experimental Windows App SDK releases only; if the project uses a stable release, flag them instead)
- Ink members that Windows App SDK 2.5.4-experimental doesn't include (new InkStrokeContainer(), assignments to InkPresenter.StrokeContainer, GetRecognitionResults, UpdateRecognitionResults, IsPenHapticFeedbackEnabled, InkToolbarRulerButton.Ruler, IsRulerButtonCheckedChanged, and progress or byte counts from SaveAsync and LoadAsync) → flag them
- PrintManager.GetForCurrentView → PrintManagerInterop.GetForWindow(hwnd)
- Win2D.uwp NuGet → Microsoft.Graphics.Win2D NuGet
- InkStroke, InkDrawingAttributes, InkPoint, InkStrokeBuilder → no change (Windows.UI.Input.Inking; use using aliases to avoid CS0104)
Do not use any Windows.UI.Xaml.* namespaces in new code.
Do not use CoreDispatcher — use DispatcherQueue.
Do not add InkToolbarEraserKind, SelectedEraser, or other eraser APIs from Windows App SDK 2.4.1-experimental. Version 2.5.4-experimental removed them.
x:Bind defaults to Mode=OneTime. Add Mode=OneWay for any binding that should update at runtime.
Flag any APIs without a direct WinUI 3 equivalent rather than guessing.
Zmiany w plikach projektu
Zastąp platformę docelową UWP:
<!-- Before (UWP) -->
<TargetPlatformVersion>10.0.19041.0</TargetPlatformVersion>
<TargetPlatformMinVersion>10.0.17763.0</TargetPlatformMinVersion>
<!-- After (WinUI 3) -->
<TargetFramework>net10.0-windows10.0.19041.0</TargetFramework>
<WindowsSdkPackageVersion>10.0.19041.31</WindowsSdkPackageVersion>
Dodaj pakiet Zestaw SDK do aplikacji systemu Windows:
dotnet add package Microsoft.WindowsAppSDK
Treści powiązane
- przewodnik po migracji Zestaw SDK do aplikacji systemu Windows — pełny przewodnik po migracji ręcznej
- Mapowanie interfejsów API i bibliotek platformy UWP do zestawu Zestaw SDK do aplikacji systemu Windows — kompleksowa tabela mapowania interfejsów API
- Co jest obsługiwane podczas migracji z platformy UWP do systemu WinUI — stan obsługi funkcji
- Migracja z WPF