Hinzufügen einer benutzerdefinierten Vorschau, einer Öffnen-Funktion sowie von Aktionen zu Dateien mithilfe von Dateihandlern der Version 2.0Adding custom preview, open, and actions to files with File Handlers 2.0

Dateihandler sind ein Typ von Office-Add-In, mit dessen Hilfe sich benutzerdefinierte Dateitypen so in Office 365 integrieren lassen wie die Office-Dateitypen.File handlers are a type of Office add-in that integrate custom file types into Office 365 the same way that Office file types are.

Über Dateihandler können Sie die folgenden Benutzerfunktionen in OneDrive for Business und SharePoint-Dokumentbibliotheken implementieren:With file handlers, you can enable the following user experiences in OneDrive for Business and SharePoint document libraries:

  • Benutzerdefinierte Dateisymbole (für proprietäre Dateierweiterungen)Customized file icons (for proprietary file extensions)
  • Erstellen neuer Dateien im Browser (für proprietäre Dateierweiterungen)Create new files in the browser (for proprietary file extensions)
  • Dateivorschau (für proprietäre Dateierweiterungen)File preview (for proprietary file extensions)
  • Erweiterte Ansichts- und Bearbeitungsfunktionen (alle Dateierweiterungen)Rich view/edit capability (all file extensions)
  • Benutzerdefinierte Aktionen, die in Ihrer App starten (alle Dateierweiterungen)Custom actions that launch into your app (all file extensions)
  • Unterstützung für Mehrfachauswahl sowie Aktionen für Ordner (nur benutzerdefinierte Aktionen)Support multiple selection and acting on folders (custom actions only)

Weitere Einzelheiten finden Sie im Beispielprojekt „Markdown File Handler“.Check out the Markdown File Handler example project for more specifics.

Änderungen bei Dateihandlern der Version 2.0What's new with file handlers 2.0

Das Upgrade 2.0 für Dateihandler ermöglicht zusätzliche Szenarien für SharePoint Online und OneDrive for Business:The 2.0 upgrade to file handlers enables additional scenarios for SharePoint Online and OneDrive for Business.

  • Verwenden der Microsoft Graph-API für stabileren Zugriff auf Dateien, einschließlich Dateimetadaten, Berechtigungen und FreigabeUse Microsoft Graph API for more robust access to files, including file metadata, permissions, and sharing.
  • Hinzufügen von Schaltflächen für benutzerdefinierte Aktionen, die Ihr Dateihandler-Add-In starten, einschließlich benutzerdefiniertem Text und benutzerdefinierter SymboleAdd custom action buttons that launch your file handler add-in, with custom text and icons.

Inhalt eines DateihandlersWhat's in a file handler

Ein Dateihandler besteht aus den folgenden Komponenten:A file handler is comprised of the following components:

  • Dateihandler-Endpunkt: Eine beim Anbieter gehostete App, die die Benutzerfunktionen Ihres Dateihandlers bereitstellt. Dieser Endpunkt kann optional Funktionen zur Erstellung sowie zur Bearbeitung aller Dateien bereitstellen, die in Ihrem Dateihandler registriert sind. Auch eine Dateivorschau kann bereitgestellt werden.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.
  • Dateihandlermanifest: Ein Satz von Metadaten, der die Interaktion zwischen Office 365 und Ihrem Dateihandler-Endpunkt definiert.File handler manifest. A set of metadata that defines the interaction between Office 365 and your file handler endpoint.
  • Eine in Azure Active Directory registrierte Anwendung: Diese Anwendung wird verwendet, um den Zugriff auf ausgewählte Dateien über Microsoft Graph zu autorisieren. In ihr wird auch das Dateihandlermanifest registriert.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.

Dateihandler-EndpunktFile handler endpoint

Der Dateihandler-Endpunkt ist eine in der Cloud gehostete App. Sie enthält die Funktionslogik, über die die vom Dateihandler unterstützten Dateien erstellt, geöffnet und gespeichert werden und über die eine Dateivorschau angezeigt wird. Der Endpunkt kann auch auf anderen Stacks als dem Microsoft-Stack gehostet werden. Dateihandler nutzen Azure Active Directory für den autorisierten Zugriff auf Office 365-Ressourcen. Daher muss Ihre Anwendung bei Azure AD registriert sein. Weitere Informationen zur Registrierung von Anwendungen bei Azure AD finden Sie unter Registering your app for Microsoft Graph.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.

Ein vollständiges Beispiel für einen Dateihandler finden Sie in unserem Projekt „Markdown File Handler“ auf GitHub.For a complete example of a file handler, see the Markdown-FileHandler on GitHub.

