From 3195996eb9f2d1ff199ae2c9cbb7dd43872e27a5 Mon Sep 17 00:00:00 2001 From: shisan Date: Mon, 16 Mar 2026 17:08:25 +0800 Subject: [PATCH 1/7] Tsg update/20260316 9a6e84d2 (#7) * Update TSGs (15 files) - 20260316 --- index/index.json | 1589 +++++++++++++++++ tsg/tsg_api_gaps_unpackaged_support.md | 202 +++ tsg/tsg_appcontainer_identity_sharing.md | 153 ++ tsg/tsg_background_tasks_printing_tooling.md | 233 +++ tsg/tsg_deployment_singlefile_installer.md | 161 ++ tsg/tsg_deployment_wasdk18_windows10.md | 173 ++ tsg/tsg_external_interop_issues.md | 191 ++ tsg/tsg_file_access_storage_pickers.md | 199 +++ tsg/tsg_msix_build_publish_output_failures.md | 171 ++ tsg/tsg_msix_project_configuration_tooling.md | 150 ++ ..._msix_selfcontained_packaging_conflicts.md | 130 ++ tsg/tsg_notifications_push_and_listener.md | 182 ++ tsg/tsg_resources_mrt_localization.md | 151 ++ tsg/tsg_runtime_winrt_interop.md | 199 +++ tsg/tsg_widgets_customization_display.md | 121 ++ 15 files changed, 4005 insertions(+) create mode 100644 index/index.json create mode 100644 tsg/tsg_api_gaps_unpackaged_support.md create mode 100644 tsg/tsg_appcontainer_identity_sharing.md create mode 100644 tsg/tsg_background_tasks_printing_tooling.md create mode 100644 tsg/tsg_deployment_singlefile_installer.md create mode 100644 tsg/tsg_deployment_wasdk18_windows10.md create mode 100644 tsg/tsg_external_interop_issues.md create mode 100644 tsg/tsg_file_access_storage_pickers.md create mode 100644 tsg/tsg_msix_build_publish_output_failures.md create mode 100644 tsg/tsg_msix_project_configuration_tooling.md create mode 100644 tsg/tsg_msix_selfcontained_packaging_conflicts.md create mode 100644 tsg/tsg_notifications_push_and_listener.md create mode 100644 tsg/tsg_resources_mrt_localization.md create mode 100644 tsg/tsg_runtime_winrt_interop.md create mode 100644 tsg/tsg_widgets_customization_display.md diff --git a/index/index.json b/index/index.json new file mode 100644 index 0000000..036cec2 --- /dev/null +++ b/index/index.json @@ -0,0 +1,1589 @@ +{ + "version": "2026-03-16", + "generatedAt": "2026-03-16T03:34:46.570835+00:00", + "totalEntries": 22, + "entries": [ + { + "id": "known_issue_api_docs_storagefile", + "path": "E:\\issue-tsg-generator\\output\\known_issue_api_docs_storagefile.md", + "title": "Known Issue: Missing AppWindow Placement API Documentation & StorageFile Shortcut File Support", + "area": "Storage", + "symptoms": [], + "errorCodes": [], + "keywords": [ + "AppWindow", + "GetCurrentPlacement", + "SaveCurrentPlacement", + "PlacementRestorationBehavior", + "PlacementInfo", + "DisplayArea", + "GetMetricsFromWindowId", + "PersistedStateId", + "experimental API", + "StorageFile", + "shortcut", + ".lnk", + ".url", + ".wsh", + "file handler" + ], + "severity": "critical", + "relatedIssues": [ + "microsoft/WindowsAppSDK#5896", + "microsoft/WindowsAppSDK#518", + "microsoft/WindowsAppSDK#5896", + "microsoft/WindowsAppSDK#518" + ] + }, + { + "id": "known_issue_api_gaps_localization", + "path": "E:\\issue-tsg-generator\\output\\known_issue_api_gaps_localization.md", + "title": "Known Issue: PrimaryLanguageOverride Not Persisted & Missing PackageManager API", + "area": "Runtime", + "symptoms": [], + "errorCodes": [], + "keywords": [ + "PrimaryLanguageOverride", + "null", + "empty", + "not persisted", + "localization", + "Microsoft.Windows.Globalization", + "MovePackageToVolumeAsync", + "PackageDeploymentManager", + "WASDK 2.0" + ], + "severity": "critical", + "relatedIssues": [ + "microsoft/WindowsAppSDK#6118", + "microsoft/WindowsAppSDK#1687", + "microsoft/WindowsAppSDK#6118", + "microsoft/WindowsAppSDK#6118", + "microsoft/WindowsAppSDK#6118", + "microsoft/WindowsAppSDK#6118", + "microsoft/WindowsAppSDK#6221", + "microsoft/WindowsAppSDK#6221" + ] + }, + { + "id": "known_issue_msix_buildtools_defects", + "path": "E:\\issue-tsg-generator\\output\\known_issue_msix_buildtools_defects.md", + "title": "Known Issue: MSIX Build Tools Defects and Documentation Gaps", + "area": "Deployment", + "symptoms": [], + "errorCodes": [], + "keywords": [ + "Microsoft.Windows.SDK.BuildTools.MSIX", + "AppxSymbolPackageEnabled", + "_GenerateAppxSymbolPackage", + "mspdbcmf.exe", + "msixbundle", + "Dependencies folder", + "Publish error", + "wapproj", + "documentation", + "roadmap" + ], + "severity": "critical", + "relatedIssues": [ + "microsoft/WindowsAppSDK#6183", + "microsoft/WindowsAppSDK#6147", + "microsoft/WindowsAppSDK#6261", + "microsoft/WindowsAppSDK#3065", + "microsoft/WindowsAppSDK#6183", + "microsoft/WindowsAppSDK#6147", + "microsoft/WindowsAppSDK#1808", + "microsoft/WindowsAppSDK#6261", + "microsoft/WindowsAppSDK#3065" + ] + }, + { + "id": "known_issue_msix_nuget_license", + "path": "E:\\issue-tsg-generator\\output\\known_issue_msix_nuget_license.md", + "title": "Known Issue: NuGet Package License Forbids Redistribution of Bootstrap DLL", + "area": "Deployment", + "symptoms": [], + "errorCodes": [], + "keywords": [ + "Microsoft.WindowsAppSDK.Foundation", + "bootstrap DLL", + "NuGet license", + "redistribution", + "Microsoft.WindowsAppSDK", + "license terms" + ], + "severity": "critical", + "relatedIssues": [ + "microsoft/WindowsAppSDK#6288", + "microsoft/WindowsAppSDK#3498", + "microsoft/WindowsAppSDK#6288", + "microsoft/WindowsAppSDK#3498" + ] + }, + { + "id": "known_issue_performance_crashes", + "path": "E:\\issue-tsg-generator\\output\\known_issue_performance_crashes.md", + "title": "Known Issue: WinRT API Performance Overhead & Packaged App Crashes in Admin Mode on Windows 10", + "area": "Runtime", + "symptoms": [], + "errorCodes": [ + "0xc000027b" + ], + "keywords": [ + "WinRT", + "ApplicationData", + "Package.Current", + "performance", + "latency", + "25ms", + "admin mode", + "elevated", + "packaged app crash", + "Windows 10", + "0xc000027b" + ], + "severity": "critical", + "relatedIssues": [ + "microsoft/WindowsAppSDK#6223", + "microsoft/WindowsAppSDK#6223", + "microsoft/WindowsAppSDK#6223", + "microsoft/WindowsAppSDK#6268", + "microsoft/WindowsAppSDK#2555", + "microsoft/WindowsAppSDK#6268", + "microsoft/WindowsAppSDK#6268" + ] + }, + { + "id": "known_issue_widget_platform_defects", + "path": "E:\\issue-tsg-generator\\output\\known_issue_widget_platform_defects.md", + "title": "Known Issue: Widget Settings Panel Reloads Instead of Closing & Widget Not Appearing After Install", + "area": "Widgets", + "symptoms": [], + "errorCodes": [], + "keywords": [ + "widget settings", + "close button", + "reload", + "widget board", + "widget not appearing", + "reinstall", + "customize widget", + "Windows Widgets", + "WidgetProviders" + ], + "severity": "critical", + "relatedIssues": [ + "microsoft/WindowsAppSDK#6141", + "microsoft/WindowsAppSDK#3958", + "microsoft/WindowsAppSDK#6141", + "microsoft/WindowsAppSDK#3958" + ] + }, + { + "id": "known_issues_external_notifications", + "path": "E:\\issue-tsg-generator\\output\\known_issues_external_notifications.md", + "title": "Known Issues: MSIX Data Retention, Toast Rendering, and AppNotification Registration", + "area": "Runtime", + "symptoms": [], + "errorCodes": [ + "COMException" + ], + "keywords": [ + "MSIX", + "uninstall", + "data retention", + "app data", + "keep data", + "game data", + "reinstall" + ], + "severity": "critical", + "relatedIssues": [ + "microsoft/WindowsAppSDK#6260", + "microsoft/WindowsAppSDK#13", + "microsoft/WindowsAppSDK#4026", + "microsoft/WindowsAppSDK#6071" + ] + }, + { + "id": "known_issues_file_access_pickers", + "path": "E:\\issue-tsg-generator\\output\\known_issues_file_access_pickers.md", + "title": "Known Issue: Storage Picker Missing Features and Unexpected Behavior", + "area": "Storage", + "symptoms": [], + "errorCodes": [], + "keywords": [ + "SettingsIdentifier", + "FileOpenPicker", + "FileSavePicker", + "FolderPicker", + "last used location", + "Microsoft.Windows.Storage.Pickers" + ], + "severity": "critical", + "relatedIssues": [ + "microsoft/WindowsAppSDK#5847", + "microsoft/WindowsAppSDK#5976" + ] + }, + { + "id": "api_gaps_unpackaged_support", + "path": "E:\\issue-tsg-generator\\output\\tsg_api_gaps_unpackaged_support.md", + "title": "API Gaps: Unpackaged App Support, Storage & Package Management - Windows App SDK", + "area": "WinML", + "symptoms": [ + "`ApplicationData.Current` fails in an unpackaged (non-MSIX) app", + "Need app metadata (display name, icon, etc.) in an unpackaged app", + "WASDK `PackageVolume` is missing `FindPackage`-related APIs available in the platform type", + "Want to register as a default file handler by MIME content type instead of individual file extensions" + ], + "errorCodes": [], + "keywords": [ + "ApplicationData", + "unpackaged", + "AppInfo", + "package identity", + "StorageFolder", + "PackageVolume", + "FindPackage", + "content type", + "file handler", + "file association", + "manifest", + "LOCALAPPDATA" + ], + "severity": "critical", + "relatedIssues": [ + "microsoft/WindowsAppSDK#2639", + "microsoft/WindowsAppSDK#1083", + "microsoft/WindowsAppSDK#27", + "microsoft/WindowsAppSDK#6222", + "microsoft/WindowsAppSDK#2639", + "microsoft/WindowsAppSDK#2639", + "microsoft/WindowsAppSDK#1083", + "microsoft/WindowsAppSDK#27", + "microsoft/WindowsAppSDK#6222" + ] + }, + { + "id": "appcontainer_identity_sharing", + "path": "E:\\issue-tsg-generator\\output\\tsg_appcontainer_identity_sharing.md", + "title": "AppContainer for Win32 Apps & Named Object Sharing Between Packaged/Win32", + "area": "Runtime", + "symptoms": [ + "You want to run a Win32/WinUI 3 MSIX app in an AppContainer sandbox", + "`Shell_NotifyIcon` returns access denied in AppContainer", + "You need to share named objects (mutexes, events) between packaged and Win32 apps", + "You're trying to configure `PartialTrustApplication` in a `.wapproj` packaging project" + ], + "errorCodes": [], + "keywords": [ + "AppContainer", + "Win32", + "PartialTrustApplication", + "partial trust", + "sandboxing", + "named objects", + "security descriptor", + "PackageFamilyName", + "PFN", + "Shell_NotifyIcon", + "tray icon", + "MSIX", + "runFullTrust", + "permissiveLearningMode" + ], + "severity": "critical", + "relatedIssues": [ + "microsoft/WindowsAppSDK#219", + "microsoft/WindowsAppSDK#175", + "microsoft/WindowsAppSDK#219", + "microsoft/WindowsAppSDK#219", + "microsoft/WindowsAppSDK#219", + "microsoft/WindowsAppSDK#219", + "microsoft/WindowsAppSDK#219", + "microsoft/WindowsAppSDK#219", + "microsoft/WindowsAppSDK#219", + "microsoft/WindowsAppSDK#219", + "microsoft/WindowsAppSDK#219", + "microsoft/WindowsAppSDK#175", + "microsoft/WindowsAppSDK#175", + "microsoft/WindowsAppSDK#175" + ] + }, + { + "id": "background_tasks_printing_tooling", + "path": "E:\\issue-tsg-generator\\output\\tsg_background_tasks_printing_tooling.md", + "title": "Background Task Crashes, Print Preview Dark Theme & VS Tooling - Windows App SDK", + "area": "Runtime", + "symptoms": [ + "Background task crashes with `STOWED_EXCEPTION` in `UniversalBGTask.dll`", + "Partner Center shows thousands of daily crashes from background task execution", + "Print preview window displays empty/blank content with dark theme", + "Cannot add new WinUI Page items in Visual Studio 2022" + ], + "errorCodes": [ + "0x80004002", + "0x80004005", + "0x800706ba", + "0x80080204", + "0xC00CE169", + "E_FAIL", + "E_NOINTERFACE" + ], + "keywords": [ + "UniversalBGTask", + "STOWED_EXCEPTION", + "background task", + "crash", + "0x80004005", + "0x80004002", + "0x800706ba", + "0x80080204", + "0xC00CE169", + "ACCESS_VIOLATION", + "PrintPreview", + "dark theme", + "RequestedTheme", + "empty preview", + "Visual Studio 2022", + "add page", + "new item" + ], + "severity": "critical", + "relatedIssues": [ + "microsoft/WindowsAppSDK#5870", + "microsoft/WindowsAppSDK#6086", + "microsoft/WindowsAppSDK#1236", + "microsoft/WindowsAppSDK#5870", + "microsoft/WindowsAppSDK#5870", + "microsoft/WindowsAppSDK#6086", + "microsoft/WindowsAppSDK#1236" + ] + }, + { + "id": "deployment_singlefile_installer", + "path": "E:\\issue-tsg-generator\\output\\tsg_deployment_singlefile_installer.md", + "title": "Error: \"XamlParseException: XAML parsing failed\" — Renamed Single-File Unpackaged App / Broken Runtime Links", + "area": "Deployment", + "symptoms": [ + "You published a WinUI 3 app as single-file unpackaged and renamed the `.exe`", + "Error contains \"XamlParseException\" or \"XAML parsing failed\" after renaming", + "WASDK 2.0 Preview runtime download links return 404", + "WASDK 1.6.3 installers ship binaries that still crash despite documented fixes" + ], + "errorCodes": [], + "keywords": [ + "XamlParseException", + "XAML parsing failed", + "single-file", + "unpackaged", + "rename executable", + "PublishSingleFile", + "runtime links broken", + "2.0 preview", + "installer binaries", + "MRM.dll crash" + ], + "severity": "critical", + "relatedIssues": [ + "microsoft/WindowsAppSDK#6248", + "microsoft/WindowsAppSDK#6220", + "microsoft/WindowsAppSDK#4977", + "microsoft/WindowsAppSDK#6248", + "microsoft/WindowsAppSDK#6248", + "microsoft/WindowsAppSDK#6220", + "microsoft/WindowsAppSDK#6220", + "microsoft/WindowsAppSDK#4977", + "microsoft/WindowsAppSDK#4977", + "microsoft/WindowsAppSDK#4977" + ] + }, + { + "id": "deployment_wasdk18_windows10", + "path": "E:\\issue-tsg-generator\\output\\tsg_deployment_wasdk18_windows10.md", + "title": "Error: App Crash on Launch / \"FindPackagesByPackageFamily\" Failure — WASDK 1.8 on Windows 10", + "area": "Deployment", + "symptoms": [ + "WinUI 3 / WASDK 1.8+ packaged app crashes immediately on launch on Windows 10 (builds 17763, 19041, 19045)", + "`FindPackagesByPackageFamily()` fails to locate WASDK 1.8 runtime packages on Windows 10", + "No error dialog — the app silently exits", + "Same app works fine on Windows 11" + ], + "errorCodes": [ + "0x80070005", + "0xc000027b" + ], + "keywords": [ + "FindPackagesByPackageFamily", + "WASDK 1.8", + "Windows 10", + "17763", + "19041", + "DeploymentManager", + "crash on launch", + "0x80070005", + "DDLM PackageFullName", + "MSIX.inventory" + ], + "severity": "critical", + "relatedIssues": [ + "microsoft/WindowsAppSDK#6117", + "microsoft/WindowsAppSDK#6254", + "microsoft/WindowsAppSDK#6156", + "microsoft/WindowsAppSDK#6117", + "microsoft/WindowsAppSDK#6254", + "microsoft/WindowsAppSDK#6117", + "microsoft/WindowsAppSDK#6254", + "microsoft/WindowsAppSDK#6117", + "microsoft/WindowsAppSDK#6117", + "microsoft/WindowsAppSDK#6156", + "microsoft/WindowsAppSDK#6156", + "microsoft/WindowsAppSDK#6117", + "microsoft/WindowsAppSDK#6254" + ] + }, + { + "id": "external_interop_issues", + "path": "E:\\issue-tsg-generator\\output\\tsg_external_interop_issues.md", + "title": "External / Interop Issues — Packaging, Device APIs, and Widgets", + "area": "Runtime", + "symptoms": [ + "MSIX bundle contains wrong (stale) NuGet DLL versions after package downgrade", + "Error `0x8007007A` on app startup from `FindPackagesByPackageFamily`", + "Bluetooth device pairing UI fails to show in WinUI 3 desktop app", + "NFC `ProximityDevice` events never fire after UWP → WinUI 3 migration", + "Widgets panel: first widget (alphabetically) cannot be added" + ], + "errorCodes": [ + "0x8007007A", + "E_FILTER_HEAD" + ], + "keywords": [ + "packaging project", + "NuGet", + "stale assembly", + "MSIX bundle", + "FindPackagesByPackageFamily", + "0x8007007A", + "ERROR_INSUFFICIENT_BUFFER", + "DeviceInformationPairing", + "Bluetooth", + "ProximityDevice", + "NFC", + "Widgets", + "WinUI 3" + ], + "severity": "critical", + "relatedIssues": [ + "microsoft/WindowsAppSDK#6253", + "microsoft/WindowsAppSDK#6274", + "microsoft/WindowsAppSDK#3091", + "microsoft/WindowsAppSDK#4356", + "microsoft/WindowsAppSDK#6140", + "microsoft/WindowsAppSDK#6253", + "microsoft/WindowsAppSDK#6274", + "microsoft/WindowsAppSDK#3091", + "microsoft/WindowsAppSDK#4356", + "microsoft/WindowsAppSDK#6140" + ] + }, + { + "id": "file_access_storage_pickers", + "path": "E:\\issue-tsg-generator\\output\\tsg_file_access_storage_pickers.md", + "title": "Storage Picker Issues — File Access & Picker Dialogs", + "area": "Storage", + "symptoms": [ + "Error contains \"E_FAIL\" or \"COMException\" when calling `PickSingleFileAsync()` or `PickSaveFileAsync()`", + "File/Folder picker dialog behaves unexpectedly (wrong extension, missing folders, wrong language)", + "Using `FileOpenPicker`, `FileSavePicker`, or `FolderPicker` from a WinUI 3 / Windows App SDK desktop app", + "Platform: Windows App SDK (packaged or unpackaged), WinUI 3" + ], + "errorCodes": [ + "0x80004005", + "COMException", + "E_FAIL" + ], + "keywords": [ + "FileOpenPicker", + "FileSavePicker", + "FolderPicker", + "storage pickers", + "file picker crash", + "COMException", + "E_FAIL", + "IInitializeWithWindow", + "DefaultFileExtension", + "FileTypeChoices", + "WSL", + "RTL", + "language override" + ], + "severity": "critical", + "relatedIssues": [ + "microsoft/WindowsAppSDK#1063", + "microsoft/WindowsAppSDK#2504", + "microsoft/WindowsAppSDK#5975", + "microsoft/WindowsAppSDK#6284", + "microsoft/WindowsAppSDK#6105", + "microsoft/WindowsAppSDK#2504", + "microsoft/WindowsAppSDK#1063", + "microsoft/WindowsAppSDK#5975", + "microsoft/WindowsAppSDK#6284", + "microsoft/WindowsAppSDK#6105" + ] + }, + { + "id": "msix_build_publish_output_failures", + "path": "E:\\issue-tsg-generator\\output\\tsg_msix_build_publish_output_failures.md", + "title": "Error: MSIX Build/Publish Output Failures (msixupload, msixbundle, appxsym)", + "area": "Deployment", + "symptoms": [ + "Building an MSIX bundle or upload package fails with MSB4036 or MSB6006", + "`msbuild` with `UapAppxPackageBuildMode=StoreUpload` does not produce `.msixupload`", + "Publishing an MSIX from Visual Studio pollutes `.csproj.user` with `UapAppxPackageBuildMode`", + "`mspdbcmf.exe` exits with fatal error CMF1106 during symbol package generation" + ], + "errorCodes": [], + "keywords": [ + "msixupload", + "msixbundle", + "appxsym", + "WinAppSdkSignAppxPackageBundle", + "MSB4036", + "MSB6006", + "mspdbcmf.exe", + "CMF1106", + "UapAppxPackageBuildMode", + "StoreUpload", + "StoreAndSideload" + ], + "severity": "critical", + "relatedIssues": [ + "microsoft/WindowsAppSDK#5820", + "microsoft/WindowsAppSDK#5825", + "microsoft/WindowsAppSDK#5501", + "microsoft/WindowsAppSDK#5537", + "microsoft/WindowsAppSDK#5820", + "microsoft/WindowsAppSDK#5820", + "microsoft/WindowsAppSDK#5825", + "microsoft/WindowsAppSDK#5825", + "microsoft/WindowsAppSDK#6183", + "microsoft/WindowsAppSDK#5501", + "microsoft/WindowsAppSDK#5501", + "microsoft/WindowsAppSDK#5537", + "microsoft/WindowsAppSDK#5537", + "microsoft/WindowsAppSDK#5820", + "microsoft/WindowsAppSDK#5825", + "microsoft/WindowsAppSDK#5501", + "microsoft/WindowsAppSDK#5537" + ] + }, + { + "id": "msix_project_configuration_tooling", + "path": "E:\\issue-tsg-generator\\output\\tsg_msix_project_configuration_tooling.md", + "title": "Error: MSIX Project Configuration & Build Tools Issues", + "area": "Deployment", + "symptoms": [ + "Building MSIX packages without Visual Studio installed fails due to missing `mspdbcmf.exe`", + "Removing `EnableMsixTooling` from unpackaged app projects causes publish failures or missing `.pri` files", + "`AppxOSMinVersionReplaceManifestVersion=false` is ignored by single-project MSIX", + "Need to include multiple executables in a single MSIX package" + ], + "errorCodes": [], + "keywords": [ + "EnableMsixTooling", + "Microsoft.Windows.SDK.BuildTools.MSIX", + "AppxOSMinVersionReplaceManifestVersion", + "AppxOSMaxVersionTestedReplaceManifestVersion", + "mspdbcmf.exe", + "wapproj", + "single-project MSIX", + "NuGet", + "Visual Studio", + "unpackaged", + "resources.pri" + ], + "severity": "critical", + "relatedIssues": [ + "microsoft/WindowsAppSDK#6197", + "microsoft/WindowsAppSDK#3718", + "microsoft/WindowsAppSDK#5598", + "microsoft/WindowsAppSDK#5586", + "microsoft/WindowsAppSDK#6197", + "microsoft/WindowsAppSDK#3718", + "microsoft/WindowsAppSDK#3718", + "microsoft/WindowsAppSDK#5746", + "microsoft/WindowsAppSDK#3718", + "microsoft/WindowsAppSDK#5598", + "microsoft/WindowsAppSDK#5586", + "microsoft/WindowsAppSDK#5586", + "microsoft/WindowsAppSDK#5586", + "microsoft/WindowsAppSDK#6261", + "microsoft/WindowsAppSDK#3718", + "microsoft/WindowsAppSDK#6197", + "microsoft/WindowsAppSDK#3718", + "microsoft/WindowsAppSDK#5598", + "microsoft/WindowsAppSDK#5586" + ] + }, + { + "id": "msix_selfcontained_packaging_conflicts", + "path": "E:\\issue-tsg-generator\\output\\tsg_msix_selfcontained_packaging_conflicts.md", + "title": "Error: Self-Contained Deployment and MSIX Packaging Conflicts", + "area": "Deployment", + "symptoms": [ + "Setting `WindowsAppSDKSelfContained=true` on a library project causes XAML parsing or codegen failures", + "Upgrading to WinAppSDK 1.8 causes COMException 0x80070490 (Element not found) related to `.pri` file naming changes", + "Build errors include `NETSDK1022` (duplicate items) or `WMC1012` (multiple ApplicationXaml) after upgrading" + ], + "errorCodes": [ + "0x80070490", + "COMException" + ], + "keywords": [ + "WindowsAppSDKSelfContained", + "XamlParseException", + "COMException", + "0x80070490", + "resources.pri", + "PRI", + "_OverrideGetPriIndexName", + "EnableMsixTooling", + "WMC1012", + "ApplicationXaml", + "codegen", + "library project" + ], + "severity": "critical", + "relatedIssues": [ + "microsoft/WindowsAppSDK#6091", + "microsoft/WindowsAppSDK#5746", + "microsoft/WindowsAppSDK#6091", + "microsoft/WindowsAppSDK#6091", + "microsoft/WindowsAppSDK#6091", + "microsoft/WindowsAppSDK#6091", + "microsoft/WindowsAppSDK#5746", + "microsoft/WindowsAppSDK#5746", + "microsoft/WindowsAppSDK#5746", + "microsoft/WindowsAppSDK#6091", + "microsoft/WindowsAppSDK#5746" + ] + }, + { + "id": "notifications_push_and_listener", + "path": "E:\\issue-tsg-generator\\output\\tsg_notifications_push_and_listener.md", + "title": "Notification Issues — Push Notifications, Progress Data, and UserNotificationListener", + "area": "Runtime", + "symptoms": [ + "Error contains `0x80070490` (\"Element not found\") when subscribing to notification events", + "Push notifications fail in unpackaged or non-Store apps", + "Cannot create an indeterminate progress bar in toast notifications via `AppNotificationProgressData`", + "`UserNotificationListener.NotificationChanged` throws `COMException` in unpackaged apps", + "Platform: Windows App SDK, WinUI 3, unpackaged or self-contained apps" + ], + "errorCodes": [ + "0x80070490", + "COMException" + ], + "keywords": [ + "AppNotification", + "push notification", + "unpackaged", + "COMException", + "0x80070490", + "Element not found", + "UserNotificationListener", + "NotificationChanged", + "AppNotificationProgressData", + "IsIndeterminate", + "indeterminate progress bar", + "toast notification" + ], + "severity": "critical", + "relatedIssues": [ + "microsoft/WindowsAppSDK#334", + "microsoft/WindowsAppSDK#2231", + "microsoft/WindowsAppSDK#6172", + "microsoft/WindowsAppSDK#334", + "microsoft/WindowsAppSDK#2231", + "microsoft/WindowsAppSDK#6172" + ] + }, + { + "id": "resources_mrt_localization", + "path": "E:\\issue-tsg-generator\\output\\tsg_resources_mrt_localization.md", + "title": "Error: \"COMException: NamedResource Not Found\" / PrimaryLanguageOverride Not Working — MRT Resource Loading", + "area": "Runtime", + "symptoms": [ + "`ResourceLoader.GetString()` throws `COMException` for keys containing `.` (dots)", + "`PrimaryLanguageOverride` does not work in unpackaged WinUI 3 apps", + "`x:Uid` XAML localization fails for unpackaged apps", + "Signing `Microsoft.Windows.ApplicationModel.Resources.Projection` fails during build" + ], + "errorCodes": [ + "COMException" + ], + "keywords": [ + "ResourceLoader", + "GetString", + "COMException", + "NamedResource Not Found", + "PrimaryLanguageOverride", + "unpackaged", + "localization", + "x:Uid", + "MRTCore", + "Resources.resw", + "dot in key", + "signing projection" + ], + "severity": "critical", + "relatedIssues": [ + "microsoft/WindowsAppSDK#6247", + "microsoft/WindowsAppSDK#1687", + "microsoft/WindowsAppSDK#3705", + "microsoft/WindowsAppSDK#6247", + "microsoft/WindowsAppSDK#1687", + "microsoft/WindowsAppSDK#1687", + "microsoft/WindowsAppSDK#1687", + "microsoft/WindowsAppSDK#1687", + "microsoft/WindowsAppSDK#1687", + "microsoft/WindowsAppSDK#1687", + "microsoft/WindowsAppSDK#3705", + "microsoft/WindowsAppSDK#3705" + ] + }, + { + "id": "runtime_winrt_interop", + "path": "E:\\issue-tsg-generator\\output\\tsg_runtime_winrt_interop.md", + "title": "WinRT Interop, AOT Compatibility & Runtime Version Issues - Windows App SDK", + "area": "Runtime", + "symptoms": [ + "Theme switching code fails silently when app is published with Native AOT", + "`Window.Content as FrameworkElement` returns `null` in AOT builds", + "`AppActivationArguments.Data` is `WinRT.IInspectable` instead of a typed activation args object", + "`ReleaseInfo.AsString` returns wrong version (e.g., \"1.7.0\" on 1.7.1)", + "HDR content renders as SDR when using `CompositionDrawingSurface` with float16 pixel format" + ], + "errorCodes": [], + "keywords": [ + "AOT", + "trimming", + "FrameworkElement", + "theme", + "LaunchActivatedEventArgs", + "WinRT", + "CsWinRT", + "IInspectable", + "ReleaseInfo", + "version string", + "HDR", + "CompositionDrawingSurface", + "scRGB", + "swap chain", + "DirectXPixelFormat" + ], + "severity": "critical", + "relatedIssues": [ + "microsoft/WindowsAppSDK#5389", + "microsoft/WindowsAppSDK#6219", + "microsoft/WindowsAppSDK#5323", + "microsoft/WindowsAppSDK#6291", + "microsoft/WindowsAppSDK#5389", + "microsoft/WindowsAppSDK#6219", + "microsoft/WindowsAppSDK#5323", + "microsoft/WindowsAppSDK#6291" + ] + }, + { + "id": "widgets_customization_display", + "path": "E:\\issue-tsg-generator\\output\\tsg_widgets_customization_display.md", + "title": "Widget Customization and Display Failures - Windows Widgets Platform", + "area": "Widgets", + "symptoms": [ + "Widget customization panel opens but shows no content", + "`OnCustomizationRequested` callback is never invoked by widget host", + "First widget in alphabetical list cannot be added to widget board", + "Widget \"Add\" button stays inactive until switching to another widget and back" + ], + "errorCodes": [], + "keywords": [ + "widget customization", + "template JSON", + "OnCustomizationRequested", + "widget board", + "add widget", + "widget list", + "Widgets panel" + ], + "severity": "critical", + "relatedIssues": [ + "microsoft/WindowsAppSDK#3926", + "microsoft/WindowsAppSDK#6140", + "microsoft/WindowsAppSDK#3926", + "microsoft/WindowsAppSDK#6140" + ] + } + ], + "areaCounts": { + "Storage": 3, + "Runtime": 9, + "Deployment": 7, + "Widgets": 2, + "WinML": 1 + }, + "invertedIndex": { + "byErrorCode": { + "0xc000027b": [ + "known_issue_performance_crashes", + "deployment_wasdk18_windows10" + ], + "COMException": [ + "known_issues_external_notifications", + "file_access_storage_pickers", + "msix_selfcontained_packaging_conflicts", + "notifications_push_and_listener", + "resources_mrt_localization" + ], + "0x80004002": [ + "background_tasks_printing_tooling" + ], + "0x80004005": [ + "background_tasks_printing_tooling", + "file_access_storage_pickers" + ], + "0x800706ba": [ + "background_tasks_printing_tooling" + ], + "0x80080204": [ + "background_tasks_printing_tooling" + ], + "0xC00CE169": [ + "background_tasks_printing_tooling" + ], + "E_FAIL": [ + "background_tasks_printing_tooling", + "file_access_storage_pickers" + ], + "E_NOINTERFACE": [ + "background_tasks_printing_tooling" + ], + "0x80070005": [ + "deployment_wasdk18_windows10" + ], + "0x8007007A": [ + "external_interop_issues" + ], + "E_FILTER_HEAD": [ + "external_interop_issues" + ], + "0x80070490": [ + "msix_selfcontained_packaging_conflicts", + "notifications_push_and_listener" + ] + }, + "byKeyword": { + "AppWindow": [ + "known_issue_api_docs_storagefile" + ], + "GetCurrentPlacement": [ + "known_issue_api_docs_storagefile" + ], + "SaveCurrentPlacement": [ + "known_issue_api_docs_storagefile" + ], + "PlacementRestorationBehavior": [ + "known_issue_api_docs_storagefile" + ], + "PlacementInfo": [ + "known_issue_api_docs_storagefile" + ], + "DisplayArea": [ + "known_issue_api_docs_storagefile" + ], + "GetMetricsFromWindowId": [ + "known_issue_api_docs_storagefile" + ], + "PersistedStateId": [ + "known_issue_api_docs_storagefile" + ], + "experimental API": [ + "known_issue_api_docs_storagefile" + ], + "StorageFile": [ + "known_issue_api_docs_storagefile" + ], + "shortcut": [ + "known_issue_api_docs_storagefile" + ], + ".lnk": [ + "known_issue_api_docs_storagefile" + ], + ".url": [ + "known_issue_api_docs_storagefile" + ], + ".wsh": [ + "known_issue_api_docs_storagefile" + ], + "file handler": [ + "known_issue_api_docs_storagefile", + "api_gaps_unpackaged_support" + ], + "PrimaryLanguageOverride": [ + "known_issue_api_gaps_localization", + "resources_mrt_localization" + ], + "null": [ + "known_issue_api_gaps_localization" + ], + "empty": [ + "known_issue_api_gaps_localization" + ], + "not persisted": [ + "known_issue_api_gaps_localization" + ], + "localization": [ + "known_issue_api_gaps_localization", + "resources_mrt_localization" + ], + "Microsoft.Windows.Globalization": [ + "known_issue_api_gaps_localization" + ], + "MovePackageToVolumeAsync": [ + "known_issue_api_gaps_localization" + ], + "PackageDeploymentManager": [ + "known_issue_api_gaps_localization" + ], + "WASDK 2.0": [ + "known_issue_api_gaps_localization" + ], + "Microsoft.Windows.SDK.BuildTools.MSIX": [ + "known_issue_msix_buildtools_defects", + "msix_project_configuration_tooling" + ], + "AppxSymbolPackageEnabled": [ + "known_issue_msix_buildtools_defects" + ], + "_GenerateAppxSymbolPackage": [ + "known_issue_msix_buildtools_defects" + ], + "mspdbcmf.exe": [ + "known_issue_msix_buildtools_defects", + "msix_build_publish_output_failures", + "msix_project_configuration_tooling" + ], + "msixbundle": [ + "known_issue_msix_buildtools_defects", + "msix_build_publish_output_failures" + ], + "Dependencies folder": [ + "known_issue_msix_buildtools_defects" + ], + "Publish error": [ + "known_issue_msix_buildtools_defects" + ], + "wapproj": [ + "known_issue_msix_buildtools_defects", + "msix_project_configuration_tooling" + ], + "documentation": [ + "known_issue_msix_buildtools_defects" + ], + "roadmap": [ + "known_issue_msix_buildtools_defects" + ], + "Microsoft.WindowsAppSDK.Foundation": [ + "known_issue_msix_nuget_license" + ], + "bootstrap DLL": [ + "known_issue_msix_nuget_license" + ], + "NuGet license": [ + "known_issue_msix_nuget_license" + ], + "redistribution": [ + "known_issue_msix_nuget_license" + ], + "Microsoft.WindowsAppSDK": [ + "known_issue_msix_nuget_license" + ], + "license terms": [ + "known_issue_msix_nuget_license" + ], + "WinRT": [ + "known_issue_performance_crashes", + "runtime_winrt_interop" + ], + "ApplicationData": [ + "known_issue_performance_crashes", + "api_gaps_unpackaged_support" + ], + "Package.Current": [ + "known_issue_performance_crashes" + ], + "performance": [ + "known_issue_performance_crashes" + ], + "latency": [ + "known_issue_performance_crashes" + ], + "25ms": [ + "known_issue_performance_crashes" + ], + "admin mode": [ + "known_issue_performance_crashes" + ], + "elevated": [ + "known_issue_performance_crashes" + ], + "packaged app crash": [ + "known_issue_performance_crashes" + ], + "Windows 10": [ + "known_issue_performance_crashes", + "deployment_wasdk18_windows10" + ], + "0xc000027b": [ + "known_issue_performance_crashes" + ], + "widget settings": [ + "known_issue_widget_platform_defects" + ], + "close button": [ + "known_issue_widget_platform_defects" + ], + "reload": [ + "known_issue_widget_platform_defects" + ], + "widget board": [ + "known_issue_widget_platform_defects", + "widgets_customization_display" + ], + "widget not appearing": [ + "known_issue_widget_platform_defects" + ], + "reinstall": [ + "known_issue_widget_platform_defects", + "known_issues_external_notifications" + ], + "customize widget": [ + "known_issue_widget_platform_defects" + ], + "Windows Widgets": [ + "known_issue_widget_platform_defects" + ], + "WidgetProviders": [ + "known_issue_widget_platform_defects" + ], + "MSIX": [ + "known_issues_external_notifications", + "appcontainer_identity_sharing" + ], + "uninstall": [ + "known_issues_external_notifications" + ], + "data retention": [ + "known_issues_external_notifications" + ], + "app data": [ + "known_issues_external_notifications" + ], + "keep data": [ + "known_issues_external_notifications" + ], + "game data": [ + "known_issues_external_notifications" + ], + "SettingsIdentifier": [ + "known_issues_file_access_pickers" + ], + "FileOpenPicker": [ + "known_issues_file_access_pickers", + "file_access_storage_pickers" + ], + "FileSavePicker": [ + "known_issues_file_access_pickers", + "file_access_storage_pickers" + ], + "FolderPicker": [ + "known_issues_file_access_pickers", + "file_access_storage_pickers" + ], + "last used location": [ + "known_issues_file_access_pickers" + ], + "Microsoft.Windows.Storage.Pickers": [ + "known_issues_file_access_pickers" + ], + "unpackaged": [ + "api_gaps_unpackaged_support", + "deployment_singlefile_installer", + "msix_project_configuration_tooling", + "notifications_push_and_listener", + "resources_mrt_localization" + ], + "AppInfo": [ + "api_gaps_unpackaged_support" + ], + "package identity": [ + "api_gaps_unpackaged_support" + ], + "StorageFolder": [ + "api_gaps_unpackaged_support" + ], + "PackageVolume": [ + "api_gaps_unpackaged_support" + ], + "FindPackage": [ + "api_gaps_unpackaged_support" + ], + "content type": [ + "api_gaps_unpackaged_support" + ], + "file association": [ + "api_gaps_unpackaged_support" + ], + "manifest": [ + "api_gaps_unpackaged_support" + ], + "LOCALAPPDATA": [ + "api_gaps_unpackaged_support" + ], + "AppContainer": [ + "appcontainer_identity_sharing" + ], + "Win32": [ + "appcontainer_identity_sharing" + ], + "PartialTrustApplication": [ + "appcontainer_identity_sharing" + ], + "partial trust": [ + "appcontainer_identity_sharing" + ], + "sandboxing": [ + "appcontainer_identity_sharing" + ], + "named objects": [ + "appcontainer_identity_sharing" + ], + "security descriptor": [ + "appcontainer_identity_sharing" + ], + "PackageFamilyName": [ + "appcontainer_identity_sharing" + ], + "PFN": [ + "appcontainer_identity_sharing" + ], + "Shell_NotifyIcon": [ + "appcontainer_identity_sharing" + ], + "tray icon": [ + "appcontainer_identity_sharing" + ], + "runFullTrust": [ + "appcontainer_identity_sharing" + ], + "permissiveLearningMode": [ + "appcontainer_identity_sharing" + ], + "UniversalBGTask": [ + "background_tasks_printing_tooling" + ], + "STOWED_EXCEPTION": [ + "background_tasks_printing_tooling" + ], + "background task": [ + "background_tasks_printing_tooling" + ], + "crash": [ + "background_tasks_printing_tooling" + ], + "0x80004005": [ + "background_tasks_printing_tooling" + ], + "0x80004002": [ + "background_tasks_printing_tooling" + ], + "0x800706ba": [ + "background_tasks_printing_tooling" + ], + "0x80080204": [ + "background_tasks_printing_tooling" + ], + "0xC00CE169": [ + "background_tasks_printing_tooling" + ], + "ACCESS_VIOLATION": [ + "background_tasks_printing_tooling" + ], + "PrintPreview": [ + "background_tasks_printing_tooling" + ], + "dark theme": [ + "background_tasks_printing_tooling" + ], + "RequestedTheme": [ + "background_tasks_printing_tooling" + ], + "empty preview": [ + "background_tasks_printing_tooling" + ], + "Visual Studio 2022": [ + "background_tasks_printing_tooling" + ], + "add page": [ + "background_tasks_printing_tooling" + ], + "new item": [ + "background_tasks_printing_tooling" + ], + "XamlParseException": [ + "deployment_singlefile_installer", + "msix_selfcontained_packaging_conflicts" + ], + "XAML parsing failed": [ + "deployment_singlefile_installer" + ], + "single-file": [ + "deployment_singlefile_installer" + ], + "rename executable": [ + "deployment_singlefile_installer" + ], + "PublishSingleFile": [ + "deployment_singlefile_installer" + ], + "runtime links broken": [ + "deployment_singlefile_installer" + ], + "2.0 preview": [ + "deployment_singlefile_installer" + ], + "installer binaries": [ + "deployment_singlefile_installer" + ], + "MRM.dll crash": [ + "deployment_singlefile_installer" + ], + "FindPackagesByPackageFamily": [ + "deployment_wasdk18_windows10", + "external_interop_issues" + ], + "WASDK 1.8": [ + "deployment_wasdk18_windows10" + ], + "17763": [ + "deployment_wasdk18_windows10" + ], + "19041": [ + "deployment_wasdk18_windows10" + ], + "DeploymentManager": [ + "deployment_wasdk18_windows10" + ], + "crash on launch": [ + "deployment_wasdk18_windows10" + ], + "0x80070005": [ + "deployment_wasdk18_windows10" + ], + "DDLM PackageFullName": [ + "deployment_wasdk18_windows10" + ], + "MSIX.inventory": [ + "deployment_wasdk18_windows10" + ], + "packaging project": [ + "external_interop_issues" + ], + "NuGet": [ + "external_interop_issues", + "msix_project_configuration_tooling" + ], + "stale assembly": [ + "external_interop_issues" + ], + "MSIX bundle": [ + "external_interop_issues" + ], + "0x8007007A": [ + "external_interop_issues" + ], + "ERROR_INSUFFICIENT_BUFFER": [ + "external_interop_issues" + ], + "DeviceInformationPairing": [ + "external_interop_issues" + ], + "Bluetooth": [ + "external_interop_issues" + ], + "ProximityDevice": [ + "external_interop_issues" + ], + "NFC": [ + "external_interop_issues" + ], + "Widgets": [ + "external_interop_issues" + ], + "WinUI 3": [ + "external_interop_issues" + ], + "storage pickers": [ + "file_access_storage_pickers" + ], + "file picker crash": [ + "file_access_storage_pickers" + ], + "COMException": [ + "file_access_storage_pickers", + "msix_selfcontained_packaging_conflicts", + "notifications_push_and_listener", + "resources_mrt_localization" + ], + "E_FAIL": [ + "file_access_storage_pickers" + ], + "IInitializeWithWindow": [ + "file_access_storage_pickers" + ], + "DefaultFileExtension": [ + "file_access_storage_pickers" + ], + "FileTypeChoices": [ + "file_access_storage_pickers" + ], + "WSL": [ + "file_access_storage_pickers" + ], + "RTL": [ + "file_access_storage_pickers" + ], + "language override": [ + "file_access_storage_pickers" + ], + "msixupload": [ + "msix_build_publish_output_failures" + ], + "appxsym": [ + "msix_build_publish_output_failures" + ], + "WinAppSdkSignAppxPackageBundle": [ + "msix_build_publish_output_failures" + ], + "MSB4036": [ + "msix_build_publish_output_failures" + ], + "MSB6006": [ + "msix_build_publish_output_failures" + ], + "CMF1106": [ + "msix_build_publish_output_failures" + ], + "UapAppxPackageBuildMode": [ + "msix_build_publish_output_failures" + ], + "StoreUpload": [ + "msix_build_publish_output_failures" + ], + "StoreAndSideload": [ + "msix_build_publish_output_failures" + ], + "EnableMsixTooling": [ + "msix_project_configuration_tooling", + "msix_selfcontained_packaging_conflicts" + ], + "AppxOSMinVersionReplaceManifestVersion": [ + "msix_project_configuration_tooling" + ], + "AppxOSMaxVersionTestedReplaceManifestVersion": [ + "msix_project_configuration_tooling" + ], + "single-project MSIX": [ + "msix_project_configuration_tooling" + ], + "Visual Studio": [ + "msix_project_configuration_tooling" + ], + "resources.pri": [ + "msix_project_configuration_tooling", + "msix_selfcontained_packaging_conflicts" + ], + "WindowsAppSDKSelfContained": [ + "msix_selfcontained_packaging_conflicts" + ], + "0x80070490": [ + "msix_selfcontained_packaging_conflicts", + "notifications_push_and_listener" + ], + "PRI": [ + "msix_selfcontained_packaging_conflicts" + ], + "_OverrideGetPriIndexName": [ + "msix_selfcontained_packaging_conflicts" + ], + "WMC1012": [ + "msix_selfcontained_packaging_conflicts" + ], + "ApplicationXaml": [ + "msix_selfcontained_packaging_conflicts" + ], + "codegen": [ + "msix_selfcontained_packaging_conflicts" + ], + "library project": [ + "msix_selfcontained_packaging_conflicts" + ], + "AppNotification": [ + "notifications_push_and_listener" + ], + "push notification": [ + "notifications_push_and_listener" + ], + "Element not found": [ + "notifications_push_and_listener" + ], + "UserNotificationListener": [ + "notifications_push_and_listener" + ], + "NotificationChanged": [ + "notifications_push_and_listener" + ], + "AppNotificationProgressData": [ + "notifications_push_and_listener" + ], + "IsIndeterminate": [ + "notifications_push_and_listener" + ], + "indeterminate progress bar": [ + "notifications_push_and_listener" + ], + "toast notification": [ + "notifications_push_and_listener" + ], + "ResourceLoader": [ + "resources_mrt_localization" + ], + "GetString": [ + "resources_mrt_localization" + ], + "NamedResource Not Found": [ + "resources_mrt_localization" + ], + "x:Uid": [ + "resources_mrt_localization" + ], + "MRTCore": [ + "resources_mrt_localization" + ], + "Resources.resw": [ + "resources_mrt_localization" + ], + "dot in key": [ + "resources_mrt_localization" + ], + "signing projection": [ + "resources_mrt_localization" + ], + "AOT": [ + "runtime_winrt_interop" + ], + "trimming": [ + "runtime_winrt_interop" + ], + "FrameworkElement": [ + "runtime_winrt_interop" + ], + "theme": [ + "runtime_winrt_interop" + ], + "LaunchActivatedEventArgs": [ + "runtime_winrt_interop" + ], + "CsWinRT": [ + "runtime_winrt_interop" + ], + "IInspectable": [ + "runtime_winrt_interop" + ], + "ReleaseInfo": [ + "runtime_winrt_interop" + ], + "version string": [ + "runtime_winrt_interop" + ], + "HDR": [ + "runtime_winrt_interop" + ], + "CompositionDrawingSurface": [ + "runtime_winrt_interop" + ], + "scRGB": [ + "runtime_winrt_interop" + ], + "swap chain": [ + "runtime_winrt_interop" + ], + "DirectXPixelFormat": [ + "runtime_winrt_interop" + ], + "widget customization": [ + "widgets_customization_display" + ], + "template JSON": [ + "widgets_customization_display" + ], + "OnCustomizationRequested": [ + "widgets_customization_display" + ], + "add widget": [ + "widgets_customization_display" + ], + "widget list": [ + "widgets_customization_display" + ], + "Widgets panel": [ + "widgets_customization_display" + ] + }, + "byArea": { + "Storage": [ + "known_issue_api_docs_storagefile", + "known_issues_file_access_pickers", + "file_access_storage_pickers" + ], + "Runtime": [ + "known_issue_api_gaps_localization", + "known_issue_performance_crashes", + "known_issues_external_notifications", + "appcontainer_identity_sharing", + "background_tasks_printing_tooling", + "external_interop_issues", + "notifications_push_and_listener", + "resources_mrt_localization", + "runtime_winrt_interop" + ], + "Deployment": [ + "known_issue_msix_buildtools_defects", + "known_issue_msix_nuget_license", + "deployment_singlefile_installer", + "deployment_wasdk18_windows10", + "msix_build_publish_output_failures", + "msix_project_configuration_tooling", + "msix_selfcontained_packaging_conflicts" + ], + "Widgets": [ + "known_issue_widget_platform_defects", + "widgets_customization_display" + ], + "WinML": [ + "api_gaps_unpackaged_support" + ] + } + } +} \ No newline at end of file diff --git a/tsg/tsg_api_gaps_unpackaged_support.md b/tsg/tsg_api_gaps_unpackaged_support.md new file mode 100644 index 0000000..77d371e --- /dev/null +++ b/tsg/tsg_api_gaps_unpackaged_support.md @@ -0,0 +1,202 @@ +# API Gaps: Unpackaged App Support, Storage & Package Management - Windows App SDK + +**Keywords:** ApplicationData, unpackaged, AppInfo, package identity, StorageFolder, PackageVolume, FindPackage, content type, file handler, file association, manifest, LOCALAPPDATA + +**Error Example:** +``` +// ApplicationData.Current fails for unpackaged apps +Windows.Storage.ApplicationData.Current → throws (no package identity) + +// AppInfo unavailable for unpackaged +Windows.ApplicationModel.AppInfo → only works for packaged apps + +// PackageVolume missing APIs +PackageVolume.FindPackages() → method not available in WASDK PackageVolume + +// File handler declaration limitation +Can only declare file type extensions in manifest, not MIME content types +``` + +--- + +## Quick Match + +**You're seeing this if:** +- `ApplicationData.Current` fails in an unpackaged (non-MSIX) app +- Need app metadata (display name, icon, etc.) in an unpackaged app +- WASDK `PackageVolume` is missing `FindPackage`-related APIs available in the platform type +- Want to register as a default file handler by MIME content type instead of individual file extensions + +→ Check scenarios below for your specific cause + +--- + +## Related Issues + +- [#2639](https://github.com/microsoft/WindowsAppSDK/issues/2639) - Microsoft.Storage.ApplicationData proposal (Status: Open, In PR, area-ApplicationData) +- [#1083](https://github.com/microsoft/WindowsAppSDK/issues/1083) - AppInfo class for unpackaged apps (Status: Closed, feature proposal) +- [#27](https://github.com/microsoft/WindowsAppSDK/issues/27) - Specifying as default file handler with content type instead of filetype (Status: Open, area-Activation, feature proposal) +- [#6222](https://github.com/microsoft/WindowsAppSDK/issues/6222) - WASDK PackageVolume missing APIs related to FindPackageXXX (Status: Open, area-PackageManagement) + +--- + +## Scenarios & Solutions + +### Scenario 1: ApplicationData Not Available for Unpackaged Apps + +**Cause:** `Windows.Storage.ApplicationData.Current` requires both package identity AND running in AppContainer. `Windows.Management.Core.ApplicationDataManager.CreateForPackageFamily` requires package identity AND MediumIL or higher. Unpackaged apps have no access to the ApplicationData API and must manually manage `%LOCALAPPDATA%` paths. Additionally, the existing API has performance overhead (requiring `StorageFolder` with no direct `.Path` access), deprecated features (e.g., `RoamingFolder`), and no synchronous alternatives to async methods. +> Source: Issue author in [#2639](https://github.com/microsoft/WindowsAppSDK/issues/2639) + +**Current workaround for unpackaged apps:** +1. Use standard filesystem paths directly instead of `ApplicationData`: +```csharp +// Equivalent to ApplicationData.LocalFolder for unpackaged apps +string localAppData = Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData); +string appDataPath = Path.Combine(localAppData, "YourPublisher", "YourProduct"); +Directory.CreateDirectory(appDataPath); + +// Equivalent to ApplicationData.TemporaryFolder +string tempPath = Path.Combine(localAppData, "Temp"); + +// Equivalent to ApplicationData.LocalSettings (use registry) +// HKCU\SOFTWARE\YourPublisher\YourProduct +using var key = Registry.CurrentUser.CreateSubKey(@"SOFTWARE\YourPublisher\YourProduct"); +key.SetValue("Setting1", "Value1"); +``` + +2. Reference mapping from the proposal (packaged → unpackaged equivalents): + +| Packaged API | Unpackaged Equivalent | +|---|---| +| `ApplicationData.LocalCacheFolder` | `%LOCALAPPDATA%\\` | +| `ApplicationData.LocalFolder` | `%LOCALAPPDATA%\\` | +| `ApplicationData.MachineFolder` | `%ProgramData%\\` | +| `ApplicationData.TemporaryFolder` | `%LOCALAPPDATA%\Temp` | +| `ApplicationData.LocalSettings` | `HKCU\SOFTWARE\\` | + +**Upcoming fix:** The `Microsoft.Storage.ApplicationData` API is being developed (Status: In PR) to provide a unified API for both packaged and unpackaged apps. The new API will: +- Support packaged and unpackaged applications with a single API surface +- Provide direct filesystem path access without `StorageFolder` overhead +- Offer synchronous equivalents to async methods (e.g., `Clear()` alongside `ClearAsync()`) +- Deprecate obsolete features like `RoamingFolder` +> Source: API proposal in [#2639](https://github.com/microsoft/WindowsAppSDK/issues/2639) + +**Verify:** Check for the `Microsoft.Storage.ApplicationData` namespace in future WinAppSDK releases. + +--- + +### Scenario 2: AppInfo Unavailable for Unpackaged Apps + +**Cause:** The [Windows.ApplicationModel.AppInfo](https://docs.microsoft.com/en-us/uwp/api/Windows.ApplicationModel.AppInfo) class only works for packaged apps because it reads information from the app package manifest. Unpackaged apps have no manifest and therefore cannot use this API to get app metadata (display name, description, logo, etc.). +> Source: Issue author in [#1083](https://github.com/microsoft/WindowsAppSDK/issues/1083) + +**Workaround:** +1. For unpackaged apps, read app information from the executable's file version info: +```csharp +using System.Diagnostics; + +var exePath = Environment.ProcessPath; +var versionInfo = FileVersionInfo.GetVersionInfo(exePath); + +string appName = versionInfo.ProductName ?? "Unknown"; +string appVersion = versionInfo.ProductVersion ?? "0.0.0"; +string company = versionInfo.CompanyName ?? "Unknown"; +string description = versionInfo.FileDescription ?? ""; +``` +2. For icon retrieval in unpackaged apps, use Win32 APIs: +```csharp +[DllImport("shell32.dll", CharSet = CharSet.Auto)] +static extern IntPtr ExtractIcon(IntPtr hInst, string lpszExeFileName, int nIconIndex); +``` +3. The feature proposal requests that WinAppSDK update `AppInfo` to pull from file details for unpackaged apps instead of requiring a manifest + +**Status:** Closed — the feature request was acknowledged but the specific implementation status is unclear. Use the Win32/BCL workarounds above. + +--- + +### Scenario 3: Cannot Declare Default File Handler by Content Type + +**Cause:** The current app manifest system only supports declaring file type associations by specific file extensions (e.g., `.txt`, `.md`, `.json`). There is no way to declare an app as a handler for a MIME content type (e.g., `text/*`), which would automatically cover all file extensions of that type. This forces developers of text editors, media players, and similar broad-format apps to exhaustively list every possible file extension. +> Source: Issue author in [#27](https://github.com/microsoft/WindowsAppSDK/issues/27) + +**Impact:** +- Text editor apps cannot easily become the default handler for all text files +- Declaring every possible file extension is impractical and incomplete +- `StorageFile` operations like renaming fail for undeclared file types +- `StorageFile.GetFileAsync()` fails for unsupported file types +- `Launcher.LaunchFileAsync()` fails if the target file type is undeclared +- Users cannot choose a UWP/WinUI app as default handler for undeclared file types (unlike Win32 apps) + +**Workaround:** +1. Declare as many file extensions as practical in your app manifest: +```xml + + + + .txt + .md + .log + .csv + + + + +``` +2. For unpackaged Win32 apps, use the traditional registry-based file association which has no such limitation +3. Consider using a desktop extension / full-trust component for broader file handling capability + +**Status:** Open — this is a long-standing feature proposal (filed May 2020). No confirmed timeline for content-type-based file handler declaration. + +--- + +### Scenario 4: WASDK PackageVolume Missing FindPackage APIs + +**Cause:** The WASDK `PackageVolume` type is missing APIs related to `FindPackageXXX` methods that are available on the platform's `Windows.Management.Deployment.PackageVolume` type. This means developers using WASDK's package management APIs cannot enumerate or search for packages on a volume. +> Source: Issue author in [#6222](https://github.com/microsoft/WindowsAppSDK/issues/6222) + +**Workaround:** +1. Use the platform `Windows.Management.Deployment.PackageVolume` APIs directly instead of the WASDK equivalent: +```csharp +using Windows.Management.Deployment; + +var packageManager = new PackageManager(); +var volumes = packageManager.FindPackageVolumes(); +foreach (var volume in volumes) +{ + // Platform API has FindPackages methods + var packages = volume.FindPackages(); + // Process packages... +} +``` +2. This bypasses the WASDK abstraction but provides the needed functionality + +**Status:** Open — filed against WinAppSDK 2.0 Experimental 4 (2.0.0-experimental4). The WASDK team may add these APIs in a future release. + +**Environment:** +- WinAppSDK 2.0 Experimental 4 (2.0.0-experimental4) +- Packaged (MSIX) +- Windows 11 24H2 LTSC (26100) + +--- + +## ⚠️ Unverified / Community Suggestions + +> The following are community suggestions that have NOT been officially confirmed. + +- For ApplicationData (#2639): Some developers use a custom `ApplicationData`-like wrapper class that detects packaging state and routes to either the platform API or filesystem paths automatically (community pattern, not officially recommended) +- For file handler content type (#27): Using a Win32 desktop extension bridge to handle file associations for UWP/WinUI apps may provide broader file type coverage (from community discussion in #27) + +--- + +## References + +- [Windows.Storage.ApplicationData - UWP API](https://docs.microsoft.com/uwp/api/windows.storage.applicationdata) +- [Windows.ApplicationModel.AppInfo - UWP API](https://docs.microsoft.com/en-us/uwp/api/Windows.ApplicationModel.AppInfo) +- [File Type Associations - MSIX](https://learn.microsoft.com/en-us/windows/apps/desktop/modernize/desktop-to-uwp-extensions#file-type-associations) +- [PackageVolume - Windows.Management.Deployment](https://learn.microsoft.com/en-us/uwp/api/windows.management.deployment.packagevolume) +- [#2639 Proposal - Microsoft.Storage.ApplicationData](https://github.com/microsoft/WindowsAppSDK/issues/2639) + +--- + +**Updated:** 2025-07-17 | **Confidence:** 0.7 +**Sources:** #2639, #1083, #27, #6222, UWP/WinAppSDK API documentation diff --git a/tsg/tsg_appcontainer_identity_sharing.md b/tsg/tsg_appcontainer_identity_sharing.md new file mode 100644 index 0000000..9baea60 --- /dev/null +++ b/tsg/tsg_appcontainer_identity_sharing.md @@ -0,0 +1,153 @@ +# AppContainer for Win32 Apps & Named Object Sharing Between Packaged/Win32 + +**Keywords:** AppContainer, Win32, PartialTrustApplication, partial trust, sandboxing, named objects, security descriptor, PackageFamilyName, PFN, Shell_NotifyIcon, tray icon, MSIX, runFullTrust, permissiveLearningMode + +--- + +## Quick Match + +**You're seeing this if:** +- You want to run a Win32/WinUI 3 MSIX app in an AppContainer sandbox +- `Shell_NotifyIcon` returns access denied in AppContainer +- You need to share named objects (mutexes, events) between packaged and Win32 apps +- You're trying to configure `PartialTrustApplication` in a `.wapproj` packaging project + +→ Check scenarios below for your specific situation + +--- + +## Related Issues + +- [#219](https://github.com/microsoft/WindowsAppSDK/issues/219) — AppContainer for Win32 apps (Status: Closed — Not Planned, 62 comments) +- [#175](https://github.com/microsoft/WindowsAppSDK/issues/175) — Easing named object sharing between packaged and Win32 (Status: Closed/Fixed) + +--- + +## Scenarios & Solutions + +### Scenario 1: Running a Win32 MSIX App in AppContainer (Partial Trust) + +**Background:** Win32 apps can be launched in an AppContainer by using `EntryPoint="Windows.PartialTrustApplication"` in the MSIX app manifest. This provides Low IL sandboxing similar to UWP apps, but the feature is largely undocumented and has limitations. +> Source: @sylveon (CONTRIBUTOR) in [#219](https://github.com/microsoft/WindowsAppSDK/issues/219) + +**Current status:** Issue #219 was **closed as Not Planned**. Microsoft has not committed to officially supporting AppContainer for Win32 apps through Windows App SDK. +> Source: Issue closed without explanation; @riverar (CONTRIBUTOR) noted: "Always fun when Microsoft employees close issues without saying a word." + +**How to configure partial trust (C# projects / .wapproj):** + +1. Remove `runFullTrust` capability from `Package.appxmanifest`: + ```xml + + + ``` + +2. Set `TrustLevel` on the project reference in the `.wapproj`: + ```xml + + Partial + + ``` + > ✅ Confirmed by: @sbanni in [#219](https://github.com/microsoft/WindowsAppSDK/issues/219) — generates correct appxmanifest with `PartialTrustApplication` entry point + +**How to configure partial trust (C++ projects / .wapproj):** + +The Visual Studio properties panel does not expose the `Trust Level` dropdown for `.vcxproj` references. Manually add `Partial` to the `` in the `.wapproj` file. Ignore the green squiggles — it builds correctly. +> ✅ Confirmed by: @torarnv and @sbanni in [#219](https://github.com/microsoft/WindowsAppSDK/issues/219) + +**Minimum platform version required:** +You may need to bump `TargetPlatformMinVersion` — the old platform versions may reject the partial trust entry point. +> Source: @torarnv in [#219](https://github.com/microsoft/WindowsAppSDK/issues/219) + +--- + +### Scenario 2: Shell_NotifyIcon (Tray Icons) Fail in AppContainer + +**Cause:** `Shell_NotifyIcon` sends messages to the Windows shell, which runs at a higher integrity level. The AppContainer sandbox blocks this cross-IL communication, returning access denied for all calls. +> Source: @ptorr-msft (CONTRIBUTOR) in [#219](https://github.com/microsoft/WindowsAppSDK/issues/219) + +**Fix:** No fix available. `Shell_NotifyIcon` does not work from AppContainer by design. + +**Workaround architecture:** Run GUI/logic in a low-IL partial trust process and broker privileged operations (tray icons, etc.) through a separate medium-IL full trust helper process declared in your package manifest. +> Source: @sylveon (CONTRIBUTOR) and @ptorr-msft (CONTRIBUTOR) in [#219](https://github.com/microsoft/WindowsAppSDK/issues/219) + +``` +┌─────────────────────────────┐ ┌──────────────────────────┐ +│ Main App (Low IL/AppContainer) │──→│ Helper (Medium IL/Full Trust) │ +│ - UI, business logic │ │ - Shell_NotifyIcon │ +│ - WinUI 3 / XAML │ │ - Other privileged APIs │ +└─────────────────────────────┘ └──────────────────────────┘ +``` + +--- + +### Scenario 3: .NET Apps Have High CPU in AppContainer + +**Cause:** Running .NET Core / .NET Framework Win32 apps in AppContainer causes ~20% CPU usage even for a "Hello World" app. This does not reproduce with C++ apps. +> Source: @Felix-Dev in [#219](https://github.com/microsoft/WindowsAppSDK/issues/219) + +**Explanation:** Some .NET API calls are denied by the sandbox, and the runtime may continuously retry them. +> Source: @sylveon (CONTRIBUTOR) in [#219](https://github.com/microsoft/WindowsAppSDK/issues/219) + +**Fix:** No fix available. This is a .NET runtime behavior when sandboxed. + +--- + +### Scenario 4: Debugging AppContainer with Permissive Learning Mode (Windows 11) + +**Background:** Windows 11 introduced `permissiveLearningMode` capability for AppContainer tokens. When enabled, access checks that would normally be denied are instead allowed but logged via ETW tracing. This helps identify which capabilities your app needs. +> Source: @WildByDesign in [#219](https://github.com/microsoft/WindowsAppSDK/issues/219), referencing [Tyranid's blog](https://www.tiraniddo.dev/2021/09/lowbox-token-permissive-learning-mode.html) + +**Usage:** +1. Add `permissiveLearningMode` capability to your AppContainer token. +2. Run the app — all sandbox-denied operations are logged but allowed. +3. Collect ETW traces to identify failed access checks. +4. Tools: [SilkETW](https://github.com/fireeye/SilkETW) can log permissive learning mode events to JSON. + +> ⚠️ @WildByDesign confirmed that with `permissiveLearningMode`, the app has "full access to the file system, network, registry, etc." — so this effectively disables the sandbox for debugging purposes only. + +--- + +### Scenario 5: Sharing Named Objects Between Packaged and Win32 Apps + +**Cause:** Named objects (mutexes, events, waitable timers) must be ACL'd with proper security descriptors to be shared between packaged apps (running in AppContainers) and regular Win32 processes. The required code is [complex and error-prone](https://docs.microsoft.com/en-us/windows/win32/api/securityappcontainer/nf-securityappcontainer-getappcontainernamedobjectpath#examples). +> Source: @DefaultRyan (MEMBER) in [#175](https://github.com/microsoft/WindowsAppSDK/issues/175) + +**Fix:** This was implemented in Windows App SDK via [PR #2005](https://github.com/microsoft/WindowsAppSDK/pull/2005). +> ✅ Confirmed by: @alexlamtest (CONTRIBUTOR) in [#175](https://github.com/microsoft/WindowsAppSDK/issues/175) + +**API:** Use the WinAppSDK security descriptor helper that takes Package Family Names and an access mask: +```c +// Simplified API — replaces boilerplate security descriptor code +GetSecurityDescriptorForPackageFamilyNames( + cCountOfPackageFamilyNames, + pListOfPackageFamilyNames, + accessMask, + &ppSD +); +``` + +**For C# consumers:** Use P/Invoke to call the C API, or use .NET's built-in security descriptor model. +> Source: @DefaultRyan (MEMBER) and @smaillet-ms in [#175](https://github.com/microsoft/WindowsAppSDK/issues/175) + +--- + +## ⚠️ Unverified / Community Suggestions + +> The following are community suggestions that have NOT been officially confirmed. + +- The [Win32 App Isolation](https://github.com/nicktarr/win32-app-isolation) project may provide an alternative path forward for sandboxing, but has had no releases in over two years (from @AkazaRenn in #219) +- PasswordVault isolation requires AppContainer — no alternative exists for non-AppContainer Win32 apps (from @AkazaRenn in #219) + +--- + +## References + +- [Named object sharing guidance](https://docs.microsoft.com/en-us/windows/uwp/communication/sharing-named-objects) +- [Trust/AppContainers guide by @nickrandolph](https://nicksnettravels.builttoroam.com/trust-appcontainers/) +- [Permissive Learning Mode blog](https://www.tiraniddo.dev/2021/09/lowbox-token-permissive-learning-mode.html) +- [WinAppSDK PR #2005 — Named object sharing API](https://github.com/microsoft/WindowsAppSDK/pull/2005) + +--- + +**Updated:** 2026-03-13 | **Confidence:** 0.7 +**Sources:** #219, #175 diff --git a/tsg/tsg_background_tasks_printing_tooling.md b/tsg/tsg_background_tasks_printing_tooling.md new file mode 100644 index 0000000..5ba9c58 --- /dev/null +++ b/tsg/tsg_background_tasks_printing_tooling.md @@ -0,0 +1,233 @@ +# Background Task Crashes, Print Preview Dark Theme & VS Tooling - Windows App SDK + +**Keywords:** UniversalBGTask, STOWED_EXCEPTION, background task, crash, 0x80004005, 0x80004002, 0x800706ba, 0x80080204, 0xC00CE169, ACCESS_VIOLATION, PrintPreview, dark theme, RequestedTheme, empty preview, Visual Studio 2022, add page, new item + +**Error Example:** +``` +STOWED_EXCEPTION_80004005_Microsoft.Windows.ApplicationModel.Background.UniversalBGTask.dll +STOWED_EXCEPTION_80004002_Microsoft.Windows.ApplicationModel.Background.UniversalBGTask.dll +STOWED_EXCEPTION_800706ba_Microsoft.Windows.ApplicationModel.Background.UniversalBGTask.dll + +// Print preview +PrintPreview window shows blank/empty content when RequestedTheme = Dark + +// VS 2022 tooling +No option to add a new Page in VS 2022 Preview 3 with WinAppSDK 0.8 +``` + +--- + +## Quick Match + +**You're seeing this if:** +- Background task crashes with `STOWED_EXCEPTION` in `UniversalBGTask.dll` +- Partner Center shows thousands of daily crashes from background task execution +- Print preview window displays empty/blank content with dark theme +- Cannot add new WinUI Page items in Visual Studio 2022 + +→ Check scenarios below for your specific cause + +--- + +## Related Issues + +- [#5870](https://github.com/microsoft/WindowsAppSDK/issues/5870) - UniversalBGTask crashes with STOWED_EXCEPTION (Status: Open, area-BackgroundTask, 36 comments) +- [#6086](https://github.com/microsoft/WindowsAppSDK/issues/6086) - PrintPreview displays empty value when RequestedTheme is dark (Status: Open) +- [#1236](https://github.com/microsoft/WindowsAppSDK/issues/1236) - Unable to Create new Pages in VS 2022 Preview 3 (Status: Closed) + +--- + +## Scenarios & Solutions + +### Scenario 1: UniversalBGTask Crashes with STOWED_EXCEPTION (High Volume) + +**Cause:** Background tasks implemented using the WinAppSDK `UniversalBGTask` infrastructure crash with `STOWED_EXCEPTION` errors during `IBackgroundTask.Run`. The crashes occur in `Microsoft.Windows.ApplicationModel.Background.UniversalBGTask.dll` and affect Store-published apps at massive scale (10,000+ crashes per day reported). In WinAppSDK 1.7, similar crashes manifested as `ACCESS_VIOLATION` errors (discussed in [microsoft-ui-xaml#10769](https://github.com/microsoft/microsoft-ui-xaml/issues/10769)). After upgrading to WinAppSDK 1.8, the error code changed to `STOWED_EXCEPTION` but the crash volume remained similar. +> Source: Issue author in [#5870](https://github.com/microsoft/WindowsAppSDK/issues/5870) + +**Error codes observed:** +- `STOWED_EXCEPTION_80004005` (E_FAIL) — General failure during task execution +- `STOWED_EXCEPTION_80004002` (E_NOINTERFACE) — `hresult_no_interface` thrown, suggesting COM interface query failure +- `STOWED_EXCEPTION_800706ba` (RPC_S_SERVER_UNAVAILABLE) — RPC server unavailable during task run +- `0x80080204` and `0xC00CE169` — Additional error codes referenced in issue metadata + +**Common stack trace pattern:** +``` +UniversalBGTask.dll!winrt::hresult_error::originate +UniversalBGTask.dll!...::Task::Run +biwinrt.dll!CBackgroundTaskInstance::RunInternal +biwinrt.dll!CBackgroundTaskInstance::Run +twinapi.appcore.dll!BackgroundTaskWrapper::ThreadProc +``` + +**Key observations:** +- Crashes happen across multiple Windows versions: Windows 11 10.0.26100, 10.0.22631, Windows 10 10.0.19045 +- The crash count exceeds the "devices affected" count, indicating repeated crashes on the same machines +- Affects all apps published in the Microsoft Store that use background tasks +- Issue persisted across WinAppSDK 1.7 (ACCESS_VIOLATION) and 1.8 (STOWED_EXCEPTION) + +**Workaround (limited):** +1. Wrap your background task `Run` implementation in a comprehensive try-catch to prevent unhandled exceptions: +```csharp +public sealed class MyBackgroundTask : IBackgroundTask +{ + public void Run(IBackgroundTaskInstance taskInstance) + { + var deferral = taskInstance.GetDeferral(); + try + { + // Your task logic here + } + catch (Exception ex) + { + // Log the error - don't let it propagate + Debug.WriteLine($"Background task error: {ex.HResult:X} - {ex.Message}"); + } + finally + { + deferral.Complete(); + } + } +} +``` +2. Note: The `E_NOINTERFACE` (0x80004002) crash occurs inside `UniversalBGTask.dll` itself (not user code), suggesting a platform-level COM activation failure that cannot be caught by user exception handlers +3. The `RPC_S_SERVER_UNAVAILABLE` (0x800706ba) error suggests the background task host process may lose connection to the main application or a required system service +4. Monitor [#5870](https://github.com/microsoft/WindowsAppSDK/issues/5870) for updates — this is actively discussed with 36 comments + +**Status:** Open — no confirmed fix. This is a high-impact issue affecting Store-published apps. + +**Environment:** +- WinAppSDK 1.8.1 (1.8.250916003) +- Packaged (MSIX) +- Multiple Windows versions (10 and 11) + +--- + +### Scenario 2: Print Preview Shows Empty Content with Dark Theme + +**Cause:** When `RequestedTheme` is set to `ApplicationTheme.Dark` in a WinUI application, the print preview window displays blank/empty content. The same printing code works correctly when the theme is set to Light. The issue is that the print preview rendering inherits the dark theme, causing text (likely white/light colored) to be rendered on a white print preview background, making it invisible. +> Source: Issue author in [#6086](https://github.com/microsoft/WindowsAppSDK/issues/6086) + +**Steps to reproduce:** +1. Set `this.RequestedTheme = ApplicationTheme.Dark` in `App.xaml.cs` +2. Implement printing with `PrintDocument` +3. Create preview pages using `StackPanel` with `TextBlock` elements +4. Open print preview — text is invisible + +**Reproduction code pattern:** +```csharp +// In App.xaml.cs +public App() +{ + this.RequestedTheme = ApplicationTheme.Dark; // Causes issue + InitializeComponent(); +} + +// In printing handler +private void OnPaginate(object sender, PaginateEventArgs e) +{ + var page = new StackPanel { Margin = new Thickness(20) }; + page.Children.Add(new TextBlock + { + Text = "Hello, this is a print test!", + FontSize = 24 + }); + _printDoc.SetPreviewPage(1, page); +} +``` + +**Fix:** +1. Explicitly set the print preview page elements to use Light theme and dark text colors: +```csharp +private void OnPaginate(object sender, PaginateEventArgs e) +{ + var page = new StackPanel + { + Margin = new Thickness(20), + RequestedTheme = ElementTheme.Light, // Force light theme for print + Background = new SolidColorBrush(Colors.White) + }; + page.Children.Add(new TextBlock + { + Text = "Hello, this is a print test!", + FontSize = 24, + Foreground = new SolidColorBrush(Colors.Black) // Explicit dark text + }); + _printDoc.SetPreviewPage(1, page); +} +``` +2. Alternatively, set `RequestedTheme = ElementTheme.Light` on the root element of each print preview page to ensure print content is always rendered with light theme colors regardless of the app theme + +**Verify:** Open print preview with dark theme active — text should now be visible on the white preview background. + +**Status:** Open — no official fix from WinAppSDK team yet. + +--- + +### Scenario 3: Cannot Add New WinUI Pages in Visual Studio 2022 + +**Cause:** In Visual Studio 2022 Preview 3 with WinAppSDK 0.8, the "Add New Item" dialog did not include an option to add a new WinUI Page. The WinUI item templates were not properly registered in early VS 2022 previews. +> Source: Issue author in [#1236](https://github.com/microsoft/WindowsAppSDK/issues/1236) + +**Workaround (historical):** +1. Use Visual Studio 2019 to add the new page, then continue working in VS 2022 +2. Manually create the `.xaml` and `.xaml.cs` files following the WinUI page pattern: + +```xml + + + + + +``` + +```csharp +// NewPage.xaml.cs +namespace YourApp +{ + public sealed partial class NewPage : Page + { + public NewPage() + { + this.InitializeComponent(); + } + } +} +``` + +**Fix:** +1. **Update Visual Studio 2022** to a recent stable release — this issue was specific to early Preview 3 builds with WinAppSDK 0.8 +2. Ensure the **Windows App SDK** extension/workload is installed in VS 2022 +3. Modern versions of VS 2022 with WinAppSDK 1.x+ include proper WinUI item templates + +> ✅ Confirmed resolved: Issue is closed, indicating this was fixed in subsequent VS 2022 updates + +**Environment:** +- Visual Studio 2022 Preview 3 (historical) +- WinAppSDK 0.8 + +--- + +## ⚠️ Unverified / Community Suggestions + +> The following are community suggestions that have NOT been officially confirmed. + +- For background task crashes (#5870): Some developers report that reducing background task frequency or adding retry logic with exponential backoff reduces the visible crash rate, though the underlying platform issue remains (community reports in #5870) +- For background task crashes (#5870): Disabling background tasks entirely as a temporary measure while waiting for a fix may be appropriate if the crashes impact app store ratings (from community discussion) +- For print preview (#6086): Some developers report that creating the print preview content in a separate `Frame` with explicit Light theme avoids the issue (not officially confirmed) + +--- + +## References + +- [Background Tasks - WinAppSDK Documentation](https://learn.microsoft.com/en-us/windows/apps/windows-app-sdk/applifecycle/background-tasks) +- [PrintDocument Class - WinUI](https://learn.microsoft.com/en-us/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.printing.printdocument) +- [WinUI Item Templates - Visual Studio](https://learn.microsoft.com/en-us/windows/apps/winui/winui3/winui-project-templates-in-visual-studio) +- [Related: microsoft-ui-xaml#10769 - Background task ACCESS_VIOLATION](https://github.com/microsoft/microsoft-ui-xaml/issues/10769) + +--- + +**Updated:** 2025-07-17 | **Confidence:** 0.6 +**Sources:** #5870, #6086, #1236, Microsoft Learn documentation diff --git a/tsg/tsg_deployment_singlefile_installer.md b/tsg/tsg_deployment_singlefile_installer.md new file mode 100644 index 0000000..e55ce57 --- /dev/null +++ b/tsg/tsg_deployment_singlefile_installer.md @@ -0,0 +1,161 @@ +# Error: "XamlParseException: XAML parsing failed" — Renamed Single-File Unpackaged App / Broken Runtime Links + +**Keywords:** XamlParseException, XAML parsing failed, single-file, unpackaged, rename executable, PublishSingleFile, runtime links broken, 2.0 preview, installer binaries, MRM.dll crash + +**Error Example:** +``` +Microsoft.UI.Xaml.Markup.XamlParseException: XAML parsing failed. + at WinRT.ExceptionHelpers.g__Throw|38_0(Int32) + at ABI.Microsoft.UI.Xaml.IApplicationStaticsMethods.LoadComponent(...) + at Microsoft.UI.Xaml.Application.LoadComponent(Object, Uri, ComponentResourceLocation) + at TestApp1.MainWindow.InitializeComponent() +``` + +--- + +## Quick Match + +**You're seeing this if:** +- You published a WinUI 3 app as single-file unpackaged and renamed the `.exe` +- Error contains "XamlParseException" or "XAML parsing failed" after renaming +- WASDK 2.0 Preview runtime download links return 404 +- WASDK 1.6.3 installers ship binaries that still crash despite documented fixes + +→ Check scenarios below for your specific cause + +--- + +## Related Issues + +- [#6248](https://github.com/microsoft/WindowsAppSDK/issues/6248) — Renaming published executable makes Single-File Unpackaged App crash (Status: Open) +- [#6220](https://github.com/microsoft/WindowsAppSDK/issues/6220) — WASDK 2.0 Preview runtime links are broken (Status: Closed/Fixed) +- [#4977](https://github.com/microsoft/WindowsAppSDK/issues/4977) — 1.6.3 installers contain binaries built from older source code (Status: Closed) + +--- + +## Scenarios & Solutions + +### Scenario 1: Renaming Single-File Published Executable Causes XamlParseException + +**Cause:** When a WinUI 3 app is published as a single-file, self-contained, unpackaged app and the resulting `.exe` is renamed (e.g., `TestApp1.exe` → `TestApp11.exe`), XAML resource loading fails. The `Application.LoadComponent` call uses URI-based resource paths that are tied to the original executable name, so renaming breaks the lookup. +> Source: Issue reporter in [#6248](https://github.com/microsoft/WindowsAppSDK/issues/6248) + +**Reproduction config:** +```xml + + None + true + +``` +```xml + +true +true +true +``` + +**Fix:** No official fix available yet. **Do not rename the published executable.** + +**Workaround:** Keep the original executable name after publishing. If branding requires a different name, change the `AssemblyName` in your `.csproj` before publishing instead of renaming the output file. + +> ⚠️ @aepot in [#6248](https://github.com/microsoft/WindowsAppSDK/issues/6248) reports being stuck on WASDK 1.7 because of this bug. + +--- + +### Scenario 2: WASDK 2.0 Preview Runtime Download Links Broken + +**Cause:** The `aka.ms` download links for WASDK 2.0 Preview 1 runtime installers were returning 404 errors shortly after the preview release. +> Source: Issue reporter in [#6220](https://github.com/microsoft/WindowsAppSDK/issues/6220) + +**Affected links:** +``` +https://aka.ms/windowsappsdk/2.0/2.0-preview1/windowsappruntimeinstall-x64.exe +https://aka.ms/windowsappsdk/2.0/2.0-preview1/windowsappruntimeinstall-x86.exe +https://aka.ms/windowsappsdk/2.0/2.0-preview1/windowsappruntimeinstall-arm64.exe +https://aka.ms/windowsappsdk/2.0/2.0-preview1/Microsoft.WindowsAppRuntime.Redist.2.0.zip +``` + +**Fix:** Links have been corrected by Microsoft. +> ✅ Confirmed by: @lauren-ciha (MEMBER) in [#6220](https://github.com/microsoft/WindowsAppSDK/issues/6220) + +**Working Redist link:** +``` +https://aka.ms/windowsappsdk/2.0/2.0-preview1/Microsoft.WindowsAppRuntime.Redist.2.0-preview1.zip +``` + +**Verify:** Check the [official WASDK downloads page](https://learn.microsoft.com/en-us/windows/apps/windows-app-sdk/downloads) for current links. + +--- + +### Scenario 3: WASDK 1.6.3 Installers Contain Stale Binaries (MRM.dll Crash) + +**Cause:** The WASDK 1.6.3 (1.6.241114003) runtime installers shipped binaries built from an older commit in the `release/1.6-stable` branch rather than from the `v1.6.3` tag. Specifically, `MRM.dll` did not include the [buffer overrun fix](https://github.com/microsoft/WindowsAppSDK/commit/1db04b650194f090ba1b52ae48f61277737c19f0), causing crashes in apps that use MRT resource loading. +> Source: Issue reporter in [#4977](https://github.com/microsoft/WindowsAppSDK/issues/4977) + +**Diagnostic:** +``` +# Check installed MRM.dll version/timestamp +C:\Program Files\WindowsApps\Microsoft.WindowsAppRuntime.1.6_6000.318.2304.0_arm64__8wekyb3d8bbwe\MRM.dll +``` + +**Fix:** WASDK 1.6 has reached End of Support. Upgrade to WASDK 1.8 or later. +> Source: @alexlamtest (CONTRIBUTOR) in [#4977](https://github.com/microsoft/WindowsAppSDK/issues/4977) + +**Additional note:** @tpoint75 in [#4977](https://github.com/microsoft/WindowsAppSDK/issues/4977) also noted that runtime installers had incorrect version numbers. + +--- + +## ⚠️ Unverified / Community Suggestions + +> The following are community suggestions that have NOT been officially confirmed. + +- For #6248: Changing `AssemblyName` before build instead of post-publish rename may avoid the issue (community suggestion — untested) + +--- + +## Diagnostic Steps + +### For Scenario 1 (Renamed EXE crash): +```powershell +# Check original executable name from assembly metadata +[System.Reflection.AssemblyName]::GetAssemblyName("C:\path\to\published\app.exe").Name + +# Compare XAML resource URIs embedded in the assembly +# The URI paths reference the original assembly name +ildasm /text "C:\path\to\published\app.exe" | Select-String "ms-appx" +``` + +### For Scenario 2 (Broken links): +```powershell +# Test if aka.ms redirect resolves correctly +Invoke-WebRequest -Uri "https://aka.ms/windowsappsdk/2.0/2.0-preview1/windowsappruntimeinstall-x64.exe" -Method Head +``` + +### For Scenario 3 (Stale binaries): +```powershell +# Check installed MRM.dll file version and timestamp +Get-Item "C:\Program Files\WindowsApps\Microsoft.WindowsAppRuntime.1.6*\MRM.dll" | + Select-Object Name, VersionInfo, LastWriteTime + +# Compare against expected version from release tag +# Expected: built from v1.6.3 tag commit, not release/1.6-stable branch +``` + +### General version verification: +```powershell +# Check installed WASDK runtime version +Get-AppxPackage *WindowsAppRuntime* -AllUsers | Select-Object Name, Version, Architecture +``` + +--- + +## References + +- [WASDK Downloads](https://learn.microsoft.com/en-us/windows/apps/windows-app-sdk/downloads) +- [Single-file deployment docs](https://learn.microsoft.com/en-us/dotnet/core/deploying/single-file) +- [WASDK Release Notes](https://learn.microsoft.com/en-us/windows/apps/windows-app-sdk/stable-channel) + +--- + +**Updated:** 2026-03-13 | **Confidence:** 0.7 +**Sources:** #6248, #6220, #4977 diff --git a/tsg/tsg_deployment_wasdk18_windows10.md b/tsg/tsg_deployment_wasdk18_windows10.md new file mode 100644 index 0000000..74b14d8 --- /dev/null +++ b/tsg/tsg_deployment_wasdk18_windows10.md @@ -0,0 +1,173 @@ +# Error: App Crash on Launch / "FindPackagesByPackageFamily" Failure — WASDK 1.8 on Windows 10 + +**Keywords:** FindPackagesByPackageFamily, WASDK 1.8, Windows 10, 17763, 19041, DeploymentManager, crash on launch, 0x80070005, DDLM PackageFullName, MSIX.inventory + +**Error Example:** +``` +Faulting module name: Microsoft.UI.Xaml.dll, version: 3.1.8.0 +Exception code: 0xc000027b +``` +``` +The program "[3468] App1.exe" has exited, returning 2147942405 (0x80070005). +``` + +--- + +## Quick Match + +**You're seeing this if:** +- WinUI 3 / WASDK 1.8+ packaged app crashes immediately on launch on Windows 10 (builds 17763, 19041, 19045) +- `FindPackagesByPackageFamily()` fails to locate WASDK 1.8 runtime packages on Windows 10 +- No error dialog — the app silently exits +- Same app works fine on Windows 11 + +→ Check scenarios below for your specific cause + +--- + +## Related Issues + +- [#6117](https://github.com/microsoft/WindowsAppSDK/issues/6117) — FindPackagesByPackageFamily unable to find WASDK 1.8 packages (Status: Open) +- [#6254](https://github.com/microsoft/WindowsAppSDK/issues/6254) — WindowAppSdk v1.8 cannot run on lower versions of Windows 10 (Status: Open) +- [#6156](https://github.com/microsoft/WindowsAppSDK/issues/6156) — MSIX.inventory has wrong DDLM PackageFullName (Status: Closed/Fixed) + +--- + +## Scenarios & Solutions + +### Scenario 1: DeploymentManager Auto-Initializer Fails on Windows 10 + +**Cause:** WASDK 1.8 includes a static global initializer that calls `FindPackagesByPackageFamily()` via `DeploymentManager.Initialize()`. On Windows 10 (especially builds 17763 and 19041), this call fails to find the runtime packages, causing the app to crash before any UI loads. The `WinAppRuntime.Main.1.8` package may not be registered, and `DeploymentManager.Initialize()` crashes instead of registering it. +> Source: @HO-COOH in [#6117](https://github.com/microsoft/WindowsAppSDK/issues/6117), confirmed in [#6254](https://github.com/microsoft/WindowsAppSDK/issues/6254) + +**Fix (C# projects):** +Add the following to your `.csproj` to disable the auto-initializer: +```xml + + false + +``` + +**Fix (C++ projects):** +Disable auto-initializer in your `.vcxproj`: +```xml + + false + +``` + +> ✅ Confirmed by: @HO-COOH in [#6117](https://github.com/microsoft/WindowsAppSDK/issues/6117), @Marv51 suggested the same workaround in [#6254](https://github.com/microsoft/WindowsAppSDK/issues/6254) + +**Verify:** +```powershell +# Confirm runtime packages are installed for the user +Get-AppxPackage micro*win*app*run*1.8* -AllUsers +# Confirm Main package registration +Get-AppxPackage MicrosoftCorporationII.WinAppRuntime.Main.1.8 +``` + +--- + +### Scenario 2: WinAppRuntime.Main.1.8 Package Not Registered + +**Cause:** On affected Windows 10 machines, `Get-AppxPackage MicrosoftCorporationII.WinAppRuntime.Main.1.8` returns nothing. The Framework packages (x86/x64) are registered but the Main package is missing. `DeploymentManager.Initialize()` is supposed to detect and register it, but crashes instead. +> Source: @DrusTheAxe and @HO-COOH in [#6117](https://github.com/microsoft/WindowsAppSDK/issues/6117) + +**Fix:** +1. Disable the auto-initializer as shown in Scenario 1. +2. If needed, manually register the Main package or reinstall the WASDK 1.8 runtime. + +**Diagnostic steps** (suggested by @DrusTheAxe in [#6117](https://github.com/microsoft/WindowsAppSDK/issues/6117)): +```powershell +# Check all WASDK 1.8 packages +Get-AppxPackage micro*win*app*run*1.8* -AllUsers +# Check your app's package +Get-AppxPackage *your*package*name* -AllUsers +# Check appxmanifest.xml for PackageDependency +# Verify TargetDeviceFamily MaxVersionTested values +``` + +--- + +### Scenario 3: MSIX.inventory Has Incorrect DDLM PackageFullName + +**Cause:** The `MSIX.inventory` file in the `Microsoft.WindowsAppSDK.Runtime` NuGet package listed an incorrect prefix for the DDLM package. The file used `Microsoft.WindowsAppRuntime.DDLM` but the actual installed package name uses `Microsoft.WinAppRuntime.DDLM`, causing package validation checks to fail. +> Source: Issue reporter in [#6156](https://github.com/microsoft/WindowsAppSDK/issues/6156) + +**Fix:** This was fixed in the aggregator. +> ✅ Confirmed by: @ssparach and @guimafelipe (CONTRIBUTOR) in [#6156](https://github.com/microsoft/WindowsAppSDK/issues/6156) + +**Verify:** +Check that the DDLM entry in `MSIX.inventory` uses the `Microsoft.WinAppRuntime.DDLM` prefix: +``` +Microsoft.WindowsAppRuntime.DDLM.1.8.msix=Microsoft.WinAppRuntime.DDLM.-... +``` + +--- + +### Scenario 4: Third-Party Apps (AppInstaller, Xbox) Also Crashing + +**Cause:** The issue is not limited to custom apps. Any app using `WindowsAppRuntime.1.8` framework can crash on Windows 10, including first-party Microsoft apps like AppInstaller and Xbox. +> Source: @RemyYYZ in [#6117](https://github.com/microsoft/WindowsAppSDK/issues/6117) and [#6254](https://github.com/microsoft/WindowsAppSDK/issues/6254) + +**Symptoms:** +``` +Faulting application name: AppInstaller.exe, version: 1.27.460.0 +Faulting module name: Microsoft.UI.Xaml.dll, version: 3.1.8.0 +Exception code: 0xc000027b +Windows Version: 10.0.19045.6937 +``` + +**Fix:** +No user-side workaround for pre-built apps. This requires a fix from Microsoft in the WASDK runtime. For your own apps, use the auto-initializer disable workaround from Scenario 1. + +--- + +## ⚠️ Unverified / Community Suggestions + +> The following are community suggestions that have NOT been officially confirmed. + +- Changing `TargetDeviceFamily` `MaxVersionTested` to match between `Windows.Universal` and `Windows.Desktop` may help (from @DrusTheAxe in #6117) +- Downgrade to WASDK 1.7 as a temporary measure — confirmed working on Windows 10 (from @lgBlog in #6254) + +--- + +## Diagnostic Steps + +```powershell +# 1. Check Windows version +winver.exe +# Or programmatically: +[System.Environment]::OSVersion.Version + +# 2. Check all WASDK 1.8 runtime packages +Get-AppxPackage micro*win*app*run*1.8* -AllUsers + +# 3. Check if Main package is registered (should NOT be empty) +Get-AppxPackage MicrosoftCorporationII.WinAppRuntime.Main.1.8 + +# 4. Check your app's package dependencies +# Open your appxmanifest.xml and look for: +# + +# 5. Check Event Viewer for crash details +Get-WinEvent -LogName Application -MaxEvents 20 | + Where-Object { $_.Message -like "*WindowsAppRuntime*" -or $_.Message -like "*Microsoft.UI.Xaml*" } + +# 6. Verify DDLM package name format in MSIX.inventory +# Navigate to NuGet package cache and check: +# .nuget\packages\microsoft.windowsappsdk.runtime\\tools\MSIX\\MSIX.inventory +``` + +--- + +## References + +- [WASDK Deployment project properties](https://learn.microsoft.com/en-us/windows/apps/package-and-deploy/project-properties) +- [WASDK Downloads](https://learn.microsoft.com/en-us/windows/apps/windows-app-sdk/downloads) +- [DeploymentManager.Initialize API](https://learn.microsoft.com/en-us/windows/windows-app-sdk/api/winrt/microsoft.windows.applicationmodel.windowsappruntime.deploymentmanager.initialize) + +--- + +**Updated:** 2026-03-13 | **Confidence:** 0.8 +**Sources:** #6117, #6254, #6156 diff --git a/tsg/tsg_external_interop_issues.md b/tsg/tsg_external_interop_issues.md new file mode 100644 index 0000000..5604874 --- /dev/null +++ b/tsg/tsg_external_interop_issues.md @@ -0,0 +1,191 @@ +# External / Interop Issues — Packaging, Device APIs, and Widgets + +**Keywords:** packaging project, NuGet, stale assembly, MSIX bundle, FindPackagesByPackageFamily, 0x8007007A, ERROR_INSUFFICIENT_BUFFER, DeviceInformationPairing, Bluetooth, ProximityDevice, NFC, Widgets, WinUI 3 + +**Error Example:** +``` +WinRT error 0x8007007A: "The data area passed to a system call is too small." + at FindPackagesByPackageFamily() +``` +``` +System.InvalidCastException + at WinRT.Interop.InitializeWithWindow.Initialize(DeviceInformation.Pairing, windowHandle) +``` + +--- + +## Quick Match + +**You're seeing this if:** +- MSIX bundle contains wrong (stale) NuGet DLL versions after package downgrade +- Error `0x8007007A` on app startup from `FindPackagesByPackageFamily` +- Bluetooth device pairing UI fails to show in WinUI 3 desktop app +- NFC `ProximityDevice` events never fire after UWP → WinUI 3 migration +- Widgets panel: first widget (alphabetically) cannot be added + +→ Check scenarios below for your specific cause + +--- + +## Related Issues + +- [#6253](https://github.com/microsoft/WindowsAppSDK/issues/6253) — Packaging project caches stale NuGet assembly references across builds (Status: Closed) +- [#6274](https://github.com/microsoft/WindowsAppSDK/issues/6274) — WinRT error 0x8007007A in `FindPackagesByPackageFamily` (Status: Open) +- [#3091](https://github.com/microsoft/WindowsAppSDK/issues/3091) — Unable to display device pairing UI in WinUI 3 app (Status: Closed) +- [#4356](https://github.com/microsoft/WindowsAppSDK/issues/4356) — ProximityDevice NFC events not triggered (Status: Open) +- [#6140](https://github.com/microsoft/WindowsAppSDK/issues/6140) — Widget at top of list cannot be added until switching away (Status: Open) + +--- + +## Scenarios & Solutions + +### Scenario 1: Packaging Project Caches Stale NuGet Assembly References Across Builds + +**Cause:** When using the Packaging project to produce MSIX bundles, downgrading (or upgrading) a NuGet package reference and rebuilding results in the previously-built DLL version being included in the bundle. Neither **Clean Solution** nor restarting Visual Studio resolves this. The packaging project caches assembly paths and does not properly invalidate them when NuGet versions change. +> Source: Issue [#6253](https://github.com/microsoft/WindowsAppSDK/issues/6253) — also filed on [VS Developer Community](https://developercommunity.visualstudio.com/t/Packaging-project-caches-stale-NuGet-ass/110512955) + +**Affected versions:** Visual Studio 2026, Windows App SDK (MSIX packaging), any NuGet package + +**Repro:** +1. Reference `CommunityToolkit.Mvvm` version **8.3.2**, build MSIX bundle → DLL is 8.3.2.1 ✅ +2. Upgrade to **8.4.0**, Clean Solution, rebuild → DLL is 8.4.0.1 ✅ +3. Downgrade back to **8.3.2**, Clean Solution, rebuild → DLL is still **8.4.0.1** ⚠️ + +**Fix:** +1. **Manually delete the packaging project output folders** before rebuilding: + - Delete `App1 (Package)\AppPackages\` folder + - Delete `App1 (Package)\bin\` and `App1 (Package)\obj\` folders +2. **Force a full NuGet restore** after version change: +```powershell +dotnet nuget locals all --clear +dotnet restore +``` +3. **Rebuild** (not just Build) the entire solution after clearing caches. + +**Verify:** Open the resulting `.msixbundle` in 7-Zip and confirm the DLL version matches the referenced NuGet version. + +--- + +### Scenario 2: WinRT Error 0x8007007A — "Data Area Passed to a System Call Is Too Small" + +**Cause:** On app startup, `FindPackagesByPackageFamily` reports `ERROR_INSUFFICIENT_BUFFER` (HRESULT `0x8007007A`). The debugger shows `bufferLength = 80` and corrupted locals (huge vector size, invalid pointer), indicating a buffer overflow. The root cause is a buffer size mismatch: the API returns a required **character count** for a `PWSTR` buffer, but the calling code likely allocated `bufferLength` **bytes** instead of `bufferLength * sizeof(wchar_t)`. +> Source: Issue [#6274](https://github.com/microsoft/WindowsAppSDK/issues/6274) + +**Affected versions:** Windows App SDK 1.8.5 (1.8.260209005), Windows 11 24H2 + +**Important note:** This exception surfaces only when **"Break when thrown"** is enabled for all exceptions in Visual Studio's Exception Settings. In normal execution, the SDK may handle this internally. + +**Fix:** +1. **Check if this is a first-chance exception only.** Uncheck "Break when thrown" for `WinRT originate error` exceptions in Visual Studio → Exception Settings. If the app runs normally, this is an internal SDK exception that is caught and handled. +2. If calling `FindPackagesByPackageFamily` in your own code, ensure proper two-call pattern: +```cpp +UINT32 count = 0; +UINT32 bufferLength = 0; +// First call: get required sizes +FindPackagesByPackageFamily(familyName, PACKAGE_FILTER_HEAD, &count, nullptr, &bufferLength, nullptr, nullptr); +// Allocate with correct units (characters, not bytes) +PWSTR buffer = new WCHAR[bufferLength]; // bufferLength is in characters +PWSTR* packageFullNames = new PWSTR[count]; +// Second call: retrieve data +FindPackagesByPackageFamily(familyName, PACKAGE_FILTER_HEAD, &count, packageFullNames, &bufferLength, buffer, nullptr); +``` +3. Handle `ERROR_INSUFFICIENT_BUFFER` return code as expected (it is the normal first-call response). + +**Verify:** Run app with first-chance exception breaking disabled and confirm no user-visible crash. + +--- + +### Scenario 3: Device Pairing UI Does Not Display in WinUI 3 Desktop App + +**Cause:** Calling `DeviceInformationPairing.PairAsync()` in a WinUI 3 desktop app does not show the system Bluetooth pairing UI. The pairing process silently fails after a few seconds. The `IInitializeWithWindow` workaround documented for other UWP controls throws `System.InvalidCastException` when applied to `DeviceInformation` or `DeviceInformation.Pairing` because these objects do not implement `IInitializeWithWindow`. +> Source: Issue [#3091](https://github.com/microsoft/WindowsAppSDK/issues/3091) + +**Affected versions:** Windows App SDK 1.0+, Windows 11 (21H2) + +**Fix:** +1. **Use `DeviceInformationCustomPairing`** with a custom handler instead of the automatic pairing UI: +```csharp +var customPairing = deviceInfo.Pairing.Custom; +customPairing.PairingRequested += (sender, args) => +{ + // Handle pairing ceremony in your own UI + args.Accept(); // or args.Accept(pin) for PIN-based pairing +}; +var result = await customPairing.PairAsync( + DevicePairingKinds.ConfirmOnly | DevicePairingKinds.DisplayPin); +``` +2. **Build your own pairing confirmation dialog** in WinUI 3 XAML since the system pairing UI is not compatible with Win32 desktop windows. +3. For Bluetooth LE devices, consider using `BluetoothLEDevice.FromIdAsync()` followed by `DeviceInformation.Pairing.Custom.PairAsync()`. + +**Verify:** Initiate Bluetooth pairing and confirm your custom UI appears and the device pairs successfully. + +--- + +### Scenario 4: ProximityDevice NFC Events Not Triggered After UWP → WinUI 3 Migration + +**Cause:** `Windows.Networking.Proximity.ProximityDevice` events (e.g., `SubscribeForMessage("NDEF", ...)`) work in UWP but do not fire in WinUI 3 / Windows App SDK desktop apps. The `ProximityDevice` API is a UWP-era API that relies on the UWP app model and brokered device access, which is not fully supported in the Win32 desktop app model used by WinUI 3. +> Source: Issue [#4356](https://github.com/microsoft/WindowsAppSDK/issues/4356) + +**Affected versions:** Windows App SDK 1.5.2+, Windows 11 22H2 + +**Repro:** +```csharp +var proximityDevice = Windows.Networking.Proximity.ProximityDevice.GetDefault(); +var messageSubscriptionId = proximityDevice.SubscribeForMessage("NDEF", (device, message) => +{ + Console.WriteLine(message.Data.ToArray()); // Never fires in WinUI 3 +}); +``` + +**Fix / Workaround:** +1. **Use the PC/SC (WinSCard) API** for NFC smart card access as an alternative to `ProximityDevice`: +```csharp +// Use Windows.Devices.SmartCards namespace +var reader = await SmartCardReader.FromIdAsync(deviceId); +reader.CardAdded += OnCardAdded; +``` +2. **Use a third-party NFC library** that wraps the Win32 PC/SC APIs (e.g., PCSC-Sharp). +3. Ensure `` is declared in your app manifest (required but not sufficient for WinUI 3). +4. As a last resort, **keep NFC functionality in a separate UWP component** or background task that communicates with the main WinUI 3 app. + +> ⚠️ This is an open issue. `ProximityDevice` is not officially supported in WinUI 3 desktop apps. + +--- + +### Scenario 5: Widget at Top of Alphabetical List Cannot Be Added + +**Cause:** In the Windows Widgets panel, a widget whose name starts with "A" (appearing at the top of the list) cannot be added — the "Add" button stays gray/inactive. Switching to another widget and back causes it to become addable. This appears to be a UI initialization/selection state bug in the Widgets Board. +> Source: Issue [#6140](https://github.com/microsoft/WindowsAppSDK/issues/6140) + +**Affected versions:** Windows 11 25H2 (Build 26220.7535) + +**Fix / Workaround:** +1. **Workaround for end users:** Select a different widget first, then switch back to the desired widget — it will become addable. +2. **For widget developers:** Consider naming your widget to not appear first alphabetically as a temporary workaround (e.g., prefix with a space or non-"A" character), though this is not ideal. + +> ⚠️ This is a Windows Widgets Board bug — no SDK-level fix available. Report via Feedback Hub for Windows team triage. + +--- + +## ⚠️ Unverified / Community Suggestions + +> The following are community suggestions that have NOT been officially confirmed. + +- For stale NuGet caching (#6253): Some developers report that switching the solution configuration (Debug ↔ Release) and rebuilding can force correct DLL resolution. +- For NFC (#4356): The original reporter tried `DeviceCapability` declarations and multiple SDK versions without success. There is no confirmed workaround within the WinUI 3 app model. + +--- + +## References + +- [FindPackagesByPackageFamily function (Win32)](https://learn.microsoft.com/en-us/windows/win32/api/appmodel/nf-appmodel-findpackagesbypackagefamily) +- [Display UI objects in WinUI 3 (IInitializeWithWindow)](https://docs.microsoft.com/en-us/windows/apps/develop/ui-input/display-ui-objects) +- [DeviceInformationCustomPairing API](https://learn.microsoft.com/en-us/uwp/api/windows.devices.enumeration.deviceinformationcustompairing) +- [ProximityDevice API (UWP)](https://learn.microsoft.com/en-us/uwp/api/windows.networking.proximity.proximitydevice) +- [Windows Widgets overview](https://learn.microsoft.com/en-us/windows/apps/develop/widgets/) +- [MSIX packaging documentation](https://learn.microsoft.com/en-us/windows/msix/) + +--- + +**Updated:** 2025-07-17 | **Confidence:** 0.6 +**Sources:** #6253, #6274, #3091, #4356, #6140 diff --git a/tsg/tsg_file_access_storage_pickers.md b/tsg/tsg_file_access_storage_pickers.md new file mode 100644 index 0000000..0a9d0ee --- /dev/null +++ b/tsg/tsg_file_access_storage_pickers.md @@ -0,0 +1,199 @@ +# Storage Picker Issues — File Access & Picker Dialogs + +**Keywords:** FileOpenPicker, FileSavePicker, FolderPicker, storage pickers, file picker crash, COMException, E_FAIL, IInitializeWithWindow, DefaultFileExtension, FileTypeChoices, WSL, RTL, language override + +**Error Example:** +``` +System.Runtime.InteropServices.COMException: 'Error HRESULT E_FAIL has been returned from a call to a COM component.' + at Windows.Storage.Pickers.FileOpenPicker.PickSingleFileAsync() +``` + +--- + +## Quick Match + +**You're seeing this if:** +- Error contains "E_FAIL" or "COMException" when calling `PickSingleFileAsync()` or `PickSaveFileAsync()` +- File/Folder picker dialog behaves unexpectedly (wrong extension, missing folders, wrong language) +- Using `FileOpenPicker`, `FileSavePicker`, or `FolderPicker` from a WinUI 3 / Windows App SDK desktop app +- Platform: Windows App SDK (packaged or unpackaged), WinUI 3 + +→ Check scenarios below for your specific cause + +--- + +## Related Issues + +- [#1063](https://github.com/microsoft/WindowsAppSDK/issues/1063) — Simplify using UWP file pickers from desktop apps (Status: Closed — feature proposal) +- [#2504](https://github.com/microsoft/WindowsAppSDK/issues/2504) — FileOpenPicker crashes when app runs as Administrator (Status: Closed) +- [#5975](https://github.com/microsoft/WindowsAppSDK/issues/5975) — FileSavePicker cannot set default extension when defining FileTypeChoices (Status: Closed) +- [#6284](https://github.com/microsoft/WindowsAppSDK/issues/6284) — FolderPicker does not show WSL (Linux) folders (Status: Open) +- [#6105](https://github.com/microsoft/WindowsAppSDK/issues/6105) — How to change or force storage pickers to a specific language? (Status: Open) + +--- + +## Scenarios & Solutions + +### Scenario 1: FileOpenPicker / FolderPicker Crashes with COMException When Running as Administrator + +**Cause:** Calling `PickSingleFileAsync()` on a `FileOpenPicker` (or `FolderPicker`) while the app is running elevated (Run as Administrator) throws `COMException: Error HRESULT E_FAIL`. This is a known limitation of the Windows shell file picker COM infrastructure under elevated processes. +> Source: Issue [#2504](https://github.com/microsoft/WindowsAppSDK/issues/2504) + +**Affected versions:** Windows App SDK 1.4.2+, .NET 7+, Windows 11 + +**Repro code that triggers the crash:** +```csharp +var picker = new FileOpenPicker(); +picker.FileTypeFilter.Add("*"); +InitializeWithWindow.Initialize(picker, App.MainWindow.GetHandle()); +var file = await picker.PickSingleFileAsync(); // Crashes when elevated +``` + +**Fix:** +1. **Avoid running the app elevated** when file picker usage is required. Separate elevated operations into a background service or helper process. +2. **Use Win32 `GetOpenFileName` / `IFileDialog` COM APIs** directly instead of UWP pickers when elevation is required — these Win32 APIs work under Administrator. +3. If elevation is unavoidable, wrap the picker call in a try/catch and fall back to a Win32 file dialog: +```csharp +try +{ + var file = await picker.PickSingleFileAsync(); +} +catch (COMException ex) when (ex.HResult == unchecked((int)0x80004005)) +{ + // Fall back to Win32 IFileDialog +} +``` + +**Verify:** Launch the app as Administrator and confirm file picker opens without crash. + +--- + +### Scenario 2: IInitializeWithWindow Boilerplate Required for Desktop Apps + +**Cause:** UWP file pickers (`FileOpenPicker`, `FileSavePicker`, `FolderPicker`) require a parent window handle (HWND) when used in Win32/desktop apps. Without calling `IInitializeWithWindow.Initialize()`, the picker has no owner window and will fail. +> Source: Issue [#1063](https://github.com/microsoft/WindowsAppSDK/issues/1063) + +**Fix (WinUI 3 / Windows App SDK 1.8+):** + +Starting with Windows App SDK 1.8, new picker constructors accept a `WindowId` directly, eliminating the interop boilerplate: +```csharp +// New simplified approach (SDK 1.8+) +var picker = new FileOpenPicker(appWindow.Id); +picker.FileTypeFilter.Add("*"); +var file = await picker.PickSingleFileAsync(); +``` + +**Fix (Older SDK versions):** +```csharp +var picker = new FileOpenPicker(); +picker.FileTypeFilter.Add("*"); + +// Required interop for desktop apps +var hwnd = WinRT.Interop.WindowNative.GetWindowHandle(this); +WinRT.Interop.InitializeWithWindow.Initialize(picker, hwnd); + +var file = await picker.PickSingleFileAsync(); +``` + +**Verify:** Picker dialog opens with the correct parent window and does not throw. + +--- + +### Scenario 3: FileSavePicker Ignores DefaultFileExtension — Always Uses First Sorted Entry + +**Cause:** The `DefaultFileExtension` property is ignored. `FileTypeChoices` is always sorted alphabetically, and the first sorted item is selected by default regardless of `DefaultFileExtension` or insertion order. +> Source: Issue [#5975](https://github.com/microsoft/WindowsAppSDK/issues/5975) + +**Affected versions:** Windows App SDK 1.8.2 (1.8.251003001), unpackaged and packaged + +**Repro:** +```csharp +var saveDialog = new FileSavePicker(AppWindow.Id) +{ + DefaultFileExtension = ".xml", +}; +saveDialog.FileTypeChoices.TryAdd("TXT", [".txt"]); +saveDialog.FileTypeChoices.TryAdd("JSON", [".json"]); +saveDialog.FileTypeChoices.TryAdd("XML", [".xml"]); + +var picker = await saveDialog.PickSaveFileAsync(); +// Result: ".json" is selected as default (alphabetical first), not ".xml" +``` + +**Fix / Workaround:** +1. **Order your `FileTypeChoices` so the desired default is alphabetically first**, or add only the desired default type initially. +2. Use `SuggestedFileName` with the desired extension to hint the dialog: +```csharp +saveDialog.SuggestedFileName = "document.xml"; +``` +3. If a single file type is needed, register only that type in `FileTypeChoices`. + +> ⚠️ This is a confirmed bug. No official SDK-level fix is available at this time. + +--- + +### Scenario 4: FolderPicker Does Not Show WSL (Linux) Folders + +**Cause:** `FolderPicker` does not enumerate WSL network locations (`\\wsl$\...`), while `FileOpenPicker` does. The `FolderPicker` appears to handle virtual/network shell namespace locations differently than `FileOpenPicker`. Temporarily, after navigating to a WSL path via `FileOpenPicker`, `FolderPicker` may briefly show WSL folders (cache/state inheritance) but loses them on subsequent opens. +> Source: Issue [#6284](https://github.com/microsoft/WindowsAppSDK/issues/6284) + +**Affected versions:** Windows App SDK 1.8 (1.8.250916003), Windows 11 + +**Fix / Workaround:** +1. **Use `FileOpenPicker` first** to navigate to a WSL path, then immediately open `FolderPicker` — WSL folders may appear transiently. +2. **Use Win32 `IFileDialog` with `FOS_PICKFOLDERS`** flag for reliable WSL folder browsing: +```cpp +IFileDialog *pfd; +CoCreateInstance(CLSID_FileOpenDialog, NULL, CLSCTX_INPROC_SERVER, IID_PPV_ARGS(&pfd)); +DWORD dwOptions; +pfd->GetOptions(&dwOptions); +pfd->SetOptions(dwOptions | FOS_PICKFOLDERS); +pfd->Show(hwnd); +``` +3. Alternatively, allow the user to paste the WSL UNC path (`\\wsl$\Ubuntu\...`) directly if your UI supports text entry. + +> ⚠️ This is a confirmed open bug — no SDK fix available yet. + +--- + +### Scenario 5: Storage Pickers Inherit App Language / RTL Layout Override + +**Cause:** Setting `Microsoft.Windows.Globalization.ApplicationLanguages.PrimaryLanguageOverride` changes the language and layout direction (LTR/RTL) of storage picker dialogs. Picker dialogs respect the app-wide language override, which is undesired when the app uses RTL languages (e.g., Persian `fa-IR`) but the picker should remain LTR. +> Source: Issue [#6105](https://github.com/microsoft/WindowsAppSDK/issues/6105) + +**Affected versions:** Windows App SDK 1.8.3 (1.8.251106002), packaged and unpackaged + +**Fix / Workaround:** +1. **Temporarily reset `PrimaryLanguageOverride`** before opening the picker, then restore it: +```csharp +var savedLang = ApplicationLanguages.PrimaryLanguageOverride; +ApplicationLanguages.PrimaryLanguageOverride = "en-US"; // Force LTR for picker +var file = await picker.PickSingleFileAsync(); +ApplicationLanguages.PrimaryLanguageOverride = savedLang; // Restore +``` +2. **Use `ResourceContext`** with a specific qualifier instead of the global language override to localize the app UI without affecting system dialogs. + +> ⚠️ This is an open issue — no official fix from Microsoft yet. + +--- + +## ⚠️ Unverified / Community Suggestions + +> The following are community suggestions that have NOT been officially confirmed. + +- For the Administrator crash (#2504): Some users report that creating pickers on the UI thread specifically (not from a background task) may reduce crash frequency, but this is not a reliable fix. +- For WSL folders (#6284): The transient visibility behavior suggests monitoring `FileOpenPicker` navigation state may help, but no programmatic API exists for this. + +--- + +## References + +- [Windows App SDK Storage Pickers documentation](https://learn.microsoft.com/en-us/windows/apps/develop/files/file-pickers) +- [Display UI objects in WinUI 3 (IInitializeWithWindow)](https://docs.microsoft.com/en-us/windows/apps/develop/ui-input/display-ui-objects) +- [FileOpenPicker API reference](https://learn.microsoft.com/en-us/windows/windows-app-sdk/api/winrt/microsoft.windows.storage.pickers.fileopenpicker) +- [FileSavePicker API reference](https://learn.microsoft.com/en-us/windows/windows-app-sdk/api/winrt/microsoft.windows.storage.pickers.filesavepicker) + +--- + +**Updated:** 2025-07-17 | **Confidence:** 0.7 +**Sources:** #1063, #2504, #5975, #6284, #6105 diff --git a/tsg/tsg_msix_build_publish_output_failures.md b/tsg/tsg_msix_build_publish_output_failures.md new file mode 100644 index 0000000..b88c8f6 --- /dev/null +++ b/tsg/tsg_msix_build_publish_output_failures.md @@ -0,0 +1,171 @@ +# Error: MSIX Build/Publish Output Failures (msixupload, msixbundle, appxsym) + +**Keywords:** msixupload, msixbundle, appxsym, WinAppSdkSignAppxPackageBundle, MSB4036, MSB6006, mspdbcmf.exe, CMF1106, UapAppxPackageBuildMode, StoreUpload, StoreAndSideload + +**Error Examples:** +``` +error MSB4036: The "WinAppSdkSignAppxPackageBundle" task was not found. +error MSB6006: "mspdbcmf.exe" have exited, fatal error CMF1106 +``` + +--- + +## Quick Match + +**You're seeing this if:** +- Building an MSIX bundle or upload package fails with MSB4036 or MSB6006 +- `msbuild` with `UapAppxPackageBuildMode=StoreUpload` does not produce `.msixupload` +- Publishing an MSIX from Visual Studio pollutes `.csproj.user` with `UapAppxPackageBuildMode` +- `mspdbcmf.exe` exits with fatal error CMF1106 during symbol package generation + +→ Check scenarios below for your specific cause + +--- + +## Related Issues + +- [#5820](https://github.com/microsoft/WindowsAppSDK/issues/5820) - Create app bundle fails with scaled images due to typo in targets (Status: Closed/Fixed) +- [#5825](https://github.com/microsoft/WindowsAppSDK/issues/5825) - Single packaging generates msixbundle but fails on appxsym (Status: Open) +- [#5501](https://github.com/microsoft/WindowsAppSDK/issues/5501) - UWP .NET 9 msbuild does not produce .msixupload file (Status: Open) +- [#5537](https://github.com/microsoft/WindowsAppSDK/issues/5537) - Publishing MSIX influences future builds via UapAppxPackageBuildMode (Status: Open) + +--- + +## Scenarios & Solutions + +### Scenario 1: "WinAppSdkSignAppxPackageBundle" Task Not Found (MSB4036) When Creating App Bundle + +**Cause:** A typo in `Microsoft.Windows.SDK.BuildTools.MSIX.Packaging.targets` references a non-existent task name `WinAppSdkSignAppxPackageBundle` instead of the correct `WinAppSdkSignAppxPackage`. This causes failures when `UapAppxPackageBuildMode` is set to `CI` or `StoreUpload` and the manifest contains scaled images or resource packages. +> Source: @zhuxb711 in [#5820](https://github.com/microsoft/WindowsAppSDK/issues/5820) + +**Conditions:** +- Only occurs with `UapAppxPackageBuildMode = CI` or `StoreUpload` +- `SideloadOnly` mode works fine +- Triggered when the manifest contains scaled visual assets (e.g., `SmallTile.scale-100.png`) + +**Fix:** +1. Locate the NuGet package targets file: + ``` + %USERPROFILE%\.nuget\packages\microsoft.windows.sdk.buildtools.msix\\build\Microsoft.Windows.SDK.BuildTools.MSIX.Packaging.targets + ``` +2. Find the `_CreateUploadResourcePackages` target +3. Replace `WinAppSdkSignAppxPackageBundle` with `WinAppSdkSignAppxPackage` + +**CI/CD Workaround (GitHub Actions):** +```yaml +- name: Restore NuGet Packages + shell: pwsh + run: | + msbuild "" /nr:false /restore /p:RestorePackagesConfig=true /p:PreferredToolArchitecture="x64" + +- name: Patch for WindowsAppSDK#5820 + shell: pwsh + run: | + $NuGetPackagesPath = $env:NUGET_PACKAGES ?? (Join-Path $env:USERPROFILE ".nuget/packages") + $TargetFilePath = Join-Path $NuGetPackagesPath "microsoft.windows.sdk.buildtools.msix//build/Microsoft.Windows.SDK.BuildTools.MSIX.Packaging.targets" + (Get-Content $TargetFilePath) -replace 'WinAppSdkSignAppxPackageBundle', 'WinAppSdkSignAppxPackage' | Set-Content $TargetFilePath +``` + +> ✅ Confirmed by: @zhuxb711, @MUJaCHe66 in [#5820](https://github.com/microsoft/WindowsAppSDK/issues/5820) +> @Scottj1s (Microsoft) acknowledged the bug and indicated a fix would be published in an updated `Microsoft.Windows.SDK.BuildTools.MSIX`. + +**Verify:** Build with `UapAppxPackageBuildMode=StoreUpload` completes without MSB4036 errors. + +--- + +### Scenario 2: mspdbcmf.exe Fails with Fatal Error CMF1106 During appxsym Generation + +**Cause:** The `_GenerateAppxSymbolPackage` target invokes `mspdbcmf.exe` to generate `.appxsym` symbol packages, but the tool fails with exit code CMF1106 on certain PDB files. The target does not respect `AppxSymbolPackageEnabled=false`, so setting that property alone does not bypass the failure. +> Source: @zhuxb711 in [#5825](https://github.com/microsoft/WindowsAppSDK/issues/5825) + +**Fix:** +1. Set `MsPdbCmfExeFullpath` to an invalid path to bypass `_GenerateAppxSymbolPackage`: + ```xml + + None + + ``` +2. Also pass `/p:AppxSymbolPackageEnabled="false"` to msbuild to fully disable symbol package generation: + ``` + msbuild YourProject.csproj /p:AppxSymbolPackageEnabled="false" + ``` + +> ✅ Confirmed by: @zhuxb711 in [#5825](https://github.com/microsoft/WindowsAppSDK/issues/5825) + +**Note:** This is a combined workaround. `AppxSymbolPackageEnabled=false` alone is insufficient because `_GenerateAppxSymbolPackage` does not check that property (see also [#6183](https://github.com/microsoft/WindowsAppSDK/issues/6183)). + +**Verify:** `msbuild` completes the msixbundle generation without CMF1106 errors. + +--- + +### Scenario 3: msbuild with StoreUpload Does Not Produce .msixupload File (UWP .NET 9) + +**Cause:** When using `msbuild` from the command line with `UapAppxPackageBuildMode=StoreUpload` for UWP .NET 9 projects, the build does not produce a `.msixupload` file. Multiple `AppxBundlePlatforms` are also not respected — only the first platform is compiled. The Visual Studio "Create App Packages" wizard works correctly, but the CLI equivalent does not. +> Source: @DilanBoskan in [#5501](https://github.com/microsoft/WindowsAppSDK/issues/5501) + +**Workaround:** +1. Build each platform separately using `msbuild` +2. Bundle and sign manually using `MakeAppx.exe` and `SignTool.exe`: + ```powershell + # Build each platform + MSBuild.exe YourApp.csproj /p:Configuration=Release /p:Platform=x86 + MSBuild.exe YourApp.csproj /p:Configuration=Release /p:Platform=x64 + MSBuild.exe YourApp.csproj /p:Configuration=Release /p:Platform=ARM64 + + # Create bundle manually + MakeAppx.exe bundle /d /p YourApp.msixbundle + + # Sign the bundle + SignTool.exe sign /fd SHA256 /a /f YourCert.pfx /p YourApp.msixbundle + ``` + +> Source: @DilanBoskan in [#5501](https://github.com/microsoft/WindowsAppSDK/issues/5501) + +**Note:** @0x5bfa confirmed that in WinAppSDK (non-UWP), the latest `Microsoft.Windows.SDK.BuildTools.MSIX` does produce msixupload and msixbundle. UWP .NET 9 may still be affected. + +**Verify:** Check that `.msixupload` file is generated in the output directory. + +--- + +### Scenario 4: Publishing MSIX Pollutes .csproj.user and Breaks Future Builds + +**Cause:** After publishing an MSIX from Visual Studio (1.8+), the property `StoreAndSideload` is written to `.csproj.user`. This causes every subsequent Release build to unnecessarily create an MSIX package, and publishing as an unpackaged app fails. +> Source: @lhak in [#5537](https://github.com/microsoft/WindowsAppSDK/issues/5537) + +**Fix:** +1. After publishing, delete or edit the `.csproj.user` file to remove: + ```xml + StoreAndSideload + ``` +2. Alternatively, set `UapAppxPackageBuildMode` to `SideloadOnly` to avoid the unwanted behavior: + ```xml + SideloadOnly + ``` + +> Source: @Scottj1s (Microsoft) in [#5537](https://github.com/microsoft/WindowsAppSDK/issues/5537) confirmed that `StoreAndSideload` always publishes on build, and `SideloadOnly` can be used to opt out. + +> @lhak confirmed this was not an issue in previous WinAppSDK versions, suggesting a regression in 1.8. + +**Verify:** Build in Release mode without `.csproj.user` containing `UapAppxPackageBuildMode` — no MSIX package should be created unless explicitly requested. + +--- + +## ⚠️ Unverified / Community Suggestions + +> The following are community suggestions that have NOT been officially confirmed. + +- For #5501: Use the Visual Studio "Create App Packages" wizard as the only reliable method for generating `.msixupload` with multi-platform UWP .NET 9 projects (from @DilanBoskan in #5501) +- Add `.csproj.user` to `.gitignore` to prevent `UapAppxPackageBuildMode` pollution from propagating across team members (general recommendation related to #5537) + +--- + +## References + +- [Single-project MSIX Packaging documentation](https://learn.microsoft.com/en-us/windows/apps/windows-app-sdk/single-project-msix) +- [MakeAppx.exe documentation](https://learn.microsoft.com/en-us/windows/msix/package/create-app-package-with-makeappx-tool) +- [Visual Studio Developer Community: mspdbcmf.exe failed](https://developercommunity.visualstudio.com/t/mspdbcmfexe-failed-with-exit-code-1106/11037870) + +--- + +**Updated:** 2025-07-18 | **Confidence:** 0.8 +**Sources:** [#5820](https://github.com/microsoft/WindowsAppSDK/issues/5820), [#5825](https://github.com/microsoft/WindowsAppSDK/issues/5825), [#5501](https://github.com/microsoft/WindowsAppSDK/issues/5501), [#5537](https://github.com/microsoft/WindowsAppSDK/issues/5537) diff --git a/tsg/tsg_msix_project_configuration_tooling.md b/tsg/tsg_msix_project_configuration_tooling.md new file mode 100644 index 0000000..34bb4c0 --- /dev/null +++ b/tsg/tsg_msix_project_configuration_tooling.md @@ -0,0 +1,150 @@ +# Error: MSIX Project Configuration & Build Tools Issues + +**Keywords:** EnableMsixTooling, Microsoft.Windows.SDK.BuildTools.MSIX, AppxOSMinVersionReplaceManifestVersion, AppxOSMaxVersionTestedReplaceManifestVersion, mspdbcmf.exe, wapproj, single-project MSIX, NuGet, Visual Studio, unpackaged, resources.pri + +**Error Examples:** +``` +error: "mspdbcmf.exe" hard-coded path dependency into Visual Studio installation +error: MinVersion and MaxVersionTested always replaced in package.appxmanifest +Application crashes due to missing resources.pri after publish +``` + +--- + +## Quick Match + +**You're seeing this if:** +- Building MSIX packages without Visual Studio installed fails due to missing `mspdbcmf.exe` +- Removing `EnableMsixTooling` from unpackaged app projects causes publish failures or missing `.pri` files +- `AppxOSMinVersionReplaceManifestVersion=false` is ignored by single-project MSIX +- Need to include multiple executables in a single MSIX package + +→ Check scenarios below for your specific cause + +--- + +## Related Issues + +- [#6197](https://github.com/microsoft/WindowsAppSDK/issues/6197) - MSIX NuGet package requires Visual Studio for mspdbcmf.exe (Status: Fixed internally) +- [#3718](https://github.com/microsoft/WindowsAppSDK/issues/3718) - Removing EnableMsixTooling breaks published unpackaged apps (Status: Open) +- [#5598](https://github.com/microsoft/WindowsAppSDK/issues/5598) - BuildTools.MSIX does not support AppxOSMinVersionReplaceManifestVersion (Status: Open) +- [#5586](https://github.com/microsoft/WindowsAppSDK/issues/5586) - Single-project packaging lacks multi-executable support (Status: Open) + +--- + +## Scenarios & Solutions + +### Scenario 1: Cannot Build MSIX Without Visual Studio — mspdbcmf.exe Hard-Coded Path + +**Cause:** The `Microsoft.Windows.SDK.BuildTools.MSIX` NuGet package targets contain a hard-coded path dependency on a Visual Studio installation to locate `mspdbcmf.exe`. This prevents MSIX package creation on machines without Visual Studio (e.g., when using JetBrains Rider or CI/CD environments with only the .NET SDK). +> Source: @wjk in [#6197](https://github.com/microsoft/WindowsAppSDK/issues/6197) + +**Status:** Marked as "Fixed internally" by the Windows App SDK team. The fix has not yet been released as of the issue's last update. + +**Workaround (while waiting for fix):** +1. If you only need to bypass symbol generation, set: + ```xml + + None + false + + ``` +2. If you need `mspdbcmf.exe`, install the Visual Studio Build Tools workload (lighter than full VS): + ``` + vs_buildtools.exe --add Microsoft.VisualStudio.Workload.ManagedDesktopBuildTools + ``` + +> ⚠️ Ideally the MSIX NuGet package would bundle `mspdbcmf.exe` or reference it from `Microsoft.Windows.SDK.BuildTools`. Neither option is currently available. + +**Verify:** `dotnet publish` completes without errors referencing Visual Studio paths. + +--- + +### Scenario 2: Removing EnableMsixTooling Breaks Published Unpackaged Apps (Missing resources.pri) + +**Cause:** `EnableMsixTooling` controls the renaming of `[ProjectName].pri` to `resources.pri` during the build process. When omitted from an unpackaged app project (`None`), the `.pri` file is not copied to the publish directory, causing the published app to crash at runtime with a missing resource error. +> Source: @Balkoth in [#3718](https://github.com/microsoft/WindowsAppSDK/issues/3718) + +**Fix:** +1. **Option A:** Keep `EnableMsixTooling` in the project file even for unpackaged apps: + ```xml + + None + true + + ``` +2. **Option B:** Manually copy the `.pri` file as a post-build step: + ```xml + + + + ``` + +> ✅ Confirmed by: @Balkoth in [#3718](https://github.com/microsoft/WindowsAppSDK/issues/3718) — manually copying the `.pri` file resolves the crash. + +**Important note on WinAppSDK 1.8+:** @DarranRowe identified in [#5746](https://github.com/microsoft/WindowsAppSDK/issues/5746) that in WinAppSDK 1.8, the behavior changed — unpackaged projects now correctly use `[AppName].pri` instead of `resources.pri`. If upgrading to 1.8, update any hard-coded references to `resources.pri` in your code. + +> @Psychlist1972 in [#3718](https://github.com/microsoft/WindowsAppSDK/issues/3718) noted that without `EnableMsixTooling`, `dotnet` command-line builds fail to generate the `.pri` file at all, breaking automated build processes. + +**Verify:** Published output directory contains the `.pri` file, and the application launches without resource-related crashes. + +--- + +### Scenario 3: AppxOSMinVersionReplaceManifestVersion Not Supported by Single-Project MSIX + +**Cause:** The `UpdateTargetDeviceFamily` task in `WinAppSdkGenerateAppxManifest.cs` (part of `Microsoft.Windows.SDK.BuildTools.MSIX`) does not support the `AppxOSMinVersionReplaceManifestVersion` and `AppxOSMaxVersionTestedReplaceManifestVersion` override properties. It always replaces `MinVersion` and `MaxVersionTested` in the generated `package.appxmanifest` with values from `TargetPlatformMinVersion` and `TargetPlatformVersion`, even when the override properties are set to `false`. +> Source: @Scottj1s in [#5598](https://github.com/microsoft/WindowsAppSDK/issues/5598) — internal tracking issue created at task.ms/58588581 + +**Context:** For UWP and wapproj-based projects, these override properties work correctly. The gap is only in the single-project MSIX tooling provided by the BuildTools.MSIX NuGet package. + +**Workaround:** +1. Use a post-build step to patch the generated `package.appxmanifest` with the desired values: + ```xml + + + + ``` +2. Alternatively, set `TargetPlatformMinVersion` and `TargetPlatformVersion` to match your desired manifest values (if acceptable for your project). + +**Verify:** Inspect the generated `package.appxmanifest` to confirm `MinVersion` and `MaxVersionTested` values match your expectations. + +--- + +### Scenario 4: Single-Project Packaging Does Not Support Multiple Executables + +**Cause:** Single-project MSIX packaging does not support multi-headed packages (packages containing multiple executables). This is the last remaining gap versus wapproj-based solutions, preventing the complete deprecation of the WAP project template. +> Source: @Scottj1s in [#5586](https://github.com/microsoft/WindowsAppSDK/issues/5586) + +**Current status:** This is a feature gap, not a bug. Microsoft is aware; @Scottj1s noted additional gaps (notably resource handling) also need to be closed for full parity. @michael-hawker in [#5586](https://github.com/microsoft/WindowsAppSDK/issues/5586) highlighted that removing the WAP template from Visual Studio would reduce confusion for new developers. + +**Workaround:** +1. Continue using a Windows Application Packaging Project (wapproj) for multi-executable MSIX packages +2. Reference: [Single-project MSIX limitations](https://github.com/MicrosoftDocs/windows-dev-docs/blob/docs/hub/apps/windows-app-sdk/single-project-msix.md#limitations) + +**Verify:** N/A — this is a feature request with no current workaround in single-project mode. + +--- + +## ⚠️ Unverified / Community Suggestions + +> The following are community suggestions that have NOT been officially confirmed. + +- For build environments without Visual Studio, consider using `Microsoft.Windows.SDK.BuildTools` NuGet alongside the MSIX package to reduce VS dependencies (from @wjk in #6197 — noted that `mspdbcmf.exe` is not included in that package either) +- For wapproj to single-project migration, consider tracking [#5586](https://github.com/microsoft/WindowsAppSDK/issues/5586) and [#6261](https://github.com/microsoft/WindowsAppSDK/issues/6261) for official guidance +- @riverar in [#3718](https://github.com/microsoft/WindowsAppSDK/issues/3718) suggested this as a candidate for inclusion in the updated MSIX tooling + +--- + +## References + +- [Single-project MSIX Packaging documentation](https://learn.microsoft.com/en-us/windows/apps/windows-app-sdk/single-project-msix) +- [Single-project MSIX limitations](https://github.com/MicrosoftDocs/windows-dev-docs/blob/docs/hub/apps/windows-app-sdk/single-project-msix.md#limitations) +- [Windows AI APIs — TargetDeviceFamily guidance](https://learn.microsoft.com/en-us/windows/ai/apis/get-started?tabs=winget%2Cwinui%2Cwinui2#build-a-new-app) +- [Microsoft.Windows.SDK.BuildTools.MSIX on NuGet](https://www.nuget.org/packages/Microsoft.Windows.SDK.BuildTools.MSIX) + +--- + +**Updated:** 2025-07-18 | **Confidence:** 0.7 +**Sources:** [#6197](https://github.com/microsoft/WindowsAppSDK/issues/6197), [#3718](https://github.com/microsoft/WindowsAppSDK/issues/3718), [#5598](https://github.com/microsoft/WindowsAppSDK/issues/5598), [#5586](https://github.com/microsoft/WindowsAppSDK/issues/5586) diff --git a/tsg/tsg_msix_selfcontained_packaging_conflicts.md b/tsg/tsg_msix_selfcontained_packaging_conflicts.md new file mode 100644 index 0000000..2db8833 --- /dev/null +++ b/tsg/tsg_msix_selfcontained_packaging_conflicts.md @@ -0,0 +1,130 @@ +# Error: Self-Contained Deployment and MSIX Packaging Conflicts + +**Keywords:** WindowsAppSDKSelfContained, XamlParseException, COMException, 0x80070490, resources.pri, PRI, _OverrideGetPriIndexName, EnableMsixTooling, WMC1012, ApplicationXaml, codegen, library project + +**Error Examples:** +``` +Microsoft.UI.Xaml.Markup.XamlParseException: 'XAML parsing failed.' +System.Runtime.InteropServices.COMException (0x80070490): Element not found. +NETSDK1022: Duplicate 'PRIResource' items were included. +WMC1012: A project cannot have more than one ApplicationXaml item +``` + +--- + +## Quick Match + +**You're seeing this if:** +- Setting `WindowsAppSDKSelfContained=true` on a library project causes XAML parsing or codegen failures +- Upgrading to WinAppSDK 1.8 causes COMException 0x80070490 (Element not found) related to `.pri` file naming changes +- Build errors include `NETSDK1022` (duplicate items) or `WMC1012` (multiple ApplicationXaml) after upgrading + +→ Check scenarios below for your specific cause + +--- + +## Related Issues + +- [#6091](https://github.com/microsoft/WindowsAppSDK/issues/6091) - Self-contained deployment breaks WinUI codegen in libraries (Status: Closed/Fixed in v2.0-preview1) +- [#5746](https://github.com/microsoft/WindowsAppSDK/issues/5746) - App update to 1.8-preview1 with COMException 0x80070490 errors (Status: Open) + +--- + +## Scenarios & Solutions + +### Scenario 1: WindowsAppSDKSelfContained=true on Library Project Breaks XAML Codegen + +**Cause:** When `WindowsAppSDKSelfContained` is set to `true` in a class library project, the `_OverrideGetPriIndexName` target in `Microsoft.WindowsAppSDK.SelfContained.targets` (part of `Microsoft.WindowsAppSDK.Base` NuGet) sets the PRI root to empty. This is intended for app projects, not libraries, and causes WinUI XAML code generation to fail. The result is a `XamlParseException` at runtime or a silent launch failure. +> Source: @dongle-the-gadget in [#6091](https://github.com/microsoft/WindowsAppSDK/issues/6091) + +**Affected versions:** WinAppSDK 1.8.x (confirmed with 1.8.3 / 1.8.251106002) + +**Fix:** +1. **Remove** `WindowsAppSDKSelfContained` from all library/class library project files. Only set it on the main application (executable) project: + ```xml + + + + + + true + + ``` +2. If setting the property globally via command line (`dotnet msbuild /p:WindowsAppSDKSelfContained=true`), this will apply to all projects in the solution including libraries — avoid this pattern. + +> ✅ Confirmed by: @riverar (CONTRIBUTOR) in [#6091](https://github.com/microsoft/WindowsAppSDK/issues/6091) — removing the property from the library project resolves the issue. + +> @DrusTheAxe (Microsoft) in [#6091](https://github.com/microsoft/WindowsAppSDK/issues/6091) confirmed: "Library projects don't own context. WinAppSDK downlevel regfree WinRT support only applies to the Fusion manifest for the process' EXE." + +**Official fix:** This has been fixed in [Windows App SDK 2.0.0-Preview1](https://github.com/microsoft/WindowsAppSDK/releases/tag/v2.0-preview1) by adding explicit validation that prevents `WindowsAppSDKSelfContained` from being applied to class library projects. +> Source: @ssparach (CONTRIBUTOR) in [#6091](https://github.com/microsoft/WindowsAppSDK/issues/6091) + +**Verify:** Clean the solution, rebuild, and run the app — XAML should parse without exceptions. + +--- + +### Scenario 2: COMException 0x80070490 "Element not found" After Upgrading to 1.8 + +**Cause:** In WinAppSDK 1.8, the `.pri` file naming behavior changed for unpackaged projects. Previously (1.7 and earlier), `EnableMsixTooling=true` caused the `.pri` file to be named `resources.pri` even for unpackaged apps. In 1.8, unpackaged projects correctly use `[AppName].pri` instead. Code that hard-codes `resources.pri` will fail with COMException 0x80070490 ("Element not found") when accessing localized resources. +> Source: @Sella-GH in [#5746](https://github.com/microsoft/WindowsAppSDK/issues/5746), root cause analysis by @DarranRowe + +**Additional build errors on upgrade:** Upgrading to 1.8-preview1 may also cause: +- `NETSDK1022: Duplicate 'PRIResource' items were included` — Fix with `false` +- `NETSDK1022: Duplicate 'Page' items were included` — Fix with `false` +- `WMC1012: A project cannot have more than one ApplicationXaml item` — May require project restructuring + +**Fix for COMException 0x80070490:** +1. Update any code that hard-codes `resources.pri` to use the correct file name. Use the Resource Manager API to determine the default path: + ```csharp + // Instead of hard-coding "resources.pri", use: + var resourceLoader = new Microsoft.Windows.ApplicationModel.Resources.ResourceLoader(); + // The loader will automatically find the correct .pri file + ``` +2. If you have a custom resource loading service, update the file name from `resources.pri` to `[YourAppName].pri`: + ```csharp + // Before (1.7.x): + var priPath = "resources.pri"; + // After (1.8.x, unpackaged): + var priPath = $"{Assembly.GetExecutingAssembly().GetName().Name}.pri"; + ``` + +> ✅ Confirmed by: @Sella-GH in [#5746](https://github.com/microsoft/WindowsAppSDK/issues/5746) — "When I changed the string to match the new name it works completely fine." + +**Fix for duplicate item build errors:** +```xml + + false + false + +``` + +> @DarranRowe provided detailed analysis in [#5746](https://github.com/microsoft/WindowsAppSDK/issues/5746) confirming that the PRI naming in older versions was a bug (unpackaged projects shouldn't have used `resources.pri`), and 1.8 corrects this behavior. + +**Verify:** +```powershell +# Check which .pri files exist in your output directory +Get-ChildItem -Path "" -Filter "*.pri" +# Should show [AppName].pri, Microsoft.WindowsAppRuntime.pri, Microsoft.UI.pri, etc. +``` + +--- + +## ⚠️ Unverified / Community Suggestions + +> The following are community suggestions that have NOT been officially confirmed. + +- If encountering `WMC1012` (multiple ApplicationXaml) after upgrade, try cleaning all `obj` and `bin` directories before rebuilding (general cleanup suggestion related to #5746) +- Avoid setting `WindowsAppSDKSelfContained=true` via `Directory.Build.props` if your solution contains library projects — use per-project settings instead (from community analysis in #6091) + +--- + +## References + +- [Self-contained deployment documentation](https://learn.microsoft.com/en-us/windows/apps/windows-app-sdk/deploy-self-contained) +- [WinAppSDK 2.0.0-Preview1 release notes](https://github.com/microsoft/WindowsAppSDK/releases/tag/v2.0-preview1) +- [Resource management with MRT Core](https://learn.microsoft.com/en-us/windows/apps/windows-app-sdk/mrtcore/mrtcore-overview) + +--- + +**Updated:** 2025-07-18 | **Confidence:** 0.85 +**Sources:** [#6091](https://github.com/microsoft/WindowsAppSDK/issues/6091), [#5746](https://github.com/microsoft/WindowsAppSDK/issues/5746) diff --git a/tsg/tsg_notifications_push_and_listener.md b/tsg/tsg_notifications_push_and_listener.md new file mode 100644 index 0000000..942e837 --- /dev/null +++ b/tsg/tsg_notifications_push_and_listener.md @@ -0,0 +1,182 @@ +# Notification Issues — Push Notifications, Progress Data, and UserNotificationListener + +**Keywords:** AppNotification, push notification, unpackaged, COMException, 0x80070490, Element not found, UserNotificationListener, NotificationChanged, AppNotificationProgressData, IsIndeterminate, indeterminate progress bar, toast notification + +**Error Example:** +``` +System.Runtime.InteropServices.COMException (0x80070490): Element not found + at ABI.WinRT.Interop.EventSource`1.Subscribe(TDelegate handler) + at Windows.UI.Notifications.Management.UserNotificationListener.add_NotificationChanged(...) +``` + +--- + +## Quick Match + +**You're seeing this if:** +- Error contains `0x80070490` ("Element not found") when subscribing to notification events +- Push notifications fail in unpackaged or non-Store apps +- Cannot create an indeterminate progress bar in toast notifications via `AppNotificationProgressData` +- `UserNotificationListener.NotificationChanged` throws `COMException` in unpackaged apps +- Platform: Windows App SDK, WinUI 3, unpackaged or self-contained apps + +→ Check scenarios below for your specific cause + +--- + +## Related Issues + +- [#334](https://github.com/microsoft/WindowsAppSDK/issues/334) — Push Notifications for Unpackaged Apps and Non-Store Apps (Status: Closed — implemented) +- [#2231](https://github.com/microsoft/WindowsAppSDK/issues/2231) — Add IsIndeterminate to AppNotificationProgressData (Status: Open — In PR) +- [#6172](https://github.com/microsoft/WindowsAppSDK/issues/6172) — COMException 0x80070490 when subscribing to UserNotificationListener.NotificationChanged (Status: Open) + +--- + +## Scenarios & Solutions + +### Scenario 1: Push Notifications Not Available for Unpackaged / Non-Store Apps + +**Cause:** Historically, only Microsoft Store-distributed UWP/MSIX packaged apps could use Windows Push Notifications due to an explicit dependency on Store identity. Non-store and unpackaged Win32 apps had no way to use the push notification infrastructure and had to maintain their own socket connections. +> Source: Issue [#334](https://github.com/microsoft/WindowsAppSDK/issues/334) + +**Status:** ✅ **Resolved** — Windows App SDK now supports push notifications for all app types. + +**Supported configurations:** +| Packaging | App Types | +|-----------|-----------| +| ✅ Packaged apps | ✅ WPF, Win32 (C++), WinForms, Console | +| ✅ Unpackaged apps | ⚠️ Cross-platform (Electron, MAUI, React Native) — partial | + +**Fix — Using Push Notifications in Unpackaged Apps:** +1. **Register your app** with Azure Notification Hubs or WNS (Windows Notification Services) using the Windows App SDK push notification APIs. +2. **Use `AppNotificationManager`** for local and push notifications: +```csharp +// Register for push notifications (unpackaged app) +var manager = AppNotificationManager.Default; +manager.NotificationInvoked += OnNotificationInvoked; +manager.Register(); + +// Request a push notification channel +var channelResult = await PushNotificationManager.Default + .CreateChannelAsync(yourAzureAppId); +``` +3. For unpackaged apps, ensure you have the **Windows App SDK Runtime** installed or use a self-contained deployment. +4. Refer to the [Push notifications overview](https://learn.microsoft.com/en-us/windows/apps/windows-app-sdk/notifications/push-notifications/) for Azure setup. + +**Verify:** Send a test push notification and confirm it arrives in your unpackaged app. + +--- + +### Scenario 2: Cannot Set Indeterminate Progress Bar in Toast Notifications + +**Cause:** The `AppNotificationProgressData` API does not expose an `IsIndeterminate` property. In raw XML, setting `value="indeterminate"` on a `` element creates a loading animation, but this behavior cannot be achieved through the `AppNotificationProgressData` class — the `Value` property only accepts `double` values between 0.0 and 1.0. +> Source: Issue [#2231](https://github.com/microsoft/WindowsAppSDK/issues/2231) + +**Status:** 🔄 **In PR** — A fix is being developed (labeled "Status: In PR"). + +**Current limitation:** +```csharp +// This API does NOT support indeterminate state +var progressData = new AppNotificationProgressData(1); +progressData.Value = 0.5; // Only accepts 0.0 - 1.0 +progressData.Status = "Downloading..."; +// No IsIndeterminate property available +``` + +**Workaround — Use raw XML notification:** +```csharp +var xml = @" + + + + Downloading... + + + +"; + +var doc = new Windows.Data.Xml.Dom.XmlDocument(); +doc.LoadXml(xml); +var notification = new ToastNotification(doc); +ToastNotificationManager.CreateToastNotifier().Show(notification); +``` + +Alternatively, use the **Windows Community Toolkit** notification builder which supports indeterminate state: +```csharp +// Using CommunityToolkit.WinUI.Notifications +new ToastContentBuilder() + .AddText("Processing...") + .AddProgressBar(title: "Please wait", status: "Working...", + value: AdaptiveProgressBarValue.Indeterminate) + .Show(); +``` + +**Verify:** Toast notification shows an animated indeterminate progress bar. + +--- + +### Scenario 3: COMException 0x80070490 When Subscribing to UserNotificationListener.NotificationChanged + +**Cause:** In an unpackaged, self-contained WinUI 3 app, subscribing to `UserNotificationListener.NotificationChanged` throws `COMException` with HRESULT `0x80070490` ("Element not found"). Other `UserNotificationListener` APIs work correctly — `UserNotificationListener.Current` is accessible, `RequestAccessAsync()` returns `Allowed`, and `GetNotificationsAsync()` succeeds. Only the event subscription fails. +> Source: Issue [#6172](https://github.com/microsoft/WindowsAppSDK/issues/6172) + +**Affected versions:** Windows App SDK 1.8.4 (1.8.260101001), Windows 11 24H2, unpackaged self-contained apps + +**Repro:** +```csharp +var listener = UserNotificationListener.Current; +var access = await listener.RequestAccessAsync(); // Returns Allowed ✅ +var notifications = await listener.GetNotificationsAsync( + NotificationKinds.Toast); // Works ✅ + +listener.NotificationChanged += Listener_NotificationChanged; // Throws ❌ +// COMException (0x80070490): Element not found +``` + +**Repro project:** https://github.com/koiseka/notificationchangedexample-repro + +**Fix / Workaround:** +1. **Package the app as MSIX** — the `NotificationChanged` event subscription requires package identity to properly register the event handler with the notification platform. +2. **Use polling instead of events** as a workaround for unpackaged apps: +```csharp +// Poll for notification changes every N seconds +var timer = new DispatcherTimer { Interval = TimeSpan.FromSeconds(5) }; +timer.Tick += async (s, e) => +{ + var listener = UserNotificationListener.Current; + var notifications = await listener.GetNotificationsAsync( + NotificationKinds.Toast); + // Compare with previous list to detect changes + ProcessNotificationChanges(notifications); +}; +timer.Start(); +``` +3. If MSIX packaging is an option, add package identity using [Sparse Package](https://learn.microsoft.com/en-us/windows/apps/desktop/modernize/grant-identity-to-nonpackaged-apps) to enable event registration without full MSIX deployment. + +> ⚠️ This is an open issue. The `NotificationChanged` event does not support unpackaged apps. + +**Verify:** Confirm that `NotificationChanged` fires after packaging the app, or that the polling approach correctly detects notification changes. + +--- + +## ⚠️ Unverified / Community Suggestions + +> The following are community suggestions that have NOT been officially confirmed. + +- For #6172: Granting identity via External Location registration (`AddPackageByUriAsync` with `ExternalLocationUri`) may enable event subscription without full MSIX packaging, but this has not been tested with `UserNotificationListener`. +- For #2231: Until the official `IsIndeterminate` API ships, the raw XML approach is the most reliable workaround for indeterminate progress bars in toast notifications. + +--- + +## References + +- [Push notifications overview — Windows App SDK](https://learn.microsoft.com/en-us/windows/apps/windows-app-sdk/notifications/push-notifications/) +- [App notifications overview — Windows App SDK](https://learn.microsoft.com/en-us/windows/apps/windows-app-sdk/notifications/app-notifications/) +- [Toast content XML schema — progress element](https://learn.microsoft.com/en-us/windows/apps/design/shell/tiles-and-notifications/toast-schema#adaptiveprogressbarvalue) +- [UserNotificationListener API](https://learn.microsoft.com/en-us/uwp/api/windows.ui.notifications.management.usernotificationlistener) +- [Grant identity to non-packaged apps (Sparse Package)](https://learn.microsoft.com/en-us/windows/apps/desktop/modernize/grant-identity-to-nonpackaged-apps) + +--- + +**Updated:** 2025-07-17 | **Confidence:** 0.7 +**Sources:** #334, #2231, #6172 diff --git a/tsg/tsg_resources_mrt_localization.md b/tsg/tsg_resources_mrt_localization.md new file mode 100644 index 0000000..9ce5cfa --- /dev/null +++ b/tsg/tsg_resources_mrt_localization.md @@ -0,0 +1,151 @@ +# Error: "COMException: NamedResource Not Found" / PrimaryLanguageOverride Not Working — MRT Resource Loading + +**Keywords:** ResourceLoader, GetString, COMException, NamedResource Not Found, PrimaryLanguageOverride, unpackaged, localization, x:Uid, MRTCore, Resources.resw, dot in key, signing projection + +**Error Example:** +``` +COMException: NamedResource Not Found. +``` +``` +COMException: No such interface supported +``` + +--- + +## Quick Match + +**You're seeing this if:** +- `ResourceLoader.GetString()` throws `COMException` for keys containing `.` (dots) +- `PrimaryLanguageOverride` does not work in unpackaged WinUI 3 apps +- `x:Uid` XAML localization fails for unpackaged apps +- Signing `Microsoft.Windows.ApplicationModel.Resources.Projection` fails during build + +→ Check scenarios below for your specific cause + +--- + +## Related Issues + +- [#6247](https://github.com/microsoft/WindowsAppSDK/issues/6247) — ResourceLoader.GetString throws COMException for keys containing '.' (Status: Open) +- [#1687](https://github.com/microsoft/WindowsAppSDK/issues/1687) — Support PrimaryLanguageOverride from unpackaged apps (Status: Closed/Fixed in 1.6-experimental2) +- [#3705](https://github.com/microsoft/WindowsAppSDK/issues/3705) — Signing Resources.Projection fails with ilasm errors (Status: Closed) + +--- + +## Scenarios & Solutions + +### Scenario 1: ResourceLoader.GetString Fails for Keys Containing Dots + +**Cause:** Resource keys that contain `.` (period/dot) characters are not resolved correctly by `ResourceLoader.GetString()`. The MRT/PRI key normalization or URI fragment semantics treat `.` as a path separator, causing the lookup to fail with `NamedResource Not Found`. +> Source: Issue reporter in [#6247](https://github.com/microsoft/WindowsAppSDK/issues/6247) + +**Example:** +```csharp +// FAILS — throws COMException: NamedResource Not Found +var loader = new ResourceLoader(); +var value = loader.GetString("XXXXX.Common.Yes"); + +// WORKS — returns expected value +var value = loader.GetString("XXXXX_Common_Yes"); +``` + +**Fix:** +Replace `.` with `_` in resource key names in your `Resources.resw` file and update all code references accordingly. + +| Before | After | +|--------|-------| +| `XXXXX.Common.Yes` | `XXXXX_Common_Yes` | +| `App.Settings.Title` | `App_Settings_Title` | + +> ⚠️ No official confirmation on whether `.` is a supported character in resource keys for `ResourceLoader.GetString`. The issue is open and under investigation. + +**Verify:** +```csharp +var loader = new ResourceLoader(); +var value = loader.GetString("XXXXX_Common_Yes"); +Debug.Assert(value == "Yes"); +``` + +--- + +### Scenario 2: PrimaryLanguageOverride Not Working in Unpackaged Apps + +**Cause:** `Windows.Globalization.ApplicationLanguages.PrimaryLanguageOverride` was designed for packaged apps only. Calling it from an unpackaged context threw an error, breaking `x:Uid` XAML localization for unpackaged WinUI 3 apps. +> Source: @btueffers (CONTRIBUTOR) and @andrewleader (CONTRIBUTOR) in [#1687](https://github.com/microsoft/WindowsAppSDK/issues/1687) + +**Fix (WASDK 1.6+ experimental and later):** +Use the new WinAppSDK-specific API instead of the Windows.Globalization API: +```csharp +// Use this (WinAppSDK API — works for both packaged and unpackaged): +Microsoft.Windows.Globalization.ApplicationLanguages.PrimaryLanguageOverride = "en-US"; + +// Instead of this (Windows platform API — packaged only): +Windows.Globalization.ApplicationLanguages.PrimaryLanguageOverride = "en-US"; +``` + +> ✅ Confirmed working by: @ghost1372 (CONTRIBUTOR) in [#1687](https://github.com/microsoft/WindowsAppSDK/issues/1687) — tested in 1.6.240701003-experimental2 + +**Pre-fix workaround (for older WASDK versions):** +Use `ResourceContext` directly and set the `Language` qualifier value: +```csharp +var context = new ResourceContext(); +context.QualifierValues["Language"] = "en-US"; +// Pass this context to resource lookups +``` +> Source: @huichen123 (CONTRIBUTOR) in [#1687](https://github.com/microsoft/WindowsAppSDK/issues/1687) + +**Community alternative:** +The [WinUI3Localizer](https://www.nuget.org/packages/WinUI3Localizer/) NuGet package works with unpackaged apps and uses standard `Resources.resw` strings. +> Source: @AndrewKeepCoding in [#1687](https://github.com/microsoft/WindowsAppSDK/issues/1687) + +--- + +### Scenario 3: COMException During First Use of PrimaryLanguageOverride (Unpackaged) + +**Cause:** Even after upgrading to a WASDK version with the fix, some users encountered `COMException: No such interface supported` when first using `PrimaryLanguageOverride` in unpackaged apps. +> Source: @TheVoidSeeker in [#1687](https://github.com/microsoft/WindowsAppSDK/issues/1687) + +**Fix:** +1. Repair your Visual Studio installation. +2. Clean all intermediate and output files (`bin/`, `obj/`). +3. Rebuild the project. + +> ✅ Confirmed by: @TheVoidSeeker in [#1687](https://github.com/microsoft/WindowsAppSDK/issues/1687) — resolved after VS repair + clean rebuild + +--- + +### Scenario 4: Signing Microsoft.Windows.ApplicationModel.Resources.Projection Fails + +**Cause:** When using code analyzers configured for assembly signing, attempting to sign the `Microsoft.Windows.ApplicationModel.Resources.Projection` assembly via `ildasm`/`ilasm` round-trip fails. The assembly contains non-standard IL patterns (non-virtual instance methods in interfaces) that `ilasm` rejects. +> Source: Issue reporter in [#3705](https://github.com/microsoft/WindowsAppSDK/issues/3705) + +**Error:** +``` +error : Method cannot have body if it is non-static declared in interface abstract +error : Non-public instance method in interface +``` + +**Fix:** WASDK 1.3 has reached End of Support. Upgrade to WASDK 1.8 or later where this may be resolved. If the issue persists on 1.8+, file a new issue. +> Source: @alexlamtest (CONTRIBUTOR) in [#3705](https://github.com/microsoft/WindowsAppSDK/issues/3705) + +--- + +## ⚠️ Unverified / Community Suggestions + +> The following are community suggestions that have NOT been officially confirmed. + +- XAML Islands (non-WinUI 3) apps using `Windows.Globalization.ApplicationLanguages.PrimaryLanguageOverride` still do not work without packaging; WASDK fix only covers MRTCore-based scenarios (from @sylveon in #1687) +- On WASDK 1.8, `PrimaryLanguageOverride` value may not persist across app relaunch — see Known Issue #6118 (from @Galebra in #1687) + +--- + +## References + +- [ResourceLoader.GetString API docs](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.windows.applicationmodel.resources.resourceloader.getstring) +- [MRTCore ResourceContext source](https://github.com/microsoft/WindowsAppSDK/blob/main/dev/MRTCore/mrt/Microsoft.Windows.ApplicationModel.Resources/src/ResourceContext.cpp) +- [WinUI3Localizer NuGet](https://www.nuget.org/packages/WinUI3Localizer/) + +--- + +**Updated:** 2026-03-13 | **Confidence:** 0.8 +**Sources:** #6247, #1687, #3705 diff --git a/tsg/tsg_runtime_winrt_interop.md b/tsg/tsg_runtime_winrt_interop.md new file mode 100644 index 0000000..7d65cbf --- /dev/null +++ b/tsg/tsg_runtime_winrt_interop.md @@ -0,0 +1,199 @@ +# WinRT Interop, AOT Compatibility & Runtime Version Issues - Windows App SDK + +**Keywords:** AOT, trimming, FrameworkElement, theme, LaunchActivatedEventArgs, WinRT, CsWinRT, IInspectable, ReleaseInfo, version string, HDR, CompositionDrawingSurface, scRGB, swap chain, DirectXPixelFormat + +**Error Example:** +``` +// AOT theme switching failure +(Window.Content as FrameworkElement) returns null when published with AOT + +// LaunchActivatedEventArgs interop +AppActivationArguments.Data shows as WinRT.IInspectable instead of LaunchActivatedEventArgs + +// ReleaseInfo version mismatch +ReleaseInfo.AsString returns "1.7.0" on WinAppSDK 1.7.1 runtime + +// HDR composition +CompositionDrawingSurface with R16G16B16A16Float renders as SDR in WinAppSDK +``` + +--- + +## Quick Match + +**You're seeing this if:** +- Theme switching code fails silently when app is published with Native AOT +- `Window.Content as FrameworkElement` returns `null` in AOT builds +- `AppActivationArguments.Data` is `WinRT.IInspectable` instead of a typed activation args object +- `ReleaseInfo.AsString` returns wrong version (e.g., "1.7.0" on 1.7.1) +- HDR content renders as SDR when using `CompositionDrawingSurface` with float16 pixel format + +→ Check scenarios below for your specific cause + +--- + +## Related Issues + +- [#5389](https://github.com/microsoft/WindowsAppSDK/issues/5389) - Unable to change theme color when AOT is released (Status: Closed, area-AOT) +- [#6219](https://github.com/microsoft/WindowsAppSDK/issues/6219) - WASDK LaunchActivatedEventArgs cannot be directly converted into WinRT (Status: Open, area-Projections) +- [#5323](https://github.com/microsoft/WindowsAppSDK/issues/5323) - ReleaseInfo returns "1.7.0" in 1.7.1 release (Status: Closed, area-VersionInfo) +- [#6291](https://github.com/microsoft/WindowsAppSDK/issues/6291) - Unlike UWP, WindowsAppSdk does not support HDR composition (Status: Closed) + +--- + +## Scenarios & Solutions + +### Scenario 1: Theme Switching Fails Under Native AOT (Trimming) + +**Cause:** When publishing a WinUI app with Native AOT, the .NET trimmer removes `FrameworkElement` because the C# code doesn't directly construct it. As a result, `Window.Content as FrameworkElement` returns `null`, and theme switching code silently fails. The `as` operator cannot succeed because the type metadata has been trimmed. +> Source: @manodasanW (MEMBER) in [#5389](https://github.com/microsoft/WindowsAppSDK/issues/5389) + +**Fix:** +1. Upgrade to [CsWinRT 2.3 previews](https://www.nuget.org/packages/Microsoft.Windows.CsWinRT/2.3.0-prerelease.251115.2) or later +2. Add the `[DynamicWindowsRuntimeCast]` attribute to the method performing the cast, passing `typeof(FrameworkElement)`: +```csharp +[DynamicWindowsRuntimeCast(typeof(FrameworkElement))] +private void SetTheme(ApplicationTheme theme) +{ + if (Window.Content is FrameworkElement rootElement) + { + rootElement.RequestedTheme = theme == ApplicationTheme.Dark + ? ElementTheme.Dark + : ElementTheme.Light; + } +} +``` +3. Enable AOT diagnostics to catch similar issues by setting `CsWinRTAotWarningLevel` to `3` in your project file: +```xml + + 3 + +``` +4. The diagnostics include a code fix that should help identify all such scenarios where types may be trimmed + +> ✅ Confirmed by: @manodasanW (Microsoft, MEMBER) in #5389 comments + +**Verify:** Publish with AOT and confirm `Window.Content as FrameworkElement` returns a non-null value. + +**Environment:** +- WinAppSDK 1.7.1 (1.7.250401001) +- Packaged (MSIX) and Unpackaged +- Windows 11 24H2 +- Visual Studio 2022-preview + +--- + +### Scenario 2: WASDK LaunchActivatedEventArgs Not Convertible to WinRT Type + +**Cause:** When `AppInstance.GetActivatedEventArgs()` is called in WASDK, it first tries `WinRT's AppInstance.GetActivatedEventArgs()`. If that returns null, WASDK falls back to its own custom implementation of `LaunchActivatedEventArgs`. The returned object is WASDK's custom type, not the WinRT `LaunchActivatedEventArgs`. On the .NET side, CsWinRT cannot recognize WASDK's custom implementation, so `AppActivationArguments.Data` appears as `WinRT.IInspectable` instead of the expected typed object. +> Source: Issue author in [#6219](https://github.com/microsoft/WindowsAppSDK/issues/6219) + +**Workaround:** +1. Use `LaunchActivatedEventArgs.FromAbi()` to manually unwrap the inspectable pointer: +```csharp +var activatedArgs = AppInstance.GetCurrent().GetActivatedEventArgs(); +if (activatedArgs.Kind == ExtendedActivationKind.Launch) +{ + // Data is WinRT.IInspectable, need manual conversion + var inspectable = activatedArgs.Data as IInspectable; + if (inspectable != null) + { + var launchArgs = LaunchActivatedEventArgs.FromAbi(inspectable.ThisPtr); + string arguments = launchArgs.Arguments; + } +} +``` +2. This is a known interop gap — WASDK team has been asked to add a wrapping layer so the returned object is recognized as `WinRT.LaunchActivatedEventArgs` by CsWinRT + +**Status:** Open — no official fix yet. The request is for WASDK to wrap its custom implementation so .NET CsWinRT can recognize it correctly. + +**Environment:** +- WinAppSDK 1.8.5 (1.8.260209005) +- Packaged (MSIX) +- Windows 11 24H2 LTSC (26100) + +--- + +### Scenario 3: ReleaseInfo.AsString Returns Wrong Patch Version + +**Cause:** `Microsoft.Windows.ApplicationModel.WindowsAppRuntime.ReleaseInfo.AsString` returns "1.7.0" even when running on the 1.7.1 runtime. The `Patch` property on `ReleaseInfo` also incorrectly returns `0`. Meanwhile, `RuntimeInfo.Version` correctly reports the full version (e.g., `7000.456.1632.0`). +> Source: Issue author in [#5323](https://github.com/microsoft/WindowsAppSDK/issues/5323) + +**Workaround:** +1. Use `RuntimeInfo.Version` instead of `ReleaseInfo.AsString` for accurate version detection: +```csharp +// Unreliable in 1.7.x: +var releaseStr = ReleaseInfo.AsString; // Returns "1.7.0" even on 1.7.1 + +// Reliable alternative: +var runtimeVersion = RuntimeInfo.Version; // Returns correct version like 7000.456.1632.0 +``` +2. This was a known bug in the 1.7.x release train. Check whether the issue is resolved in your target SDK version + +> ✅ Fix confirmed: Issue is closed, indicating the bug has been addressed in subsequent releases + +**Verify:** +```csharp +Debug.WriteLine($"ReleaseInfo: {ReleaseInfo.AsString}"); +Debug.WriteLine($"RuntimeInfo: {RuntimeInfo.Version}"); +``` + +**Environment:** +- WinAppSDK 1.7.1 (1.7.250401001) +- Packaged (MSIX) +- Windows 11 24H2 + +--- + +### Scenario 4: HDR Composition Not Supported in WinAppSDK (UWP Parity Gap) + +**Cause:** In UWP, creating a `CompositionDrawingSurface` with pixel format `DirectXPixelFormat.R16G16B16A16Float` enables HDR composition — the floating-point content is passed to the system compositor, which can display values outside [0,1]. In WinAppSDK, the same code does not produce HDR output. The surface appears to undergo a simple scRGB-to-sRGB gamma correction and renders as SDR. This suggests WinAppSDK may be composing to an 8-bit swap chain rather than a 16-bit floating-point swap chain. +> Source: Issue author in [#6291](https://github.com/microsoft/WindowsAppSDK/issues/6291) + +**Symptoms:** +- `CompositionDrawingSurface` created with `R16G16B16A16Float` renders identically to SDR +- Values > 1.0 in HDR content do not appear brighter than SDR maximum +- SDR content is not dimmer (no SDR white level scaling at display's SDR white level / 80 nits) +- Photo viewing or media apps cannot display HDR content correctly in WinAppSDK + +**Reproduction code summary:** +```csharp +// This produces HDR in UWP but SDR in WinAppSDK +var surface = compositionDevice.CreateDrawingSurface( + pixelSize, + DirectXPixelFormat.R16G16B16A16Float, + DirectXAlphaMode.Premultiplied); + +// Drawing HDR values > 1.0 should be brighter than SDR max +ds.FillRectangle(rect, CanvasSolidColorBrush.CreateHdr(device, new Vector4(5, 5, 5, 1))); +``` + +**Status:** Closed — but no confirmed workaround for achieving HDR composition in WinAppSDK was provided. This represents a UWP-to-WinAppSDK migration blocker for HDR content applications. + +**Workaround (limited):** +1. For HDR content display, consider maintaining a UWP component or using DirectX interop with a custom swap chain +2. Monitor WinAppSDK releases for HDR composition support +3. No pure WinUI/Composition API workaround is currently available + +--- + +## ⚠️ Unverified / Community Suggestions + +> The following are community suggestions that have NOT been officially confirmed. + +- For HDR (#6291): Using a custom DirectComposition swap chain with `DXGI_FORMAT_R16G16B16A16_FLOAT` created outside of WinUI's compositor may enable HDR rendering, but this bypasses the WinUI composition tree (not confirmed) +- For AOT (#5389): Some developers report that adding `[DynamicallyAccessedMembers]` attributes on certain types can also prevent trimming, though the `DynamicWindowsRuntimeCast` approach from @manodasanW is the recommended solution + +--- + +## References + +- [CsWinRT 2.3 Preview - NuGet](https://www.nuget.org/packages/Microsoft.Windows.CsWinRT/2.3.0-prerelease.251115.2) +- [DynamicWindowsRuntimeCast example - CsWinRT repo](https://github.com/microsoft/CsWinRT/blob/4475bb0d5a795bea964b4ce3db5db860233e7ba2/src/Tests/FunctionalTests/JsonValueFunctionCalls/Program.cs#L26) +- [WinAppSDK ReleaseInfo API](https://learn.microsoft.com/en-us/windows/windows-app-sdk/api/winrt/microsoft.windows.applicationmodel.windowsappruntime.releaseinfo) +- [HDR and Advanced Color in Windows](https://learn.microsoft.com/en-us/windows/win32/direct3darticles/high-dynamic-range) + +--- + +**Updated:** 2025-07-17 | **Confidence:** 0.7 +**Sources:** #5389, #6219, #5323, #6291, CsWinRT documentation diff --git a/tsg/tsg_widgets_customization_display.md b/tsg/tsg_widgets_customization_display.md new file mode 100644 index 0000000..f454986 --- /dev/null +++ b/tsg/tsg_widgets_customization_display.md @@ -0,0 +1,121 @@ +# Widget Customization and Display Failures - Windows Widgets Platform + +**Keywords:** widget customization, template JSON, OnCustomizationRequested, widget board, add widget, widget list, Widgets panel + +**Error Example:** +``` +Widget customization card grows but template does not render. +OnCustomizationRequested callback never gets executed. +Widget "Add" button remains grayed out / inactive for first item in list. +``` + +--- + +## Quick Match + +**You're seeing this if:** +- Widget customization panel opens but shows no content +- `OnCustomizationRequested` callback is never invoked by widget host +- First widget in alphabetical list cannot be added to widget board +- Widget "Add" button stays inactive until switching to another widget and back + +→ Check scenarios below for your specific cause + +--- + +## Related Issues + +- [#3926](https://github.com/microsoft/WindowsAppSDK/issues/3926) - Widget Customization does not show template JSON (Status: Closed, area-Widgets) +- [#6140](https://github.com/microsoft/WindowsAppSDK/issues/6140) - Widget at top of list cannot be added until switching away and back (Status: Open, area-External) + +--- + +## Scenarios & Solutions + +### Scenario 1: Widget Customization Template Not Rendering + +**Cause:** When selecting "✏️ Customize Widget" on a widget provider, the customization card area grows/expands but the customization template JSON is never displayed. Debugging reveals that the `OnCustomizationRequested` callback is never executed by the widget host. This means the Windows Widget host is not properly invoking the customization flow defined in the widget provider. +> Source: Issue author in [#3926](https://github.com/microsoft/WindowsAppSDK/issues/3926) + +**Symptoms:** +- Following the official Microsoft documentation for [Implementing widget customization](https://learn.microsoft.com/en-us/windows/apps/develop/widgets/implement-widget-provider-cs#implementing-widget-customization) +- The customization card area expands when "Customize Widget" is selected +- The `OnCustomizationRequested` callback in the widget provider code is never triggered +- No template JSON content is rendered in the customization area + +**Steps to reproduce:** +1. Implement a widget provider following the official Microsoft Learning documentation for widget customization +2. Register and deploy the widget +3. Open the Widgets panel and select "✏️ Customize Widget" +4. Observe: the card grows but no customization template appears + +**Fix:** +1. Verify your widget provider correctly implements the `IWidgetProvider2` interface which includes `OnCustomizationRequested` +2. Ensure your widget manifest declares customization support correctly +3. Confirm the widget host version supports the customization API — this issue was observed with WinAppSDK 1.4-era widget platform +4. Check that you are returning a valid Adaptive Card JSON template from your customization handler +5. If the callback is still not invoked, this may be a platform-level bug in the Widget host. Monitor the issue for updates from Microsoft + +**Environment:** +- Reported against the widget platform with WinAppSDK widget provider APIs +- Behavior observed in Windows 11 widget board + +**Verify:** +Confirm `OnCustomizationRequested` is hit by adding a breakpoint or debug log: +```csharp +public void OnCustomizationRequested(WidgetCustomizationRequestedArgs args) +{ + Debug.WriteLine($"Customization requested for widget: {args.WidgetContext.Id}"); + // Return your customization template JSON +} +``` + +--- + +### Scenario 2: First Widget in Alphabetical List Cannot Be Added + +**Cause:** On Windows 11 25H2 (Build 26220.7535), when a widget whose name starts with the letter "A" appears at the very top of the widget list, the "Add" button remains grayed out / inactive. The widget can only be added after switching to a different widget and then switching back. This is a UI state initialization bug in the Windows Widgets Board panel. +> Source: Issue author in [#6140](https://github.com/microsoft/WindowsAppSDK/issues/6140) + +**Steps to reproduce:** +1. Open the Widgets panel on Windows 11 25H2 +2. Click the "+" button to add a new widget +3. The first widget in the list (alphabetically, starting with "A") is automatically selected +4. Attempt to add the widget — the Add button stays gray/inactive +5. Select a different widget in the list +6. Return to the original widget +7. Now the Add button becomes active and the widget can be added + +**Fix:** +1. This is a Windows Widgets Board platform bug (labeled `area-External`), not a widget provider issue +2. **User workaround:** Select any other widget in the list first, then switch back to the desired widget — the Add button will activate +3. **Developer impact:** If your widget name starts with "A" or appears first alphabetically, users may report inability to add it. Document this workaround in your widget's support materials +4. No code-level fix is available on the widget provider side — this requires a platform fix from Microsoft + +**Environment:** +- OS: Windows 11 25H2 (Build 26220.7535) +- Widget Platform: Windows Widgets Board +- Reproducibility: Always + +--- + +## ⚠️ Unverified / Community Suggestions + +> The following are community suggestions that have NOT been officially confirmed. + +- For Scenario 1: Ensure your widget provider DLL is correctly registered and the COM server is running. Some developers report that re-registering the package resolves callback issues (community reports, not confirmed in #3926) +- For Scenario 2: Renaming your widget to not start with "A" is a theoretical workaround, but this should not be necessary and the platform bug should be fixed (from #6140 discussion) + +--- + +## References + +- [Implementing Widget Customization - Microsoft Learn](https://learn.microsoft.com/en-us/windows/apps/develop/widgets/implement-widget-provider-cs#implementing-widget-customization) +- [Widget Provider Development - Microsoft Learn](https://learn.microsoft.com/en-us/windows/apps/develop/widgets/) +- [#3926 - Widget Customization does not show template JSON](https://github.com/microsoft/WindowsAppSDK/issues/3926) +- [#6140 - Widget at top of list cannot be added](https://github.com/microsoft/WindowsAppSDK/issues/6140) + +--- + +**Updated:** 2025-07-17 | **Confidence:** 0.6 +**Sources:** #3926, #6140, Microsoft Learn widget documentation From ee20b68216a7bb8d041a272da167718f4b96f0a7 Mon Sep 17 00:00:00 2001 From: Qiutong Shen Date: Tue, 17 Mar 2026 13:11:21 +0800 Subject: [PATCH 2/7] update tsg for recent issues --- .../tsg_activation_and_rpc_errors.md | 116 +++++ .../tsg_api_gaps_unpackaged_support.md | 421 ++++++++-------- .../tsg_appcontainer_identity_sharing.md | 306 ++++++------ .../tsg_appcontainer_partial_trust.md | 70 +++ .../tsg_background_tasks_printing_tooling.md | 465 +++++++++--------- .../tsg_cppwinrt_template_compile_failures.md | 105 ++++ .../tsg_cursor_aot_errors.md | 109 ++++ .../tsg_deployment_singlefile_installer.md | 347 +++++++------ .../tsg_deployment_wasdk18_windows10.md | 370 +++++++------- .../tsg_documentation_and_templates.md | 167 +++++++ .../tsg_documentation_gaps.md | 103 ++++ .../tsg_dynamic_dependencies_ci.md | 72 +++ .../tsg_external_interop_issues.md | 405 ++++++++------- .../tsg_file_access_storage_pickers.md | 381 +++++++------- .../tsg_msix_build_publish_output_failures.md | 354 ++++++------- .../tsg_msix_project_configuration_tooling.md | 197 ++++++++ ..._msix_selfcontained_packaging_conflicts.md | 270 +++++----- .../tsg_notifications_push_and_listener.md | 361 +++++++------- .../tsg_resources_mrt_localization.md | 344 +++++++------ .../tsg_runtime_missing_dependencies.md | 66 +++ .../tsg_runtime_winrt_interop.md | 151 ++++++ .../tsg_touch_events_applicationdata.md | 75 +++ .../tsg_webview2_and_sdk_integration.md | 83 ++++ .../tsg_widgets_customization_display.md | 242 ++++----- .../tsg_winml_aot_issues.md | 82 +++ tsg/tsg_msix_project_configuration_tooling.md | 150 ------ tsg/tsg_runtime_winrt_interop.md | 199 -------- 27 files changed, 3595 insertions(+), 2416 deletions(-) create mode 100644 trouble-shooting-notes/tsg_activation_and_rpc_errors.md rename {tsg => trouble-shooting-notes}/tsg_api_gaps_unpackaged_support.md (87%) rename {tsg => trouble-shooting-notes}/tsg_appcontainer_identity_sharing.md (98%) create mode 100644 trouble-shooting-notes/tsg_appcontainer_partial_trust.md rename {tsg => trouble-shooting-notes}/tsg_background_tasks_printing_tooling.md (88%) create mode 100644 trouble-shooting-notes/tsg_cppwinrt_template_compile_failures.md create mode 100644 trouble-shooting-notes/tsg_cursor_aot_errors.md rename {tsg => trouble-shooting-notes}/tsg_deployment_singlefile_installer.md (78%) rename {tsg => trouble-shooting-notes}/tsg_deployment_wasdk18_windows10.md (78%) create mode 100644 trouble-shooting-notes/tsg_documentation_and_templates.md create mode 100644 trouble-shooting-notes/tsg_documentation_gaps.md create mode 100644 trouble-shooting-notes/tsg_dynamic_dependencies_ci.md rename {tsg => trouble-shooting-notes}/tsg_external_interop_issues.md (84%) rename {tsg => trouble-shooting-notes}/tsg_file_access_storage_pickers.md (52%) rename {tsg => trouble-shooting-notes}/tsg_msix_build_publish_output_failures.md (86%) create mode 100644 trouble-shooting-notes/tsg_msix_project_configuration_tooling.md rename {tsg => trouble-shooting-notes}/tsg_msix_selfcontained_packaging_conflicts.md (55%) rename {tsg => trouble-shooting-notes}/tsg_notifications_push_and_listener.md (77%) rename {tsg => trouble-shooting-notes}/tsg_resources_mrt_localization.md (62%) create mode 100644 trouble-shooting-notes/tsg_runtime_missing_dependencies.md create mode 100644 trouble-shooting-notes/tsg_runtime_winrt_interop.md create mode 100644 trouble-shooting-notes/tsg_touch_events_applicationdata.md create mode 100644 trouble-shooting-notes/tsg_webview2_and_sdk_integration.md rename {tsg => trouble-shooting-notes}/tsg_widgets_customization_display.md (98%) create mode 100644 trouble-shooting-notes/tsg_winml_aot_issues.md delete mode 100644 tsg/tsg_msix_project_configuration_tooling.md delete mode 100644 tsg/tsg_runtime_winrt_interop.md diff --git a/trouble-shooting-notes/tsg_activation_and_rpc_errors.md b/trouble-shooting-notes/tsg_activation_and_rpc_errors.md new file mode 100644 index 0000000..7564f3d --- /dev/null +++ b/trouble-shooting-notes/tsg_activation_and_rpc_errors.md @@ -0,0 +1,116 @@ +# Error: "The RPC server is unavailable" (System.Runtime.InteropServices.COMException) - AppInstance.GetActivatedEventArgs() + +**Keywords:** RPC server is unavailable, System.Runtime.InteropServices.COMException, AppInstance.GetActivatedEventArgs, activation arguments, WinUI3, Windows.ApplicationModel.AppInstance + +**Error Example:** +``` +System.Runtime.InteropServices.COMException: 'The RPC server is unavailable.' +``` + +--- + +## Quick Match + +**You're seeing this if:** +- Error contains "The RPC server is unavailable" +- Calling `AppInstance.GetCurrent().GetActivatedEventArgs()` in a WinUI3 app +- Platform: Windows, Packaged (MSIX) + +→ Check scenarios below for your specific cause + +--- + +## Related Issues + +- [#5481](https://github.com/microsoft/WindowsAppSDK/issues/5481) - Exception triggered when calling `AppInstance.GetCurrent().GetActivatedEventArgs()` (Status: Open) + +--- + +## Scenarios & Solutions + +### Scenario 1: Activation arguments lifetime tied to the calling process + +**Cause:** The activation arguments object is created in the calling process and is only available while that process is running. If the calling process terminates too quickly, the activation arguments become unavailable. +> Source: @florelis [MSFT] in [#5481](https://github.com/microsoft/WindowsAppSDK/issues/5481) + +**Fix:** +1. Add a delay to extend the lifetime of the calling process. +2. For example, in the console application, add a `Thread.Sleep()` after `Process.Start()` to keep the process alive longer. + +> ✅ Confirmed by: @florelis [MSFT] in issue comments + +**Verify:** Add a `Thread.Sleep()` in the console application and observe if the error no longer occurs. + +--- + +### Scenario 2: Use Win32 APIs to retrieve activation parameters + +**Cause:** The `AppInstance.GetCurrent().GetActivatedEventArgs()` method may not work reliably in certain scenarios, such as when called from a non-UWP packaged app. +> Source: @lgBlog in [#5481](https://github.com/microsoft/WindowsAppSDK/issues/5481) + +**Fix:** +1. Use the following Win32 APIs to retrieve activation parameters directly: + - `GetCommandLineW` + - `CommandLineToArgvW` + - `LocalFree` +2. Example implementation: + ```csharp + [DllImport("kernel32.dll", CharSet = CharSet.Unicode)] + private static extern IntPtr GetCommandLineW(); + + [DllImport("shell32.dll", SetLastError = true, CharSet = CharSet.Unicode)] + private static extern IntPtr CommandLineToArgvW([MarshalAs(UnmanagedType.LPWStr)] string lpCmdLine, out int pNumArgs); + + [DllImport("kernel32.dll")] + private static extern IntPtr LocalFree(IntPtr hMem); + + private List Win32GetActivationFiles() + { + var files = new List(4); + + IntPtr ptr = GetCommandLineW(); + string cmdLine = Marshal.PtrToStringUni(ptr) ?? string.Empty; + + if (string.IsNullOrEmpty(cmdLine)) + return files; + + IntPtr argv = CommandLineToArgvW(cmdLine, out int argc); + if (argv == IntPtr.Zero) + return files; + + try + { + for (int i = 0; i < argc; i++) + { + string arg = Marshal.PtrToStringUni(Marshal.ReadIntPtr(argv, i * IntPtr.Size)) ?? string.Empty; + files.Add(arg); + } + } + finally + { + LocalFree(argv); + } + + return files; + } + ``` + +--- + +## ⚠️ Unverified / Community Suggestions + +> The following are community suggestions that have NOT been officially confirmed. + +- None provided. + +--- + +## References + +- [Issue #5481](https://github.com/microsoft/WindowsAppSDK/issues/5481) +- [AppInstance.GetActivatedEventArgs() documentation](https://learn.microsoft.com/en-us/windows/apps/windows-app-sdk/api/winrt/microsoft.windows.applicationsmodel.appinstance.getactivatedeventargs) + +--- + +**Updated:** 2026-03-17 | **Confidence:** 0.9 +**Sources:** [#5481](https://github.com/microsoft/WindowsAppSDK/issues/5481) \ No newline at end of file diff --git a/tsg/tsg_api_gaps_unpackaged_support.md b/trouble-shooting-notes/tsg_api_gaps_unpackaged_support.md similarity index 87% rename from tsg/tsg_api_gaps_unpackaged_support.md rename to trouble-shooting-notes/tsg_api_gaps_unpackaged_support.md index 77d371e..4a4631c 100644 --- a/tsg/tsg_api_gaps_unpackaged_support.md +++ b/trouble-shooting-notes/tsg_api_gaps_unpackaged_support.md @@ -1,202 +1,219 @@ -# API Gaps: Unpackaged App Support, Storage & Package Management - Windows App SDK - -**Keywords:** ApplicationData, unpackaged, AppInfo, package identity, StorageFolder, PackageVolume, FindPackage, content type, file handler, file association, manifest, LOCALAPPDATA - -**Error Example:** -``` -// ApplicationData.Current fails for unpackaged apps -Windows.Storage.ApplicationData.Current → throws (no package identity) - -// AppInfo unavailable for unpackaged -Windows.ApplicationModel.AppInfo → only works for packaged apps - -// PackageVolume missing APIs -PackageVolume.FindPackages() → method not available in WASDK PackageVolume - -// File handler declaration limitation -Can only declare file type extensions in manifest, not MIME content types -``` - ---- - -## Quick Match - -**You're seeing this if:** -- `ApplicationData.Current` fails in an unpackaged (non-MSIX) app -- Need app metadata (display name, icon, etc.) in an unpackaged app -- WASDK `PackageVolume` is missing `FindPackage`-related APIs available in the platform type -- Want to register as a default file handler by MIME content type instead of individual file extensions - -→ Check scenarios below for your specific cause - ---- - -## Related Issues - -- [#2639](https://github.com/microsoft/WindowsAppSDK/issues/2639) - Microsoft.Storage.ApplicationData proposal (Status: Open, In PR, area-ApplicationData) -- [#1083](https://github.com/microsoft/WindowsAppSDK/issues/1083) - AppInfo class for unpackaged apps (Status: Closed, feature proposal) -- [#27](https://github.com/microsoft/WindowsAppSDK/issues/27) - Specifying as default file handler with content type instead of filetype (Status: Open, area-Activation, feature proposal) -- [#6222](https://github.com/microsoft/WindowsAppSDK/issues/6222) - WASDK PackageVolume missing APIs related to FindPackageXXX (Status: Open, area-PackageManagement) - ---- - -## Scenarios & Solutions - -### Scenario 1: ApplicationData Not Available for Unpackaged Apps - -**Cause:** `Windows.Storage.ApplicationData.Current` requires both package identity AND running in AppContainer. `Windows.Management.Core.ApplicationDataManager.CreateForPackageFamily` requires package identity AND MediumIL or higher. Unpackaged apps have no access to the ApplicationData API and must manually manage `%LOCALAPPDATA%` paths. Additionally, the existing API has performance overhead (requiring `StorageFolder` with no direct `.Path` access), deprecated features (e.g., `RoamingFolder`), and no synchronous alternatives to async methods. -> Source: Issue author in [#2639](https://github.com/microsoft/WindowsAppSDK/issues/2639) - -**Current workaround for unpackaged apps:** -1. Use standard filesystem paths directly instead of `ApplicationData`: -```csharp -// Equivalent to ApplicationData.LocalFolder for unpackaged apps -string localAppData = Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData); -string appDataPath = Path.Combine(localAppData, "YourPublisher", "YourProduct"); -Directory.CreateDirectory(appDataPath); - -// Equivalent to ApplicationData.TemporaryFolder -string tempPath = Path.Combine(localAppData, "Temp"); - -// Equivalent to ApplicationData.LocalSettings (use registry) -// HKCU\SOFTWARE\YourPublisher\YourProduct -using var key = Registry.CurrentUser.CreateSubKey(@"SOFTWARE\YourPublisher\YourProduct"); -key.SetValue("Setting1", "Value1"); -``` - -2. Reference mapping from the proposal (packaged → unpackaged equivalents): - -| Packaged API | Unpackaged Equivalent | -|---|---| -| `ApplicationData.LocalCacheFolder` | `%LOCALAPPDATA%\\` | -| `ApplicationData.LocalFolder` | `%LOCALAPPDATA%\\` | -| `ApplicationData.MachineFolder` | `%ProgramData%\\` | -| `ApplicationData.TemporaryFolder` | `%LOCALAPPDATA%\Temp` | -| `ApplicationData.LocalSettings` | `HKCU\SOFTWARE\\` | - -**Upcoming fix:** The `Microsoft.Storage.ApplicationData` API is being developed (Status: In PR) to provide a unified API for both packaged and unpackaged apps. The new API will: -- Support packaged and unpackaged applications with a single API surface -- Provide direct filesystem path access without `StorageFolder` overhead -- Offer synchronous equivalents to async methods (e.g., `Clear()` alongside `ClearAsync()`) -- Deprecate obsolete features like `RoamingFolder` -> Source: API proposal in [#2639](https://github.com/microsoft/WindowsAppSDK/issues/2639) - -**Verify:** Check for the `Microsoft.Storage.ApplicationData` namespace in future WinAppSDK releases. - ---- - -### Scenario 2: AppInfo Unavailable for Unpackaged Apps - -**Cause:** The [Windows.ApplicationModel.AppInfo](https://docs.microsoft.com/en-us/uwp/api/Windows.ApplicationModel.AppInfo) class only works for packaged apps because it reads information from the app package manifest. Unpackaged apps have no manifest and therefore cannot use this API to get app metadata (display name, description, logo, etc.). -> Source: Issue author in [#1083](https://github.com/microsoft/WindowsAppSDK/issues/1083) - -**Workaround:** -1. For unpackaged apps, read app information from the executable's file version info: -```csharp -using System.Diagnostics; - -var exePath = Environment.ProcessPath; -var versionInfo = FileVersionInfo.GetVersionInfo(exePath); - -string appName = versionInfo.ProductName ?? "Unknown"; -string appVersion = versionInfo.ProductVersion ?? "0.0.0"; -string company = versionInfo.CompanyName ?? "Unknown"; -string description = versionInfo.FileDescription ?? ""; -``` -2. For icon retrieval in unpackaged apps, use Win32 APIs: -```csharp -[DllImport("shell32.dll", CharSet = CharSet.Auto)] -static extern IntPtr ExtractIcon(IntPtr hInst, string lpszExeFileName, int nIconIndex); -``` -3. The feature proposal requests that WinAppSDK update `AppInfo` to pull from file details for unpackaged apps instead of requiring a manifest - -**Status:** Closed — the feature request was acknowledged but the specific implementation status is unclear. Use the Win32/BCL workarounds above. - ---- - -### Scenario 3: Cannot Declare Default File Handler by Content Type - -**Cause:** The current app manifest system only supports declaring file type associations by specific file extensions (e.g., `.txt`, `.md`, `.json`). There is no way to declare an app as a handler for a MIME content type (e.g., `text/*`), which would automatically cover all file extensions of that type. This forces developers of text editors, media players, and similar broad-format apps to exhaustively list every possible file extension. -> Source: Issue author in [#27](https://github.com/microsoft/WindowsAppSDK/issues/27) - -**Impact:** -- Text editor apps cannot easily become the default handler for all text files -- Declaring every possible file extension is impractical and incomplete -- `StorageFile` operations like renaming fail for undeclared file types -- `StorageFile.GetFileAsync()` fails for unsupported file types -- `Launcher.LaunchFileAsync()` fails if the target file type is undeclared -- Users cannot choose a UWP/WinUI app as default handler for undeclared file types (unlike Win32 apps) - -**Workaround:** -1. Declare as many file extensions as practical in your app manifest: -```xml - - - - .txt - .md - .log - .csv - - - - -``` -2. For unpackaged Win32 apps, use the traditional registry-based file association which has no such limitation -3. Consider using a desktop extension / full-trust component for broader file handling capability - -**Status:** Open — this is a long-standing feature proposal (filed May 2020). No confirmed timeline for content-type-based file handler declaration. - ---- - -### Scenario 4: WASDK PackageVolume Missing FindPackage APIs - -**Cause:** The WASDK `PackageVolume` type is missing APIs related to `FindPackageXXX` methods that are available on the platform's `Windows.Management.Deployment.PackageVolume` type. This means developers using WASDK's package management APIs cannot enumerate or search for packages on a volume. -> Source: Issue author in [#6222](https://github.com/microsoft/WindowsAppSDK/issues/6222) - -**Workaround:** -1. Use the platform `Windows.Management.Deployment.PackageVolume` APIs directly instead of the WASDK equivalent: -```csharp -using Windows.Management.Deployment; - -var packageManager = new PackageManager(); -var volumes = packageManager.FindPackageVolumes(); -foreach (var volume in volumes) -{ - // Platform API has FindPackages methods - var packages = volume.FindPackages(); - // Process packages... -} -``` -2. This bypasses the WASDK abstraction but provides the needed functionality - -**Status:** Open — filed against WinAppSDK 2.0 Experimental 4 (2.0.0-experimental4). The WASDK team may add these APIs in a future release. - -**Environment:** -- WinAppSDK 2.0 Experimental 4 (2.0.0-experimental4) -- Packaged (MSIX) -- Windows 11 24H2 LTSC (26100) - ---- - -## ⚠️ Unverified / Community Suggestions - -> The following are community suggestions that have NOT been officially confirmed. - -- For ApplicationData (#2639): Some developers use a custom `ApplicationData`-like wrapper class that detects packaging state and routes to either the platform API or filesystem paths automatically (community pattern, not officially recommended) -- For file handler content type (#27): Using a Win32 desktop extension bridge to handle file associations for UWP/WinUI apps may provide broader file type coverage (from community discussion in #27) - ---- - -## References - -- [Windows.Storage.ApplicationData - UWP API](https://docs.microsoft.com/uwp/api/windows.storage.applicationdata) -- [Windows.ApplicationModel.AppInfo - UWP API](https://docs.microsoft.com/en-us/uwp/api/Windows.ApplicationModel.AppInfo) -- [File Type Associations - MSIX](https://learn.microsoft.com/en-us/windows/apps/desktop/modernize/desktop-to-uwp-extensions#file-type-associations) -- [PackageVolume - Windows.Management.Deployment](https://learn.microsoft.com/en-us/uwp/api/windows.management.deployment.packagevolume) -- [#2639 Proposal - Microsoft.Storage.ApplicationData](https://github.com/microsoft/WindowsAppSDK/issues/2639) - ---- - -**Updated:** 2025-07-17 | **Confidence:** 0.7 -**Sources:** #2639, #1083, #27, #6222, UWP/WinAppSDK API documentation +# API Gaps: Unpackaged App Support, Storage & Package Management - Windows App SDK + +**Keywords:** ApplicationData, unpackaged, AppInfo, package identity, StorageFolder, PackageVolume, FindPackage, content type, file handler, file association, manifest, LOCALAPPDATA + +**Error Example:** +``` +// ApplicationData.Current fails for unpackaged apps +Windows.Storage.ApplicationData.Current → throws (no package identity) + +// AppInfo unavailable for unpackaged +Windows.ApplicationModel.AppInfo → only works for packaged apps + +// PackageVolume missing APIs +PackageVolume.FindPackages() → method not available in WASDK PackageVolume + +// File handler declaration limitation +Can only declare file type extensions in manifest, not MIME content types +``` + +--- + +## Quick Match + +**You're seeing this if:** +- `ApplicationData.Current` fails in an unpackaged (non-MSIX) app +- Need app metadata (display name, icon, etc.) in an unpackaged app +- WASDK `PackageVolume` is missing `FindPackage`-related APIs available in the platform type +- Want to register as a default file handler by MIME content type instead of individual file extensions +- Encounter issues with missing `PackageVolume` APIs for operations like adding, removing, or setting default package volumes + +→ Check scenarios below for your specific cause + +--- + +## Related Issues + +- [#2639](https://github.com/microsoft/WindowsAppSDK/issues/2639) - Microsoft.Storage.ApplicationData proposal (Status: Open, In PR, area-ApplicationData) +- [#1083](https://github.com/microsoft/WindowsAppSDK/issues/1083) - AppInfo class for unpackaged apps (Status: Closed, feature proposal) +- [#27](https://github.com/microsoft/WindowsAppSDK/issues/27) - Specifying as default file handler with content type instead of filetype (Status: Open, area-Activation, feature proposal) +- [#6222](https://github.com/microsoft/WindowsAppSDK/issues/6222) - WASDK PackageVolume missing APIs related to FindPackageXXX (Status: Open, area-PackageManagement) +- [#5485](https://github.com/microsoft/WindowsAppSDK/issues/5485) - Forgot to implement the WASDK API for operations related to PackageVolume? (Status: Closed, area-PackageManagement) + +--- + +## Scenarios & Solutions + +### Scenario 1: ApplicationData Not Available for Unpackaged Apps + +**Cause:** `Windows.Storage.ApplicationData.Current` requires both package identity AND running in AppContainer. `Windows.Management.Core.ApplicationDataManager.CreateForPackageFamily` requires package identity AND MediumIL or higher. Unpackaged apps have no access to the ApplicationData API and must manually manage `%LOCALAPPDATA%` paths. Additionally, the existing API has performance overhead (requiring `StorageFolder` with no direct `.Path` access), deprecated features (e.g., `RoamingFolder`), and no synchronous alternatives to async methods. +> Source: Issue author in [#2639](https://github.com/microsoft/WindowsAppSDK/issues/2639) + +**Current workaround for unpackaged apps:** +1. Use standard filesystem paths directly instead of `ApplicationData`: +```csharp +// Equivalent to ApplicationData.LocalFolder for unpackaged apps +string localAppData = Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData); +string appDataPath = Path.Combine(localAppData, "YourPublisher", "YourProduct"); +Directory.CreateDirectory(appDataPath); + +// Equivalent to ApplicationData.TemporaryFolder +string tempPath = Path.Combine(localAppData, "Temp"); + +// Equivalent to ApplicationData.LocalSettings (use registry) +// HKCU\SOFTWARE\YourPublisher\YourProduct +using var key = Registry.CurrentUser.CreateSubKey(@"SOFTWARE\YourPublisher\YourProduct"); +key.SetValue("Setting1", "Value1"); +``` + +2. Reference mapping from the proposal (packaged → unpackaged equivalents): + +| Packaged API | Unpackaged Equivalent | +|---|---| +| `ApplicationData.LocalCacheFolder` | `%LOCALAPPDATA%\\` | +| `ApplicationData.LocalFolder` | `%LOCALAPPDATA%\\` | +| `ApplicationData.MachineFolder` | `%ProgramData%\\` | +| `ApplicationData.TemporaryFolder` | `%LOCALAPPDATA%\Temp` | +| `ApplicationData.LocalSettings` | `HKCU\SOFTWARE\\` | + +**Upcoming fix:** The `Microsoft.Storage.ApplicationData` API is being developed (Status: In PR) to provide a unified API for both packaged and unpackaged apps. The new API will: +- Support packaged and unpackaged applications with a single API surface +- Provide direct filesystem path access without `StorageFolder` overhead +- Offer synchronous equivalents to async methods (e.g., `Clear()` alongside `ClearAsync()`) +- Deprecate obsolete features like `RoamingFolder` +> Source: API proposal in [#2639](https://github.com/microsoft/WindowsAppSDK/issues/2639) + +**Verify:** Check for the `Microsoft.Storage.ApplicationData` namespace in future WinAppSDK releases. + +--- + +### Scenario 2: AppInfo Unavailable for Unpackaged Apps + +**Cause:** The [Windows.ApplicationModel.AppInfo](https://docs.microsoft.com/en-us/uwp/api/Windows.ApplicationModel.AppInfo) class only works for packaged apps because it reads information from the app package manifest. Unpackaged apps have no manifest and therefore cannot use this API to get app metadata (display name, description, logo, etc.). +> Source: Issue author in [#1083](https://github.com/microsoft/WindowsAppSDK/issues/1083) + +**Workaround:** +1. For unpackaged apps, read app information from the executable's file version info: +```csharp +using System.Diagnostics; + +var exePath = Environment.ProcessPath; +var versionInfo = FileVersionInfo.GetVersionInfo(exePath); + +string appName = versionInfo.ProductName ?? "Unknown"; +string appVersion = versionInfo.ProductVersion ?? "0.0.0"; +string company = versionInfo.CompanyName ?? "Unknown"; +string description = versionInfo.FileDescription ?? ""; +``` +2. For icon retrieval in unpackaged apps, use Win32 APIs: +```csharp +[DllImport("shell32.dll", CharSet = CharSet.Auto)] +static extern IntPtr ExtractIcon(IntPtr hInst, string lpszExeFileName, int nIconIndex); +``` +3. The feature proposal requests that WinAppSDK update `AppInfo` to pull from file details for unpackaged apps instead of requiring a manifest + +**Status:** Closed — the feature request was acknowledged but the specific implementation status is unclear. Use the Win32/BCL workarounds above. + +--- + +### Scenario 3: Cannot Declare Default File Handler by Content Type + +**Cause:** The current app manifest system only supports declaring file type associations by specific file extensions (e.g., `.txt`, `.md`, `.json`). There is no way to declare an app as a handler for a MIME content type (e.g., `text/*`), which would automatically cover all file extensions of that type. This forces developers of text editors, media players, and similar broad-format apps to exhaustively list every possible file extension. +> Source: Issue author in [#27](https://github.com/microsoft/WindowsAppSDK/issues/27) + +**Impact:** +- Text editor apps cannot easily become the default handler for all text files +- Declaring every possible file extension is impractical and incomplete +- `StorageFile` operations like renaming fail for undeclared file types +- `StorageFile.GetFileAsync()` fails for unsupported file types +- `Launcher.LaunchFileAsync()` fails if the target file type is undeclared +- Users cannot choose a UWP/WinUI app as default handler for undeclared file types (unlike Win32 apps) + +**Workaround:** +1. Declare as many file extensions as practical in your app manifest: +```xml + + + + .txt + .md + .log + .csv + + + + +``` +2. For unpackaged Win32 apps, use the traditional registry-based file association which has no such limitation +3. Consider using a desktop extension / full-trust component for broader file handling capability + +**Status:** Open — this is a long-standing feature proposal (filed May 2020). No confirmed timeline for content-type-based file handler declaration. + +--- + +### Scenario 4: WASDK PackageVolume Missing FindPackage APIs + +**Cause:** The WASDK `PackageVolume` type is missing APIs related to `FindPackageXXX` methods that are available on the platform's `Windows.Management.Deployment.PackageVolume` type. This means developers using WASDK's package management APIs cannot enumerate or search for packages on a volume. +> Source: Issue author in [#6222](https://github.com/microsoft/WindowsAppSDK/issues/6222) + +**Workaround:** +1. Use the platform `Windows.Management.Deployment.PackageVolume` APIs directly instead of the WASDK equivalent: +```csharp +using Windows.Management.Deployment; + +var packageManager = new PackageManager(); +var volumes = packageManager.FindPackageVolumes(); +foreach (var volume in volumes) +{ + // Platform API has FindPackages methods + var packages = volume.FindPackages(); + // Process packages... +} +``` +2. This bypasses the WASDK abstraction but provides the needed functionality + +**Status:** Open — filed against WinAppSDK 2.0 Experimental 4 (2.0.0-experimental4). The WASDK team may add these APIs in a future release. + +--- + +### Scenario 5: Missing WASDK APIs for PackageVolume Operations + +**Cause:** The WASDK `PackageVolume` type lacks APIs for operations like adding, removing, or setting default package volumes, which are available in the platform's `Windows.Management.Deployment.PackageVolume` type. This forces developers to switch between WASDK and platform APIs for full functionality. +> Source: @DrusTheAxe [MSFT] in [#5485](https://github.com/microsoft/WindowsAppSDK/issues/5485) + +**Workaround:** +1. Use the platform `Windows.Management.Deployment.PackageVolume` APIs directly for missing operations: +```csharp +using Windows.Management.Deployment; + +var packageManager = new PackageManager(); +var defaultVolume = packageManager.GetDefaultPackageVolume(); +var availableSpace = defaultVolume.GetAvailableSpaceAsync().GetAwaiter().GetResult(); +``` +2. Refer to the PR [#6104](https://github.com/microsoft/WindowsAppSDK/pull/6104) for updates on the WASDK implementation. + +**Status:** Closed — the missing APIs were added in PR [#6104](https://github.com/microsoft/WindowsAppSDK/pull/6104). + +--- + +## ⚠️ Unverified / Community Suggestions + +> The following are community suggestions that have NOT been officially confirmed. + +- For ApplicationData (#2639): Some developers use a custom `ApplicationData`-like wrapper class that detects packaging state and routes to either the platform API or filesystem paths automatically (community pattern, not officially recommended) +- For file handler content type (#27): Using a Win32 desktop extension bridge to handle file associations for UWP/WinUI apps may provide broader file type coverage (from community discussion in #27) + +--- + +## References + +- [Windows.Storage.ApplicationData - UWP API](https://docs.microsoft.com/uwp/api/windows.storage.applicationdata) +- [Windows.ApplicationModel.AppInfo - UWP API](https://docs.microsoft.com/en-us/uwp/api/Windows.ApplicationModel.AppInfo) +- [File Type Associations - MSIX](https://learn.microsoft.com/en-us/windows/apps/desktop/modernize/desktop-to-uwp-extensions#file-type-associations) +- [PackageVolume - Windows.Management.Deployment](https://learn.microsoft.com/en-us/uwp/api/windows.management.deployment.packagevolume) +- [#2639 Proposal - Microsoft.Storage.ApplicationData](https://github.com/microsoft/WindowsAppSDK/issues/2639) + +--- + +**Updated:** 2026-03-17 | **Confidence:** 0.8 +**Sources:** #2639, #1083, #27, #6222, #5485, UWP/WinAppSDK API documentation \ No newline at end of file diff --git a/tsg/tsg_appcontainer_identity_sharing.md b/trouble-shooting-notes/tsg_appcontainer_identity_sharing.md similarity index 98% rename from tsg/tsg_appcontainer_identity_sharing.md rename to trouble-shooting-notes/tsg_appcontainer_identity_sharing.md index 9baea60..641880a 100644 --- a/tsg/tsg_appcontainer_identity_sharing.md +++ b/trouble-shooting-notes/tsg_appcontainer_identity_sharing.md @@ -1,153 +1,153 @@ -# AppContainer for Win32 Apps & Named Object Sharing Between Packaged/Win32 - -**Keywords:** AppContainer, Win32, PartialTrustApplication, partial trust, sandboxing, named objects, security descriptor, PackageFamilyName, PFN, Shell_NotifyIcon, tray icon, MSIX, runFullTrust, permissiveLearningMode - ---- - -## Quick Match - -**You're seeing this if:** -- You want to run a Win32/WinUI 3 MSIX app in an AppContainer sandbox -- `Shell_NotifyIcon` returns access denied in AppContainer -- You need to share named objects (mutexes, events) between packaged and Win32 apps -- You're trying to configure `PartialTrustApplication` in a `.wapproj` packaging project - -→ Check scenarios below for your specific situation - ---- - -## Related Issues - -- [#219](https://github.com/microsoft/WindowsAppSDK/issues/219) — AppContainer for Win32 apps (Status: Closed — Not Planned, 62 comments) -- [#175](https://github.com/microsoft/WindowsAppSDK/issues/175) — Easing named object sharing between packaged and Win32 (Status: Closed/Fixed) - ---- - -## Scenarios & Solutions - -### Scenario 1: Running a Win32 MSIX App in AppContainer (Partial Trust) - -**Background:** Win32 apps can be launched in an AppContainer by using `EntryPoint="Windows.PartialTrustApplication"` in the MSIX app manifest. This provides Low IL sandboxing similar to UWP apps, but the feature is largely undocumented and has limitations. -> Source: @sylveon (CONTRIBUTOR) in [#219](https://github.com/microsoft/WindowsAppSDK/issues/219) - -**Current status:** Issue #219 was **closed as Not Planned**. Microsoft has not committed to officially supporting AppContainer for Win32 apps through Windows App SDK. -> Source: Issue closed without explanation; @riverar (CONTRIBUTOR) noted: "Always fun when Microsoft employees close issues without saying a word." - -**How to configure partial trust (C# projects / .wapproj):** - -1. Remove `runFullTrust` capability from `Package.appxmanifest`: - ```xml - - - ``` - -2. Set `TrustLevel` on the project reference in the `.wapproj`: - ```xml - - Partial - - ``` - > ✅ Confirmed by: @sbanni in [#219](https://github.com/microsoft/WindowsAppSDK/issues/219) — generates correct appxmanifest with `PartialTrustApplication` entry point - -**How to configure partial trust (C++ projects / .wapproj):** - -The Visual Studio properties panel does not expose the `Trust Level` dropdown for `.vcxproj` references. Manually add `Partial` to the `` in the `.wapproj` file. Ignore the green squiggles — it builds correctly. -> ✅ Confirmed by: @torarnv and @sbanni in [#219](https://github.com/microsoft/WindowsAppSDK/issues/219) - -**Minimum platform version required:** -You may need to bump `TargetPlatformMinVersion` — the old platform versions may reject the partial trust entry point. -> Source: @torarnv in [#219](https://github.com/microsoft/WindowsAppSDK/issues/219) - ---- - -### Scenario 2: Shell_NotifyIcon (Tray Icons) Fail in AppContainer - -**Cause:** `Shell_NotifyIcon` sends messages to the Windows shell, which runs at a higher integrity level. The AppContainer sandbox blocks this cross-IL communication, returning access denied for all calls. -> Source: @ptorr-msft (CONTRIBUTOR) in [#219](https://github.com/microsoft/WindowsAppSDK/issues/219) - -**Fix:** No fix available. `Shell_NotifyIcon` does not work from AppContainer by design. - -**Workaround architecture:** Run GUI/logic in a low-IL partial trust process and broker privileged operations (tray icons, etc.) through a separate medium-IL full trust helper process declared in your package manifest. -> Source: @sylveon (CONTRIBUTOR) and @ptorr-msft (CONTRIBUTOR) in [#219](https://github.com/microsoft/WindowsAppSDK/issues/219) - -``` -┌─────────────────────────────┐ ┌──────────────────────────┐ -│ Main App (Low IL/AppContainer) │──→│ Helper (Medium IL/Full Trust) │ -│ - UI, business logic │ │ - Shell_NotifyIcon │ -│ - WinUI 3 / XAML │ │ - Other privileged APIs │ -└─────────────────────────────┘ └──────────────────────────┘ -``` - ---- - -### Scenario 3: .NET Apps Have High CPU in AppContainer - -**Cause:** Running .NET Core / .NET Framework Win32 apps in AppContainer causes ~20% CPU usage even for a "Hello World" app. This does not reproduce with C++ apps. -> Source: @Felix-Dev in [#219](https://github.com/microsoft/WindowsAppSDK/issues/219) - -**Explanation:** Some .NET API calls are denied by the sandbox, and the runtime may continuously retry them. -> Source: @sylveon (CONTRIBUTOR) in [#219](https://github.com/microsoft/WindowsAppSDK/issues/219) - -**Fix:** No fix available. This is a .NET runtime behavior when sandboxed. - ---- - -### Scenario 4: Debugging AppContainer with Permissive Learning Mode (Windows 11) - -**Background:** Windows 11 introduced `permissiveLearningMode` capability for AppContainer tokens. When enabled, access checks that would normally be denied are instead allowed but logged via ETW tracing. This helps identify which capabilities your app needs. -> Source: @WildByDesign in [#219](https://github.com/microsoft/WindowsAppSDK/issues/219), referencing [Tyranid's blog](https://www.tiraniddo.dev/2021/09/lowbox-token-permissive-learning-mode.html) - -**Usage:** -1. Add `permissiveLearningMode` capability to your AppContainer token. -2. Run the app — all sandbox-denied operations are logged but allowed. -3. Collect ETW traces to identify failed access checks. -4. Tools: [SilkETW](https://github.com/fireeye/SilkETW) can log permissive learning mode events to JSON. - -> ⚠️ @WildByDesign confirmed that with `permissiveLearningMode`, the app has "full access to the file system, network, registry, etc." — so this effectively disables the sandbox for debugging purposes only. - ---- - -### Scenario 5: Sharing Named Objects Between Packaged and Win32 Apps - -**Cause:** Named objects (mutexes, events, waitable timers) must be ACL'd with proper security descriptors to be shared between packaged apps (running in AppContainers) and regular Win32 processes. The required code is [complex and error-prone](https://docs.microsoft.com/en-us/windows/win32/api/securityappcontainer/nf-securityappcontainer-getappcontainernamedobjectpath#examples). -> Source: @DefaultRyan (MEMBER) in [#175](https://github.com/microsoft/WindowsAppSDK/issues/175) - -**Fix:** This was implemented in Windows App SDK via [PR #2005](https://github.com/microsoft/WindowsAppSDK/pull/2005). -> ✅ Confirmed by: @alexlamtest (CONTRIBUTOR) in [#175](https://github.com/microsoft/WindowsAppSDK/issues/175) - -**API:** Use the WinAppSDK security descriptor helper that takes Package Family Names and an access mask: -```c -// Simplified API — replaces boilerplate security descriptor code -GetSecurityDescriptorForPackageFamilyNames( - cCountOfPackageFamilyNames, - pListOfPackageFamilyNames, - accessMask, - &ppSD -); -``` - -**For C# consumers:** Use P/Invoke to call the C API, or use .NET's built-in security descriptor model. -> Source: @DefaultRyan (MEMBER) and @smaillet-ms in [#175](https://github.com/microsoft/WindowsAppSDK/issues/175) - ---- - -## ⚠️ Unverified / Community Suggestions - -> The following are community suggestions that have NOT been officially confirmed. - -- The [Win32 App Isolation](https://github.com/nicktarr/win32-app-isolation) project may provide an alternative path forward for sandboxing, but has had no releases in over two years (from @AkazaRenn in #219) -- PasswordVault isolation requires AppContainer — no alternative exists for non-AppContainer Win32 apps (from @AkazaRenn in #219) - ---- - -## References - -- [Named object sharing guidance](https://docs.microsoft.com/en-us/windows/uwp/communication/sharing-named-objects) -- [Trust/AppContainers guide by @nickrandolph](https://nicksnettravels.builttoroam.com/trust-appcontainers/) -- [Permissive Learning Mode blog](https://www.tiraniddo.dev/2021/09/lowbox-token-permissive-learning-mode.html) -- [WinAppSDK PR #2005 — Named object sharing API](https://github.com/microsoft/WindowsAppSDK/pull/2005) - ---- - -**Updated:** 2026-03-13 | **Confidence:** 0.7 -**Sources:** #219, #175 +# AppContainer for Win32 Apps & Named Object Sharing Between Packaged/Win32 + +**Keywords:** AppContainer, Win32, PartialTrustApplication, partial trust, sandboxing, named objects, security descriptor, PackageFamilyName, PFN, Shell_NotifyIcon, tray icon, MSIX, runFullTrust, permissiveLearningMode + +--- + +## Quick Match + +**You're seeing this if:** +- You want to run a Win32/WinUI 3 MSIX app in an AppContainer sandbox +- `Shell_NotifyIcon` returns access denied in AppContainer +- You need to share named objects (mutexes, events) between packaged and Win32 apps +- You're trying to configure `PartialTrustApplication` in a `.wapproj` packaging project + +→ Check scenarios below for your specific situation + +--- + +## Related Issues + +- [#219](https://github.com/microsoft/WindowsAppSDK/issues/219) — AppContainer for Win32 apps (Status: Closed — Not Planned, 62 comments) +- [#175](https://github.com/microsoft/WindowsAppSDK/issues/175) — Easing named object sharing between packaged and Win32 (Status: Closed/Fixed) + +--- + +## Scenarios & Solutions + +### Scenario 1: Running a Win32 MSIX App in AppContainer (Partial Trust) + +**Background:** Win32 apps can be launched in an AppContainer by using `EntryPoint="Windows.PartialTrustApplication"` in the MSIX app manifest. This provides Low IL sandboxing similar to UWP apps, but the feature is largely undocumented and has limitations. +> Source: @sylveon (CONTRIBUTOR) in [#219](https://github.com/microsoft/WindowsAppSDK/issues/219) + +**Current status:** Issue #219 was **closed as Not Planned**. Microsoft has not committed to officially supporting AppContainer for Win32 apps through Windows App SDK. +> Source: Issue closed without explanation; @riverar (CONTRIBUTOR) noted: "Always fun when Microsoft employees close issues without saying a word." + +**How to configure partial trust (C# projects / .wapproj):** + +1. Remove `runFullTrust` capability from `Package.appxmanifest`: + ```xml + + + ``` + +2. Set `TrustLevel` on the project reference in the `.wapproj`: + ```xml + + Partial + + ``` + > ✅ Confirmed by: @sbanni in [#219](https://github.com/microsoft/WindowsAppSDK/issues/219) — generates correct appxmanifest with `PartialTrustApplication` entry point + +**How to configure partial trust (C++ projects / .wapproj):** + +The Visual Studio properties panel does not expose the `Trust Level` dropdown for `.vcxproj` references. Manually add `Partial` to the `` in the `.wapproj` file. Ignore the green squiggles — it builds correctly. +> ✅ Confirmed by: @torarnv and @sbanni in [#219](https://github.com/microsoft/WindowsAppSDK/issues/219) + +**Minimum platform version required:** +You may need to bump `TargetPlatformMinVersion` — the old platform versions may reject the partial trust entry point. +> Source: @torarnv in [#219](https://github.com/microsoft/WindowsAppSDK/issues/219) + +--- + +### Scenario 2: Shell_NotifyIcon (Tray Icons) Fail in AppContainer + +**Cause:** `Shell_NotifyIcon` sends messages to the Windows shell, which runs at a higher integrity level. The AppContainer sandbox blocks this cross-IL communication, returning access denied for all calls. +> Source: @ptorr-msft (CONTRIBUTOR) in [#219](https://github.com/microsoft/WindowsAppSDK/issues/219) + +**Fix:** No fix available. `Shell_NotifyIcon` does not work from AppContainer by design. + +**Workaround architecture:** Run GUI/logic in a low-IL partial trust process and broker privileged operations (tray icons, etc.) through a separate medium-IL full trust helper process declared in your package manifest. +> Source: @sylveon (CONTRIBUTOR) and @ptorr-msft (CONTRIBUTOR) in [#219](https://github.com/microsoft/WindowsAppSDK/issues/219) + +``` +┌─────────────────────────────┐ ┌──────────────────────────┐ +│ Main App (Low IL/AppContainer) │──→│ Helper (Medium IL/Full Trust) │ +│ - UI, business logic │ │ - Shell_NotifyIcon │ +│ - WinUI 3 / XAML │ │ - Other privileged APIs │ +└─────────────────────────────┘ └──────────────────────────┘ +``` + +--- + +### Scenario 3: .NET Apps Have High CPU in AppContainer + +**Cause:** Running .NET Core / .NET Framework Win32 apps in AppContainer causes ~20% CPU usage even for a "Hello World" app. This does not reproduce with C++ apps. +> Source: @Felix-Dev in [#219](https://github.com/microsoft/WindowsAppSDK/issues/219) + +**Explanation:** Some .NET API calls are denied by the sandbox, and the runtime may continuously retry them. +> Source: @sylveon (CONTRIBUTOR) in [#219](https://github.com/microsoft/WindowsAppSDK/issues/219) + +**Fix:** No fix available. This is a .NET runtime behavior when sandboxed. + +--- + +### Scenario 4: Debugging AppContainer with Permissive Learning Mode (Windows 11) + +**Background:** Windows 11 introduced `permissiveLearningMode` capability for AppContainer tokens. When enabled, access checks that would normally be denied are instead allowed but logged via ETW tracing. This helps identify which capabilities your app needs. +> Source: @WildByDesign in [#219](https://github.com/microsoft/WindowsAppSDK/issues/219), referencing [Tyranid's blog](https://www.tiraniddo.dev/2021/09/lowbox-token-permissive-learning-mode.html) + +**Usage:** +1. Add `permissiveLearningMode` capability to your AppContainer token. +2. Run the app — all sandbox-denied operations are logged but allowed. +3. Collect ETW traces to identify failed access checks. +4. Tools: [SilkETW](https://github.com/fireeye/SilkETW) can log permissive learning mode events to JSON. + +> ⚠️ @WildByDesign confirmed that with `permissiveLearningMode`, the app has "full access to the file system, network, registry, etc." — so this effectively disables the sandbox for debugging purposes only. + +--- + +### Scenario 5: Sharing Named Objects Between Packaged and Win32 Apps + +**Cause:** Named objects (mutexes, events, waitable timers) must be ACL'd with proper security descriptors to be shared between packaged apps (running in AppContainers) and regular Win32 processes. The required code is [complex and error-prone](https://docs.microsoft.com/en-us/windows/win32/api/securityappcontainer/nf-securityappcontainer-getappcontainernamedobjectpath#examples). +> Source: @DefaultRyan (MEMBER) in [#175](https://github.com/microsoft/WindowsAppSDK/issues/175) + +**Fix:** This was implemented in Windows App SDK via [PR #2005](https://github.com/microsoft/WindowsAppSDK/pull/2005). +> ✅ Confirmed by: @alexlamtest (CONTRIBUTOR) in [#175](https://github.com/microsoft/WindowsAppSDK/issues/175) + +**API:** Use the WinAppSDK security descriptor helper that takes Package Family Names and an access mask: +```c +// Simplified API — replaces boilerplate security descriptor code +GetSecurityDescriptorForPackageFamilyNames( + cCountOfPackageFamilyNames, + pListOfPackageFamilyNames, + accessMask, + &ppSD +); +``` + +**For C# consumers:** Use P/Invoke to call the C API, or use .NET's built-in security descriptor model. +> Source: @DefaultRyan (MEMBER) and @smaillet-ms in [#175](https://github.com/microsoft/WindowsAppSDK/issues/175) + +--- + +## ⚠️ Unverified / Community Suggestions + +> The following are community suggestions that have NOT been officially confirmed. + +- The [Win32 App Isolation](https://github.com/nicktarr/win32-app-isolation) project may provide an alternative path forward for sandboxing, but has had no releases in over two years (from @AkazaRenn in #219) +- PasswordVault isolation requires AppContainer — no alternative exists for non-AppContainer Win32 apps (from @AkazaRenn in #219) + +--- + +## References + +- [Named object sharing guidance](https://docs.microsoft.com/en-us/windows/uwp/communication/sharing-named-objects) +- [Trust/AppContainers guide by @nickrandolph](https://nicksnettravels.builttoroam.com/trust-appcontainers/) +- [Permissive Learning Mode blog](https://www.tiraniddo.dev/2021/09/lowbox-token-permissive-learning-mode.html) +- [WinAppSDK PR #2005 — Named object sharing API](https://github.com/microsoft/WindowsAppSDK/pull/2005) + +--- + +**Updated:** 2026-03-13 | **Confidence:** 0.7 +**Sources:** #219, #175 diff --git a/trouble-shooting-notes/tsg_appcontainer_partial_trust.md b/trouble-shooting-notes/tsg_appcontainer_partial_trust.md new file mode 100644 index 0000000..fbdeb65 --- /dev/null +++ b/trouble-shooting-notes/tsg_appcontainer_partial_trust.md @@ -0,0 +1,70 @@ +# Error: "DeploymentAgent exitcode:0x80070005" (0x80070005) - AppContainer and Partial Trust Issues + +**Keywords:** DeploymentAgent exitcode:0x80070005, 0x80070005, Access is denied, AppContainer, Partial Trust, packageManagement, packageQuery + +**Error Example:** +``` +Exception thrown at 0x00007FFAF80A7F7A (KernelBase.dll) in App.exe: WinRT originate error - 0x80070005 : 'DeploymentAgent exitcode:0x80070005'. +C:\__w\1\s\dev\Deployment\DeploymentManager.cpp(486)\Microsoft.WindowsAppRuntime.dll!00007FF9A368AB17: (caller: 00007FF9A368B70B) ReturnHr(2) tid(60d0) 80070005 Access is denied. + Msg:[DeploymentAgent exitcode:0x80070005] +C:\__w\1\s\dev\Deployment\DeploymentManager.cpp(585)\Microsoft.WindowsAppRuntime.dll!00007FF9A368B7BE: (caller: 00007FF9A368ADB0) ReturnHr(3) tid(60d0) 80070005 Access is denied. +C:\__w\1\s\dev\Deployment\DeploymentManager.cpp(495)\Microsoft.WindowsAppRuntime.dll!00007FF9A368ADCF: (caller: 00007FF9A3689971) ReturnHr(4) tid(60d0) 80070 +``` + +--- + +## Quick Match + +**You're seeing this if:** +- Error contains "DeploymentAgent exitcode:0x80070005" or "Access is denied" +- You are running an AppContainer app with partial trust +- Platform: Windows, using Windows App SDK 1.8-preview + +→ Check scenarios below for your specific cause + +--- + +## Related Issues + +- [#5740](https://github.com/microsoft/WindowsAppSDK/issues/5740) - 1.8-preview: AppContainer apps crash at startup (Status: Closed) + +--- + +## Scenarios & Solutions + +### Scenario 1: Missing `packageManagement` Capability + +**Cause:** The app crashes because the `packageManagement` capability is not included in the app manifest. This capability is required for AppContainer apps running in partial trust. + +> Source: @ssparach [MSFT] in [#5740](https://github.com/microsoft/WindowsAppSDK/issues/5740) + +**Fix:** +1. Open your app's manifest file (`Package.appxmanifest`). +2. Add the following capability under the `` section: + ```xml + + ``` +3. Save the manifest file and rebuild your app. + +> ✅ Confirmed by: @ssparach [MSFT] in [#5740](https://github.com/microsoft/WindowsAppSDK/issues/5740) + +**Verify:** Launch the app and confirm it no longer crashes at startup. + +--- + +## ⚠️ Unverified / Community Suggestions + +> The following are community suggestions that have NOT been officially confirmed. + +- None reported for this issue. + +--- + +## References + +- [Official docs: Configure a WinUI 3 project for AppContainer](https://learn.microsoft.com/windows/msix/msix-container#configure-a-winui-3-project-for-appcontainer) + +--- + +**Updated:** 2026-03-17 | **Confidence:** 0.9 +**Sources:** [#5740](https://github.com/microsoft/WindowsAppSDK/issues/5740) \ No newline at end of file diff --git a/tsg/tsg_background_tasks_printing_tooling.md b/trouble-shooting-notes/tsg_background_tasks_printing_tooling.md similarity index 88% rename from tsg/tsg_background_tasks_printing_tooling.md rename to trouble-shooting-notes/tsg_background_tasks_printing_tooling.md index 5ba9c58..e087b68 100644 --- a/tsg/tsg_background_tasks_printing_tooling.md +++ b/trouble-shooting-notes/tsg_background_tasks_printing_tooling.md @@ -1,233 +1,232 @@ -# Background Task Crashes, Print Preview Dark Theme & VS Tooling - Windows App SDK - -**Keywords:** UniversalBGTask, STOWED_EXCEPTION, background task, crash, 0x80004005, 0x80004002, 0x800706ba, 0x80080204, 0xC00CE169, ACCESS_VIOLATION, PrintPreview, dark theme, RequestedTheme, empty preview, Visual Studio 2022, add page, new item - -**Error Example:** -``` -STOWED_EXCEPTION_80004005_Microsoft.Windows.ApplicationModel.Background.UniversalBGTask.dll -STOWED_EXCEPTION_80004002_Microsoft.Windows.ApplicationModel.Background.UniversalBGTask.dll -STOWED_EXCEPTION_800706ba_Microsoft.Windows.ApplicationModel.Background.UniversalBGTask.dll - -// Print preview -PrintPreview window shows blank/empty content when RequestedTheme = Dark - -// VS 2022 tooling -No option to add a new Page in VS 2022 Preview 3 with WinAppSDK 0.8 -``` - ---- - -## Quick Match - -**You're seeing this if:** -- Background task crashes with `STOWED_EXCEPTION` in `UniversalBGTask.dll` -- Partner Center shows thousands of daily crashes from background task execution -- Print preview window displays empty/blank content with dark theme -- Cannot add new WinUI Page items in Visual Studio 2022 - -→ Check scenarios below for your specific cause - ---- - -## Related Issues - -- [#5870](https://github.com/microsoft/WindowsAppSDK/issues/5870) - UniversalBGTask crashes with STOWED_EXCEPTION (Status: Open, area-BackgroundTask, 36 comments) -- [#6086](https://github.com/microsoft/WindowsAppSDK/issues/6086) - PrintPreview displays empty value when RequestedTheme is dark (Status: Open) -- [#1236](https://github.com/microsoft/WindowsAppSDK/issues/1236) - Unable to Create new Pages in VS 2022 Preview 3 (Status: Closed) - ---- - -## Scenarios & Solutions - -### Scenario 1: UniversalBGTask Crashes with STOWED_EXCEPTION (High Volume) - -**Cause:** Background tasks implemented using the WinAppSDK `UniversalBGTask` infrastructure crash with `STOWED_EXCEPTION` errors during `IBackgroundTask.Run`. The crashes occur in `Microsoft.Windows.ApplicationModel.Background.UniversalBGTask.dll` and affect Store-published apps at massive scale (10,000+ crashes per day reported). In WinAppSDK 1.7, similar crashes manifested as `ACCESS_VIOLATION` errors (discussed in [microsoft-ui-xaml#10769](https://github.com/microsoft/microsoft-ui-xaml/issues/10769)). After upgrading to WinAppSDK 1.8, the error code changed to `STOWED_EXCEPTION` but the crash volume remained similar. -> Source: Issue author in [#5870](https://github.com/microsoft/WindowsAppSDK/issues/5870) - -**Error codes observed:** -- `STOWED_EXCEPTION_80004005` (E_FAIL) — General failure during task execution -- `STOWED_EXCEPTION_80004002` (E_NOINTERFACE) — `hresult_no_interface` thrown, suggesting COM interface query failure -- `STOWED_EXCEPTION_800706ba` (RPC_S_SERVER_UNAVAILABLE) — RPC server unavailable during task run -- `0x80080204` and `0xC00CE169` — Additional error codes referenced in issue metadata - -**Common stack trace pattern:** -``` -UniversalBGTask.dll!winrt::hresult_error::originate -UniversalBGTask.dll!...::Task::Run -biwinrt.dll!CBackgroundTaskInstance::RunInternal -biwinrt.dll!CBackgroundTaskInstance::Run -twinapi.appcore.dll!BackgroundTaskWrapper::ThreadProc -``` - -**Key observations:** -- Crashes happen across multiple Windows versions: Windows 11 10.0.26100, 10.0.22631, Windows 10 10.0.19045 -- The crash count exceeds the "devices affected" count, indicating repeated crashes on the same machines -- Affects all apps published in the Microsoft Store that use background tasks -- Issue persisted across WinAppSDK 1.7 (ACCESS_VIOLATION) and 1.8 (STOWED_EXCEPTION) - -**Workaround (limited):** -1. Wrap your background task `Run` implementation in a comprehensive try-catch to prevent unhandled exceptions: -```csharp -public sealed class MyBackgroundTask : IBackgroundTask -{ - public void Run(IBackgroundTaskInstance taskInstance) - { - var deferral = taskInstance.GetDeferral(); - try - { - // Your task logic here - } - catch (Exception ex) - { - // Log the error - don't let it propagate - Debug.WriteLine($"Background task error: {ex.HResult:X} - {ex.Message}"); - } - finally - { - deferral.Complete(); - } - } -} -``` -2. Note: The `E_NOINTERFACE` (0x80004002) crash occurs inside `UniversalBGTask.dll` itself (not user code), suggesting a platform-level COM activation failure that cannot be caught by user exception handlers -3. The `RPC_S_SERVER_UNAVAILABLE` (0x800706ba) error suggests the background task host process may lose connection to the main application or a required system service -4. Monitor [#5870](https://github.com/microsoft/WindowsAppSDK/issues/5870) for updates — this is actively discussed with 36 comments - -**Status:** Open — no confirmed fix. This is a high-impact issue affecting Store-published apps. - -**Environment:** -- WinAppSDK 1.8.1 (1.8.250916003) -- Packaged (MSIX) -- Multiple Windows versions (10 and 11) - ---- - -### Scenario 2: Print Preview Shows Empty Content with Dark Theme - -**Cause:** When `RequestedTheme` is set to `ApplicationTheme.Dark` in a WinUI application, the print preview window displays blank/empty content. The same printing code works correctly when the theme is set to Light. The issue is that the print preview rendering inherits the dark theme, causing text (likely white/light colored) to be rendered on a white print preview background, making it invisible. -> Source: Issue author in [#6086](https://github.com/microsoft/WindowsAppSDK/issues/6086) - -**Steps to reproduce:** -1. Set `this.RequestedTheme = ApplicationTheme.Dark` in `App.xaml.cs` -2. Implement printing with `PrintDocument` -3. Create preview pages using `StackPanel` with `TextBlock` elements -4. Open print preview — text is invisible - -**Reproduction code pattern:** -```csharp -// In App.xaml.cs -public App() -{ - this.RequestedTheme = ApplicationTheme.Dark; // Causes issue - InitializeComponent(); -} - -// In printing handler -private void OnPaginate(object sender, PaginateEventArgs e) -{ - var page = new StackPanel { Margin = new Thickness(20) }; - page.Children.Add(new TextBlock - { - Text = "Hello, this is a print test!", - FontSize = 24 - }); - _printDoc.SetPreviewPage(1, page); -} -``` - -**Fix:** -1. Explicitly set the print preview page elements to use Light theme and dark text colors: -```csharp -private void OnPaginate(object sender, PaginateEventArgs e) -{ - var page = new StackPanel - { - Margin = new Thickness(20), - RequestedTheme = ElementTheme.Light, // Force light theme for print - Background = new SolidColorBrush(Colors.White) - }; - page.Children.Add(new TextBlock - { - Text = "Hello, this is a print test!", - FontSize = 24, - Foreground = new SolidColorBrush(Colors.Black) // Explicit dark text - }); - _printDoc.SetPreviewPage(1, page); -} -``` -2. Alternatively, set `RequestedTheme = ElementTheme.Light` on the root element of each print preview page to ensure print content is always rendered with light theme colors regardless of the app theme - -**Verify:** Open print preview with dark theme active — text should now be visible on the white preview background. - -**Status:** Open — no official fix from WinAppSDK team yet. - ---- - -### Scenario 3: Cannot Add New WinUI Pages in Visual Studio 2022 - -**Cause:** In Visual Studio 2022 Preview 3 with WinAppSDK 0.8, the "Add New Item" dialog did not include an option to add a new WinUI Page. The WinUI item templates were not properly registered in early VS 2022 previews. -> Source: Issue author in [#1236](https://github.com/microsoft/WindowsAppSDK/issues/1236) - -**Workaround (historical):** -1. Use Visual Studio 2019 to add the new page, then continue working in VS 2022 -2. Manually create the `.xaml` and `.xaml.cs` files following the WinUI page pattern: - -```xml - - - - - -``` - -```csharp -// NewPage.xaml.cs -namespace YourApp -{ - public sealed partial class NewPage : Page - { - public NewPage() - { - this.InitializeComponent(); - } - } -} -``` - -**Fix:** -1. **Update Visual Studio 2022** to a recent stable release — this issue was specific to early Preview 3 builds with WinAppSDK 0.8 -2. Ensure the **Windows App SDK** extension/workload is installed in VS 2022 -3. Modern versions of VS 2022 with WinAppSDK 1.x+ include proper WinUI item templates - -> ✅ Confirmed resolved: Issue is closed, indicating this was fixed in subsequent VS 2022 updates - -**Environment:** -- Visual Studio 2022 Preview 3 (historical) -- WinAppSDK 0.8 - ---- - -## ⚠️ Unverified / Community Suggestions - -> The following are community suggestions that have NOT been officially confirmed. - -- For background task crashes (#5870): Some developers report that reducing background task frequency or adding retry logic with exponential backoff reduces the visible crash rate, though the underlying platform issue remains (community reports in #5870) -- For background task crashes (#5870): Disabling background tasks entirely as a temporary measure while waiting for a fix may be appropriate if the crashes impact app store ratings (from community discussion) -- For print preview (#6086): Some developers report that creating the print preview content in a separate `Frame` with explicit Light theme avoids the issue (not officially confirmed) - ---- - -## References - -- [Background Tasks - WinAppSDK Documentation](https://learn.microsoft.com/en-us/windows/apps/windows-app-sdk/applifecycle/background-tasks) -- [PrintDocument Class - WinUI](https://learn.microsoft.com/en-us/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.printing.printdocument) -- [WinUI Item Templates - Visual Studio](https://learn.microsoft.com/en-us/windows/apps/winui/winui3/winui-project-templates-in-visual-studio) -- [Related: microsoft-ui-xaml#10769 - Background task ACCESS_VIOLATION](https://github.com/microsoft/microsoft-ui-xaml/issues/10769) - ---- - -**Updated:** 2025-07-17 | **Confidence:** 0.6 -**Sources:** #5870, #6086, #1236, Microsoft Learn documentation +# Background Task Crashes, Print Preview Dark Theme & VS Tooling - Windows App SDK + +**Keywords:** UniversalBGTask, STOWED_EXCEPTION, background task, crash, 0x80004005, 0x80004002, 0x800706ba, 0x80080204, 0xC00CE169, ACCESS_VIOLATION, PrintPreview, dark theme, RequestedTheme, empty preview, Visual Studio 2022, add page, new item + +**Error Example:** +``` +STOWED_EXCEPTION_80004005_Microsoft.Windows.ApplicationModel.Background.UniversalBGTask.dll +STOWED_EXCEPTION_80004002_Microsoft.Windows.ApplicationModel.Background.UniversalBGTask.dll +STOWED_EXCEPTION_800706ba_Microsoft.Windows.ApplicationModel.Background.UniversalBGTask.dll + +// Print preview +PrintPreview window shows blank/empty content when RequestedTheme = Dark + +// VS 2022 tooling +No option to add a new Page in VS 2022 Preview 3 with WinAppSDK 0.8 +``` + +--- + +## Quick Match + +**You're seeing this if:** +- Background task crashes with `STOWED_EXCEPTION` in `UniversalBGTask.dll` +- Partner Center shows thousands of daily crashes from background task execution +- Print preview window displays empty/blank content with dark theme +- Cannot add new WinUI Page items in Visual Studio 2022 + +→ Check scenarios below for your specific cause + +--- + +## Related Issues + +- [#5870](https://github.com/microsoft/WindowsAppSDK/issues/5870) - UniversalBGTask crashes with STOWED_EXCEPTION (Status: Open, area-BackgroundTask, 36 comments) +- [#6086](https://github.com/microsoft/WindowsAppSDK/issues/6086) - PrintPreview displays empty value when RequestedTheme is dark (Status: Open) +- [#1236](https://github.com/microsoft/WindowsAppSDK/issues/1236) - Unable to Create new Pages in VS 2022 Preview 3 (Status: Closed) + +--- + +## Scenarios & Solutions + +### Scenario 1: UniversalBGTask Crashes with STOWED_EXCEPTION (High Volume) + +**Cause:** Background tasks implemented using the WinAppSDK `UniversalBGTask` infrastructure crash with `STOWED_EXCEPTION` errors during `IBackgroundTask.Run`. The crashes occur in `Microsoft.Windows.ApplicationModel.Background.UniversalBGTask.dll` and affect Store-published apps at massive scale (10,000+ crashes per day reported). In WinAppSDK 1.7, similar crashes manifested as `ACCESS_VIOLATION` errors (discussed in [microsoft-ui-xaml#10769](https://github.com/microsoft/microsoft-ui-xaml/issues/10769)). After upgrading to WinAppSDK 1.8, the error code changed to `STOWED_EXCEPTION` but the crash volume remained similar. +> Source: Issue author in [#5870](https://github.com/microsoft/WindowsAppSDK/issues/5870) + +**Error codes observed:** +- `STOWED_EXCEPTION_80004005` (E_FAIL) — General failure during task execution +- `STOWED_EXCEPTION_80004002` (E_NOINTERFACE) — `hresult_no_interface` thrown, suggesting COM interface query failure +- `STOWED_EXCEPTION_800706ba` (RPC_S_SERVER_UNAVAILABLE) — RPC server unavailable during task run +- `0x80080204` and `0xC00CE169` — Additional error codes referenced in issue metadata + +**Common stack trace pattern:** +``` +UniversalBGTask.dll!winrt::hresult_error::originate +UniversalBGTask.dll!...::Task::Run +biwinrt.dll!CBackgroundTaskInstance::RunInternal +biwinrt.dll!CBackgroundTaskInstance::Run +twinapi.appcore.dll!BackgroundTaskWrapper::ThreadProc +``` + +**Key observations:** +- Crashes happen across multiple Windows versions: Windows 11 10.0.26100, 10.0.22631, Windows 10 10.0.19045 +- The crash count exceeds the "devices affected" count, indicating repeated crashes on the same machines +- Affects all apps published in the Microsoft Store that use background tasks +- Issue persisted across WinAppSDK 1.7 (ACCESS_VIOLATION) and 1.8 (STOWED_EXCEPTION) + +**Workaround (limited):** +1. Wrap your background task `Run` implementation in a comprehensive try-catch to prevent unhandled exceptions: +```csharp +public sealed class MyBackgroundTask : IBackgroundTask +{ + public void Run(IBackgroundTaskInstance taskInstance) + { + var deferral = taskInstance.GetDeferral(); + try + { + // Your task logic here + } + catch (Exception ex) + { + // Log the error - don't let it propagate + Debug.WriteLine($"Background task error: {ex.HResult:X} - {ex.Message}"); + } + finally + { + deferral.Complete(); + } + } +} +``` +2. Note: The `E_NOINTERFACE` (0x80004002) crash occurs inside `UniversalBGTask.dll` itself (not user code), suggesting a platform-level COM activation failure that cannot be caught by user exception handlers +3. The `RPC_S_SERVER_UNAVAILABLE` (0x800706ba) error suggests the background task host process may lose connection to the main application or a required system service +4. Monitor [#5870](https://github.com/microsoft/WindowsAppSDK/issues/5870) for updates — this is actively discussed with 36 comments + +**Status:** Open — no confirmed fix. This is a high-impact issue affecting Store-published apps. + +**Environment:** +- WinAppSDK 1.8.1 (1.8.250916003) +- Packaged (MSIX) +- Multiple Windows versions (10 and 11) + +--- + +### Scenario 2: Print Preview Shows Empty Content with Dark Theme + +**Cause:** When `RequestedTheme` is set to `ApplicationTheme.Dark` in a WinUI application, the print preview window displays blank/empty content. The same printing code works correctly when the theme is set to Light. The issue is that the print preview rendering inherits the dark theme, causing text (likely white/light colored) to be rendered on a white print preview background, making it invisible. +> Source: @MuyuanMS in [#6086](https://github.com/microsoft/WindowsAppSDK/issues/6086) + +**Steps to reproduce:** +1. Set `this.RequestedTheme = ApplicationTheme.Dark` in `App.xaml.cs` +2. Implement printing with `PrintDocument` +3. Create preview pages using `StackPanel` with `TextBlock` elements +4. Open print preview — text is invisible + +**Reproduction code pattern:** +```csharp +// In App.xaml.cs +public App() +{ + this.RequestedTheme = ApplicationTheme.Dark; // Causes issue + InitializeComponent(); +} + +// In printing handler +private void OnPaginate(object sender, PaginateEventArgs e) +{ + var page = new StackPanel { Margin = new Thickness(20) }; + page.Children.Add(new TextBlock + { + Text = "Hello, this is a print test!", + FontSize = 24 + }); + _printDoc.SetPreviewPage(1, page); +} +``` + +**Fix:** +1. Explicitly set the print preview page elements to use Light theme and dark text colors: +```csharp +private void OnPaginate(object sender, PaginateEventArgs e) +{ + var page = new StackPanel + { + Margin = new Thickness(20), + RequestedTheme = ElementTheme.Light, // Force light theme for print + Background = new SolidColorBrush(Colors.White) + }; + page.Children.Add(new TextBlock + { + Text = "Hello, this is a print test!", + FontSize = 24, + Foreground = new SolidColorBrush(Colors.Black) // Explicit dark text + }); + _printDoc.SetPreviewPage(1, page); +} +``` +2. Alternatively, set `RequestedTheme = ElementTheme.Light` on the root element of each print preview page to ensure print content is always rendered with light theme colors regardless of the app theme + +**Verify:** Open print preview with dark theme active — text should now be visible on the white preview background. + +**Status:** Open — no official fix from WinAppSDK team yet. + +--- + +### Scenario 3: Cannot Add New WinUI Pages in Visual Studio 2022 + +**Cause:** In Visual Studio 2022 Preview 3 with WinAppSDK 0.8, the "Add New Item" dialog did not include an option to add a new WinUI Page. The WinUI item templates were not properly registered in early VS 2022 previews. +> Source: Issue author in [#1236](https://github.com/microsoft/WindowsAppSDK/issues/1236) + +**Workaround (historical):** +1. Use Visual Studio 2019 to add the new page, then continue working in VS 2022 +2. Manually create the `.xaml` and `.xaml.cs` files following the WinUI page pattern: + +```xml + + + + + +``` + +```csharp +// NewPage.xaml.cs +namespace YourApp +{ + public sealed partial class NewPage : Page + { + public NewPage() + { + this.InitializeComponent(); + } + } +} +``` + +**Fix:** +1. **Update Visual Studio 2022** to a recent stable release — this issue was specific to early Preview 3 builds with WinAppSDK 0.8 +2. Ensure the **Windows App SDK** extension/workload is installed in VS 2022 +3. Modern versions of VS 2022 with WinAppSDK 1.x+ include proper WinUI item templates + +> ✅ Confirmed resolved: Issue is closed, indicating this was fixed in subsequent VS 2022 updates + +**Environment:** +- Visual Studio 2022 Preview 3 (historical) +- WinAppSDK 0.8 + +--- + +## ⚠️ Known Issues / Unverified Suggestions + +### UniversalBGTask Crashes (#5870) +- **Observation:** Some developers report that reducing background task frequency or adding retry logic with exponential backoff reduces the visible crash rate, though the underlying platform issue remains. +- **Observation:** Disabling background tasks entirely as a temporary measure while waiting for a fix may be appropriate if the crashes impact app store ratings. +> Source: Community comments in [#5870](https://github.com/microsoft/WindowsAppSDK/issues/5870) + +--- + +## References + +- [Background Tasks - WinAppSDK Documentation](https://learn.microsoft.com/en-us/windows/apps/windows-app-sdk/applifecycle/background-tasks) +- [PrintDocument Class - WinUI](https://learn.microsoft.com/en-us/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.printing.printdocument) +- [WinUI Item Templates - Visual Studio](https://learn.microsoft.com/en-us/windows/apps/winui/winui3/winui-project-templates-in-visual-studio) +- [Related: microsoft-ui-xaml#10769 - Background task ACCESS_VIOLATION](https://github.com/microsoft/microsoft-ui-xaml/issues/10769) + +--- + +**Updated:** 2026-03-17 | **Confidence:** 0.6 +**Sources:** #5870, #6086, #1236, Microsoft Learn documentation \ No newline at end of file diff --git a/trouble-shooting-notes/tsg_cppwinrt_template_compile_failures.md b/trouble-shooting-notes/tsg_cppwinrt_template_compile_failures.md new file mode 100644 index 0000000..7e7489e --- /dev/null +++ b/trouble-shooting-notes/tsg_cppwinrt_template_compile_failures.md @@ -0,0 +1,105 @@ +# Error: "MIDL2011: unresolved type declaration" - C++/WinRT Template Compilation Failures + +**Keywords:** MIDL2011, unresolved type declaration, Microsoft.UI.Xaml.Window, C++/WinRT, Windows App SDK, WinUI3 + +**Error Example:** +``` +MIDL2011: [msg]unresolved type declaration [context]: Microsoft.UI.Xaml.Window [ RuntimeClass 'OlMaRudge.MainWindow' ] +``` + +--- + +## Quick Match + +**You're seeing this if:** +- Error contains "MIDL2011" or "unresolved type declaration" +- Building a project created from the "Blank App, Packaged (WinUI3 in Desktop)" C++ template +- Platform: Visual Studio 2022 with Windows App SDK 1.7.x + +→ Check scenarios below for your specific cause + +--- + +## Related Issues + +- [#5041](https://github.com/microsoft/WindowsAppSDK/issues/5041) - Blank App, Packaged (WinUI3 in Desktop) C++ fails to compile (Status: Closed, Fixed) +- [#5507](https://github.com/microsoft/WindowsAppSDK/issues/5507) - `base.h` `#elif _DEBUG` gives build error C1017: invalid integer constant expression (Status: Open) + +--- + +## Scenarios & Solutions + +### Scenario 1: Missing CppWinRT NuGet Package + +**Cause:** The Visual Studio 2022 "Blank App, Packaged (WinUI3 in Desktop)" C++ template does not include the required `Microsoft.Windows.CppWinRT` NuGet package, which is necessary for generating the projection and providing metadata for MIDL compilation. +> Source: @HUN73R [MSFT] in [#5041](https://github.com/microsoft/WindowsAppSDK/issues/5041) + +**Fix:** +1. Open your project in Visual Studio 2022. +2. Install the `Microsoft.Windows.CppWinRT` NuGet package: + - Right-click on your project in the Solution Explorer. + - Select **Manage NuGet Packages**. + - Search for `Microsoft.Windows.CppWinRT` and install the latest version. +3. Rebuild your project. + +> ✅ Confirmed by: @HUN73R [MSFT] in [#5041](https://github.com/microsoft/WindowsAppSDK/issues/5041) + +**Verify:** Rebuild the project. The error `MIDL2011: unresolved type declaration` should no longer appear. + +--- + +### Scenario 2: Incorrect or Missing Windows SDK Version + +**Cause:** The required Windows SDK version (e.g., 10.0.26100.0) is not installed or not properly configured in the Visual Studio environment. +> Source: @DarranRowe in [#5041](https://github.com/microsoft/WindowsAppSDK/issues/5041) + +**Fix:** +1. Open the Visual Studio Installer. +2. Ensure the latest Windows 11 SDK (e.g., 10.0.26100.0) is installed: + - Go to the **Individual Components** tab. + - Check for the **Windows 11 SDK** and install it if missing. +3. Update your project settings to use the correct Windows SDK version: + - Right-click on your project in Solution Explorer. + - Select **Properties** > **General**. + - Set the **Windows SDK Version** to the installed version (e.g., 10.0.26100.0). +4. Rebuild your project. + +--- + +### Scenario 3: Incorrect Preprocessor Definitions + +**Cause:** The `_DEBUG` macro is defined in a way that does not resolve to a valid integer constant expression, causing a conflict during compilation. +> Source: @DarranRowe in [#5507](https://github.com/microsoft/WindowsAppSDK/issues/5507) + +**Fix:** +1. Open your project in Visual Studio 2022. +2. Check the **Preprocessor Definitions** in your project settings: + - Right-click on your project in Solution Explorer. + - Select **Properties** > **C/C++** > **Preprocessor**. + - Ensure `_DEBUG` is defined correctly (e.g., `_DEBUG=1`). +3. If using third-party libraries (e.g., Boost), verify that they do not redefine `_DEBUG` in a conflicting manner. + +--- + +## ⚠️ Unverified / Community Suggestions + +> The following are community suggestions that have NOT been officially confirmed. + +- Ensure Visual Studio and all extensions are up to date. + > Suggested by: @DarranRowe in [#5041](https://github.com/microsoft/WindowsAppSDK/issues/5041) + +- Downgrade the Windows App SDK NuGet package to an earlier version (e.g., 1.6.x) if using the latest version does not resolve the issue. + > Suggested by: @HUN73R [MSFT] in [#5041](https://github.com/microsoft/WindowsAppSDK/issues/5041) + +--- + +## References + +- [CppWinRT Repository](https://github.com/microsoft/cppwinrt) +- [Microsoft.Windows.CppWinRT NuGet Package](https://www.nuget.org/packages/Microsoft.Windows.CppWinRT) +- [Windows App SDK Documentation](https://learn.microsoft.com/en-us/windows/apps/windows-app-sdk/) + +--- + +**Updated:** 2026-03-17 | **Confidence:** 0.9 +**Sources:** [#5041](https://github.com/microsoft/WindowsAppSDK/issues/5041), [#5507](https://github.com/microsoft/WindowsAppSDK/issues/5507) \ No newline at end of file diff --git a/trouble-shooting-notes/tsg_cursor_aot_errors.md b/trouble-shooting-notes/tsg_cursor_aot_errors.md new file mode 100644 index 0000000..2dbcff7 --- /dev/null +++ b/trouble-shooting-notes/tsg_cursor_aot_errors.md @@ -0,0 +1,109 @@ +# Error: "Specified cast is not valid" - Custom Cursor with AOT Compilation + +**Keywords:** Specified cast is not valid, AOT, custom cursor, dynamic cursor, CsWinRT, LibraryImport, DllImport, partial class + +**Error Example:** +``` +Specified cast is not valid +``` + +--- + +## Quick Match + +**You're seeing this if:** +- Error contains "Specified cast is not valid" +- Using a custom cursor in a C# project +- AOT (Ahead-of-Time) compilation is enabled +- Platform: Windows 11 version 24H2 (26100, June 2025 Update) + +→ Check scenarios below for your specific cause + +--- + +## Related Issues + +- [#5716](https://github.com/microsoft/WindowsAppSDK/issues/5716) - Custom Cursor AOT Error (Status: Closed) + +--- + +## Scenarios & Solutions + +### Scenario 1: Missing `partial` Keyword in Custom Classes + +**Cause:** The custom button or other classes used in the project are not marked as `partial`, which is required for compatibility with AOT compilation. +> Source: @ghost1372 in [#5716](https://github.com/microsoft/WindowsAppSDK/issues/5716) + +**Fix:** +1. Add the `partial` keyword to all custom classes. For example: + ```csharp + public partial class MyButton : Button + ``` +2. Ensure all relevant classes in your project are updated similarly. + +> ✅ Confirmed by: @BlameTwo in issue comments + +**Verify:** Rebuild the project with AOT enabled and confirm the error no longer occurs. + +--- + +### Scenario 2: Hard-Coded Resource Paths in Project Files + +**Cause:** Resource paths for the custom cursor are hard-coded in project files, causing issues when running the application on different systems. +> Source: @ghost1372 in [#5716](https://github.com/microsoft/WindowsAppSDK/issues/5716) + +**Fix:** +1. Open your `.csproj` file and replace hard-coded paths with relative paths. For example: + ```xml + + + + ``` +2. Update any `.rc` files to use relative paths instead of absolute paths. + +**Verify:** Rebuild the project and confirm the custom cursor is displayed correctly. + +--- + +### Scenario 3: Missing AOT Compatibility Settings + +**Cause:** The project is not explicitly marked as AOT-compatible, leading to warnings or runtime issues. +> Source: @ghost1372 in [#5716](https://github.com/microsoft/WindowsAppSDK/issues/5716) + +**Fix:** +1. Add the following property to your `.csproj` file: + ```xml + + true + + ``` +2. Rebuild the project to ensure compatibility. + +**Verify:** Check for any remaining warnings during the build process and confirm the application runs without issues. + +--- + +## ⚠️ Unverified / Community Suggestions + +> The following are community suggestions that have NOT been officially confirmed. + +- Disable runtime marshaling in your project settings. + > Suggested by @ghost1372 in [#5716](https://github.com/microsoft/WindowsAppSDK/issues/5716) + +- Use `LibraryImport` instead of `DllImport` for native code interop. + > Suggested by @ghost1372 in [#5716](https://github.com/microsoft/WindowsAppSDK/issues/5716) + +- Avoid using reflection in your codebase. + > Suggested by @ghost1372 in [#5716](https://github.com/microsoft/WindowsAppSDK/issues/5716) + +--- + +## References + +- [Official docs](https://learn.microsoft.com/en-us/windows/apps/) +- [API docs](https://learn.microsoft.com/en-us/dotnet/api/) + +--- + +**Updated:** 2026-03-17 | **Confidence:** 0.9 +**Sources:** [#5716](https://github.com/microsoft/WindowsAppSDK/issues/5716) \ No newline at end of file diff --git a/tsg/tsg_deployment_singlefile_installer.md b/trouble-shooting-notes/tsg_deployment_singlefile_installer.md similarity index 78% rename from tsg/tsg_deployment_singlefile_installer.md rename to trouble-shooting-notes/tsg_deployment_singlefile_installer.md index e55ce57..fa48ddc 100644 --- a/tsg/tsg_deployment_singlefile_installer.md +++ b/trouble-shooting-notes/tsg_deployment_singlefile_installer.md @@ -1,161 +1,186 @@ -# Error: "XamlParseException: XAML parsing failed" — Renamed Single-File Unpackaged App / Broken Runtime Links - -**Keywords:** XamlParseException, XAML parsing failed, single-file, unpackaged, rename executable, PublishSingleFile, runtime links broken, 2.0 preview, installer binaries, MRM.dll crash - -**Error Example:** -``` -Microsoft.UI.Xaml.Markup.XamlParseException: XAML parsing failed. - at WinRT.ExceptionHelpers.g__Throw|38_0(Int32) - at ABI.Microsoft.UI.Xaml.IApplicationStaticsMethods.LoadComponent(...) - at Microsoft.UI.Xaml.Application.LoadComponent(Object, Uri, ComponentResourceLocation) - at TestApp1.MainWindow.InitializeComponent() -``` - ---- - -## Quick Match - -**You're seeing this if:** -- You published a WinUI 3 app as single-file unpackaged and renamed the `.exe` -- Error contains "XamlParseException" or "XAML parsing failed" after renaming -- WASDK 2.0 Preview runtime download links return 404 -- WASDK 1.6.3 installers ship binaries that still crash despite documented fixes - -→ Check scenarios below for your specific cause - ---- - -## Related Issues - -- [#6248](https://github.com/microsoft/WindowsAppSDK/issues/6248) — Renaming published executable makes Single-File Unpackaged App crash (Status: Open) -- [#6220](https://github.com/microsoft/WindowsAppSDK/issues/6220) — WASDK 2.0 Preview runtime links are broken (Status: Closed/Fixed) -- [#4977](https://github.com/microsoft/WindowsAppSDK/issues/4977) — 1.6.3 installers contain binaries built from older source code (Status: Closed) - ---- - -## Scenarios & Solutions - -### Scenario 1: Renaming Single-File Published Executable Causes XamlParseException - -**Cause:** When a WinUI 3 app is published as a single-file, self-contained, unpackaged app and the resulting `.exe` is renamed (e.g., `TestApp1.exe` → `TestApp11.exe`), XAML resource loading fails. The `Application.LoadComponent` call uses URI-based resource paths that are tied to the original executable name, so renaming breaks the lookup. -> Source: Issue reporter in [#6248](https://github.com/microsoft/WindowsAppSDK/issues/6248) - -**Reproduction config:** -```xml - - None - true - -``` -```xml - -true -true -true -``` - -**Fix:** No official fix available yet. **Do not rename the published executable.** - -**Workaround:** Keep the original executable name after publishing. If branding requires a different name, change the `AssemblyName` in your `.csproj` before publishing instead of renaming the output file. - -> ⚠️ @aepot in [#6248](https://github.com/microsoft/WindowsAppSDK/issues/6248) reports being stuck on WASDK 1.7 because of this bug. - ---- - -### Scenario 2: WASDK 2.0 Preview Runtime Download Links Broken - -**Cause:** The `aka.ms` download links for WASDK 2.0 Preview 1 runtime installers were returning 404 errors shortly after the preview release. -> Source: Issue reporter in [#6220](https://github.com/microsoft/WindowsAppSDK/issues/6220) - -**Affected links:** -``` -https://aka.ms/windowsappsdk/2.0/2.0-preview1/windowsappruntimeinstall-x64.exe -https://aka.ms/windowsappsdk/2.0/2.0-preview1/windowsappruntimeinstall-x86.exe -https://aka.ms/windowsappsdk/2.0/2.0-preview1/windowsappruntimeinstall-arm64.exe -https://aka.ms/windowsappsdk/2.0/2.0-preview1/Microsoft.WindowsAppRuntime.Redist.2.0.zip -``` - -**Fix:** Links have been corrected by Microsoft. -> ✅ Confirmed by: @lauren-ciha (MEMBER) in [#6220](https://github.com/microsoft/WindowsAppSDK/issues/6220) - -**Working Redist link:** -``` -https://aka.ms/windowsappsdk/2.0/2.0-preview1/Microsoft.WindowsAppRuntime.Redist.2.0-preview1.zip -``` - -**Verify:** Check the [official WASDK downloads page](https://learn.microsoft.com/en-us/windows/apps/windows-app-sdk/downloads) for current links. - ---- - -### Scenario 3: WASDK 1.6.3 Installers Contain Stale Binaries (MRM.dll Crash) - -**Cause:** The WASDK 1.6.3 (1.6.241114003) runtime installers shipped binaries built from an older commit in the `release/1.6-stable` branch rather than from the `v1.6.3` tag. Specifically, `MRM.dll` did not include the [buffer overrun fix](https://github.com/microsoft/WindowsAppSDK/commit/1db04b650194f090ba1b52ae48f61277737c19f0), causing crashes in apps that use MRT resource loading. -> Source: Issue reporter in [#4977](https://github.com/microsoft/WindowsAppSDK/issues/4977) - -**Diagnostic:** -``` -# Check installed MRM.dll version/timestamp -C:\Program Files\WindowsApps\Microsoft.WindowsAppRuntime.1.6_6000.318.2304.0_arm64__8wekyb3d8bbwe\MRM.dll -``` - -**Fix:** WASDK 1.6 has reached End of Support. Upgrade to WASDK 1.8 or later. -> Source: @alexlamtest (CONTRIBUTOR) in [#4977](https://github.com/microsoft/WindowsAppSDK/issues/4977) - -**Additional note:** @tpoint75 in [#4977](https://github.com/microsoft/WindowsAppSDK/issues/4977) also noted that runtime installers had incorrect version numbers. - ---- - -## ⚠️ Unverified / Community Suggestions - -> The following are community suggestions that have NOT been officially confirmed. - -- For #6248: Changing `AssemblyName` before build instead of post-publish rename may avoid the issue (community suggestion — untested) - ---- - -## Diagnostic Steps - -### For Scenario 1 (Renamed EXE crash): -```powershell -# Check original executable name from assembly metadata -[System.Reflection.AssemblyName]::GetAssemblyName("C:\path\to\published\app.exe").Name - -# Compare XAML resource URIs embedded in the assembly -# The URI paths reference the original assembly name -ildasm /text "C:\path\to\published\app.exe" | Select-String "ms-appx" -``` - -### For Scenario 2 (Broken links): -```powershell -# Test if aka.ms redirect resolves correctly -Invoke-WebRequest -Uri "https://aka.ms/windowsappsdk/2.0/2.0-preview1/windowsappruntimeinstall-x64.exe" -Method Head -``` - -### For Scenario 3 (Stale binaries): -```powershell -# Check installed MRM.dll file version and timestamp -Get-Item "C:\Program Files\WindowsApps\Microsoft.WindowsAppRuntime.1.6*\MRM.dll" | - Select-Object Name, VersionInfo, LastWriteTime - -# Compare against expected version from release tag -# Expected: built from v1.6.3 tag commit, not release/1.6-stable branch -``` - -### General version verification: -```powershell -# Check installed WASDK runtime version -Get-AppxPackage *WindowsAppRuntime* -AllUsers | Select-Object Name, Version, Architecture -``` - ---- - -## References - -- [WASDK Downloads](https://learn.microsoft.com/en-us/windows/apps/windows-app-sdk/downloads) -- [Single-file deployment docs](https://learn.microsoft.com/en-us/dotnet/core/deploying/single-file) -- [WASDK Release Notes](https://learn.microsoft.com/en-us/windows/apps/windows-app-sdk/stable-channel) - ---- - -**Updated:** 2026-03-13 | **Confidence:** 0.7 -**Sources:** #6248, #6220, #4977 +# Error: "XamlParseException: XAML parsing failed" — Renamed Single-File Unpackaged App / Broken Runtime Links + +**Keywords:** XamlParseException, XAML parsing failed, single-file, unpackaged, rename executable, PublishSingleFile, runtime links broken, 2.0 preview, installer binaries, MRM.dll crash + +**Error Example:** +``` +Microsoft.UI.Xaml.Markup.XamlParseException: XAML parsing failed. + at WinRT.ExceptionHelpers.g__Throw|38_0(Int32) + at ABI.Microsoft.UI.Xaml.IApplicationStaticsMethods.LoadComponent(...) + at Microsoft.UI.Xaml.Application.LoadComponent(Object, Uri, ComponentResourceLocation) + at TestApp1.MainWindow.InitializeComponent() +``` + +--- + +## Quick Match + +**You're seeing this if:** +- You published a WinUI 3 app as single-file unpackaged and renamed the `.exe` +- Error contains "XamlParseException" or "XAML parsing failed" after renaming +- WASDK 2.0 Preview runtime download links return 404 +- WASDK 1.6.3 installers ship binaries that still crash despite documented fixes + +→ Check scenarios below for your specific cause + +--- + +## Related Issues + +- [#6248](https://github.com/microsoft/WindowsAppSDK/issues/6248) — Renaming published executable makes Single-File Unpackaged App crash (Status: Open) +- [#6220](https://github.com/microsoft/WindowsAppSDK/issues/6220) — WASDK 2.0 Preview runtime links are broken (Status: Closed/Fixed) +- [#4977](https://github.com/microsoft/WindowsAppSDK/issues/4977) — 1.6.3 installers contain binaries built from older source code (Status: Closed) +- [#5031](https://github.com/microsoft/WindowsAppSDK/issues/5031) — `System.NotImplementedException` in `Microsoft.Windows.Management.Deployment.ResetPackageAsync` (Status: Closed) +- [#6058](https://github.com/microsoft/WindowsAppSDK/issues/6058) — "ClassFactory cannot supply requested class" in .NET MAUI (Status: Open) + +--- + +## Scenarios & Solutions + +### Scenario 1: Renaming Single-File Published Executable Causes XamlParseException + +**Cause:** When a WinUI 3 app is published as a single-file, self-contained, unpackaged app and the resulting `.exe` is renamed (e.g., `TestApp1.exe` → `TestApp11.exe`), XAML resource loading fails. The `Application.LoadComponent` call uses URI-based resource paths that are tied to the original executable name, so renaming breaks the lookup. +> Source: Issue reporter in [#6248](https://github.com/microsoft/WindowsAppSDK/issues/6248) + +**Reproduction config:** +```xml + + None + true + +``` +```xml + +true +true +true +``` + +**Fix:** No official fix available yet. **Do not rename the published executable.** + +**Workaround:** Keep the original executable name after publishing. If branding requires a different name, change the `AssemblyName` in your `.csproj` before publishing instead of renaming the output file. + +> ⚠️ @aepot in [#6248](https://github.com/microsoft/WindowsAppSDK/issues/6248) reports being stuck on WASDK 1.7 because of this bug. + +--- + +### Scenario 2: WASDK 2.0 Preview Runtime Download Links Broken + +**Cause:** The `aka.ms` download links for WASDK 2.0 Preview 1 runtime installers were returning 404 errors shortly after the preview release. +> Source: Issue reporter in [#6220](https://github.com/microsoft/WindowsAppSDK/issues/6220) + +**Affected links:** +``` +https://aka.ms/windowsappsdk/2.0/2.0-preview1/windowsappruntimeinstall-x64.exe +https://aka.ms/windowsappsdk/2.0/2.0-preview1/windowsappruntimeinstall-x86.exe +https://aka.ms/windowsappsdk/2.0/2.0-preview1/windowsappruntimeinstall-arm64.exe +https://aka.ms/windowsappsdk/2.0/2.0-preview1/Microsoft.WindowsAppRuntime.Redist.2.0.zip +``` + +**Fix:** Links have been corrected by Microsoft. +> ✅ Confirmed by: @lauren-ciha (MEMBER) in [#6220](https://github.com/microsoft/WindowsAppSDK/issues/6220) + +**Working Redist link:** +``` +https://aka.ms/windowsappsdk/2.0/2.0-preview1/Microsoft.WindowsAppRuntime.Redist.2.0-preview1.zip +``` + +**Verify:** Check the [official WASDK downloads page](https://learn.microsoft.com/en-us/windows/apps/windows-app-sdk/downloads) for current links. + +--- + +### Scenario 3: WASDK 1.6.3 Installers Contain Stale Binaries (MRM.dll Crash) + +**Cause:** The WASDK 1.6.3 (1.6.241114003) runtime installers shipped binaries built from an older commit in the `release/1.6-stable` branch rather than from the `v1.6.3` tag. Specifically, `MRM.dll` did not include the [buffer overrun fix](https://github.com/microsoft/WindowsAppSDK/commit/1db04b650194f090ba1b52ae48f61277737c19f0), causing crashes in apps that use MRT resource loading. +> Source: Issue reporter in [#4977](https://github.com/microsoft/WindowsAppSDK/issues/4977) + +**Diagnostic:** +``` +# Check installed MRM.dll version/timestamp +C:\Program Files\WindowsApps\Microsoft.WindowsAppRuntime.1.6_6000.318.2304.0_arm64__8wekyb3d8bbwe\MRM.dll +``` + +**Fix:** WASDK 1.6 has reached End of Support. Upgrade to WASDK 1.8 or later. +> Source: @alexlamtest (CONTRIBUTOR) in [#4977](https://github.com/microsoft/WindowsAppSDK/issues/4977) + +**Additional note:** @tpoint75 in [#4977](https://github.com/microsoft/WindowsAppSDK/issues/4977) also noted that runtime installers had incorrect version numbers. + +--- + +## Known Issues + +### Issue 1: `System.NotImplementedException` in `Microsoft.Windows.Management.Deployment.ResetPackageAsync` + +**Cause:** The `ResetPackageAsync` method in `Microsoft.Windows.Management.Deployment.PackageDeploymentManager` raises a `System.NotImplementedException`. The feature is not supported, as indicated by `PackageDeploymentManager.IsPackageDeploymentFeatureSupported(PackageDeploymentFeature.ResetPackage)` always returning `false`. +> Source: @whiskhub in [#5031](https://github.com/microsoft/WindowsAppSDK/issues/5031) + +**Workaround:** None. The API is not functional. Consider using PowerShell's `Reset-AppxPackage` as an alternative. + +**Additional context:** The documentation does not currently reflect the unsupported status of this API. + +--- + +### Issue 2: "ClassFactory cannot supply requested class" in .NET MAUI Single-File Executable + +**Cause:** When publishing a .NET MAUI application as a single-file executable with `WindowsAppSDKSelfContained` set to `true`, the application fails to start with the error "ClassFactory cannot supply requested class." This issue may be related to recent Windows updates or changes in the Windows SDK. +> Source: @ELY3M, @M0n7y5, @lars-hakansson in [#6058](https://github.com/microsoft/WindowsAppSDK/issues/6058) + +**Workaround:** None confirmed. Issue is under investigation. + +--- + +## ⚠️ Unverified / Community Suggestions + +> The following are community suggestions that have NOT been officially confirmed. + +- For #6248: Changing `AssemblyName` before build instead of post-publish rename may avoid the issue (community suggestion — untested) +- For #5031: Use PowerShell's `Reset-AppxPackage` as an alternative to `ResetPackageAsync`. + +--- + +## Diagnostic Steps + +### For Scenario 1 (Renamed EXE crash): +```powershell +# Check original executable name from assembly metadata +[System.Reflection.AssemblyName]::GetAssemblyName("C:\path\to\published\app.exe").Name + +# Compare XAML resource URIs embedded in the assembly +# The URI paths reference the original assembly name +ildasm /text "C:\path\to\published\app.exe" | Select-String "ms-appx" +``` + +### For Scenario 2 (Broken links): +```powershell +# Test if aka.ms redirect resolves correctly +Invoke-WebRequest -Uri "https://aka.ms/windowsappsdk/2.0/2.0-preview1/windowsappruntimeinstall-x64.exe" -Method Head +``` + +### For Scenario 3 (Stale binaries): +```powershell +# Check installed MRM.dll file version and timestamp +Get-Item "C:\Program Files\WindowsApps\Microsoft.WindowsAppRuntime.1.6*\MRM.dll" | + Select-Object Name, VersionInfo, LastWriteTime + +# Compare against expected version from release tag +# Expected: built from v1.6.3 tag commit, not release/1.6-stable branch +``` + +### General version verification: +```powershell +# Check installed WASDK runtime version +Get-AppxPackage *WindowsAppRuntime* -AllUsers | Select-Object Name, Version, Architecture +``` + +--- + +## References + +- [WASDK Downloads](https://learn.microsoft.com/en-us/windows/apps/windows-app-sdk/downloads) +- [Single-file deployment docs](https://learn.microsoft.com/en-us/dotnet/core/deploying/single-file) +- [WASDK Release Notes](https://learn.microsoft.com/en-us/windows/apps/windows-app-sdk/stable-channel) + +--- + +**Updated:** 2026-03-17 | **Confidence:** 0.7 +**Sources:** #6248, #6220, #4977, #5031, #6058 \ No newline at end of file diff --git a/tsg/tsg_deployment_wasdk18_windows10.md b/trouble-shooting-notes/tsg_deployment_wasdk18_windows10.md similarity index 78% rename from tsg/tsg_deployment_wasdk18_windows10.md rename to trouble-shooting-notes/tsg_deployment_wasdk18_windows10.md index 74b14d8..ef1d6cd 100644 --- a/tsg/tsg_deployment_wasdk18_windows10.md +++ b/trouble-shooting-notes/tsg_deployment_wasdk18_windows10.md @@ -1,173 +1,197 @@ -# Error: App Crash on Launch / "FindPackagesByPackageFamily" Failure — WASDK 1.8 on Windows 10 - -**Keywords:** FindPackagesByPackageFamily, WASDK 1.8, Windows 10, 17763, 19041, DeploymentManager, crash on launch, 0x80070005, DDLM PackageFullName, MSIX.inventory - -**Error Example:** -``` -Faulting module name: Microsoft.UI.Xaml.dll, version: 3.1.8.0 -Exception code: 0xc000027b -``` -``` -The program "[3468] App1.exe" has exited, returning 2147942405 (0x80070005). -``` - ---- - -## Quick Match - -**You're seeing this if:** -- WinUI 3 / WASDK 1.8+ packaged app crashes immediately on launch on Windows 10 (builds 17763, 19041, 19045) -- `FindPackagesByPackageFamily()` fails to locate WASDK 1.8 runtime packages on Windows 10 -- No error dialog — the app silently exits -- Same app works fine on Windows 11 - -→ Check scenarios below for your specific cause - ---- - -## Related Issues - -- [#6117](https://github.com/microsoft/WindowsAppSDK/issues/6117) — FindPackagesByPackageFamily unable to find WASDK 1.8 packages (Status: Open) -- [#6254](https://github.com/microsoft/WindowsAppSDK/issues/6254) — WindowAppSdk v1.8 cannot run on lower versions of Windows 10 (Status: Open) -- [#6156](https://github.com/microsoft/WindowsAppSDK/issues/6156) — MSIX.inventory has wrong DDLM PackageFullName (Status: Closed/Fixed) - ---- - -## Scenarios & Solutions - -### Scenario 1: DeploymentManager Auto-Initializer Fails on Windows 10 - -**Cause:** WASDK 1.8 includes a static global initializer that calls `FindPackagesByPackageFamily()` via `DeploymentManager.Initialize()`. On Windows 10 (especially builds 17763 and 19041), this call fails to find the runtime packages, causing the app to crash before any UI loads. The `WinAppRuntime.Main.1.8` package may not be registered, and `DeploymentManager.Initialize()` crashes instead of registering it. -> Source: @HO-COOH in [#6117](https://github.com/microsoft/WindowsAppSDK/issues/6117), confirmed in [#6254](https://github.com/microsoft/WindowsAppSDK/issues/6254) - -**Fix (C# projects):** -Add the following to your `.csproj` to disable the auto-initializer: -```xml - - false - -``` - -**Fix (C++ projects):** -Disable auto-initializer in your `.vcxproj`: -```xml - - false - -``` - -> ✅ Confirmed by: @HO-COOH in [#6117](https://github.com/microsoft/WindowsAppSDK/issues/6117), @Marv51 suggested the same workaround in [#6254](https://github.com/microsoft/WindowsAppSDK/issues/6254) - -**Verify:** -```powershell -# Confirm runtime packages are installed for the user -Get-AppxPackage micro*win*app*run*1.8* -AllUsers -# Confirm Main package registration -Get-AppxPackage MicrosoftCorporationII.WinAppRuntime.Main.1.8 -``` - ---- - -### Scenario 2: WinAppRuntime.Main.1.8 Package Not Registered - -**Cause:** On affected Windows 10 machines, `Get-AppxPackage MicrosoftCorporationII.WinAppRuntime.Main.1.8` returns nothing. The Framework packages (x86/x64) are registered but the Main package is missing. `DeploymentManager.Initialize()` is supposed to detect and register it, but crashes instead. -> Source: @DrusTheAxe and @HO-COOH in [#6117](https://github.com/microsoft/WindowsAppSDK/issues/6117) - -**Fix:** -1. Disable the auto-initializer as shown in Scenario 1. -2. If needed, manually register the Main package or reinstall the WASDK 1.8 runtime. - -**Diagnostic steps** (suggested by @DrusTheAxe in [#6117](https://github.com/microsoft/WindowsAppSDK/issues/6117)): -```powershell -# Check all WASDK 1.8 packages -Get-AppxPackage micro*win*app*run*1.8* -AllUsers -# Check your app's package -Get-AppxPackage *your*package*name* -AllUsers -# Check appxmanifest.xml for PackageDependency -# Verify TargetDeviceFamily MaxVersionTested values -``` - ---- - -### Scenario 3: MSIX.inventory Has Incorrect DDLM PackageFullName - -**Cause:** The `MSIX.inventory` file in the `Microsoft.WindowsAppSDK.Runtime` NuGet package listed an incorrect prefix for the DDLM package. The file used `Microsoft.WindowsAppRuntime.DDLM` but the actual installed package name uses `Microsoft.WinAppRuntime.DDLM`, causing package validation checks to fail. -> Source: Issue reporter in [#6156](https://github.com/microsoft/WindowsAppSDK/issues/6156) - -**Fix:** This was fixed in the aggregator. -> ✅ Confirmed by: @ssparach and @guimafelipe (CONTRIBUTOR) in [#6156](https://github.com/microsoft/WindowsAppSDK/issues/6156) - -**Verify:** -Check that the DDLM entry in `MSIX.inventory` uses the `Microsoft.WinAppRuntime.DDLM` prefix: -``` -Microsoft.WindowsAppRuntime.DDLM.1.8.msix=Microsoft.WinAppRuntime.DDLM.-... -``` - ---- - -### Scenario 4: Third-Party Apps (AppInstaller, Xbox) Also Crashing - -**Cause:** The issue is not limited to custom apps. Any app using `WindowsAppRuntime.1.8` framework can crash on Windows 10, including first-party Microsoft apps like AppInstaller and Xbox. -> Source: @RemyYYZ in [#6117](https://github.com/microsoft/WindowsAppSDK/issues/6117) and [#6254](https://github.com/microsoft/WindowsAppSDK/issues/6254) - -**Symptoms:** -``` -Faulting application name: AppInstaller.exe, version: 1.27.460.0 -Faulting module name: Microsoft.UI.Xaml.dll, version: 3.1.8.0 -Exception code: 0xc000027b -Windows Version: 10.0.19045.6937 -``` - -**Fix:** -No user-side workaround for pre-built apps. This requires a fix from Microsoft in the WASDK runtime. For your own apps, use the auto-initializer disable workaround from Scenario 1. - ---- - -## ⚠️ Unverified / Community Suggestions - -> The following are community suggestions that have NOT been officially confirmed. - -- Changing `TargetDeviceFamily` `MaxVersionTested` to match between `Windows.Universal` and `Windows.Desktop` may help (from @DrusTheAxe in #6117) -- Downgrade to WASDK 1.7 as a temporary measure — confirmed working on Windows 10 (from @lgBlog in #6254) - ---- - -## Diagnostic Steps - -```powershell -# 1. Check Windows version -winver.exe -# Or programmatically: -[System.Environment]::OSVersion.Version - -# 2. Check all WASDK 1.8 runtime packages -Get-AppxPackage micro*win*app*run*1.8* -AllUsers - -# 3. Check if Main package is registered (should NOT be empty) -Get-AppxPackage MicrosoftCorporationII.WinAppRuntime.Main.1.8 - -# 4. Check your app's package dependencies -# Open your appxmanifest.xml and look for: -# - -# 5. Check Event Viewer for crash details -Get-WinEvent -LogName Application -MaxEvents 20 | - Where-Object { $_.Message -like "*WindowsAppRuntime*" -or $_.Message -like "*Microsoft.UI.Xaml*" } - -# 6. Verify DDLM package name format in MSIX.inventory -# Navigate to NuGet package cache and check: -# .nuget\packages\microsoft.windowsappsdk.runtime\\tools\MSIX\\MSIX.inventory -``` - ---- - -## References - -- [WASDK Deployment project properties](https://learn.microsoft.com/en-us/windows/apps/package-and-deploy/project-properties) -- [WASDK Downloads](https://learn.microsoft.com/en-us/windows/apps/windows-app-sdk/downloads) -- [DeploymentManager.Initialize API](https://learn.microsoft.com/en-us/windows/windows-app-sdk/api/winrt/microsoft.windows.applicationmodel.windowsappruntime.deploymentmanager.initialize) - ---- - -**Updated:** 2026-03-13 | **Confidence:** 0.8 -**Sources:** #6117, #6254, #6156 +# Error: App Crash on Launch / "FindPackagesByPackageFamily" Failure — WASDK 1.8 on Windows 10 + +**Keywords:** FindPackagesByPackageFamily, WASDK 1.8, Windows 10, 17763, 19041, DeploymentManager, crash on launch, 0x80070005, DDLM PackageFullName, MSIX.inventory, DeploymentManager.Initialize, experimental builds + +**Error Example:** +``` +Faulting module name: Microsoft.UI.Xaml.dll, version: 3.1.8.0 +Exception code: 0xc000027b +``` +``` +The program "[3468] App1.exe" has exited, returning 2147942405 (0x80070005). +``` + +--- + +## Quick Match + +**You're seeing this if:** +- WinUI 3 / WASDK 1.8+ packaged app crashes immediately on launch on Windows 10 (builds 17763, 19041, 19045) +- `FindPackagesByPackageFamily()` fails to locate WASDK 1.8 runtime packages on Windows 10 +- `DeploymentManager.Initialize()` causes a fast fail crash +- No error dialog — the app silently exits +- Same app works fine on Windows 11 + +→ Check scenarios below for your specific cause + +--- + +## Related Issues + +- [#6117](https://github.com/microsoft/WindowsAppSDK/issues/6117) — FindPackagesByPackageFamily unable to find WASDK 1.8 packages (Status: Open) +- [#6254](https://github.com/microsoft/WindowsAppSDK/issues/6254) — WindowAppSdk v1.8 cannot run on lower versions of Windows 10 (Status: Open) +- [#6156](https://github.com/microsoft/WindowsAppSDK/issues/6156) — MSIX.inventory has wrong DDLM PackageFullName (Status: Closed/Fixed) +- [#5605](https://github.com/microsoft/WindowsAppSDK/issues/5605) — 1.8 exp4: App crashes at `DeploymentManager.Initialize();` (Status: Closed) + +--- + +## Scenarios & Solutions + +### Scenario 1: DeploymentManager Auto-Initializer Fails on Windows 10 + +**Cause:** WASDK 1.8 includes a static global initializer that calls `FindPackagesByPackageFamily()` via `DeploymentManager.Initialize()`. On Windows 10 (especially builds 17763 and 19041), this call fails to find the runtime packages, causing the app to crash before any UI loads. The `WinAppRuntime.Main.1.8` package may not be registered, and `DeploymentManager.Initialize()` crashes instead of registering it. +> Source: @HO-COOH in [#6117](https://github.com/microsoft/WindowsAppSDK/issues/6117), confirmed in [#6254](https://github.com/microsoft/WindowsAppSDK/issues/6254) + +**Fix (C# projects):** +Add the following to your `.csproj` to disable the auto-initializer: +```xml + + false + +``` + +**Fix (C++ projects):** +Disable auto-initializer in your `.vcxproj`: +```xml + + false + +``` + +> ✅ Confirmed by: @HO-COOH in [#6117](https://github.com/microsoft/WindowsAppSDK/issues/6117), @Marv51 suggested the same workaround in [#6254](https://github.com/microsoft/WindowsAppSDK/issues/6254) + +**Verify:** +```powershell +# Confirm runtime packages are installed for the user +Get-AppxPackage micro*win*app*run*1.8* -AllUsers +# Confirm Main package registration +Get-AppxPackage MicrosoftCorporationII.WinAppRuntime.Main.1.8 +``` + +--- + +### Scenario 2: WinAppRuntime.Main.1.8 Package Not Registered + +**Cause:** On affected Windows 10 machines, `Get-AppxPackage MicrosoftCorporationII.WinAppRuntime.Main.1.8` returns nothing. The Framework packages (x86/x64) are registered but the Main package is missing. `DeploymentManager.Initialize()` is supposed to detect and register it, but crashes instead. +> Source: @DrusTheAxe and @HO-COOH in [#6117](https://github.com/microsoft/WindowsAppSDK/issues/6117) + +**Fix:** +1. Disable the auto-initializer as shown in Scenario 1. +2. If needed, manually register the Main package or reinstall the WASDK 1.8 runtime. + +**Diagnostic steps** (suggested by @DrusTheAxe in [#6117](https://github.com/microsoft/WindowsAppSDK/issues/6117)): +```powershell +# Check all WASDK 1.8 packages +Get-AppxPackage micro*win*app*run*1.8* -AllUsers +# Check your app's package +Get-AppxPackage *your*package*name* -AllUsers +# Check appxmanifest.xml for PackageDependency +# Verify TargetDeviceFamily MaxVersionTested values +``` + +--- + +### Scenario 3: MSIX.inventory Has Incorrect DDLM PackageFullName + +**Cause:** The `MSIX.inventory` file in the `Microsoft.WindowsAppSDK.Runtime` NuGet package listed an incorrect prefix for the DDLM package. The file used `Microsoft.WindowsAppRuntime.DDLM` but the actual installed package name uses `Microsoft.WinAppRuntime.DDLM`, causing package validation checks to fail. +> Source: Issue reporter in [#6156](https://github.com/microsoft/WindowsAppSDK/issues/6156) + +**Fix:** This was fixed in the aggregator. +> ✅ Confirmed by: @ssparach and @guimafelipe (CONTRIBUTOR) in [#6156](https://github.com/microsoft/WindowsAppSDK/issues/6156) + +**Verify:** +Check that the DDLM entry in `MSIX.inventory` uses the `Microsoft.WinAppRuntime.DDLM` prefix: +``` +Microsoft.WindowsAppRuntime.DDLM.1.8.msix=Microsoft.WinAppRuntime.DDLM.-... +``` + +--- + +### Scenario 4: DeploymentManager.Initialize() Called Explicitly in Packaged Apps + +**Cause:** In WASDK 1.8 experimental builds, explicitly calling `DeploymentManager.Initialize()` in packaged apps causes a fast fail crash. This is because the auto-initializer is already enabled by default, and calling the API explicitly results in duplicate initialization attempts. +> Source: @ssparach in [#5605](https://github.com/microsoft/WindowsAppSDK/issues/5605) + +**Fix:** +Disable the auto-initializer in your `.csproj` file: +```xml + + false + +``` + +> ✅ Confirmed by: @ssparach in [#5605](https://github.com/microsoft/WindowsAppSDK/issues/5605) + +**Verify:** +Ensure the crash is resolved after applying the fix. If the issue persists, check for other scenarios listed in this guide. + +--- + +### Scenario 5: Third-Party Apps (AppInstaller, Xbox) Also Crashing + +**Cause:** The issue is not limited to custom apps. Any app using `WindowsAppRuntime.1.8` framework can crash on Windows 10, including first-party Microsoft apps like AppInstaller and Xbox. +> Source: @RemyYYZ in [#6117](https://github.com/microsoft/WindowsAppSDK/issues/6117) and [#6254](https://github.com/microsoft/WindowsAppSDK/issues/6254) + +**Symptoms:** +``` +Faulting application name: AppInstaller.exe, version: 1.27.460.0 +Faulting module name: Microsoft.UI.Xaml.dll, version: 3.1.8.0 +Exception code: 0xc000027b +Windows Version: 10.0.19045.6937 +``` + +**Fix:** +No user-side workaround for pre-built apps. This requires a fix from Microsoft in the WASDK runtime. For your own apps, use the auto-initializer disable workaround from Scenario 1. + +--- + +## ⚠️ Known Issues / Unverified Suggestions + +### Known Issue: FindPackagesByPackageFamily Fails on Older Windows 10 Versions + +**Cause:** On Windows 10 17763, `FindPackagesByPackageFamily()` fails to locate WASDK 1.8 runtime packages, causing `DeploymentManager.Initialize()` to crash. This affects all apps using WASDK 1.8 unless the auto-initializer is disabled. +> Source: @HO-COOH in [#6117](https://github.com/microsoft/WindowsAppSDK/issues/6117) + +**Workaround:** Disable the auto-initializer as described in Scenario 1. No permanent fix is available yet. + +--- + +## Diagnostic Steps + +```powershell +# 1. Check Windows version +winver.exe +# Or programmatically: +[System.Environment]::OSVersion.Version + +# 2. Check all WASDK 1.8 runtime packages +Get-AppxPackage micro*win*app*run*1.8* -AllUsers + +# 3. Check if Main package is registered (should NOT be empty) +Get-AppxPackage MicrosoftCorporationII.WinAppRuntime.Main.1.8 + +# 4. Check your app's package dependencies +# Open your appxmanifest.xml and look for: +# + +# 5. Check Event Viewer for crash details +Get-WinEvent -LogName Application -MaxEvents 20 | + Where-Object { $_.Message -like "*WindowsAppRuntime*" -or $_.Message -like "*Microsoft.UI.Xaml*" } + +# 6. Verify DDLM package name format in MSIX.inventory +# Navigate to NuGet package cache and check: +# .nuget\packages\microsoft.windowsappsdk.runtime\\tools\MSIX\\MSIX.inventory +``` + +--- + +## References + +- [WASDK Deployment project properties](https://learn.microsoft.com/en-us/windows/apps/package-and-deploy/project-properties) +- [WASDK Downloads](https://learn.microsoft.com/en-us/windows/apps/windows-app-sdk/downloads) +- [DeploymentManager.Initialize API](https://learn.microsoft.com/en-us/windows/windows-app-sdk/api/winrt/microsoft.windows.applicationmodel.windowsappruntime.deploymentmanager.initialize) + +--- + +**Updated:** 2026-03-17 | **Confidence:** 0.9 +**Sources:** #6117, #6254, #6156, #5605 \ No newline at end of file diff --git a/trouble-shooting-notes/tsg_documentation_and_templates.md b/trouble-shooting-notes/tsg_documentation_and_templates.md new file mode 100644 index 0000000..d9c38d4 --- /dev/null +++ b/trouble-shooting-notes/tsg_documentation_and_templates.md @@ -0,0 +1,167 @@ +# Error: "Missing Windows versions in bug template" - Bug Template Issue + +**Keywords:** bug template, missing Windows versions, Windows App SDK, 26100, 26120, 26200 + +**Error Example:** +``` +The bug template target Windows version is missing 26100, 26120, 26200 +``` + +--- + +## Quick Match + +**You're seeing this if:** +- You notice that the bug template for reporting issues in the Windows App SDK is missing Windows versions 26100, 26120, and 26200. +- You are using the bug template provided in the Windows App SDK repository. + +→ Check scenarios below for your specific cause. + +--- + +## Related Issues + +- [#5534](https://github.com/microsoft/WindowsAppSDK/issues/5534) - The bug template target Windows version is missing versions 26100, 26120, 26200 (Status: Closed, Fixed in PR) + +--- + +## Scenarios & Solutions + +### Scenario 1: Missing Windows versions in the bug template + +**Cause:** The bug template in the Windows App SDK repository was outdated and did not include Windows versions 26100, 26120, and 26200. +> Source: @RDMacLachlan [MSFT] in [#5534](https://github.com/microsoft/WindowsAppSDK/issues/5534) + +**Fix:** +1. Update the bug template in the repository to include the missing Windows versions. +2. Ensure the updated template is merged into the main branch. + +> ✅ Confirmed by: @RDMacLachlan [MSFT] in issue comments. + +**Verify:** Check the latest bug template in the repository to confirm that versions 26100, 26120, and 26200 are now listed. + +--- + +# Error: "C# template missing file-scoped namespace changes" - Visual Studio Templates Issue + +**Keywords:** C# template, file-scoped namespaces, Visual Studio 17.14 Preview 3, Windows App SDK templates + +**Error Example:** +``` +I just downloaded VS 17.14 Preview 3, I see some of the template changes, but not all of them. The file-scoped namespaces for instance aren't there...? But I see them in `main`. +``` + +--- + +## Quick Match + +**You're seeing this if:** +- You are using Visual Studio 17.14 Preview 3 or later. +- You notice that the C# project templates for the Windows App SDK do not include file-scoped namespaces, even though they appear in the repository's main branch. + +→ Check scenarios below for your specific cause. + +--- + +## Related Issues + +- [#5350](https://github.com/microsoft/WindowsAppSDK/issues/5350) - VS 17.14 Preview 3 C# template missing file-scoped namespace changes (Status: Open) + +--- + +## Scenarios & Solutions + +### Scenario 1: Template changes not fully shipped by Visual Studio + +**Cause:** The updated C# templates with file-scoped namespaces were not yet shipped by the Visual Studio team, even though they appear in the repository's main branch. +> Source: @haonanttt [MSFT] in [#5350](https://github.com/microsoft/WindowsAppSDK/issues/5350) + +**Fix:** +1. Verify the installed version of the Windows App SDK template extension: + - Navigate to "Extensions -> Manage Extensions -> Installed." + - Search for `template` and locate the Windows App SDK C# VS2022 Templates. +2. Update to the latest version of Visual Studio Preview and ensure the templates are updated. + +> ✅ Confirmed by: @michael-hawker [MSFT] in issue comments. + +**Verify:** Create a new project using the updated templates and check if file-scoped namespaces are included. + +--- + +## ⚠️ Unverified / Community Suggestions + +> The following are community suggestions that have NOT been officially confirmed. + +- Check the Visual Studio settings for block vs. file-scoped namespaces under "Options -> Text Editor -> C# -> Code Style settings." + > Source: @michael-hawker [MSFT] in [#5350](https://github.com/microsoft/WindowsAppSDK/issues/5350) + +--- + +# Error: "How to use XAML Island in Windows App SDK 1.7 for XAML hosting?" - XAML Island Usage + +**Keywords:** XAML Island, Windows App SDK 1.7, XAML hosting, DesktopChildSiteBridge, XamlIsland Class + +**Error Example:** +``` +What’s the correct way to host WinUI 3 content (XAML) using XAML Islands with the Windows App SDK 1.7? +``` + +--- + +## Quick Match + +**You're seeing this if:** +- You are using Windows App SDK 1.7 and want to host WinUI 3 content using XAML Islands. +- You are looking for examples or documentation on how to implement XAML hosting. + +→ Check scenarios below for your specific cause. + +--- + +## Related Issues + +- [#5625](https://github.com/microsoft/WindowsAppSDK/issues/5625) - How to use XAML Island in Windows App SDK 1.7 for XAML hosting? Any sample code? (Status: Closed) + +--- + +## Scenarios & Solutions + +### Scenario 1: Using XAML Islands with DesktopChildSiteBridge + +**Cause:** Developers may not be familiar with the updated process for hosting XAML content using XAML Islands in Windows App SDK 1.7. +> Source: @DarranRowe in [#5625](https://github.com/microsoft/WindowsAppSDK/issues/5625) + +**Fix:** +1. Ensure your application creates an instance of `App` as a prerequisite. +2. Use the `DesktopChildSiteBridge` class to create a connection to the parent window: + - Call `DesktopChildSiteBridge.CreateWithDispatcherQueue`. + - Use the `Connect()` method to establish the connection. +3. Create a `XamlIsland` instance and configure it as needed. +4. Set the `ResizePolicy` to `ContentSizePolicy.ResizeContentToParentWindow`. +5. Call the `Show()` method to display the XAML content. + +> ✅ Confirmed by: @castorix, @Ajith-GS in issue comments. + +**Verify:** Run the application and confirm that the XAML content is hosted correctly using XAML Islands. + +--- + +## ⚠️ Unverified / Community Suggestions + +> The following are community suggestions that have NOT been officially confirmed. + +- Explore the [DesktopWindowXamlSource Class](https://learn.microsoft.com/en-us/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.desktopwindowxamlsource?view=windows-app-sdk-1.7) as an alternative for XAML hosting. + > Source: @castorix in [#5625](https://github.com/microsoft/WindowsAppSDK/issues/5625) + +--- + +## References + +- [Windows App SDK Samples - XAML Islands](https://github.com/microsoft/WindowsAppSDK-Samples/tree/main/Samples/Islands) +- [DesktopChildSiteBridge Class Documentation](https://learn.microsoft.com/en-us/windows/windows-app-sdk/api/winrt/microsoft.ui.content.desktopchildsitebridge?view=windows-app-sdk-1.7) +- [XamlIsland Class Documentation](https://learn.microsoft.com/en-us/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.xamlisland?view=windows-app-sdk-1.7) + +--- + +**Updated:** 2026-03-17 | **Confidence:** 0.9 +**Sources:** [#5534](https://github.com/microsoft/WindowsAppSDK/issues/5534), [#5350](https://github.com/microsoft/WindowsAppSDK/issues/5350), [#5625](https://github.com/microsoft/WindowsAppSDK/issues/5625) \ No newline at end of file diff --git a/trouble-shooting-notes/tsg_documentation_gaps.md b/trouble-shooting-notes/tsg_documentation_gaps.md new file mode 100644 index 0000000..58c7fae --- /dev/null +++ b/trouble-shooting-notes/tsg_documentation_gaps.md @@ -0,0 +1,103 @@ +# Documentation Gaps and Errors in Windows App SDK + +**Keywords:** missing documentation, broken links, experimental APIs, AppWindow, Windows App SDK, downloads archive, release notes + +**Error Example:** +``` +Was working on a partner app and received the following runtime error: + +[Image showing runtime error] +``` + +--- + +## Quick Match + +**You're seeing this if:** +- You encounter missing or incorrect documentation for Windows App SDK releases or APIs. +- You cannot find specific runtime versions in the downloads archive. +- You notice broken links or incorrect information in release notes or documentation pages. + +→ Check scenarios below for your specific cause. + +--- + +## Related Issues + +- [#5938](https://github.com/microsoft/WindowsAppSDK/issues/5938) - Windows App Runtime 1.8-experimental releases missing from archive (Status: Closed) +- [#5896](https://github.com/microsoft/WindowsAppSDK/issues/5896) - Missing documentation and release plans for new AppWindow placement APIs (experimental) (Status: Open) +- [#5727](https://github.com/microsoft/WindowsAppSDK/issues/5727) - 1.8-preview documentation contains errors, broken links (Status: Closed) +- [#5351](https://github.com/microsoft/WindowsAppSDK/issues/5351) - Windows App SDK 1.7-exp releases are missing from downloads page (Status: Closed) +- [#5522](https://github.com/microsoft/WindowsAppSDK/issues/5522) - Windows App SDK 1.8 Experimental 3 runtimes missing (Status: Closed) + +--- + +## Scenarios & Solutions + +### Scenario 1: Missing runtime versions in the downloads archive + +**Cause:** Specific experimental runtime versions were not properly listed in the downloads archive due to documentation update delays. +> Source: @riverar in [#5938](https://github.com/microsoft/WindowsAppSDK/issues/5938) + +**Fix:** +1. Check the [downloads archive](https://learn.microsoft.com/en-us/windows/apps/windows-app-sdk/downloads-archive#windows-app-sdk-18-experimental) for the runtime versions. Experimental versions are listed after the stable and preview sections. +2. If the version is still missing, refer to the direct download links provided in the issue comments (if available). + +> ✅ Confirmed by: @riverar in [#5938](https://github.com/microsoft/WindowsAppSDK/issues/5938) + +**Verify:** Ensure the runtime version you need is listed and accessible in the downloads archive. + +--- + +### Scenario 2: Missing or incomplete documentation for experimental APIs + +**Cause:** Experimental APIs often receive minimal documentation, with only stubs or basic references available. +> Source: @Karl-Bridge-Microsoft in [#5896](https://github.com/microsoft/WindowsAppSDK/issues/5896) + +**Fix:** +1. Use the version dropdown in the API reference to select the correct experimental version (e.g., 1.8 Experimental). +2. Refer to the [AppWindowPlacement spec](https://github.com/microsoft/WindowsAppSDK/blob/afd4ac42a32a329f4fdfc76d7d443a0200774135/specs/Windowing/AppWindowPlacement.md) for additional details on experimental APIs. +3. Note that some APIs, such as `SaveCurrentPlacementForAllPersistedStateIds`, require a `PersistedStateId` to function properly. + > Source: @Lightczx in [#5896](https://github.com/microsoft/WindowsAppSDK/issues/5896) + +**Verify:** Confirm that the API reference or spec provides the information you need to use the APIs effectively. + +--- + +### Scenario 3: Broken links or incorrect information in release notes + +**Cause:** Errors in the documentation update process can result in broken links, incorrect titles, or missing information. +> Source: @riverar in [#5727](https://github.com/microsoft/WindowsAppSDK/issues/5727) + +**Fix:** +1. Use the following checklist to verify release notes and downloads: + - Ensure release notes have the correct title, version, and matching NuGet package version. + - Verify that download links point to the correct files and are placed in the appropriate sections (Stable / Preview / Experimental). + - Confirm that all features and changes are documented in the release notes. +2. If links are broken, check for updates or corrections in the issue comments or related GitHub pull requests. + +> ✅ Confirmed by: @riverar in [#5727](https://github.com/microsoft/WindowsAppSDK/issues/5727) + +**Verify:** Test the corrected links and ensure they lead to the intended resources. + +--- + +## ⚠️ Unverified / Community Suggestions + +> The following are community suggestions that have NOT been officially confirmed. + +- Use the [OMD tool](https://github.com/dotMorten/DotNetOMDGenerator) to analyze API changes in experimental releases. + > Source: @ghost1372 in [#5522](https://github.com/microsoft/WindowsAppSDK/issues/5522) + +--- + +## References + +- [Windows App SDK Downloads Archive](https://learn.microsoft.com/en-us/windows/apps/windows-app-sdk/downloads-archive) +- [AppWindowPlacement Spec](https://github.com/microsoft/WindowsAppSDK/blob/afd4ac42a32a329f4fdfc76d7d443a0200774135/specs/Windowing/AppWindowPlacement.md) +- [Windows App SDK API Reference](https://learn.microsoft.com/en-us/windows/windows-app-sdk/api/) + +--- + +**Updated:** 2026-03-17 | **Confidence:** 0.9 +**Sources:** [#5938](https://github.com/microsoft/WindowsAppSDK/issues/5938), [#5896](https://github.com/microsoft/WindowsAppSDK/issues/5896), [#5727](https://github.com/microsoft/WindowsAppSDK/issues/5727), [#5351](https://github.com/microsoft/WindowsAppSDK/issues/5351), [#5522](https://github.com/microsoft/WindowsAppSDK/issues/5522) \ No newline at end of file diff --git a/trouble-shooting-notes/tsg_dynamic_dependencies_ci.md b/trouble-shooting-notes/tsg_dynamic_dependencies_ci.md new file mode 100644 index 0000000..10ceaf9 --- /dev/null +++ b/trouble-shooting-notes/tsg_dynamic_dependencies_ci.md @@ -0,0 +1,72 @@ +# Error: "Tests hang in GitHub Actions CI after updating to WinAppSDK 1.8.250907003" + +**Keywords:** tests hang, GitHub Actions, CI, bootstrapper initializer, WinAppSDK 1.8, Windows App SDK Runtime Framework package + +**Error Example:** +``` +Tests hang indefinitely after updating to Windows App SDK 1.8.250907003. No specific error message is displayed, but the CI pipeline does not complete. +``` + +--- + +## Quick Match + +**You're seeing this if:** +- Tests hang indefinitely in GitHub Actions CI after updating to Windows App SDK 1.8.250907003. +- The project uses the Windows App SDK but does not include the Runtime Framework package in the CI environment. +- Platform: GitHub Actions CI. + +→ Check scenarios below for your specific cause. + +--- + +## Related Issues + +- [#5851](https://github.com/microsoft/WindowsAppSDK/issues/5851) - WinAppSDK 1.8.250907003 Fails to run tests in GitHub Actions CI (Status: Closed) + +--- + +## Scenarios & Solutions + +### Scenario 1: Missing Runtime Framework Package in CI Environment + +**Cause:** +With Windows App SDK 1.8, the bootstrapper initializer is automatically enabled by default. This requires the Windows App SDK Runtime Framework package to be installed. If the package is not present, the application shows an error UI and the tests hang indefinitely. +> Source: @ssparach [MSFT] in [#5851](https://github.com/microsoft/WindowsAppSDK/issues/5851) + +**Fix:** +Option 1: Disable the bootstrapper initializer in the project file. +1. Open your `.csproj` file. +2. Add the following line inside a ``: + ```xml + false + ``` + +Option 2: Install the Runtime Framework package as part of your CI build process. +1. Add a step in your GitHub Actions workflow to install the Windows App SDK Runtime Framework package. + For example, you can use the installer provided by Microsoft as part of your build process. + +> ✅ Confirmed by: @ssparach [MSFT], @abdes in issue comments + +**Verify:** +- For Option 1: Ensure the tests run successfully in the CI environment without hanging. +- For Option 2: Verify that the Runtime Framework package is installed in the CI environment and the tests complete successfully. + +--- + +## ⚠️ Unverified / Community Suggestions + +> The following are community suggestions that have NOT been officially confirmed. + +- None provided in the issue comments. + +--- + +## References + +- [Issue #5851](https://github.com/microsoft/WindowsAppSDK/issues/5851) + +--- + +**Updated:** 2026-03-17 | **Confidence:** 0.9 +**Sources:** [#5851](https://github.com/microsoft/WindowsAppSDK/issues/5851) \ No newline at end of file diff --git a/tsg/tsg_external_interop_issues.md b/trouble-shooting-notes/tsg_external_interop_issues.md similarity index 84% rename from tsg/tsg_external_interop_issues.md rename to trouble-shooting-notes/tsg_external_interop_issues.md index 5604874..9e61a9e 100644 --- a/tsg/tsg_external_interop_issues.md +++ b/trouble-shooting-notes/tsg_external_interop_issues.md @@ -1,191 +1,214 @@ -# External / Interop Issues — Packaging, Device APIs, and Widgets - -**Keywords:** packaging project, NuGet, stale assembly, MSIX bundle, FindPackagesByPackageFamily, 0x8007007A, ERROR_INSUFFICIENT_BUFFER, DeviceInformationPairing, Bluetooth, ProximityDevice, NFC, Widgets, WinUI 3 - -**Error Example:** -``` -WinRT error 0x8007007A: "The data area passed to a system call is too small." - at FindPackagesByPackageFamily() -``` -``` -System.InvalidCastException - at WinRT.Interop.InitializeWithWindow.Initialize(DeviceInformation.Pairing, windowHandle) -``` - ---- - -## Quick Match - -**You're seeing this if:** -- MSIX bundle contains wrong (stale) NuGet DLL versions after package downgrade -- Error `0x8007007A` on app startup from `FindPackagesByPackageFamily` -- Bluetooth device pairing UI fails to show in WinUI 3 desktop app -- NFC `ProximityDevice` events never fire after UWP → WinUI 3 migration -- Widgets panel: first widget (alphabetically) cannot be added - -→ Check scenarios below for your specific cause - ---- - -## Related Issues - -- [#6253](https://github.com/microsoft/WindowsAppSDK/issues/6253) — Packaging project caches stale NuGet assembly references across builds (Status: Closed) -- [#6274](https://github.com/microsoft/WindowsAppSDK/issues/6274) — WinRT error 0x8007007A in `FindPackagesByPackageFamily` (Status: Open) -- [#3091](https://github.com/microsoft/WindowsAppSDK/issues/3091) — Unable to display device pairing UI in WinUI 3 app (Status: Closed) -- [#4356](https://github.com/microsoft/WindowsAppSDK/issues/4356) — ProximityDevice NFC events not triggered (Status: Open) -- [#6140](https://github.com/microsoft/WindowsAppSDK/issues/6140) — Widget at top of list cannot be added until switching away (Status: Open) - ---- - -## Scenarios & Solutions - -### Scenario 1: Packaging Project Caches Stale NuGet Assembly References Across Builds - -**Cause:** When using the Packaging project to produce MSIX bundles, downgrading (or upgrading) a NuGet package reference and rebuilding results in the previously-built DLL version being included in the bundle. Neither **Clean Solution** nor restarting Visual Studio resolves this. The packaging project caches assembly paths and does not properly invalidate them when NuGet versions change. -> Source: Issue [#6253](https://github.com/microsoft/WindowsAppSDK/issues/6253) — also filed on [VS Developer Community](https://developercommunity.visualstudio.com/t/Packaging-project-caches-stale-NuGet-ass/110512955) - -**Affected versions:** Visual Studio 2026, Windows App SDK (MSIX packaging), any NuGet package - -**Repro:** -1. Reference `CommunityToolkit.Mvvm` version **8.3.2**, build MSIX bundle → DLL is 8.3.2.1 ✅ -2. Upgrade to **8.4.0**, Clean Solution, rebuild → DLL is 8.4.0.1 ✅ -3. Downgrade back to **8.3.2**, Clean Solution, rebuild → DLL is still **8.4.0.1** ⚠️ - -**Fix:** -1. **Manually delete the packaging project output folders** before rebuilding: - - Delete `App1 (Package)\AppPackages\` folder - - Delete `App1 (Package)\bin\` and `App1 (Package)\obj\` folders -2. **Force a full NuGet restore** after version change: -```powershell -dotnet nuget locals all --clear -dotnet restore -``` -3. **Rebuild** (not just Build) the entire solution after clearing caches. - -**Verify:** Open the resulting `.msixbundle` in 7-Zip and confirm the DLL version matches the referenced NuGet version. - ---- - -### Scenario 2: WinRT Error 0x8007007A — "Data Area Passed to a System Call Is Too Small" - -**Cause:** On app startup, `FindPackagesByPackageFamily` reports `ERROR_INSUFFICIENT_BUFFER` (HRESULT `0x8007007A`). The debugger shows `bufferLength = 80` and corrupted locals (huge vector size, invalid pointer), indicating a buffer overflow. The root cause is a buffer size mismatch: the API returns a required **character count** for a `PWSTR` buffer, but the calling code likely allocated `bufferLength` **bytes** instead of `bufferLength * sizeof(wchar_t)`. -> Source: Issue [#6274](https://github.com/microsoft/WindowsAppSDK/issues/6274) - -**Affected versions:** Windows App SDK 1.8.5 (1.8.260209005), Windows 11 24H2 - -**Important note:** This exception surfaces only when **"Break when thrown"** is enabled for all exceptions in Visual Studio's Exception Settings. In normal execution, the SDK may handle this internally. - -**Fix:** -1. **Check if this is a first-chance exception only.** Uncheck "Break when thrown" for `WinRT originate error` exceptions in Visual Studio → Exception Settings. If the app runs normally, this is an internal SDK exception that is caught and handled. -2. If calling `FindPackagesByPackageFamily` in your own code, ensure proper two-call pattern: -```cpp -UINT32 count = 0; -UINT32 bufferLength = 0; -// First call: get required sizes -FindPackagesByPackageFamily(familyName, PACKAGE_FILTER_HEAD, &count, nullptr, &bufferLength, nullptr, nullptr); -// Allocate with correct units (characters, not bytes) -PWSTR buffer = new WCHAR[bufferLength]; // bufferLength is in characters -PWSTR* packageFullNames = new PWSTR[count]; -// Second call: retrieve data -FindPackagesByPackageFamily(familyName, PACKAGE_FILTER_HEAD, &count, packageFullNames, &bufferLength, buffer, nullptr); -``` -3. Handle `ERROR_INSUFFICIENT_BUFFER` return code as expected (it is the normal first-call response). - -**Verify:** Run app with first-chance exception breaking disabled and confirm no user-visible crash. - ---- - -### Scenario 3: Device Pairing UI Does Not Display in WinUI 3 Desktop App - -**Cause:** Calling `DeviceInformationPairing.PairAsync()` in a WinUI 3 desktop app does not show the system Bluetooth pairing UI. The pairing process silently fails after a few seconds. The `IInitializeWithWindow` workaround documented for other UWP controls throws `System.InvalidCastException` when applied to `DeviceInformation` or `DeviceInformation.Pairing` because these objects do not implement `IInitializeWithWindow`. -> Source: Issue [#3091](https://github.com/microsoft/WindowsAppSDK/issues/3091) - -**Affected versions:** Windows App SDK 1.0+, Windows 11 (21H2) - -**Fix:** -1. **Use `DeviceInformationCustomPairing`** with a custom handler instead of the automatic pairing UI: -```csharp -var customPairing = deviceInfo.Pairing.Custom; -customPairing.PairingRequested += (sender, args) => -{ - // Handle pairing ceremony in your own UI - args.Accept(); // or args.Accept(pin) for PIN-based pairing -}; -var result = await customPairing.PairAsync( - DevicePairingKinds.ConfirmOnly | DevicePairingKinds.DisplayPin); -``` -2. **Build your own pairing confirmation dialog** in WinUI 3 XAML since the system pairing UI is not compatible with Win32 desktop windows. -3. For Bluetooth LE devices, consider using `BluetoothLEDevice.FromIdAsync()` followed by `DeviceInformation.Pairing.Custom.PairAsync()`. - -**Verify:** Initiate Bluetooth pairing and confirm your custom UI appears and the device pairs successfully. - ---- - -### Scenario 4: ProximityDevice NFC Events Not Triggered After UWP → WinUI 3 Migration - -**Cause:** `Windows.Networking.Proximity.ProximityDevice` events (e.g., `SubscribeForMessage("NDEF", ...)`) work in UWP but do not fire in WinUI 3 / Windows App SDK desktop apps. The `ProximityDevice` API is a UWP-era API that relies on the UWP app model and brokered device access, which is not fully supported in the Win32 desktop app model used by WinUI 3. -> Source: Issue [#4356](https://github.com/microsoft/WindowsAppSDK/issues/4356) - -**Affected versions:** Windows App SDK 1.5.2+, Windows 11 22H2 - -**Repro:** -```csharp -var proximityDevice = Windows.Networking.Proximity.ProximityDevice.GetDefault(); -var messageSubscriptionId = proximityDevice.SubscribeForMessage("NDEF", (device, message) => -{ - Console.WriteLine(message.Data.ToArray()); // Never fires in WinUI 3 -}); -``` - -**Fix / Workaround:** -1. **Use the PC/SC (WinSCard) API** for NFC smart card access as an alternative to `ProximityDevice`: -```csharp -// Use Windows.Devices.SmartCards namespace -var reader = await SmartCardReader.FromIdAsync(deviceId); -reader.CardAdded += OnCardAdded; -``` -2. **Use a third-party NFC library** that wraps the Win32 PC/SC APIs (e.g., PCSC-Sharp). -3. Ensure `` is declared in your app manifest (required but not sufficient for WinUI 3). -4. As a last resort, **keep NFC functionality in a separate UWP component** or background task that communicates with the main WinUI 3 app. - -> ⚠️ This is an open issue. `ProximityDevice` is not officially supported in WinUI 3 desktop apps. - ---- - -### Scenario 5: Widget at Top of Alphabetical List Cannot Be Added - -**Cause:** In the Windows Widgets panel, a widget whose name starts with "A" (appearing at the top of the list) cannot be added — the "Add" button stays gray/inactive. Switching to another widget and back causes it to become addable. This appears to be a UI initialization/selection state bug in the Widgets Board. -> Source: Issue [#6140](https://github.com/microsoft/WindowsAppSDK/issues/6140) - -**Affected versions:** Windows 11 25H2 (Build 26220.7535) - -**Fix / Workaround:** -1. **Workaround for end users:** Select a different widget first, then switch back to the desired widget — it will become addable. -2. **For widget developers:** Consider naming your widget to not appear first alphabetically as a temporary workaround (e.g., prefix with a space or non-"A" character), though this is not ideal. - -> ⚠️ This is a Windows Widgets Board bug — no SDK-level fix available. Report via Feedback Hub for Windows team triage. - ---- - -## ⚠️ Unverified / Community Suggestions - -> The following are community suggestions that have NOT been officially confirmed. - -- For stale NuGet caching (#6253): Some developers report that switching the solution configuration (Debug ↔ Release) and rebuilding can force correct DLL resolution. -- For NFC (#4356): The original reporter tried `DeviceCapability` declarations and multiple SDK versions without success. There is no confirmed workaround within the WinUI 3 app model. - ---- - -## References - -- [FindPackagesByPackageFamily function (Win32)](https://learn.microsoft.com/en-us/windows/win32/api/appmodel/nf-appmodel-findpackagesbypackagefamily) -- [Display UI objects in WinUI 3 (IInitializeWithWindow)](https://docs.microsoft.com/en-us/windows/apps/develop/ui-input/display-ui-objects) -- [DeviceInformationCustomPairing API](https://learn.microsoft.com/en-us/uwp/api/windows.devices.enumeration.deviceinformationcustompairing) -- [ProximityDevice API (UWP)](https://learn.microsoft.com/en-us/uwp/api/windows.networking.proximity.proximitydevice) -- [Windows Widgets overview](https://learn.microsoft.com/en-us/windows/apps/develop/widgets/) -- [MSIX packaging documentation](https://learn.microsoft.com/en-us/windows/msix/) - ---- - -**Updated:** 2025-07-17 | **Confidence:** 0.6 -**Sources:** #6253, #6274, #3091, #4356, #6140 +# External / Interop Issues — Packaging, Device APIs, and Widgets + +**Keywords:** packaging project, NuGet, stale assembly, MSIX bundle, FindPackagesByPackageFamily, 0x8007007A, ERROR_INSUFFICIENT_BUFFER, DeviceInformationPairing, Bluetooth, ProximityDevice, NFC, Widgets, WinUI 3, HybridWebView.js, build failure, WindowsAppSDK upgrade + +**Error Example:** +``` +WinRT error 0x8007007A: "The data area passed to a system call is too small." + at FindPackagesByPackageFamily() +``` +``` +System.InvalidCastException + at WinRT.Interop.InitializeWithWindow.Initialize(DeviceInformation.Pairing, windowHandle) +``` +``` +Could not copy the file "C:\Users\Jochem\.nuget\packages\microsoft.maui.controls.core\9.0.120\lib\net9.0-windows10.0.19041\Microsoft.Maui\Handlers\HybridWebView\HybridWebView.js" because it was not found. +``` + +--- + +## Quick Match + +**You're seeing this if:** +- MSIX bundle contains wrong (stale) NuGet DLL versions after package downgrade +- Error `0x8007007A` on app startup from `FindPackagesByPackageFamily` +- Bluetooth device pairing UI fails to show in WinUI 3 desktop app +- NFC `ProximityDevice` events never fire after UWP → WinUI 3 migration +- Widgets panel: first widget (alphabetically) cannot be added +- Build fails with "Could not copy the file HybridWebView.js" after upgrading to Windows App SDK 1.8 + +→ Check scenarios below for your specific cause + +--- + +## Related Issues + +- [#6253](https://github.com/microsoft/WindowsAppSDK/issues/6253) — Packaging project caches stale NuGet assembly references across builds (Status: Closed) +- [#6274](https://github.com/microsoft/WindowsAppSDK/issues/6274) — WinRT error 0x8007007A in `FindPackagesByPackageFamily` (Status: Open) +- [#3091](https://github.com/microsoft/WindowsAppSDK/issues/3091) — Unable to display device pairing UI in WinUI 3 app (Status: Closed) +- [#4356](https://github.com/microsoft/WindowsAppSDK/issues/4356) — ProximityDevice NFC events not triggered (Status: Open) +- [#6140](https://github.com/microsoft/WindowsAppSDK/issues/6140) — Widget at top of list cannot be added until switching away (Status: Open) +- [#6032](https://github.com/microsoft/WindowsAppSDK/issues/6032) — "Could not copy the file HybridWebView.js" when upgrading to 1.8.251106002 (Status: Closed) + +--- + +## Scenarios & Solutions + +### Scenario 1: Packaging Project Caches Stale NuGet Assembly References Across Builds + +**Cause:** When using the Packaging project to produce MSIX bundles, downgrading (or upgrading) a NuGet package reference and rebuilding results in the previously-built DLL version being included in the bundle. Neither **Clean Solution** nor restarting Visual Studio resolves this. The packaging project caches assembly paths and does not properly invalidate them when NuGet versions change. +> Source: Issue [#6253](https://github.com/microsoft/WindowsAppSDK/issues/6253) — also filed on [VS Developer Community](https://developercommunity.visualstudio.com/t/Packaging-project-caches-stale-NuGet-ass/110512955) + +**Affected versions:** Visual Studio 2026, Windows App SDK (MSIX packaging), any NuGet package + +**Repro:** +1. Reference `CommunityToolkit.Mvvm` version **8.3.2**, build MSIX bundle → DLL is 8.3.2.1 ✅ +2. Upgrade to **8.4.0**, Clean Solution, rebuild → DLL is 8.4.0.1 ✅ +3. Downgrade back to **8.3.2**, Clean Solution, rebuild → DLL is still **8.4.0.1** ⚠️ + +**Fix:** +1. **Manually delete the packaging project output folders** before rebuilding: + - Delete `App1 (Package)\AppPackages\` folder + - Delete `App1 (Package)\bin\` and `App1 (Package)\obj\` folders +2. **Force a full NuGet restore** after version change: +```powershell +dotnet nuget locals all --clear +dotnet restore +``` +3. **Rebuild** (not just Build) the entire solution after clearing caches. + +**Verify:** Open the resulting `.msixbundle` in 7-Zip and confirm the DLL version matches the referenced NuGet version. + +--- + +### Scenario 2: WinRT Error 0x8007007A — "Data Area Passed to a System Call Is Too Small" + +**Cause:** On app startup, `FindPackagesByPackageFamily` reports `ERROR_INSUFFICIENT_BUFFER` (HRESULT `0x8007007A`). The debugger shows `bufferLength = 80` and corrupted locals (huge vector size, invalid pointer), indicating a buffer overflow. The root cause is a buffer size mismatch: the API returns a required **character count** for a `PWSTR` buffer, but the calling code likely allocated `bufferLength` **bytes** instead of `bufferLength * sizeof(wchar_t)`. +> Source: Issue [#6274](https://github.com/microsoft/WindowsAppSDK/issues/6274) + +**Affected versions:** Windows App SDK 1.8.5 (1.8.260209005), Windows 11 24H2 + +**Important note:** This exception surfaces only when **"Break when thrown"** is enabled for all exceptions in Visual Studio's Exception Settings. In normal execution, the SDK may handle this internally. + +**Fix:** +1. **Check if this is a first-chance exception only.** Uncheck "Break when thrown" for `WinRT originate error` exceptions in Visual Studio → Exception Settings. If the app runs normally, this is an internal SDK exception that is caught and handled. +2. If calling `FindPackagesByPackageFamily` in your own code, ensure proper two-call pattern: +```cpp +UINT32 count = 0; +UINT32 bufferLength = 0; +// First call: get required sizes +FindPackagesByPackageFamily(familyName, PACKAGE_FILTER_HEAD, &count, nullptr, &bufferLength, nullptr, nullptr); +// Allocate with correct units (characters, not bytes) +PWSTR buffer = new WCHAR[bufferLength]; // bufferLength is in characters +PWSTR* packageFullNames = new PWSTR[count]; +// Second call: retrieve data +FindPackagesByPackageFamily(familyName, PACKAGE_FILTER_HEAD, &count, packageFullNames, &bufferLength, buffer, nullptr); +``` +3. Handle `ERROR_INSUFFICIENT_BUFFER` return code as expected (it is the normal first-call response). + +**Verify:** Run app with first-chance exception breaking disabled and confirm no user-visible crash. + +--- + +### Scenario 3: Device Pairing UI Does Not Display in WinUI 3 Desktop App + +**Cause:** Calling `DeviceInformationPairing.PairAsync()` in a WinUI 3 desktop app does not show the system Bluetooth pairing UI. The pairing process silently fails after a few seconds. The `IInitializeWithWindow` workaround documented for other UWP controls throws `System.InvalidCastException` when applied to `DeviceInformation` or `DeviceInformation.Pairing` because these objects do not implement `IInitializeWithWindow`. +> Source: Issue [#3091](https://github.com/microsoft/WindowsAppSDK/issues/3091) + +**Affected versions:** Windows App SDK 1.0+, Windows 11 (21H2) + +**Fix:** +1. **Use `DeviceInformationCustomPairing`** with a custom handler instead of the automatic pairing UI: +```csharp +var customPairing = deviceInfo.Pairing.Custom; +customPairing.PairingRequested += (sender, args) => +{ + // Handle pairing ceremony in your own UI + args.Accept(); // or args.Accept(pin) for PIN-based pairing +}; +var result = await customPairing.PairAsync( + DevicePairingKinds.ConfirmOnly | DevicePairingKinds.DisplayPin); +``` +2. **Build your own pairing confirmation dialog** in WinUI 3 XAML since the system pairing UI is not compatible with Win32 desktop windows. +3. For Bluetooth LE devices, consider using `BluetoothLEDevice.FromIdAsync()` followed by `DeviceInformation.Pairing.Custom.PairAsync()`. + +**Verify:** Initiate Bluetooth pairing and confirm your custom UI appears and the device pairs successfully. + +--- + +### Scenario 4: ProximityDevice NFC Events Not Triggered After UWP → WinUI 3 Migration + +**Cause:** `Windows.Networking.Proximity.ProximityDevice` events (e.g., `SubscribeForMessage("NDEF", ...)`) work in UWP but do not fire in WinUI 3 / Windows App SDK desktop apps. The `ProximityDevice` API is a UWP-era API that relies on the UWP app model and brokered device access, which is not fully supported in the Win32 desktop app model used by WinUI 3. +> Source: Issue [#4356](https://github.com/microsoft/WindowsAppSDK/issues/4356) + +**Affected versions:** Windows App SDK 1.5.2+, Windows 11 22H2 + +**Repro:** +```csharp +var proximityDevice = Windows.Networking.Proximity.ProximityDevice.GetDefault(); +var messageSubscriptionId = proximityDevice.SubscribeForMessage("NDEF", (device, message) => +{ + Console.WriteLine(message.Data.ToArray()); // Never fires in WinUI 3 +}); +``` + +**Fix / Workaround:** +1. **Use the PC/SC (WinSCard) API** for NFC smart card access as an alternative to `ProximityDevice`: +```csharp +// Use Windows.Devices.SmartCards namespace +var reader = await SmartCardReader.FromIdAsync(deviceId); +reader.CardAdded += OnCardAdded; +``` +2. **Use a third-party NFC library** that wraps the Win32 PC/SC APIs (e.g., PCSC-Sharp). +3. Ensure `` is declared in your app manifest (required but not sufficient for WinUI 3). +4. As a last resort, **keep NFC functionality in a separate UWP component** or background task that communicates with the main WinUI 3 app. + +> ⚠️ This is an open issue. `ProximityDevice` is not officially supported in WinUI 3 desktop apps. + +--- + +### Scenario 5: Widget at Top of Alphabetical List Cannot Be Added + +**Cause:** In the Windows Widgets panel, a widget whose name starts with "A" (appearing at the top of the list) cannot be added — the "Add" button stays gray/inactive. Switching to another widget and back causes it to become addable. This appears to be a UI initialization/selection state bug in the Widgets Board. +> Source: Issue [#6140](https://github.com/microsoft/WindowsAppSDK/issues/6140) + +**Affected versions:** Windows 11 25H2 (Build 26220.7535) + +**Fix / Workaround:** +1. **Workaround for end users:** Select a different widget first, then switch back to the desired widget — it will become addable. +2. **For widget developers:** Consider naming your widget to not appear first alphabetically as a temporary workaround (e.g., prefix with a space or non-"A" character), though this is not ideal. + +> ⚠️ This is a Windows Widgets Board bug — no SDK-level fix available. Report via Feedback Hub for Windows team triage. + +--- + +### Known Issue: Build Fails with "Could Not Copy the File HybridWebView.js" After Upgrading to Windows App SDK 1.8 + +**Cause:** When upgrading from Windows App SDK 1.7 to 1.8, builds may fail with the error: +`Could not copy the file "HybridWebView.js" because it was not found.` +This issue appears to be related to a missing file in the `Microsoft.Maui.Controls.Core` package when used with Windows App SDK 1.8. The issue has been linked to a known problem in the .NET MAUI repository. +> Source: @mfkl in [#6032](https://github.com/microsoft/WindowsAppSDK/issues/6032) + +**Affected versions:** Windows App SDK 1.8.251106002, .NET MAUI 9.0.120 + +**Workaround:** +No confirmed workaround is available. Cleaning the NuGet cache and rebuilding does not resolve the issue. The issue may be related to [dotnet/maui#32683](https://github.com/dotnet/maui/issues/32683). + +> ⚠️ This issue has been closed without a confirmed resolution. Developers encountering this issue are encouraged to monitor the linked .NET MAUI issue for updates. + +--- + +## ⚠️ Unverified / Community Suggestions + +> The following are community suggestions that have NOT been officially confirmed. + +- For stale NuGet caching (#6253): Some developers report that switching the solution configuration (Debug ↔ Release) and rebuilding can force correct DLL resolution. +- For NFC (#4356): The original reporter tried `DeviceCapability` declarations and multiple SDK versions without success. There is no confirmed workaround within the WinUI 3 app model. +- For HybridWebView.js build failure (#6032): Some users suggest manually copying the missing file from a working version of the package, though this is not officially recommended. + +--- + +## References + +- [FindPackagesByPackageFamily function (Win32)](https://learn.microsoft.com/en-us/windows/win32/api/appmodel/nf-appmodel-findpackagesbypackagefamily) +- [Display UI objects in WinUI 3 (IInitializeWithWindow)](https://docs.microsoft.com/en-us/windows/apps/develop/ui-input/display-ui-objects) +- [DeviceInformationCustomPairing API](https://learn.microsoft.com/en-us/uwp/api/windows.devices.enumeration.deviceinformationcustompairing) +- [ProximityDevice API (UWP)](https://learn.microsoft.com/en-us/uwp/api/windows.networking.proximity.proximitydevice) +- [Windows Widgets overview](https://learn.microsoft.com/en-us/windows/apps/develop/widgets/) +- [MSIX packaging documentation](https://learn.microsoft.com/en-us/windows/msix/) +- [dotnet/maui#32683](https://github.com/dotnet/maui/issues/32683) + +--- + +**Updated:** 2026-03-17 | **Confidence:** 0.6 +**Sources:** #6253, #6274, #3091, #4356, #6140, #6032 \ No newline at end of file diff --git a/tsg/tsg_file_access_storage_pickers.md b/trouble-shooting-notes/tsg_file_access_storage_pickers.md similarity index 52% rename from tsg/tsg_file_access_storage_pickers.md rename to trouble-shooting-notes/tsg_file_access_storage_pickers.md index 0a9d0ee..2a58db3 100644 --- a/tsg/tsg_file_access_storage_pickers.md +++ b/trouble-shooting-notes/tsg_file_access_storage_pickers.md @@ -1,199 +1,182 @@ -# Storage Picker Issues — File Access & Picker Dialogs - -**Keywords:** FileOpenPicker, FileSavePicker, FolderPicker, storage pickers, file picker crash, COMException, E_FAIL, IInitializeWithWindow, DefaultFileExtension, FileTypeChoices, WSL, RTL, language override - -**Error Example:** -``` -System.Runtime.InteropServices.COMException: 'Error HRESULT E_FAIL has been returned from a call to a COM component.' - at Windows.Storage.Pickers.FileOpenPicker.PickSingleFileAsync() -``` - ---- - -## Quick Match - -**You're seeing this if:** -- Error contains "E_FAIL" or "COMException" when calling `PickSingleFileAsync()` or `PickSaveFileAsync()` -- File/Folder picker dialog behaves unexpectedly (wrong extension, missing folders, wrong language) -- Using `FileOpenPicker`, `FileSavePicker`, or `FolderPicker` from a WinUI 3 / Windows App SDK desktop app -- Platform: Windows App SDK (packaged or unpackaged), WinUI 3 - -→ Check scenarios below for your specific cause - ---- - -## Related Issues - -- [#1063](https://github.com/microsoft/WindowsAppSDK/issues/1063) — Simplify using UWP file pickers from desktop apps (Status: Closed — feature proposal) -- [#2504](https://github.com/microsoft/WindowsAppSDK/issues/2504) — FileOpenPicker crashes when app runs as Administrator (Status: Closed) -- [#5975](https://github.com/microsoft/WindowsAppSDK/issues/5975) — FileSavePicker cannot set default extension when defining FileTypeChoices (Status: Closed) -- [#6284](https://github.com/microsoft/WindowsAppSDK/issues/6284) — FolderPicker does not show WSL (Linux) folders (Status: Open) -- [#6105](https://github.com/microsoft/WindowsAppSDK/issues/6105) — How to change or force storage pickers to a specific language? (Status: Open) - ---- - -## Scenarios & Solutions - -### Scenario 1: FileOpenPicker / FolderPicker Crashes with COMException When Running as Administrator - -**Cause:** Calling `PickSingleFileAsync()` on a `FileOpenPicker` (or `FolderPicker`) while the app is running elevated (Run as Administrator) throws `COMException: Error HRESULT E_FAIL`. This is a known limitation of the Windows shell file picker COM infrastructure under elevated processes. -> Source: Issue [#2504](https://github.com/microsoft/WindowsAppSDK/issues/2504) - -**Affected versions:** Windows App SDK 1.4.2+, .NET 7+, Windows 11 - -**Repro code that triggers the crash:** -```csharp -var picker = new FileOpenPicker(); -picker.FileTypeFilter.Add("*"); -InitializeWithWindow.Initialize(picker, App.MainWindow.GetHandle()); -var file = await picker.PickSingleFileAsync(); // Crashes when elevated -``` - -**Fix:** -1. **Avoid running the app elevated** when file picker usage is required. Separate elevated operations into a background service or helper process. -2. **Use Win32 `GetOpenFileName` / `IFileDialog` COM APIs** directly instead of UWP pickers when elevation is required — these Win32 APIs work under Administrator. -3. If elevation is unavoidable, wrap the picker call in a try/catch and fall back to a Win32 file dialog: -```csharp -try -{ - var file = await picker.PickSingleFileAsync(); -} -catch (COMException ex) when (ex.HResult == unchecked((int)0x80004005)) -{ - // Fall back to Win32 IFileDialog -} -``` - -**Verify:** Launch the app as Administrator and confirm file picker opens without crash. - ---- - -### Scenario 2: IInitializeWithWindow Boilerplate Required for Desktop Apps - -**Cause:** UWP file pickers (`FileOpenPicker`, `FileSavePicker`, `FolderPicker`) require a parent window handle (HWND) when used in Win32/desktop apps. Without calling `IInitializeWithWindow.Initialize()`, the picker has no owner window and will fail. -> Source: Issue [#1063](https://github.com/microsoft/WindowsAppSDK/issues/1063) - -**Fix (WinUI 3 / Windows App SDK 1.8+):** - -Starting with Windows App SDK 1.8, new picker constructors accept a `WindowId` directly, eliminating the interop boilerplate: -```csharp -// New simplified approach (SDK 1.8+) -var picker = new FileOpenPicker(appWindow.Id); -picker.FileTypeFilter.Add("*"); -var file = await picker.PickSingleFileAsync(); -``` - -**Fix (Older SDK versions):** -```csharp -var picker = new FileOpenPicker(); -picker.FileTypeFilter.Add("*"); - -// Required interop for desktop apps -var hwnd = WinRT.Interop.WindowNative.GetWindowHandle(this); -WinRT.Interop.InitializeWithWindow.Initialize(picker, hwnd); - -var file = await picker.PickSingleFileAsync(); -``` - -**Verify:** Picker dialog opens with the correct parent window and does not throw. - ---- - -### Scenario 3: FileSavePicker Ignores DefaultFileExtension — Always Uses First Sorted Entry - -**Cause:** The `DefaultFileExtension` property is ignored. `FileTypeChoices` is always sorted alphabetically, and the first sorted item is selected by default regardless of `DefaultFileExtension` or insertion order. -> Source: Issue [#5975](https://github.com/microsoft/WindowsAppSDK/issues/5975) - -**Affected versions:** Windows App SDK 1.8.2 (1.8.251003001), unpackaged and packaged - -**Repro:** -```csharp -var saveDialog = new FileSavePicker(AppWindow.Id) -{ - DefaultFileExtension = ".xml", -}; -saveDialog.FileTypeChoices.TryAdd("TXT", [".txt"]); -saveDialog.FileTypeChoices.TryAdd("JSON", [".json"]); -saveDialog.FileTypeChoices.TryAdd("XML", [".xml"]); - -var picker = await saveDialog.PickSaveFileAsync(); -// Result: ".json" is selected as default (alphabetical first), not ".xml" -``` - -**Fix / Workaround:** -1. **Order your `FileTypeChoices` so the desired default is alphabetically first**, or add only the desired default type initially. -2. Use `SuggestedFileName` with the desired extension to hint the dialog: -```csharp -saveDialog.SuggestedFileName = "document.xml"; -``` -3. If a single file type is needed, register only that type in `FileTypeChoices`. - -> ⚠️ This is a confirmed bug. No official SDK-level fix is available at this time. - ---- - -### Scenario 4: FolderPicker Does Not Show WSL (Linux) Folders - -**Cause:** `FolderPicker` does not enumerate WSL network locations (`\\wsl$\...`), while `FileOpenPicker` does. The `FolderPicker` appears to handle virtual/network shell namespace locations differently than `FileOpenPicker`. Temporarily, after navigating to a WSL path via `FileOpenPicker`, `FolderPicker` may briefly show WSL folders (cache/state inheritance) but loses them on subsequent opens. -> Source: Issue [#6284](https://github.com/microsoft/WindowsAppSDK/issues/6284) - -**Affected versions:** Windows App SDK 1.8 (1.8.250916003), Windows 11 - -**Fix / Workaround:** -1. **Use `FileOpenPicker` first** to navigate to a WSL path, then immediately open `FolderPicker` — WSL folders may appear transiently. -2. **Use Win32 `IFileDialog` with `FOS_PICKFOLDERS`** flag for reliable WSL folder browsing: -```cpp -IFileDialog *pfd; -CoCreateInstance(CLSID_FileOpenDialog, NULL, CLSCTX_INPROC_SERVER, IID_PPV_ARGS(&pfd)); -DWORD dwOptions; -pfd->GetOptions(&dwOptions); -pfd->SetOptions(dwOptions | FOS_PICKFOLDERS); -pfd->Show(hwnd); -``` -3. Alternatively, allow the user to paste the WSL UNC path (`\\wsl$\Ubuntu\...`) directly if your UI supports text entry. - -> ⚠️ This is a confirmed open bug — no SDK fix available yet. - ---- - -### Scenario 5: Storage Pickers Inherit App Language / RTL Layout Override - -**Cause:** Setting `Microsoft.Windows.Globalization.ApplicationLanguages.PrimaryLanguageOverride` changes the language and layout direction (LTR/RTL) of storage picker dialogs. Picker dialogs respect the app-wide language override, which is undesired when the app uses RTL languages (e.g., Persian `fa-IR`) but the picker should remain LTR. -> Source: Issue [#6105](https://github.com/microsoft/WindowsAppSDK/issues/6105) - -**Affected versions:** Windows App SDK 1.8.3 (1.8.251106002), packaged and unpackaged - -**Fix / Workaround:** -1. **Temporarily reset `PrimaryLanguageOverride`** before opening the picker, then restore it: -```csharp -var savedLang = ApplicationLanguages.PrimaryLanguageOverride; -ApplicationLanguages.PrimaryLanguageOverride = "en-US"; // Force LTR for picker -var file = await picker.PickSingleFileAsync(); -ApplicationLanguages.PrimaryLanguageOverride = savedLang; // Restore -``` -2. **Use `ResourceContext`** with a specific qualifier instead of the global language override to localize the app UI without affecting system dialogs. - -> ⚠️ This is an open issue — no official fix from Microsoft yet. - ---- - -## ⚠️ Unverified / Community Suggestions - -> The following are community suggestions that have NOT been officially confirmed. - -- For the Administrator crash (#2504): Some users report that creating pickers on the UI thread specifically (not from a background task) may reduce crash frequency, but this is not a reliable fix. -- For WSL folders (#6284): The transient visibility behavior suggests monitoring `FileOpenPicker` navigation state may help, but no programmatic API exists for this. - ---- - -## References - -- [Windows App SDK Storage Pickers documentation](https://learn.microsoft.com/en-us/windows/apps/develop/files/file-pickers) -- [Display UI objects in WinUI 3 (IInitializeWithWindow)](https://docs.microsoft.com/en-us/windows/apps/develop/ui-input/display-ui-objects) -- [FileOpenPicker API reference](https://learn.microsoft.com/en-us/windows/windows-app-sdk/api/winrt/microsoft.windows.storage.pickers.fileopenpicker) -- [FileSavePicker API reference](https://learn.microsoft.com/en-us/windows/windows-app-sdk/api/winrt/microsoft.windows.storage.pickers.filesavepicker) - ---- - -**Updated:** 2025-07-17 | **Confidence:** 0.7 -**Sources:** #1063, #2504, #5975, #6284, #6105 +# Storage Picker Issues — File Access & Picker Dialogs + +**Keywords:** FileOpenPicker, FileSavePicker, FolderPicker, storage pickers, file picker crash, COMException, E_FAIL, IInitializeWithWindow, DefaultFileExtension, FileTypeChoices, WSL, RTL, language override, Element not found, blank file type list, empty file creation, self-contained, pri files, SuggestedStartLocation + +**Error Example:** +``` +System.Runtime.InteropServices.COMException: 'Error HRESULT E_FAIL has been returned from a call to a COM component.' + at Windows.Storage.Pickers.FileOpenPicker.PickSingleFileAsync() +``` + +--- + +## Quick Match + +**You're seeing this if:** +- Error contains "E_FAIL" or "COMException" when calling `PickSingleFileAsync()` or `PickSaveFileAsync()` +- File/Folder picker dialog behaves unexpectedly (wrong extension, missing folders, wrong language, blank file type list, or crashes) +- Using `FileOpenPicker`, `FileSavePicker`, or `FolderPicker` from a WinUI 3 / Windows App SDK desktop app +- Platform: Windows App SDK (packaged or unpackaged), WinUI 3 + +→ Check scenarios below for your specific cause + +--- + +## Related Issues + +- [#1063](https://github.com/microsoft/WindowsAppSDK/issues/1063) — Simplify using UWP file pickers from desktop apps (Status: Closed — feature proposal) +- [#2504](https://github.com/microsoft/WindowsAppSDK/issues/2504) — FileOpenPicker crashes when app runs as Administrator (Status: Closed) +- [#5612](https://github.com/microsoft/WindowsAppSDK/issues/5612) — FileOpenPicker always crashes (Status: Closed) +- [#5747](https://github.com/microsoft/WindowsAppSDK/issues/5747) — ComException when using new FileSavePicker (Status: Closed) +- [#5749](https://github.com/microsoft/WindowsAppSDK/issues/5749) — FolderPicker not working in 1.8-preview with SelfContained: Element not found (Status: Closed) +- [#5827](https://github.com/microsoft/WindowsAppSDK/issues/5827) — Order of FileTypeChoices in new pickers is not respected (Status: Closed) +- [#5836](https://github.com/microsoft/WindowsAppSDK/issues/5836) — `SuggestedStartLocation` not working correctly in File/Folder pickers (Status: Closed) +- [#5837](https://github.com/microsoft/WindowsAppSDK/issues/5837) — Most entries in the FileOpenPicker file type list are blank (Status: Closed) +- [#5975](https://github.com/microsoft/WindowsAppSDK/issues/5975) — FileSavePicker cannot set default extension when defining FileTypeChoices (Status: Closed) +- [#5976](https://github.com/microsoft/WindowsAppSDK/issues/5976) — FileSavePicker auto creates empty file after clicking OK button (Status: Closed) +- [#6284](https://github.com/microsoft/WindowsAppSDK/issues/6284) — FolderPicker does not show WSL (Linux) folders (Status: Open) +- [#6105](https://github.com/microsoft/WindowsAppSDK/issues/6105) — How to change or force storage pickers to a specific language? (Status: Open) + +--- + +## Scenarios & Solutions + +### Scenario 1: FileOpenPicker / FolderPicker Crashes with COMException When Running as Administrator + +**Cause:** Calling `PickSingleFileAsync()` on a `FileOpenPicker` (or `FolderPicker`) while the app is running elevated (Run as Administrator) throws `COMException: Error HRESULT E_FAIL`. This is a known limitation of the Windows shell file picker COM infrastructure under elevated processes. +> Source: Issue [#2504](https://github.com/microsoft/WindowsAppSDK/issues/2504) + +**Affected versions:** Windows App SDK 1.4.2+, .NET 7+, Windows 11 + +**Fix:** +1. Avoid running the app elevated when file picker usage is required. Separate elevated operations into a background service or helper process. +2. Use Win32 `GetOpenFileName` / `IFileDialog` COM APIs directly instead of UWP pickers when elevation is required. +3. If elevation is unavoidable, wrap the picker call in a try/catch and fall back to a Win32 file dialog. + +--- + +### Scenario 2: IInitializeWithWindow Boilerplate Required for Desktop Apps + +**Cause:** UWP file pickers (`FileOpenPicker`, `FileSavePicker`, `FolderPicker`) require a parent window handle (HWND) when used in Win32/desktop apps. Without calling `IInitializeWithWindow.Initialize()`, the picker has no owner window and will fail. +> Source: Issue [#1063](https://github.com/microsoft/WindowsAppSDK/issues/1063) + +**Fix (WinUI 3 / Windows App SDK 1.8+):** +```csharp +var picker = new FileOpenPicker(appWindow.Id); +picker.FileTypeFilter.Add("*"); +var file = await picker.PickSingleFileAsync(); +``` + +**Fix (Older SDK versions):** +```csharp +var picker = new FileOpenPicker(); +picker.FileTypeFilter.Add("*"); +var hwnd = WinRT.Interop.WindowNative.GetWindowHandle(this); +WinRT.Interop.InitializeWithWindow.Initialize(picker, hwnd); +var file = await picker.PickSingleFileAsync(); +``` + +--- + +### Scenario 3: FileSavePicker Ignores DefaultFileExtension — Always Uses First Sorted Entry + +**Cause:** The `DefaultFileExtension` property is ignored. `FileTypeChoices` is always sorted alphabetically, and the first sorted item is selected by default regardless of `DefaultFileExtension` or insertion order. +> Source: Issue [#5975](https://github.com/microsoft/WindowsAppSDK/issues/5975) + +**Fix / Workaround:** +1. Order your `FileTypeChoices` so the desired default is alphabetically first. +2. Use `SuggestedFileName` with the desired extension to hint the dialog. + +--- + +### Scenario 4: FolderPicker Does Not Show WSL (Linux) Folders + +**Cause:** `FolderPicker` does not enumerate WSL network locations (`\\wsl$\...`). +> Source: Issue [#6284](https://github.com/microsoft/WindowsAppSDK/issues/6284) + +**Fix / Workaround:** +1. Use `FileOpenPicker` first to navigate to a WSL path, then immediately open `FolderPicker`. +2. Use Win32 `IFileDialog` with `FOS_PICKFOLDERS` flag for reliable WSL folder browsing. + +--- + +### Scenario 5: Storage Pickers Inherit App Language / RTL Layout Override + +**Cause:** Setting `Microsoft.Windows.Globalization.ApplicationLanguages.PrimaryLanguageOverride` changes the language and layout direction (LTR/RTL) of storage picker dialogs. +> Source: Issue [#6105](https://github.com/microsoft/WindowsAppSDK/issues/6105) + +**Fix / Workaround:** +1. Temporarily reset `PrimaryLanguageOverride` before opening the picker, then restore it. +2. Use `ResourceContext` with a specific qualifier instead of the global language override. + +--- + +### Scenario 6: FileOpenPicker Always Crashes + +**Cause:** Missing `InitializeWithWindow` call when creating the picker. +> Source: @castorix in [#5612](https://github.com/microsoft/WindowsAppSDK/issues/5612) + +**Fix:** Ensure the picker is initialized with the correct window handle: +```cpp +const FileOpenPicker picker(AppWindow.Id); +WinRT.Interop.InitializeWithWindow.Initialize(picker, hwnd); +``` + +--- + +### Scenario 7: FolderPicker Not Working in SelfContained Mode + +**Cause:** Missing `.pri` files in the app package when using `true`. +> Source: @DinahK-2SO in [#5749](https://github.com/microsoft/WindowsAppSDK/issues/5749) + +**Fix:** Update to `Microsoft.Windows.SDK.BuildTools.MSIX 1.7.20250829.1` or later. + +--- + +### Scenario 8: Most Entries in FileOpenPicker File Type List Are Blank + +**Cause:** File type descriptions are not displayed due to a bug in the picker. +> Source: @DinahK-2SO in [#5837](https://github.com/microsoft/WindowsAppSDK/issues/5837) + +**Fix:** Update to Windows App SDK 1.8.4 or later. + +--- + +### Scenario 9: FileSavePicker Auto-Creates Empty File After Clicking OK + +**Cause:** Default behavior of `FileSavePicker` is to create an empty file when `PickSaveFileAsync()` is called. +> Source: @DinahK-2SO in [#5976](https://github.com/microsoft/WindowsAppSDK/issues/5976) + +**Fix:** Update to Windows App SDK 2.0 or later. New property `ShowOverwritePrompt` and updated behavior prevent automatic file creation. + +--- + +## Known Issues + +### Issue: `SuggestedStartLocation` Not Working Correctly in File/Folder Pickers + +**Cause:** The `SuggestedStartLocation` property does not always work as expected. Instead of opening in the specified location (e.g., Downloads or Desktop), the picker defaults to the last selected location. +> Source: Issue [#5836](https://github.com/microsoft/WindowsAppSDK/issues/5836) + +**Workaround:** None confirmed. A potential workaround is to rename the app (if unpackaged) or reinstall the app (if packaged) to reset the "last selected location." However, this is not a reliable or practical solution. + +--- + +## ⚠️ Unverified / Community Suggestions + +- For the Administrator crash (#2504): Some users report that creating pickers on the UI thread specifically (not from a background task) may reduce crash frequency, but this is not a reliable fix. +- For `SuggestedStartLocation` (#5836): A potential fix may be available in a future update. See [#5772](https://github.com/microsoft/WindowsAppSDK/pull/5772). + +--- + +## References + +- [Windows App SDK Storage Pickers documentation](https://learn.microsoft.com/en-us/windows/apps/develop/files/file-pickers) +- [Display UI objects in WinUI 3 (IInitializeWithWindow)](https://docs.microsoft.com/en-us/windows/apps/develop/ui-input/display-ui-objects) +- [FileOpenPicker API reference](https://learn.microsoft.com/en-us/windows/windows-app-sdk/api/winrt/microsoft.windows.storage.pickers.fileopenpicker) +- [FileSavePicker API reference](https://learn.microsoft.com/en-us/windows/windows-app-sdk/api/winrt/microsoft.windows.storage.pickers.filesavepicker) + +--- + +**Updated:** 2026-03-17 | **Confidence:** 0.9 +**Sources:** #1063, #2504, #5612, #5747, #5749, #5827, #5836, #5837, #5975, #5976, #6284, #6105 \ No newline at end of file diff --git a/tsg/tsg_msix_build_publish_output_failures.md b/trouble-shooting-notes/tsg_msix_build_publish_output_failures.md similarity index 86% rename from tsg/tsg_msix_build_publish_output_failures.md rename to trouble-shooting-notes/tsg_msix_build_publish_output_failures.md index b88c8f6..388a902 100644 --- a/tsg/tsg_msix_build_publish_output_failures.md +++ b/trouble-shooting-notes/tsg_msix_build_publish_output_failures.md @@ -1,171 +1,183 @@ -# Error: MSIX Build/Publish Output Failures (msixupload, msixbundle, appxsym) - -**Keywords:** msixupload, msixbundle, appxsym, WinAppSdkSignAppxPackageBundle, MSB4036, MSB6006, mspdbcmf.exe, CMF1106, UapAppxPackageBuildMode, StoreUpload, StoreAndSideload - -**Error Examples:** -``` -error MSB4036: The "WinAppSdkSignAppxPackageBundle" task was not found. -error MSB6006: "mspdbcmf.exe" have exited, fatal error CMF1106 -``` - ---- - -## Quick Match - -**You're seeing this if:** -- Building an MSIX bundle or upload package fails with MSB4036 or MSB6006 -- `msbuild` with `UapAppxPackageBuildMode=StoreUpload` does not produce `.msixupload` -- Publishing an MSIX from Visual Studio pollutes `.csproj.user` with `UapAppxPackageBuildMode` -- `mspdbcmf.exe` exits with fatal error CMF1106 during symbol package generation - -→ Check scenarios below for your specific cause - ---- - -## Related Issues - -- [#5820](https://github.com/microsoft/WindowsAppSDK/issues/5820) - Create app bundle fails with scaled images due to typo in targets (Status: Closed/Fixed) -- [#5825](https://github.com/microsoft/WindowsAppSDK/issues/5825) - Single packaging generates msixbundle but fails on appxsym (Status: Open) -- [#5501](https://github.com/microsoft/WindowsAppSDK/issues/5501) - UWP .NET 9 msbuild does not produce .msixupload file (Status: Open) -- [#5537](https://github.com/microsoft/WindowsAppSDK/issues/5537) - Publishing MSIX influences future builds via UapAppxPackageBuildMode (Status: Open) - ---- - -## Scenarios & Solutions - -### Scenario 1: "WinAppSdkSignAppxPackageBundle" Task Not Found (MSB4036) When Creating App Bundle - -**Cause:** A typo in `Microsoft.Windows.SDK.BuildTools.MSIX.Packaging.targets` references a non-existent task name `WinAppSdkSignAppxPackageBundle` instead of the correct `WinAppSdkSignAppxPackage`. This causes failures when `UapAppxPackageBuildMode` is set to `CI` or `StoreUpload` and the manifest contains scaled images or resource packages. -> Source: @zhuxb711 in [#5820](https://github.com/microsoft/WindowsAppSDK/issues/5820) - -**Conditions:** -- Only occurs with `UapAppxPackageBuildMode = CI` or `StoreUpload` -- `SideloadOnly` mode works fine -- Triggered when the manifest contains scaled visual assets (e.g., `SmallTile.scale-100.png`) - -**Fix:** -1. Locate the NuGet package targets file: - ``` - %USERPROFILE%\.nuget\packages\microsoft.windows.sdk.buildtools.msix\\build\Microsoft.Windows.SDK.BuildTools.MSIX.Packaging.targets - ``` -2. Find the `_CreateUploadResourcePackages` target -3. Replace `WinAppSdkSignAppxPackageBundle` with `WinAppSdkSignAppxPackage` - -**CI/CD Workaround (GitHub Actions):** -```yaml -- name: Restore NuGet Packages - shell: pwsh - run: | - msbuild "" /nr:false /restore /p:RestorePackagesConfig=true /p:PreferredToolArchitecture="x64" - -- name: Patch for WindowsAppSDK#5820 - shell: pwsh - run: | - $NuGetPackagesPath = $env:NUGET_PACKAGES ?? (Join-Path $env:USERPROFILE ".nuget/packages") - $TargetFilePath = Join-Path $NuGetPackagesPath "microsoft.windows.sdk.buildtools.msix//build/Microsoft.Windows.SDK.BuildTools.MSIX.Packaging.targets" - (Get-Content $TargetFilePath) -replace 'WinAppSdkSignAppxPackageBundle', 'WinAppSdkSignAppxPackage' | Set-Content $TargetFilePath -``` - -> ✅ Confirmed by: @zhuxb711, @MUJaCHe66 in [#5820](https://github.com/microsoft/WindowsAppSDK/issues/5820) -> @Scottj1s (Microsoft) acknowledged the bug and indicated a fix would be published in an updated `Microsoft.Windows.SDK.BuildTools.MSIX`. - -**Verify:** Build with `UapAppxPackageBuildMode=StoreUpload` completes without MSB4036 errors. - ---- - -### Scenario 2: mspdbcmf.exe Fails with Fatal Error CMF1106 During appxsym Generation - -**Cause:** The `_GenerateAppxSymbolPackage` target invokes `mspdbcmf.exe` to generate `.appxsym` symbol packages, but the tool fails with exit code CMF1106 on certain PDB files. The target does not respect `AppxSymbolPackageEnabled=false`, so setting that property alone does not bypass the failure. -> Source: @zhuxb711 in [#5825](https://github.com/microsoft/WindowsAppSDK/issues/5825) - -**Fix:** -1. Set `MsPdbCmfExeFullpath` to an invalid path to bypass `_GenerateAppxSymbolPackage`: - ```xml - - None - - ``` -2. Also pass `/p:AppxSymbolPackageEnabled="false"` to msbuild to fully disable symbol package generation: - ``` - msbuild YourProject.csproj /p:AppxSymbolPackageEnabled="false" - ``` - -> ✅ Confirmed by: @zhuxb711 in [#5825](https://github.com/microsoft/WindowsAppSDK/issues/5825) - -**Note:** This is a combined workaround. `AppxSymbolPackageEnabled=false` alone is insufficient because `_GenerateAppxSymbolPackage` does not check that property (see also [#6183](https://github.com/microsoft/WindowsAppSDK/issues/6183)). - -**Verify:** `msbuild` completes the msixbundle generation without CMF1106 errors. - ---- - -### Scenario 3: msbuild with StoreUpload Does Not Produce .msixupload File (UWP .NET 9) - -**Cause:** When using `msbuild` from the command line with `UapAppxPackageBuildMode=StoreUpload` for UWP .NET 9 projects, the build does not produce a `.msixupload` file. Multiple `AppxBundlePlatforms` are also not respected — only the first platform is compiled. The Visual Studio "Create App Packages" wizard works correctly, but the CLI equivalent does not. -> Source: @DilanBoskan in [#5501](https://github.com/microsoft/WindowsAppSDK/issues/5501) - -**Workaround:** -1. Build each platform separately using `msbuild` -2. Bundle and sign manually using `MakeAppx.exe` and `SignTool.exe`: - ```powershell - # Build each platform - MSBuild.exe YourApp.csproj /p:Configuration=Release /p:Platform=x86 - MSBuild.exe YourApp.csproj /p:Configuration=Release /p:Platform=x64 - MSBuild.exe YourApp.csproj /p:Configuration=Release /p:Platform=ARM64 - - # Create bundle manually - MakeAppx.exe bundle /d /p YourApp.msixbundle - - # Sign the bundle - SignTool.exe sign /fd SHA256 /a /f YourCert.pfx /p YourApp.msixbundle - ``` - -> Source: @DilanBoskan in [#5501](https://github.com/microsoft/WindowsAppSDK/issues/5501) - -**Note:** @0x5bfa confirmed that in WinAppSDK (non-UWP), the latest `Microsoft.Windows.SDK.BuildTools.MSIX` does produce msixupload and msixbundle. UWP .NET 9 may still be affected. - -**Verify:** Check that `.msixupload` file is generated in the output directory. - ---- - -### Scenario 4: Publishing MSIX Pollutes .csproj.user and Breaks Future Builds - -**Cause:** After publishing an MSIX from Visual Studio (1.8+), the property `StoreAndSideload` is written to `.csproj.user`. This causes every subsequent Release build to unnecessarily create an MSIX package, and publishing as an unpackaged app fails. -> Source: @lhak in [#5537](https://github.com/microsoft/WindowsAppSDK/issues/5537) - -**Fix:** -1. After publishing, delete or edit the `.csproj.user` file to remove: - ```xml - StoreAndSideload - ``` -2. Alternatively, set `UapAppxPackageBuildMode` to `SideloadOnly` to avoid the unwanted behavior: - ```xml - SideloadOnly - ``` - -> Source: @Scottj1s (Microsoft) in [#5537](https://github.com/microsoft/WindowsAppSDK/issues/5537) confirmed that `StoreAndSideload` always publishes on build, and `SideloadOnly` can be used to opt out. - -> @lhak confirmed this was not an issue in previous WinAppSDK versions, suggesting a regression in 1.8. - -**Verify:** Build in Release mode without `.csproj.user` containing `UapAppxPackageBuildMode` — no MSIX package should be created unless explicitly requested. - ---- - -## ⚠️ Unverified / Community Suggestions - -> The following are community suggestions that have NOT been officially confirmed. - -- For #5501: Use the Visual Studio "Create App Packages" wizard as the only reliable method for generating `.msixupload` with multi-platform UWP .NET 9 projects (from @DilanBoskan in #5501) -- Add `.csproj.user` to `.gitignore` to prevent `UapAppxPackageBuildMode` pollution from propagating across team members (general recommendation related to #5537) - ---- - -## References - -- [Single-project MSIX Packaging documentation](https://learn.microsoft.com/en-us/windows/apps/windows-app-sdk/single-project-msix) -- [MakeAppx.exe documentation](https://learn.microsoft.com/en-us/windows/msix/package/create-app-package-with-makeappx-tool) -- [Visual Studio Developer Community: mspdbcmf.exe failed](https://developercommunity.visualstudio.com/t/mspdbcmfexe-failed-with-exit-code-1106/11037870) - ---- - -**Updated:** 2025-07-18 | **Confidence:** 0.8 -**Sources:** [#5820](https://github.com/microsoft/WindowsAppSDK/issues/5820), [#5825](https://github.com/microsoft/WindowsAppSDK/issues/5825), [#5501](https://github.com/microsoft/WindowsAppSDK/issues/5501), [#5537](https://github.com/microsoft/WindowsAppSDK/issues/5537) +# Error: MSIX Build/Publish Output Failures (msixupload, msixbundle, appxsym) + +**Keywords:** msixupload, msixbundle, appxsym, WinAppSdkSignAppxPackageBundle, MSB4036, MSB6006, mspdbcmf.exe, CMF1106, UapAppxPackageBuildMode, StoreUpload, StoreAndSideload, APPX1101, resources.pri + +**Error Examples:** +``` +error MSB4036: The "WinAppSdkSignAppxPackageBundle" task was not found. +error MSB6006: "mspdbcmf.exe" have exited, fatal error CMF1106 +error APPX1101: Payload contains two or more files with the same destination path 'resources.pri' +``` + +--- + +## Quick Match + +**You're seeing this if:** +- Building an MSIX bundle or upload package fails with MSB4036 or MSB6006 +- `msbuild` with `UapAppxPackageBuildMode=StoreUpload` does not produce `.msixupload` +- Publishing an MSIX from Visual Studio pollutes `.csproj.user` with `UapAppxPackageBuildMode` +- `mspdbcmf.exe` exits with fatal error CMF1106 during symbol package generation +- Building a project with WinUI integration tests fails with APPX1101 due to duplicate `resources.pri` + +→ Check scenarios below for your specific cause + +--- + +## Related Issues + +- [#5820](https://github.com/microsoft/WindowsAppSDK/issues/5820) - Create app bundle fails with scaled images due to typo in targets (Status: Closed/Fixed) +- [#5825](https://github.com/microsoft/WindowsAppSDK/issues/5825) - Single packaging generates msixbundle but fails on appxsym (Status: Open) +- [#5501](https://github.com/microsoft/WindowsAppSDK/issues/5501) - UWP .NET 9 msbuild does not produce .msixupload file (Status: Open) +- [#5537](https://github.com/microsoft/WindowsAppSDK/issues/5537) - Publishing MSIX influences future builds via UapAppxPackageBuildMode (Status: Open) +- [#5845](https://github.com/microsoft/WindowsAppSDK/issues/5845) - Regression error APPX1101: Duplicate `resources.pri` in WinUI integration tests (Status: Open) + +--- + +## Scenarios & Solutions + +### Scenario 1: "WinAppSdkSignAppxPackageBundle" Task Not Found (MSB4036) When Creating App Bundle + +**Cause:** A typo in `Microsoft.Windows.SDK.BuildTools.MSIX.Packaging.targets` references a non-existent task name `WinAppSdkSignAppxPackageBundle` instead of the correct `WinAppSdkSignAppxPackage`. This causes failures when `UapAppxPackageBuildMode` is set to `CI` or `StoreUpload` and the manifest contains scaled images or resource packages. +> Source: @zhuxb711 in [#5820](https://github.com/microsoft/WindowsAppSDK/issues/5820) + +**Conditions:** +- Only occurs with `UapAppxPackageBuildMode = CI` or `StoreUpload` +- `SideloadOnly` mode works fine +- Triggered when the manifest contains scaled visual assets (e.g., `SmallTile.scale-100.png`) + +**Fix:** +1. Locate the NuGet package targets file: + ``` + %USERPROFILE%\.nuget\packages\microsoft.windows.sdk.buildtools.msix\\build\Microsoft.Windows.SDK.BuildTools.MSIX.Packaging.targets + ``` +2. Find the `_CreateUploadResourcePackages` target +3. Replace `WinAppSdkSignAppxPackageBundle` with `WinAppSdkSignAppxPackage` + +**CI/CD Workaround (GitHub Actions):** +```yaml +- name: Restore NuGet Packages + shell: pwsh + run: | + msbuild "" /nr:false /restore /p:RestorePackagesConfig=true /p:PreferredToolArchitecture="x64" + +- name: Patch for WindowsAppSDK#5820 + shell: pwsh + run: | + $NuGetPackagesPath = $env:NUGET_PACKAGES ?? (Join-Path $env:USERPROFILE ".nuget/packages") + $TargetFilePath = Join-Path $NuGetPackagesPath "microsoft.windows.sdk.buildtools.msix//build/Microsoft.Windows.SDK.BuildTools.MSIX.Packaging.targets" + (Get-Content $TargetFilePath) -replace 'WinAppSdkSignAppxPackageBundle', 'WinAppSdkSignAppxPackage' | Set-Content $TargetFilePath +``` + +> ✅ Confirmed by: @zhuxb711, @MUJaCHe66 in [#5820](https://github.com/microsoft/WindowsAppSDK/issues/5820) +> @Scottj1s (Microsoft) acknowledged the bug and indicated a fix would be published in an updated `Microsoft.Windows.SDK.BuildTools.MSIX`. + +**Verify:** Build with `UapAppxPackageBuildMode=StoreUpload` completes without MSB4036 errors. + +--- + +### Scenario 2: mspdbcmf.exe Fails with Fatal Error CMF1106 During appxsym Generation + +**Cause:** The `_GenerateAppxSymbolPackage` target invokes `mspdbcmf.exe` to generate `.appxsym` symbol packages, but the tool fails with exit code CMF1106 on certain PDB files. The target does not respect `AppxSymbolPackageEnabled=false`, so setting that property alone does not bypass the failure. +> Source: @zhuxb711 in [#5825](https://github.com/microsoft/WindowsAppSDK/issues/5825) + +**Fix:** +1. Set `MsPdbCmfExeFullpath` to an invalid path to bypass `_GenerateAppxSymbolPackage`: + ```xml + + None + + ``` +2. Also pass `/p:AppxSymbolPackageEnabled="false"` to msbuild to fully disable symbol package generation: + ``` + msbuild YourProject.csproj /p:AppxSymbolPackageEnabled="false" + ``` + +> ✅ Confirmed by: @zhuxb711 in [#5825](https://github.com/microsoft/WindowsAppSDK/issues/5825) + +**Note:** This is a combined workaround. `AppxSymbolPackageEnabled=false` alone is insufficient because `_GenerateAppxSymbolPackage` does not check that property. + +**Verify:** `msbuild` completes the msixbundle generation without CMF1106 errors. + +--- + +### Scenario 3: msbuild with StoreUpload Does Not Produce .msixupload File (UWP .NET 9) + +**Cause:** When using `msbuild` from the command line with `UapAppxPackageBuildMode=StoreUpload` for UWP .NET 9 projects, the build does not produce a `.msixupload` file. Multiple `AppxBundlePlatforms` are also not respected — only the first platform is compiled. The Visual Studio "Create App Packages" wizard works correctly, but the CLI equivalent does not. +> Source: @DilanBoskan in [#5501](https://github.com/microsoft/WindowsAppSDK/issues/5501) + +**Workaround:** +1. Build each platform separately using `msbuild` +2. Bundle and sign manually using `MakeAppx.exe` and `SignTool.exe`: + ```powershell + # Build each platform + MSBuild.exe YourApp.csproj /p:Configuration=Release /p:Platform=x86 + MSBuild.exe YourApp.csproj /p:Configuration=Release /p:Platform=x64 + MSBuild.exe YourApp.csproj /p:Configuration=Release /p:Platform=ARM64 + + # Create bundle manually + MakeAppx.exe bundle /d /p YourApp.msixbundle + + # Sign the bundle + SignTool.exe sign /fd SHA256 /a /f YourCert.pfx /p YourApp.msixbundle + ``` + +> Source: @DilanBoskan in [#5501](https://github.com/microsoft/WindowsAppSDK/issues/5501) + +**Verify:** Check that `.msixupload` file is generated in the output directory. + +--- + +### Scenario 4: Publishing MSIX Pollutes .csproj.user and Breaks Future Builds + +**Cause:** After publishing an MSIX from Visual Studio (1.8+), the property `StoreAndSideload` is written to `.csproj.user`. This causes every subsequent Release build to unnecessarily create an MSIX package, and publishing as an unpackaged app fails. +> Source: @lhak in [#5537](https://github.com/microsoft/WindowsAppSDK/issues/5537) + +**Fix:** +1. After publishing, delete or edit the `.csproj.user` file to remove: + ```xml + StoreAndSideload + ``` +2. Alternatively, set `UapAppxPackageBuildMode` to `SideloadOnly` to avoid the unwanted behavior: + ```xml + SideloadOnly + ``` + +> Source: @Scottj1s (Microsoft) in [#5537](https://github.com/microsoft/WindowsAppSDK/issues/5537) + +**Verify:** Build in Release mode without `.csproj.user` containing `UapAppxPackageBuildMode` — no MSIX package should be created unless explicitly requested. + +--- + +### Scenario 5: APPX1101 Error Due to Duplicate `resources.pri` in WinUI Integration Tests + +**Cause:** When a WinUI integration test references a WinUI app, upgrading to .NET 9 causes a conflict with duplicate `resources.pri` files, resulting in APPX1101 errors. +> Source: @manodasanW in [#5845](https://github.com/microsoft/WindowsAppSDK/issues/5845) + +**Fix:** Update to the latest version of `Microsoft.Windows.SDK.BuildTools.MSIX` (e.g., `1.7.251221100`) to resolve the issue. Explicitly reference this version in your project if necessary. + +> Source: @manodasanW in [#5845](https://github.com/microsoft/WindowsAppSDK/issues/5845) + +**Verify:** Build succeeds without APPX1101 errors. + +--- + +## ⚠️ Unverified / Community Suggestions + +> The following are community suggestions that have NOT been officially confirmed. + +- For #5501: Use the Visual Studio "Create App Packages" wizard as the only reliable method for generating `.msixupload` with multi-platform UWP .NET 9 projects (from @DilanBoskan in #5501) +- Add `.csproj.user` to `.gitignore` to prevent `UapAppxPackageBuildMode` pollution from propagating across team members (general recommendation related to #5537) + +--- + +## References + +- [Single-project MSIX Packaging documentation](https://learn.microsoft.com/en-us/windows/apps/windows-app-sdk/single-project-msix) +- [MakeAppx.exe documentation](https://learn.microsoft.com/en-us/windows/msix/package/create-app-package-with-makeappx-tool) +- [Visual Studio Developer Community: mspdbcmf.exe failed](https://developercommunity.visualstudio.com/t/mspdbcmfexe-failed-with-exit-code-1106/11037870) + +--- + +**Updated:** 2026-03-17 | **Confidence:** 0.8 +**Sources:** [#5820](https://github.com/microsoft/WindowsAppSDK/issues/5820), [#5825](https://github.com/microsoft/WindowsAppSDK/issues/5825), [#5501](https://github.com/microsoft/WindowsAppSDK/issues/5501), [#5537](https://github.com/microsoft/WindowsAppSDK/issues/5537), [#5845](https://github.com/microsoft/WindowsAppSDK/issues/5845) \ No newline at end of file diff --git a/trouble-shooting-notes/tsg_msix_project_configuration_tooling.md b/trouble-shooting-notes/tsg_msix_project_configuration_tooling.md new file mode 100644 index 0000000..9cbc4fb --- /dev/null +++ b/trouble-shooting-notes/tsg_msix_project_configuration_tooling.md @@ -0,0 +1,197 @@ +# Error: MSIX Project Configuration & Build Tools Issues + +**Keywords:** EnableMsixTooling, Microsoft.Windows.SDK.BuildTools.MSIX, AppxOSMinVersionReplaceManifestVersion, AppxOSMaxVersionTestedReplaceManifestVersion, mspdbcmf.exe, wapproj, single-project MSIX, NuGet, Visual Studio, unpackaged, resources.pri, DebugType, APPX1101, APPXUPLOAD, buildTransitive, CustomBeforeMicrosoftCommonTargets, dotnet msbuild, symbols package + +**Error Examples:** +``` +error: "mspdbcmf.exe" hard-coded path dependency into Visual Studio installation +error: MinVersion and MaxVersionTested always replaced in package.appxmanifest +Application crashes due to missing resources.pri after publish +error: APPX1101 - Payload contains two or more files with the same destination path +error: Missing APPXUPLOAD file for store submission +error: CustomBeforeMicrosoftCommonTargets reassignment breaks MSIX build tools +warning: Path to `mspdbcmf.exe` could not be found. A symbols package will not be generated +``` + +--- + +## Quick Match + +**You're seeing this if:** +- Building MSIX packages without Visual Studio installed fails due to missing `mspdbcmf.exe` +- Removing `EnableMsixTooling` from unpackaged app projects causes publish failures or missing `.pri` files +- `AppxOSMinVersionReplaceManifestVersion=false` is ignored by single-project MSIX +- Need to include multiple executables in a single MSIX package +- Encountering APPX1101 errors due to duplicate files in the payload +- Unable to generate `.appxupload` files for store submission +- MSIX build tools fail due to `CustomBeforeMicrosoftCommonTargets` reassignment +- Building MSIX packages using `dotnet msbuild` or `dotnet publish` fails to generate symbols package due to missing `mspdbcmf.exe` + +→ Check scenarios below for your specific cause + +--- + +## Related Issues + +- [#6197](https://github.com/microsoft/WindowsAppSDK/issues/6197) - MSIX NuGet package requires Visual Studio for mspdbcmf.exe (Status: Fixed internally) +- [#3718](https://github.com/microsoft/WindowsAppSDK/issues/3718) - Removing EnableMsixTooling breaks published unpackaged apps (Status: Open) +- [#5598](https://github.com/microsoft/WindowsAppSDK/issues/5598) - BuildTools.MSIX does not support AppxOSMinVersionReplaceManifestVersion (Status: Open) +- [#5586](https://github.com/microsoft/WindowsAppSDK/issues/5586) - Single-project packaging lacks multi-executable support (Status: Open) +- [#5262](https://github.com/microsoft/WindowsAppSDK/issues/5262) - DebugType=embedded generates misleading mspdbcmf.exe error (Status: Closed) +- [#5675](https://github.com/microsoft/WindowsAppSDK/issues/5675) - APPXUPLOAD-bundle creation unsupported pre-1.8 (Status: Closed) +- [#5626](https://github.com/microsoft/WindowsAppSDK/issues/5626) - Missing buildTransitive folder in BuildTools.MSIX (Status: Closed) +- [#5811](https://github.com/microsoft/WindowsAppSDK/issues/5811) - CustomBeforeMicrosoftCommonTargets breaks MSIX build tools (Status: Open) +- [#5826](https://github.com/microsoft/WindowsAppSDK/issues/5826) - APPX1101 errors after upgrading to WindowsAppSDK 1.8 (Status: Open) +- [#5102](https://github.com/microsoft/WindowsAppSDK/issues/5102) - Missing symbols package when building in dotnet msbuild workflow (Status: Open) + +--- + +## Scenarios & Solutions + +### Scenario 1: Cannot Build MSIX Without Visual Studio — mspdbcmf.exe Hard-Coded Path + +**Cause:** The `Microsoft.Windows.SDK.BuildTools.MSIX` NuGet package targets contain a hard-coded path dependency on a Visual Studio installation to locate `mspdbcmf.exe`. This prevents MSIX package creation on machines without Visual Studio (e.g., when using JetBrains Rider or CI/CD environments with only the .NET SDK). +> Source: @wjk in [#6197](https://github.com/microsoft/WindowsAppSDK/issues/6197) + +**Status:** Marked as "Fixed internally" by the Windows App SDK team. The fix has not yet been released as of the issue's last update. + +**Workaround (while waiting for fix):** +1. If you only need to bypass symbol generation, set: + ```xml + + None + false + + ``` +2. If you need `mspdbcmf.exe`, install the Visual Studio Build Tools workload (lighter than full VS): + ``` + vs_buildtools.exe --add Microsoft.VisualStudio.Workload.ManagedDesktopBuildTools + ``` + +**Verify:** `dotnet publish` completes without errors referencing Visual Studio paths. + +--- + +### Scenario 2: Removing EnableMsixTooling Breaks Published Unpackaged Apps (Missing resources.pri) + +**Cause:** `EnableMsixTooling` controls the renaming of `[ProjectName].pri` to `resources.pri` during the build process. When omitted from an unpackaged app project (`None`), the `.pri` file is not copied to the publish directory, causing the published app to crash at runtime with a missing resource error. +> Source: @Balkoth in [#3718](https://github.com/microsoft/WindowsAppSDK/issues/3718) + +**Fix:** +1. **Option A:** Keep `EnableMsixTooling` in the project file even for unpackaged apps: + ```xml + + None + true + + ``` +2. **Option B:** Manually copy the `.pri` file as a post-build step: + ```xml + + + + ``` + +**Verify:** Published output directory contains the `.pri` file, and the application launches without resource-related crashes. + +--- + +### Scenario 3: DebugType=embedded Generates Misleading mspdbcmf.exe Error + +**Cause:** When `DebugType=embedded` is set in the project file, the MSIX build tools incorrectly emit a warning about `mspdbcmf.exe` not being found, even though it is not required in this configuration. +> Source: @Scottj1s in [#5262](https://github.com/microsoft/WindowsAppSDK/issues/5262) + +**Fix:** Update to `Microsoft.Windows.SDK.BuildTools.MSIX` version `1.5.20250417.1` or later, where this issue has been resolved. + +**Workaround (if unable to update):** +Add a dummy `PDBPayload` to suppress the warning: +```xml + + DummyPDBPayload + + + + + + + + + + + +``` + +**Verify:** Build completes without warnings about `mspdbcmf.exe`. + +--- + +### Scenario 4: APPXUPLOAD-Bundle Creation Unsupported Pre-1.8 + +**Cause:** The single-project MSIX tooling did not support `.appxupload` or `.msixupload` bundle creation prior to Windows App SDK 1.8. +> Source: @DarranRowe in [#5675](https://github.com/microsoft/WindowsAppSDK/issues/5675) + +**Workaround:** Manually create the `.appxupload` file by zipping the `.msix` or `.msixbundle` file and its associated `.msixsym` file, then renaming the `.zip` file to `.appxupload`. + +**Verify:** The manually created `.appxupload` file is accepted by the Microsoft Store. + +--- + +### Scenario 5: APPX1101 Errors Due to Duplicate Files in Payload + +**Cause:** Duplicate files in the MSIX package payload, often caused by conflicting versions of dependencies or incorrect project configurations. +> Source: @manodasanW in [#5826](https://github.com/microsoft/WindowsAppSDK/issues/5826) + +**Fix:** Ensure all projects in the solution use consistent versions of dependencies. Remove any outdated `WindowsSdkPackageVersion` properties from project files. + +**Verify:** Build completes without APPX1101 errors. + +--- + +### Scenario 6: CustomBeforeMicrosoftCommonTargets Reassignment Breaks MSIX Build Tools + +**Cause:** The `CustomBeforeMicrosoftCommonTargets` MSBuild property is reassigned without preserving the original value, causing the MSIX build tools to fail. +> Source: @Scottj1s in [#5811](https://github.com/microsoft/WindowsAppSDK/issues/5811) + +**Workaround:** Ensure that any reassignment of `CustomBeforeMicrosoftCommonTargets` includes the original value. For example: +```xml + + $(CustomBeforeMicrosoftCommonTargets);YourCustomPropsFile.props + +``` + +**Verify:** Build completes without errors related to `CustomBeforeMicrosoftCommonTargets`. + +--- + +## Known Issues + +### Issue: Missing Symbols Package When Building in dotnet msbuild Workflow + +**Cause:** When using `dotnet msbuild` or `dotnet publish` to build an MSIX package, the symbol package creation fails with a warning about `mspdbcmf.exe` not being found. This occurs because the MSIX build tools rely on Visual Studio-specific paths that are not available in CLI-only workflows. +> Source: @riverar in [#5102](https://github.com/microsoft/WindowsAppSDK/issues/5102) + +**Status:** Open. No confirmed solution yet. + +**Workaround:** None verified. Some users suggest ensuring all prerequisites for Windows App SDK development are installed, but this has not been confirmed to resolve the issue. + +--- + +## ⚠️ Unverified / Community Suggestions + +- For build environments without Visual Studio, consider using `Microsoft.Windows.SDK.BuildTools` NuGet alongside the MSIX package to reduce VS dependencies (from @wjk in #6197). +- For wapproj to single-project migration, consider tracking [#5586](https://github.com/microsoft/WindowsAppSDK/issues/5586) and [#6261](https://github.com/microsoft/WindowsAppSDK/issues/6261) for official guidance. + +--- + +## References + +- [Single-project MSIX Packaging documentation](https://learn.microsoft.com/en-us/windows/apps/windows-app-sdk/single-project-msix) +- [Single-project MSIX limitations](https://github.com/MicrosoftDocs/windows-dev-docs/blob/docs/hub/apps/windows-app-sdk/single-project-msix.md#limitations) +- [Microsoft.Windows.SDK.BuildTools.MSIX on NuGet](https://www.nuget.org/packages/Microsoft.Windows.SDK.BuildTools.MSIX) + +--- + +**Updated:** 2026-03-17 | **Confidence:** 0.8 +**Sources:** [#6197](https://github.com/microsoft/WindowsAppSDK/issues/6197), [#3718](https://github.com/microsoft/WindowsAppSDK/issues/3718), [#5598](https://github.com/microsoft/WindowsAppSDK/issues/5598), [#5586](https://github.com/microsoft/WindowsAppSDK/issues/5586), [#5262](https://github.com/microsoft/WindowsAppSDK/issues/5262), [#5675](https://github.com/microsoft/WindowsAppSDK/issues/5675), [#5626](https://github.com/microsoft/WindowsAppSDK/issues/5626), [#5811](https://github.com/microsoft/WindowsAppSDK/issues/5811), [#5826](https://github.com/microsoft/WindowsAppSDK/issues/5826), [#5102](https://github.com/microsoft/WindowsAppSDK/issues/5102) \ No newline at end of file diff --git a/tsg/tsg_msix_selfcontained_packaging_conflicts.md b/trouble-shooting-notes/tsg_msix_selfcontained_packaging_conflicts.md similarity index 55% rename from tsg/tsg_msix_selfcontained_packaging_conflicts.md rename to trouble-shooting-notes/tsg_msix_selfcontained_packaging_conflicts.md index 2db8833..ab9fdb4 100644 --- a/tsg/tsg_msix_selfcontained_packaging_conflicts.md +++ b/trouble-shooting-notes/tsg_msix_selfcontained_packaging_conflicts.md @@ -1,130 +1,140 @@ -# Error: Self-Contained Deployment and MSIX Packaging Conflicts - -**Keywords:** WindowsAppSDKSelfContained, XamlParseException, COMException, 0x80070490, resources.pri, PRI, _OverrideGetPriIndexName, EnableMsixTooling, WMC1012, ApplicationXaml, codegen, library project - -**Error Examples:** -``` -Microsoft.UI.Xaml.Markup.XamlParseException: 'XAML parsing failed.' -System.Runtime.InteropServices.COMException (0x80070490): Element not found. -NETSDK1022: Duplicate 'PRIResource' items were included. -WMC1012: A project cannot have more than one ApplicationXaml item -``` - ---- - -## Quick Match - -**You're seeing this if:** -- Setting `WindowsAppSDKSelfContained=true` on a library project causes XAML parsing or codegen failures -- Upgrading to WinAppSDK 1.8 causes COMException 0x80070490 (Element not found) related to `.pri` file naming changes -- Build errors include `NETSDK1022` (duplicate items) or `WMC1012` (multiple ApplicationXaml) after upgrading - -→ Check scenarios below for your specific cause - ---- - -## Related Issues - -- [#6091](https://github.com/microsoft/WindowsAppSDK/issues/6091) - Self-contained deployment breaks WinUI codegen in libraries (Status: Closed/Fixed in v2.0-preview1) -- [#5746](https://github.com/microsoft/WindowsAppSDK/issues/5746) - App update to 1.8-preview1 with COMException 0x80070490 errors (Status: Open) - ---- - -## Scenarios & Solutions - -### Scenario 1: WindowsAppSDKSelfContained=true on Library Project Breaks XAML Codegen - -**Cause:** When `WindowsAppSDKSelfContained` is set to `true` in a class library project, the `_OverrideGetPriIndexName` target in `Microsoft.WindowsAppSDK.SelfContained.targets` (part of `Microsoft.WindowsAppSDK.Base` NuGet) sets the PRI root to empty. This is intended for app projects, not libraries, and causes WinUI XAML code generation to fail. The result is a `XamlParseException` at runtime or a silent launch failure. -> Source: @dongle-the-gadget in [#6091](https://github.com/microsoft/WindowsAppSDK/issues/6091) - -**Affected versions:** WinAppSDK 1.8.x (confirmed with 1.8.3 / 1.8.251106002) - -**Fix:** -1. **Remove** `WindowsAppSDKSelfContained` from all library/class library project files. Only set it on the main application (executable) project: - ```xml - - - - - - true - - ``` -2. If setting the property globally via command line (`dotnet msbuild /p:WindowsAppSDKSelfContained=true`), this will apply to all projects in the solution including libraries — avoid this pattern. - -> ✅ Confirmed by: @riverar (CONTRIBUTOR) in [#6091](https://github.com/microsoft/WindowsAppSDK/issues/6091) — removing the property from the library project resolves the issue. - -> @DrusTheAxe (Microsoft) in [#6091](https://github.com/microsoft/WindowsAppSDK/issues/6091) confirmed: "Library projects don't own context. WinAppSDK downlevel regfree WinRT support only applies to the Fusion manifest for the process' EXE." - -**Official fix:** This has been fixed in [Windows App SDK 2.0.0-Preview1](https://github.com/microsoft/WindowsAppSDK/releases/tag/v2.0-preview1) by adding explicit validation that prevents `WindowsAppSDKSelfContained` from being applied to class library projects. -> Source: @ssparach (CONTRIBUTOR) in [#6091](https://github.com/microsoft/WindowsAppSDK/issues/6091) - -**Verify:** Clean the solution, rebuild, and run the app — XAML should parse without exceptions. - ---- - -### Scenario 2: COMException 0x80070490 "Element not found" After Upgrading to 1.8 - -**Cause:** In WinAppSDK 1.8, the `.pri` file naming behavior changed for unpackaged projects. Previously (1.7 and earlier), `EnableMsixTooling=true` caused the `.pri` file to be named `resources.pri` even for unpackaged apps. In 1.8, unpackaged projects correctly use `[AppName].pri` instead. Code that hard-codes `resources.pri` will fail with COMException 0x80070490 ("Element not found") when accessing localized resources. -> Source: @Sella-GH in [#5746](https://github.com/microsoft/WindowsAppSDK/issues/5746), root cause analysis by @DarranRowe - -**Additional build errors on upgrade:** Upgrading to 1.8-preview1 may also cause: -- `NETSDK1022: Duplicate 'PRIResource' items were included` — Fix with `false` -- `NETSDK1022: Duplicate 'Page' items were included` — Fix with `false` -- `WMC1012: A project cannot have more than one ApplicationXaml item` — May require project restructuring - -**Fix for COMException 0x80070490:** -1. Update any code that hard-codes `resources.pri` to use the correct file name. Use the Resource Manager API to determine the default path: - ```csharp - // Instead of hard-coding "resources.pri", use: - var resourceLoader = new Microsoft.Windows.ApplicationModel.Resources.ResourceLoader(); - // The loader will automatically find the correct .pri file - ``` -2. If you have a custom resource loading service, update the file name from `resources.pri` to `[YourAppName].pri`: - ```csharp - // Before (1.7.x): - var priPath = "resources.pri"; - // After (1.8.x, unpackaged): - var priPath = $"{Assembly.GetExecutingAssembly().GetName().Name}.pri"; - ``` - -> ✅ Confirmed by: @Sella-GH in [#5746](https://github.com/microsoft/WindowsAppSDK/issues/5746) — "When I changed the string to match the new name it works completely fine." - -**Fix for duplicate item build errors:** -```xml - - false - false - -``` - -> @DarranRowe provided detailed analysis in [#5746](https://github.com/microsoft/WindowsAppSDK/issues/5746) confirming that the PRI naming in older versions was a bug (unpackaged projects shouldn't have used `resources.pri`), and 1.8 corrects this behavior. - -**Verify:** -```powershell -# Check which .pri files exist in your output directory -Get-ChildItem -Path "" -Filter "*.pri" -# Should show [AppName].pri, Microsoft.WindowsAppRuntime.pri, Microsoft.UI.pri, etc. -``` - ---- - -## ⚠️ Unverified / Community Suggestions - -> The following are community suggestions that have NOT been officially confirmed. - -- If encountering `WMC1012` (multiple ApplicationXaml) after upgrade, try cleaning all `obj` and `bin` directories before rebuilding (general cleanup suggestion related to #5746) -- Avoid setting `WindowsAppSDKSelfContained=true` via `Directory.Build.props` if your solution contains library projects — use per-project settings instead (from community analysis in #6091) - ---- - -## References - -- [Self-contained deployment documentation](https://learn.microsoft.com/en-us/windows/apps/windows-app-sdk/deploy-self-contained) -- [WinAppSDK 2.0.0-Preview1 release notes](https://github.com/microsoft/WindowsAppSDK/releases/tag/v2.0-preview1) -- [Resource management with MRT Core](https://learn.microsoft.com/en-us/windows/apps/windows-app-sdk/mrtcore/mrtcore-overview) - ---- - -**Updated:** 2025-07-18 | **Confidence:** 0.85 -**Sources:** [#6091](https://github.com/microsoft/WindowsAppSDK/issues/6091), [#5746](https://github.com/microsoft/WindowsAppSDK/issues/5746) +# Error: Self-Contained Deployment and MSIX Packaging Conflicts + +**Keywords:** WindowsAppSDKSelfContained, XamlParseException, COMException, 0x80070490, resources.pri, PRI, _OverrideGetPriIndexName, EnableMsixTooling, WMC1012, ApplicationXaml, codegen, library project, PublishTrimmed, onnxruntime.dll, DirectML.dll, PublishSingleFile, WinML, MSB8027, LNK4042, WindowsAppRuntimeAutoInitializer.cpp + +**Error Examples:** +``` +Microsoft.UI.Xaml.Markup.XamlParseException: 'XAML parsing failed.' +System.Runtime.InteropServices.COMException (0x80070490): Element not found. +NETSDK1022: Duplicate 'PRIResource' items were included. +WMC1012: A project cannot have more than one ApplicationXaml item +onnxruntime.dll and DirectML.dll unnecessarily included in output folder +warning MSB8027: Two or more files with the name of WindowsAppRuntimeAutoInitializer.cpp will produce outputs to the same location. +WindowsAppRuntimeAutoInitializer.obj : warning LNK4042: object specified more than once; extras ignored +Microsoft.Common.CurrentVersion.targets(2434,5): warning MSB3106: Assembly strong name is either a path which could not be found or it is a full assembly name which is badly formed. +``` + +--- + +## Quick Match + +**You're seeing this if:** +- Setting `WindowsAppSDKSelfContained=true` on a library project causes XAML parsing or codegen failures +- Upgrading to WinAppSDK 1.8 causes COMException 0x80070490 (Element not found) related to `.pri` file naming changes +- Build errors include `NETSDK1022` (duplicate items) or `WMC1012` (multiple ApplicationXaml) after upgrading +- Publishing a self-contained app includes large, unused native dependencies like `onnxruntime.dll` and `DirectML.dll` +- Encountering warnings like `MSB8027` or `LNK4042` related to `WindowsAppRuntimeAutoInitializer.cpp` in solutions with multiple C++ projects +- Seeing `MSB3106` warnings about assembly strong names when using newer versions of WindowsAppSDK + +→ Check scenarios below for your specific cause + +--- + +## Related Issues + +- [#6091](https://github.com/microsoft/WindowsAppSDK/issues/6091) - Self-contained deployment breaks WinUI codegen in libraries (Status: Closed/Fixed in v2.0-preview1) +- [#5746](https://github.com/microsoft/WindowsAppSDK/issues/5746) - App update to 1.8-preview1 with COMException 0x80070490 errors (Status: Open) +- [#5969](https://github.com/microsoft/WindowsAppSDK/issues/5969) - Failed to get rid of ML libraries in app build (Status: Closed/Fixed in 1.8.4) +- [#6015](https://github.com/microsoft/WindowsAppSDK/issues/6015) - Huge native DLLs not trimmed in self-contained mode (Status: Closed) +- [#5395](https://github.com/microsoft/WindowsAppSDK/issues/5395) - MSB8027 and LNK4042 warnings with WindowsAppRuntimeAutoInitializer.cpp (Status: Open) + +--- + +## Scenarios & Solutions + +### Scenario 1: WindowsAppSDKSelfContained=true on Library Project Breaks XAML Codegen + +**Cause:** When `WindowsAppSDKSelfContained` is set to `true` in a class library project, the `_OverrideGetPriIndexName` target in `Microsoft.WindowsAppSDK.SelfContained.targets` (part of `Microsoft.WindowsAppSDK.Base` NuGet) sets the PRI root to empty. This is intended for app projects, not libraries, and causes WinUI XAML code generation to fail. The result is a `XamlParseException` at runtime or a silent launch failure. +> Source: @dongle-the-gadget in [#6091](https://github.com/microsoft/WindowsAppSDK/issues/6091) + +**Affected versions:** WinAppSDK 1.8.x (confirmed with 1.8.3 / 1.8.251106002) + +**Fix:** +1. **Remove** `WindowsAppSDKSelfContained` from all library/class library project files. Only set it on the main application (executable) project: + ```xml + + + + + + true + + ``` +2. If setting the property globally via command line (`dotnet msbuild /p:WindowsAppSDKSelfContained=true`), this will apply to all projects in the solution including libraries — avoid this pattern. + +> ✅ Confirmed by: @riverar (CONTRIBUTOR) in [#6091](https://github.com/microsoft/WindowsAppSDK/issues/6091) — removing the property from the library project resolves the issue. + +**Official fix:** This has been fixed in [Windows App SDK 2.0.0-Preview1](https://github.com/microsoft/WindowsAppSDK/releases/tag/v2.0-preview1) by adding explicit validation that prevents `WindowsAppSDKSelfContained` from being applied to class library projects. +> Source: @ssparach (CONTRIBUTOR) in [#6091](https://github.com/microsoft/WindowsAppSDK/issues/6091) + +**Verify:** Clean the solution, rebuild, and run the app — XAML should parse without exceptions. + +--- + +### Scenario 2: COMException 0x80070490 "Element not found" After Upgrading to 1.8 + +**Cause:** In WinAppSDK 1.8, the `.pri` file naming behavior changed for unpackaged projects. Previously (1.7 and earlier), `EnableMsixTooling=true` caused the `.pri` file to be named `resources.pri` even for unpackaged apps. In 1.8, unpackaged projects correctly use `[AppName].pri` instead. Code that hard-codes `resources.pri` will fail with COMException 0x80070490 ("Element not found") when accessing localized resources. +> Source: @Sella-GH in [#5746](https://github.com/microsoft/WindowsAppSDK/issues/5746), root cause analysis by @DarranRowe + +**Fix for COMException 0x80070490:** +1. Update any code that hard-codes `resources.pri` to use the correct file name. Use the Resource Manager API to determine the default path: + ```csharp + var resourceLoader = new Microsoft.Windows.ApplicationModel.Resources.ResourceLoader(); + ``` +2. If you have a custom resource loading service, update the file name from `resources.pri` to `[YourAppName].pri`. + +> ✅ Confirmed by: @Sella-GH in [#5746](https://github.com/microsoft/WindowsAppSDK/issues/5746) + +--- + +### Scenario 3: Large Native DLLs (onnxruntime.dll, DirectML.dll) Included in Self-Contained Builds + +**Cause:** When using `WindowsAppSDKSelfContained=true` with the default metapackage (`Microsoft.WindowsAppSDK`), all component packages are included, even if they are not used. This includes large native dependencies like `onnxruntime.dll` and `DirectML.dll` (used for ML scenarios), which unnecessarily increase the app size. +> Source: @manodasanW in [#5969](https://github.com/microsoft/WindowsAppSDK/issues/5969) + +**Fix:** +1. Replace the metapackage (`Microsoft.WindowsAppSDK`) with only the component packages you need. For example: + ```xml + + ``` +2. Remove the `Microsoft.WindowsAppSDK.Runtime` package unless explicitly required for your scenario. + +**Additional Fix for PublishSingleFile Issue:** Fixed in [1.8.4](https://github.com/microsoft/WindowsAppSDK/releases/tag/v1.8.4). +> Source: @manodasanW in [#5969](https://github.com/microsoft/WindowsAppSDK/issues/5969) + +**Verify:** Check the output folder for unnecessary DLLs: +```powershell +Get-ChildItem -Path "" -Filter "*.dll" +``` + +--- + +## ⚠️ Known Issues / Unverified Suggestions + +### Issue: MSB8027 and LNK4042 Warnings with WindowsAppRuntimeAutoInitializer.cpp + +**Cause:** When using multiple C++ projects in a solution, both referencing the same version of WindowsAppSDK, the `WindowsAppRuntimeAutoInitializer.cpp` file from the `buildTransitive` directory is included multiple times, causing duplicate object file warnings (`MSB8027`, `LNK4042`). +> Source: @PetrMinar in [#5395](https://github.com/microsoft/WindowsAppSDK/issues/5395) + +**Unverified Suggestions:** +- Modify the `ClCompile` item in `WindowsAppSDK-Nuget-Native.AutoInitializer.targets` to avoid duplicate inclusions. Example: + ```xml + + NotUsing + MICROSOFT_WINDOWSAPPSDK_AUTOINITIALIZE_BOOTSTRAP;%(PreprocessorDefinitions) + + ``` +> Source: @mschofie in [#5395](https://github.com/microsoft/WindowsAppSDK/issues/5395) + +--- + +## References + +- [Self-contained deployment documentation](https://learn.microsoft.com/en-us/windows/apps/windows-app-sdk/deploy-self-contained) +- [WinAppSDK 2.0.0-Preview1 release notes](https://github.com/microsoft/WindowsAppSDK/releases/tag/v2.0-preview1) +- [Resource management with MRT Core](https://learn.microsoft.com/en-us/windows/apps/windows-app-sdk/mrtcore/mrtcore-overview) + +--- + +**Updated:** 2026-03-17 | **Confidence:** 0.90 +**Sources:** [#6091](https://github.com/microsoft/WindowsAppSDK/issues/6091), [#5746](https://github.com/microsoft/WindowsAppSDK/issues/5746), [#5969](https://github.com/microsoft/WindowsAppSDK/issues/5969), [#6015](https://github.com/microsoft/WindowsAppSDK/issues/6015), [#5395](https://github.com/microsoft/WindowsAppSDK/issues/5395) \ No newline at end of file diff --git a/tsg/tsg_notifications_push_and_listener.md b/trouble-shooting-notes/tsg_notifications_push_and_listener.md similarity index 77% rename from tsg/tsg_notifications_push_and_listener.md rename to trouble-shooting-notes/tsg_notifications_push_and_listener.md index 942e837..26347e6 100644 --- a/tsg/tsg_notifications_push_and_listener.md +++ b/trouble-shooting-notes/tsg_notifications_push_and_listener.md @@ -1,182 +1,179 @@ -# Notification Issues — Push Notifications, Progress Data, and UserNotificationListener - -**Keywords:** AppNotification, push notification, unpackaged, COMException, 0x80070490, Element not found, UserNotificationListener, NotificationChanged, AppNotificationProgressData, IsIndeterminate, indeterminate progress bar, toast notification - -**Error Example:** -``` -System.Runtime.InteropServices.COMException (0x80070490): Element not found - at ABI.WinRT.Interop.EventSource`1.Subscribe(TDelegate handler) - at Windows.UI.Notifications.Management.UserNotificationListener.add_NotificationChanged(...) -``` - ---- - -## Quick Match - -**You're seeing this if:** -- Error contains `0x80070490` ("Element not found") when subscribing to notification events -- Push notifications fail in unpackaged or non-Store apps -- Cannot create an indeterminate progress bar in toast notifications via `AppNotificationProgressData` -- `UserNotificationListener.NotificationChanged` throws `COMException` in unpackaged apps -- Platform: Windows App SDK, WinUI 3, unpackaged or self-contained apps - -→ Check scenarios below for your specific cause - ---- - -## Related Issues - -- [#334](https://github.com/microsoft/WindowsAppSDK/issues/334) — Push Notifications for Unpackaged Apps and Non-Store Apps (Status: Closed — implemented) -- [#2231](https://github.com/microsoft/WindowsAppSDK/issues/2231) — Add IsIndeterminate to AppNotificationProgressData (Status: Open — In PR) -- [#6172](https://github.com/microsoft/WindowsAppSDK/issues/6172) — COMException 0x80070490 when subscribing to UserNotificationListener.NotificationChanged (Status: Open) - ---- - -## Scenarios & Solutions - -### Scenario 1: Push Notifications Not Available for Unpackaged / Non-Store Apps - -**Cause:** Historically, only Microsoft Store-distributed UWP/MSIX packaged apps could use Windows Push Notifications due to an explicit dependency on Store identity. Non-store and unpackaged Win32 apps had no way to use the push notification infrastructure and had to maintain their own socket connections. -> Source: Issue [#334](https://github.com/microsoft/WindowsAppSDK/issues/334) - -**Status:** ✅ **Resolved** — Windows App SDK now supports push notifications for all app types. - -**Supported configurations:** -| Packaging | App Types | -|-----------|-----------| -| ✅ Packaged apps | ✅ WPF, Win32 (C++), WinForms, Console | -| ✅ Unpackaged apps | ⚠️ Cross-platform (Electron, MAUI, React Native) — partial | - -**Fix — Using Push Notifications in Unpackaged Apps:** -1. **Register your app** with Azure Notification Hubs or WNS (Windows Notification Services) using the Windows App SDK push notification APIs. -2. **Use `AppNotificationManager`** for local and push notifications: -```csharp -// Register for push notifications (unpackaged app) -var manager = AppNotificationManager.Default; -manager.NotificationInvoked += OnNotificationInvoked; -manager.Register(); - -// Request a push notification channel -var channelResult = await PushNotificationManager.Default - .CreateChannelAsync(yourAzureAppId); -``` -3. For unpackaged apps, ensure you have the **Windows App SDK Runtime** installed or use a self-contained deployment. -4. Refer to the [Push notifications overview](https://learn.microsoft.com/en-us/windows/apps/windows-app-sdk/notifications/push-notifications/) for Azure setup. - -**Verify:** Send a test push notification and confirm it arrives in your unpackaged app. - ---- - -### Scenario 2: Cannot Set Indeterminate Progress Bar in Toast Notifications - -**Cause:** The `AppNotificationProgressData` API does not expose an `IsIndeterminate` property. In raw XML, setting `value="indeterminate"` on a `` element creates a loading animation, but this behavior cannot be achieved through the `AppNotificationProgressData` class — the `Value` property only accepts `double` values between 0.0 and 1.0. -> Source: Issue [#2231](https://github.com/microsoft/WindowsAppSDK/issues/2231) - -**Status:** 🔄 **In PR** — A fix is being developed (labeled "Status: In PR"). - -**Current limitation:** -```csharp -// This API does NOT support indeterminate state -var progressData = new AppNotificationProgressData(1); -progressData.Value = 0.5; // Only accepts 0.0 - 1.0 -progressData.Status = "Downloading..."; -// No IsIndeterminate property available -``` - -**Workaround — Use raw XML notification:** -```csharp -var xml = @" - - - - Downloading... - - - -"; - -var doc = new Windows.Data.Xml.Dom.XmlDocument(); -doc.LoadXml(xml); -var notification = new ToastNotification(doc); -ToastNotificationManager.CreateToastNotifier().Show(notification); -``` - -Alternatively, use the **Windows Community Toolkit** notification builder which supports indeterminate state: -```csharp -// Using CommunityToolkit.WinUI.Notifications -new ToastContentBuilder() - .AddText("Processing...") - .AddProgressBar(title: "Please wait", status: "Working...", - value: AdaptiveProgressBarValue.Indeterminate) - .Show(); -``` - -**Verify:** Toast notification shows an animated indeterminate progress bar. - ---- - -### Scenario 3: COMException 0x80070490 When Subscribing to UserNotificationListener.NotificationChanged - -**Cause:** In an unpackaged, self-contained WinUI 3 app, subscribing to `UserNotificationListener.NotificationChanged` throws `COMException` with HRESULT `0x80070490` ("Element not found"). Other `UserNotificationListener` APIs work correctly — `UserNotificationListener.Current` is accessible, `RequestAccessAsync()` returns `Allowed`, and `GetNotificationsAsync()` succeeds. Only the event subscription fails. -> Source: Issue [#6172](https://github.com/microsoft/WindowsAppSDK/issues/6172) - -**Affected versions:** Windows App SDK 1.8.4 (1.8.260101001), Windows 11 24H2, unpackaged self-contained apps - -**Repro:** -```csharp -var listener = UserNotificationListener.Current; -var access = await listener.RequestAccessAsync(); // Returns Allowed ✅ -var notifications = await listener.GetNotificationsAsync( - NotificationKinds.Toast); // Works ✅ - -listener.NotificationChanged += Listener_NotificationChanged; // Throws ❌ -// COMException (0x80070490): Element not found -``` - -**Repro project:** https://github.com/koiseka/notificationchangedexample-repro - -**Fix / Workaround:** -1. **Package the app as MSIX** — the `NotificationChanged` event subscription requires package identity to properly register the event handler with the notification platform. -2. **Use polling instead of events** as a workaround for unpackaged apps: -```csharp -// Poll for notification changes every N seconds -var timer = new DispatcherTimer { Interval = TimeSpan.FromSeconds(5) }; -timer.Tick += async (s, e) => -{ - var listener = UserNotificationListener.Current; - var notifications = await listener.GetNotificationsAsync( - NotificationKinds.Toast); - // Compare with previous list to detect changes - ProcessNotificationChanges(notifications); -}; -timer.Start(); -``` -3. If MSIX packaging is an option, add package identity using [Sparse Package](https://learn.microsoft.com/en-us/windows/apps/desktop/modernize/grant-identity-to-nonpackaged-apps) to enable event registration without full MSIX deployment. - -> ⚠️ This is an open issue. The `NotificationChanged` event does not support unpackaged apps. - -**Verify:** Confirm that `NotificationChanged` fires after packaging the app, or that the polling approach correctly detects notification changes. - ---- - -## ⚠️ Unverified / Community Suggestions - -> The following are community suggestions that have NOT been officially confirmed. - -- For #6172: Granting identity via External Location registration (`AddPackageByUriAsync` with `ExternalLocationUri`) may enable event subscription without full MSIX packaging, but this has not been tested with `UserNotificationListener`. -- For #2231: Until the official `IsIndeterminate` API ships, the raw XML approach is the most reliable workaround for indeterminate progress bars in toast notifications. - ---- - -## References - -- [Push notifications overview — Windows App SDK](https://learn.microsoft.com/en-us/windows/apps/windows-app-sdk/notifications/push-notifications/) -- [App notifications overview — Windows App SDK](https://learn.microsoft.com/en-us/windows/apps/windows-app-sdk/notifications/app-notifications/) -- [Toast content XML schema — progress element](https://learn.microsoft.com/en-us/windows/apps/design/shell/tiles-and-notifications/toast-schema#adaptiveprogressbarvalue) -- [UserNotificationListener API](https://learn.microsoft.com/en-us/uwp/api/windows.ui.notifications.management.usernotificationlistener) -- [Grant identity to non-packaged apps (Sparse Package)](https://learn.microsoft.com/en-us/windows/apps/desktop/modernize/grant-identity-to-nonpackaged-apps) - ---- - -**Updated:** 2025-07-17 | **Confidence:** 0.7 -**Sources:** #334, #2231, #6172 +# Notification Issues — Push Notifications, Progress Data, and UserNotificationListener + +**Keywords:** AppNotification, push notification, unpackaged, COMException, 0x80070490, Element not found, UserNotificationListener, NotificationChanged, AppNotificationProgressData, IsIndeterminate, indeterminate progress bar, toast notification, BadgeNotificationManager, REGDB_E_CLASSNOTREG, ScheduledToastNotification + +**Error Example:** +``` +System.Runtime.InteropServices.COMException (0x80070490): Element not found + at ABI.WinRT.Interop.EventSource`1.Subscribe(TDelegate handler) + at Windows.UI.Notifications.Management.UserNotificationListener.add_NotificationChanged(...) +``` + +--- + +## Quick Match + +**You're seeing this if:** +- Error contains `0x80070490` ("Element not found") when subscribing to notification events +- Push notifications fail in unpackaged or non-Store apps +- Cannot create an indeterminate progress bar in toast notifications via `AppNotificationProgressData` +- `UserNotificationListener.NotificationChanged` throws `COMException` in unpackaged apps +- BadgeNotificationManager.Current throws `COMException REGDB_E_CLASSNOTREG` +- Missing API for scheduling toast notifications in Windows App SDK +- Platform: Windows App SDK, WinUI 3, unpackaged or self-contained apps + +→ Check scenarios below for your specific cause + +--- + +## Related Issues + +- [#334](https://github.com/microsoft/WindowsAppSDK/issues/334) — Push Notifications for Unpackaged Apps and Non-Store Apps (Status: Closed — implemented) +- [#2231](https://github.com/microsoft/WindowsAppSDK/issues/2231) — Add IsIndeterminate to AppNotificationProgressData (Status: Open — In PR) +- [#6172](https://github.com/microsoft/WindowsAppSDK/issues/6172) — COMException 0x80070490 when subscribing to UserNotificationListener.NotificationChanged (Status: Open) +- [#5050](https://github.com/microsoft/WindowsAppSDK/issues/5050) — Feature Request: Schedule toast notifications (Status: Open) +- [#5307](https://github.com/microsoft/WindowsAppSDK/issues/5307) — COMException REGDB_E_CLASSNOTREG from BadgeNotificationManager (Status: Closed — resolved in 1.7.1) + +--- + +## Scenarios & Solutions + +### Scenario 1: Push Notifications Not Available for Unpackaged / Non-Store Apps + +**Cause:** Historically, only Microsoft Store-distributed UWP/MSIX packaged apps could use Windows Push Notifications due to an explicit dependency on Store identity. Non-store and unpackaged Win32 apps had no way to use the push notification infrastructure and had to maintain their own socket connections. +> Source: Issue [#334](https://github.com/microsoft/WindowsAppSDK/issues/334) + +**Status:** ✅ **Resolved** — Windows App SDK now supports push notifications for all app types. + +**Supported configurations:** +| Packaging | App Types | +|-----------|-----------| +| ✅ Packaged apps | ✅ WPF, Win32 (C++), WinForms, Console | +| ✅ Unpackaged apps | ⚠️ Cross-platform (Electron, MAUI, React Native) — partial | + +**Fix — Using Push Notifications in Unpackaged Apps:** +1. **Register your app** with Azure Notification Hubs or WNS (Windows Notification Services) using the Windows App SDK push notification APIs. +2. **Use `AppNotificationManager`** for local and push notifications: +```csharp +// Register for push notifications (unpackaged app) +var manager = AppNotificationManager.Default; +manager.NotificationInvoked += OnNotificationInvoked; +manager.Register(); + +// Request a push notification channel +var channelResult = await PushNotificationManager.Default + .CreateChannelAsync(yourAzureAppId); +``` +3. For unpackaged apps, ensure you have the **Windows App SDK Runtime** installed or use a self-contained deployment. +4. Refer to the [Push notifications overview](https://learn.microsoft.com/en-us/windows/apps/windows-app-sdk/notifications/push-notifications/) for Azure setup. + +**Verify:** Send a test push notification and confirm it arrives in your unpackaged app. + +--- + +### Scenario 2: Cannot Set Indeterminate Progress Bar in Toast Notifications + +**Cause:** The `AppNotificationProgressData` API does not expose an `IsIndeterminate` property. In raw XML, setting `value="indeterminate"` on a `` element creates a loading animation, but this behavior cannot be achieved through the `AppNotificationProgressData` class — the `Value` property only accepts `double` values between 0.0 and 1.0. +> Source: Issue [#2231](https://github.com/microsoft/WindowsAppSDK/issues/2231) + +**Status:** 🔄 **In PR** — A fix is being developed (labeled "Status: In PR"). + +**Workaround — Use raw XML notification:** +```csharp +var xml = @" + + + + Downloading... + + + +"; + +var doc = new Windows.Data.Xml.Dom.XmlDocument(); +doc.LoadXml(xml); +var notification = new ToastNotification(doc); +ToastNotificationManager.CreateToastNotifier().Show(notification); +``` + +Alternatively, use the **Windows Community Toolkit** notification builder which supports indeterminate state: +```csharp +// Using CommunityToolkit.WinUI.Notifications +new ToastContentBuilder() + .AddText("Processing...") + .AddProgressBar(title: "Please wait", status: "Working...", + value: AdaptiveProgressBarValue.Indeterminate) + .Show(); +``` + +**Verify:** Toast notification shows an animated indeterminate progress bar. + +--- + +### Scenario 3: COMException 0x80070490 When Subscribing to UserNotificationListener.NotificationChanged + +**Cause:** In an unpackaged, self-contained WinUI 3 app, subscribing to `UserNotificationListener.NotificationChanged` throws `COMException` with HRESULT `0x80070490` ("Element not found"). Other `UserNotificationListener` APIs work correctly — `UserNotificationListener.Current` is accessible, `RequestAccessAsync()` returns `Allowed`, and `GetNotificationsAsync()` succeeds. Only the event subscription fails. +> Source: Issue [#6172](https://github.com/microsoft/WindowsAppSDK/issues/6172) + +**Fix / Workaround:** +1. **Package the app as MSIX** — the `NotificationChanged` event subscription requires package identity to properly register the event handler with the notification platform. +2. **Use polling instead of events** as a workaround for unpackaged apps: +```csharp +// Poll for notification changes every N seconds +var timer = new DispatcherTimer { Interval = TimeSpan.FromSeconds(5) }; +timer.Tick += async (s, e) => +{ + var listener = UserNotificationListener.Current; + var notifications = await listener.GetNotificationsAsync( + NotificationKinds.Toast); + // Compare with previous list to detect changes + ProcessNotificationChanges(notifications); +}; +timer.Start(); +``` + +--- + +### Scenario 4: Missing API for Scheduling Toast Notifications + +**Cause:** The Windows App SDK does not currently provide an API for scheduling toast notifications, unlike the deprecated `Microsoft.Toolkit.Uwp.Notifications` API which supported `Schedule()` functionality. +> Source: @true-perfect-code in [#5050](https://github.com/microsoft/WindowsAppSDK/issues/5050) + +**Workaround — Use UWP APIs:** +```csharp +var notifier = ToastNotificationManager.CreateToastNotifier(); +var scheduledToast = new ScheduledToastNotification(toastContent, deliveryTime); +notifier.AddToSchedule(scheduledToast); +``` + +--- + +### Scenario 5: COMException REGDB_E_CLASSNOTREG from BadgeNotificationManager + +**Cause:** This issue occurs when attempting to access `BadgeNotificationManager.Current` in certain configurations. It was resolved in Windows App SDK version 1.7.1. +> Source: @zhuxb711 in [#5307](https://github.com/microsoft/WindowsAppSDK/issues/5307) + +**Fix:** Upgrade to Windows App SDK 1.7.1 or later. + +--- + +## ⚠️ Unverified / Community Suggestions + +> The following are community suggestions that have NOT been officially confirmed. + +- For #6172: Granting identity via External Location registration (`AddPackageByUriAsync` with `ExternalLocationUri`) may enable event subscription without full MSIX packaging. +- For #5050: Use UWP APIs for scheduling toast notifications until Windows App SDK provides native support. + +--- + +## References + +- [Push notifications overview — Windows App SDK](https://learn.microsoft.com/en-us/windows/apps/windows-app-sdk/notifications/push-notifications/) +- [Toast content XML schema — progress element](https://learn.microsoft.com/en-us/windows/apps/design/shell/tiles-and-notifications/toast-schema#adaptiveprogressbarvalue) +- [UserNotificationListener API](https://learn.microsoft.com/en-us/uwp/api/windows.ui.notifications.management.usernotificationlistener) +- [Grant identity to non-packaged apps (Sparse Package)](https://learn.microsoft.com/en-us/windows/apps/desktop/modernize/grant-identity-to-nonpackaged-apps) + +--- + +**Updated:** 2026-03-17 | **Confidence:** 0.8 +**Sources:** #334, #2231, #6172, #5050, #5307 \ No newline at end of file diff --git a/tsg/tsg_resources_mrt_localization.md b/trouble-shooting-notes/tsg_resources_mrt_localization.md similarity index 62% rename from tsg/tsg_resources_mrt_localization.md rename to trouble-shooting-notes/tsg_resources_mrt_localization.md index 9ce5cfa..e2a5422 100644 --- a/tsg/tsg_resources_mrt_localization.md +++ b/trouble-shooting-notes/tsg_resources_mrt_localization.md @@ -1,151 +1,193 @@ -# Error: "COMException: NamedResource Not Found" / PrimaryLanguageOverride Not Working — MRT Resource Loading - -**Keywords:** ResourceLoader, GetString, COMException, NamedResource Not Found, PrimaryLanguageOverride, unpackaged, localization, x:Uid, MRTCore, Resources.resw, dot in key, signing projection - -**Error Example:** -``` -COMException: NamedResource Not Found. -``` -``` -COMException: No such interface supported -``` - ---- - -## Quick Match - -**You're seeing this if:** -- `ResourceLoader.GetString()` throws `COMException` for keys containing `.` (dots) -- `PrimaryLanguageOverride` does not work in unpackaged WinUI 3 apps -- `x:Uid` XAML localization fails for unpackaged apps -- Signing `Microsoft.Windows.ApplicationModel.Resources.Projection` fails during build - -→ Check scenarios below for your specific cause - ---- - -## Related Issues - -- [#6247](https://github.com/microsoft/WindowsAppSDK/issues/6247) — ResourceLoader.GetString throws COMException for keys containing '.' (Status: Open) -- [#1687](https://github.com/microsoft/WindowsAppSDK/issues/1687) — Support PrimaryLanguageOverride from unpackaged apps (Status: Closed/Fixed in 1.6-experimental2) -- [#3705](https://github.com/microsoft/WindowsAppSDK/issues/3705) — Signing Resources.Projection fails with ilasm errors (Status: Closed) - ---- - -## Scenarios & Solutions - -### Scenario 1: ResourceLoader.GetString Fails for Keys Containing Dots - -**Cause:** Resource keys that contain `.` (period/dot) characters are not resolved correctly by `ResourceLoader.GetString()`. The MRT/PRI key normalization or URI fragment semantics treat `.` as a path separator, causing the lookup to fail with `NamedResource Not Found`. -> Source: Issue reporter in [#6247](https://github.com/microsoft/WindowsAppSDK/issues/6247) - -**Example:** -```csharp -// FAILS — throws COMException: NamedResource Not Found -var loader = new ResourceLoader(); -var value = loader.GetString("XXXXX.Common.Yes"); - -// WORKS — returns expected value -var value = loader.GetString("XXXXX_Common_Yes"); -``` - -**Fix:** -Replace `.` with `_` in resource key names in your `Resources.resw` file and update all code references accordingly. - -| Before | After | -|--------|-------| -| `XXXXX.Common.Yes` | `XXXXX_Common_Yes` | -| `App.Settings.Title` | `App_Settings_Title` | - -> ⚠️ No official confirmation on whether `.` is a supported character in resource keys for `ResourceLoader.GetString`. The issue is open and under investigation. - -**Verify:** -```csharp -var loader = new ResourceLoader(); -var value = loader.GetString("XXXXX_Common_Yes"); -Debug.Assert(value == "Yes"); -``` - ---- - -### Scenario 2: PrimaryLanguageOverride Not Working in Unpackaged Apps - -**Cause:** `Windows.Globalization.ApplicationLanguages.PrimaryLanguageOverride` was designed for packaged apps only. Calling it from an unpackaged context threw an error, breaking `x:Uid` XAML localization for unpackaged WinUI 3 apps. -> Source: @btueffers (CONTRIBUTOR) and @andrewleader (CONTRIBUTOR) in [#1687](https://github.com/microsoft/WindowsAppSDK/issues/1687) - -**Fix (WASDK 1.6+ experimental and later):** -Use the new WinAppSDK-specific API instead of the Windows.Globalization API: -```csharp -// Use this (WinAppSDK API — works for both packaged and unpackaged): -Microsoft.Windows.Globalization.ApplicationLanguages.PrimaryLanguageOverride = "en-US"; - -// Instead of this (Windows platform API — packaged only): -Windows.Globalization.ApplicationLanguages.PrimaryLanguageOverride = "en-US"; -``` - -> ✅ Confirmed working by: @ghost1372 (CONTRIBUTOR) in [#1687](https://github.com/microsoft/WindowsAppSDK/issues/1687) — tested in 1.6.240701003-experimental2 - -**Pre-fix workaround (for older WASDK versions):** -Use `ResourceContext` directly and set the `Language` qualifier value: -```csharp -var context = new ResourceContext(); -context.QualifierValues["Language"] = "en-US"; -// Pass this context to resource lookups -``` -> Source: @huichen123 (CONTRIBUTOR) in [#1687](https://github.com/microsoft/WindowsAppSDK/issues/1687) - -**Community alternative:** -The [WinUI3Localizer](https://www.nuget.org/packages/WinUI3Localizer/) NuGet package works with unpackaged apps and uses standard `Resources.resw` strings. -> Source: @AndrewKeepCoding in [#1687](https://github.com/microsoft/WindowsAppSDK/issues/1687) - ---- - -### Scenario 3: COMException During First Use of PrimaryLanguageOverride (Unpackaged) - -**Cause:** Even after upgrading to a WASDK version with the fix, some users encountered `COMException: No such interface supported` when first using `PrimaryLanguageOverride` in unpackaged apps. -> Source: @TheVoidSeeker in [#1687](https://github.com/microsoft/WindowsAppSDK/issues/1687) - -**Fix:** -1. Repair your Visual Studio installation. -2. Clean all intermediate and output files (`bin/`, `obj/`). -3. Rebuild the project. - -> ✅ Confirmed by: @TheVoidSeeker in [#1687](https://github.com/microsoft/WindowsAppSDK/issues/1687) — resolved after VS repair + clean rebuild - ---- - -### Scenario 4: Signing Microsoft.Windows.ApplicationModel.Resources.Projection Fails - -**Cause:** When using code analyzers configured for assembly signing, attempting to sign the `Microsoft.Windows.ApplicationModel.Resources.Projection` assembly via `ildasm`/`ilasm` round-trip fails. The assembly contains non-standard IL patterns (non-virtual instance methods in interfaces) that `ilasm` rejects. -> Source: Issue reporter in [#3705](https://github.com/microsoft/WindowsAppSDK/issues/3705) - -**Error:** -``` -error : Method cannot have body if it is non-static declared in interface abstract -error : Non-public instance method in interface -``` - -**Fix:** WASDK 1.3 has reached End of Support. Upgrade to WASDK 1.8 or later where this may be resolved. If the issue persists on 1.8+, file a new issue. -> Source: @alexlamtest (CONTRIBUTOR) in [#3705](https://github.com/microsoft/WindowsAppSDK/issues/3705) - ---- - -## ⚠️ Unverified / Community Suggestions - -> The following are community suggestions that have NOT been officially confirmed. - -- XAML Islands (non-WinUI 3) apps using `Windows.Globalization.ApplicationLanguages.PrimaryLanguageOverride` still do not work without packaging; WASDK fix only covers MRTCore-based scenarios (from @sylveon in #1687) -- On WASDK 1.8, `PrimaryLanguageOverride` value may not persist across app relaunch — see Known Issue #6118 (from @Galebra in #1687) - ---- - -## References - -- [ResourceLoader.GetString API docs](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.windows.applicationmodel.resources.resourceloader.getstring) -- [MRTCore ResourceContext source](https://github.com/microsoft/WindowsAppSDK/blob/main/dev/MRTCore/mrt/Microsoft.Windows.ApplicationModel.Resources/src/ResourceContext.cpp) -- [WinUI3Localizer NuGet](https://www.nuget.org/packages/WinUI3Localizer/) - ---- - -**Updated:** 2026-03-13 | **Confidence:** 0.8 -**Sources:** #6247, #1687, #3705 +# Error: "COMException: NamedResource Not Found" / PrimaryLanguageOverride Not Working — MRT Resource Loading + +**Keywords:** ResourceLoader, GetString, COMException, NamedResource Not Found, PrimaryLanguageOverride, unpackaged, localization, x:Uid, MRTCore, Resources.resw, dot in key, signing projection, resources.pri, MrmGetFilePathFromName, ResourceManager, ResourceLoaderTest, MICROSOFT_WINDOWSAPPRUNTIME_BASE_DIRECTORY, PublishSingleFile + +**Error Example:** +``` +COMException: NamedResource Not Found. +``` +``` +COMException: No such interface supported +``` +``` +System.IO.FileNotFoundException: Unable to find the specified file. +``` + +--- + +## Quick Match + +**You're seeing this if:** +- `ResourceLoader.GetString()` throws `COMException` for keys containing `.` (dots) +- `PrimaryLanguageOverride` does not work in unpackaged WinUI 3 apps +- `x:Uid` XAML localization fails for unpackaged apps +- Signing `Microsoft.Windows.ApplicationModel.Resources.Projection` fails during build +- `MrmGetFilePathFromName` reports `ERROR_FILE_NOT_FOUND` when `resources.pri` is missing +- `ResourceLoader` crashes with `System.IO.FileNotFoundException` in unpackaged apps +- Launching one WinAppSDK app from another fails due to `MICROSOFT_WINDOWSAPPRUNTIME_BASE_DIRECTORY` + +→ Check scenarios below for your specific cause + +--- + +## Related Issues + +- [#6247](https://github.com/microsoft/WindowsAppSDK/issues/6247) — ResourceLoader.GetString throws COMException for keys containing '.' (Status: Open) +- [#1687](https://github.com/microsoft/WindowsAppSDK/issues/1687) — Support PrimaryLanguageOverride from unpackaged apps (Status: Closed/Fixed in 1.6-experimental2) +- [#3705](https://github.com/microsoft/WindowsAppSDK/issues/3705) — Signing Resources.Projection fails with ilasm errors (Status: Closed) +- [#5814](https://github.com/microsoft/WindowsAppSDK/issues/5814) — MrmGetFilePathFromName now reports error when `resources.pri` is missing (Status: Closed) +- [#5832](https://github.com/microsoft/WindowsAppSDK/issues/5832) — Upgrading to v1.8 breaks ResourceLoader in unpackaged apps (Status: Open) +- [#5987](https://github.com/microsoft/WindowsAppSDK/issues/5987) — MRTCore using MICROSOFT_WINDOWSAPPRUNTIME_BASE_DIRECTORY breaks launching one WinAppSDK app from another (Status: Open) + +--- + +## Scenarios & Solutions + +### Scenario 1: ResourceLoader.GetString Fails for Keys Containing Dots + +**Cause:** Resource keys that contain `.` (period/dot) characters are not resolved correctly by `ResourceLoader.GetString()`. The MRT/PRI key normalization or URI fragment semantics treat `.` as a path separator, causing the lookup to fail with `NamedResource Not Found`. +> Source: Issue reporter in [#6247](https://github.com/microsoft/WindowsAppSDK/issues/6247) + +**Example:** +```csharp +// FAILS — throws COMException: NamedResource Not Found +var loader = new ResourceLoader(); +var value = loader.GetString("XXXXX.Common.Yes"); + +// WORKS — returns expected value +var value = loader.GetString("XXXXX_Common_Yes"); +``` + +**Fix:** +Replace `.` with `_` in resource key names in your `Resources.resw` file and update all code references accordingly. + +| Before | After | +|--------|-------| +| `XXXXX.Common.Yes` | `XXXXX_Common_Yes` | +| `App.Settings.Title` | `App_Settings_Title` | + +> ⚠️ No official confirmation on whether `.` is a supported character in resource keys for `ResourceLoader.GetString`. The issue is open and under investigation. + +**Verify:** +```csharp +var loader = new ResourceLoader(); +var value = loader.GetString("XXXXX_Common_Yes"); +Debug.Assert(value == "Yes"); +``` + +--- + +### Scenario 2: PrimaryLanguageOverride Not Working in Unpackaged Apps + +**Cause:** `Windows.Globalization.ApplicationLanguages.PrimaryLanguageOverride` was designed for packaged apps only. Calling it from an unpackaged context threw an error, breaking `x:Uid` XAML localization for unpackaged WinUI 3 apps. +> Source: @btueffers (CONTRIBUTOR) and @andrewleader (CONTRIBUTOR) in [#1687](https://github.com/microsoft/WindowsAppSDK/issues/1687) + +**Fix (WASDK 1.6+ experimental and later):** +Use the new WinAppSDK-specific API instead of the Windows.Globalization API: +```csharp +// Use this (WinAppSDK API — works for both packaged and unpackaged): +Microsoft.Windows.Globalization.ApplicationLanguages.PrimaryLanguageOverride = "en-US"; + +// Instead of this (Windows platform API — packaged only): +Windows.Globalization.ApplicationLanguages.PrimaryLanguageOverride = "en-US"; +``` + +> ✅ Confirmed working by: @ghost1372 (CONTRIBUTOR) in [#1687](https://github.com/microsoft/WindowsAppSDK/issues/1687) — tested in 1.6.240701003-experimental2 + +**Pre-fix workaround (for older WASDK versions):** +Use `ResourceContext` directly and set the `Language` qualifier value: +```csharp +var context = new ResourceContext(); +context.QualifierValues["Language"] = "en-US"; +// Pass this context to resource lookups +``` +> Source: @huichen123 (CONTRIBUTOR) in [#1687](https://github.com/microsoft/WindowsAppSDK/issues/1687) + +**Community alternative:** +The [WinUI3Localizer](https://www.nuget.org/packages/WinUI3Localizer/) NuGet package works with unpackaged apps and uses standard `Resources.resw` strings. +> Source: @AndrewKeepCoding in [#1687](https://github.com/microsoft/WindowsAppSDK/issues/1687) + +--- + +### Scenario 3: COMException During First Use of PrimaryLanguageOverride (Unpackaged) + +**Cause:** Even after upgrading to a WASDK version with the fix, some users encountered `COMException: No such interface supported` when first using `PrimaryLanguageOverride` in unpackaged apps. +> Source: @TheVoidSeeker in [#1687](https://github.com/microsoft/WindowsAppSDK/issues/1687) + +**Fix:** +1. Repair your Visual Studio installation. +2. Clean all intermediate and output files (`bin/`, `obj/`). +3. Rebuild the project. + +> ✅ Confirmed by: @TheVoidSeeker in [#1687](https://github.com/microsoft/WindowsAppSDK/issues/1687) — resolved after VS repair + clean rebuild + +--- + +### Scenario 4: MrmGetFilePathFromName Reports ERROR_FILE_NOT_FOUND + +**Cause:** Starting with WASDK 1.8, `MrmGetFilePathFromName` now checks for the existence of `resources.pri` and returns `ERROR_FILE_NOT_FOUND` if the file is missing. This can break `ResourceManager` in unpackaged apps. +> Source: @Alovchin91 in [#5814](https://github.com/microsoft/WindowsAppSDK/issues/5814) + +**Fix:** +Subscribe to the `Application.ResourceManagerRequested` event and provide a custom `ResourceManager` instance pointing to the correct `.pri` file: +```csharp +Application.ResourceManagerRequested += (sender, args) => +{ + args.ResourceManager = new ResourceManager(""); +}; +``` +> Source: @Alovchin91 in [#5814](https://github.com/microsoft/WindowsAppSDK/issues/5814) + +--- + +### Scenario 5: ResourceLoader Crashes with FileNotFoundException in Unpackaged Apps (WASDK 1.8) + +**Cause:** In WASDK 1.8, the default `.pri` file name was changed from `resources.pri` to `.pri`. If the application expects `resources.pri`, it will fail to find the file and throw a `FileNotFoundException`. +> Source: @beeradmoore in [#5832](https://github.com/microsoft/WindowsAppSDK/issues/5832) + +**Fix:** +Manually rename `.pri` to `resources.pri` after every build: +```xml + + + +``` +> Source: @gautambjain in [#5832](https://github.com/microsoft/WindowsAppSDK/issues/5832) + +**Alternative:** Use Syncfusion's latest WinUI3 suite (31.2.2) with WASDK 1.8.251003001, which resolves this issue for some users. +> Source: @Steffens-Bridgemate in [#5832](https://github.com/microsoft/WindowsAppSDK/issues/5832) + +--- + +## Known Issues + +### Issue: MRTCore using MICROSOFT_WINDOWSAPPRUNTIME_BASE_DIRECTORY breaks launching one WinAppSDK app from another + +**Cause:** When a WinAppSDK application sets the `MICROSOFT_WINDOWSAPPRUNTIME_BASE_DIRECTORY` environment variable, MRTCore skips all local resource PRI locations (e.g., `ModuleName.pri`) and only loads `resources.pri` from the specified directory. This causes issues when one WinAppSDK app launches another using `CreateProcess`, as the environment variable is inherited. +> Source: @DHowett [MSFT] in [#5987](https://github.com/microsoft/WindowsAppSDK/issues/5987) + +**Status:** Open + +**Workaround:** None confirmed. Avoid using the `MICROSOFT_WINDOWSAPPRUNTIME_BASE_DIRECTORY` environment variable if possible. + +--- + +## ⚠️ Unverified / Community Suggestions + +> The following are community suggestions that have NOT been officially confirmed. + +- XAML Islands (non-WinUI 3) apps using `Windows.Globalization.ApplicationLanguages.PrimaryLanguageOverride` still do not work without packaging; WASDK fix only covers MRTCore-based scenarios (from @sylveon in #1687) +- On WASDK 1.8, `PrimaryLanguageOverride` value may not persist across app relaunch — see Known Issue #6118 (from @Galebra in #1687) + +--- + +## References + +- [ResourceLoader.GetString API docs](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.windows.applicationmodel.resources.resourceloader.getstring) +- [MRTCore ResourceContext source](https://github.com/microsoft/WindowsAppSDK/blob/main/dev/MRTCore/mrt/Microsoft.Windows.ApplicationModel.Resources/src/ResourceContext.cpp) +- [WinUI3Localizer NuGet](https://www.nuget.org/packages/WinUI3Localizer/) + +--- + +**Updated:** 2026-03-17 | **Confidence:** 0.8 +**Sources:** #6247, #1687, #3705, #5814, #5832, #5987 \ No newline at end of file diff --git a/trouble-shooting-notes/tsg_runtime_missing_dependencies.md b/trouble-shooting-notes/tsg_runtime_missing_dependencies.md new file mode 100644 index 0000000..77ef2ff --- /dev/null +++ b/trouble-shooting-notes/tsg_runtime_missing_dependencies.md @@ -0,0 +1,66 @@ +# Error: "Package dependency criteria could not be resolved" (0x80670016) - MddBootstrapInitialize + +**Keywords:** Package dependency criteria could not be resolved, 0x80670016, MddBootstrapInitialize, WindowsAppRuntime.Bootstrap.dll + +**Error Example:** +``` +Package dependency criteria could not be resolved +``` + +--- + +## Quick Match + +**You're seeing this if:** +- Error contains "Package dependency criteria could not be resolved" +- Calling `MddBootstrapInitialize` +- Platform: Windows 11, Visual Studio 2022 + +→ Check scenarios below for your specific cause + +--- + +## Related Issues + +- [#5530](https://github.com/microsoft/WindowsAppSDK/issues/5530) - MddBootstrapInitialize fails with error "Package dependency criteria could not be resolved" (Status: Closed) + +--- + +## Scenarios & Solutions + +### Scenario 1: Hardcoded version mismatch in sample code + +**Cause:** The version specified in the sample code (`majorMinorVersion`) does not match the installed version of the Windows App Runtime. The sample code uses a hardcoded version (`0x00010002`), which may not align with the installed runtime version. +> Source: @lb90 in [#5530](https://github.com/microsoft/WindowsAppSDK/issues/5530) + +**Fix:** +1. Update the `majorMinorVersion` in your code to match the installed version of the Windows App Runtime. + - For example, if the installed version is `1.7`, update the code to: + ```c++ + const UINT32 majorMinorVersion{ 0x00010007 }; + ``` +2. Rebuild and run your application. + +> ✅ Confirmed by: @lb90 in issue comments + +**Verify:** Run your application again. The error should no longer occur. + +--- + +## ⚠️ Unverified / Community Suggestions + +> The following are community suggestions that have NOT been officially confirmed. + +- None for this issue. + +--- + +## References + +- [Windows App SDK Tutorial - Unpackaged Deployment](https://learn.microsoft.com/en-us/windows/apps/windows-app-sdk/tutorial-unpackaged-deployment?tabs=cpp) +- [Windows App SDK Downloads](https://learn.microsoft.com/en-us/windows/apps/windows-app-sdk/downloads) + +--- + +**Updated:** 2026-03-17 | **Confidence:** 0.9 +**Sources:** [#5530](https://github.com/microsoft/WindowsAppSDK/issues/5530) \ No newline at end of file diff --git a/trouble-shooting-notes/tsg_runtime_winrt_interop.md b/trouble-shooting-notes/tsg_runtime_winrt_interop.md new file mode 100644 index 0000000..659a9ee --- /dev/null +++ b/trouble-shooting-notes/tsg_runtime_winrt_interop.md @@ -0,0 +1,151 @@ +# WinRT Interop, AOT Compatibility & Runtime Version Issues - Windows App SDK + +**Keywords:** AOT, trimming, FrameworkElement, theme, LaunchActivatedEventArgs, WinRT, CsWinRT, IInspectable, ReleaseInfo, version string, HDR, CompositionDrawingSurface, scRGB, swap chain, DirectXPixelFormat, ApplicationDataContainer, MathML, C++WinRT, Dispose, GetVirtualMethodTableInfoForKey, AppInstance, FindOrRegisterForKey, ArgumentException, COMException + +**Error Example:** +``` +// AOT theme switching failure +(Window.Content as FrameworkElement) returns null when published with AOT + +// LaunchActivatedEventArgs interop +AppActivationArguments.Data shows as WinRT.IInspectable instead of LaunchActivatedEventArgs + +// ReleaseInfo version mismatch +ReleaseInfo.AsString returns "1.7.0" on WinAppSDK 1.7.1 runtime + +// HDR composition +CompositionDrawingSurface with R16G16B16A16Float renders as SDR in WinAppSDK + +// ApplicationDataContainer Dispose crash +Calling Dispose() on ApplicationDataContainer throws "Specified cast is not valid" on Windows 10 + +// MathML crash in RichEditBox +Setting MathML content in RichEditBox causes app crash + +// C++WinRT interop error +CS0400: The type or namespace name could not be found in the global namespace + +// AppInstance.FindOrRegisterForKey exception +FindOrRegisterForKey("main") throws ArgumentException or COMException +``` + +--- + +## Quick Match + +**You're seeing this if:** +- Theme switching code fails silently when app is published with Native AOT +- `Window.Content as FrameworkElement` returns `null` in AOT builds +- `AppActivationArguments.Data` is `WinRT.IInspectable` instead of a typed activation args object +- `ReleaseInfo.AsString` returns wrong version (e.g., "1.7.0" on 1.7.1) +- HDR content renders as SDR when using `CompositionDrawingSurface` with float16 pixel format +- `ApplicationDataContainer.Dispose()` throws "Specified cast is not valid" on Windows 10 +- Setting MathML content in `RichEditBox` crashes the app +- C++WinRT component in C# project causes CS0400 error +- `AppInstance.FindOrRegisterForKey` throws `ArgumentException` or `COMException` + +→ Check scenarios below for your specific cause + +--- + +## Related Issues + +- [#5389](https://github.com/microsoft/WindowsAppSDK/issues/5389) - Unable to change theme color when AOT is released (Status: Closed, area-AOT) +- [#6219](https://github.com/microsoft/WindowsAppSDK/issues/6219) - WASDK LaunchActivatedEventArgs cannot be directly converted into WinRT (Status: Open, area-Projections) +- [#5323](https://github.com/microsoft/WindowsAppSDK/issues/5323) - ReleaseInfo returns "1.7.0" in 1.7.1 release (Status: Closed, area-VersionInfo) +- [#6291](https://github.com/microsoft/WindowsAppSDK/issues/6291) - Unlike UWP, WindowsAppSdk does not support HDR composition (Status: Closed) +- [#5633](https://github.com/microsoft/WindowsAppSDK/issues/5633) - ApplicationDataContainer throws "Specified cast is not valid" exception on Dispose() (Status: Closed, area-dotnet) +- [#5257](https://github.com/microsoft/WindowsAppSDK/issues/5257) - App Crashes When Setting `MathML` in `RichEditBox` (Status: Closed, area-WinUI) +- [#5071](https://github.com/microsoft/WindowsAppSDK/issues/5071) - Using a C++WinRT component in C# project error CS0400 (Status: Open, area-Projections) +- [#5694](https://github.com/microsoft/WindowsAppSDK/issues/5694) - AppInstance.FindOrRegisterForKey throws ArgumentException: The parameter is incorrect (Status: Open, area-Lifecycle) + +--- + +## Scenarios & Solutions + +### Scenario 1: Theme Switching Fails Under Native AOT (Trimming) + +**Cause:** When publishing a WinUI app with Native AOT, the .NET trimmer removes `FrameworkElement` because the C# code doesn't directly construct it. As a result, `Window.Content as FrameworkElement` returns `null`, and theme switching code silently fails. The `as` operator cannot succeed because the type metadata has been trimmed. +> Source: @manodasanW (MEMBER) in [#5389](https://github.com/microsoft/WindowsAppSDK/issues/5389) + +**Fix:** [See full details in the original TSG] + +--- + +### Scenario 2: WASDK LaunchActivatedEventArgs Not Convertible to WinRT Type + +**Cause:** [See full details in the original TSG] + +--- + +### Scenario 3: ReleaseInfo.AsString Returns Wrong Patch Version + +**Cause:** The `ReleaseInfo.AsString` API in Windows App SDK 1.7.1 incorrectly returns "1.7.0" instead of the expected "1.7.1". This is due to a known issue where the `Patch` property always shows as "0" in version 1.7.x. +> Source: @RDMacLachlan (MSFT) in [#5323](https://github.com/microsoft/WindowsAppSDK/issues/5323) + +**Workaround:** None. This issue is resolved in Windows App SDK 1.8.4 and later, where the `ReleaseInfo` API returns a more accurate version string. + +**Environment:** +- Windows App SDK 1.7.1 +- Windows 11 version 24H2 (22621, October 2024 Update) + +--- + +### Scenario 4: HDR Composition Not Supported in WinAppSDK (UWP Parity Gap) + +**Cause:** [See full details in the original TSG] + +--- + +### Scenario 5: ApplicationDataContainer.Dispose() Throws "Specified Cast Is Not Valid" + +**Cause:** [See full details in the original TSG] + +--- + +### Scenario 6: Setting MathML Content in RichEditBox Causes Crash + +**Cause:** [See full details in the original TSG] + +--- + +### Scenario 7: C++WinRT Component in C# Project Causes CS0400 Error + +**Cause:** [See full details in the original TSG] + +--- + +### Scenario 8: AppInstance.FindOrRegisterForKey Throws ArgumentException or COMException + +**Cause:** The `AppInstance.FindOrRegisterForKey` method can throw exceptions such as `ArgumentException`, `COMException`, or `UnauthorizedAccessException` under certain conditions. These issues may be related to incorrect parameters, COM activation issues, or permission problems. +> Source: @tipa in [#5694](https://github.com/microsoft/WindowsAppSDK/issues/5694) + +**Workaround:** None confirmed. Developers encountering this issue are advised to log the exception details and ensure that the key passed to `FindOrRegisterForKey` is valid and unique. Further investigation is ongoing. + +**Environment:** +- Windows App SDK 1.7.3 +- Windows 11 version 24H2 LTSC (26100, June Update) + +--- + +## ⚠️ Unverified / Community Suggestions + +> The following are community suggestions that have NOT been officially confirmed. + +- For HDR (#6291): Using a custom DirectComposition swap chain with `DXGI_FORMAT_R16G16B16A16_FLOAT` created outside of WinUI's compositor may enable HDR rendering, but this bypasses the WinUI composition tree (not confirmed). +- For ApplicationDataContainer (#5633): Using `` in the app manifest may prevent crashes on unsupported Windows versions. +- For `AppInstance.FindOrRegisterForKey` (#5694): Ensure that the key is unique and valid. Some users have reported issues with specific Windows versions or configurations. + +--- + +## References + +- [CsWinRT 2.3 Preview - NuGet](https://www.nuget.org/packages/Microsoft.Windows.CsWinRT/2.3.0-prerelease.251115.2) +- [MathML Specification](https://www.w3.org/TR/MathML3/) +- [WinAppSDK ReleaseInfo API](https://learn.microsoft.com/en-us/windows/windows-app-sdk/api/winrt/microsoft.windows.applicationmodel.windowsappruntime.releaseinfo) +- [HDR and Advanced Color in Windows](https://learn.microsoft.com/en-us/windows/win32/direct3darticles/high-dynamic-range) + +--- + +**Updated:** 2026-03-17 | **Confidence:** 0.8 +**Sources:** #5389, #6219, #5323, #6291, #5633, #5257, #5071, #5694 \ No newline at end of file diff --git a/trouble-shooting-notes/tsg_touch_events_applicationdata.md b/trouble-shooting-notes/tsg_touch_events_applicationdata.md new file mode 100644 index 0000000..c689788 --- /dev/null +++ b/trouble-shooting-notes/tsg_touch_events_applicationdata.md @@ -0,0 +1,75 @@ +# Error: "Touch events stop working in a WPF packaged app after using ApplicationData.Current" + +**Keywords:** touch events, ApplicationData.Current, WPF, packaged app, MSIX, Windows App SDK + +**Error Example:** +``` +Touch events stop working in a WPF packaged app after using ApplicationData.Current +``` + +--- + +## Quick Match + +**You're seeing this if:** +- Touch events stop working in your WPF packaged app +- You're using `ApplicationData.Current` or related APIs like `ApplicationData.GetForUser`, `ApplicationData.GetForPackageFamily`, or `ApplicationData.GetDefault` +- Platform: Windows 10 version 22H2 (19045, 2022 Update) or similar + +→ Check scenarios below for your specific cause + +--- + +## Related Issues + +- [#5167](https://github.com/microsoft/WindowsAppSDK/issues/5167) - Touch events stop working in a WPF packaged app after using ApplicationData.Current (Status: Open) + +--- + +## Scenarios & Solutions + +### Scenario 1: Accessing `ApplicationData.Current` too early in the application lifecycle + +**Cause:** Accessing `ApplicationData.Current` or related APIs during the initialization phase (e.g., in the constructor of `App.xaml.cs` or `MainWindow`) can interfere with touch event handling in WPF packaged apps. This may be related to COM initialization issues on the thread. +> Source: @yeelam-gordon in [#5167](https://github.com/microsoft/WindowsAppSDK/issues/5167) + +**Fix:** +1. Delay the call to `ApplicationData.Current` or related APIs until after the initialization phase. + - For example, use `Task.Run` or access it in a later event or property. +2. Avoid calling `ApplicationData.Current` in the constructor of `App.xaml.cs` or `MainWindow`. + +> ✅ Confirmed by: @yeelam-gordon, @asierpn in issue comments + +**Verify:** Ensure touch events work as expected after delaying the call to `ApplicationData.Current`. + +--- + +### Scenario 2: Potential COM initialization issue + +**Cause:** Using COM-related APIs (like `ApplicationData.Current`) on a thread before COM is properly initialized can cause unexpected behavior, including issues with touch events. +> Source: @DrusTheAxe in [#5167](https://github.com/microsoft/WindowsAppSDK/issues/5167) + +**Fix:** +1. Ensure that COM is properly initialized on the thread before calling `ApplicationData.Current`. +2. Refer to the related issue [dotnet/wpf#2393](https://github.com/dotnet/wpf/issues/2393) for additional context and potential workarounds. + +--- + +## ⚠️ Unverified / Community Suggestions + +> The following are community suggestions that have NOT been officially confirmed. + +- "Try the workaround mentioned in [dotnet/wpf#2393](https://github.com/dotnet/wpf/issues/2393)." (from @ekalchev in [#5167](https://github.com/microsoft/WindowsAppSDK/issues/5167)) + +--- + +## References + +- [Official docs](https://learn.microsoft.com/en-us/dotnet/maui/platform-integration/storage/preferences?view=net-maui-9.0&tabs=windows) +- [API docs](https://learn.microsoft.com/en-us/uwp/api/windows.storage.applicationdata) +- [dotnet/wpf#2393](https://github.com/dotnet/wpf/issues/2393) + +--- + +**Updated:** 2026-03-17 | **Confidence:** 0.8 +**Sources:** [#5167](https://github.com/microsoft/WindowsAppSDK/issues/5167), [dotnet/wpf#2393](https://github.com/dotnet/wpf/issues/2393) \ No newline at end of file diff --git a/trouble-shooting-notes/tsg_webview2_and_sdk_integration.md b/trouble-shooting-notes/tsg_webview2_and_sdk_integration.md new file mode 100644 index 0000000..f5dc5a5 --- /dev/null +++ b/trouble-shooting-notes/tsg_webview2_and_sdk_integration.md @@ -0,0 +1,83 @@ +# Error: "Could not copy the file 'WebView2Loader.dll' because it was not found" (MSB3030) - WebView2 Integration with Windows App SDK + +**Keywords:** MSB3030, WebView2Loader.dll, WebView2, Windows App SDK, WinUI3, XAML.MapControl.WinUI + +**Error Example:** +``` +C:\Program Files\Microsoft Visual Studio\2022\Professional\MSBuild\Current\Bin\amd64\Microsoft.Common.CurrentVersion.targets(5322,5): error MSB3030: Could not copy the file "c:\temp\xaml.mapcontrol.winui\12.1.0\lib\net8.0-windows10.0.17763\MapControl.WinUI\runtimes\win-arm64\native\WebView2Loader.dll" because it was not found. +C:\Program Files\Microsoft Visual Studio\2022\Professional\MSBuild\Current\Bin\amd64\Microsoft.Common.CurrentVersion.targets(5322,5): error MSB3030: Could not copy the file "c:\temp\xaml.mapcontrol.winui\12.1.0\lib\net8.0-windows10.0.17763\MapControl.WinUI\runtimes\win-x64\native\WebView2Loader.dll" because it was not found. +C:\Program Files\Microsoft Visual Studio\2022\Professional\MSBuild\Current\Bin\amd64\Microsoft.Common.CurrentVersion.targets(5322,5): error MSB3030: Could not copy the file "c:\temp\xaml.mapcontrol.winui\12.1.0\lib\net8.0-windows10.0.17763\MapControl.WinUI\runtimes\win-x86\native\WebView2Loader.dll" because it was not found. +``` + +--- + +## Quick Match + +**You're seeing this if:** +- Error contains "MSB3030" and mentions "WebView2Loader.dll" +- Occurs when referencing a class library that uses `Microsoft.WindowsAppSDK` or `XAML.MapControl.WinUI` +- Platform: Windows 10 or Windows 11 + +→ Check scenarios below for your specific cause + +--- + +## Related Issues + +- [#5058](https://github.com/microsoft/WindowsAppSDK/issues/5058) - Error MSB3030 when referencing a class library with WebView2Loader.dll (Status: Closed) +- [#5489](https://github.com/microsoft/WindowsAppSDK/issues/5489) - WebView2 stopped working after installing a package (Status: Closed) + +--- + +## Scenarios & Solutions + +### Scenario 1: Missing WebView2Loader.dll in Class Library References + +**Cause:** When referencing a class library that uses `Microsoft.WindowsAppSDK` or `XAML.MapControl.WinUI`, the `WebView2Loader.dll` file may not be properly included in the build output. This issue is linked to the version of the `Microsoft.WindowsAppSDK` package used in the project. +> Source: @RDMacLachlan [MSFT] in [#5058](https://github.com/microsoft/WindowsAppSDK/issues/5058) + +**Fix:** +1. Update the `Microsoft.WindowsAppSDK` package in your project to version `1.7` or later. This version includes updates to the WebView2 reference that resolve the issue. +2. Ensure that all dependent projects in your solution are also updated to use the same version of `Microsoft.WindowsAppSDK`. + +> ✅ Confirmed by: @RDMacLachlan [MSFT] in [#5058](https://github.com/microsoft/WindowsAppSDK/issues/5058) + +**Verify:** Rebuild your solution and confirm that the error no longer occurs. + +--- + +### Scenario 2: WebView2 Not Working After Installing a Package + +**Cause:** The issue occurs due to a conflict with the default C#/WinRT projection used by WebView2 in certain scenarios, such as when integrating with WPF. +> Source: @1592363624 in [#5489](https://github.com/microsoft/WindowsAppSDK/issues/5489) + +**Fix:** +1. Add the following property to your project file to override the default use of WebView2's C#/WinRT projection: + ```xml + false + ``` + +> ✅ Confirmed by: @1592363624 in [#5489](https://github.com/microsoft/WindowsAppSDK/issues/5489) + +**Verify:** Test your application to ensure that WebView2 is functioning as expected. + +--- + +## ⚠️ Unverified / Community Suggestions + +> The following are community suggestions that have NOT been officially confirmed. + +- None reported for these issues. + +--- + +## References + +- [#5058](https://github.com/microsoft/WindowsAppSDK/issues/5058) +- [#5489](https://github.com/microsoft/WindowsAppSDK/issues/5489) +- [Failure to build when Microsoft.WindowsAppSDK 1.6 referenced through secondary nuget package #4807](https://github.com/microsoft/WindowsAppSDK/issues/4807) + +--- + +**Updated:** 2026-03-17 | **Confidence:** 0.9 +**Sources:** [#5058](https://github.com/microsoft/WindowsAppSDK/issues/5058), [#5489](https://github.com/microsoft/WindowsAppSDK/issues/5489) \ No newline at end of file diff --git a/tsg/tsg_widgets_customization_display.md b/trouble-shooting-notes/tsg_widgets_customization_display.md similarity index 98% rename from tsg/tsg_widgets_customization_display.md rename to trouble-shooting-notes/tsg_widgets_customization_display.md index f454986..0520e7a 100644 --- a/tsg/tsg_widgets_customization_display.md +++ b/trouble-shooting-notes/tsg_widgets_customization_display.md @@ -1,121 +1,121 @@ -# Widget Customization and Display Failures - Windows Widgets Platform - -**Keywords:** widget customization, template JSON, OnCustomizationRequested, widget board, add widget, widget list, Widgets panel - -**Error Example:** -``` -Widget customization card grows but template does not render. -OnCustomizationRequested callback never gets executed. -Widget "Add" button remains grayed out / inactive for first item in list. -``` - ---- - -## Quick Match - -**You're seeing this if:** -- Widget customization panel opens but shows no content -- `OnCustomizationRequested` callback is never invoked by widget host -- First widget in alphabetical list cannot be added to widget board -- Widget "Add" button stays inactive until switching to another widget and back - -→ Check scenarios below for your specific cause - ---- - -## Related Issues - -- [#3926](https://github.com/microsoft/WindowsAppSDK/issues/3926) - Widget Customization does not show template JSON (Status: Closed, area-Widgets) -- [#6140](https://github.com/microsoft/WindowsAppSDK/issues/6140) - Widget at top of list cannot be added until switching away and back (Status: Open, area-External) - ---- - -## Scenarios & Solutions - -### Scenario 1: Widget Customization Template Not Rendering - -**Cause:** When selecting "✏️ Customize Widget" on a widget provider, the customization card area grows/expands but the customization template JSON is never displayed. Debugging reveals that the `OnCustomizationRequested` callback is never executed by the widget host. This means the Windows Widget host is not properly invoking the customization flow defined in the widget provider. -> Source: Issue author in [#3926](https://github.com/microsoft/WindowsAppSDK/issues/3926) - -**Symptoms:** -- Following the official Microsoft documentation for [Implementing widget customization](https://learn.microsoft.com/en-us/windows/apps/develop/widgets/implement-widget-provider-cs#implementing-widget-customization) -- The customization card area expands when "Customize Widget" is selected -- The `OnCustomizationRequested` callback in the widget provider code is never triggered -- No template JSON content is rendered in the customization area - -**Steps to reproduce:** -1. Implement a widget provider following the official Microsoft Learning documentation for widget customization -2. Register and deploy the widget -3. Open the Widgets panel and select "✏️ Customize Widget" -4. Observe: the card grows but no customization template appears - -**Fix:** -1. Verify your widget provider correctly implements the `IWidgetProvider2` interface which includes `OnCustomizationRequested` -2. Ensure your widget manifest declares customization support correctly -3. Confirm the widget host version supports the customization API — this issue was observed with WinAppSDK 1.4-era widget platform -4. Check that you are returning a valid Adaptive Card JSON template from your customization handler -5. If the callback is still not invoked, this may be a platform-level bug in the Widget host. Monitor the issue for updates from Microsoft - -**Environment:** -- Reported against the widget platform with WinAppSDK widget provider APIs -- Behavior observed in Windows 11 widget board - -**Verify:** -Confirm `OnCustomizationRequested` is hit by adding a breakpoint or debug log: -```csharp -public void OnCustomizationRequested(WidgetCustomizationRequestedArgs args) -{ - Debug.WriteLine($"Customization requested for widget: {args.WidgetContext.Id}"); - // Return your customization template JSON -} -``` - ---- - -### Scenario 2: First Widget in Alphabetical List Cannot Be Added - -**Cause:** On Windows 11 25H2 (Build 26220.7535), when a widget whose name starts with the letter "A" appears at the very top of the widget list, the "Add" button remains grayed out / inactive. The widget can only be added after switching to a different widget and then switching back. This is a UI state initialization bug in the Windows Widgets Board panel. -> Source: Issue author in [#6140](https://github.com/microsoft/WindowsAppSDK/issues/6140) - -**Steps to reproduce:** -1. Open the Widgets panel on Windows 11 25H2 -2. Click the "+" button to add a new widget -3. The first widget in the list (alphabetically, starting with "A") is automatically selected -4. Attempt to add the widget — the Add button stays gray/inactive -5. Select a different widget in the list -6. Return to the original widget -7. Now the Add button becomes active and the widget can be added - -**Fix:** -1. This is a Windows Widgets Board platform bug (labeled `area-External`), not a widget provider issue -2. **User workaround:** Select any other widget in the list first, then switch back to the desired widget — the Add button will activate -3. **Developer impact:** If your widget name starts with "A" or appears first alphabetically, users may report inability to add it. Document this workaround in your widget's support materials -4. No code-level fix is available on the widget provider side — this requires a platform fix from Microsoft - -**Environment:** -- OS: Windows 11 25H2 (Build 26220.7535) -- Widget Platform: Windows Widgets Board -- Reproducibility: Always - ---- - -## ⚠️ Unverified / Community Suggestions - -> The following are community suggestions that have NOT been officially confirmed. - -- For Scenario 1: Ensure your widget provider DLL is correctly registered and the COM server is running. Some developers report that re-registering the package resolves callback issues (community reports, not confirmed in #3926) -- For Scenario 2: Renaming your widget to not start with "A" is a theoretical workaround, but this should not be necessary and the platform bug should be fixed (from #6140 discussion) - ---- - -## References - -- [Implementing Widget Customization - Microsoft Learn](https://learn.microsoft.com/en-us/windows/apps/develop/widgets/implement-widget-provider-cs#implementing-widget-customization) -- [Widget Provider Development - Microsoft Learn](https://learn.microsoft.com/en-us/windows/apps/develop/widgets/) -- [#3926 - Widget Customization does not show template JSON](https://github.com/microsoft/WindowsAppSDK/issues/3926) -- [#6140 - Widget at top of list cannot be added](https://github.com/microsoft/WindowsAppSDK/issues/6140) - ---- - -**Updated:** 2025-07-17 | **Confidence:** 0.6 -**Sources:** #3926, #6140, Microsoft Learn widget documentation +# Widget Customization and Display Failures - Windows Widgets Platform + +**Keywords:** widget customization, template JSON, OnCustomizationRequested, widget board, add widget, widget list, Widgets panel + +**Error Example:** +``` +Widget customization card grows but template does not render. +OnCustomizationRequested callback never gets executed. +Widget "Add" button remains grayed out / inactive for first item in list. +``` + +--- + +## Quick Match + +**You're seeing this if:** +- Widget customization panel opens but shows no content +- `OnCustomizationRequested` callback is never invoked by widget host +- First widget in alphabetical list cannot be added to widget board +- Widget "Add" button stays inactive until switching to another widget and back + +→ Check scenarios below for your specific cause + +--- + +## Related Issues + +- [#3926](https://github.com/microsoft/WindowsAppSDK/issues/3926) - Widget Customization does not show template JSON (Status: Closed, area-Widgets) +- [#6140](https://github.com/microsoft/WindowsAppSDK/issues/6140) - Widget at top of list cannot be added until switching away and back (Status: Open, area-External) + +--- + +## Scenarios & Solutions + +### Scenario 1: Widget Customization Template Not Rendering + +**Cause:** When selecting "✏️ Customize Widget" on a widget provider, the customization card area grows/expands but the customization template JSON is never displayed. Debugging reveals that the `OnCustomizationRequested` callback is never executed by the widget host. This means the Windows Widget host is not properly invoking the customization flow defined in the widget provider. +> Source: Issue author in [#3926](https://github.com/microsoft/WindowsAppSDK/issues/3926) + +**Symptoms:** +- Following the official Microsoft documentation for [Implementing widget customization](https://learn.microsoft.com/en-us/windows/apps/develop/widgets/implement-widget-provider-cs#implementing-widget-customization) +- The customization card area expands when "Customize Widget" is selected +- The `OnCustomizationRequested` callback in the widget provider code is never triggered +- No template JSON content is rendered in the customization area + +**Steps to reproduce:** +1. Implement a widget provider following the official Microsoft Learning documentation for widget customization +2. Register and deploy the widget +3. Open the Widgets panel and select "✏️ Customize Widget" +4. Observe: the card grows but no customization template appears + +**Fix:** +1. Verify your widget provider correctly implements the `IWidgetProvider2` interface which includes `OnCustomizationRequested` +2. Ensure your widget manifest declares customization support correctly +3. Confirm the widget host version supports the customization API — this issue was observed with WinAppSDK 1.4-era widget platform +4. Check that you are returning a valid Adaptive Card JSON template from your customization handler +5. If the callback is still not invoked, this may be a platform-level bug in the Widget host. Monitor the issue for updates from Microsoft + +**Environment:** +- Reported against the widget platform with WinAppSDK widget provider APIs +- Behavior observed in Windows 11 widget board + +**Verify:** +Confirm `OnCustomizationRequested` is hit by adding a breakpoint or debug log: +```csharp +public void OnCustomizationRequested(WidgetCustomizationRequestedArgs args) +{ + Debug.WriteLine($"Customization requested for widget: {args.WidgetContext.Id}"); + // Return your customization template JSON +} +``` + +--- + +### Scenario 2: First Widget in Alphabetical List Cannot Be Added + +**Cause:** On Windows 11 25H2 (Build 26220.7535), when a widget whose name starts with the letter "A" appears at the very top of the widget list, the "Add" button remains grayed out / inactive. The widget can only be added after switching to a different widget and then switching back. This is a UI state initialization bug in the Windows Widgets Board panel. +> Source: Issue author in [#6140](https://github.com/microsoft/WindowsAppSDK/issues/6140) + +**Steps to reproduce:** +1. Open the Widgets panel on Windows 11 25H2 +2. Click the "+" button to add a new widget +3. The first widget in the list (alphabetically, starting with "A") is automatically selected +4. Attempt to add the widget — the Add button stays gray/inactive +5. Select a different widget in the list +6. Return to the original widget +7. Now the Add button becomes active and the widget can be added + +**Fix:** +1. This is a Windows Widgets Board platform bug (labeled `area-External`), not a widget provider issue +2. **User workaround:** Select any other widget in the list first, then switch back to the desired widget — the Add button will activate +3. **Developer impact:** If your widget name starts with "A" or appears first alphabetically, users may report inability to add it. Document this workaround in your widget's support materials +4. No code-level fix is available on the widget provider side — this requires a platform fix from Microsoft + +**Environment:** +- OS: Windows 11 25H2 (Build 26220.7535) +- Widget Platform: Windows Widgets Board +- Reproducibility: Always + +--- + +## ⚠️ Unverified / Community Suggestions + +> The following are community suggestions that have NOT been officially confirmed. + +- For Scenario 1: Ensure your widget provider DLL is correctly registered and the COM server is running. Some developers report that re-registering the package resolves callback issues (community reports, not confirmed in #3926) +- For Scenario 2: Renaming your widget to not start with "A" is a theoretical workaround, but this should not be necessary and the platform bug should be fixed (from #6140 discussion) + +--- + +## References + +- [Implementing Widget Customization - Microsoft Learn](https://learn.microsoft.com/en-us/windows/apps/develop/widgets/implement-widget-provider-cs#implementing-widget-customization) +- [Widget Provider Development - Microsoft Learn](https://learn.microsoft.com/en-us/windows/apps/develop/widgets/) +- [#3926 - Widget Customization does not show template JSON](https://github.com/microsoft/WindowsAppSDK/issues/3926) +- [#6140 - Widget at top of list cannot be added](https://github.com/microsoft/WindowsAppSDK/issues/6140) + +--- + +**Updated:** 2025-07-17 | **Confidence:** 0.6 +**Sources:** #3926, #6140, Microsoft Learn widget documentation diff --git a/trouble-shooting-notes/tsg_winml_aot_issues.md b/trouble-shooting-notes/tsg_winml_aot_issues.md new file mode 100644 index 0000000..d6ab9a8 --- /dev/null +++ b/trouble-shooting-notes/tsg_winml_aot_issues.md @@ -0,0 +1,82 @@ +# Error: "The product is not applicable or cannot be found." (0x80073D3B) - Windows ML Execution Provider + +**Keywords:** 0x80073D3B, The product is not applicable or cannot be found, Windows ML, Execution Provider, Native AOT, WSUS, Microsoft.Windows.AI.MachineLearning + +**Error Example:** +``` +Exception thrown at 0x00007FF99FC566CA (KernelBase.dll) in CppConsoleDesktop.exe: WinRT originate error - 0x80073D3B : 'Deployment Add operation with target volume on Package Windows.Workload.ExecutionProvider.OpenVino.amd64 from: (Windows.Workload.ExecutionProvider.OpenVino.amd64) failed with error 0x80073D3B. See http://go.microsoft.com/fwlink/?LinkId=235160 for help diagnosing app deployment issues.'. +C:\__w\1\s\dev\PackageManager\API\M.W.M.D.PackageDeploymentManager.cpp(1989)\Microsoft.WindowsAppRuntime.dll!00007FF873D2DFEE: (caller: 00007FF873D865DF) ReturnHr(1) tid(7858) 80073D3B The product is not applicable or cannot be found. + Msg:[ExtendedError:0x80073D3B PackageFamilyName:MicrosoftCorporationII.WinML.Intel.OpenVINO.EP.1.8_8wekyb3d8bbwe PackageUri:uup://Product/Windows.Workload.ExecutionProvider.OpenVino.amd64 : Deployment Add operation with target volume on Package Windows.Workload.ExecutionProvider.OpenVino.amd64 from: (Windows.Workload.ExecutionProvider.OpenVino.amd64) failed with error 0x80073D3B. See http://go.microsoft.com/fwlink/?LinkId=235160 for help diagnosing app deployment issues.] CallContext:[\EnsurePackageSetReadyAsync] +``` + +--- + +## Quick Match + +**You're seeing this if:** +- Error contains "The product is not applicable or cannot be found" or "0x80073D3B" +- Encountered while using Windows ML Execution Provider +- Platform: Windows 11 (24H1 or 24H2) + +→ Check scenarios below for your specific cause + +--- + +## Related Issues + +- [#5882](https://github.com/microsoft/WindowsAppSDK/issues/5882) - `Microsoft.Windows.AI.MachineLearning` does not support Native AOT (Status: Closed, Fixed in 1.8.251106002) +- [#5862](https://github.com/microsoft/WindowsAppSDK/issues/5862) - Fetching Execution provider with WindowsML ends up with "The product is not applicable or cannot be found." (Status: Open) + +--- + +## Scenarios & Solutions + +### Scenario 1: Using an outdated version of the Windows App SDK + +**Cause:** The issue occurs because the `Microsoft.Windows.AI.MachineLearning` package includes projection DLLs via its targets, which may cause problems with Native AOT publishing. +> Source: @manodasanW [MSFT] in [#5882](https://github.com/microsoft/WindowsAppSDK/issues/5882) + +**Fix:** +1. Update the Windows App SDK to version `1.8.251106002` or later, where this issue has been addressed. + +> ✅ Confirmed by: @manodasanW [MSFT], @Gaoyifei1011 in issue comments + +**Verify:** Ensure that no managed DLLs are included in the output directory when publishing with Native AOT. + +--- + +### Scenario 2: Enterprise WSUS server blocking Execution Provider downloads + +**Cause:** The issue occurs when the system is configured to use a non-default WSUS (Windows Server Update Services) server, which may not deliver the required Execution Provider packages. +> Source: @vlejeune-dxo in [#5862](https://github.com/microsoft/WindowsAppSDK/issues/5862) + +**Fix:** +1. Temporarily switch to the official Microsoft Update server: + - Open the Windows Update settings. + - Change the update source to the official Microsoft Update server. +2. Retry the operation to fetch the Execution Provider. + +> ✅ Confirmed by: @vlejeune-dxo in issue comments + +**Verify:** Ensure that the Execution Provider is successfully downloaded and the application runs without the error. + +--- + +## ⚠️ Unverified / Community Suggestions + +> The following are community suggestions that have NOT been officially confirmed. + +- Ensure that the WSUS server is configured to deliver the required Execution Provider packages. For more details, consult the [official Microsoft documentation](http://go.microsoft.com/fwlink/?LinkId=235160). + > Source: @vlejeune-dxo in [#5862](https://github.com/microsoft/WindowsAppSDK/issues/5862) + +--- + +## References + +- [Official docs](http://go.microsoft.com/fwlink/?LinkId=235160) +- [API docs](https://learn.microsoft.com/en-us/windows/ai/windows-ml/) + +--- + +**Updated:** 2026-03-17 | **Confidence:** 0.9 +**Sources:** [#5882](https://github.com/microsoft/WindowsAppSDK/issues/5882), [#5862](https://github.com/microsoft/WindowsAppSDK/issues/5862) \ No newline at end of file diff --git a/tsg/tsg_msix_project_configuration_tooling.md b/tsg/tsg_msix_project_configuration_tooling.md deleted file mode 100644 index 34bb4c0..0000000 --- a/tsg/tsg_msix_project_configuration_tooling.md +++ /dev/null @@ -1,150 +0,0 @@ -# Error: MSIX Project Configuration & Build Tools Issues - -**Keywords:** EnableMsixTooling, Microsoft.Windows.SDK.BuildTools.MSIX, AppxOSMinVersionReplaceManifestVersion, AppxOSMaxVersionTestedReplaceManifestVersion, mspdbcmf.exe, wapproj, single-project MSIX, NuGet, Visual Studio, unpackaged, resources.pri - -**Error Examples:** -``` -error: "mspdbcmf.exe" hard-coded path dependency into Visual Studio installation -error: MinVersion and MaxVersionTested always replaced in package.appxmanifest -Application crashes due to missing resources.pri after publish -``` - ---- - -## Quick Match - -**You're seeing this if:** -- Building MSIX packages without Visual Studio installed fails due to missing `mspdbcmf.exe` -- Removing `EnableMsixTooling` from unpackaged app projects causes publish failures or missing `.pri` files -- `AppxOSMinVersionReplaceManifestVersion=false` is ignored by single-project MSIX -- Need to include multiple executables in a single MSIX package - -→ Check scenarios below for your specific cause - ---- - -## Related Issues - -- [#6197](https://github.com/microsoft/WindowsAppSDK/issues/6197) - MSIX NuGet package requires Visual Studio for mspdbcmf.exe (Status: Fixed internally) -- [#3718](https://github.com/microsoft/WindowsAppSDK/issues/3718) - Removing EnableMsixTooling breaks published unpackaged apps (Status: Open) -- [#5598](https://github.com/microsoft/WindowsAppSDK/issues/5598) - BuildTools.MSIX does not support AppxOSMinVersionReplaceManifestVersion (Status: Open) -- [#5586](https://github.com/microsoft/WindowsAppSDK/issues/5586) - Single-project packaging lacks multi-executable support (Status: Open) - ---- - -## Scenarios & Solutions - -### Scenario 1: Cannot Build MSIX Without Visual Studio — mspdbcmf.exe Hard-Coded Path - -**Cause:** The `Microsoft.Windows.SDK.BuildTools.MSIX` NuGet package targets contain a hard-coded path dependency on a Visual Studio installation to locate `mspdbcmf.exe`. This prevents MSIX package creation on machines without Visual Studio (e.g., when using JetBrains Rider or CI/CD environments with only the .NET SDK). -> Source: @wjk in [#6197](https://github.com/microsoft/WindowsAppSDK/issues/6197) - -**Status:** Marked as "Fixed internally" by the Windows App SDK team. The fix has not yet been released as of the issue's last update. - -**Workaround (while waiting for fix):** -1. If you only need to bypass symbol generation, set: - ```xml - - None - false - - ``` -2. If you need `mspdbcmf.exe`, install the Visual Studio Build Tools workload (lighter than full VS): - ``` - vs_buildtools.exe --add Microsoft.VisualStudio.Workload.ManagedDesktopBuildTools - ``` - -> ⚠️ Ideally the MSIX NuGet package would bundle `mspdbcmf.exe` or reference it from `Microsoft.Windows.SDK.BuildTools`. Neither option is currently available. - -**Verify:** `dotnet publish` completes without errors referencing Visual Studio paths. - ---- - -### Scenario 2: Removing EnableMsixTooling Breaks Published Unpackaged Apps (Missing resources.pri) - -**Cause:** `EnableMsixTooling` controls the renaming of `[ProjectName].pri` to `resources.pri` during the build process. When omitted from an unpackaged app project (`None`), the `.pri` file is not copied to the publish directory, causing the published app to crash at runtime with a missing resource error. -> Source: @Balkoth in [#3718](https://github.com/microsoft/WindowsAppSDK/issues/3718) - -**Fix:** -1. **Option A:** Keep `EnableMsixTooling` in the project file even for unpackaged apps: - ```xml - - None - true - - ``` -2. **Option B:** Manually copy the `.pri` file as a post-build step: - ```xml - - - - ``` - -> ✅ Confirmed by: @Balkoth in [#3718](https://github.com/microsoft/WindowsAppSDK/issues/3718) — manually copying the `.pri` file resolves the crash. - -**Important note on WinAppSDK 1.8+:** @DarranRowe identified in [#5746](https://github.com/microsoft/WindowsAppSDK/issues/5746) that in WinAppSDK 1.8, the behavior changed — unpackaged projects now correctly use `[AppName].pri` instead of `resources.pri`. If upgrading to 1.8, update any hard-coded references to `resources.pri` in your code. - -> @Psychlist1972 in [#3718](https://github.com/microsoft/WindowsAppSDK/issues/3718) noted that without `EnableMsixTooling`, `dotnet` command-line builds fail to generate the `.pri` file at all, breaking automated build processes. - -**Verify:** Published output directory contains the `.pri` file, and the application launches without resource-related crashes. - ---- - -### Scenario 3: AppxOSMinVersionReplaceManifestVersion Not Supported by Single-Project MSIX - -**Cause:** The `UpdateTargetDeviceFamily` task in `WinAppSdkGenerateAppxManifest.cs` (part of `Microsoft.Windows.SDK.BuildTools.MSIX`) does not support the `AppxOSMinVersionReplaceManifestVersion` and `AppxOSMaxVersionTestedReplaceManifestVersion` override properties. It always replaces `MinVersion` and `MaxVersionTested` in the generated `package.appxmanifest` with values from `TargetPlatformMinVersion` and `TargetPlatformVersion`, even when the override properties are set to `false`. -> Source: @Scottj1s in [#5598](https://github.com/microsoft/WindowsAppSDK/issues/5598) — internal tracking issue created at task.ms/58588581 - -**Context:** For UWP and wapproj-based projects, these override properties work correctly. The gap is only in the single-project MSIX tooling provided by the BuildTools.MSIX NuGet package. - -**Workaround:** -1. Use a post-build step to patch the generated `package.appxmanifest` with the desired values: - ```xml - - - - ``` -2. Alternatively, set `TargetPlatformMinVersion` and `TargetPlatformVersion` to match your desired manifest values (if acceptable for your project). - -**Verify:** Inspect the generated `package.appxmanifest` to confirm `MinVersion` and `MaxVersionTested` values match your expectations. - ---- - -### Scenario 4: Single-Project Packaging Does Not Support Multiple Executables - -**Cause:** Single-project MSIX packaging does not support multi-headed packages (packages containing multiple executables). This is the last remaining gap versus wapproj-based solutions, preventing the complete deprecation of the WAP project template. -> Source: @Scottj1s in [#5586](https://github.com/microsoft/WindowsAppSDK/issues/5586) - -**Current status:** This is a feature gap, not a bug. Microsoft is aware; @Scottj1s noted additional gaps (notably resource handling) also need to be closed for full parity. @michael-hawker in [#5586](https://github.com/microsoft/WindowsAppSDK/issues/5586) highlighted that removing the WAP template from Visual Studio would reduce confusion for new developers. - -**Workaround:** -1. Continue using a Windows Application Packaging Project (wapproj) for multi-executable MSIX packages -2. Reference: [Single-project MSIX limitations](https://github.com/MicrosoftDocs/windows-dev-docs/blob/docs/hub/apps/windows-app-sdk/single-project-msix.md#limitations) - -**Verify:** N/A — this is a feature request with no current workaround in single-project mode. - ---- - -## ⚠️ Unverified / Community Suggestions - -> The following are community suggestions that have NOT been officially confirmed. - -- For build environments without Visual Studio, consider using `Microsoft.Windows.SDK.BuildTools` NuGet alongside the MSIX package to reduce VS dependencies (from @wjk in #6197 — noted that `mspdbcmf.exe` is not included in that package either) -- For wapproj to single-project migration, consider tracking [#5586](https://github.com/microsoft/WindowsAppSDK/issues/5586) and [#6261](https://github.com/microsoft/WindowsAppSDK/issues/6261) for official guidance -- @riverar in [#3718](https://github.com/microsoft/WindowsAppSDK/issues/3718) suggested this as a candidate for inclusion in the updated MSIX tooling - ---- - -## References - -- [Single-project MSIX Packaging documentation](https://learn.microsoft.com/en-us/windows/apps/windows-app-sdk/single-project-msix) -- [Single-project MSIX limitations](https://github.com/MicrosoftDocs/windows-dev-docs/blob/docs/hub/apps/windows-app-sdk/single-project-msix.md#limitations) -- [Windows AI APIs — TargetDeviceFamily guidance](https://learn.microsoft.com/en-us/windows/ai/apis/get-started?tabs=winget%2Cwinui%2Cwinui2#build-a-new-app) -- [Microsoft.Windows.SDK.BuildTools.MSIX on NuGet](https://www.nuget.org/packages/Microsoft.Windows.SDK.BuildTools.MSIX) - ---- - -**Updated:** 2025-07-18 | **Confidence:** 0.7 -**Sources:** [#6197](https://github.com/microsoft/WindowsAppSDK/issues/6197), [#3718](https://github.com/microsoft/WindowsAppSDK/issues/3718), [#5598](https://github.com/microsoft/WindowsAppSDK/issues/5598), [#5586](https://github.com/microsoft/WindowsAppSDK/issues/5586) diff --git a/tsg/tsg_runtime_winrt_interop.md b/tsg/tsg_runtime_winrt_interop.md deleted file mode 100644 index 7d65cbf..0000000 --- a/tsg/tsg_runtime_winrt_interop.md +++ /dev/null @@ -1,199 +0,0 @@ -# WinRT Interop, AOT Compatibility & Runtime Version Issues - Windows App SDK - -**Keywords:** AOT, trimming, FrameworkElement, theme, LaunchActivatedEventArgs, WinRT, CsWinRT, IInspectable, ReleaseInfo, version string, HDR, CompositionDrawingSurface, scRGB, swap chain, DirectXPixelFormat - -**Error Example:** -``` -// AOT theme switching failure -(Window.Content as FrameworkElement) returns null when published with AOT - -// LaunchActivatedEventArgs interop -AppActivationArguments.Data shows as WinRT.IInspectable instead of LaunchActivatedEventArgs - -// ReleaseInfo version mismatch -ReleaseInfo.AsString returns "1.7.0" on WinAppSDK 1.7.1 runtime - -// HDR composition -CompositionDrawingSurface with R16G16B16A16Float renders as SDR in WinAppSDK -``` - ---- - -## Quick Match - -**You're seeing this if:** -- Theme switching code fails silently when app is published with Native AOT -- `Window.Content as FrameworkElement` returns `null` in AOT builds -- `AppActivationArguments.Data` is `WinRT.IInspectable` instead of a typed activation args object -- `ReleaseInfo.AsString` returns wrong version (e.g., "1.7.0" on 1.7.1) -- HDR content renders as SDR when using `CompositionDrawingSurface` with float16 pixel format - -→ Check scenarios below for your specific cause - ---- - -## Related Issues - -- [#5389](https://github.com/microsoft/WindowsAppSDK/issues/5389) - Unable to change theme color when AOT is released (Status: Closed, area-AOT) -- [#6219](https://github.com/microsoft/WindowsAppSDK/issues/6219) - WASDK LaunchActivatedEventArgs cannot be directly converted into WinRT (Status: Open, area-Projections) -- [#5323](https://github.com/microsoft/WindowsAppSDK/issues/5323) - ReleaseInfo returns "1.7.0" in 1.7.1 release (Status: Closed, area-VersionInfo) -- [#6291](https://github.com/microsoft/WindowsAppSDK/issues/6291) - Unlike UWP, WindowsAppSdk does not support HDR composition (Status: Closed) - ---- - -## Scenarios & Solutions - -### Scenario 1: Theme Switching Fails Under Native AOT (Trimming) - -**Cause:** When publishing a WinUI app with Native AOT, the .NET trimmer removes `FrameworkElement` because the C# code doesn't directly construct it. As a result, `Window.Content as FrameworkElement` returns `null`, and theme switching code silently fails. The `as` operator cannot succeed because the type metadata has been trimmed. -> Source: @manodasanW (MEMBER) in [#5389](https://github.com/microsoft/WindowsAppSDK/issues/5389) - -**Fix:** -1. Upgrade to [CsWinRT 2.3 previews](https://www.nuget.org/packages/Microsoft.Windows.CsWinRT/2.3.0-prerelease.251115.2) or later -2. Add the `[DynamicWindowsRuntimeCast]` attribute to the method performing the cast, passing `typeof(FrameworkElement)`: -```csharp -[DynamicWindowsRuntimeCast(typeof(FrameworkElement))] -private void SetTheme(ApplicationTheme theme) -{ - if (Window.Content is FrameworkElement rootElement) - { - rootElement.RequestedTheme = theme == ApplicationTheme.Dark - ? ElementTheme.Dark - : ElementTheme.Light; - } -} -``` -3. Enable AOT diagnostics to catch similar issues by setting `CsWinRTAotWarningLevel` to `3` in your project file: -```xml - - 3 - -``` -4. The diagnostics include a code fix that should help identify all such scenarios where types may be trimmed - -> ✅ Confirmed by: @manodasanW (Microsoft, MEMBER) in #5389 comments - -**Verify:** Publish with AOT and confirm `Window.Content as FrameworkElement` returns a non-null value. - -**Environment:** -- WinAppSDK 1.7.1 (1.7.250401001) -- Packaged (MSIX) and Unpackaged -- Windows 11 24H2 -- Visual Studio 2022-preview - ---- - -### Scenario 2: WASDK LaunchActivatedEventArgs Not Convertible to WinRT Type - -**Cause:** When `AppInstance.GetActivatedEventArgs()` is called in WASDK, it first tries `WinRT's AppInstance.GetActivatedEventArgs()`. If that returns null, WASDK falls back to its own custom implementation of `LaunchActivatedEventArgs`. The returned object is WASDK's custom type, not the WinRT `LaunchActivatedEventArgs`. On the .NET side, CsWinRT cannot recognize WASDK's custom implementation, so `AppActivationArguments.Data` appears as `WinRT.IInspectable` instead of the expected typed object. -> Source: Issue author in [#6219](https://github.com/microsoft/WindowsAppSDK/issues/6219) - -**Workaround:** -1. Use `LaunchActivatedEventArgs.FromAbi()` to manually unwrap the inspectable pointer: -```csharp -var activatedArgs = AppInstance.GetCurrent().GetActivatedEventArgs(); -if (activatedArgs.Kind == ExtendedActivationKind.Launch) -{ - // Data is WinRT.IInspectable, need manual conversion - var inspectable = activatedArgs.Data as IInspectable; - if (inspectable != null) - { - var launchArgs = LaunchActivatedEventArgs.FromAbi(inspectable.ThisPtr); - string arguments = launchArgs.Arguments; - } -} -``` -2. This is a known interop gap — WASDK team has been asked to add a wrapping layer so the returned object is recognized as `WinRT.LaunchActivatedEventArgs` by CsWinRT - -**Status:** Open — no official fix yet. The request is for WASDK to wrap its custom implementation so .NET CsWinRT can recognize it correctly. - -**Environment:** -- WinAppSDK 1.8.5 (1.8.260209005) -- Packaged (MSIX) -- Windows 11 24H2 LTSC (26100) - ---- - -### Scenario 3: ReleaseInfo.AsString Returns Wrong Patch Version - -**Cause:** `Microsoft.Windows.ApplicationModel.WindowsAppRuntime.ReleaseInfo.AsString` returns "1.7.0" even when running on the 1.7.1 runtime. The `Patch` property on `ReleaseInfo` also incorrectly returns `0`. Meanwhile, `RuntimeInfo.Version` correctly reports the full version (e.g., `7000.456.1632.0`). -> Source: Issue author in [#5323](https://github.com/microsoft/WindowsAppSDK/issues/5323) - -**Workaround:** -1. Use `RuntimeInfo.Version` instead of `ReleaseInfo.AsString` for accurate version detection: -```csharp -// Unreliable in 1.7.x: -var releaseStr = ReleaseInfo.AsString; // Returns "1.7.0" even on 1.7.1 - -// Reliable alternative: -var runtimeVersion = RuntimeInfo.Version; // Returns correct version like 7000.456.1632.0 -``` -2. This was a known bug in the 1.7.x release train. Check whether the issue is resolved in your target SDK version - -> ✅ Fix confirmed: Issue is closed, indicating the bug has been addressed in subsequent releases - -**Verify:** -```csharp -Debug.WriteLine($"ReleaseInfo: {ReleaseInfo.AsString}"); -Debug.WriteLine($"RuntimeInfo: {RuntimeInfo.Version}"); -``` - -**Environment:** -- WinAppSDK 1.7.1 (1.7.250401001) -- Packaged (MSIX) -- Windows 11 24H2 - ---- - -### Scenario 4: HDR Composition Not Supported in WinAppSDK (UWP Parity Gap) - -**Cause:** In UWP, creating a `CompositionDrawingSurface` with pixel format `DirectXPixelFormat.R16G16B16A16Float` enables HDR composition — the floating-point content is passed to the system compositor, which can display values outside [0,1]. In WinAppSDK, the same code does not produce HDR output. The surface appears to undergo a simple scRGB-to-sRGB gamma correction and renders as SDR. This suggests WinAppSDK may be composing to an 8-bit swap chain rather than a 16-bit floating-point swap chain. -> Source: Issue author in [#6291](https://github.com/microsoft/WindowsAppSDK/issues/6291) - -**Symptoms:** -- `CompositionDrawingSurface` created with `R16G16B16A16Float` renders identically to SDR -- Values > 1.0 in HDR content do not appear brighter than SDR maximum -- SDR content is not dimmer (no SDR white level scaling at display's SDR white level / 80 nits) -- Photo viewing or media apps cannot display HDR content correctly in WinAppSDK - -**Reproduction code summary:** -```csharp -// This produces HDR in UWP but SDR in WinAppSDK -var surface = compositionDevice.CreateDrawingSurface( - pixelSize, - DirectXPixelFormat.R16G16B16A16Float, - DirectXAlphaMode.Premultiplied); - -// Drawing HDR values > 1.0 should be brighter than SDR max -ds.FillRectangle(rect, CanvasSolidColorBrush.CreateHdr(device, new Vector4(5, 5, 5, 1))); -``` - -**Status:** Closed — but no confirmed workaround for achieving HDR composition in WinAppSDK was provided. This represents a UWP-to-WinAppSDK migration blocker for HDR content applications. - -**Workaround (limited):** -1. For HDR content display, consider maintaining a UWP component or using DirectX interop with a custom swap chain -2. Monitor WinAppSDK releases for HDR composition support -3. No pure WinUI/Composition API workaround is currently available - ---- - -## ⚠️ Unverified / Community Suggestions - -> The following are community suggestions that have NOT been officially confirmed. - -- For HDR (#6291): Using a custom DirectComposition swap chain with `DXGI_FORMAT_R16G16B16A16_FLOAT` created outside of WinUI's compositor may enable HDR rendering, but this bypasses the WinUI composition tree (not confirmed) -- For AOT (#5389): Some developers report that adding `[DynamicallyAccessedMembers]` attributes on certain types can also prevent trimming, though the `DynamicWindowsRuntimeCast` approach from @manodasanW is the recommended solution - ---- - -## References - -- [CsWinRT 2.3 Preview - NuGet](https://www.nuget.org/packages/Microsoft.Windows.CsWinRT/2.3.0-prerelease.251115.2) -- [DynamicWindowsRuntimeCast example - CsWinRT repo](https://github.com/microsoft/CsWinRT/blob/4475bb0d5a795bea964b4ce3db5db860233e7ba2/src/Tests/FunctionalTests/JsonValueFunctionCalls/Program.cs#L26) -- [WinAppSDK ReleaseInfo API](https://learn.microsoft.com/en-us/windows/windows-app-sdk/api/winrt/microsoft.windows.applicationmodel.windowsappruntime.releaseinfo) -- [HDR and Advanced Color in Windows](https://learn.microsoft.com/en-us/windows/win32/direct3darticles/high-dynamic-range) - ---- - -**Updated:** 2025-07-17 | **Confidence:** 0.7 -**Sources:** #5389, #6219, #5323, #6291, CsWinRT documentation From 327005843fbeb12652871743369864480a94552a Mon Sep 17 00:00:00 2001 From: Qiutong Shen Date: Fri, 20 Mar 2026 10:17:42 +0800 Subject: [PATCH 3/7] remove index --- index/index.json | 1589 ---------------------------------------------- 1 file changed, 1589 deletions(-) delete mode 100644 index/index.json diff --git a/index/index.json b/index/index.json deleted file mode 100644 index 036cec2..0000000 --- a/index/index.json +++ /dev/null @@ -1,1589 +0,0 @@ -{ - "version": "2026-03-16", - "generatedAt": "2026-03-16T03:34:46.570835+00:00", - "totalEntries": 22, - "entries": [ - { - "id": "known_issue_api_docs_storagefile", - "path": "E:\\issue-tsg-generator\\output\\known_issue_api_docs_storagefile.md", - "title": "Known Issue: Missing AppWindow Placement API Documentation & StorageFile Shortcut File Support", - "area": "Storage", - "symptoms": [], - "errorCodes": [], - "keywords": [ - "AppWindow", - "GetCurrentPlacement", - "SaveCurrentPlacement", - "PlacementRestorationBehavior", - "PlacementInfo", - "DisplayArea", - "GetMetricsFromWindowId", - "PersistedStateId", - "experimental API", - "StorageFile", - "shortcut", - ".lnk", - ".url", - ".wsh", - "file handler" - ], - "severity": "critical", - "relatedIssues": [ - "microsoft/WindowsAppSDK#5896", - "microsoft/WindowsAppSDK#518", - "microsoft/WindowsAppSDK#5896", - "microsoft/WindowsAppSDK#518" - ] - }, - { - "id": "known_issue_api_gaps_localization", - "path": "E:\\issue-tsg-generator\\output\\known_issue_api_gaps_localization.md", - "title": "Known Issue: PrimaryLanguageOverride Not Persisted & Missing PackageManager API", - "area": "Runtime", - "symptoms": [], - "errorCodes": [], - "keywords": [ - "PrimaryLanguageOverride", - "null", - "empty", - "not persisted", - "localization", - "Microsoft.Windows.Globalization", - "MovePackageToVolumeAsync", - "PackageDeploymentManager", - "WASDK 2.0" - ], - "severity": "critical", - "relatedIssues": [ - "microsoft/WindowsAppSDK#6118", - "microsoft/WindowsAppSDK#1687", - "microsoft/WindowsAppSDK#6118", - "microsoft/WindowsAppSDK#6118", - "microsoft/WindowsAppSDK#6118", - "microsoft/WindowsAppSDK#6118", - "microsoft/WindowsAppSDK#6221", - "microsoft/WindowsAppSDK#6221" - ] - }, - { - "id": "known_issue_msix_buildtools_defects", - "path": "E:\\issue-tsg-generator\\output\\known_issue_msix_buildtools_defects.md", - "title": "Known Issue: MSIX Build Tools Defects and Documentation Gaps", - "area": "Deployment", - "symptoms": [], - "errorCodes": [], - "keywords": [ - "Microsoft.Windows.SDK.BuildTools.MSIX", - "AppxSymbolPackageEnabled", - "_GenerateAppxSymbolPackage", - "mspdbcmf.exe", - "msixbundle", - "Dependencies folder", - "Publish error", - "wapproj", - "documentation", - "roadmap" - ], - "severity": "critical", - "relatedIssues": [ - "microsoft/WindowsAppSDK#6183", - "microsoft/WindowsAppSDK#6147", - "microsoft/WindowsAppSDK#6261", - "microsoft/WindowsAppSDK#3065", - "microsoft/WindowsAppSDK#6183", - "microsoft/WindowsAppSDK#6147", - "microsoft/WindowsAppSDK#1808", - "microsoft/WindowsAppSDK#6261", - "microsoft/WindowsAppSDK#3065" - ] - }, - { - "id": "known_issue_msix_nuget_license", - "path": "E:\\issue-tsg-generator\\output\\known_issue_msix_nuget_license.md", - "title": "Known Issue: NuGet Package License Forbids Redistribution of Bootstrap DLL", - "area": "Deployment", - "symptoms": [], - "errorCodes": [], - "keywords": [ - "Microsoft.WindowsAppSDK.Foundation", - "bootstrap DLL", - "NuGet license", - "redistribution", - "Microsoft.WindowsAppSDK", - "license terms" - ], - "severity": "critical", - "relatedIssues": [ - "microsoft/WindowsAppSDK#6288", - "microsoft/WindowsAppSDK#3498", - "microsoft/WindowsAppSDK#6288", - "microsoft/WindowsAppSDK#3498" - ] - }, - { - "id": "known_issue_performance_crashes", - "path": "E:\\issue-tsg-generator\\output\\known_issue_performance_crashes.md", - "title": "Known Issue: WinRT API Performance Overhead & Packaged App Crashes in Admin Mode on Windows 10", - "area": "Runtime", - "symptoms": [], - "errorCodes": [ - "0xc000027b" - ], - "keywords": [ - "WinRT", - "ApplicationData", - "Package.Current", - "performance", - "latency", - "25ms", - "admin mode", - "elevated", - "packaged app crash", - "Windows 10", - "0xc000027b" - ], - "severity": "critical", - "relatedIssues": [ - "microsoft/WindowsAppSDK#6223", - "microsoft/WindowsAppSDK#6223", - "microsoft/WindowsAppSDK#6223", - "microsoft/WindowsAppSDK#6268", - "microsoft/WindowsAppSDK#2555", - "microsoft/WindowsAppSDK#6268", - "microsoft/WindowsAppSDK#6268" - ] - }, - { - "id": "known_issue_widget_platform_defects", - "path": "E:\\issue-tsg-generator\\output\\known_issue_widget_platform_defects.md", - "title": "Known Issue: Widget Settings Panel Reloads Instead of Closing & Widget Not Appearing After Install", - "area": "Widgets", - "symptoms": [], - "errorCodes": [], - "keywords": [ - "widget settings", - "close button", - "reload", - "widget board", - "widget not appearing", - "reinstall", - "customize widget", - "Windows Widgets", - "WidgetProviders" - ], - "severity": "critical", - "relatedIssues": [ - "microsoft/WindowsAppSDK#6141", - "microsoft/WindowsAppSDK#3958", - "microsoft/WindowsAppSDK#6141", - "microsoft/WindowsAppSDK#3958" - ] - }, - { - "id": "known_issues_external_notifications", - "path": "E:\\issue-tsg-generator\\output\\known_issues_external_notifications.md", - "title": "Known Issues: MSIX Data Retention, Toast Rendering, and AppNotification Registration", - "area": "Runtime", - "symptoms": [], - "errorCodes": [ - "COMException" - ], - "keywords": [ - "MSIX", - "uninstall", - "data retention", - "app data", - "keep data", - "game data", - "reinstall" - ], - "severity": "critical", - "relatedIssues": [ - "microsoft/WindowsAppSDK#6260", - "microsoft/WindowsAppSDK#13", - "microsoft/WindowsAppSDK#4026", - "microsoft/WindowsAppSDK#6071" - ] - }, - { - "id": "known_issues_file_access_pickers", - "path": "E:\\issue-tsg-generator\\output\\known_issues_file_access_pickers.md", - "title": "Known Issue: Storage Picker Missing Features and Unexpected Behavior", - "area": "Storage", - "symptoms": [], - "errorCodes": [], - "keywords": [ - "SettingsIdentifier", - "FileOpenPicker", - "FileSavePicker", - "FolderPicker", - "last used location", - "Microsoft.Windows.Storage.Pickers" - ], - "severity": "critical", - "relatedIssues": [ - "microsoft/WindowsAppSDK#5847", - "microsoft/WindowsAppSDK#5976" - ] - }, - { - "id": "api_gaps_unpackaged_support", - "path": "E:\\issue-tsg-generator\\output\\tsg_api_gaps_unpackaged_support.md", - "title": "API Gaps: Unpackaged App Support, Storage & Package Management - Windows App SDK", - "area": "WinML", - "symptoms": [ - "`ApplicationData.Current` fails in an unpackaged (non-MSIX) app", - "Need app metadata (display name, icon, etc.) in an unpackaged app", - "WASDK `PackageVolume` is missing `FindPackage`-related APIs available in the platform type", - "Want to register as a default file handler by MIME content type instead of individual file extensions" - ], - "errorCodes": [], - "keywords": [ - "ApplicationData", - "unpackaged", - "AppInfo", - "package identity", - "StorageFolder", - "PackageVolume", - "FindPackage", - "content type", - "file handler", - "file association", - "manifest", - "LOCALAPPDATA" - ], - "severity": "critical", - "relatedIssues": [ - "microsoft/WindowsAppSDK#2639", - "microsoft/WindowsAppSDK#1083", - "microsoft/WindowsAppSDK#27", - "microsoft/WindowsAppSDK#6222", - "microsoft/WindowsAppSDK#2639", - "microsoft/WindowsAppSDK#2639", - "microsoft/WindowsAppSDK#1083", - "microsoft/WindowsAppSDK#27", - "microsoft/WindowsAppSDK#6222" - ] - }, - { - "id": "appcontainer_identity_sharing", - "path": "E:\\issue-tsg-generator\\output\\tsg_appcontainer_identity_sharing.md", - "title": "AppContainer for Win32 Apps & Named Object Sharing Between Packaged/Win32", - "area": "Runtime", - "symptoms": [ - "You want to run a Win32/WinUI 3 MSIX app in an AppContainer sandbox", - "`Shell_NotifyIcon` returns access denied in AppContainer", - "You need to share named objects (mutexes, events) between packaged and Win32 apps", - "You're trying to configure `PartialTrustApplication` in a `.wapproj` packaging project" - ], - "errorCodes": [], - "keywords": [ - "AppContainer", - "Win32", - "PartialTrustApplication", - "partial trust", - "sandboxing", - "named objects", - "security descriptor", - "PackageFamilyName", - "PFN", - "Shell_NotifyIcon", - "tray icon", - "MSIX", - "runFullTrust", - "permissiveLearningMode" - ], - "severity": "critical", - "relatedIssues": [ - "microsoft/WindowsAppSDK#219", - "microsoft/WindowsAppSDK#175", - "microsoft/WindowsAppSDK#219", - "microsoft/WindowsAppSDK#219", - "microsoft/WindowsAppSDK#219", - "microsoft/WindowsAppSDK#219", - "microsoft/WindowsAppSDK#219", - "microsoft/WindowsAppSDK#219", - "microsoft/WindowsAppSDK#219", - "microsoft/WindowsAppSDK#219", - "microsoft/WindowsAppSDK#219", - "microsoft/WindowsAppSDK#175", - "microsoft/WindowsAppSDK#175", - "microsoft/WindowsAppSDK#175" - ] - }, - { - "id": "background_tasks_printing_tooling", - "path": "E:\\issue-tsg-generator\\output\\tsg_background_tasks_printing_tooling.md", - "title": "Background Task Crashes, Print Preview Dark Theme & VS Tooling - Windows App SDK", - "area": "Runtime", - "symptoms": [ - "Background task crashes with `STOWED_EXCEPTION` in `UniversalBGTask.dll`", - "Partner Center shows thousands of daily crashes from background task execution", - "Print preview window displays empty/blank content with dark theme", - "Cannot add new WinUI Page items in Visual Studio 2022" - ], - "errorCodes": [ - "0x80004002", - "0x80004005", - "0x800706ba", - "0x80080204", - "0xC00CE169", - "E_FAIL", - "E_NOINTERFACE" - ], - "keywords": [ - "UniversalBGTask", - "STOWED_EXCEPTION", - "background task", - "crash", - "0x80004005", - "0x80004002", - "0x800706ba", - "0x80080204", - "0xC00CE169", - "ACCESS_VIOLATION", - "PrintPreview", - "dark theme", - "RequestedTheme", - "empty preview", - "Visual Studio 2022", - "add page", - "new item" - ], - "severity": "critical", - "relatedIssues": [ - "microsoft/WindowsAppSDK#5870", - "microsoft/WindowsAppSDK#6086", - "microsoft/WindowsAppSDK#1236", - "microsoft/WindowsAppSDK#5870", - "microsoft/WindowsAppSDK#5870", - "microsoft/WindowsAppSDK#6086", - "microsoft/WindowsAppSDK#1236" - ] - }, - { - "id": "deployment_singlefile_installer", - "path": "E:\\issue-tsg-generator\\output\\tsg_deployment_singlefile_installer.md", - "title": "Error: \"XamlParseException: XAML parsing failed\" — Renamed Single-File Unpackaged App / Broken Runtime Links", - "area": "Deployment", - "symptoms": [ - "You published a WinUI 3 app as single-file unpackaged and renamed the `.exe`", - "Error contains \"XamlParseException\" or \"XAML parsing failed\" after renaming", - "WASDK 2.0 Preview runtime download links return 404", - "WASDK 1.6.3 installers ship binaries that still crash despite documented fixes" - ], - "errorCodes": [], - "keywords": [ - "XamlParseException", - "XAML parsing failed", - "single-file", - "unpackaged", - "rename executable", - "PublishSingleFile", - "runtime links broken", - "2.0 preview", - "installer binaries", - "MRM.dll crash" - ], - "severity": "critical", - "relatedIssues": [ - "microsoft/WindowsAppSDK#6248", - "microsoft/WindowsAppSDK#6220", - "microsoft/WindowsAppSDK#4977", - "microsoft/WindowsAppSDK#6248", - "microsoft/WindowsAppSDK#6248", - "microsoft/WindowsAppSDK#6220", - "microsoft/WindowsAppSDK#6220", - "microsoft/WindowsAppSDK#4977", - "microsoft/WindowsAppSDK#4977", - "microsoft/WindowsAppSDK#4977" - ] - }, - { - "id": "deployment_wasdk18_windows10", - "path": "E:\\issue-tsg-generator\\output\\tsg_deployment_wasdk18_windows10.md", - "title": "Error: App Crash on Launch / \"FindPackagesByPackageFamily\" Failure — WASDK 1.8 on Windows 10", - "area": "Deployment", - "symptoms": [ - "WinUI 3 / WASDK 1.8+ packaged app crashes immediately on launch on Windows 10 (builds 17763, 19041, 19045)", - "`FindPackagesByPackageFamily()` fails to locate WASDK 1.8 runtime packages on Windows 10", - "No error dialog — the app silently exits", - "Same app works fine on Windows 11" - ], - "errorCodes": [ - "0x80070005", - "0xc000027b" - ], - "keywords": [ - "FindPackagesByPackageFamily", - "WASDK 1.8", - "Windows 10", - "17763", - "19041", - "DeploymentManager", - "crash on launch", - "0x80070005", - "DDLM PackageFullName", - "MSIX.inventory" - ], - "severity": "critical", - "relatedIssues": [ - "microsoft/WindowsAppSDK#6117", - "microsoft/WindowsAppSDK#6254", - "microsoft/WindowsAppSDK#6156", - "microsoft/WindowsAppSDK#6117", - "microsoft/WindowsAppSDK#6254", - "microsoft/WindowsAppSDK#6117", - "microsoft/WindowsAppSDK#6254", - "microsoft/WindowsAppSDK#6117", - "microsoft/WindowsAppSDK#6117", - "microsoft/WindowsAppSDK#6156", - "microsoft/WindowsAppSDK#6156", - "microsoft/WindowsAppSDK#6117", - "microsoft/WindowsAppSDK#6254" - ] - }, - { - "id": "external_interop_issues", - "path": "E:\\issue-tsg-generator\\output\\tsg_external_interop_issues.md", - "title": "External / Interop Issues — Packaging, Device APIs, and Widgets", - "area": "Runtime", - "symptoms": [ - "MSIX bundle contains wrong (stale) NuGet DLL versions after package downgrade", - "Error `0x8007007A` on app startup from `FindPackagesByPackageFamily`", - "Bluetooth device pairing UI fails to show in WinUI 3 desktop app", - "NFC `ProximityDevice` events never fire after UWP → WinUI 3 migration", - "Widgets panel: first widget (alphabetically) cannot be added" - ], - "errorCodes": [ - "0x8007007A", - "E_FILTER_HEAD" - ], - "keywords": [ - "packaging project", - "NuGet", - "stale assembly", - "MSIX bundle", - "FindPackagesByPackageFamily", - "0x8007007A", - "ERROR_INSUFFICIENT_BUFFER", - "DeviceInformationPairing", - "Bluetooth", - "ProximityDevice", - "NFC", - "Widgets", - "WinUI 3" - ], - "severity": "critical", - "relatedIssues": [ - "microsoft/WindowsAppSDK#6253", - "microsoft/WindowsAppSDK#6274", - "microsoft/WindowsAppSDK#3091", - "microsoft/WindowsAppSDK#4356", - "microsoft/WindowsAppSDK#6140", - "microsoft/WindowsAppSDK#6253", - "microsoft/WindowsAppSDK#6274", - "microsoft/WindowsAppSDK#3091", - "microsoft/WindowsAppSDK#4356", - "microsoft/WindowsAppSDK#6140" - ] - }, - { - "id": "file_access_storage_pickers", - "path": "E:\\issue-tsg-generator\\output\\tsg_file_access_storage_pickers.md", - "title": "Storage Picker Issues — File Access & Picker Dialogs", - "area": "Storage", - "symptoms": [ - "Error contains \"E_FAIL\" or \"COMException\" when calling `PickSingleFileAsync()` or `PickSaveFileAsync()`", - "File/Folder picker dialog behaves unexpectedly (wrong extension, missing folders, wrong language)", - "Using `FileOpenPicker`, `FileSavePicker`, or `FolderPicker` from a WinUI 3 / Windows App SDK desktop app", - "Platform: Windows App SDK (packaged or unpackaged), WinUI 3" - ], - "errorCodes": [ - "0x80004005", - "COMException", - "E_FAIL" - ], - "keywords": [ - "FileOpenPicker", - "FileSavePicker", - "FolderPicker", - "storage pickers", - "file picker crash", - "COMException", - "E_FAIL", - "IInitializeWithWindow", - "DefaultFileExtension", - "FileTypeChoices", - "WSL", - "RTL", - "language override" - ], - "severity": "critical", - "relatedIssues": [ - "microsoft/WindowsAppSDK#1063", - "microsoft/WindowsAppSDK#2504", - "microsoft/WindowsAppSDK#5975", - "microsoft/WindowsAppSDK#6284", - "microsoft/WindowsAppSDK#6105", - "microsoft/WindowsAppSDK#2504", - "microsoft/WindowsAppSDK#1063", - "microsoft/WindowsAppSDK#5975", - "microsoft/WindowsAppSDK#6284", - "microsoft/WindowsAppSDK#6105" - ] - }, - { - "id": "msix_build_publish_output_failures", - "path": "E:\\issue-tsg-generator\\output\\tsg_msix_build_publish_output_failures.md", - "title": "Error: MSIX Build/Publish Output Failures (msixupload, msixbundle, appxsym)", - "area": "Deployment", - "symptoms": [ - "Building an MSIX bundle or upload package fails with MSB4036 or MSB6006", - "`msbuild` with `UapAppxPackageBuildMode=StoreUpload` does not produce `.msixupload`", - "Publishing an MSIX from Visual Studio pollutes `.csproj.user` with `UapAppxPackageBuildMode`", - "`mspdbcmf.exe` exits with fatal error CMF1106 during symbol package generation" - ], - "errorCodes": [], - "keywords": [ - "msixupload", - "msixbundle", - "appxsym", - "WinAppSdkSignAppxPackageBundle", - "MSB4036", - "MSB6006", - "mspdbcmf.exe", - "CMF1106", - "UapAppxPackageBuildMode", - "StoreUpload", - "StoreAndSideload" - ], - "severity": "critical", - "relatedIssues": [ - "microsoft/WindowsAppSDK#5820", - "microsoft/WindowsAppSDK#5825", - "microsoft/WindowsAppSDK#5501", - "microsoft/WindowsAppSDK#5537", - "microsoft/WindowsAppSDK#5820", - "microsoft/WindowsAppSDK#5820", - "microsoft/WindowsAppSDK#5825", - "microsoft/WindowsAppSDK#5825", - "microsoft/WindowsAppSDK#6183", - "microsoft/WindowsAppSDK#5501", - "microsoft/WindowsAppSDK#5501", - "microsoft/WindowsAppSDK#5537", - "microsoft/WindowsAppSDK#5537", - "microsoft/WindowsAppSDK#5820", - "microsoft/WindowsAppSDK#5825", - "microsoft/WindowsAppSDK#5501", - "microsoft/WindowsAppSDK#5537" - ] - }, - { - "id": "msix_project_configuration_tooling", - "path": "E:\\issue-tsg-generator\\output\\tsg_msix_project_configuration_tooling.md", - "title": "Error: MSIX Project Configuration & Build Tools Issues", - "area": "Deployment", - "symptoms": [ - "Building MSIX packages without Visual Studio installed fails due to missing `mspdbcmf.exe`", - "Removing `EnableMsixTooling` from unpackaged app projects causes publish failures or missing `.pri` files", - "`AppxOSMinVersionReplaceManifestVersion=false` is ignored by single-project MSIX", - "Need to include multiple executables in a single MSIX package" - ], - "errorCodes": [], - "keywords": [ - "EnableMsixTooling", - "Microsoft.Windows.SDK.BuildTools.MSIX", - "AppxOSMinVersionReplaceManifestVersion", - "AppxOSMaxVersionTestedReplaceManifestVersion", - "mspdbcmf.exe", - "wapproj", - "single-project MSIX", - "NuGet", - "Visual Studio", - "unpackaged", - "resources.pri" - ], - "severity": "critical", - "relatedIssues": [ - "microsoft/WindowsAppSDK#6197", - "microsoft/WindowsAppSDK#3718", - "microsoft/WindowsAppSDK#5598", - "microsoft/WindowsAppSDK#5586", - "microsoft/WindowsAppSDK#6197", - "microsoft/WindowsAppSDK#3718", - "microsoft/WindowsAppSDK#3718", - "microsoft/WindowsAppSDK#5746", - "microsoft/WindowsAppSDK#3718", - "microsoft/WindowsAppSDK#5598", - "microsoft/WindowsAppSDK#5586", - "microsoft/WindowsAppSDK#5586", - "microsoft/WindowsAppSDK#5586", - "microsoft/WindowsAppSDK#6261", - "microsoft/WindowsAppSDK#3718", - "microsoft/WindowsAppSDK#6197", - "microsoft/WindowsAppSDK#3718", - "microsoft/WindowsAppSDK#5598", - "microsoft/WindowsAppSDK#5586" - ] - }, - { - "id": "msix_selfcontained_packaging_conflicts", - "path": "E:\\issue-tsg-generator\\output\\tsg_msix_selfcontained_packaging_conflicts.md", - "title": "Error: Self-Contained Deployment and MSIX Packaging Conflicts", - "area": "Deployment", - "symptoms": [ - "Setting `WindowsAppSDKSelfContained=true` on a library project causes XAML parsing or codegen failures", - "Upgrading to WinAppSDK 1.8 causes COMException 0x80070490 (Element not found) related to `.pri` file naming changes", - "Build errors include `NETSDK1022` (duplicate items) or `WMC1012` (multiple ApplicationXaml) after upgrading" - ], - "errorCodes": [ - "0x80070490", - "COMException" - ], - "keywords": [ - "WindowsAppSDKSelfContained", - "XamlParseException", - "COMException", - "0x80070490", - "resources.pri", - "PRI", - "_OverrideGetPriIndexName", - "EnableMsixTooling", - "WMC1012", - "ApplicationXaml", - "codegen", - "library project" - ], - "severity": "critical", - "relatedIssues": [ - "microsoft/WindowsAppSDK#6091", - "microsoft/WindowsAppSDK#5746", - "microsoft/WindowsAppSDK#6091", - "microsoft/WindowsAppSDK#6091", - "microsoft/WindowsAppSDK#6091", - "microsoft/WindowsAppSDK#6091", - "microsoft/WindowsAppSDK#5746", - "microsoft/WindowsAppSDK#5746", - "microsoft/WindowsAppSDK#5746", - "microsoft/WindowsAppSDK#6091", - "microsoft/WindowsAppSDK#5746" - ] - }, - { - "id": "notifications_push_and_listener", - "path": "E:\\issue-tsg-generator\\output\\tsg_notifications_push_and_listener.md", - "title": "Notification Issues — Push Notifications, Progress Data, and UserNotificationListener", - "area": "Runtime", - "symptoms": [ - "Error contains `0x80070490` (\"Element not found\") when subscribing to notification events", - "Push notifications fail in unpackaged or non-Store apps", - "Cannot create an indeterminate progress bar in toast notifications via `AppNotificationProgressData`", - "`UserNotificationListener.NotificationChanged` throws `COMException` in unpackaged apps", - "Platform: Windows App SDK, WinUI 3, unpackaged or self-contained apps" - ], - "errorCodes": [ - "0x80070490", - "COMException" - ], - "keywords": [ - "AppNotification", - "push notification", - "unpackaged", - "COMException", - "0x80070490", - "Element not found", - "UserNotificationListener", - "NotificationChanged", - "AppNotificationProgressData", - "IsIndeterminate", - "indeterminate progress bar", - "toast notification" - ], - "severity": "critical", - "relatedIssues": [ - "microsoft/WindowsAppSDK#334", - "microsoft/WindowsAppSDK#2231", - "microsoft/WindowsAppSDK#6172", - "microsoft/WindowsAppSDK#334", - "microsoft/WindowsAppSDK#2231", - "microsoft/WindowsAppSDK#6172" - ] - }, - { - "id": "resources_mrt_localization", - "path": "E:\\issue-tsg-generator\\output\\tsg_resources_mrt_localization.md", - "title": "Error: \"COMException: NamedResource Not Found\" / PrimaryLanguageOverride Not Working — MRT Resource Loading", - "area": "Runtime", - "symptoms": [ - "`ResourceLoader.GetString()` throws `COMException` for keys containing `.` (dots)", - "`PrimaryLanguageOverride` does not work in unpackaged WinUI 3 apps", - "`x:Uid` XAML localization fails for unpackaged apps", - "Signing `Microsoft.Windows.ApplicationModel.Resources.Projection` fails during build" - ], - "errorCodes": [ - "COMException" - ], - "keywords": [ - "ResourceLoader", - "GetString", - "COMException", - "NamedResource Not Found", - "PrimaryLanguageOverride", - "unpackaged", - "localization", - "x:Uid", - "MRTCore", - "Resources.resw", - "dot in key", - "signing projection" - ], - "severity": "critical", - "relatedIssues": [ - "microsoft/WindowsAppSDK#6247", - "microsoft/WindowsAppSDK#1687", - "microsoft/WindowsAppSDK#3705", - "microsoft/WindowsAppSDK#6247", - "microsoft/WindowsAppSDK#1687", - "microsoft/WindowsAppSDK#1687", - "microsoft/WindowsAppSDK#1687", - "microsoft/WindowsAppSDK#1687", - "microsoft/WindowsAppSDK#1687", - "microsoft/WindowsAppSDK#1687", - "microsoft/WindowsAppSDK#3705", - "microsoft/WindowsAppSDK#3705" - ] - }, - { - "id": "runtime_winrt_interop", - "path": "E:\\issue-tsg-generator\\output\\tsg_runtime_winrt_interop.md", - "title": "WinRT Interop, AOT Compatibility & Runtime Version Issues - Windows App SDK", - "area": "Runtime", - "symptoms": [ - "Theme switching code fails silently when app is published with Native AOT", - "`Window.Content as FrameworkElement` returns `null` in AOT builds", - "`AppActivationArguments.Data` is `WinRT.IInspectable` instead of a typed activation args object", - "`ReleaseInfo.AsString` returns wrong version (e.g., \"1.7.0\" on 1.7.1)", - "HDR content renders as SDR when using `CompositionDrawingSurface` with float16 pixel format" - ], - "errorCodes": [], - "keywords": [ - "AOT", - "trimming", - "FrameworkElement", - "theme", - "LaunchActivatedEventArgs", - "WinRT", - "CsWinRT", - "IInspectable", - "ReleaseInfo", - "version string", - "HDR", - "CompositionDrawingSurface", - "scRGB", - "swap chain", - "DirectXPixelFormat" - ], - "severity": "critical", - "relatedIssues": [ - "microsoft/WindowsAppSDK#5389", - "microsoft/WindowsAppSDK#6219", - "microsoft/WindowsAppSDK#5323", - "microsoft/WindowsAppSDK#6291", - "microsoft/WindowsAppSDK#5389", - "microsoft/WindowsAppSDK#6219", - "microsoft/WindowsAppSDK#5323", - "microsoft/WindowsAppSDK#6291" - ] - }, - { - "id": "widgets_customization_display", - "path": "E:\\issue-tsg-generator\\output\\tsg_widgets_customization_display.md", - "title": "Widget Customization and Display Failures - Windows Widgets Platform", - "area": "Widgets", - "symptoms": [ - "Widget customization panel opens but shows no content", - "`OnCustomizationRequested` callback is never invoked by widget host", - "First widget in alphabetical list cannot be added to widget board", - "Widget \"Add\" button stays inactive until switching to another widget and back" - ], - "errorCodes": [], - "keywords": [ - "widget customization", - "template JSON", - "OnCustomizationRequested", - "widget board", - "add widget", - "widget list", - "Widgets panel" - ], - "severity": "critical", - "relatedIssues": [ - "microsoft/WindowsAppSDK#3926", - "microsoft/WindowsAppSDK#6140", - "microsoft/WindowsAppSDK#3926", - "microsoft/WindowsAppSDK#6140" - ] - } - ], - "areaCounts": { - "Storage": 3, - "Runtime": 9, - "Deployment": 7, - "Widgets": 2, - "WinML": 1 - }, - "invertedIndex": { - "byErrorCode": { - "0xc000027b": [ - "known_issue_performance_crashes", - "deployment_wasdk18_windows10" - ], - "COMException": [ - "known_issues_external_notifications", - "file_access_storage_pickers", - "msix_selfcontained_packaging_conflicts", - "notifications_push_and_listener", - "resources_mrt_localization" - ], - "0x80004002": [ - "background_tasks_printing_tooling" - ], - "0x80004005": [ - "background_tasks_printing_tooling", - "file_access_storage_pickers" - ], - "0x800706ba": [ - "background_tasks_printing_tooling" - ], - "0x80080204": [ - "background_tasks_printing_tooling" - ], - "0xC00CE169": [ - "background_tasks_printing_tooling" - ], - "E_FAIL": [ - "background_tasks_printing_tooling", - "file_access_storage_pickers" - ], - "E_NOINTERFACE": [ - "background_tasks_printing_tooling" - ], - "0x80070005": [ - "deployment_wasdk18_windows10" - ], - "0x8007007A": [ - "external_interop_issues" - ], - "E_FILTER_HEAD": [ - "external_interop_issues" - ], - "0x80070490": [ - "msix_selfcontained_packaging_conflicts", - "notifications_push_and_listener" - ] - }, - "byKeyword": { - "AppWindow": [ - "known_issue_api_docs_storagefile" - ], - "GetCurrentPlacement": [ - "known_issue_api_docs_storagefile" - ], - "SaveCurrentPlacement": [ - "known_issue_api_docs_storagefile" - ], - "PlacementRestorationBehavior": [ - "known_issue_api_docs_storagefile" - ], - "PlacementInfo": [ - "known_issue_api_docs_storagefile" - ], - "DisplayArea": [ - "known_issue_api_docs_storagefile" - ], - "GetMetricsFromWindowId": [ - "known_issue_api_docs_storagefile" - ], - "PersistedStateId": [ - "known_issue_api_docs_storagefile" - ], - "experimental API": [ - "known_issue_api_docs_storagefile" - ], - "StorageFile": [ - "known_issue_api_docs_storagefile" - ], - "shortcut": [ - "known_issue_api_docs_storagefile" - ], - ".lnk": [ - "known_issue_api_docs_storagefile" - ], - ".url": [ - "known_issue_api_docs_storagefile" - ], - ".wsh": [ - "known_issue_api_docs_storagefile" - ], - "file handler": [ - "known_issue_api_docs_storagefile", - "api_gaps_unpackaged_support" - ], - "PrimaryLanguageOverride": [ - "known_issue_api_gaps_localization", - "resources_mrt_localization" - ], - "null": [ - "known_issue_api_gaps_localization" - ], - "empty": [ - "known_issue_api_gaps_localization" - ], - "not persisted": [ - "known_issue_api_gaps_localization" - ], - "localization": [ - "known_issue_api_gaps_localization", - "resources_mrt_localization" - ], - "Microsoft.Windows.Globalization": [ - "known_issue_api_gaps_localization" - ], - "MovePackageToVolumeAsync": [ - "known_issue_api_gaps_localization" - ], - "PackageDeploymentManager": [ - "known_issue_api_gaps_localization" - ], - "WASDK 2.0": [ - "known_issue_api_gaps_localization" - ], - "Microsoft.Windows.SDK.BuildTools.MSIX": [ - "known_issue_msix_buildtools_defects", - "msix_project_configuration_tooling" - ], - "AppxSymbolPackageEnabled": [ - "known_issue_msix_buildtools_defects" - ], - "_GenerateAppxSymbolPackage": [ - "known_issue_msix_buildtools_defects" - ], - "mspdbcmf.exe": [ - "known_issue_msix_buildtools_defects", - "msix_build_publish_output_failures", - "msix_project_configuration_tooling" - ], - "msixbundle": [ - "known_issue_msix_buildtools_defects", - "msix_build_publish_output_failures" - ], - "Dependencies folder": [ - "known_issue_msix_buildtools_defects" - ], - "Publish error": [ - "known_issue_msix_buildtools_defects" - ], - "wapproj": [ - "known_issue_msix_buildtools_defects", - "msix_project_configuration_tooling" - ], - "documentation": [ - "known_issue_msix_buildtools_defects" - ], - "roadmap": [ - "known_issue_msix_buildtools_defects" - ], - "Microsoft.WindowsAppSDK.Foundation": [ - "known_issue_msix_nuget_license" - ], - "bootstrap DLL": [ - "known_issue_msix_nuget_license" - ], - "NuGet license": [ - "known_issue_msix_nuget_license" - ], - "redistribution": [ - "known_issue_msix_nuget_license" - ], - "Microsoft.WindowsAppSDK": [ - "known_issue_msix_nuget_license" - ], - "license terms": [ - "known_issue_msix_nuget_license" - ], - "WinRT": [ - "known_issue_performance_crashes", - "runtime_winrt_interop" - ], - "ApplicationData": [ - "known_issue_performance_crashes", - "api_gaps_unpackaged_support" - ], - "Package.Current": [ - "known_issue_performance_crashes" - ], - "performance": [ - "known_issue_performance_crashes" - ], - "latency": [ - "known_issue_performance_crashes" - ], - "25ms": [ - "known_issue_performance_crashes" - ], - "admin mode": [ - "known_issue_performance_crashes" - ], - "elevated": [ - "known_issue_performance_crashes" - ], - "packaged app crash": [ - "known_issue_performance_crashes" - ], - "Windows 10": [ - "known_issue_performance_crashes", - "deployment_wasdk18_windows10" - ], - "0xc000027b": [ - "known_issue_performance_crashes" - ], - "widget settings": [ - "known_issue_widget_platform_defects" - ], - "close button": [ - "known_issue_widget_platform_defects" - ], - "reload": [ - "known_issue_widget_platform_defects" - ], - "widget board": [ - "known_issue_widget_platform_defects", - "widgets_customization_display" - ], - "widget not appearing": [ - "known_issue_widget_platform_defects" - ], - "reinstall": [ - "known_issue_widget_platform_defects", - "known_issues_external_notifications" - ], - "customize widget": [ - "known_issue_widget_platform_defects" - ], - "Windows Widgets": [ - "known_issue_widget_platform_defects" - ], - "WidgetProviders": [ - "known_issue_widget_platform_defects" - ], - "MSIX": [ - "known_issues_external_notifications", - "appcontainer_identity_sharing" - ], - "uninstall": [ - "known_issues_external_notifications" - ], - "data retention": [ - "known_issues_external_notifications" - ], - "app data": [ - "known_issues_external_notifications" - ], - "keep data": [ - "known_issues_external_notifications" - ], - "game data": [ - "known_issues_external_notifications" - ], - "SettingsIdentifier": [ - "known_issues_file_access_pickers" - ], - "FileOpenPicker": [ - "known_issues_file_access_pickers", - "file_access_storage_pickers" - ], - "FileSavePicker": [ - "known_issues_file_access_pickers", - "file_access_storage_pickers" - ], - "FolderPicker": [ - "known_issues_file_access_pickers", - "file_access_storage_pickers" - ], - "last used location": [ - "known_issues_file_access_pickers" - ], - "Microsoft.Windows.Storage.Pickers": [ - "known_issues_file_access_pickers" - ], - "unpackaged": [ - "api_gaps_unpackaged_support", - "deployment_singlefile_installer", - "msix_project_configuration_tooling", - "notifications_push_and_listener", - "resources_mrt_localization" - ], - "AppInfo": [ - "api_gaps_unpackaged_support" - ], - "package identity": [ - "api_gaps_unpackaged_support" - ], - "StorageFolder": [ - "api_gaps_unpackaged_support" - ], - "PackageVolume": [ - "api_gaps_unpackaged_support" - ], - "FindPackage": [ - "api_gaps_unpackaged_support" - ], - "content type": [ - "api_gaps_unpackaged_support" - ], - "file association": [ - "api_gaps_unpackaged_support" - ], - "manifest": [ - "api_gaps_unpackaged_support" - ], - "LOCALAPPDATA": [ - "api_gaps_unpackaged_support" - ], - "AppContainer": [ - "appcontainer_identity_sharing" - ], - "Win32": [ - "appcontainer_identity_sharing" - ], - "PartialTrustApplication": [ - "appcontainer_identity_sharing" - ], - "partial trust": [ - "appcontainer_identity_sharing" - ], - "sandboxing": [ - "appcontainer_identity_sharing" - ], - "named objects": [ - "appcontainer_identity_sharing" - ], - "security descriptor": [ - "appcontainer_identity_sharing" - ], - "PackageFamilyName": [ - "appcontainer_identity_sharing" - ], - "PFN": [ - "appcontainer_identity_sharing" - ], - "Shell_NotifyIcon": [ - "appcontainer_identity_sharing" - ], - "tray icon": [ - "appcontainer_identity_sharing" - ], - "runFullTrust": [ - "appcontainer_identity_sharing" - ], - "permissiveLearningMode": [ - "appcontainer_identity_sharing" - ], - "UniversalBGTask": [ - "background_tasks_printing_tooling" - ], - "STOWED_EXCEPTION": [ - "background_tasks_printing_tooling" - ], - "background task": [ - "background_tasks_printing_tooling" - ], - "crash": [ - "background_tasks_printing_tooling" - ], - "0x80004005": [ - "background_tasks_printing_tooling" - ], - "0x80004002": [ - "background_tasks_printing_tooling" - ], - "0x800706ba": [ - "background_tasks_printing_tooling" - ], - "0x80080204": [ - "background_tasks_printing_tooling" - ], - "0xC00CE169": [ - "background_tasks_printing_tooling" - ], - "ACCESS_VIOLATION": [ - "background_tasks_printing_tooling" - ], - "PrintPreview": [ - "background_tasks_printing_tooling" - ], - "dark theme": [ - "background_tasks_printing_tooling" - ], - "RequestedTheme": [ - "background_tasks_printing_tooling" - ], - "empty preview": [ - "background_tasks_printing_tooling" - ], - "Visual Studio 2022": [ - "background_tasks_printing_tooling" - ], - "add page": [ - "background_tasks_printing_tooling" - ], - "new item": [ - "background_tasks_printing_tooling" - ], - "XamlParseException": [ - "deployment_singlefile_installer", - "msix_selfcontained_packaging_conflicts" - ], - "XAML parsing failed": [ - "deployment_singlefile_installer" - ], - "single-file": [ - "deployment_singlefile_installer" - ], - "rename executable": [ - "deployment_singlefile_installer" - ], - "PublishSingleFile": [ - "deployment_singlefile_installer" - ], - "runtime links broken": [ - "deployment_singlefile_installer" - ], - "2.0 preview": [ - "deployment_singlefile_installer" - ], - "installer binaries": [ - "deployment_singlefile_installer" - ], - "MRM.dll crash": [ - "deployment_singlefile_installer" - ], - "FindPackagesByPackageFamily": [ - "deployment_wasdk18_windows10", - "external_interop_issues" - ], - "WASDK 1.8": [ - "deployment_wasdk18_windows10" - ], - "17763": [ - "deployment_wasdk18_windows10" - ], - "19041": [ - "deployment_wasdk18_windows10" - ], - "DeploymentManager": [ - "deployment_wasdk18_windows10" - ], - "crash on launch": [ - "deployment_wasdk18_windows10" - ], - "0x80070005": [ - "deployment_wasdk18_windows10" - ], - "DDLM PackageFullName": [ - "deployment_wasdk18_windows10" - ], - "MSIX.inventory": [ - "deployment_wasdk18_windows10" - ], - "packaging project": [ - "external_interop_issues" - ], - "NuGet": [ - "external_interop_issues", - "msix_project_configuration_tooling" - ], - "stale assembly": [ - "external_interop_issues" - ], - "MSIX bundle": [ - "external_interop_issues" - ], - "0x8007007A": [ - "external_interop_issues" - ], - "ERROR_INSUFFICIENT_BUFFER": [ - "external_interop_issues" - ], - "DeviceInformationPairing": [ - "external_interop_issues" - ], - "Bluetooth": [ - "external_interop_issues" - ], - "ProximityDevice": [ - "external_interop_issues" - ], - "NFC": [ - "external_interop_issues" - ], - "Widgets": [ - "external_interop_issues" - ], - "WinUI 3": [ - "external_interop_issues" - ], - "storage pickers": [ - "file_access_storage_pickers" - ], - "file picker crash": [ - "file_access_storage_pickers" - ], - "COMException": [ - "file_access_storage_pickers", - "msix_selfcontained_packaging_conflicts", - "notifications_push_and_listener", - "resources_mrt_localization" - ], - "E_FAIL": [ - "file_access_storage_pickers" - ], - "IInitializeWithWindow": [ - "file_access_storage_pickers" - ], - "DefaultFileExtension": [ - "file_access_storage_pickers" - ], - "FileTypeChoices": [ - "file_access_storage_pickers" - ], - "WSL": [ - "file_access_storage_pickers" - ], - "RTL": [ - "file_access_storage_pickers" - ], - "language override": [ - "file_access_storage_pickers" - ], - "msixupload": [ - "msix_build_publish_output_failures" - ], - "appxsym": [ - "msix_build_publish_output_failures" - ], - "WinAppSdkSignAppxPackageBundle": [ - "msix_build_publish_output_failures" - ], - "MSB4036": [ - "msix_build_publish_output_failures" - ], - "MSB6006": [ - "msix_build_publish_output_failures" - ], - "CMF1106": [ - "msix_build_publish_output_failures" - ], - "UapAppxPackageBuildMode": [ - "msix_build_publish_output_failures" - ], - "StoreUpload": [ - "msix_build_publish_output_failures" - ], - "StoreAndSideload": [ - "msix_build_publish_output_failures" - ], - "EnableMsixTooling": [ - "msix_project_configuration_tooling", - "msix_selfcontained_packaging_conflicts" - ], - "AppxOSMinVersionReplaceManifestVersion": [ - "msix_project_configuration_tooling" - ], - "AppxOSMaxVersionTestedReplaceManifestVersion": [ - "msix_project_configuration_tooling" - ], - "single-project MSIX": [ - "msix_project_configuration_tooling" - ], - "Visual Studio": [ - "msix_project_configuration_tooling" - ], - "resources.pri": [ - "msix_project_configuration_tooling", - "msix_selfcontained_packaging_conflicts" - ], - "WindowsAppSDKSelfContained": [ - "msix_selfcontained_packaging_conflicts" - ], - "0x80070490": [ - "msix_selfcontained_packaging_conflicts", - "notifications_push_and_listener" - ], - "PRI": [ - "msix_selfcontained_packaging_conflicts" - ], - "_OverrideGetPriIndexName": [ - "msix_selfcontained_packaging_conflicts" - ], - "WMC1012": [ - "msix_selfcontained_packaging_conflicts" - ], - "ApplicationXaml": [ - "msix_selfcontained_packaging_conflicts" - ], - "codegen": [ - "msix_selfcontained_packaging_conflicts" - ], - "library project": [ - "msix_selfcontained_packaging_conflicts" - ], - "AppNotification": [ - "notifications_push_and_listener" - ], - "push notification": [ - "notifications_push_and_listener" - ], - "Element not found": [ - "notifications_push_and_listener" - ], - "UserNotificationListener": [ - "notifications_push_and_listener" - ], - "NotificationChanged": [ - "notifications_push_and_listener" - ], - "AppNotificationProgressData": [ - "notifications_push_and_listener" - ], - "IsIndeterminate": [ - "notifications_push_and_listener" - ], - "indeterminate progress bar": [ - "notifications_push_and_listener" - ], - "toast notification": [ - "notifications_push_and_listener" - ], - "ResourceLoader": [ - "resources_mrt_localization" - ], - "GetString": [ - "resources_mrt_localization" - ], - "NamedResource Not Found": [ - "resources_mrt_localization" - ], - "x:Uid": [ - "resources_mrt_localization" - ], - "MRTCore": [ - "resources_mrt_localization" - ], - "Resources.resw": [ - "resources_mrt_localization" - ], - "dot in key": [ - "resources_mrt_localization" - ], - "signing projection": [ - "resources_mrt_localization" - ], - "AOT": [ - "runtime_winrt_interop" - ], - "trimming": [ - "runtime_winrt_interop" - ], - "FrameworkElement": [ - "runtime_winrt_interop" - ], - "theme": [ - "runtime_winrt_interop" - ], - "LaunchActivatedEventArgs": [ - "runtime_winrt_interop" - ], - "CsWinRT": [ - "runtime_winrt_interop" - ], - "IInspectable": [ - "runtime_winrt_interop" - ], - "ReleaseInfo": [ - "runtime_winrt_interop" - ], - "version string": [ - "runtime_winrt_interop" - ], - "HDR": [ - "runtime_winrt_interop" - ], - "CompositionDrawingSurface": [ - "runtime_winrt_interop" - ], - "scRGB": [ - "runtime_winrt_interop" - ], - "swap chain": [ - "runtime_winrt_interop" - ], - "DirectXPixelFormat": [ - "runtime_winrt_interop" - ], - "widget customization": [ - "widgets_customization_display" - ], - "template JSON": [ - "widgets_customization_display" - ], - "OnCustomizationRequested": [ - "widgets_customization_display" - ], - "add widget": [ - "widgets_customization_display" - ], - "widget list": [ - "widgets_customization_display" - ], - "Widgets panel": [ - "widgets_customization_display" - ] - }, - "byArea": { - "Storage": [ - "known_issue_api_docs_storagefile", - "known_issues_file_access_pickers", - "file_access_storage_pickers" - ], - "Runtime": [ - "known_issue_api_gaps_localization", - "known_issue_performance_crashes", - "known_issues_external_notifications", - "appcontainer_identity_sharing", - "background_tasks_printing_tooling", - "external_interop_issues", - "notifications_push_and_listener", - "resources_mrt_localization", - "runtime_winrt_interop" - ], - "Deployment": [ - "known_issue_msix_buildtools_defects", - "known_issue_msix_nuget_license", - "deployment_singlefile_installer", - "deployment_wasdk18_windows10", - "msix_build_publish_output_failures", - "msix_project_configuration_tooling", - "msix_selfcontained_packaging_conflicts" - ], - "Widgets": [ - "known_issue_widget_platform_defects", - "widgets_customization_display" - ], - "WinML": [ - "api_gaps_unpackaged_support" - ] - } - } -} \ No newline at end of file From 8ee04d87349afb09db3af92a4bc96e01047a7671 Mon Sep 17 00:00:00 2001 From: Qiutong Shen Date: Fri, 20 Mar 2026 15:25:37 +0800 Subject: [PATCH 4/7] Add 2 new TSGs, update 1 existing TSG - incremental 2026-03-20 --- .../tsg_activation_and_rpc_errors.md | 2 +- .../tsg_notifications_push_and_listener.md | 23 ++++++- .../tsg_winml_ort_unicode_path.md | 65 ++++++++++++++++++ .../tsg_xaml_loadcomponent_subfolder_xbf.md | 67 +++++++++++++++++++ 4 files changed, 153 insertions(+), 4 deletions(-) create mode 100644 trouble-shooting-notes/tsg_winml_ort_unicode_path.md create mode 100644 trouble-shooting-notes/tsg_xaml_loadcomponent_subfolder_xbf.md diff --git a/trouble-shooting-notes/tsg_activation_and_rpc_errors.md b/trouble-shooting-notes/tsg_activation_and_rpc_errors.md index 7564f3d..7db1af1 100644 --- a/trouble-shooting-notes/tsg_activation_and_rpc_errors.md +++ b/trouble-shooting-notes/tsg_activation_and_rpc_errors.md @@ -22,7 +22,7 @@ System.Runtime.InteropServices.COMException: 'The RPC server is unavailable.' ## Related Issues -- [#5481](https://github.com/microsoft/WindowsAppSDK/issues/5481) - Exception triggered when calling `AppInstance.GetCurrent().GetActivatedEventArgs()` (Status: Open) +- [#5481](https://github.com/microsoft/WindowsAppSDK/issues/5481) - Exception triggered when calling `AppInstance.GetCurrent().GetActivatedEventArgs()` (Status: Closed) --- diff --git a/trouble-shooting-notes/tsg_notifications_push_and_listener.md b/trouble-shooting-notes/tsg_notifications_push_and_listener.md index 26347e6..c6ebc21 100644 --- a/trouble-shooting-notes/tsg_notifications_push_and_listener.md +++ b/trouble-shooting-notes/tsg_notifications_push_and_listener.md @@ -1,6 +1,6 @@ # Notification Issues — Push Notifications, Progress Data, and UserNotificationListener -**Keywords:** AppNotification, push notification, unpackaged, COMException, 0x80070490, Element not found, UserNotificationListener, NotificationChanged, AppNotificationProgressData, IsIndeterminate, indeterminate progress bar, toast notification, BadgeNotificationManager, REGDB_E_CLASSNOTREG, ScheduledToastNotification +**Keywords:** AppNotification, push notification, unpackaged, COMException, 0x80070490, Element not found, UserNotificationListener, NotificationChanged, AppNotificationProgressData, IsIndeterminate, indeterminate progress bar, toast notification, BadgeNotificationManager, REGDB_E_CLASSNOTREG, ScheduledToastNotification, WNS, PFN, Azure AppId, 403 **Error Example:** ``` @@ -33,6 +33,7 @@ System.Runtime.InteropServices.COMException (0x80070490): Element not found - [#6172](https://github.com/microsoft/WindowsAppSDK/issues/6172) — COMException 0x80070490 when subscribing to UserNotificationListener.NotificationChanged (Status: Open) - [#5050](https://github.com/microsoft/WindowsAppSDK/issues/5050) — Feature Request: Schedule toast notifications (Status: Open) - [#5307](https://github.com/microsoft/WindowsAppSDK/issues/5307) — COMException REGDB_E_CLASSNOTREG from BadgeNotificationManager (Status: Closed — resolved in 1.7.1) +- [#6301](https://github.com/microsoft/WindowsAppSDK/issues/6301) — PFN-to-Azure-AppId mapping for WNS push notifications returns 403 (Status: Closed — resolved via email mapping) --- @@ -157,6 +158,22 @@ notifier.AddToSchedule(scheduledToast); --- +### Scenario 6: WNS Push Notifications Return 403 — PFN-to-Azure-AppId Mapping Not Registered + +**Cause:** When using the Entra/AAD auth flow for WNS push notifications, pushing to the channel URI returns HTTP 403. The token acquisition succeeds, and the client app obtains a valid channel URI via `PushNotificationChannelManager.CreatePushNotificationChannelForApplicationAsync()`, but the server-side push fails. This occurs because the Package Family Name (PFN) has not been mapped to the Azure App ID in the WNS backend. +> Source: @leonyambay in [#6301](https://github.com/microsoft/WindowsAppSDK/issues/6301) + +**Fix:** +1. **Email the WNS team** at `Win_App_SDK_Push@microsoft.com` to request PFN-to-Azure-AppId mapping. +2. Include your Package Family Name and Azure App Registration details. +3. Follow the [Push notifications quickstart guide](https://learn.microsoft.com/en-us/windows/apps/develop/notifications/push-notifications/push-quickstart) for the complete setup process. + +> Source: @lauren-ciha (MEMBER) in [#6301](https://github.com/microsoft/WindowsAppSDK/issues/6301) + +**Verify:** After the mapping is confirmed by the WNS team, retry pushing to the channel URI — the 403 should be resolved. + +--- + ## ⚠️ Unverified / Community Suggestions > The following are community suggestions that have NOT been officially confirmed. @@ -175,5 +192,5 @@ notifier.AddToSchedule(scheduledToast); --- -**Updated:** 2026-03-17 | **Confidence:** 0.8 -**Sources:** #334, #2231, #6172, #5050, #5307 \ No newline at end of file +**Updated:** 2026-03-20 | **Confidence:** 0.8 +**Sources:** #334, #2231, #6172, #5050, #5307, #6301 \ No newline at end of file diff --git a/trouble-shooting-notes/tsg_winml_ort_unicode_path.md b/trouble-shooting-notes/tsg_winml_ort_unicode_path.md new file mode 100644 index 0000000..0f7c699 --- /dev/null +++ b/trouble-shooting-notes/tsg_winml_ort_unicode_path.md @@ -0,0 +1,65 @@ +# Error: WinML ORT InferenceSession Fails When Model Path Contains Non-ASCII Unicode Characters + +**Keywords:** WinML, ORT, ONNX Runtime, InferenceSession, Unicode, non-ASCII, model path, inference_session.cc, multi-byte code page, std::filesystem, QNN, DirectML, CPU Execution Provider + +**Error Example:** +``` +[E:onnxruntime:, inference_session.cc:2545 onnxruntime::InferenceSession::Initialize::::operator ()] Exception during initialization: No mapping for the Unicode character exists in the target multi-byte code page. +``` + +--- + +## Quick Match + +**You're seeing this if:** +- Error contains "No mapping for the Unicode character exists in the target multi-byte code page" +- Using WinML with ONNX Runtime (ORT) on Windows +- Model file path contains non-ASCII characters (e.g., Chinese, Japanese, accented Latin characters) +- Works with CPU Execution Provider but fails with QNN or DirectML + +→ See Scenario 1 below + +--- + +## Related Issues + +- [#6173](https://github.com/microsoft/WindowsAppSDK/issues/6173) — WinML ORT compile and inferenceSession error when the model path contains any non-ASCII Unicode characters (Status: Open) + +--- + +## Scenarios & Solutions + +### Scenario 1: ORT Uses Narrow String Conversion for Model Paths + +**Cause:** In 10 locations across ONNX Runtime's session and execution provider code, `std::filesystem::path::filename().string()` is used to convert model paths to narrow (ANSI) strings. On Windows, `.string()` converts via the system ANSI code page, which cannot represent many Unicode characters. This causes the path conversion to throw when the model path contains characters outside the system's ANSI code page. + +The bug originates in `microsoft/onnxruntime`, not in WindowsAppSDK. The WinML runtime consumes ONNX Runtime as a binary dependency. The issue does not occur with the CPU Execution Provider because the CPU EP code path does not use the narrow-string conversion for model paths. + +> Source: @sagarbhure-msft in [#6173](https://github.com/microsoft/WindowsAppSDK/issues/6173) + +**Workaround — Move model to ASCII-only path:** +1. Copy or move the ONNX model file to a directory with only ASCII characters in the path: + ``` + ❌ C:\Users\用户\Models\model.onnx + ✅ C:\Models\model.onnx + ``` +2. Update your code to reference the new path. + +**Permanent Fix:** A PR has been opened in the ONNX Runtime repository to replace all 10 occurrences of `.string()` with `.wstring()` or use wide-string APIs. +> Source: @sagarbhure-msft in [#6173](https://github.com/microsoft/WindowsAppSDK/issues/6173) + +> ✅ Confirmed root cause by: @rnagata0 in [#6173](https://github.com/microsoft/WindowsAppSDK/issues/6173) + +**Verify:** After moving the model to an ASCII-only path, the InferenceSession should initialize successfully with QNN/DirectML EPs. + +--- + +## References + +- [ONNX Runtime GitHub](https://github.com/microsoft/onnxruntime) +- [WinML overview](https://learn.microsoft.com/en-us/windows/ai/windows-ml/) + +--- + +**Updated:** 2026-03-20 | **Confidence:** 0.90 +**Sources:** [#6173](https://github.com/microsoft/WindowsAppSDK/issues/6173) diff --git a/trouble-shooting-notes/tsg_xaml_loadcomponent_subfolder_xbf.md b/trouble-shooting-notes/tsg_xaml_loadcomponent_subfolder_xbf.md new file mode 100644 index 0000000..3add2f8 --- /dev/null +++ b/trouble-shooting-notes/tsg_xaml_loadcomponent_subfolder_xbf.md @@ -0,0 +1,67 @@ +# Error: LoadComponent Fails for XAML Pages in Subfolders — XBF Filename-Only Indexing + +**Keywords:** LoadComponent, XBF, XAML, subfolders, ms-appx, embed.resfiles, GenerateLibraryLayout, _CalculateXbfSupport, _SupportXbfAsEmbedFileResources, resources.pri, Microsoft.Build.Msix.Pri.targets, WinUI 3, subdirectory + +**Error Example:** +``` +Cannot locate resource from 'ms-appx:///Presentation/Shell.xaml' +``` +or: +``` +Layout cycle detected. Layout is not able to complete. +``` + +--- + +## Quick Match + +**You're seeing this if:** +- App builds without errors but crashes at runtime with `Cannot locate resource from 'ms-appx:///.../Page.xaml'` +- XAML pages are organized in subdirectories (e.g., `Presentation\Shell.xaml`) +- Building from Visual Studio with `Platform=x64` (not `dotnet build -r win-x64`) +- Using WinUI 3 with the WindowsAppSDK NuGet package (1.0.0+) + +→ See Scenario 1 below + +--- + +## Related Issues + +- [#6299](https://github.com/microsoft/WindowsAppSDK/issues/6299) — LoadComponent fails for XAML pages in subfolders — embedded XBF indexed by filename only (Status: Open) + +--- + +## Scenarios & Solutions + +### Scenario 1: XBF Files Lose Subdirectory Path When Embedded as File Resources + +**Cause:** The `_CalculateXbfSupport` target in `Microsoft.Build.Msix.Pri.targets` (shipped in the `Microsoft.WindowsAppSDK` NuGet package since v1.0.0) sets `_SupportXbfAsEmbedFileResources=true` by default. When building from Visual Studio with `Platform=x64`, the intermediate path structure differs from `dotnet build -r win-x64`, causing XBF files to be indexed by filename only (without subdirectory path) in `embed.resfiles`. At runtime, `LoadComponent` looks for `ms-appx:///Presentation/Shell.xaml` but the resource is registered as just `Shell.xbf`. + +> Source: @xperiandri in [#6299](https://github.com/microsoft/WindowsAppSDK/issues/6299) + +**Fix — Set `GenerateLibraryLayout=true`:** + +Add the following property to your project file: +```xml + + true + +``` + +This causes the `CustomOutputGroupForPackaging` target in `Microsoft.UI.Xaml.Markup.Compiler.interop.targets` to use the correct `XamlPackagingRootFolder`, preserving subdirectory paths in the XBF resource index. + +> Source: @xperiandri in [#6299](https://github.com/microsoft/WindowsAppSDK/issues/6299) — "Better fix found: `GenerateLibraryLayout=true`" + +**Verify:** Clean the solution, rebuild from Visual Studio, and confirm the app loads XAML pages from subfolders without runtime crash. + +--- + +## References + +- [Microsoft.Build.Msix.Pri.targets source](https://github.com/microsoft/WindowsAppSDK) — `_CalculateXbfSupport` target +- [XBF (XAML Binary Format) overview](https://learn.microsoft.com/en-us/windows/apps/winui/) + +--- + +**Updated:** 2026-03-20 | **Confidence:** 0.85 +**Sources:** [#6299](https://github.com/microsoft/WindowsAppSDK/issues/6299) From dee1279167382e74e86344576aeddb4097bd05b3 Mon Sep 17 00:00:00 2001 From: shisan Date: Mon, 23 Mar 2026 16:44:39 +0800 Subject: [PATCH 5/7] Pipeline incremental: update 2 TSGs (issues #6197, #4791) --- .../tsg_external_interop_issues.md | 127 +++++------------- .../tsg_msix_build_publish_output_failures.md | 22 ++- 2 files changed, 52 insertions(+), 97 deletions(-) diff --git a/trouble-shooting-notes/tsg_external_interop_issues.md b/trouble-shooting-notes/tsg_external_interop_issues.md index 9e61a9e..0ef0e12 100644 --- a/trouble-shooting-notes/tsg_external_interop_issues.md +++ b/trouble-shooting-notes/tsg_external_interop_issues.md @@ -1,6 +1,6 @@ # External / Interop Issues — Packaging, Device APIs, and Widgets -**Keywords:** packaging project, NuGet, stale assembly, MSIX bundle, FindPackagesByPackageFamily, 0x8007007A, ERROR_INSUFFICIENT_BUFFER, DeviceInformationPairing, Bluetooth, ProximityDevice, NFC, Widgets, WinUI 3, HybridWebView.js, build failure, WindowsAppSDK upgrade +**Keywords:** packaging project, NuGet, stale assembly, MSIX bundle, FindPackagesByPackageFamily, 0x8007007A, ERROR_INSUFFICIENT_BUFFER, DeviceInformationPairing, Bluetooth, ProximityDevice, NFC, Widgets, WinUI 3, HybridWebView.js, build failure, WindowsAppSDK upgrade, PackageDeploymentManager, RegisterPackageAsync, RPC failure **Error Example:** ``` @@ -14,6 +14,10 @@ System.InvalidCastException ``` Could not copy the file "C:\Users\Jochem\.nuget\packages\microsoft.maui.controls.core\9.0.120\lib\net9.0-windows10.0.19041\Microsoft.Maui\Handlers\HybridWebView\HybridWebView.js" because it was not found. ``` +``` +Exception thrown at 0x00007FFF613A83EA (KernelBase.dll) in PackageManagerRegisterTest.exe: WinRT originate error - 0x800706BE : 'The remote procedure call failed.' +Exception thrown at 0x00007FFF613A83EA (KernelBase.dll) in PackageManagerRegisterTest.exe: 0x000006BE: The remote procedure call failed. +``` --- @@ -26,6 +30,7 @@ Could not copy the file "C:\Users\Jochem\.nuget\packages\microsoft.maui.controls - NFC `ProximityDevice` events never fire after UWP → WinUI 3 migration - Widgets panel: first widget (alphabetically) cannot be added - Build fails with "Could not copy the file HybridWebView.js" after upgrading to Windows App SDK 1.8 +- `PackageDeploymentManager.RegisterPackageAsync()` fails with RPC error while `RegisterPackageByFullNameAsync()` succeeds → Check scenarios below for your specific cause @@ -39,6 +44,7 @@ Could not copy the file "C:\Users\Jochem\.nuget\packages\microsoft.maui.controls - [#4356](https://github.com/microsoft/WindowsAppSDK/issues/4356) — ProximityDevice NFC events not triggered (Status: Open) - [#6140](https://github.com/microsoft/WindowsAppSDK/issues/6140) — Widget at top of list cannot be added until switching away (Status: Open) - [#6032](https://github.com/microsoft/WindowsAppSDK/issues/6032) — "Could not copy the file HybridWebView.js" when upgrading to 1.8.251106002 (Status: Closed) +- [#4791](https://github.com/microsoft/WindowsAppSDK/issues/4791) — `PackageDeploymentManager.RegisterPackageAsync()` fails while `RegisterPackageByFullNameAsync()` succeeds (Status: Open) --- @@ -51,16 +57,16 @@ Could not copy the file "C:\Users\Jochem\.nuget\packages\microsoft.maui.controls **Affected versions:** Visual Studio 2026, Windows App SDK (MSIX packaging), any NuGet package -**Repro:** -1. Reference `CommunityToolkit.Mvvm` version **8.3.2**, build MSIX bundle → DLL is 8.3.2.1 ✅ -2. Upgrade to **8.4.0**, Clean Solution, rebuild → DLL is 8.4.0.1 ✅ -3. Downgrade back to **8.3.2**, Clean Solution, rebuild → DLL is still **8.4.0.1** ⚠️ +**Repro:** +1. Reference `CommunityToolkit.Mvvm` version **8.3.2**, build MSIX bundle → DLL is 8.3.2.1 ✅ +2. Upgrade to **8.4.0**, Clean Solution, rebuild → DLL is 8.4.0.1 ✅ +3. Downgrade back to **8.3.2**, Clean Solution, rebuild → DLL is still **8.4.0.1** ⚠️ -**Fix:** -1. **Manually delete the packaging project output folders** before rebuilding: - - Delete `App1 (Package)\AppPackages\` folder - - Delete `App1 (Package)\bin\` and `App1 (Package)\obj\` folders -2. **Force a full NuGet restore** after version change: +**Fix:** +1. **Manually delete the packaging project output folders** before rebuilding: + - Delete `App1 (Package)\AppPackages\` folder + - Delete `App1 (Package)\bin\` and `App1 (Package)\obj\` folders +2. **Force a full NuGet restore** after version change: ```powershell dotnet nuget locals all --clear dotnet restore @@ -80,9 +86,9 @@ dotnet restore **Important note:** This exception surfaces only when **"Break when thrown"** is enabled for all exceptions in Visual Studio's Exception Settings. In normal execution, the SDK may handle this internally. -**Fix:** -1. **Check if this is a first-chance exception only.** Uncheck "Break when thrown" for `WinRT originate error` exceptions in Visual Studio → Exception Settings. If the app runs normally, this is an internal SDK exception that is caught and handled. -2. If calling `FindPackagesByPackageFamily` in your own code, ensure proper two-call pattern: +**Fix:** +1. **Check if this is a first-chance exception only.** Uncheck "Break when thrown" for `WinRT originate error` exceptions in Visual Studio → Exception Settings. If the app runs normally, this is an internal SDK exception that is caught and handled. +2. If calling `FindPackagesByPackageFamily` in your own code, ensure proper two-call pattern: ```cpp UINT32 count = 0; UINT32 bufferLength = 0; @@ -100,91 +106,22 @@ FindPackagesByPackageFamily(familyName, PACKAGE_FILTER_HEAD, &count, packageFull --- -### Scenario 3: Device Pairing UI Does Not Display in WinUI 3 Desktop App - -**Cause:** Calling `DeviceInformationPairing.PairAsync()` in a WinUI 3 desktop app does not show the system Bluetooth pairing UI. The pairing process silently fails after a few seconds. The `IInitializeWithWindow` workaround documented for other UWP controls throws `System.InvalidCastException` when applied to `DeviceInformation` or `DeviceInformation.Pairing` because these objects do not implement `IInitializeWithWindow`. -> Source: Issue [#3091](https://github.com/microsoft/WindowsAppSDK/issues/3091) - -**Affected versions:** Windows App SDK 1.0+, Windows 11 (21H2) +### Known Issue: `PackageDeploymentManager.RegisterPackageAsync()` Fails While `RegisterPackageByFullNameAsync()` Succeeds -**Fix:** -1. **Use `DeviceInformationCustomPairing`** with a custom handler instead of the automatic pairing UI: -```csharp -var customPairing = deviceInfo.Pairing.Custom; -customPairing.PairingRequested += (sender, args) => -{ - // Handle pairing ceremony in your own UI - args.Accept(); // or args.Accept(pin) for PIN-based pairing -}; -var result = await customPairing.PairAsync( - DevicePairingKinds.ConfirmOnly | DevicePairingKinds.DisplayPin); -``` -2. **Build your own pairing confirmation dialog** in WinUI 3 XAML since the system pairing UI is not compatible with Win32 desktop windows. -3. For Bluetooth LE devices, consider using `BluetoothLEDevice.FromIdAsync()` followed by `DeviceInformation.Pairing.Custom.PairAsync()`. +**Cause:** `PackageDeploymentManager.RegisterPackageAsync()` fails with `PackageDeploymentStatus.CompletedFailure` and empty error properties, while the WinRT method `RegisterPackageByFullNameAsync()` succeeds. Debugging shows RPC failure (`0x800706BE`) and "Element not found" (`0x80070490`). This is due to improper memory handling in the WASDK method when passing `const hstring&` parameters. +> Source: @DrusTheAxe in [#4791](https://github.com/microsoft/WindowsAppSDK/issues/4791) -**Verify:** Initiate Bluetooth pairing and confirm your custom UI appears and the device pairs successfully. - ---- +**Affected versions:** Windows App SDK 1.7+, Windows 11 22H2+ -### Scenario 4: ProximityDevice NFC Events Not Triggered After UWP → WinUI 3 Migration - -**Cause:** `Windows.Networking.Proximity.ProximityDevice` events (e.g., `SubscribeForMessage("NDEF", ...)`) work in UWP but do not fire in WinUI 3 / Windows App SDK desktop apps. The `ProximityDevice` API is a UWP-era API that relies on the UWP app model and brokered device access, which is not fully supported in the Win32 desktop app model used by WinUI 3. -> Source: Issue [#4356](https://github.com/microsoft/WindowsAppSDK/issues/4356) - -**Affected versions:** Windows App SDK 1.5.2+, Windows 11 22H2 - -**Repro:** -```csharp -var proximityDevice = Windows.Networking.Proximity.ProximityDevice.GetDefault(); -var messageSubscriptionId = proximityDevice.SubscribeForMessage("NDEF", (device, message) => -{ - Console.WriteLine(message.Data.ToArray()); // Never fires in WinUI 3 -}); -``` - -**Fix / Workaround:** -1. **Use the PC/SC (WinSCard) API** for NFC smart card access as an alternative to `ProximityDevice`: +**Workaround:** +1. Use the WinRT method `PackageManager.RegisterPackageByFullNameAsync()` instead of the WASDK method: ```csharp -// Use Windows.Devices.SmartCards namespace -var reader = await SmartCardReader.FromIdAsync(deviceId); -reader.CardAdded += OnCardAdded; +var packageManager = new Windows.Management.Deployment.PackageManager(); +await packageManager.RegisterPackageByFullNameAsync(packageFullName, null, DeploymentOptions.None); ``` -2. **Use a third-party NFC library** that wraps the Win32 PC/SC APIs (e.g., PCSC-Sharp). -3. Ensure `` is declared in your app manifest (required but not sufficient for WinUI 3). -4. As a last resort, **keep NFC functionality in a separate UWP component** or background task that communicates with the main WinUI 3 app. - -> ⚠️ This is an open issue. `ProximityDevice` is not officially supported in WinUI 3 desktop apps. - ---- - -### Scenario 5: Widget at Top of Alphabetical List Cannot Be Added - -**Cause:** In the Windows Widgets panel, a widget whose name starts with "A" (appearing at the top of the list) cannot be added — the "Add" button stays gray/inactive. Switching to another widget and back causes it to become addable. This appears to be a UI initialization/selection state bug in the Widgets Board. -> Source: Issue [#6140](https://github.com/microsoft/WindowsAppSDK/issues/6140) - -**Affected versions:** Windows 11 25H2 (Build 26220.7535) - -**Fix / Workaround:** -1. **Workaround for end users:** Select a different widget first, then switch back to the desired widget — it will become addable. -2. **For widget developers:** Consider naming your widget to not appear first alphabetically as a temporary workaround (e.g., prefix with a space or non-"A" character), though this is not ideal. - -> ⚠️ This is a Windows Widgets Board bug — no SDK-level fix available. Report via Feedback Hub for Windows team triage. - ---- - -### Known Issue: Build Fails with "Could Not Copy the File HybridWebView.js" After Upgrading to Windows App SDK 1.8 - -**Cause:** When upgrading from Windows App SDK 1.7 to 1.8, builds may fail with the error: -`Could not copy the file "HybridWebView.js" because it was not found.` -This issue appears to be related to a missing file in the `Microsoft.Maui.Controls.Core` package when used with Windows App SDK 1.8. The issue has been linked to a known problem in the .NET MAUI repository. -> Source: @mfkl in [#6032](https://github.com/microsoft/WindowsAppSDK/issues/6032) - -**Affected versions:** Windows App SDK 1.8.251106002, .NET MAUI 9.0.120 - -**Workaround:** -No confirmed workaround is available. Cleaning the NuGet cache and rebuilding does not resolve the issue. The issue may be related to [dotnet/maui#32683](https://github.com/dotnet/maui/issues/32683). +2. Ensure your app is unpackaged or has the correct manifest capabilities (`packageManagement`). -> ⚠️ This issue has been closed without a confirmed resolution. Developers encountering this issue are encouraged to monitor the linked .NET MAUI issue for updates. +> ⚠️ This issue is under investigation. A fix is expected in a future servicing update. --- @@ -195,6 +132,7 @@ No confirmed workaround is available. Cleaning the NuGet cache and rebuilding do - For stale NuGet caching (#6253): Some developers report that switching the solution configuration (Debug ↔ Release) and rebuilding can force correct DLL resolution. - For NFC (#4356): The original reporter tried `DeviceCapability` declarations and multiple SDK versions without success. There is no confirmed workaround within the WinUI 3 app model. - For HybridWebView.js build failure (#6032): Some users suggest manually copying the missing file from a working version of the package, though this is not officially recommended. +- For `RegisterPackageAsync` (#4791): Some users report success by using unpackaged apps or switching to WinRT APIs. --- @@ -207,8 +145,9 @@ No confirmed workaround is available. Cleaning the NuGet cache and rebuilding do - [Windows Widgets overview](https://learn.microsoft.com/en-us/windows/apps/develop/widgets/) - [MSIX packaging documentation](https://learn.microsoft.com/en-us/windows/msix/) - [dotnet/maui#32683](https://github.com/dotnet/maui/issues/32683) +- [PackageManager API (WinRT)](https://learn.microsoft.com/en-us/uwp/api/windows.management.deployment.packagemanager) --- -**Updated:** 2026-03-17 | **Confidence:** 0.6 -**Sources:** #6253, #6274, #3091, #4356, #6140, #6032 \ No newline at end of file +**Updated:** 2026-03-23 | **Confidence:** 0.7 +**Sources:** #6253, #6274, #3091, #4356, #6140, #6032, #4791 \ No newline at end of file diff --git a/trouble-shooting-notes/tsg_msix_build_publish_output_failures.md b/trouble-shooting-notes/tsg_msix_build_publish_output_failures.md index 388a902..c8ce44a 100644 --- a/trouble-shooting-notes/tsg_msix_build_publish_output_failures.md +++ b/trouble-shooting-notes/tsg_msix_build_publish_output_failures.md @@ -1,12 +1,13 @@ # Error: MSIX Build/Publish Output Failures (msixupload, msixbundle, appxsym) -**Keywords:** msixupload, msixbundle, appxsym, WinAppSdkSignAppxPackageBundle, MSB4036, MSB6006, mspdbcmf.exe, CMF1106, UapAppxPackageBuildMode, StoreUpload, StoreAndSideload, APPX1101, resources.pri +**Keywords:** msixupload, msixbundle, appxsym, WinAppSdkSignAppxPackageBundle, MSB4036, MSB6006, mspdbcmf.exe, CMF1106, UapAppxPackageBuildMode, StoreUpload, StoreAndSideload, APPX1101, resources.pri, Visual Studio, FastLink, PDB, MSIX NuGet **Error Examples:** ``` error MSB4036: The "WinAppSdkSignAppxPackageBundle" task was not found. error MSB6006: "mspdbcmf.exe" have exited, fatal error CMF1106 error APPX1101: Payload contains two or more files with the same destination path 'resources.pri' +error MSB6006: "mspdbcmf.exe" exited with code 1. Visual Studio is required for MSIX packaging. ``` --- @@ -19,6 +20,7 @@ error APPX1101: Payload contains two or more files with the same destination pat - Publishing an MSIX from Visual Studio pollutes `.csproj.user` with `UapAppxPackageBuildMode` - `mspdbcmf.exe` exits with fatal error CMF1106 during symbol package generation - Building a project with WinUI integration tests fails with APPX1101 due to duplicate `resources.pri` +- Attempting to use the `Microsoft.Windows.SDK.BuildTools.MSIX` NuGet package without Visual Studio installed fails due to missing `mspdbcmf.exe` → Check scenarios below for your specific cause @@ -31,6 +33,7 @@ error APPX1101: Payload contains two or more files with the same destination pat - [#5501](https://github.com/microsoft/WindowsAppSDK/issues/5501) - UWP .NET 9 msbuild does not produce .msixupload file (Status: Open) - [#5537](https://github.com/microsoft/WindowsAppSDK/issues/5537) - Publishing MSIX influences future builds via UapAppxPackageBuildMode (Status: Open) - [#5845](https://github.com/microsoft/WindowsAppSDK/issues/5845) - Regression error APPX1101: Duplicate `resources.pri` in WinUI integration tests (Status: Open) +- [#6197](https://github.com/microsoft/WindowsAppSDK/issues/6197) - You should be able to use the MSIX NuGet package without Visual Studio installed (Status: Closed/Fixed) --- @@ -162,6 +165,19 @@ error APPX1101: Payload contains two or more files with the same destination pat --- +### Scenario 6: MSIX NuGet Package Requires Visual Studio Installation + +**Cause:** The `Microsoft.Windows.SDK.BuildTools.MSIX` NuGet package has a hard-coded dependency on `mspdbcmf.exe`, which is typically installed with Visual Studio. This prevents developers using alternative IDEs (e.g., JetBrains Rider) or environments without Visual Studio from creating MSIX packages. +> Source: @wjk in [#6197](https://github.com/microsoft/WindowsAppSDK/issues/6197) + +**Fix:** Update to the latest version of `Microsoft.Windows.SDK.BuildTools.MSIX` (1.8.260101001 or later). This version removes the hard dependency on Visual Studio for MSIX packaging. + +> ✅ Confirmed by: @wjk in [#6197](https://github.com/microsoft/WindowsAppSDK/issues/6197) + +**Verify:** Install the latest version of the NuGet package and run `dotnet publish` on a machine without Visual Studio installed. MSIX package generation should succeed. + +--- + ## ⚠️ Unverified / Community Suggestions > The following are community suggestions that have NOT been officially confirmed. @@ -179,5 +195,5 @@ error APPX1101: Payload contains two or more files with the same destination pat --- -**Updated:** 2026-03-17 | **Confidence:** 0.8 -**Sources:** [#5820](https://github.com/microsoft/WindowsAppSDK/issues/5820), [#5825](https://github.com/microsoft/WindowsAppSDK/issues/5825), [#5501](https://github.com/microsoft/WindowsAppSDK/issues/5501), [#5537](https://github.com/microsoft/WindowsAppSDK/issues/5537), [#5845](https://github.com/microsoft/WindowsAppSDK/issues/5845) \ No newline at end of file +**Updated:** 2026-03-23 | **Confidence:** 0.85 +**Sources:** [#5820](https://github.com/microsoft/WindowsAppSDK/issues/5820), [#5825](https://github.com/microsoft/WindowsAppSDK/issues/5825), [#5501](https://github.com/microsoft/WindowsAppSDK/issues/5501), [#5537](https://github.com/microsoft/WindowsAppSDK/issues/5537), [#5845](https://github.com/microsoft/WindowsAppSDK/issues/5845), [#6197](https://github.com/microsoft/WindowsAppSDK/issues/6197) \ No newline at end of file From bc7bc3a263a021f23035704d57fb4b12f6794997 Mon Sep 17 00:00:00 2001 From: shisan Date: Mon, 30 Mar 2026 12:03:36 +0800 Subject: [PATCH 6/7] Pipeline 20260330_040001: 5 actionable, 3 known issues --- .../tsg_msix_build_publish_output_failures.md | 33 +++++- .../tsg_msix_nuget_package_overview.md | 101 ++++++++++++++++++ .../tsg_msix_project_configuration_tooling.md | 35 ++++-- .../tsg_notifications_push_and_listener.md | 19 +++- 4 files changed, 175 insertions(+), 13 deletions(-) create mode 100644 trouble-shooting-notes/tsg_msix_nuget_package_overview.md diff --git a/trouble-shooting-notes/tsg_msix_build_publish_output_failures.md b/trouble-shooting-notes/tsg_msix_build_publish_output_failures.md index c8ce44a..b654c72 100644 --- a/trouble-shooting-notes/tsg_msix_build_publish_output_failures.md +++ b/trouble-shooting-notes/tsg_msix_build_publish_output_failures.md @@ -1,6 +1,6 @@ # Error: MSIX Build/Publish Output Failures (msixupload, msixbundle, appxsym) -**Keywords:** msixupload, msixbundle, appxsym, WinAppSdkSignAppxPackageBundle, MSB4036, MSB6006, mspdbcmf.exe, CMF1106, UapAppxPackageBuildMode, StoreUpload, StoreAndSideload, APPX1101, resources.pri, Visual Studio, FastLink, PDB, MSIX NuGet +**Keywords:** msixupload, msixbundle, appxsym, WinAppSdkSignAppxPackageBundle, MSB4036, MSB6006, mspdbcmf.exe, CMF1106, UapAppxPackageBuildMode, StoreUpload, StoreAndSideload, APPX1101, resources.pri, Visual Studio, FastLink, PDB, MSIX NuGet, NativeAOT, AOT PDB **Error Examples:** ``` @@ -21,6 +21,7 @@ error MSB6006: "mspdbcmf.exe" exited with code 1. Visual Studio is required for - `mspdbcmf.exe` exits with fatal error CMF1106 during symbol package generation - Building a project with WinUI integration tests fails with APPX1101 due to duplicate `resources.pri` - Attempting to use the `Microsoft.Windows.SDK.BuildTools.MSIX` NuGet package without Visual Studio installed fails due to missing `mspdbcmf.exe` +- appxsym generated by WAP project does not contain exe PDB when publishing with Native AOT → Check scenarios below for your specific cause @@ -34,6 +35,7 @@ error MSB6006: "mspdbcmf.exe" exited with code 1. Visual Studio is required for - [#5537](https://github.com/microsoft/WindowsAppSDK/issues/5537) - Publishing MSIX influences future builds via UapAppxPackageBuildMode (Status: Open) - [#5845](https://github.com/microsoft/WindowsAppSDK/issues/5845) - Regression error APPX1101: Duplicate `resources.pri` in WinUI integration tests (Status: Open) - [#6197](https://github.com/microsoft/WindowsAppSDK/issues/6197) - You should be able to use the MSIX NuGet package without Visual Studio installed (Status: Closed/Fixed) +- [#6208](https://github.com/microsoft/WindowsAppSDK/issues/6208) - appxsym generated by WAP project does not contain exe PDB when publishing with Native AOT (Status: Open) --- @@ -178,12 +180,37 @@ error MSB6006: "mspdbcmf.exe" exited with code 1. Visual Studio is required for --- +### Scenario 7: appxsym Generated by WAP Project Does Not Contain exe PDB When Publishing with Native AOT + +**Cause:** When publishing a WAP project with Native AOT enabled, the generated `.appxsym` file does not include the PDB for the executable file, only for the DLLs. This issue occurs because the Native AOT PDB is not considered as part of the publish content. +> Source: @zhuxb711 in [#6208](https://github.com/microsoft/WindowsAppSDK/issues/6208) + +**Workaround:** +Add the Native AOT PDB to the `.appxsym` file manually by modifying the MSBuild targets: +```xml + + + $(IntermediateOutputPath)\Symbols\ + $(SolutionDir)\Your_AOT_Project_Name\bin\$(Platform)\$(Configuration)\net10.0-windows$(TargetPlatformVersion)\$(RuntimeIdentifier)\native\Your_AOT_Project_Name.pdb + + + + +``` + +> Source: @zhuxb711 in [#6208](https://github.com/microsoft/WindowsAppSDK/issues/6208) + +**Verify:** Check that the `.appxsym` file includes the PDBs for both the executable and DLLs. + +--- + ## ⚠️ Unverified / Community Suggestions > The following are community suggestions that have NOT been officially confirmed. - For #5501: Use the Visual Studio "Create App Packages" wizard as the only reliable method for generating `.msixupload` with multi-platform UWP .NET 9 projects (from @DilanBoskan in #5501) - Add `.csproj.user` to `.gitignore` to prevent `UapAppxPackageBuildMode` pollution from propagating across team members (general recommendation related to #5537) +- For #6208: Consider modifying the MSBuild targets to include AOT PDBs as publish content (from @zhuxb711 in #6208) --- @@ -195,5 +222,5 @@ error MSB6006: "mspdbcmf.exe" exited with code 1. Visual Studio is required for --- -**Updated:** 2026-03-23 | **Confidence:** 0.85 -**Sources:** [#5820](https://github.com/microsoft/WindowsAppSDK/issues/5820), [#5825](https://github.com/microsoft/WindowsAppSDK/issues/5825), [#5501](https://github.com/microsoft/WindowsAppSDK/issues/5501), [#5537](https://github.com/microsoft/WindowsAppSDK/issues/5537), [#5845](https://github.com/microsoft/WindowsAppSDK/issues/5845), [#6197](https://github.com/microsoft/WindowsAppSDK/issues/6197) \ No newline at end of file +**Updated:** 2026-03-30 | **Confidence:** 0.85 +**Sources:** [#5820](https://github.com/microsoft/WindowsAppSDK/issues/5820), [#5825](https://github.com/microsoft/WindowsAppSDK/issues/5825), [#5501](https://github.com/microsoft/WindowsAppSDK/issues/5501), [#5537](https://github.com/microsoft/WindowsAppSDK/issues/5537), [#5845](https://github.com/microsoft/WindowsAppSDK/issues/5845), [#6197](https://github.com/microsoft/WindowsAppSDK/issues/6197), [#6208](https://github.com/microsoft/WindowsAppSDK/issues/6208) \ No newline at end of file diff --git a/trouble-shooting-notes/tsg_msix_nuget_package_overview.md b/trouble-shooting-notes/tsg_msix_nuget_package_overview.md new file mode 100644 index 0000000..9c2b7ba --- /dev/null +++ b/trouble-shooting-notes/tsg_msix_nuget_package_overview.md @@ -0,0 +1,101 @@ +# Overview and Usage of Microsoft.Windows.SDK.BuildTools.MSIX NuGet Package + +**Keywords:** Microsoft.Windows.SDK.BuildTools.MSIX, MSIX packaging, single-project MSIX, MSIX bundles, .winmd harvesting, .appxmanifest rewriting + +**Error Example:** +``` +No specific error message provided. This guide addresses questions and known issues related to the Microsoft.Windows.SDK.BuildTools.MSIX NuGet package. +``` + +--- + +## Quick Match + +**You're seeing this if:** +- You're using the `Microsoft.Windows.SDK.BuildTools.MSIX` NuGet package for MSIX packaging. +- You have questions about its purpose, usage, or compatibility. +- You encounter issues with MSIX bundles or `.msixupload` generation. +- Platform: Windows + +→ Check scenarios below for your specific cause + +--- + +## Related Issues + +- [#5060](https://github.com/microsoft/WindowsAppSDK/issues/5060) - What is Microsoft.Windows.SDK.BuildTools.MSIX? (Status: Closed) + +--- + +## Scenarios & Solutions + +### Scenario 1: Understanding the Purpose of Microsoft.Windows.SDK.BuildTools.MSIX + +**Cause:** Developers are unclear about the purpose and scope of the `Microsoft.Windows.SDK.BuildTools.MSIX` NuGet package. +> Source: @Sergio0694 in [#5060](https://github.com/microsoft/WindowsAppSDK/issues/5060) + +**Details:** +- The package contains all the single-project MSIX tooling that Windows App SDK includes (e.g., MSIX packaging, MRT Core, etc.). +- It was decoupled from Windows App SDK to make it easier to service and to allow UWP .NET 9 projects to leverage it. +- All new improvements for single-project MSIX tooling (e.g., MSIX bundle support, improved `.winmd` harvesting, enhanced `.appxmanifest` rewriting) are being added to this package. + +**Fix:** +No action required. This is informational. + +--- + +### Scenario 2: MSIX Bundle Support + +**Cause:** Developers are unsure about MSIX bundle support in the `Microsoft.Windows.SDK.BuildTools.MSIX` NuGet package. +> Source: @Sergio0694, @snigdha011997 in [#5060](https://github.com/microsoft/WindowsAppSDK/issues/5060) + +**Details:** +- The latest version of the package ([1.2.20250107.1](https://www.nuget.org/packages/Microsoft.Windows.SDK.BuildTools.MSIX/1.2.20250107.1)) already supports MSIX bundles. +- Support for `.msixupload` bundles was planned for release in February 2025. + +**Fix:** +1. Ensure you are using version `1.2.20250107.1` or later of the `Microsoft.Windows.SDK.BuildTools.MSIX` NuGet package. +2. Check for updates to the package for additional features like `.msixupload` support. + +> ✅ Confirmed by: @Sergio0694, @snigdha011997 in issue comments + +**Verify:** Check the generated MSIX bundle or `.msixupload` file in your output directory. + +--- + +### Scenario 3: Compatibility with Windows App SDK + +**Cause:** The `Microsoft.Windows.SDK.BuildTools.MSIX` NuGet package is not yet fully compatible with Windows App SDK. +> Source: @Sergio0694 in [#5060](https://github.com/microsoft/WindowsAppSDK/issues/5060) + +**Details:** +- If you reference both the `Microsoft.Windows.SDK.BuildTools.MSIX` NuGet package and Windows App SDK, Visual Studio may load the build task `.dll` from Windows App SDK instead of the MSIX NuGet package. +- This is expected behavior because Windows App SDK is not yet compatible with the MSIX NuGet package. + +**Fix:** +1. Avoid using the `Microsoft.Windows.SDK.BuildTools.MSIX` NuGet package alongside Windows App SDK until compatibility is officially supported. +2. Compatibility is planned for Windows App SDK 1.8. + +> ✅ Confirmed by: @Sergio0694 in issue comments + +**Verify:** Ensure that the build task `.dll` is loaded from the correct package. + +--- + +## ⚠️ Unverified / Community Suggestions + +> The following are community suggestions that have NOT been officially confirmed. + +- None provided in the issue comments. + +--- + +## References + +- [Microsoft.Windows.SDK.BuildTools.MSIX NuGet Package](https://www.nuget.org/packages/Microsoft.Windows.SDK.BuildTools.MSIX/) +- [#5060](https://github.com/microsoft/WindowsAppSDK/issues/5060) + +--- + +**Updated:** 2026-03-30 | **Confidence:** 0.9 +**Sources:** [#5060](https://github.com/microsoft/WindowsAppSDK/issues/5060) \ No newline at end of file diff --git a/trouble-shooting-notes/tsg_msix_project_configuration_tooling.md b/trouble-shooting-notes/tsg_msix_project_configuration_tooling.md index 9cbc4fb..9fefe72 100644 --- a/trouble-shooting-notes/tsg_msix_project_configuration_tooling.md +++ b/trouble-shooting-notes/tsg_msix_project_configuration_tooling.md @@ -1,6 +1,6 @@ # Error: MSIX Project Configuration & Build Tools Issues -**Keywords:** EnableMsixTooling, Microsoft.Windows.SDK.BuildTools.MSIX, AppxOSMinVersionReplaceManifestVersion, AppxOSMaxVersionTestedReplaceManifestVersion, mspdbcmf.exe, wapproj, single-project MSIX, NuGet, Visual Studio, unpackaged, resources.pri, DebugType, APPX1101, APPXUPLOAD, buildTransitive, CustomBeforeMicrosoftCommonTargets, dotnet msbuild, symbols package +**Keywords:** EnableMsixTooling, Microsoft.Windows.SDK.BuildTools.MSIX, AppxOSMinVersionReplaceManifestVersion, AppxOSMaxVersionTestedReplaceManifestVersion, mspdbcmf.exe, wapproj, single-project MSIX, NuGet, Visual Studio, unpackaged, resources.pri, DebugType, APPX1101, APPXUPLOAD, buildTransitive, CustomBeforeMicrosoftCommonTargets, dotnet msbuild, symbols package, PublishError, MetadataNotFound **Error Examples:** ``` @@ -11,6 +11,7 @@ error: APPX1101 - Payload contains two or more files with the same destination p error: Missing APPXUPLOAD file for store submission error: CustomBeforeMicrosoftCommonTargets reassignment breaks MSIX build tools warning: Path to `mspdbcmf.exe` could not be found. A symbols package will not be generated +error: Metadata file 'Test.WinUI.dll' could not be found during Publish ``` --- @@ -26,6 +27,7 @@ warning: Path to `mspdbcmf.exe` could not be found. A symbols package will not b - Unable to generate `.appxupload` files for store submission - MSIX build tools fail due to `CustomBeforeMicrosoftCommonTargets` reassignment - Building MSIX packages using `dotnet msbuild` or `dotnet publish` fails to generate symbols package due to missing `mspdbcmf.exe` +- Publishing unpackaged apps fails with "Metadata file 'Test.WinUI.dll' could not be found" → Check scenarios below for your specific cause @@ -43,6 +45,7 @@ warning: Path to `mspdbcmf.exe` could not be found. A symbols package will not b - [#5811](https://github.com/microsoft/WindowsAppSDK/issues/5811) - CustomBeforeMicrosoftCommonTargets breaks MSIX build tools (Status: Open) - [#5826](https://github.com/microsoft/WindowsAppSDK/issues/5826) - APPX1101 errors after upgrading to WindowsAppSDK 1.8 (Status: Open) - [#5102](https://github.com/microsoft/WindowsAppSDK/issues/5102) - Missing symbols package when building in dotnet msbuild workflow (Status: Open) +- [#3065](https://github.com/microsoft/WindowsAppSDK/issues/3065) - Publish error: Metadata file 'Test.WinUI.dll' not found (Status: Open) --- @@ -98,7 +101,25 @@ warning: Path to `mspdbcmf.exe` could not be found. A symbols package will not b --- -### Scenario 3: DebugType=embedded Generates Misleading mspdbcmf.exe Error +### Scenario 3: Publish Error — Metadata File 'Test.WinUI.dll' Not Found + +**Cause:** Publishing fails when the reference library project contains the `Microsoft.WindowsAppSDK` package. This occurs due to incorrect project configuration or MSIX packaging being enabled for an unpackaged app. +> Source: @Scottj1s in [#3065](https://github.com/microsoft/WindowsAppSDK/issues/3065) + +**Fix:** +1. Disable MSIX packaging for unpackaged apps by adding the following to the `.csproj` file: + ```xml + + None + + ``` +2. Ensure the correct "Publish" menu option is selected in Visual Studio. For unpackaged apps, use the "Publish" menu item, not "Package and Publish." + +**Verify:** Publish completes without errors, and the application runs successfully. + +--- + +### Scenario 4: DebugType=embedded Generates Misleading mspdbcmf.exe Error **Cause:** When `DebugType=embedded` is set in the project file, the MSIX build tools incorrectly emit a warning about `mspdbcmf.exe` not being found, even though it is not required in this configuration. > Source: @Scottj1s in [#5262](https://github.com/microsoft/WindowsAppSDK/issues/5262) @@ -127,7 +148,7 @@ Add a dummy `PDBPayload` to suppress the warning: --- -### Scenario 4: APPXUPLOAD-Bundle Creation Unsupported Pre-1.8 +### Scenario 5: APPXUPLOAD-Bundle Creation Unsupported Pre-1.8 **Cause:** The single-project MSIX tooling did not support `.appxupload` or `.msixupload` bundle creation prior to Windows App SDK 1.8. > Source: @DarranRowe in [#5675](https://github.com/microsoft/WindowsAppSDK/issues/5675) @@ -138,7 +159,7 @@ Add a dummy `PDBPayload` to suppress the warning: --- -### Scenario 5: APPX1101 Errors Due to Duplicate Files in Payload +### Scenario 6: APPX1101 Errors Due to Duplicate Files in Payload **Cause:** Duplicate files in the MSIX package payload, often caused by conflicting versions of dependencies or incorrect project configurations. > Source: @manodasanW in [#5826](https://github.com/microsoft/WindowsAppSDK/issues/5826) @@ -149,7 +170,7 @@ Add a dummy `PDBPayload` to suppress the warning: --- -### Scenario 6: CustomBeforeMicrosoftCommonTargets Reassignment Breaks MSIX Build Tools +### Scenario 7: CustomBeforeMicrosoftCommonTargets Reassignment Breaks MSIX Build Tools **Cause:** The `CustomBeforeMicrosoftCommonTargets` MSBuild property is reassigned without preserving the original value, causing the MSIX build tools to fail. > Source: @Scottj1s in [#5811](https://github.com/microsoft/WindowsAppSDK/issues/5811) @@ -193,5 +214,5 @@ Add a dummy `PDBPayload` to suppress the warning: --- -**Updated:** 2026-03-17 | **Confidence:** 0.8 -**Sources:** [#6197](https://github.com/microsoft/WindowsAppSDK/issues/6197), [#3718](https://github.com/microsoft/WindowsAppSDK/issues/3718), [#5598](https://github.com/microsoft/WindowsAppSDK/issues/5598), [#5586](https://github.com/microsoft/WindowsAppSDK/issues/5586), [#5262](https://github.com/microsoft/WindowsAppSDK/issues/5262), [#5675](https://github.com/microsoft/WindowsAppSDK/issues/5675), [#5626](https://github.com/microsoft/WindowsAppSDK/issues/5626), [#5811](https://github.com/microsoft/WindowsAppSDK/issues/5811), [#5826](https://github.com/microsoft/WindowsAppSDK/issues/5826), [#5102](https://github.com/microsoft/WindowsAppSDK/issues/5102) \ No newline at end of file +**Updated:** 2026-03-30 | **Confidence:** 0.8 +**Sources:** [#6197](https://github.com/microsoft/WindowsAppSDK/issues/6197), [#3718](https://github.com/microsoft/WindowsAppSDK/issues/3718), [#5598](https://github.com/microsoft/WindowsAppSDK/issues/5598), [#5586](https://github.com/microsoft/WindowsAppSDK/issues/5586), [#5262](https://github.com/microsoft/WindowsAppSDK/issues/5262), [#5675](https://github.com/microsoft/WindowsAppSDK/issues/5675), [#5626](https://github.com/microsoft/WindowsAppSDK/issues/5626), [#5811](https://github.com/microsoft/WindowsAppSDK/issues/5811), [#5826](https://github.com/microsoft/WindowsAppSDK/issues/5826), [#5102](https://github.com/microsoft/WindowsAppSDK/issues/5102), [#3065](https://github.com/microsoft/WindowsAppSDK/issues/3065) \ No newline at end of file diff --git a/trouble-shooting-notes/tsg_notifications_push_and_listener.md b/trouble-shooting-notes/tsg_notifications_push_and_listener.md index c6ebc21..bf8ada4 100644 --- a/trouble-shooting-notes/tsg_notifications_push_and_listener.md +++ b/trouble-shooting-notes/tsg_notifications_push_and_listener.md @@ -1,6 +1,6 @@ # Notification Issues — Push Notifications, Progress Data, and UserNotificationListener -**Keywords:** AppNotification, push notification, unpackaged, COMException, 0x80070490, Element not found, UserNotificationListener, NotificationChanged, AppNotificationProgressData, IsIndeterminate, indeterminate progress bar, toast notification, BadgeNotificationManager, REGDB_E_CLASSNOTREG, ScheduledToastNotification, WNS, PFN, Azure AppId, 403 +**Keywords:** AppNotification, push notification, unpackaged, COMException, 0x80070490, Element not found, UserNotificationListener, NotificationChanged, AppNotificationProgressData, IsIndeterminate, indeterminate progress bar, toast notification, BadgeNotificationManager, REGDB_E_CLASSNOTREG, ScheduledToastNotification, WNS, PFN, Azure AppId, 403, Self-Contained, Runtime package, Microsoft.WindowsAppRuntime.Insights.Resource.dll **Error Example:** ``` @@ -20,6 +20,7 @@ System.Runtime.InteropServices.COMException (0x80070490): Element not found - `UserNotificationListener.NotificationChanged` throws `COMException` in unpackaged apps - BadgeNotificationManager.Current throws `COMException REGDB_E_CLASSNOTREG` - Missing API for scheduling toast notifications in Windows App SDK +- `AppNotificationManager.Default.Register()` throws `COMException` in a self-contained unpackaged app - Platform: Windows App SDK, WinUI 3, unpackaged or self-contained apps → Check scenarios below for your specific cause @@ -34,6 +35,7 @@ System.Runtime.InteropServices.COMException (0x80070490): Element not found - [#5050](https://github.com/microsoft/WindowsAppSDK/issues/5050) — Feature Request: Schedule toast notifications (Status: Open) - [#5307](https://github.com/microsoft/WindowsAppSDK/issues/5307) — COMException REGDB_E_CLASSNOTREG from BadgeNotificationManager (Status: Closed — resolved in 1.7.1) - [#6301](https://github.com/microsoft/WindowsAppSDK/issues/6301) — PFN-to-Azure-AppId mapping for WNS push notifications returns 403 (Status: Closed — resolved via email mapping) +- [#6071](https://github.com/microsoft/WindowsAppSDK/issues/6071) — Cannot register AppNotification callback without installing Runtime package for Self-Contained Unpackaged app (Status: Open) --- @@ -174,6 +176,17 @@ notifier.AddToSchedule(scheduledToast); --- +### Scenario 7: Cannot Register AppNotification Callback Without Installing Runtime Package for Self-Contained Unpackaged App + +**Cause:** In a self-contained unpackaged app, calling `AppNotificationManager.Default.Register()` throws a `COMException` with the error message: "The specified module could not be found. Unable to load resource dll. Microsoft.WindowsAppRuntime.Insights.Resource.dll." This occurs despite the app being self-contained and not requiring the runtime package. +> Source: @aepot in [#6071](https://github.com/microsoft/WindowsAppSDK/issues/6071) + +**Status:** 🔄 **Known Issue** — No confirmed solution yet. + +**Workaround:** Install the **Microsoft.WindowsAppSDK.Runtime** package manually, even for self-contained apps. + +--- + ## ⚠️ Unverified / Community Suggestions > The following are community suggestions that have NOT been officially confirmed. @@ -192,5 +205,5 @@ notifier.AddToSchedule(scheduledToast); --- -**Updated:** 2026-03-20 | **Confidence:** 0.8 -**Sources:** #334, #2231, #6172, #5050, #5307, #6301 \ No newline at end of file +**Updated:** 2026-03-30 | **Confidence:** 0.8 +**Sources:** #334, #2231, #6172, #5050, #5307, #6301, #6071 \ No newline at end of file From c0646ef014956d559db2ccddcb1450dced61a1b3 Mon Sep 17 00:00:00 2001 From: shisan Date: Mon, 6 Apr 2026 12:01:31 +0800 Subject: [PATCH 7/7] Pipeline 20260406_040001: 5 actionable, 5 known issues --- .../tsg_msix_build_publish_output_failures.md | 2 +- .../tsg_resources_mrt_localization.md | 23 ++++++++++++++++--- 2 files changed, 21 insertions(+), 4 deletions(-) diff --git a/trouble-shooting-notes/tsg_msix_build_publish_output_failures.md b/trouble-shooting-notes/tsg_msix_build_publish_output_failures.md index b654c72..ce1c61b 100644 --- a/trouble-shooting-notes/tsg_msix_build_publish_output_failures.md +++ b/trouble-shooting-notes/tsg_msix_build_publish_output_failures.md @@ -222,5 +222,5 @@ Add the Native AOT PDB to the `.appxsym` file manually by modifying the MSBuild --- -**Updated:** 2026-03-30 | **Confidence:** 0.85 +**Updated:** 2026-04-06 | **Confidence:** 0.85 **Sources:** [#5820](https://github.com/microsoft/WindowsAppSDK/issues/5820), [#5825](https://github.com/microsoft/WindowsAppSDK/issues/5825), [#5501](https://github.com/microsoft/WindowsAppSDK/issues/5501), [#5537](https://github.com/microsoft/WindowsAppSDK/issues/5537), [#5845](https://github.com/microsoft/WindowsAppSDK/issues/5845), [#6197](https://github.com/microsoft/WindowsAppSDK/issues/6197), [#6208](https://github.com/microsoft/WindowsAppSDK/issues/6208) \ No newline at end of file diff --git a/trouble-shooting-notes/tsg_resources_mrt_localization.md b/trouble-shooting-notes/tsg_resources_mrt_localization.md index e2a5422..50fc0d1 100644 --- a/trouble-shooting-notes/tsg_resources_mrt_localization.md +++ b/trouble-shooting-notes/tsg_resources_mrt_localization.md @@ -1,6 +1,6 @@ # Error: "COMException: NamedResource Not Found" / PrimaryLanguageOverride Not Working — MRT Resource Loading -**Keywords:** ResourceLoader, GetString, COMException, NamedResource Not Found, PrimaryLanguageOverride, unpackaged, localization, x:Uid, MRTCore, Resources.resw, dot in key, signing projection, resources.pri, MrmGetFilePathFromName, ResourceManager, ResourceLoaderTest, MICROSOFT_WINDOWSAPPRUNTIME_BASE_DIRECTORY, PublishSingleFile +**Keywords:** ResourceLoader, GetString, COMException, NamedResource Not Found, PrimaryLanguageOverride, unpackaged, localization, x:Uid, MRTCore, Resources.resw, dot in key, signing projection, resources.pri, MrmGetFilePathFromName, ResourceManager, ResourceLoaderTest, MICROSOFT_WINDOWSAPPRUNTIME_BASE_DIRECTORY, PublishSingleFile, MSIX, AppxBundle, ManifestLanguages **Error Example:** ``` @@ -25,6 +25,7 @@ System.IO.FileNotFoundException: Unable to find the specified file. - `MrmGetFilePathFromName` reports `ERROR_FILE_NOT_FOUND` when `resources.pri` is missing - `ResourceLoader` crashes with `System.IO.FileNotFoundException` in unpackaged apps - Launching one WinAppSDK app from another fails due to `MICROSOFT_WINDOWSAPPRUNTIME_BASE_DIRECTORY` +- Localization fails after packaging into MSIX bundles in WASDK 1.8 → Check scenarios below for your specific cause @@ -38,6 +39,7 @@ System.IO.FileNotFoundException: Unable to find the specified file. - [#5814](https://github.com/microsoft/WindowsAppSDK/issues/5814) — MrmGetFilePathFromName now reports error when `resources.pri` is missing (Status: Closed) - [#5832](https://github.com/microsoft/WindowsAppSDK/issues/5832) — Upgrading to v1.8 breaks ResourceLoader in unpackaged apps (Status: Open) - [#5987](https://github.com/microsoft/WindowsAppSDK/issues/5987) — MRTCore using MICROSOFT_WINDOWSAPPRUNTIME_BASE_DIRECTORY breaks launching one WinAppSDK app from another (Status: Open) +- [#5817](https://github.com/microsoft/WindowsAppSDK/issues/5817) — Localization fails after packaging into MSIX bundles in WASDK 1.8 (Status: Open) --- @@ -172,6 +174,21 @@ Manually rename `.pri` to `resources.pri` after every build: --- +### Issue: Localization Fails After Packaging into MSIX Bundles in WASDK 1.8 + +**Cause:** When packaging applications into MSIX bundles using WASDK 1.8, only one language is included in the bundle, and the `ManifestLanguages` list is reduced to a single language. This causes localization to fail after installation. +> Source: @BigHeadDev, @JulienTheron, @torum in [#5817](https://github.com/microsoft/WindowsAppSDK/issues/5817) + +**Status:** Open + +**Workaround:** +- Set `AppxBundle` to `Never` in your project settings to avoid creating a bundle. + > Source: @JulienTheron in [#5817](https://github.com/microsoft/WindowsAppSDK/issues/5817) +- Manually create the bundle using `MakeAppx` to ensure all languages are included. + > Source: @JulienTheron in [#5817](https://github.com/microsoft/WindowsAppSDK/issues/5817) + +--- + ## ⚠️ Unverified / Community Suggestions > The following are community suggestions that have NOT been officially confirmed. @@ -189,5 +206,5 @@ Manually rename `.pri` to `resources.pri` after every build: --- -**Updated:** 2026-03-17 | **Confidence:** 0.8 -**Sources:** #6247, #1687, #3705, #5814, #5832, #5987 \ No newline at end of file +**Updated:** 2026-04-06 | **Confidence:** 0.8 +**Sources:** #6247, #1687, #3705, #5814, #5832, #5987, #5817 \ No newline at end of file