Outlook-Add-In-Manifeste

Ein Outlook-Add-In besteht aus zwei Komponenten: dem XML-Add-In-Manifest und einer Webseite, die von der JavaScript-Bibliothek für Office-Add-Ins (office.js) unterstützt wird. Das Manifest beschreibt, wie das Add-In in Outlook-Clients integriert wird. Es folgt ein Beispiel.

Hinweis Alle URL-Werte im folgenden Beispiel beginnen mit „https://appdemo.contoso.com“. Dies ist ein Platzhalter. In einem gültigen Manifest würden diese Werte gültige https web-URLs enthalten.

<?xml version="1.0" encoding="UTF-8" ?>
<!--Created:cb85b80c-f585-40ff-8bfc-12ff4d0e34a9-->
<OfficeApp
  xmlns="http://schemas.microsoft.com/office/appforoffice/1.1"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:bt="http://schemas.microsoft.com/office/officeappbasictypes/1.0"
  xmlns:mailappor="http://schemas.microsoft.com/office/mailappversionoverrides/1.0"
  xsi:type="MailApp">
  <Id>7164e750-dc86-49c0-b548-1bac57abdc7c</Id>
  <Version>1.0.0.0</Version>
  <ProviderName>Microsoft Outlook Dev Center</ProviderName>
  <DefaultLocale>en-US</DefaultLocale>
  <DisplayName DefaultValue="Add-in Command Demo" />
  <Description DefaultValue="Adds command buttons to the ribbon in Outlook"/>
  <IconUrl DefaultValue="https://appdemo.contoso.com/images/blue-64.png" />
  <HighResolutionIconUrl DefaultValue="https://appdemo.contoso.com/images/blue-80.png" />
  <Hosts>
    <Host Name="Mailbox" />
  </Hosts>
  <Requirements>
    <Sets>
      <Set Name="MailBox" MinVersion="1.1" />
    </Sets>
  </Requirements>
  <!-- These elements support older clients that don't support add-in commands -->
  <FormSettings>
    <Form xsi:type="ItemRead">
      <DesktopSettings>
        <!-- NOTE: Just reusing the read taskpane page that is invoked by the button
             on the ribbon in clients that support add-in commands. You can 
             use a completely different page if desired -->
        <SourceLocation DefaultValue="https://appdemo.contoso.com/AppRead/TaskPane/TaskPane.html"/>
        <RequestedHeight>450</RequestedHeight>
      </DesktopSettings>
    </Form>
  </FormSettings>
  <Permissions>ReadWriteItem</Permissions>
  <Rule xsi:type="RuleCollection" Mode="Or">
    <Rule xsi:type="ItemIs" ItemType="Message" FormType="Read" />
  </Rule>
  <DisableEntityHighlighting>false</DisableEntityHighlighting>

  <VersionOverrides xmlns="http://schemas.microsoft.com/office/mailappversionoverrides" xsi:type="VersionOverridesV1_0">

    <Requirements>
      <bt:Sets DefaultMinVersion="1.3">
        <bt:Set Name="Mailbox" />
      </bt:Sets>
    </Requirements>

    <Hosts>
      <Host xsi:type="MailHost">
        <DesktopFormFactor>
          <FunctionFile resid="functionFile" />

          <!-- Message read form -->
          <ExtensionPoint xsi:type="MessageReadCommandSurface">
            <OfficeTab id="TabDefault">
              <Group id="msgReadDemoGroup">
                <Label resid="groupLabel" />
                <!-- Function (UI-less) button -->
                <Control xsi:type="Button" id="msgReadFunctionButton">
                  <Label resid="funcReadButtonLabel" />
                  <Supertip>
                    <Title resid="funcReadSuperTipTitle" />
                    <Description resid="funcReadSuperTipDescription" />
                  </Supertip>
                  <Icon>
                    <bt:Image size="16" resid="blue-icon-16" />
                    <bt:Image size="32" resid="blue-icon-32" />
                    <bt:Image size="80" resid="blue-icon-80" />
                  </Icon>
                  <Action xsi:type="ExecuteFunction">
                    <FunctionName>getSubject</FunctionName>
                  </Action>
                </Control>
                <!-- Menu (dropdown) button -->
                <Control xsi:type="Menu" id="msgReadMenuButton">
                  <Label resid="menuReadButtonLabel" />
                  <Supertip>
                    <Title resid="menuReadSuperTipTitle" />
                    <Description resid="menuReadSuperTipDescription" />
                  </Supertip>
                  <Icon>
                    <bt:Image size="16" resid="red-icon-16" />
                    <bt:Image size="32" resid="red-icon-32" />
                    <bt:Image size="80" resid="red-icon-80" />
                  </Icon>
                  <Items>
                    <Item id="msgReadMenuItem1">
                      <Label resid="menuItem1ReadLabel" />
                      <Supertip>
                        <Title resid="menuItem1ReadLabel" />
                        <Description resid="menuItem1ReadTip" />
                      </Supertip>
                      <Icon>
                        <bt:Image size="16" resid="red-icon-16" />
                        <bt:Image size="32" resid="red-icon-32" />
                        <bt:Image size="80" resid="red-icon-80" />
                      </Icon>
                      <Action xsi:type="ExecuteFunction">
                        <FunctionName>getItemClass</FunctionName>
                      </Action>
                    </Item>
                    <Item id="msgReadMenuItem2">
                      <Label resid="menuItem2ReadLabel" />
                      <Supertip>
                        <Title resid="menuItem2ReadLabel" />
                        <Description resid="menuItem2ReadTip" />
                      </Supertip>
                      <Icon>
                        <bt:Image size="16" resid="red-icon-16" />
                        <bt:Image size="32" resid="red-icon-32" />
                        <bt:Image size="80" resid="red-icon-80" />
                      </Icon>
                      <Action xsi:type="ExecuteFunction">
                        <FunctionName>getDateTimeCreated</FunctionName>
                      </Action>
                    </Item>
                    <Item id="msgReadMenuItem3">
                      <Label resid="menuItem3ReadLabel" />
                      <Supertip>
                        <Title resid="menuItem3ReadLabel" />
                        <Description resid="menuItem3ReadTip" />
                      </Supertip>
                      <Icon>
                        <bt:Image size="16" resid="red-icon-16" />
                        <bt:Image size="32" resid="red-icon-32" />
                        <bt:Image size="80" resid="red-icon-80" />
                      </Icon>
                      <Action xsi:type="ExecuteFunction">
                        <FunctionName>getItemID</FunctionName>
                      </Action>
                    </Item>
                  </Items>
                </Control>
                <!-- Task pane button -->
                <Control xsi:type="Button" id="msgReadOpenPaneButton">
                  <Label resid="paneReadButtonLabel" />
                  <Supertip>
                    <Title resid="paneReadSuperTipTitle" />
                    <Description resid="paneReadSuperTipDescription" />
                  </Supertip>
                  <Icon>
                    <bt:Image size="16" resid="green-icon-16" />
                    <bt:Image size="32" resid="green-icon-32" />
                    <bt:Image size="80" resid="green-icon-80" />
                  </Icon>
                  <Action xsi:type="ShowTaskpane">
                    <SourceLocation resid="readTaskPaneUrl" />
                  </Action>
                </Control>
              </Group>
            </OfficeTab>
          </ExtensionPoint>
        </DesktopFormFactor>
      </Host>
    </Hosts>

    <Resources>
      <bt:Images>
        <!-- Blue icon -->
        <bt:Image id="blue-icon-16" DefaultValue="https://appdemo.contoso.com/images/blue-16.png" />
        <bt:Image id="blue-icon-32" DefaultValue="https://appdemo.contoso.com/images/blue-32.png" />
        <bt:Image id="blue-icon-80" DefaultValue="https://appdemo.contoso.com/images/blue-80.png" />
        <!-- Red icon -->
        <bt:Image id="red-icon-16" DefaultValue="https://appdemo.contoso.com/images/red-16.png" />
        <bt:Image id="red-icon-32" DefaultValue="https://appdemo.contoso.com/images/red-32.png" />
        <bt:Image id="red-icon-80" DefaultValue="https://appdemo.contoso.com/images/red-80.png" />
        <!-- Green icon -->
        <bt:Image id="green-icon-16" DefaultValue="https://appdemo.contoso.com/images/green-16.png" />
        <bt:Image id="green-icon-32" DefaultValue="https://appdemo.contoso.com/images/green-32.png" />
        <bt:Image id="green-icon-80" DefaultValue="https://appdemo.contoso.com/images/green-80.png" />
      </bt:Images>
      <bt:Urls>
        <bt:Url id="functionFile" DefaultValue="https://appdemo.contoso.com/FunctionFile/Functions.html" />
        <bt:Url id="readTaskPaneUrl" DefaultValue="https://appdemo.contoso.com/AppRead/TaskPane/TaskPane.html" />
      </bt:Urls>
      <bt:ShortStrings>
        <bt:String id="groupLabel" DefaultValue="Add-in Demo" />
        <bt:String id="funcReadButtonLabel" DefaultValue="Get subject" />
        <bt:String id="menuReadButtonLabel" DefaultValue="Get property" />
        <bt:String id="paneReadButtonLabel" DefaultValue="Display all properties" />

        <bt:String id="funcReadSuperTipTitle" DefaultValue="Gets the subject of the message or appointment" />
        <bt:String id="menuReadSuperTipTitle" DefaultValue="Choose a property to get" />
        <bt:String id="paneReadSuperTipTitle" DefaultValue="Get all properties" />

        <bt:String id="menuItem1ReadLabel" DefaultValue="Get item class" />
        <bt:String id="menuItem2ReadLabel" DefaultValue="Get date time created" />
        <bt:String id="menuItem3ReadLabel" DefaultValue="Get item ID" />
      </bt:ShortStrings>
      <bt:LongStrings>
        <bt:String id="funcReadSuperTipDescription" DefaultValue="Gets the subject of the message or appointment and displays it in the info bar. This is an example of a function button." />
        <bt:String id="menuReadSuperTipDescription" DefaultValue="Gets the selected property of the message or appointment and displays it in the info bar. This is an example of a drop-down menu button." />
        <bt:String id="paneReadSuperTipDescription" DefaultValue="Opens a pane displaying all available properties of the message or appointment. This is an example of a button that opens a task pane." />

        <bt:String id="menuItem1ReadTip" DefaultValue="Gets the item class of the message or appointment and displays it in the info bar." />
        <bt:String id="menuItem2ReadTip" DefaultValue="Gets the date and time the message or appointment was created and displays it in the info bar." />
        <bt:String id="menuItem3ReadTip" DefaultValue="Gets the item ID of the message or appointment and displays it in the info bar." />
      </bt:LongStrings>
    </Resources>
  </VersionOverrides>
</OfficeApp>

Schemaversionen

Nicht alle Outlook-Clients bieten Unterstützung für die neuesten Funktionen. Einige Outlook-Benutzer verwenden möglicherweise eine ältere Version von Outlook. Mit den Schemaversionen können Entwickler Add-Ins erstellen, die abwärtskompatibel sind, und so die neusten Funktionen verwenden, wo diese verfügbar sind, die gleichzeitig auch in älteren Versionen funktionieren.

Das VersionOverrides-Element in der Manifestdatei ist ein Beispiel dafür. Alle Elemente, die innerhalb von VersionOverrides definiert sind, überschreiben dasselbe Element im anderen Teil des Manifests. Dies bedeutet, dass Outlook möglichst die Elemente aus dem VersionOverrides-Abschnitt verwendet, um das Add-In einzurichten. Wenn die Version von Outlook jedoch eine bestimmte Version von VersionOverrides nicht unterstützt, ignoriert Outlook sie und verwendet die Informationen im Rest des Manifests.

Dieser Ansatz bedeutet, dass Entwickler nicht mehrere einzelne Manifeste erstellen müssen, sondern alles in einer Datei definieren können.

Die aktuellen Versionen des Schemas sind:

Version Beschreibung
v1.0 Unterstützt Version 1.0 der JavaScript-API für Office. Für Outlook-Add-Ins wird das Leseformular unterstützt.
v1.1 Unterstützt Version 1.1 der JavaScript-API für Office und VersionOverrides. Für Outlook-Add-Ins wird Unterstützung für das Entwurfsformular hinzugefügt.
VersionOverrides 1.0 Unterstützt neuere Versionen der JavaScript-API für Office. Dies unterstützt Add-In-Befehle.
VersionOverrides 1.1 Unterstützt neuere Versionen der JavaScript-API für Office. Dies unterstützt Add-In-Befehle und bietet zusätzliche Unterstützung für neuere Funktionen, z. B. anheftbare Aufgabenbereiche und mobile Add-Ins.

In diesem Artikel werden die Anforderungen für ein Manifest der Version 1.1 erläutert. Auch wenn Ihr Add-In-Manifest das VersionOverrides-Element verwendet, ist es dennoch wichtig, Manifestelemente der Version 1.1 einzufügen, damit Ihre App mit älteren Clients funktioniert, die VersionOverrides nicht unterstützten.

Hinweis: Outlook verwendet ein Schema zum Überprüfen von Manifesten. Das Schema erfordert, dass Elemente im Manifest in einer bestimmten Reihenfolge angezeigt werden. Wenn Sie Elemente einschließen, die nicht in der erforderlichen Reihenfolge sind, treten beim Querladen Ihres Add-Ins möglicherweise Fehler auf. Sie können die Schemadefinitionen von GitHub herunterladen, um Ihr Manifest mit den Elementen in der erforderlichen Reihenfolge zu erstellen.

Stammelement

Das Stammelement für das Outlook-Add-In-Manifest ist OfficeApp. Dieses Element deklariert auch den Standard-Namespace, die Schemaversion und den Typ des Add-Ins. Platzieren Sie alle anderen Elemente im Manifest innerhalb der öffnenden und schließenden Tags. Der folgende Code ist ein Beispiel des Stammelements:

<OfficeApp
  xmlns="http://schemas.microsoft.com/office/appforoffice/1.1"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:bt="http://schemas.microsoft.com/office/officeappbasictypes/1.0"
  xmlns:mailappor="http://schemas.microsoft.com/office/mailappversionoverrides/1.0"
  xsi:type="MailApp">

  <!-- the rest of the manifest -->

</OfficeApp>

Version

Dies ist die Version des bestimmten Add-Ins. Wenn ein Entwickler etwas in dem Manifest aktualisiert, muss die Version ebenfalls erhöht werden. So wird beim Installieren des neuen Manifests das vorhandenen überschrieben, und der Benutzer erhält neue Funktionen. Wenn dieses Add-In an den Store übermittelt wurde, muss das neue Manifest erneut gesendet und überprüft werden. Sobald es genehmigt wurde, wird das Manifest innerhalb einiger Stunden für die Benutzer dieses Add-Ins automatisch aktualisiert.

Wenn sich die angeforderten Berechtigungen des Add-Ins ändern, werden die Benutzer aufgefordert, eine Aktualisierung durchzuführen und dem Add-In erneut zuzustimmen. Wenn der Administrator dieses Add-In für die gesamte Organisation installiert hat, muss der Administrator zuerst erneut zustimmen. Für Benutzer werden in der Zwischenzeit weiterhin die alten Funktionen angezeigt.

VersionOverrides

Das VersionOverrides-Element ist der Ort, an dem sich Informationen für Add-In-Befehle befinden. Weitere Informationen zu diesem Element finden Sie unter Definieren von Add-In-Befehlen in Ihrem Manifest.

In diesem Element wird auf die Unterstützung für mobile Add-Ins in den Add-Ins definiert.

Lokalisierung

Einige Aspekte des Add-Ins müssen für unterschiedliche Gebietsschemas lokalisiert werden, z. B. der Name, die Beschreibung und die URL, die geladen wird. Diese Elemente können ganz einfach durch die Angabe des Standardwerts und anschließende Gebietsschemaüberschreibungen im Ressourcen-Element innerhalb des VersionOverrides-Element lokalisiert werden. Die folgende Abbildung zeigt, wie ein Bild, eine URL und eine Zeichenfolge überschrieben werden:

<Resources>
  <bt:Images>
    <bt:Image id="icon1_16x16" DefaultValue="https://contoso.com/images/app_icon_small.png" >
      <bt:Override Locale="ar-sa" Value="https://contoso.com/images/app_icon_small_arsa.png" />
      <!-- add information for other locales -->
    </bt:Image>
  </bt:Images>

  <bt:Urls>
    <bt:Url id="residDesktopFuncUrl" DefaultValue="https://contoso.com/urls/page_appcmdcode.html" >
      <bt:Override Locale="ar-sa" Value="https://contoso.com/urls/page_appcmdcode.html?lcid=ar-sa" />
      <!-- add information for other locales -->
    </bt:Url>
  </bt:Urls>

  <bt:ShortStrings> 
    <bt:String id="residViewTemplates" DefaultValue="Launch My Add-in">
      <bt:Override Locale="ar-sa" Value="<add localized value here>" />
      <!-- add information for other locales -->
    </bt:String>
  </bt:ShortStrings>
</Resources>

Die Schemareferenz enthält umfassende Informationen dazu, welche Elemente lokalisiert werden können.

Hosts

Outlook-Add-Ins geben das Hosts-Element folgendermaßen an:

<OfficeApp>
...
  <Hosts>
    <Host Name="Mailbox" />
  </Hosts>
...
</OfficeApp>

Dies unterscheidet sich von dem Hosts-Element innerhalb des VersionOverrides-Elements, das in Definieren von Add-In-Befehlen in Ihrem Manifest erläutert wird.

Anforderungen

Das Requirements-Element gibt den Satz von APIs für das Add-In an. Für ein Outlook-Add-In muss der Anforderungssatz „Mailbox" und ein Wert von 1.1 oder höher angegeben werden. Die neueste Anforderungssatzversion finden Sie in der API-Referenz. Eine Erläuterung der Funktionsweise finden Sie unter Outlook-Add-In-APIs.

Das Requirements-Element kann auch im VersionOverrides-Element angezeigt werden, sodass das Add-In eine andere Anforderung angeben kann, wenn es in Clients geladen wird, die VersionOverrides unterstützen.

Im folgenden Beispiel wird das DefaultMinVersion-Attribut des Sets-Elements verwendet, um office.jx, Version 1.1 oder höher, anzufordern, und das MinVersion-Attribut des Set-Elements, um den Postfach-Anforderungssatz, Version 1.1, anzufordern.

<OfficeApp>
...
  <Requirements>
    <Sets DefaultMinVersion="1.1">
      <Set Name="MailBox" MinVersion="1.1" />
    </Sets>
  </Requirements>
...
</OfficeApp>

Formulareinstellungen

Das FormSettings-Element wird von älteren Outlook-Clients verwendet, die nur Schema 1.1 und nicht VersionOverrides unterstützen. Mithilfe dieses Elements definieren Entwickler, wie das Add-In in diesen Clients angezeigt wird. Es gibt zwei Teile – ItemRead und ItemEdit. Mit ItemRead wird angegeben, wie das Add-In angezeigt wird, wenn der Benutzer Nachrichten und Termine liest. ItemEdit beschreibt, wie das Add-In angezeigt wird, während der Benutzer eine Antwort, eine neue Nachricht, einen neuen Termin erstellt oder einen Termin bearbeitet, dessen Organisator er ist.

Diese Einstellungen beziehen sich direkt auf die Aktivierungsregeln im Rule-Element. Wenn ein Add-In beispielsweise angibt, dass es in einer gerade verfassten Nachricht angezeigt werden soll, muss ein ItemEdit-Formular angegeben werden.

Weitere Informationen finden Sie in der Schemareferenz für Office-Add-In-Manifeste (v1.1).

App-Domänen