DateihandlermanifestFile handler manifest

Das Manifest definiert die Interaktion zwischen Office 365 und dem Dateihandler-Endpunkt. Es ist bei Azure Active Directory registriert, über die Sammlung addIns für ein Anwendungsobjekt im Verzeichnis. Informationen zur Registrierung eines Dateihandlermanifests sowie zur Registrierungsaktualisierung finden Sie im Artikel zum Thema Manuelles Registrieren eines Dateihandlers.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.

Hier ein Beispiel für ein Dateihandlermanifest: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" }
    ]
}

Jedes Dateihandlermanifest enthält die folgenden Schlüssel-Wert-Paare im Array properties:Each file handler manifest includes the following key-value pairs as part of the properties array:

EigenschaftennameProperty Name TypType BeschreibungDescription
versionversion StringString Hier geben Sie die Version des Dateihandlers an. Dieser Wert muss auf 2 gesetzt werden. Erforderlich für Dateihandler der Version 2.0.Specify the version of the file handler. This value must be set to 2. Required for file handlers 2.0.
appIconAppIcon String, encoded JSONString, encoded JSON Eine Zusammenstellung von Symbol-URLs in verschiedenen Formaten, die zur Darstellung der Dateihandler-Anwendung verwendet werden.A collection of icon URLs in different formats that are used to represent the file handler application. Optional.Optional.
fileTypeDisplayNamefileTypeDisplayName StringString Die Beschreibung des Dateityps in der Sprache des Standardgebietsschemas. Optional.The default locale description for the file type. Optional.
fileTypeIconfileTypeIcon String, encoded JSONString, encoded JSON Eine Zusammenstellung von Symbol-URLs in verschiedenen Formaten, die zur Darstellung von Dateitypen verwendet werden, die von diesem Dateihandler behandelt werden.A collection of icon URLs in different formats that are used to represent file types handled by this file handler. Optional.Optional.
actionMenuDisplayNameactionMenuDisplayName ZeichenfolgeString Optional.Optional. Eine Anzeigezeichenfolge im standardmäßigen Gebietsschema, das verwendet wird, wenn mit diesem Dateihandler verbundene Aktionen in einem Menü reduziert werden.A display string in the default locale that is used when the actions associated with this file handler are collapsed into a menu.
actionsactions String, encoded JSONString, encoded JSON Eine Sammlung von Aktionen, die von der Dateihandlererweiterung implementiert werden. Weitere Informationen finden Sie im Artikel zum Thema Definieren von Aktionen. Erforderlich.A collection of actions implemented by this file handler extension. See specifying actions for more information. Required.

Dateihandler zur LaufzeitFile handlers at runtime

Das Dateihandler-Add-In wird über die Endpunkt-URL aufgerufen, die im Dateihandlermanifest für die aufgerufene Aktion definiert ist. Betrachten wir zur Verdeutlichung ein Szenario, in dem ein Benutzer auf eine Datei klickt, um die Dateivorschau anzuzeigen. Wenn ein registrierter Dateihandler für den betreffenden Dateityp existiert, ruft Office 365 die Dateihandler-App auf, über eine POST-Anforderung an die für die Aktion preview definierte URL. In den Text der POST-Anforderung schreibt Office 365 die Aktivierungsparameter, die die ausgewählte Datei definieren. Die anderen Aktionen, einschließlich newFile, open und custom, werden ebenso aufgerufen.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.

AktivierungsparameterActivation parameters

In den zuvor beschriebenen Szenarien benötigt Ihre Dateihandler-App bestimmte Details, um mit der ausgewählten Datei arbeiten zu können, beispielsweise solche zur Datei selbst, zum Mandanten und zum Office 365-Client. Diese Details werden als Aktivierungsparameter bezeichnet. Office 365 schreibt diese Details als Formulardaten in die POST-Anforderung, die an den der Benutzeraktion zugeordneten Dateihandler-Endpunkt gesendet wird. Die Parameter werden mit dem MIME-Typ application/x-www-form-urlencoded in die Anforderung geschrieben und im Anforderungstext URL-codiert.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.

Die folgenden Parameter werden als Aktivierungsparameter bereitgestellt:The following parameters are provided in the activation parameters:

