Improved APIs for Picker/Dialog classes that implement IInitializeWithWindow

[angelazhangmsft]

The team is looking at improving the API pattern for several picker/dialog classes that currently require interop code with IInitializeWithWindow. We would love to hear your feedback on the proposal below!

Summary

Several WinRT classes (e.g. FileOpenPicker, FolderPicker, MessageDialog) require a CoreWindow to call certain methods, typically to display a UI. However, CoreWindow is not supported in desktop apps so these WinRT classes cannot be used in desktop apps by default (using the same API usage pattern as in UWP). Some of the classes implement the IInitializeWithWindow interface, which enables using these APIs in desktop apps but requires interop with IInitializeWithWindow, which is not developer-friendly or discoverable.

See issues: microsoft/microsoft-ui-xaml#2716, #1063

Current API pattern

C# (Current API pattern)

// Need to get the hwnd (“window” is a pointer to a WinUI Window object). 
// WinRT.Interop namespace is provided by C#/WinRT projected interop wrappers for .NET 5+
var hwnd = WinRT.Interop.WindowNative.GetWindowHandle(window);

var picker = new Windows.Storage.Pickers.FolderPicker();

// Need to initialize the picker object with the hwnd / IInitializeWithWindow 
WinRT.Interop.InitializeWithWindow.Initialize(picker, hwnd);

// Now we can use the picker object as normal
picker.FileTypeFilter.Add("*");
var file = await picker.PickSingleFolderAsync();

C++ (Current API pattern)

#include <shobjidl.h>
#include <winrt/windows.storage.pickers.h>

// Need to get the hwnd (“this” is a pointer to a WinUI Window object)
auto windowNative{ this->try_as<::IWindowNative>() };
HWND hWnd{ 0 };
windowNative->get_WindowHandle(&hWnd);

auto picker = winrt::Windows::Storage::Pickers::FileOpenPicker();

// Need to initialize the picker object with the hwnd / IInitializeWithWindow
picker.as<IInitializeWithWindow>()->Initialize(hwnd);

// Now we can use the picker object as normal
picker.FileTypeFilter().Append(L".jpg");
auto file = co_await picker.PickSingleFileAsync();

Proposed Solution

Introduce new WinAppSDK 1.x APIs that support WindowId parameter

These new APIs would be available with the Windows App SDK and wrap underlying Windows APIs. For example, a Microsoft.Windows.Storage.Pickers.FolderPicker that wraps Windows.Storage.Pickers.FolderPicker but adds a required WindowId-based constructor.

There are existing CSWinRT-generated APIs in the WinRT.Interop namespace that make WindowId from various types easy to get, such as from a Xaml Window and AppWindow. These can be used to call the picker/dialog API with the correct WindowId value. We can retrieve a Microsoft.UI.WindowId object from the AppWindow APIs, passing in whichever framework is being used (WPF, Winforms, HWND, etc), and construct the picker/dialog object with the WindowId parameter.

The following APIs fall under this pattern:

• Windows.Storage.Pickers.FileOpenPicker
• Windows.Storage.Pickers.FileSavePicker
• Windows.Storage.Pickers.FolderPicker
• Windows.Devices.Enumeration.DevicePicker
• Windows.Graphics.Capture.GraphicsCapturePicker
• Windows.UI.StartScreen.SecondaryTile
• Windows.Services.Store.StoreContext
• Windows.UI.Popups.MessageDialog
• Windows.UI.Popups.PopupMenu

C# (Proposed API pattern)

// First retrieve WindowId object using Windowing APIs. This currently requires some interop code with the hwnd. 
// Note: "window" is a pointer to a Microsoft.UI.Xaml.Window object.
Microsoft.UI.WindowId windowId;
var hwnd = WinRT.Interop.WindowNative.GetWindowHandle(window); 
Microsoft.UI.Win32Interop.GetWindowIdFromWindow(hwnd, out windowId);

// Initialize picker with new lifted API
var picker = new Microsoft.Windows.Storage.Pickers.FolderPicker(windowId);

// Now we can use the picker object as normal
picker.FileTypeFilter.Add("*");
var file = await picker.PickSingleFolderAsync();

Note: Long term, Microsoft.UI.WindowId would be a property of the Window object, which would simplify the code to obtain the WindowId (eliminating the requirement to obtain an hwnd). This would simplify the picker initialization code to something like:

// this is a pointer to the Window object
var picker = new Microsoft.Windows.Storage.Pickers.FolderPicker(this.WindowId);

Alternative Solutions

Introduce new WinAppSDK 1.x APIs that support parameter-less constructors

Ideally, we would support parameter-less constructors in addition to supporting explicit WindowId (the above Proposed Solution).

C# (Proposed API pattern)

// First retrieve WindowId object using Windowing APIs. This currently requires some interop code with the hwnd. 
// Note: "window" is a pointer to a Microsoft.UI.Xaml.Window object.
Microsoft.UI.WindowId windowId;
var hwnd = WinRT.Interop.WindowNative.GetWindowHandle(window); 
Microsoft.UI.Win32Interop.GetWindowIdFromWindow(hwnd, out windowId);

// Initialize picker with parameter-less constructor
var picker = new Microsoft.Windows.Storage.Pickers.FolderPicker();

Possible approaches and considerations:

• Can the default constructor do some default lookup mechanism?
• Since a majority of apps are single window, should we provide default behavior with a parameter-less constructor, and fallback if the “default” window cannot be determined?
• One idea is adding a global "ObtainHwnd" method that all developers implement. Developers will have to call that themselves and define their global hwnd in their app somewhere. All subsequent calls automatically pull the hwnd from there.

Open Questions

• Should we duplicate the existing namespaces (e.g., Window.Storage.Pickers.FolderPicker and Microsoft.Windows.Storage.Pickers.FolderPicker), or should we change these class names? Duplicating the class names may result in confusion with Intellisense since both classes will show up.

[JaiganeshKumaran]

Related to #1063.

[terrycox]

While you're improving FolderPicker, please consider relaxing the SuggestedStartLocation from the PickerLocationId enumeration to any folder location. What made sense in the sandbox doesn't work so well in the Win32 world.

[Gavin-Williams]

I've always wondered why they never provided options to break out of the default folders. The Sandbox concept doesn't preclude navigation to any folder. That's merely a contract with the user that can be okayed at install.

[JaiganeshKumaran]

This limitation isn't ideal even under the sandbox.

[JaiganeshKumaran]

I don't see much point in duplicating system file pickers as they're UI framework agnostic and currently WindowsAppSDK also force-installs WinUI 3, making it unusable if WinUI 3 isn't required unless you're willing to include it without using it. While the system APIs could be updated themselves, it won't be backward compatible and the Initialize method already exists in the object, just not accessible from the projected world. Language projections could make the Initialize method directly avoid without needing to query for a classic COM interface or use the interop wrapper. Ideally, I want to the pickers and other UI objects to work directly just like in UWP, it can obtain the window ID of the currently focused window in the process.

[charlesroddie]

The API is good here but much more pressing than the current API not being clean is that it doesn't work at all in AppContainer, meaning that pickers cannot be used! microsoft/microsoft-ui-xaml#9557 Does the new approach potentially fix this @angelazhangmsft ?