Tsg update/20260320

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: Closed)
+
+---
+
+## 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<string> Win32GetActivationFiles()
+   {
+       var files = new List<string>(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)

trouble-shooting-notes/tsg_api_gaps_unpackaged_support.md

@@ -0,0 +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
+- 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%\<publisher>\<product>` |
+| `ApplicationData.LocalFolder` | `%LOCALAPPDATA%\<publisher>\<product>` |
+| `ApplicationData.MachineFolder` | `%ProgramData%\<publisher>\<product>` |
+| `ApplicationData.TemporaryFolder` | `%LOCALAPPDATA%\Temp` |
+| `ApplicationData.LocalSettings` | `HKCU\SOFTWARE\<publisher>\<product>` |
+
+**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
+<uap:Extension Category="windows.fileTypeAssociation">
+    <uap:FileTypeAssociation Name="textfiles">
+        <uap:SupportedFileTypes>
+            <uap:FileType>.txt</uap:FileType>
+            <uap:FileType>.md</uap:FileType>
+            <uap:FileType>.log</uap:FileType>
+            <uap:FileType>.csv</uap:FileType>
+            <!-- Add more as needed -->
+        </uap:SupportedFileTypes>
+    </uap:FileTypeAssociation>
+</uap:Extension>
+```
+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