Runtimes in Office-Add-Ins

Office-Add-Ins werden in Runtimes ausgeführt, die in Office eingebettet sind. Als interpretierte Sprache muss JavaScript in einer JavaScript-Runtime ausgeführt werden. Node.js und moderne Browser sind Beispiele für solche Runtimes.

Laufzeittypen

Es gibt zwei Arten von Laufzeiten, die von Office-Add-Ins verwendet werden:

• Reine JavaScript-Runtime: Eine JavaScript-Engine, die durch Unterstützung für WebSockets, vollständige CORS (Cross-Origin Resource Sharing) und clientseitige Speicherung von Daten ergänzt wird. Lokale Speicherung oder Cookies werden nicht unterstützt.
• Browserruntime: Enthält alle Features einer reinen JavaScript-Runtime und fügt Unterstützung für lokalen Speicher, eine Rendering-Engine zum Rendern von HTML und Cookies hinzu.

Ausführliche Informationen zu diesen Typen finden Sie weiter unten in diesem Artikel unter Reine JavaScript-Runtime und Browserruntime.

Die folgende Tabelle zeigt die möglichen Features eines Add-Ins je nach Laufzeittyp.

Laufzeittyp	Add-In-Funktion
Nur JavaScript	Benutzerdefinierte Excel-Funktionen (außer wenn die Laufzeit freigegeben wird oder das Add-In in Office im Web ausgeführt wird) Outlook-ereignisbasierte Aufgabe (nur, wenn das Add-In im klassischen Outlook unter Windows ausgeführt wird) Integriertes Spam-Berichterstellungsfeature von Outlook (nur, wenn das Add-In im klassischen Outlook unter Windows ausgeführt wird)
Browser	Aufgabenbereich Dialogfeld Funktionsbefehl Benutzerdefinierte Excel-Funktionen (wenn die Laufzeit freigegeben wird oder das Add-In in Office im Web ausgeführt wird) Outlook-ereignisbasierte Aufgabe (wenn das Add-In in Outlook auf Mac oder Outlook im Web oder im neuen Outlook unter Windows ausgeführt wird) Integriertes Spamberichtsfeature von Outlook (nur, wenn das Add-In in Outlook auf Mac oder im Web oder im neuen Outlook unter Windows ausgeführt wird)

Die folgende Tabelle enthält dieselben Informationen, die nach dem Typ der Laufzeit für die verschiedenen möglichen Features eines Add-Ins verwendet werden.

Add-In-Funktion	Laufzeittyp unter Windows	Laufzeittyp auf Dem Mac	Typ der Laufzeit im Web
Benutzerdefinierte Excel-Funktionen	Nur JavaScript (aber Browser , wenn die Runtime freigegeben ist)	Browser	Browser
Ereignisbasierte Outlook-Aufgaben	Nur JavaScript (klassisches Outlook unter Windows) Browser (neues Outlook unter Windows)	Browser	Browser
Integriertes Outlook-Spam-Berichterstellungsfeature (Vorschau)	Nur JavaScript (klassisches Outlook unter Windows) Browser (neues Outlook unter Windows)	Browser	Browser
Aufgabenbereich	Browser	Browser	Browser
Dialogfeld	Browser	Browser	Browser
Funktionsbefehl	Browser	Browser	Browser

In Office im Web wird alles immer in einer Laufzeit vom Typ "Browser" ausgeführt. Mit einer Ausnahme wird alles in einem Add-In im Web im gleichen Browserprozess ausgeführt: dem Browserprozess, in dem der Benutzer Office im Web geöffnet hat. Die Ausnahme ist, wenn ein Dialogfeld mit einem Aufruf von Office.ui.displayDialogAsync geöffnet wird und die Option DialogOptions.displayInIFramenicht übergeben und auf truefestgelegt wird. Wenn die Option nicht übergeben wird (sie hat also den Standardwert false ), wird das Dialogfeld in einem eigenen Prozess geöffnet. Das gleiche Prinzip gilt für die OfficeRuntime.displayWebDialog-Methode und die OfficeRuntime.DisplayWebDialogOptions.displayInIFrame-Option .

Wenn ein Add-In auf einer anderen Plattform als dem Web ausgeführt wird, gelten die folgenden Prinzipien.

• Ein Dialogfeld wird in einem eigenen Laufzeitprozess ausgeführt.

