Microsoft recently announced the general availability of file handler add-ins for Office 365. This add-in type enables Office 365 customers to implement custom icons, previews and editors for specific file extensions in SharePoint Online, OneDrive for Business, and Outlook Web App (OWA). In this post, I’ll outline a solution for creating a file handler add-in for .png images. The add-in will allow .png images to be opened in an in-browser editor (think browser-based paint) for drawing/annotation/whiteboarding.
Azure AD and Add-ins
Until now, Azure AD applications were considered stand-alone in the context of Office 365. File handler add-ins are similar to a stand-alone Azure AD web application, but are dependent on contextual information passed when invoked from Office 365 (more on that later).
The file handler add-in can be provisioned in Azure AD using the Connected Service Wizard in Visual Studio or manually through the Azure Management Portal or New Getting Started experience. However, file handler add-ins require a new permission that are currently only surfaced through the Azure Management Portal. This new permission is Read and write user selected files (preview) using the Office 365 Unified API. This permission allows a 3rd party file handler add-in to get access only to the files the user select (vs. ALL of the users files).
Once the application is registered, some additional configuration needs to be performed that the Azure Management Portal doesn’t (yet) surface in the user interface. Azure needs to know the extension, icon url, open URL, and preview URL for the file handler. This can be accomplished by submitting a json manifest update using Azure AD Graph API queries (outlined HERE). However, the Office Extensibility Team created an Add-in Manager website that provides a nice interface for making these updates. It allows you to select an Azure AD application and register file handler add-ins against it. Below, you can see the file handler registration for my .png file handler.
When the file handler add-in is invoked, the host application (SharePoint/OneDrive/OWA) posts some form details to the application. This includes the following parameters.
- Client - The Office 365 client from which the file is opened or previewed; for example, "SharePoint".
- CultureName - The culture name of the current thread, used for localization.
- FileGet - The full URL of the REST endpoint your app calls to retrieve the file from Office 365. Your app retrieves file using a GET request.
- FilePut - The full URL of the REST endpoint your app calls to save the file back to Office 365. You must call this with the HTTP POST method.
- ResourceID - The URL of the Office 365 tenant used to get the access token from Azure AD.
- DocumentID - The document ID for a specific document; allows your application to open more than one document at the same time.
If the application (which is secured by Azure AD) isn’t authenticated, it will need to perform an OAuth flow with Azure AD. This OAuth flow (which includes a redirect) will cause the application to loose these contextual parameters posted from Office 365. To preserve these parameters, you should employ a caching technique so they can be used after a completed OAuth flow completes. In the code below, you can see that the form data is cached in a cookie using the RedirectToIdentityProvider handler provided with Open ID Connect.
public void ConfigureAuth(IAppBuilder app)
//cache the token in session state
Opening and Saving Files
One of the form parameters Office 365 posts to the application is the GET URI for the file. The code below shows the controller to Open the file using this URI. Notice that is first loads the form data using ActivationParameters object, then gets an access token, and retrieves the file. The controller view also adds a number of ViewData values that will be used later for saving changes to the file (including the refresh token, resource, and file put URI).
public async Task<ActionResult> Index()
//try to get access token using refresh token
//get the image
Saving changes to the file is implemented in a Web API controller. The application POSTs the save details including the updated image, resource, refresh token, and file put URI to this end-point. The end-point gets an access token (using the refresh token) and POST and update to the existing image.
//convert base64 image string into byte and then stream
return Request.CreateResponse<bool>(HttpStatusCode.OK, true);
var canvas = document.getElementById("canvas");
The completed solution uses a highly modified version of sketch.js to provide client-side drawing on a canvas element (modified to support images and scaling).
In my opinion, these new file handler add-ins are incredibly powerful. Imagine the scenarios for proprietary file extensions or extensions that haven’t traditionally been considered a first-class citizen in Office 365 (ex: .cad, .pdf, etc). You can download the .png file handler add-in solution from GitHub: https://github.com/OfficeDev/Image-FileHandler. You should also checkout Dorrene Brown's (@dorreneb) Ignite talk on File Handler Add-ins and Sonya Koptyev's (@SonyaKoptyev) Office Dev Show on the same subject.