How to handle file activation (XAML)
An app can register to become the default handler for a certain file type. Both desktop apps and Windows Runtime apps can register to be a default file handler. If the user chooses your app as the default handler for a certain file type, your app will be activated every time that type of file is launched.
We recommend that you only register for a file type if you expect to handle all file launches for that type of file. If your app only needs to use the file type internally, then you don't need to register to be the default handler. If you do choose to register for a file type, you must provide the end user with the functionality that is expected when your app is activated for that file type. For example, a picture viewer app may register to display a .jpg file. For more info on file associations, see Guidelines for file types and URIs.
These steps show how to register for a custom file type, .alsdk, and how to activate your app when the user launches an .alsdk file.
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.
The app receives activation events only for the file extensions listed in the package manifest. Here's how you indicate that your app handles the files with the
- Double click to open package.appxmanifest in Solution Explorer.
See Programmatic Identifiers for more details of identifiers used by file associations. Here is a brief description of each of the fields that you may fill in the package manifest:
Specify the MIME content type, such as image/jpeg, for a particular file type.
Important Note about allowed content types: Here is an alphabetic list of MIME content types that you cannot enter into the package manifest because they are either reserved or forbidden: application/force-download, application/octet-stream, application/unknown, application/x-msdownload.
Choose a name for a group of file types that share the same display name, logo, info tip, and edit flags. Choose a group name that can stay the same across app updates.Note The Name must be in all lower case letters.
Specify the info tip for a group of file types. This tool tip text appears when the user hovers on the icon for a file of this type.
Specify the edit flags for a group of file types. The edit flags control how a file is accessed when it is acquired from an untrusted source. The OpenIsSafe flag indicates that the Open verb for the file type can be safely invoked for any downloaded files. AlwaysUnsafe flag indicates that the option to automatically invoke the Open verb for the file type is disabled. The user can override this attribute through the File Type dialog box. Use of this flag means OpenIsSafe is not respected. It prevents the Never ask me check box from being enabled on the security dialog when opening untrusted files of this type.
Specify the display name for a group of file types. The display name is used to identify the file type in the Set Default Programs on the Control Panel.
Specify the logo that is used to identify the file type on the desktop and in the Set Default Programs on the Control Panel. If no Logo is specified, the application’s small logo is used.
Specify the file type to register for, preceded by a period, for example, “.jpeg”."
Reserved and forbidden file types
Here are alphabetic lists of file types that you can't register for your app because they are either reserved or forbidden:
For Windows Store apps
Accountpicture-ms, Appx, application, Appref-ms, Bat, Cer, Chm, Cmd, Com, Cpl, crt, dll, drv, Exe, fon, gadget, Hlp, Hta, Inf ,Ins, jse, lnk, Msi, Msp, ocx, pif, Ps1, Reg, Scf, Scr, Shb, Shs, Sys, ttf, url, Vbe, Vbs, Ws, Wsc, Wsf, Wsh
For Windows Phone Store apps
Windows Phone reserves the following file types for built-in apps.
aac, aetx, asf, bmp, cer, dotm, dotx, gif, hdp, htm, html, ico, icon, jpeg, jpg, jxr, m4a, m4rm, m4v, mov, mp3, mp4, one, onetoc2, p7b, pem, png, pptm, pptx, qcp, rtf, tif, tiff, txt, url, vcf, wav, wdp, wmv, xap, xht, xhtml, xltm, xltx, xml, xsl, zip
Windows Phone reserves the following file types for the operating system.
ade, adp, app, application, apprefms, asp, bas, bat, cab, chm, cmd, cnt, com, cpf, cpl, crd, crds, crt, csh, der, dll, exe, fxp, gadget, grp, hlp, hme, hpj, hta, inf, ins, isp, its, jar, js, jse, ksh, lnk, mad, maf, mag, mam, maq, mar, mas, mat, mau, mav, maw, mcf, mda, mdb, mde, mdt, mdw, mdz, msc, msh, msh1, msh1xml, msh2, msh2xml, mshxml, msi, msp, mst, msu, ops, pcd, pif, pl, plg, plsc, prf, prg, printerexport, provxml, ps1, ps1xml, ps2, ps2xml, psc1, psc2, psm1, pst, pvw, py, pyc, pyo, rb, rbw, rdp, reg, rgu, scf, scr, shb, shs, theme, tmp, tsk, url, vb, vbe, vbp, vbs, vhd, vhdx, vsmacros, vsw, webpnp, ws, wsc, wsf, wsh, xaml, xdp, xip, xnk
Specify the Desired View field to indicate the amount of space the app’s window needs when it is launched for the file type. 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 File Type Associations from the drop-down list and click Add.
alsdkas the Name.
.alsdkas the File Type.
- 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.fileTypeAssociation category indicates that the app handles files with the
<Package xmlns="http://schemas.microsoft.com/appx/2010/manifest" xmlns:m2="http://schemas.microsoft.com/appx/2013/manifest"> <Applications> <Application Id="AutoLaunch.App"> <Extensions> <Extension Category="windows.fileTypeAssociation"> <FileTypeAssociation Name="alsdk"> <DisplayName>SDK Sample File Type</DisplayName> <Logo>images\logo.png</Logo> <InfoTip>SDK Sample tip </InfoTip> <EditFlags OpenIsSafe="true" /> <SupportedFileTypes> <FileType ContentType="image/jpeg">.alsdk</FileType> </SupportedFileTypes> </FileTypeAssociation> </Extension> </Extensions> </Application> </Applications> </Package>
Apps that become the default for a file type have their icons displayed in various places throughout the system. For example these icons are shown in:
- Windows Explorer ItemsView, context menus, and the Ribbon
- Default programs Control Panel
- File picker
- Search results on the Start screen
The OnFileActivated event handler receives all file activation events.
Protected Overrides Sub OnFileActivated(ByVal args As Windows.ApplicationModel.Activation.FileActivatedEventArgs) ' TODO: Handle file activation ' The number of files received is args.Files.Size ' The first file is args.Files(0).Name End Sub
When launched via File 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's navigation journal before navigating to a new page.
When launched via File activation, apps should consider including UI that allows the user to go back to the top page of the app.
The files that you receive could come from an untrusted source. We recommend that you validate the content of a file before taking action on it. For more info on input validation, see Writing Secure Code.
- Default Programs
- File Type and Protocol Associations Model
- Windows and Windows Server compatibility cookbook: Windows 8, Windows 8.1, and Windows Server 2012 (User model information)
- How to launch the default app for a file
- How to handle protocol activation
- Guidelines for file types and URIs