• Ein ereignisbasiertes Outlook- oder Spamberichts-Add-In wird in einem eigenen Laufzeitprozess ausgeführt.

  Hinweis

  Die funktionen für die ereignisbasierte Aktivierung und die integrierte Spamberichterstattung in Outlook müssen dieselbe Laufzeit verwenden. Mehrere Runtimes werden in Outlook derzeit nicht unterstützt.

• Standardmäßig werden Aufgabenbereiche, Funktionsbefehle und benutzerdefinierte Excel-Funktionen jeweils in ihrem eigenen Laufzeitprozess ausgeführt. Für einige Office-Hostanwendungen kann das Add-In-Manifest jedoch so konfiguriert werden, dass zwei oder alle drei in derselben Runtime ausgeführt werden können. Weitere Informationen finden Sie unter Freigegebene Runtime.

Abhängig von der Office-Hostanwendung und den im Add-In verwendeten Features kann es viele Runtimes in einem Add-In geben. Jedes wird in der Regel in einem eigenen Prozess ausgeführt, aber nicht notwendigerweise gleichzeitig. Es folgen einige Beispiele.

• Ein PowerPoint- oder Word-Add-In, das keine Runtimes gemeinsam verwendet und die folgenden Features enthält, verfügt über bis zu drei Laufzeiten.

  • Ein Aufgabenbereich

  • Ein Funktionsbefehl

  • Ein Dialogfeld (Ein Dialogfeld kann entweder über den Aufgabenbereich oder den Funktionsbefehl gestartet werden.)

    Hinweis

    Es ist keine bewährte Methode, mehrere Dialogfelder gleichzeitig zu öffnen, aber wenn das Add-In es dem Benutzer ermöglicht, eines aus dem Aufgabenbereich und ein anderes über den Funktionsbefehl gleichzeitig zu öffnen, würde dieses Add-In vier Laufzeiten aufweisen. Ein Aufgabenbereich und ein gegebener Aufruf eines Funktionsbefehls können jeweils nur einen geöffneten Dialog aufweisen. Wenn der Funktionsbefehl jedoch mehrmals aufgerufen wird, wird über dem Vorgänger mit jedem Aufruf ein neues Dialogfeld geöffnet, sodass es viele Laufzeiten geben kann. Der Rest dieser Liste ignoriert die Möglichkeit mehrerer geöffneter Dialoge.

• Ein Excel-Add-In, das keine Runtimes gemeinsam verwendet und die folgenden Features enthält, verfügt über bis zu vier Laufzeiten.

  • Ein Aufgabenbereich
  • Ein Funktionsbefehl
  • Eine benutzerdefinierte Funktion
  • Ein Dialogfeld (Ein Dialogfeld kann entweder über den Aufgabenbereich, den Funktionsbefehl oder eine benutzerdefinierte Funktion gestartet werden.)

• Ein Excel-Add-In mit den gleichen Features und ist so konfiguriert, dass die gleiche Laufzeit im Aufgabenbereich, im Funktionsbefehl und in der benutzerdefinierten Funktion gemeinsam verwendet wird, über zwei Laufzeiten verfügt. Eine freigegebene Runtime kann jeweils nur einen Dialog öffnen.

• Ein Excel-Add-In mit den gleichen Features, mit der Ausnahme, dass es über kein Dialogfeld verfügt und so konfiguriert ist, dass die gleiche Laufzeit im Aufgabenbereich, im Funktionsbefehl und in der benutzerdefinierten Funktion gemeinsam verwendet wird, verfügt über eine Laufzeit.

• Ein Outlook-Add-In mit den folgenden Features verfügt über bis zu vier Laufzeiten. Freigegebene Runtimes werden in Outlook nicht unterstützt.

  • Ein Aufgabenbereich
  • Ein Funktionsbefehl
  • Eine ereignisbasierte Aufgabe oder eine integrierte Spamberichterstattungsfunktion
  • Ein Dialogfeld (Ein Dialogfeld kann entweder über den Aufgabenbereich oder den Funktionsbefehl, aber nicht über eine ereignisbasierte Aufgabe gestartet werden.)

Freigeben von Daten über Runtimes hinweg

Hinweis

• Wenn Sie wissen, dass Ihr Add-In nur in Office im Web verwendet wird und keine Dialogfelder mit der displayInIFrame auf truefestgelegten Option geöffnet werden, können Sie diesen Abschnitt ignorieren. Da alles in Ihrem Add-In im selben Laufzeitprozess ausgeführt wird, können Sie einfach globale Variablen verwenden, um Daten zwischen Features freizugeben.
• Wie oben unter Laufzeittypen erwähnt, variiert der Von einem Feature verwendete Laufzeittyp teilweise je nach Plattform. Es empfiehlt sich, add-in-Code zu vermeiden, der plattformbasiert ist. Daher empfiehlt die Anleitung in diesem Abschnitt Techniken, die plattformübergreifend funktionieren. Es gibt nur einen Fall, der unten angegeben ist, in dem Verzweigungscode erforderlich ist.

