How to handle URI activation (XAML)

Article
08/31/2015

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.

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:

Field	Description
Logo	Specify the logo that is used to identify the URI scheme name in the Set Default Programs on the Control Panel. If no Logo is specified, the small logo for the app is used.
Display Name	Specify the display name to identify the URI scheme name in the Set Default Programs on the Control Panel.
Name	Choose a name for the Uri scheme. Note The Name must be in all lower case letters. Reserved and forbidden file types Here are alphabetic lists of Uri schemes that you can't register for your app because they are either reserved or forbidden: Note For Windows Store apps application.manifest, application.reference, batfile, blob, cerfile, chm.file, cmdfile, comfile, cplfile, dllfile, drvfile, exefile, explorer.assocactionid.burnselection, explorer.assocactionid.closesession, explorer.assocactionid.erasedisc, explorer.assocactionid.zipselection, explorer.assocprotocol.search-ms, explorer.burnselection, explorer.closesession, explorer.erasedisc, explorer.zipselection, file, fonfile, hlpfile, htafile, inffile , insfile, internetshortcut, jsefile, lnkfile, microsoft.powershellscript.1, ms-accountpictureprovider, ms-appdata, ms-appx, ms-autoplay, msi.package, msi.patch, ms-windows-store, ocxfile, piffile, regfile, scrfile, scriptletfile, shbfile, shcmdfile, shsfile,smb, sysfile, ttffile,unknown, usertileprovider,vbefile,vbsfile, windows.gadget,wsffile, wsfile,wshfile Note For Windows Phone Store apps Windows Phone reserves the following Uri schemes for built-in apps. bing, callto, dtmf, http, https, mailto, maps, ms-excel, ms-powerpoint, ms-settings-airplanemode, ms-settings-bluetooth, ms-settings-cellular, ms-settings-emailandaccounts, ms-settings-location, ms-settings-lock, ms-settings-wifi, ms-word, office, onenote, tel, wallet, xbls, zune Windows Phone reserves the following Uri schemes for the operating system. Explorer.AssocActionId.BurnSelection, Explorer.AssocActionId.CloseSession, Explorer.AssocActionId.EraseDisc, Explorer.AssocActionId.ZipSelection, Explorer.AssocProtocol.search-ms, Explorer.BurnSelection, Explorer.CloseSession, Explorer.EraseDisc, Explorer.ZipSelection, File, Iehistory, Ierss, Javascript, Jscript, LDAP, Res, rlogin, StickyNotes, telnet, tn3270, Vbscript, windowsmediacenterapp, windowsmediacenterssl, windowsmediacenterweb, WMP11.AssocProtocol.MMS
Desired View (Windows-only)	Specify the Desired View field to indicate the amount of space the app’s window needs when it is launched for the URI scheme name. The possible values for Desired View are Default, UseLess, UseHalf, UseMore, or UseMinimum. Note Windows takes into account multiple different factors when determining the target app's final window size, for example, the preference of the source app, the number of apps on screen, the screen orientation, and so on. Setting Desired View doesn't guarantee a specific windowing behavior for the target app. Windows 8.1: Desired View is not supported until Windows 8.1 and Windows Server 2012 R2. Windows Phone: Desired View isn't supported for Windows Phone.

Select the Declarations tab.
Select Protocol from the drop-down list and click Add.
Enter alsdk as the Name.
Enter “images\Icon.png” as the Logo.
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.