ShellExecute with PWA Parameters in Windows: Complete Guide

When trying to open a Progressive Web App (PWA) with path and query parameters using ShellExecute in Windows, you’re encountering a common limitation of this API with installed PWAs. The issue occurs because ShellExecute doesn’t properly handle URI activation for installed PWAs, while LaunchUriAsync is designed specifically for this purpose. When your PWA is uninstalled, the browser handles the URI directly, allowing parameters to work correctly, but the installed PWA needs special handling to process these parameters.

Contents

• Understanding Progressive Web Apps in Windows
• ShellExecute API Limitations with PWAs
• The Root Cause: Parameter Handling Differences
• Solution: Using LaunchUriAsync Instead of ShellExecute
• Implementing Parameter Handling in Your PWA
• Best Practices for PWA Deep Linking

Understanding Progressive Web Apps in Windows

Progressive Web Apps are web applications that can be installed on a user’s device and behave similarly to native applications. In Windows, PWAs are treated as first-class applications that can be launched from the Start menu, taskbar, or even through system APIs like ShellExecute. When you install a PWA, Windows creates a special container that manages the application’s lifecycle and activation.

The key difference between a PWA running in the browser versus installed is how Windows handles URI activation. When your PWA runs in the browser, the browser’s engine processes the entire URI including path and query parameters. However, when installed as a PWA, Windows needs to use a different activation mechanism that might not preserve all URL components by default.

PWAs in Windows benefit from features like offline functionality, push notifications, and app-like behavior. But these features come with different activation semantics that developers need to understand when implementing deep linking functionality.

ShellExecute API Limitations with PWAs

The ShellExecute function has been a staple of Windows development for decades, allowing applications to launch files, URLs, and perform system operations. However, this API wasn’t specifically designed with Progressive Web Apps in mind.

According to Microsoft’s documentation, ShellExecute primarily focuses on file operations and basic URL launching. When you use ShellExecute to open a PWA like YouTube with parameters, the function successfully launches the application but doesn’t guarantee that the full URI with parameters gets passed to the installed PWA. The API might strip query parameters or fail to route the activation properly to the PWA’s activation handler.

// Traditional ShellExecute approach - doesn't work well with installed PWAs
ShellExecute(NULL, "open", "youtube.com/watch?v=123", NULL, NULL, SW_SHOWNORMAL);

The problem becomes more apparent when comparing how browsers versus installed PWAs handle URI activation. Browsers have sophisticated URI routing mechanisms that preserve all URL components, while installed PWAs rely on Windows’ URI activation system which may not forward parameters in the same way.

The Root Cause: Parameter Handling Differences

Why do parameters work when the PWA is uninstalled but not when installed? The answer lies in how Windows activates different types of applications.

When your PWA is uninstalled, Windows treats it as a web application and passes the full URI to the default browser. The browser then processes the URI, extracts parameters, and navigates to the appropriate content. This is the behavior you’re experiencing as “working correctly.”

However, when the PWA is installed, Windows activates it as a standalone application using the Windows Runtime (WinRT) activation system. The PWA receives an activation event, but this event might not contain the complete URI with all parameters intact. The PWA needs to be specifically designed to handle this activation and extract the necessary information.

The Launch Handler API mentioned in Chrome’s documentation can help here. This API allows PWAs to control how they handle incoming navigation requests, which is crucial for maintaining parameter functionality in installed PWAs. Without proper navigation handling, the PWA might launch but not navigate to the specified content.

Solution: Using LaunchUriAsync Instead of ShellExecute

For launching Progressive Web Apps with parameters, Microsoft recommends using Windows.System.Launcher.LaunchUriAsync instead of ShellExecute. This API is specifically designed to handle URI activation and parameter passing to UWP applications, including PWAs.

Here’s how to use LaunchUriAsync in your Windows application:

#include <windows.h>
#include <winrt/Windows.System.h>

void LaunchPWAWithParameters() {
 try {
 // Create the full URI with parameters
 winrt::Windows::Foundation::Uri uri(L"youtube.com/watch?v=123");
 
 // Use LaunchUriAsync to launch the PWA with parameters
 auto launchOperation = winrt::Windows::System::Launcher::LaunchUriAsync(uri);
 
 // Handle the result
 launchOperation.Completed([](auto&& sender, auto&& args) {
 if (args.Status() == winrt::Windows::Foundation::AsyncStatus::Completed) {
 if (args.Results()) {
 // PWA launched successfully
 } else {
 // PWA launch failed
 }
 }
 });
 }
 catch (const winrt::hresult_error& ex) {
 // Handle any errors
 }
}

The key advantage of LaunchUriAsync is that it properly forwards the URI to the installed PWA, allowing the PWA to handle activation and parameter processing. This method ensures that both path and query parameters are preserved and can be processed by the PWA’s activation handler.

According to Microsoft’s documentation on URI activation, when a PWA is launched with parameters using LaunchUriAsync, it receives an activation event that contains the complete URI. The PWA can then extract the parameters and navigate to the appropriate content.

Implementing Parameter Handling in Your PWA

To properly handle parameters in your Progressive Web App, you need to implement activation event handling. In JavaScript, this can be done by listening for the ‘launch’ event and extracting the parameters from the event object.

Here’s how to implement proper parameter handling in your PWA:

// In your PWA's main JavaScript file
window.addEventListener('launch', (event) => {
 // Extract the launch URI
 const launchUri = event.detail.uri;
 
 if (launchUri) {
 // Parse the URI to get parameters
 const url = new URL(launchUri);
 const path = url.pathname;
 const params = new URLSearchParams(url.search);
 
 // Navigate to the appropriate content based on parameters
 if (params.has('v')) {
 // Handle YouTube video ID parameter
 const videoId = params.get('v');
 navigateToVideo(videoId);
 } else if (params.has('playlist')) {
 // Handle playlist parameter
 const playlistId = params.get('playlist');
 navigateToPlaylist(playlistId);
 }
 // Add more parameter handling as needed
 }
});

// Function to navigate based on parameters
function navigateToVideo(videoId) {
 // Your implementation to navigate to the specific video
 console.log('Navigating to video:', videoId);
 // Update the UI or perform navigation
}

function navigateToPlaylist(playlistId) {
 // Your implementation to navigate to the specific playlist
 console.log('Navigating to playlist:', playlistId);
 // Update the UI or perform navigation
}

Additionally, you should register your PWA to handle specific URI schemes if needed. This can be done in your web app manifest file:

{
 "name": "Your PWA",
 "start_url": "/",
 "display": "standalone",
 "icons": [...],
 "launch_handler": {
 "client_mode": "navigate-existing"
 }
}

The Launch Handler API configuration helps control how your PWA handles incoming navigation requests. Setting client_mode to “navigate-existing” ensures that the PWA handles the navigation in its existing context rather than creating a new window.

Best Practices for PWA Deep Linking

When implementing deep linking in Progressive Web Apps for Windows, consider these best practices:

1. Use meaningful parameters: Design your URL structure with clear, descriptive parameters that make sense for your application’s functionality.

2. Implement proper error handling: Not all launches will contain valid parameters. Ensure your PWA gracefully handles cases where expected parameters are missing or invalid.

3. Test both installed and browser scenarios: Always test your deep linking functionality both when the PWA is installed and when it runs in the browser to ensure consistent behavior.

4. Use consistent URI schemes: If your PWA needs to handle custom URI schemes, register them properly and ensure they follow standard conventions.

5. Document your deep linking: Provide clear documentation for users and developers about how to launch your PWA with specific parameters.

6. Consider fallback mechanisms: If parameter handling fails, provide a fallback to the default view or a helpful error message.

7. Test with different launch methods: Verify that your PWA works correctly when launched from various contexts - Start menu, taskbar, URI activation, etc.

8. Handle activation events properly: Ensure your PWA can handle activation events both on launch and when returning from the background.

By implementing these best practices and using the correct activation methods like LaunchUriAsync, you can ensure that your Progressive Web App properly handles parameters and provides a seamless user experience on Windows.

Sources

1. Microsoft ShellExecute Documentation — Windows API reference for ShellExecute function: https://learn.microsoft.com/en-us/windows/win32/api/shellapi/nf-shellapi-shellexecutea
2. Microsoft LaunchUriAsync Documentation — UWP API for launching applications with URIs: https://learn.microsoft.com/en-us/windows/uwp/launch-resume/launch-app-with-uri
3. Chrome Launch Handler API — Progressive Web App navigation management documentation: https://developer.chrome.com/docs/capabilities/pwa-navigation-management
4. Microsoft URI Activation Documentation — Handling URI activation in Windows applications: https://learn.microsoft.com/en-us/windows/uwp/launch-resume/handle-uri-activation

Conclusion

The challenge of passing parameters to installed Progressive Web Apps using ShellExecute in Windows stems from fundamental differences in how Windows activates browser-based versus installed applications. While ShellExecute works for basic URL launching, it doesn’t properly preserve and forward URI parameters to installed PWAs. The correct approach is to use Windows.System.Launcher.LaunchUriAsync, which is specifically designed for URI activation and parameter passing. Additionally, your PWA must implement proper activation event handling to process these parameters correctly. By understanding these concepts and implementing the right APIs and event handlers, you can ensure that your PWA works seamlessly with parameters whether it’s installed running as a standalone application or accessed through the browser.