Verwenden Sie für Excel-, PowerPoint- und Word-Add-Ins eine freigegebene Runtime , wenn mindestens zwei Features mit Ausnahme von Dialogfeldern Daten freigeben müssen. In Outlook oder Szenarien, in denen die Freigabe einer Runtime nicht möglich ist, benötigen Sie alternative Methoden. Die Teile des Add-Ins, die sich in separaten Laufzeitprozessen befinden, teilen nicht automatisch globale Daten und werden vom Webanwendungsserver des Add-Ins als separate Sitzungen behandelt, sodass Window.sessionStorage nicht zum Freigeben von Daten zwischen ihnen verwendet werden kann. In der folgenden Anleitung wird davon ausgegangen, dass Sie keine freigegebene Runtime verwenden.

• Übergeben Sie Daten zwischen einem Dialogfeld und dem übergeordneten Aufgabenbereich, dem Funktionsbefehl oder der benutzerdefinierten Funktion mithilfe der Methoden Office.ui.messageParent und Dialog.messageChild .

  Hinweis

  Die OfficeRuntime.storage Methoden können nicht in einem Dialog aufgerufen werden, sodass dies keine Option zum Freigeben von Daten zwischen einem Dialog und einer anderen Laufzeit ist.

• Um Daten zwischen einem Aufgabenbereich und einem Funktionsbefehl freizugeben, speichern Sie Daten in Window.localStorage, die für alle Laufzeiten freigegeben werden, die auf denselben bestimmten Ursprung zugreifen.

  Hinweis

  Auf LocalStorage kann in einer reinen JavaScript-Runtime nicht zugegriffen werden, und daher ist es in benutzerdefinierten Excel-Funktionen nicht verfügbar. Es kann auch nicht verwendet werden, um Daten für ereignisbasierte Outlook-Aufgaben freizugeben (da diese Aufgaben auf einigen Plattformen eine reine JavaScript-Runtime verwenden).

  Ab Version 115 von Chromium-basierten Browsern wie Chrome und Edge ist die Speicherpartitionierung aktiviert, um bestimmte seitenkanalübergreifende Nachverfolgung zu verhindern (siehe auch Microsoft Edge-Browserrichtlinien). Dies bedeutet, dass von Speicher-APIs gespeicherte Daten, z. B. lokaler Speicher, nur für Kontexte mit demselben Ursprung und demselben Standort der obersten Ebene verfügbar sind.

  Tipp

  Daten in Window.localStorage werden zwischen Sitzungen des Add-Ins beibehalten und von Add-Ins mit demselben Ursprung freigegeben. Beide Eigenschaften sind für ein Add-In häufig unerwünscht.

  • Um sicherzustellen, dass jede Sitzung eines bestimmten Add-Ins neu gestartet wird, rufen Sie die Window.localStorage.clear-Methode auf, wenn das Add-In gestartet wird.
  • Damit einige gespeicherte Werte beibehalten, aber andere Werte erneut initialisiert werden können, verwenden Sie Window.localStorage.setItem , wenn das Add-In für jedes Element gestartet wird, das auf einen Anfangswert zurückgesetzt werden soll.
  • Um ein Element vollständig zu löschen, rufen Sie Window.localStorage.removeItem auf.

• Verwenden Sie OfficeRuntime.storage, um Daten zwischen einer benutzerdefinierten Excel-Funktion und einer beliebigen anderen Laufzeit gemeinsam zu nutzen.

• Um Daten zwischen einer ereignisbasierten Outlook-Aufgabe und einem Aufgabenbereich oder Funktionsbefehl freizugeben, müssen Sie Ihren Code nach dem Wert der Office.context.platform-Eigenschaft verzweigen.

  • Wenn der Wert (Windows) lautet PC , können Sie Daten mithilfe der Office.sessionData-APIs speichern und abrufen.
  • Wenn der Wert ist Mac, verwenden Sie Window.localStorage wie weiter oben in dieser Liste beschrieben.

Weitere Möglichkeiten zum Freigeben von Daten sind die folgenden:

• Speichern Sie freigegebene Daten in einer Onlinedatenbank, auf die für alle Runtimes zugegriffen werden kann.
• Speichern Sie freigegebene Daten in einem Cookie für die Domäne des Add-Ins, um sie zwischen Browserruntimes freizugeben. Reine JavaScript-Runtimes unterstützen keine Cookies.

Weitere Informationen finden Sie unter Beibehalten des Add-In-Zustands und -Einstellungen und Abrufen und Festlegen von Add-In-Metadaten für ein Outlook-Add-In.

Reine JavaScript-Runtime

Die reine JavaScript-Runtime, die in Office-Add-Ins verwendet wird, ist eine Änderung einer Open-Source-Runtime, die ursprünglich für React Native erstellt wurde. Es enthält eine JavaScript-Engine, die mit Unterstützung für WebSockets, full CORS (Cross-Origin Resource Sharing) und OfficeRuntime.storage ergänzt wird. Es verfügt nicht über eine Rendering-Engine und unterstützt keine Cookies oder lokalen Speicher.

Diese Art von Laufzeit wird nur in ereignisbasierten Add-Ins und Spamberichts-Add-Ins im klassischen Outlook unter Windows und in benutzerdefinierten Excel-Funktionen verwendet, außer wenn die benutzerdefinierten Funktionen eine Laufzeit gemeinsam nutzen.

• Bei Verwendung für eine benutzerdefinierte Excel-Funktion wird die Laufzeit gestartet, wenn entweder das Arbeitsblatt neu berechnet oder die benutzerdefinierte Funktion berechnet wird. Sie wird erst heruntergefahren, wenn die Arbeitsmappe geschlossen wird.

• Bei Verwendung in einem Outlook-Ereignis- oder Spamberichts-Add-In wird die Laufzeit gestartet, wenn das Ereignis auftritt. Es endet, wenn der erste der folgenden Auftritte auftritt.

  • Der Ereignishandler ruft die completed -Methode seines Ereignisparameters auf.
  • Seit dem auslösenden Ereignis sind fünf Minuten vergangen.
  • Der Benutzer ändert den Fokus von dem Fenster, in dem das Ereignis ausgelöst wurde, z. B. ein Fenster zum Verfassen von Nachrichten (gilt nur für ereignisbasierte Add-Ins).

  Hinweis

  Die funktionen für die ereignisbasierte Aktivierung und die integrierte Spamberichterstattung in Outlook müssen dieselbe Laufzeit verwenden. Mehrere Runtimes werden in Outlook derzeit nicht unterstützt.

Eine reine JavaScript-Runtime benötigt weniger Arbeitsspeicher und startet schneller als eine Browserruntime, verfügt aber über weniger Features.

Wichtig

In Office für Windows-Versionen vor 2403 (Build 16.0.17425.20000) und unbefristeten Lizenzen von Office bis Office 2021 unterstützt die reine JavaScript-Runtime direkt den ECMAScript 2016-Standard von JavaScript. Sie können jedoch höhere Versionen von JavaScript oder TypeScript verwenden. Informationen dazu finden Sie unter Unterstützung für aktuelle JavaScript-Versionen.

Browserruntime

Office-Add-Ins verwenden eine andere Browserlaufzeit, abhängig von der Plattform, auf der Office ausgeführt wird (Web, Mac oder Windows), sowie von der Version und dem Build von Windows und Office. Wenn der Benutzer beispielsweise Office im Web in einem FireFox-Browser ausführt, wird die Firefox-Runtime verwendet. Wenn der Benutzer Office auf dem Mac ausführt, wird die Safari-Runtime verwendet. Wenn der Benutzer Office unter Windows ausführt, stellt entweder ein Edge oder Internet Explorer die Runtime bereit, abhängig von der Version von Windows und Office. Details finden Sie unter Browser und Webview-Steuerelemente, die von Office-Add-Ins verwendet werden.

Alle diese Runtimes enthalten eine HTML-Rendering-Engine und bieten Unterstützung für WebSockets, full CORS (Cross-Origin Resource Sharing) und lokalen Speicher sowie Cookies.

Die Lebensdauer einer Browserlaufzeit variiert je nach implementiertem Feature und davon, ob sie freigegeben wird oder nicht.

• Wenn ein Add-In mit einem Aufgabenbereich gestartet wird, wird eine Browserruntime gestartet, es sei denn, es handelt sich um eine freigegebene Runtime, die bereits ausgeführt wird. Wenn es sich um eine freigegebene Runtime handelt, wird sie heruntergefahren, wenn das Dokument geschlossen wird. Wenn es sich nicht um eine freigegebene Runtime handelt, wird sie heruntergefahren, wenn der Aufgabenbereich geschlossen wird.

