Konfigurieren Ihres Office-Add-Ins für die Verwendung einer freigegebenen Runtime

  • Artikel

Wichtig

Die freigegebene Runtime wird nur in einigen Office-Anwendungen unterstützt. Weitere Informationen finden Sie unter Gemeinsame Laufzeitanforderungsgruppen.

Sie können Ihr Office-Add-In so konfigurieren, dass der gesamte Code in einer einzelnen freigegebenen Runtime ausgeführt wird. Dies ermöglicht eine bessere Koordination im gesamten Add-In sowie Zugriff auf DOM und CORS aus allen Teilen des Add-In. Sie ermöglicht auch zusätzliche Funktionen wie das Ausführen von Code beim Öffnen des Dokuments oder das Aktivieren oder Deaktivieren von Menüband-Schaltflächen. Wenn Sie Ihr Add-In für die Verwendung einer freigegebenen Laufzeit konfigurieren möchten, folgen Sie den Anleitungen in diesem Artikel.

Erstellen des Add-In-Projekts

Wenn Sie ein neues Projekt starten, verwenden Sie den Yeoman-Generator für Office-Add-Ins, um ein Excel-, PowerPoint- oder Word-Add-In-Projekt zu erstellen.

Führen Sie den Befehl ausyo office --projectType taskpane --name "my office add in" --host <host> --js true, wobei <host>einer der folgenden Werte ist.

  • Excel
  • PowerPoint
  • Wort

Wichtig

Der --name Argumentwert muss in doppelten Anführungszeichen stehen, auch wenn er keine Leerzeichen aufweist.

Sie können verschiedene Optionen für die Befehlszeilenoptionen --projecttype, --name und --js verwenden. Die vollständige Liste der Optionen finden Sie unter Yeoman-Generator für Office-Add-Ins.

Der Generator erstellt das Projekt und installiert unterstützende Node-Komponenten. Sie können auch die Schritte in diesem Artikel verwenden, um ein vorhandenes Visual Studio-Projekt zu aktualisieren, um die freigegebene Laufzeit zu verwenden. Möglicherweise müssen Sie jedoch die XML-Schemas für das Manifest aktualisieren. Weitere Informationen finden Sie unter Problembehandlung von Entwicklungsfehlern mit Office-Add-Ins.

Konfigurieren des Manifests

Führen Sie die folgenden Schritte aus, um ein neues oder vorhandenes Projekt für die Verwendung einer freigegebenen Laufzeit zu konfigurieren. Diese Schritte gehen davon aus, dass Sie Ihr Projekt mithilfe des Yeoman-Generator für Office-Add-Ins erstellt haben.

  1. Starten Sie Visual Studio Code, und öffnen Sie das Add-In-Projekt, das Sie generiert haben.

  2. Öffnen Sie die Datei manifest.xml.

  3. Aktualisieren Sie für ein Excel- oder PowerPoint-Add-In den Abschnitt "Anforderungen", um die freigegebene Laufzeit einzuschließen. Achten Sie darauf, die CustomFunctionsRuntime Anforderung zu entfernen, wenn sie vorhanden ist. Das XML sollte wie folgt angezeigt werden.

    <Hosts>
  <Host Name="Workbook"/>
</Hosts>
<Requirements>
  <Sets DefaultMinVersion="1.1">
    <Set Name="SharedRuntime" MinVersion="1.1"/>
  </Sets>
</Requirements>
<DefaultSettings>

  4. Suchen Sie den <Abschnitt VersionOverrides,> und fügen Sie den folgenden <Abschnitt Runtimes> hinzu. Die Lebensdauer muss long sein, damit Ihr Add-In-Code auch dann weiterhin läuft, wenn der Aufgabenbereich geschlossen wird. Der Wert resid lautet Taskpane.Url und verweist auf den Speicherort der Datei taskpane.html, der im Abschnitt <bt:Urls> am unteren Rand der Datei manifest.xml angegeben ist.

    Wichtig

    Die freigegebene Runtime wird nicht geladen, wenn im resid Manifest unterschiedliche Werte verwendet werden. Wenn Sie den Wert in einen anderen Wert als Taskpane.Url ändern, stellen Sie sicher, dass Sie auch den Wert an allen Speicherorten ändern, die in den folgenden Schritten in diesem Artikel gezeigt werden.

    Außerdem muss der <Abschnitt Runtimes> nach dem <Host-Element> in der genauen Reihenfolge eingegeben werden, die im folgenden XML-Code gezeigt wird.

    <VersionOverrides ...>
  <Hosts>
    <Host ...>
      <Runtimes>
        <Runtime resid="Taskpane.Url" lifetime="long" />
      </Runtimes>
    ...
    </Host>

  5. Wenn Sie ein Excel-Add-In mit benutzerdefinierten Funktionen generiert haben, suchen Sie das <Page-Element> . Ändern Sie dann den Quellspeicherort von Functions.Page.Url in Taskpane.Url.

    <AllFormFactors>
