Skip to content

[develop] Fix: UWP→WinUI namespace and reference replacements#13

Open
qiutongMS wants to merge 4 commits intodocsfrom
fix/develop/uwp-to-winui-namespace-and-reference-replacements
Open

[develop] Fix: UWP→WinUI namespace and reference replacements#13
qiutongMS wants to merge 4 commits intodocsfrom
fix/develop/uwp-to-winui-namespace-and-reference-replacements

Conversation

@qiutongMS
Copy link
Copy Markdown
Owner

Mechanical replacement of 65 UWP namespace references and API links across 45 pages. All changes follow the same pattern: Windows.UI.Xaml → Microsoft.UI.Xaml and /uwp/api/ → /windows/windows-app-sdk/api/winrt/.

@qiutongMS
Copy link
Copy Markdown
Owner Author

Review Result: APPROVED

This PR implements a large-scale mechanical replacement of UWP API reference links (/uwp/api/Windows.UI.Xaml.) with WinUI 3 paths (/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.) across 38 modified files.

The namespace and API link replacements are technically correct. WinUI 3 paths correctly map Windows.UI.Xaml.* to microsoft.ui.xaml.*. Additional code quality fixes (removal of deprecated ListViewItemRevealStyle, update of obsolete SystemControlAccentAcrylicWindowAccentMediumHighBrush) are also appropriate.

Must-Fix Issues

None.

Suggestions (non-blocking)

  1. identify-input-devices.md: File was touched (line-ending normalization across all 183 lines) but Windows.UI.Xaml API links were NOT updated — [Windows.UI.Xaml.Input] and 3x [TextBlock] still point to /uwp/api/Windows.UI.Xaml.*. The stated purpose of the PR was not accomplished for this file. Worth a follow-up pass.

  2. copy-and-paste.md and create-read-write-files.md: 195/195 and 359/359 symmetric line changes are line-ending normalization only — no actual link changes. Adds noise to the PR diff.

  3. adjust-layout-and-fonts.md: FlowDirection API links correctly updated to WinUI 3, but C#/C++/WinRT code examples still use Windows.UI.Xaml.FlowDirection (pre-existing inconsistency).

  4. forms.md: Replacement AcrylicBrush uses FallbackColor="Transparent" — on systems without acrylic support the background will be fully transparent. A theme brush fallback would be safer.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@qiutongMS qiutongMS force-pushed the fix/develop/uwp-to-winui-namespace-and-reference-replacements branch from 27b2cf3 to 51a4876 Compare May 8, 2026 09:50
@qiutongMS
Copy link
Copy Markdown
Owner Author

Review Result: CHANGES_REQUESTED

Summary

This PR performs a mechanical UWP→WinUI namespace replacement across 30 files. Most changes are correct, but 3 must-fix issues were found: two broken links (404s) introduced by the replacement, and link display texts that still show old UWP namespace qualifiers while targeting WinUI 3 API pages.


Must-Fix Issues

# File Section Issue Severity
1 hub/apps/develop/camera/capture-device-controls-for-photo-and-video-capture.md Tap-to-focus section CaptureElement linked to /windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.captureelement — returns 404. CaptureElement does not exist in WinUI 3 / Windows App SDK; it exists only in UWP (Windows.UI.Xaml.Controls.CaptureElement). Revert to /uwp/api/Windows.UI.Xaml.Controls.CaptureElement. must-fix
2 hub/apps/develop/launch/handle-uri-activation.md Important APIs list Windows.UI.Xaml.Application.OnActivated — link returns 404. Additionally, the prose says "In UWP apps, the [OnActivated]..." while linking to WinUI 3. If this section is describing UWP behavior, the link should revert to /uwp/api/windows.ui.xaml.application.onactivated. If it's describing WinUI 3, the link text display name must be corrected from Windows.UI.Xaml.Application.OnActivated to Microsoft.UI.Xaml.Application.OnActivated. must-fix
3 hub/apps/windows-app-sdk/migrate-to-windows-app-sdk/guides/keyboard-events.md Related APIs list Link display texts still show old UWP namespace qualifiers while link targets are now WinUI 3: KeyboardAccelerator class (Windows.UI.Xaml.Input), UIElement.CharacterReceived event (Windows.UI.Xaml), etc. In a migration guide explicitly contrasting Windows.UI.Xaml with Microsoft.UI.Xaml, showing the wrong namespace in link text is directly misleading. Update parenthetical namespace labels to (Microsoft.UI.Xaml.Input) and (Microsoft.UI.Xaml). must-fix

