How to handle URI activation (XAML)

An app can register to become the default handler for a certain Uniform Resource Identifier (URI) scheme name. Both desktop apps and Windows Runtime apps can register to be a default handler for a URI scheme name. If the user chooses your app as the default handler for a URI scheme name, your app will be activated every time that type of URI is launched.

We recommend that you only register for a URI scheme name if you expect to handle all URI launches for that type of URI scheme. If you do choose to register for a URI scheme name, you must provide the end user with the functionality that is expected when your app is activated for that URI scheme. For example, an app that registers for the mailto: URI scheme name should open to a new e-mail message so that the user can compose a new e-mail. For more info on URI associations, see Guidelines and checklist for file types and URIs.

These steps show how to register for a custom URI scheme name, alsdk://, and how to activate your app when the user launches a alsdk:// URI.

Note  

In Windows Phone Store apps, certain URIs and file extensions are reserved for use by built-in apps and the operating system. Attempts to register your app with a reserved URI or file extension will be ignored. For more information, see the list on this page.

Instructions

Step 1: Specify the extension point in the package manifest

The app receives activation events only for the URI scheme names listed in the package manifest. Here's how you indicate that your app handles the alsdkURI scheme name.

1. Double click to open package.appxmanifest in Solution Explorer.

   Here is a brief description of each of the fields that you may fill in the package manifest:

2. Select the Declarations tab.

3. Select Protocol from the drop-down list and click Add.

4. Enter alsdk as the Name.

5. Enter “images\Icon.png” as the Logo.

6. Press Ctrl+S to save the change to package.appxmanifest.

This adds an Extension element like this one to the package manifest. The windows.protocol category indicates that the app handles the alsdk URI scheme name.

<Package xmlns="https://schemas.microsoft.com/appx/2010/manifest" xmlns:m2="https://schemas.microsoft.com/appx/2013/manifest">
   <Applications>
      <Application Id="AutoLaunch.App">
         <Extensions>
            <Extension Category="windows.protocol">
               <Protocol Name="alsdk" m2:DesiredView="useLess"/>
               <Logo>images\logo.png</Logo>                                     
               <DisplayName>SDK Sample URI Scheme</DisplayName>
            </Extension>                      
         </Extensions>
      </Application>
   </Applications>
</Package>

Step 2: Add the proper icons

Apps that become the default for a URI scheme name have their icons displayed in various places throughout the system, for example, in the Default programs control panel.

We recommend that you include the proper icons with your project so that your logo looks great in all of these places. For a Windows Store app, include in your image folder 16/32/48/256 pixel versions for the small logo and icon sizes. For a Windows Phone Store app, include 63/129/336 pixel versions instead. Match the look of the app tile logo with the color plate baked in and have the logo extend to the edge without padding it. Test your icons on white backgrounds. For example icons, see the Association launching sample.

Step 3: Handle the activated event

The OnActivated event handler receives all activation events. The Kind property indicates the type of activation event. This example is set up to handle Protocol activation events.

public partial class App
{
   protected override void OnActivated(IActivatedEventArgs args)
   {
      if (args.Kind == ActivationKind.Protocol)
      {
         ProtocolActivatedEventArgs eventArgs = args as ProtocolActivatedEventArgs;

         // TODO: Handle URI activation
         // The received URI is eventArgs.Uri.AbsoluteUri
      }
   }
}

Protected Overrides Sub OnActivated(ByVal args As Windows.ApplicationModel.Activation.IActivatedEventArgs)
   If args.Kind = ActivationKind.Protocol Then
      ProtocolActivatedEventArgs eventArgs = args As ProtocolActivatedEventArgs

      ' TODO: Handle URI activation
      ' The received URI is eventArgs.Uri.AbsoluteUri
   End If
End Sub

void App::OnActivated(Windows::ApplicationModel::Activation::IActivatedEventArgs^ args)
{
   if (args->Kind == Windows::ApplicationModel::Activation::ActivationKind::Protocol)
   {
      Windows::ApplicationModel::Activation::ProtocolActivatedEventArgs^ eventArgs = 
          dynamic_cast<Windows::ApplicationModel::Activation::ProtocolActivatedEventArgs^>(args);
      
      // TODO: Handle URI activation  
      // The received URI is eventArgs->Uri->RawUri
   } 
}

Note  

When launched via Protocol Contract, Windows Phone Store apps should make sure that Back button takes the user back to the screen that launched the app and not to the app's previous content.

It is recommended that apps create a new XAML Frame for each activation event that opens a new page. This way, the navigation backstack for the new XAML Frame will not contain any previous content that the app might have on the current window when suspended. Apps that decide to use a single XAML Frame for Launch and File Contracts should clear the pages on the Frame navigation journal before navigating to a new page.

When launched via Protocol activation, apps should consider including UI that allows the user to go back to the top page of the app.

Remarks

Any app or website can use your URI scheme name, including malicious ones. So any data that you get in the URI could come from an untrusted source. We recommend that you never perform a permanent action based on the parameters that you receive in the URI. For example, URI parameters could be used to launch the app to a user's account page, but we recommend that you never use them to directly modify the user's account.

Note  If you are creating a new URI scheme name for your app, be sure to follow the guidance in RFC 4395. This ensures that your name meets the standards for URI schemes.

Note  

When launched via Protocol Contract, Windows Phone Store apps should make sure that Back button takes the user back to the screen that launched the app and not to the app's previous content.

We recommend that apps create a new XAML Frame for each activation event that opens a new Uri target. This way, the navigation backstack for the new XAML Frame will not contain any previous content that the app might have on the current window when suspended.

If you decide that you want your apps to use a single XAML Frame for Launch and Protocol Contracts, clear the pages on the Frame navigation journal before navigating to a new page. When launched via Protocol Contract, consider including UI into your apps that allows the user to go back to the top of the app.

Complete example

See Association launching sample.

Related topics

Concepts

Default Programs

File Type and URI Associations Model

Windows and Windows Server compatibility cookbook: Windows 8, Windows 8.1, and Windows Server 2012 (User model information)

Tasks

How to launch the default app for a URI

How to handle file activation

Guidelines

Guidelines for file types and URIs

Reference

Windows.ApplicationModel.Activation.ProtocolActivatedEventArgs

Windows.UI.Xaml.Application.OnActivated