...
<Page>
  <SourceLocation resid="Taskpane.Url"/>
</Page>
...

  6. Suchen Sie das <FunctionFile-Tag> , und ändern Sie von residCommands.Url in Taskpane.Url. Beachten Sie, dass Sie ohne Aktionsbefehle keinen FunctionFile-Eintrag> haben< und diesen Schritt überspringen können.

    </GetStarted>
...
<FunctionFile resid="Taskpane.Url"/>
...

  7. Speichern Sie die Datei manifest.xml.

Konfigurieren der Datei webpack.config.js

Die Datei webpack.config.js wird mehrere Runtime-Lader erstellen. Sie müssen sie so ändern, dass nur die freigegebene Runtime über die taskpane.html-Datei geladen wird.

  1. Starten Sie Visual Studio Code, und öffnen Sie das Add-In-Projekt, das Sie generiert haben.

  2. Öffnen Sie die Datei webpack.config.js.

  3. Wenn Ihre Datei webpack.config.js den folgenden Plug-In-Code functions.html enthält, dann entfernen Sie diesen.

    new HtmlWebpackPlugin({
    filename: "functions.html",
    template: "./src/functions/functions.html",
    chunks: ["polyfill", "functions"]
  })

  4. Wenn Ihre Datei webpack.config.js den folgenden Plug-In-Code commands.html enthält, dann entfernen Sie diesen.

    new HtmlWebpackPlugin({
    filename: "commands.html",
    template: "./src/commands/commands.html",
    chunks: ["polyfill", "commands"]
  })

  5. Wenn Ihr Projekt entweder die Blöcke Funktionen oder Befehle verwendet hat, fügen Sie diese wie im Folgenden gezeigt zur Blockliste hinzu (der folgende Code gilt, wenn Ihr Projekt beide Blöcke verwendet hat).

      new HtmlWebpackPlugin({
    filename: "taskpane.html",
    template: "./src/taskpane/taskpane.html",
    chunks: ["polyfill", "taskpane", "commands", "functions"]
  })

  6. Speichern Sie Ihre Änderungen, und erstellen Sie das Projekt neu.

    npm run build

Hinweis

Wenn Ihr Projekt eine Datei functions.html oder commands.html beinhaltet, können diese entfernt werden. Die taskpane.html lädt die functions.js und commands.js Code über die webpack-Updates, die Sie gerade vorgenommen haben, in die freigegebene Runtime.

Testen Ihrer Office-Add-In-Änderungen

Mithilfe der folgenden Anweisungen können Sie bestätigen, dass Sie die freigegebene Runtime ordnungsgemäß verwenden.

  1. Öffnen Sie die taskpane.js Datei.

  2. Ersetzen Sie den gesamten Inhalt der Datei durch den folgenden Code: Dadurch wird die Anzahl angezeigt, wie oft der Aufgabenbereich geöffnet wurde. Das Hinzufügen des onVisibilityModeChanged-Ereignisses wird nur in einer freigegebenen Runtime unterstützt.

    /*global document, Office*/

let _count = 0;

Office.onReady(() => {
  document.getElementById("sideload-msg").style.display = "none";
  document.getElementById("app-body").style.display = "flex";

  updateCount(); // Update count on first open.
  Office.addin.onVisibilityModeChanged(function (args) {
    if (args.visibilityMode === "Taskpane") {
      updateCount(); // Update count on subsequent opens.
    }
  });
});

function updateCount() {
  _count++;
  document.getElementById("run").textContent = "Task pane opened " + _count + " times.";
}

  3. Speichern Sie die Änderungen, und führen Sie die Projekt aus.

    npm start

Jedes Mal, wenn Sie den Aufgabenbereich öffnen, wird die Anzahl der Geöffneten erhöht. Der Wert von _count geht nicht verloren, da die freigegebene Laufzeit den Code auch dann weiter ausführt, wenn der Aufgabenbereich geschlossen wird.

Lebensdauer der Laufzeit

Wenn Sie das <Runtime-Element> hinzufügen, geben Sie auch eine Lebensdauer mit dem Wert oder shortanlong. Legen Sie diesen Wert auf long fest, um bestimmte Features nutzen zu können, beispielsweise den Start Ihres Add-Ins beim Öffnen des Dokuments, die Fortsetzung der Codeausführung nach dem Schließen des Aufgabenbereichs oder die Verwendung von CORS und DOM aus benutzerdefinierten Funktionen.

Hinweis

Der Standardwert für die Lebensdauer ist short, aber wir empfehlen die Verwendung long in Excel-, PowerPoint- und Word-Add-Ins. Wenn Sie die Laufzeit short in diesem Beispiel festlegen, wird das Add-In gestartet, wenn eine der Menübandschaltflächen gedrückt wird. Es wird jedoch möglicherweise beendet, nachdem der Menübandhandler ausgeführt wurde. In ähnlicher Weise wird Ihr Add-In beim Öffnen des Aufgabenbereichs gestartet, beim Schließen des Bereichs aber möglicherweise heruntergefahren.

<Runtimes>
  <Runtime resid="Taskpane.Url" lifetime="long" />
</Runtimes>

Hinweis

Wenn Ihr Add-In das <Runtimes-Element> im Manifest enthält (für eine freigegebene Runtime erforderlich) und die Bedingungen für die Verwendung von WebView2 (Microsoft Edge Chromium-basiert) erfüllt sind, wird dieses Steuerelement verwendet. Wenn die Bedingungen nicht erfüllt sind, wird das Webview-Steuerelement Trident (Internet Explorer 11) unabhängig von der Windows- oder Microsoft 365-Version verwendet. Weitere Informationen finden Sie unter Runtimes und Browser und Webview-Steuerelemente, die von Office-Add-Ins verwendet werden.

Informationen zur freigegebenen Runtime

Unter Windows oder Mac führt Ihr Add-In Code für Menübandschaltflächen, benutzerdefinierte Funktionen und den Aufgabenbereich in separaten Laufzeitumgebungen aus. Dies verursacht Einschränkungen – beispielsweise, dass eine einfache Freigabe globaler Daten und der Zugriff auf die gesamte CORS-Funktionalität aus einer benutzerdefinierten Funktion nicht möglich ist.

Sie können Ihr Office-Add-In jedoch so konfigurieren, dass Code in derselben Runtime (auch als freigegebene Runtime bezeichnet) freigegeben wird. Dies ermöglicht eine bessere Koordination im gesamten Add-in sowie Zugriff auf den Aufgabenbereich DOM und CORS aus allen Teilen des Add-Ins.

Das Konfigurieren einer freigegebenen Runtime ermöglicht die folgenden Szenarien.

Für Office unter Windows verwendet die freigegebene Runtime WebView2 (Microsoft Edge Chromium-basiert), wenn die Bedingungen für die Verwendung erfüllt sind, wie unter Browser und Webview-Steuerelemente von Office-Add-Ins erläutert. Andernfalls wird Trident (Internet Explorer 11) verwendet. Darüber hinaus werden alle Schaltflächen, die Ihr Add-In im Menüband anzeigt, in derselben freigegebenen Runtime ausgeführt. Die folgende Abbildung zeigt, wie benutzerdefinierte Funktionen, die Menübandbenutzeroberfläche und der Aufgabenbereichscode in derselben Laufzeit ausgeführt werden.

Diagramm einer benutzerdefinierten Funktion, eines Aufgabenbereichs und von Menüband-Schaltflächen, die alle in einer gemeinsam genutzten Browserruntime in Excel ausgeführt werden.

Debuggen

Wenn Sie eine freigegebene Laufzeit verwenden, können Sie benutzerdefinierte Funktionen in Excel unter Windows zu diesem Zeitpunkt nicht mithilfe von Visual Studio Code debuggen. Sie müssen stattdessen Entwicklertools verwenden. Weitere Informationen finden Sie unter Debuggen von Add-Ins mithilfe von Entwicklertools für Internet Explorer oder Debuggen von Add-Ins mithilfe von Entwicklertools in Microsoft Edge (auf der Basis von Chromium).

Mehrere Aufgabenbereiche

Entwerfen Sie Ihr Add-in nicht für die Verwendung mehrerer Aufgabenbereiche, wenn Sie eine freigegebene Laufzeit verwenden möchten. Eine freigegebene Laufzeit unterstützt nur die Verwendung eines Aufgabenbereichs. Hinweis: Ein Aufgabenbereich ohne eine <TaskpaneID> wird als ein anderer Aufgabenbereich betrachtet.

Siehe auch