Suggestions

# File Section Suggestion Severity
1 hub/apps/develop/camera/*.md pages Throughout Camera pages still mix /uwp/api/ links (for Windows.Media.Devices, Windows.Media.Capture) with new /windows/windows-app-sdk/api/winrt/ XAML control links. Consider a brief note clarifying that camera device APIs are WinRT APIs shared across UWP and WinUI 3. suggestion
2 hub/apps/design/globalizing/adjust-layout-and-fonts--and-support-rtl.md Important APIs The Important APIs section now has one WinUI 3 link (FlowDirection) alongside one remaining UWP link (LanguageFont). Both are intentional but the mixed state may confuse readers. A comment distinguishing XAML-framework APIs from globalization WinRT APIs would help. suggestion

Page Health Assessment

File Overall Quality Notes
hub/apps/design/accessibility/custom-automation-peers.md ✅ Good Clean namespace update, correct WinUI 3 targets
hub/apps/design/globalizing/adjust-layout-and-fonts--and-support-rtl.md ✅ Good Valid replacements; LanguageFont correctly kept as UWP
hub/apps/design/layout/attached-layouts.md ✅ Good All API references correctly point to WinUI 3
hub/apps/design/layout/boxpanel-example-custom-panel.md ✅ Good Consistent namespace update
hub/apps/design/layout/custom-panels-overview.md ✅ Good Consistent namespace update
hub/apps/develop/camera/basic-photo-capture.md ✅ Good Only MediaPlayerElement changed (exists in WinUI 3)
hub/apps/develop/camera/capture-device-controls-for-photo-and-video-capture.md ❌ Broken link CaptureElement link → 404; class not in WinUI 3
hub/apps/develop/camera/process-media-frames-with-mediaframereader.md ✅ Good SoftwareBitmapSource, Image, MediaPlayerElement confirmed present in WinUI 3
hub/apps/develop/launch/handle-uri-activation.md ❌ Broken link Application.OnActivated link → 404; display text/target namespace mismatch
hub/apps/develop/platform/xaml/3-d-perspective-effects.md ✅ Good Correct WinUI 3 namespace replacements
hub/apps/develop/ui/controls/collection-commanding.md ✅ Good ListViewItemRevealStyle removed (not in WinUI 3), correct CoreWindow migration
hub/apps/develop/ui/controls/commanding.md ✅ Good ListViewItemRevealStyle removed, mixed UWP/WinUI links properly reconciled
hub/apps/develop/ui/controls/controls-and-events-intro.md ✅ Good Correct replacements
hub/apps/develop/ui/controls/custom-transport-controls.md ✅ Good Consistent namespace updates
hub/apps/develop/ui/controls/dialogs-and-flyouts/dialogs.md ✅ Good Single link correctly updated
hub/apps/develop/ui/controls/dialogs-and-flyouts/flyouts.md ✅ Good Single link correctly updated
hub/apps/develop/ui/controls/flipview.md ✅ Good Single link correctly updated
hub/apps/develop/ui/controls/forms.md ✅ Good AcrylicBrush replacement for removed WinUI 2 resource key is correct
hub/apps/develop/ui/controls/lists.md ✅ Good Single link correctly updated
hub/apps/develop/ui/controls/navigationview.md ✅ Good Single link correctly updated
hub/apps/develop/ui/controls/nested-ui.md ✅ Good Single link correctly updated
hub/apps/develop/ui/controls/pipspager.md ✅ Good Single link correctly updated
hub/apps/develop/ui/controls/radio-button.md ✅ Good Single link correctly updated
hub/apps/develop/ui/layout-panels.md ✅ Good All panel APIs confirmed present in WinUI 3
hub/apps/develop/ui/navigation/navigate-between-two-pages.md ✅ Good PageStackEntry, NavigationCacheMode correctly updated
hub/apps/develop/win2d/choosing-control-resolution.md ✅ Good Viewbox exists in WinUI 3
hub/apps/get-started/simple-photo-viewer-winui3.md ✅ Good INotifyPropertyChanged in WinUI 3 confirmed
hub/apps/windows-app-sdk/migrate-to-windows-app-sdk/guides/keyboard-events.md ⚠️ Needs attention Typo fix (Ui→UI) is good; but link display texts still show UWP namespace qualifiers
hub/apps/windows-app-sdk/mrtcore/tailor-resources-lang-scale-contrast.md ✅ Good FlowDirection correctly updated
hub/apps/winui/winui3/xaml-templated-controls-winui-3.md ✅ Good DependencyProperty, DependencyObject correctly updated

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@qiutongMS
Copy link
Copy Markdown
Owner Author

Review Result: CHANGES_REQUESTED

Summary

The PR correctly migrates most Windows.UI.Xaml namespace references to Microsoft.UI.Xaml with proper Windows App SDK link prefixes. However, one change introduces a broken link (404) in navigationview.md: the TypeName API URL was migrated to a path that does not exist in the Windows App SDK docs.

Must-Fix Issues

# File Section Issue Severity
1 hub/apps/develop/ui/controls/navigationview.md Navigation implementation example Windows::UI::Xaml::Interop::TypeName is a broken link (HTTP 404). The old /uwp/api/windows.ui.xaml.interop.typename URL was valid (HTTP 200). Additionally, the link text still says Windows::UI::Xaml::Interop::TypeName (UWP namespace) instead of Microsoft::UI::Xaml::Interop::TypeName (WinUI 3 namespace). must-fix

Suggestions

# File Section Suggestion Severity
1 hub/apps/develop/camera/capture-device-controls-for-photo-and-video-capture.md Tap-to-focus and pinch-to-zoom sections 3 CaptureElement links were changed from /uwp/api/Windows.UI.Xaml.Controls.CaptureElement to /uwp/api/windows.ui.xaml.controls.captureelement (casing only; URL prefix unchanged). CaptureElement does not exist in WinUI 3 (404 at /windows/windows-app-sdk/api/winrt/), so the UWP link is correct. Consider reverting these to the original casing to avoid confusion with the migration intent. suggestion
2 hub/apps/develop/ui/controls/dialogs-and-flyouts/dialogs.md Last paragraph (pre-existing) ApplicationView and AppWindow still link to legacy UWP classes. For a WinUI 3 ContentDialog page, AppWindow should reference the Windows App SDK Microsoft.UI.Windowing.AppWindow. This is pre-existing and not introduced by this PR. suggestion

Page Health Assessment

File Overall Quality Notes
hub/apps/develop/ui/controls/navigationview.md ⚠️ Needs fix Introduces a broken 404 link for TypeName; link text also retains UWP namespace
hub/apps/design/accessibility/custom-automation-peers.md ✅ Good Namespace links correctly migrated and verified
hub/apps/design/layout/custom-panels-overview.md ✅ Good Migrations correct; pre-existing LayoutCycleException UWP link not touched
hub/apps/develop/ui/controls/commanding.md ✅ Good Link updates + ListViewItemRevealStyle removal are correct
hub/apps/develop/ui/controls/forms.md ✅ Good AcrylicBrush substitution for removed UWP theme resource is correct
hub/apps/develop/camera/capture-device-controls-for-photo-and-video-capture.md ✅ Functional CaptureElement links work but are inconsistent with migration intent
All other 24 files ✅ Good Mechanical namespace/URL replacements verified; sample links reachable

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@qiutongMS
Copy link
Copy Markdown
Owner Author

Review Result: CHANGES_REQUESTED

Summary

The PR correctly migrates 65 namespace/link references across 30 files from UWP (Windows.UI.Xaml / /uwp/api/) to WinUI 3 (Microsoft.UI.Xaml / /windows/windows-app-sdk/api/winrt/). However, one file has a self-contradicting section introduced by the changes: the ### UWP APIs section in keyboard-events.md now contains WinUI 3 API links.

Must-Fix Issues

# File Section Issue Severity
1 hub/apps/windows-app-sdk/migrate-to-windows-app-sdk/guides/keyboard-events.md ### UWP APIs reference list Three entries under the ### UWP APIs heading were changed to WinUI 3 links (microsoft.ui.xaml.* / /windows/windows-app-sdk/api/winrt/) while the section heading and the remaining CoreWindow entry are still UWP. The section now contradicts itself — it says "UWP APIs" but links to Windows App SDK APIs. The heading should be updated (e.g., split the list, or retitle to reflect the mixed content). must-fix

Suggestions

# File Section Suggestion Severity
1 hub/apps/develop/ui/controls/custom-transport-controls.md "Important APIs" callout (line ~15) MediaTransportControls is still linked to /uwp/api/Windows.Media.SystemMediaTransportControls — the wrong class (SystemMediaTransportControls is a system/OS control surface, not the XAML control). This is a pre-existing bug, but since the other two links in the same callout were migrated, consider also updating this to /windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.mediatransportcontrols. suggestion
2 hub/apps/develop/ui/controls/navigationview.md C++/WinRT navigation example Windows::UI::Xaml::Interop::TypeName was correctly renamed to Microsoft::UI::Xaml::Interop::TypeName but the hyperlink to the API docs was dropped entirely. Consider adding a link to the WinUI 3 API reference for discoverability. suggestion

Page Health Assessment

File Overall Quality Notes
hub/apps/windows-app-sdk/migrate-to-windows-app-sdk/guides/keyboard-events.md ⚠️ Needs attention ### UWP APIs section heading contradicts its new WinUI 3 content
hub/apps/develop/ui/controls/custom-transport-controls.md ⚠️ Needs attention Wrong class linked for MediaTransportControls (pre-existing, but surface to fix)
hub/apps/develop/ui/controls/navigationview.md ✅ Good Minor: dropped hyperlink on TypeName reference
All other 27 files ✅ Good Namespace/link replacements are mechanically correct; WinRT-foundation types (Windows.Foundation.Size, etc.) and non-XAML-UI APIs (MediaPlayer, CaptureElement, etc.) correctly left as UWP links

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@qiutongMS
Copy link
Copy Markdown
Owner Author

Review Result: APPROVED

Summary

All 30 files contain technically correct WinUI 3 migrations: Windows.UI.XamlMicrosoft.UI.Xaml namespace replacements, /uwp/api//windows/windows-app-sdk/api/winrt/ link updates, and several non-namespace API modernizations (CoreWindow, ListViewItemRevealStyle, DisplayInformation, WebViewWebView2). No must-fix issues were found.

Must-Fix Issues

None.

Suggestions

# File Section Suggestion Severity
1 hub/apps/develop/ui/controls/dialogs-and-flyouts/flyouts.md XAML snippet ~line 179 WebView2 is correct for WinUI 3, but consider adding a note that WebView2 may require calling EnsureCoreWebView2Async() on first use. suggestion
2 hub/apps/develop/ui/controls/forms.md XAML snippet ~line 174 The new AcrylicBrush with BackgroundSource="HostBackdrop" works best when the app window has a system backdrop enabled. Consider noting this requirement. suggestion
3 hub/apps/develop/ui/controls/custom-transport-controls.md Important APIs callout Pre-existing issue (not introduced by this PR): MediaTransportControls links to SystemMediaTransportControls (the OS-level API), not the XAML MediaTransportControls class. Worth fixing in a follow-up. suggestion

Page Health Assessment

All 30 modified files read well. Notable highlights:

  • collection-commanding.md: CoreWindow → InputKeyboardSource.GetKeyStateForCurrentThread() is the correct WinUI 3 pattern; ListViewItemRevealStyle removal is correct.
  • nested-ui.md: DisplayInformation.GetForCurrentView().RawPixelsPerViewPixel → XamlRoot.RasterizationScale is the correct WinUI 3 migration.
  • keyboard-events.md: Fixed capitalization Microsoft.Ui.Xaml → Microsoft.UI.Xaml (correct).
  • Non-XAML APIs in camera/media files (Windows.Media., Windows.Globalization.) were correctly left on /uwp/api/ paths as they have no WinUI 3 equivalents.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant