Adding custom preview, open, and actions to files with File Handlers 2.0

Article
02/21/2023

File Handlers are a type of Microsoft 365 add-in that integrates custom file types into the service allowing you to provide rich experiences for any proprietary format.

With File Handlers, you can enable the following user experiences in OneDrive for Business and SharePoint document libraries:

Customized file icons (for proprietary file extensions)
Create new files in the browser (for proprietary file extensions)
File preview (for proprietary file extensions)
Rich view/edit capability (all file extensions)
Custom actions that launch into your app (all file extensions)
Support multiple selection and acting on folders (custom actions only)

Check out the file handler example solutions for additional details.

Important

File Handler configurations are aggressively cached throughout the system for optimal performance. It may take 24-48 hours for any configuration changes to take effect. See Registering for information about how to configure file handlers.

What's changed with File Handlers 2.0

The 2.0 upgrade to file handlers enables additional scenarios for SharePoint Online and OneDrive for Business.

Use Microsoft Graph API for more robust access to files, including file metadata, permissions, and sharing.
Add custom action buttons that launch your file handler add-in, with custom text and icons.

What's in a file handler

A file handler is comprised of the following components:

File handler endpoint. A provider-hosted app that enables the experience of your file handler. This end point can optionally provide an experience for creating, previewing, and editing files that are registered with your file handler.
File handler manifest. A set of metadata that defines the interaction between Office 365 and your file handler endpoint.
Application registered in Azure Active Directory. This application is used to authorize your access to selected files via Microsoft Graph, and is where the file handler manifest is registered.

File handler endpoint

The file handler endpoint is a cloud-hosted app that contains the functional logic for creating, previewing, opening, and saving files of the type that it handles. It can be hosted on any stack, including non-Microsoft stacks. File handlers uses Azure Active Directory to gain authorized access to Office 365 resources, so your application needs to be registered with Azure AD. For more information about registering an application with Azure AD, see Registering your app for Microsoft Graph.

For a complete examples of a file handler, see the list of available samples.

File handler manifest

The manifest defines the interaction between Office 365 and the file handler endpoint. The manifest is registered with Azure Active Directory, using the addIns collection for an application object in the directory. To register or update the registration for your file handler manifest, see How to: Register a file handler manually.

An example file handler manifest:

{
    "id": "guid",
    "type": "FileHandler",
    "properties": [
        { "key": "version", "value": "2" },
        { "key": "appIcon", "value": "{\"svg\":\"https://example.org/icon.svg\",\"png1x\":\"https://example.org/icon@1x.png\",\"png1.5x\":\"https://example.org/icon@1.5x.png\",\"png2x\":\"https://example.org/icon@2x.png\"}" },
        { "key": "fileTypeDisplayName", "value": "Contoso Document File" },
        { "key": "fileTypeIcon", "value": "{\"svg\":\"https://example.org/icon.svg\",\"png1x\":\"https://example.org/icon@1x.png\",\"png1.5x\":\"https://example.org/icon@1.5x.png\",\"png2x\":\"https://example.org/icon@2x.png\"}" },
        { "key": "actionMenuDisplayName", "value": "Contoso Actions" },
        { "key": "actions", "value": "json" }
    ]
}

Each file handler manifest includes the following key-value pairs as part of the properties array:

Property Name	Type	Description
version	String	Specify the version of the file handler. This value must be set to `2`. Required for file handlers 2.0.
appIcon	String, encoded JSON	A collection of icon URLs in different formats that are used to represent the file handler application. Optional.
fileTypeDisplayName	String	The default locale description for the file type. Optional.
fileTypeIcon	String, encoded JSON	A collection of icon URLs in different formats that are used to represent file types handled by this file handler. Optional.
actionMenuDisplayName	String	Optional. A display string in the default locale that is used when the actions associated with this file handler are collapsed into a menu.
actions	String, encoded JSON	A collection of actions implemented by this file handler extension. See specifying actions for more information. Required.

File handlers at runtime

The file handler add-in is invoked via the endpoint URL specified in the file handler manifest for the invoked action. To understand what happens, let's take a look at the scenario where a user clicks to preview a file. If there is a registered file handler for that file type, Office 365 invokes the file handler app by making a POST request to the URL specified for the preview action. In the body of the POST request, Office 365 will include the activation parameters that specify the file that was selected. The other actions, including newFile, open, and custom are invoked the same way.

Activation parameters

In the previous scenarios, your file handler app requires details, called activation parameters, about the file, tenant, Office 365 client, etc., to work with the selected file. Office 365 includes these details as form data sent in the POST request to the file handler endpoint associated with the user's action. These parameters are included in the request with the MIME type application/x-www-form-urlencoded and are URL encoded in the body of the request.

The following parameters are provided in the activation parameters:

Parameter Name	Type	Description
cultureName	string	The locale identifier for the user's current display language.
client	string	The Office 365 application from which the file handler was invoked; for example "SharePoint" or "OneDrive".
userId	string	The UPN/login email for the user who invoked the file handler.
domainHint	string	A domain hint string that indicates either `organizations` or `consumers`.
items	JSON string collection of URLs	A collection of Microsoft Graph URLs to the selected item(s).

These values are encoded in the POST request as form values.

Here is an example request that will be sent to the file handler endpoint:

POST https://contoso.com/_api/filehandlers/preview
Content-Type: application/x-www-form-urlencoded

cultureName=en-us&client=OneDrive&userId=rgregg%40contoso.com&items=%5B%22https%3A%2F%2Fgraph.microsoft.com%2Fv1.0%2Fme%2Fdrive%2Fitems%2F4D679BEA-6F9B-4106-AB11-101DDE52B06E%22%5D

Note: The URLs returned in the items collection may be very long (but less than the maximum URL length of 2048 characters). Each URL contains a token embedded in the URL that allows the file handler app to access the content without a full-trust permission scope. However, your file handler endpoint should ensure it expects long URLs to be returned and handles them correctly.

For ASP.NET developers, you can access these values using the Request.Form collection, for example:

var itemsJson = Request.Form["items"];
var itemUrls = JsonConvert.DecodeObject<string[]>(items);

The activation parameters should be cached when the request comes in, either using a server-side cache or via cookies on the response. For the initial file handler request, it's likely that the file handler app will need to redirect the user to retrieve an accessToken via Azure Active Directory OAuth2 experience. The activation parameters will be lost if not persisted before this redirect occurs.

You can see an example of using a data model object and handler method for caching the activation parameters in a cookie, in either the C# or TypeScript examples linked below in the example solutions.

File Handler example solutions

Seamless authentication with file handlers 2.0

After your file handler has received a request with activation parameters, it will need to retrieve an access token to make API calls to Microsoft Graph. Your app will need to call the Azure Active Directory authentication endpoint to retrieve an access token for the signed in user. To enable single sign-on and avoid prompting the user to select an account, you can use the login_hint parameter and provide the value of the userId activation parameter.

In some scenarios, your file handler may need to prompt the user to sign-in. If your file handler is running as a preview action, you cannot redirect to the sign-in experience inside an IFRAME and will need to popup the sign-in experience for your file handler.

File handler availability

The following table lists the Office 365 services that support file handlers.

Service name	File handlers 2.0	File handlers 1.0
SharePoint Online	Generally available (GA)	GA
OneDrive for Business	GA	GA
OneDrive personal	Not available	Not available
Outlook Web App	Not available	GA