Die Domäne der Add-In-Startseite, die Sie im Element SourceLocation angeben, ist die Standarddomäne. Wenn die Elemente AppDomains und AppDomain nicht verwendet werden und Ihr Add-In versucht, zu einer andere Domäne zu navigieren, öffnet der Browser ein neues Fenster außerhalb des Add-In-Bereichs. Wenn die Navigation innerhalb des Add-In-Bereichs bleiben soll, müssen Sie ein AppDomains-Element hinzufügen und jede zusätzliche Domäne in der Add-In-Manifestdatei in ein eigenes AppDomain-Unterelement einbeziehen.

Das folgende Beispiel gibt eine Domäne https://www.contoso2.com als zweite Domäne an, zu der das Add-In innerhalb des Add-In-Bereichs navigieren kann:

<OfficeApp>
...
  <AppDomains>
    <AppDomain>https://www.contoso2.com</AppDomain>
  </AppDomains>
...
</OfficeApp>

App-Domänen sind auch erforderlich, um die gemeinsame Nutzung von Cookies zwischen dem Popupfenster und dem im Rich-Client ausgeführten Add-In zu ermöglichen.

Berechtigungen

Das Permissions-Element enthält die erforderlichen Berechtigungen für das Add-In. In der Regel sollten Sie die erforderliche Mindestberechtigung angeben, die das Add-In benötigt, je nachdem, welche Methoden zum Verfassen Sie genau verwenden möchten. Für ein Mail-Add-In beispielsweise, das in einem Entwurfsformular aktiviert ist und Elementeigenschaften wie item.requiredAttendees nur liest und nicht in diese schreibt, und mailbox.makeEwsRequestAsync nicht für den Zugriff auf Exchange Web Services-Vorgänge afruft, sollte die ReadItem-Berechtigung angegeben werden. Weitere Informationen zu den verfügbaren Berechtigungen finden Sie unter Angeben von Berechtigungen für den Outlook-Add-In-Zugriff auf die Benutzerpostfächer.

Vierstufiges Berechtigungsmodell für Mail-Add-Ins

4-Stufen-Berechtigungsmodell für Mail-Apps-Schema v1.1

<OfficeApp>
...
  <Permissions>ReadWriteItem</Permissions>
...
</OfficeApp>

Aktivierungsregeln

Aktivierungsregeln sind im Rule-Element angegeben. Das Rule-Element kann als untergeordnetes Element des OfficeApp-Elements in Manifesten der Version 1.1 angezeigt werden.

Aktivierungsregeln können zum Aktivieren eines Add-Ins basierend auf einer oder mehrerer der folgenden Bedingungen in dem aktuell ausgewählten Element verwendet werden.

Hinweis: Aktivierungsregeln gelten nur für Clients, die das VersionOverrides-Element nicht unterstützen.

  • Der Elementtyp und/oder die Nachrichtenklasse.

  • Das Vorhandensein eines bestimmten Typs einer bekannten Entität, z. B. eine Adresse oder Telefonnummer

  • Die Übereinstimmung eines regulären Ausdrucks im Nachrichtentext, Betreff oder der Absender-E-Mail-Adresse

  • Das Vorhandensein einer Anlage

Weitere Informationen sowie Beispiele zu Aktivierungsregeln finden Sie unter Aktivierungsregeln für Outlook-Add-Ins.

Nächste Schritte: Add-In-Befehle

Nachdem Sie eine einfache Manifestdatei definiert haben, definieren Sie Add-In-Befehle für Ihr Add-In. Add-In-Befehle werden als Schaltfläche im Menüband dargestellt, sodass Benutzer Ihr Add-In auf einfache und intuitive Weise aktivieren können. Weitere Informationen finden Sie unter Add-In-Befehle für Outlook.

Ein Beispiel-Add-In, das Add-In-Befehle definiert, finden Sie unter command-demo.

Nächste Schritte: Hinzufügen der Unterstützung für mobile Umgebungen

In Add-Ins kann optional die Unterstützung für Outlook Mobile hinzugefügt werden. Outlook Mobile unterstützt Add-In-Befehle auf ähnliche Weise wie Outlook unter Windows und Mac. Weitere Informationen finden Sie unter Hinzufügen der Unterstützung für Add-In-Befehle für Outlook Mobile.

Zusätzliche Ressourcen