|
| 1 | +--- |
| 2 | +title: Handle file activation in a Windows app |
| 3 | +description: A Windows app can register to become the default handler for a certain file type. |
| 4 | +ms.date: 02/11/2025 |
| 5 | +ms.topic: concept-article |
| 6 | +keywords: windows 10, uwp, windows 11, winui, winrt |
| 7 | +ms.localizationpriority: medium |
| 8 | +dev_langs: |
| 9 | + - csharp |
| 10 | + - vb |
| 11 | + - cppwinrt |
| 12 | + - cpp |
| 13 | +# customer-intent: As a Windows developer, I want to learn how to register my app to become the default handler for a certain file type. |
| 14 | +--- |
| 15 | + |
| 16 | +# Handle file activation in a Windows app |
| 17 | + |
| 18 | +Your app can register to become the default handler for a certain file type. Both Windows desktop applications and Universal Windows Platform (UWP) 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 when that type of file is launched. |
| 19 | + |
| 20 | +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](../files/index.md). |
| 21 | + |
| 22 | +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. |
| 23 | + |
| 24 | +> [!NOTE] |
| 25 | +> In Windows, 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. See [Reserved URI scheme names and file types](reserved-uri-scheme-names.md) for an alphabetic list of Uri schemes that you can't register for your apps because they are either reserved or forbidden. |
| 26 | +
|
| 27 | +## Important APIs |
| 28 | + |
| 29 | +The following APIs are used in this topic: |
| 30 | + |
| 31 | +- [Windows.ApplicationModel.Activation.FileActivatedEventArgs](/uwp/api/Windows.ApplicationModel.Activation.FileActivatedEventArgs) |
| 32 | +- [Windows.UI.Xaml.Application.OnFileActivated](/uwp/api/windows.ui.xaml.application.onfileactivated) |
| 33 | +- [AppInstance.GetActivatedEventArgs](/windows/windows-app-sdk/api/winrt/microsoft.windows.applifecycle.appinstance.getactivatedeventargs) |
| 34 | + |
| 35 | +## Step 1: Specify the extension point in the package manifest |
| 36 | + |
| 37 | +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 `.alsdk` extension. |
| 38 | + |
| 39 | +1. In the **Solution Explorer**, double-click package.appxmanifest to open the manifest designer. Select the **Declarations** tab and in the **Available Declarations** drop-down, select **File Type Associations** and then click **Add**. See [Programmatic Identifiers](/windows/win32/shell/fa-progids) for more details of identifiers used by file associations. |
| 40 | + |
| 41 | + Here is a brief description of each of the fields that you may fill in the manifest designer: |
| 42 | + |
| 43 | +| Field | Description | |
| 44 | +|-------|-------------| |
| 45 | +| **Display Name** | 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](/windows/win32/shell/default-programs) on the **Control Panel**. | |
| 46 | +| **Logo** | Specify the logo that is used to identify the file type on the desktop and in the [Set Default Programs](/windows/win32/shell/default-programs) on the **Control Panel**. If no Logo is specified, the application’s small logo is used. | |
| 47 | +| **Info Tip** | Specify the [info tip](/windows/win32/shell/fa-progids) for a group of file types. This tool tip text appears when the user hovers on the icon for a file of this type. | |
| 48 | +| **Name** | 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. | |
| 49 | +| **Content Type** | 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**. | |
| 50 | +| **File type** | Specify the file type to register for, preceded by a period, for example, “.jpeg”. **Reserved and forbidden file types:** See [Reserved URI scheme names and file types](reserved-uri-scheme-names.md) for an alphabetic list of file types for built-in apps that you can't register for your UWP apps because they are either reserved or forbidden. | |
| 51 | + |
| 52 | +2. Enter `alsdk` as the **Name**. |
| 53 | +3. Enter `.alsdk` as the **File Type**. |
| 54 | +4. Enter “images\\Icon.png” as the Logo. |
| 55 | +5. Press Ctrl+S to save the change to package.appxmanifest. |
| 56 | + |
| 57 | +The steps above add an [Extension](/uwp/schemas/appxpackage/appxmanifestschema/element-1-extension) element like this one to the package manifest. The **windows.fileTypeAssociation** category indicates that the app handles files with the `.alsdk` extension. |
| 58 | + |
| 59 | +```xml |
| 60 | + <Extensions> |
| 61 | + <uap:Extension Category="windows.fileTypeAssociation"> |
| 62 | + <uap:FileTypeAssociation Name="alsdk"> |
| 63 | + <uap:Logo>images\icon.png</uap:Logo> |
| 64 | + <uap:SupportedFileTypes> |
| 65 | + <uap:FileType>.alsdk</uap:FileType> |
| 66 | + </uap:SupportedFileTypes> |
| 67 | + </uap:FileTypeAssociation> |
| 68 | + </uap:Extension> |
| 69 | + </Extensions> |
| 70 | +``` |
| 71 | + |
| 72 | +## Step 2: Add the proper icons |
| 73 | + |
| 74 | +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: |
| 75 | + |
| 76 | +- Windows Explorer Items View, context menus, and the Ribbon |
| 77 | +- Default programs Control Panel |
| 78 | +- File picker |
| 79 | +- Search results on the Start screen |
| 80 | + |
| 81 | +Include a 44x44 icon with your project so that your logo can appear in those locations. Match the look of the app tile logo and use your app's background color rather than making the icon transparent. Have the logo extend to the edge without padding it. Test your icons on white backgrounds. See [Guidelines for tile and icon assets](/windows/apps/design/style/app-icons-and-logos) for more details about icons. |
| 82 | + |
| 83 | +## Step 3: Handle the activated event |
| 84 | + |
| 85 | +The [OnFileActivated](/uwp/api/windows.ui.xaml.application.onfileactivated) event handler receives all file activation events. |
| 86 | + |
| 87 | +```csharp |
| 88 | +protected override void OnFileActivated(FileActivatedEventArgs args) |
| 89 | +{ |
| 90 | + // TODO: Handle file activation |
| 91 | + // The number of files received is args.Files.Count |
| 92 | + // The name of the first file is args.Files[0].Name |
| 93 | +} |
| 94 | +``` |
| 95 | + |
| 96 | +```vb |
| 97 | +Protected Overrides Sub OnFileActivated(ByVal args As Windows.ApplicationModel.Activation.FileActivatedEventArgs) |
| 98 | + ' TODO: Handle file activation |
| 99 | + ' The number of files received is args.Files.Size |
| 100 | + ' The name of the first file is args.Files(0).Name |
| 101 | +End Sub |
| 102 | +``` |
| 103 | + |
| 104 | +```cppwinrt |
| 105 | +void App::OnFileActivated(Windows::ApplicationModel::Activation::FileActivatedEventArgs const& args) |
| 106 | +{ |
| 107 | + // TODO: Handle file activation. |
| 108 | + auto numberOfFilesReceived{ args.Files().Size() }; |
| 109 | + auto nameOfTheFirstFile{ args.Files().GetAt(0).Name() }; |
| 110 | +} |
| 111 | +``` |
| 112 | + |
| 113 | +```cpp |
| 114 | +void App::OnFileActivated(Windows::ApplicationModel::Activation::FileActivatedEventArgs^ args) |
| 115 | +{ |
| 116 | + // TODO: Handle file activation |
| 117 | + // The number of files received is args->Files->Size |
| 118 | + // The name of the first file is args->Files->GetAt(0)->Name |
| 119 | +} |
| 120 | +``` |
| 121 | +
|
| 122 | +> [!NOTE] |
| 123 | +> When launched via File Contract, make sure that Back button takes the user back to the screen that launched the app and not to the app's previous content. |
| 124 | +
|
| 125 | +> [!NOTE] |
| 126 | +> In a WinUI app, in App.OnLaunched (or in fact at any time) you can call ([AppInstance.GetActivatedEventArgs](/windows/windows-app-sdk/api/winrt/microsoft.windows.applifecycle.appinstance.getactivatedeventargs)) to retrieve the activated event args, and check them to determine how the app was activated. See [Application lifecycle functionality migration](/windows/apps/windows-app-sdk/migrate-to-windows-app-sdk/guides/applifecycle) for more information about lifecycle differences between UWP and WinUI apps. |
| 127 | +
|
| 128 | +We recommend that you create a new XAML **Frame** for each activation event that opens a new page. That way, the navigation backstack for the new XAML Frame doesn't contain any previous content that the app might have on the current window when suspended. If you decide to use a single XAML **Frame** for Launch and for File Contracts, then you should clear the pages in the **Frame**'s navigation journal before navigating to a new page. |
| 129 | +
|
| 130 | +When your app is launched via File activation, you should consider including UI that allows the user to go back to the top page of the app. |
| 131 | +
|
| 132 | +## Remarks |
| 133 | +
|
| 134 | +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. |
| 135 | +
|
| 136 | +## Related content |
| 137 | +
|
| 138 | +- [Association launching sample](https://github.com/microsoft/Windows-universal-samples/tree/master/Samples/AssociationLaunching) |
| 139 | +- [Launch the default app for a file](launch-the-default-app-for-a-file.md) |
| 140 | +- [Handle URI activation](handle-uri-activation.md) |
0 commit comments