• Wenn ein Dialogfeld geöffnet wird, wird eine Browserruntime gestartet. Sie wird heruntergefahren, wenn das Dialogfeld geschlossen wird.

• Wenn ein Funktionsbefehl ausgeführt wird (was geschieht, wenn ein Benutzer seine Schaltfläche oder sein Menüelement auswählt), wird eine Browserruntime gestartet, es sei denn, es handelt sich um eine freigegebene Runtime, die bereits ausgeführt wird. Wenn es sich um eine freigegebene Runtime handelt, wird sie heruntergefahren, wenn das Dokument geschlossen wird. Wenn es sich nicht um eine freigegebene Runtime handelt, wird sie beim ersten der folgenden Aktionen heruntergefahren.

  • Der Funktionsbefehl ruft die completed -Methode des -Ereignisparameters auf.
  • Seit dem auslösenden Ereignis sind fünf Minuten vergangen. (Wenn ein Dialogfeld im Funktionsbefehl geöffnet wurde und es immer noch geöffnet ist, wenn die übergeordnete Laufzeit ein Timeout aufweist, wird die Dialogruntime so lange ausgeführt, bis der Dialog geschlossen wird.)

• Wenn eine benutzerdefinierte Excel-Funktion eine freigegebene Runtime verwendet, wird eine Browserruntime gestartet, wenn die benutzerdefinierte Funktion berechnet, ob die freigegebene Runtime nicht bereits aus einem anderen Grund gestartet wurde. Es wird heruntergefahren, wenn das Dokument geschlossen wird.

Hinweis

Wenn eine Runtime freigegeben wird, ist es möglich, dass Ihr Code den Aufgabenbereich schließt, ohne das Add-In herunterzufahren. Weitere Informationen finden Sie unter Ein- oder Ausblenden des Aufgabenbereichs Ihres Office-Add-Ins .

Eine Browserruntime verfügt über mehr Features als eine reine JavaScript-Runtime, startet jedoch langsamer und verwendet mehr Arbeitsspeicher.

Freigegebene Runtime

Eine "freigegebene Runtime" ist kein Laufzeittyp. Es bezieht sich auf eine Browserlaufzeit , die von Features des Add-Ins gemeinsam genutzt wird, die andernfalls jeweils über eine eigene Runtime verfügen würden. Insbesondere haben Sie die Möglichkeit, den Aufgabenbereich und die Funktionsbefehle des Add-Ins so zu konfigurieren, dass eine Laufzeit gemeinsam verwendet wird. In einem Excel-Add-In können Sie auch benutzerdefinierte Funktionen so konfigurieren, dass die Laufzeit eines Aufgabenbereichs oder Funktionsbefehls oder beides gemeinsam verwendet wird. Wenn Sie dies tun, werden die benutzerdefinierten Funktionen in einer Browserlaufzeit anstelle einer reinen JavaScript-Runtime ausgeführt, wie dies andernfalls der Fall wäre. Unter Konfigurieren Ihres Add-Ins für die Verwendung einer freigegebenen Runtime finden Sie Informationen zu den Vorteilen und Einschränkungen von Freigaberuntimes sowie Anweisungen zum Konfigurieren des Add-Ins für die Verwendung einer freigegebenen Runtime. Kurz gesagt: Die reine JavaScript-Runtime benötigt weniger Arbeitsspeicher und startet schneller, verfügt aber über weniger Features.

Hinweis

• Laufzeiten können nur in Excel, PowerPoint und Word freigegeben werden.
• Sie können ein Dialogfeld nicht so konfigurieren, dass eine Runtime freigegeben wird. Jedes Dialogfeld verfügt immer über einen eigenen Dialog, es sei denn, der Dialog wird in Office im Web gestartet, wobei die displayInIFrame Option auf truefestgelegt ist.
• Eine freigegebene Runtime verwendet niemals die ursprüngliche Microsoft Edge WebView-Runtime (EdgeHTML). Wenn die Bedingungen für die Verwendung von Microsoft Edge mit WebView2 (Chromium-basiert) erfüllt sind (wie unter Browser und Webview-Steuerelemente angegeben, die von Office-Add-Ins verwendet werden), wird diese Runtime verwendet. Andernfalls wird die Internet Explorer 11-Runtime verwendet.