ParameternameParameter Name TypType BeschreibungDescription
cultureNamecultureName stringstring Die Gebietsschema-ID für die aktuelle Anzeigesprache des BenutzersThe locale identifier for the user's current display language.
clientclient stringstring Die Office 365-Anwendung, über die der Dateihandler aufgerufen wurde, beispielsweise „SharePoint“ oder „OneDrive“The Office 365 application from which the file handler was invoked; for example "SharePoint" or "OneDrive".
userIdUserId stringstring Die UPN/Anmelde-E-Mail-Adresse des Benutzers, der den Dateihandler aufgerufen hatThe AAD object ID for the user who has invoked the file handler.
domainHintdomainHint stringstring Eine Domänen-Hinweiszeichenfolge, die entweder organizations oder consumers angibt.A domain hint string that indicates either organizations or consumers.
itemsitems JSON string collection of URLsJSON string collection of URLs Eine Sammlung von Microsoft Graph-URLs zu den ausgewählten ElementenA collection of Microsoft Graph URLs to the selected item(s).

Diese Werte werden als Formularwerte in die POST-Anforderung geschrieben.These values are encoded in the POST request as form values.

Hier eine Beispielanforderung an den Dateihandler-Endpunkt: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

Hinweis: Die URLs, die in der Auflistung der Elemente zurückgegeben werden, können sehr lang sein (jedoch kürzer als die maximale URL-Länge von 2.048 Zeichen).Note: The URLs returned in the items collection may be very long (but less than the maximum URL length of 2048 characters). Jede URL umfasst ein in die URL eingebettetes Token, mit dem die Dateinhandler-App auf die Inhalte zugreifen kann, ohne dass eine Berechtigung mit voller Vertrauenswürdigkeit erforderlich ist.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. Ihre Dateihandler-Endpunkt sollte jedoch sicherstellen, dass er lange URLs für die Rückgabe erwartet und sie korrekt behandelt.However, your file handler endpoint should ensure it expects long URLs to be returned and handles them correctly.

ASP.NET-Entwickler können über die Sammlung Request.Form auf diese Werte zugreifen, beispielsweise wie folgt: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);

Die Aktivierungsparameter sollten zwischengespeichert werden, wenn die Anforderung eingeht, entweder in einem serverseitigen Cache oder in Cookies beim Senden der Antwort. Bei der ersten Dateihandleranforderung muss die Dateihandler-App den Benutzer wahrscheinlich zur Azure Active Directory-OAuth2-Oberfläche umleiten, damit er ein Zugriffstoken abrufen kann. Werden die Aktivierungsparameter vor dieser Umleitung nicht gespeichert, gehen sie verloren.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.

In unserem Beispielprojekt „Markdown File Handler“ ist illustriert, wie Sie eine Datenmodellobjekt- und eine Handlermethode nutzen können, um die Aktivierungsparameter in einem Cookie zwischenzuspeichern.You can see an example of using a data model object and handler method for caching the activation parameters in a cookie, in the Markdown File Handler sample.

Nahtlose Authentifizierung mit Dateihandlern der Version 2.0Seamless authentication with file handlers 2.0

Wenn Ihr Dateihandler eine Anforderung mit Aktivierungsparametern empfängt, muss er ein Zugriffstoken abrufen, um API-Aufrufe an Microsoft Graph senden zu können. Die App muss den Azure Active Directory-Authentifizierungsendpunkt aufrufen, um ein Zugriffstoken für den angemeldeten Benutzer abzurufen. Um einmaliges Anmelden zu ermöglichen und zu vermeiden, dass der Benutzer ein Konto auswählen muss, können Sie den Parameter login_hint verwenden und den Wert des Aktivierungsparameters userId bereitstellen.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 einigen Fällen fordert der Dateihandler den Benutzer möglicherweise dazu auf, sich anzumelden.In some scenarios, your file handler may need to prompt the user to sign-in. Wenn Ihr Dateihandler als preview-Aktion ausgeführt wird, können Sie innerhalb eines IFRAME nicht zur Anmeldung zurückkehren und Sie müssen die Anmeldung für Ihren Dateihandler per Popup-Meldung realisieren.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.

Dateihandler-VerfügbarkeitFile handler availability

In der folgenden Tabelle sind die Office 365-Dienste aufgeführt, die Dateihandler unterstützen:The following table lists the Office 365 services that support file handlers.

DienstnameService name Dateihandler Version 2.0File handlers 2.0 Dateihandler Version 1.0File handlers 1.0
SharePoint OnlineSharePoint Online Allgemein verfügbarGenerally available (GA) Allgemein verfügbarGA
OneDrive for BusinessOneDrive for Business Allgemein verfügbarGA Allgemein verfügbarGA
OneDrive PersonalOneDrive personal Nicht verfügbarNot available Nicht verfügbarNot available
Outlook Web AppOutlook Web App Nicht verfügbarNot available Allgemein verfügbarGA