Aktivierungsregeln für kontextbezogene Outlook-Add-InsActivation rules for contextual Outlook add-ins

Outlook aktiviert einige Arten von Add-Ins, wenn Nachrichten oder Termine, die der Benutzer gerade liest oder erstellt, den Aktivierungsregeln des Add-Ins entsprechen. Dies gilt für alle Add-Ins, die das Manifestschema 1.1 verwenden. Der Benutzer kann dann das Add-In aus der Outlook-Benutzeroberfläche auswählen, um es für das jeweils aktuelle Element zu starten.Outlook activates some types of add-ins if the message or appointment that the user is reading or composing satisfies the activation rules of the add-in. This is true for all add-ins that use the 1.1 manifest schema. The user can then choose the add-in from the Outlook UI to start it for the current item.

Die folgende Abbildung zeigt Outlook-Add-Ins, die in der Add-In-Leiste für die Nachricht im Lesebereich aktiviert sind.The following figure shows Outlook add-ins activated in the add-in bar for the message in the Reading Pane.

App-Leiste, die aktivierte Apps zum Lesen von E-Mails zeigt

Angeben von Aktivierungsregeln in einem ManifestSpecify activation rules in a manifest

Wenn Sie die kontextbezogene Aktivierung verwenden möchten und in Outlook ein Add-In für bestimmte Bedingungen aktiviert werden soll, geben Sie Aktivierungsregeln im Add-In-Manifest an. Verwenden Sie hierfür eines dieser zwei Rule-Elemente:To have Outlook activate an add-in for specific conditions, specify activation rules in the add-in manifest by using one of the following Rule elements:

Hinweis: Das Rule-Element, das Sie zum Angeben einer einzelnen Regel verwenden, entspricht dem abstrakten komplexen Typ Rule. Jede der folgenden Regeltypen erweitert diesen abstrakten komplexen Typ Rule. Wenn Sie also eine einzelne Regel in einem Manifest angeben, müssen Sie das Attribut xsi:type verwenden, um einen der folgenden Regeltypen genauer zu definieren. Die folgende Regel definiert z. B. eine ItemIs-Regel: <Rule xsi:type="ItemIs" ItemType="Message" /> Das FormType-Attribut bezieht sich auf Aktivierungsregeln in der Manifestdatei v1.1, ist jedoch in VersionOverrides v1.0 nicht definiert. Deshalb kann es nicht verwendet werden, wenn ItemIs im Knoten VersionOverrides verwendet wird.Note: The Rule element that you use to specify an individual rule is of the abstract Rule complex type. Each of the following types of rules extends this abstract Rule complex type. So when you specify an individual rule in a manifest, you must use the xsi:type attribute to further define one of the following types of rules. For example, the following rule defines an ItemIs rule: <Rule xsi:type="ItemIs" ItemType="Message" /> The FormType attribute applies to activation rules in the manifest v1.1 but is not defined in VersionOverrides v1.0. So it can't be used when ItemIs is used in the VersionOverrides node.

In der folgenden Tabelle werden die verfügbaren Regeltypen aufgeführt. Weitere Informationen finden Sie im Anschluss an die Tabelle und in den unter Erstellen von Outlook-Add-Ins für Leseformulare angegebenen Artikeln.The following table lists the types of rules that are available. You can find more information following the table and in the specified articles under Create Outlook add-ins for read forms.

RegelnameRule name Anwendbare FormulareApplicable forms BeschreibungDescription
ItemIsItemIs Lesen, VerfassenRead ,Compose Überprüft, ob das aktuelle Element den angegebenen Typ (Nachricht oder Termin) und (optional) die angegebene Elementnachrichtenklasse aufweist.Checks to see whether the current item is of the specified type (message or appointment). Can also check the item class and form type.and optionally, item message class.
ItemHasAttachmentItemHasAttachment LesenRead Überprüft, ob das ausgewählte Element über einen Anhang verfügt.Checks to see whether the selected item contains an attachment.
ItemHasKnownEntityItemHasKnownEntity LesenRead Überprüft, ob das ausgewählte Element über eine oder mehrere allgemein bekannte Entitäten verfügt.Weitere Informationen: Erkennen bestimmter Zeichenfolgen in einem Outlook-Element als bekannte Entitäten.Checks to see whether the selected item contains one or more well-known entities. More information: Match strings in an Outlook item as well-known entities.
ItemHasRegularExpressionMatchItemHasRegularExpressionMatch LesenRead Überprüft, ob die E-Mail-Adresse des Absenders, der Betreff und/oder der Textkörper des ausgewählten Elements mit einem regulären Ausdruck übereinstimmt.Weitere Informationen: Verwenden regulärer Ausdrücke für Aktivierungsregeln zum Anzeigen eines Outlook-Add-Ins.Checks to see whether the sender's email address, the subject, and/or the body of the selected item contains a match to a regular expression.More information: Use regular expression activation rules to show an Outlook add-in.
RuleCollectionRuleCollection Lesen, VerfassenRead, Compose Kombiniert einen Satz von Regeln, damit Sie komplexere Regeln erstellen können.Combines a set of rules so that you can form more complex rules.

ItemIs-RegelItemIs rule

Der komplexe Typ ItemIs definiert eine Regel, deren Auswertung true ergibt, wenn das aktuelle Element dem Elementtyp und optional der Elementnachrichtenklasse entspricht, sofern diese in der Regel angegeben ist.The ItemIs complex type defines a rule that evaluates to true if the current item matches the item type, and optionally the item message class if it's stated in the rule.

Geben Sie einen der folgenden Elementtypen in das Attribut ItemType einer ItemIs-Regel ein. Sie können mehr als eine ItemIsRegel in einem Manifest angeben. Der ItemType-SimpleType legt die Outlook-Elementtypen fest, die Outlook-Add-Ins unterstützen.Specify one of the following item types in the ItemType attribute of an ItemIs rule. You can specify more than one ItemIs rule in a manifest. The ItemType simpleType defines the types of Outlook items that support Outlook add-ins.

WertValue BeschreibungDescription
TerminAppointment Gibt ein Element in einem Outlook-Kalender an. Dies kann eine Einladung sein, ein Besprechungselement, das beantwortet wurde und einen Organisator und Teilnehmer hat, oder ein Termin, der keinen Organisator oder Teilnehmer hat und einfach ein Element im Kalender darstellt.Entspricht der IPM.Appointment-Nachrichtenklassen in Outlook:Specifies an item in an Outlook calendar. This includes a meeting item that has been responded to and has an organizer and attendees, or an appointment that does not have an organizer or attendee and is simply an item on the calendar.This corresponds to the IPM.Appointment message class in Outlook.
MeldungMessage Gibt eines der folgenden, typischerweise im Posteingang empfangenen Elemente an:Specifies one of the following items received in typically the Inbox:
  • Eine E-Mail-Nachricht. Entspricht der Nachrichtenklasse "IPM.Note" in Outlook.An email message. This corresponds to the IPM.Note message class in Outlook.

  • Eine Besprechung, Antwort oder ein Abbruch. Entspricht den folgenden Nachrichtenklassen in Outlook:A meeting request, response, or cancellation. This corresponds to the following message classes in Outlook:

    IPM.Schedule.Meeting.RequestIPM.Schedule.Meeting.Request

    IPM.Schedule.Meeting.NegIPM.Schedule.Meeting.Neg

    IPM.Schedule.Meeting.PosIPM.Schedule.Meeting.Pos

    IPM.Schedule.Meeting.TentIPM.Schedule.Meeting.Tent

    IPM.Schedule.Meeting.CanceledIPM.Schedule.Meeting.Canceled

Das FormType-Attribut wird zum Angeben des Modus (Lesen oder Verfassen) verwendet, in dem das Add-In aktiviert werden sollte.The FormType attribute is used to specify the mode (read or compose) in which the add-in should activate.

** Hinweis: ** Das ItemIs FormType-Attribut ist im Schema Version 1.1 und höher definiert, aber nicht in VersionOverrides Version 1.0. Schließen Sie das FormType-Attribut nicht ein, wenn Sie Add-In-Befehle definieren.Note: ** The ItemIs **FormType attribute is defined in schema v1.1 and later but not in VersionOverrides v1.0. Do not include the FormType attribute when defining add-in commands.

Nach der Aktivierung eines Add-Ins können Sie mit der Eigenschaft mailbox.item das aktuell ausgewählte Element in Outlook und mit der Eigenschaft item.itemType die Art des aktuell ausgewählten Elements abrufen.After an add-in is activated, you can use the mailbox.item property to obtain the currently selected item in Outlook, and the item.itemType property to obtain the type of the current item.

Optional können Sie mit dem ItemClass-Attribut die Nachrichtenklasse des Elements angeben, und mit dem IncludeSubClasses-Attribut können Sie angeben, ob die Regel " true" sein soll, wenn es sich bei dem Element um eine Unterklasse der angegebenen Klasse handelt.You can optionally use the ItemClass attribute to specify the message class of the item, and the IncludeSubClasses attribute to specify whether the rule should be true when the item is a subclass of the specified class.

Weitere Informationen zu Nachrichtenklassen finden Sie unter Elementtypen und Meldungsklassen.For more information about message classes, see Item Types and Message Classes.

Das folgende Beispiel ist eine ItemIs-Regel, mit deren Hilfe Benutzer das Add-In in der Outlook-Add-In-Leiste sehen können, wenn der Benutzer eine Nachricht oder einen Termin liest.The following example is an ItemIs rule that lets users see the add-in in the Outlook add-in bar when the user is reading a message:

<Rule xsi:type="ItemIs" ItemType="Message" FormType="Read" />

Das folgende Beispiel ist eine ItemIs-Regel, mit deren Hilfe Benutzer das Add-In in der Outlook-Add-In-Leiste sehen können, wenn der Benutzer eine Nachricht liest.The following example is an ItemIs rule that lets users see the add-in in the Outlook add-in bar when the user is reading a message or appointment.

<Rule xsi:type="RuleCollection" Mode="Or">
  <Rule xsi:type="ItemIs" ItemType="Message" FormType="Read" />
  <Rule xsi:type="ItemIs" ItemType="Appointment" FormType="Read" />
</Rule>

ItemHasAttachment-RegelItemHasAttachment rule

Der komplexe Typ ItemHasAttachment definiert eine Regel, die überprüft, ob das ausgewählte Element eine Anlage enthält.The ItemHasAttachment complex type defines a rule that checks if the selected item contains an attachment.

<Rule xsi:type="ItemHasAttachment" />

ItemHasKnownEntity-RegelItemHasKnownEntity rule

Bevor ein Element für ein Add-In verfügbar gemacht wird, wird es vom Server untersucht, um festzustellen, ob der Betreff oder der Textkörper Text enthält, bei dem es sich um eine der bekannten Entitäten handeln könnte. Wird eine dieser Entitäten gefunden, wird sie in eine Sammlung bekannter Entitäten verschoben. Diese können Sie mit der getEntities- oder der getEntitiesByType-Methode dieses Elements aufrufen.Before an item is made available to an add-in, the server examines it to determine whether the subject and body contain any text that is likely to be one of the known entities. If any of these entities are found, it is placed in a collection of known entities that you access by using the getEntities or getEntitiesByType method of that item.

Mithilfe von ItemHasKnownEntity können Sie eine Regel angeben, mit der Ihr Add-In angezeigt wird, wenn eine Entität des angegebenen Typs in dem Element vorhanden ist. Im EntityType-Attribut einer ItemHasKnownEntity-Regel können die folgenden bekannten Entitäten angegeben werden:You can specify a rule by using ItemHasKnownEntity that shows your add-in when an entity of the specified type is present in the item. You can specify the following known entities in the EntityType attribute of an ItemHasKnownEntity rule:

  • AdresseAddress
  • KontaktContact
  • EmailAddressEmailAddress
  • MeetingSuggestionMeetingSuggestion
  • PhoneNumberPhoneNumber
  • TaskSuggestionTaskSuggestion
  • URLURL

Optional können Sie einen regulären Ausdruck in das RegularExpression-Attribut integrieren, damit Ihr Add-In nur dann angezeigt wird, wenn eine Entität vorhanden ist, die mit dem regulären Ausdruck übereinstimmt. Um Übereinstimmungen mit regulären Ausrücken abzurufen, die in ItemHasKnownEntity-Regeln angegeben sind, können Sie die Methode getRegExMatches oder getFilteredEntitiesByName für das aktuell ausgewählte Outlook-Element verwenden.You can optionally include a regular expression in the RegularExpression attribute so that your add-in is only shown when an entity that matches the regular expression in present. To obtain matches to regular expressions specified in ItemHasKnownEntity rules, you can use the getRegExMatches or getFilteredEntitiesByName method for the currently selected Outlook item.

Im folgenden Beispiel finden Sie eine Sammlung von Rule-Elementen, mit denen das Add-in angezeigt wird, wenn sich eine der angegebenen bekannten Entitäten in der Nachricht befindet.The following example shows a collection of Rule elements that show the add-in when one of the specified well-known entities is present in the message.

<Rule xsi:type="RuleCollection" Mode="Or">
    <Rule xsi:type="ItemHasKnownEntity" EntityType="Address" />
    <Rule xsi:type="ItemHasKnownEntity" EntityType="MeetingSuggestion" />
    <Rule xsi:type="ItemHasKnownEntity" EntityType="TaskSuggestion" />
</Rule>

Im folgenden Beispiel finden Sie eine ItemHasKnownEntity-Regel mit einem RegularExpression-Attribut, mit dem das Add-In aktiviert wird, wenn sich eine URL in der Nachricht befindet, die das Wort "contoso" enthält.The following example shows an ItemHasKnownEntity rule with a RegularExpression attribute that activates the add-in when a URL that contains the word "contoso" is present in a message.

<Rule xsi:type="ItemHasKnownEntity" EntityType="Url" RegularExpression="contoso" />

Weitere Informationen zu Entitäten in Aktivierungsregeln finden Sie unter Erkennen bestimmter Zeichenfolgen in einem Outlook-Element als bekannte Entitäten.For more information about entities in activation rules, see Match strings in an Outlook item as well-known entities.

ItemHasRegularExpressionMatch-RegelItemHasRegularExpressionMatch rule

Mithilfe des komplexen Typs ItemHasRegularExpressionMatch wird eine Regel definiert, in der ein regulärer Ausdruck verwendet wird, um die Inhalte der angegebenen Eigenschaft eines Elements abzugleichen. Wird in der angegebenen Eigenschaft des Elements Text gefunden, der mit dem regulären Ausdruck übereinstimmt, wird das Add-In von Outlook aktiviert und auf der Add-In-Leiste angezeigt. Mithilfe der Methode getRegExMatches oder getRegExMatchesByName des Objekts, das für das aktuell ausgewählte Element steht, können Sie Übereinstimmungen für den angegebenen regulären Ausdruck abrufen.The ItemHasRegularExpressionMatch complex type defines a rule that uses a regular expression to match the contents of the specified property of an item. If text that matches the regular expression is found in the specified property of the item, Outlook activates the add-in bar and displays the add-in. You can use the getRegExMatches or getRegExMatchesByName method of the object that represents the currently selected item to obtain matches for the specified regular expression.

Im folgenden Beispiel ist ein ItemHasRegularExpressionMatch dargestellt, der das Add-In aktiviert, wenn der Textkörper des ausgewählten Elements das Wort "apple", "banana" oder "coconut" enthält (Groß-/Kleinschreibung wird ignoriert).The following example shows an ItemHasRegularExpressionMatch that activates the add-in when the body of the selected item contains "apple", "banana", or "coconut", ignoring case.

<Rule xsi:type="ItemHasRegularExpressionMatch" RegExName="fruits" RegExValue="apple|banana|coconut" pPropertyName="BodyAsPlaintext" IgnoreCase="true" />

Weitere Informationen zur Verwendung der ItemHasRegularExpressionMatch-Regel finden Sie unter Verwenden regulärer Ausdrücke für Aktivierungsregeln zum Anzeigen eines Outlook-Add-Ins.For more information about using the ItemHasRegularExpressionMatch rule, see Use regular expression activation rules to show an Outlook add-in.

RuleCollection-RegelRuleCollection rule

Mithilfe des komplexen Typs " RuleCollection" werden mehrere Regeln in einer einzigen Regel kombiniert. Mit dem Mode-Attribut können Sie angeben, ob die Regeln in der Sammlung mit einem logischen OR oder einem logischen AND kombiniert werden.The RuleCollection complex type combines multiple rules into a single rule. You can specify whether the rules in the collection should be combined with a logical OR or a logical AND by using the Mode attribute.

Wird ein logisches AND angegeben, muss ein Element mit allen in der Sammlung angegebenen Regeln übereinstimmen, damit das Add-In angezeigt wird. Wird ein logisches OR angegeben, wird das Add-in angezeigt, wenn ein Element mit einer der in der Sammlung angegebenen Regeln übereinstimmt.When a logical AND is specified, an item must match all the specified rules in the collection to show the add-in. When a logical OR is specified, an item that matches any of the specified rules in the collection will show the add-in.

Sie können RuleCollection-Regeln kombinieren, um komplexe Regeln zu erstellen. Im folgenden Beispiel wird das Add-In aktiviert, wenn der Benutzer einen Termin oder eine Nachricht anzeigt und der Betreff oder der Textkörper des Elements eine Adresse enthält.You can combine RuleCollection rules to form complex rules. The following example activates the add-in when the user is viewing an appointment or message item and the subject or body of the item contains an address.

<Rule xsi:type="RuleCollection" Mode="And">
  <Rule xsi:type="RuleCollection" Mode="Or">
    <Rule xsi:type="ItemIs" ItemType="Message" FormType="Read" />
    <Rule xsi:type="ItemIs" ItemType="Appointment" FormType="Read"/>
  </Rule>
  <Rule xsi:type="ItemHasKnownEntity" EntityType="Address" />
</Rule>

Mit dem folgenden Beispiel wird das Add-In aktiviert, wenn der Benutzer eine Nachricht verfasst oder wenn der Benutzer einen Termin anzeigt und der Betreff oder der Textkörper des Termins eine Adresse enthalten.The following example activates the add-in when the user is composing a message, or when the user is viewing an appointment and the subject or body of the appointment contains an address.

<Rule xsi:type="RuleCollection" Mode="Or"> 
  <Rule xsi:type="ItemIs" ItemType="Message" FormType="Edit" /> 
  <Rule xsi:type="RuleCollection" Mode="And">
    <Rule xsi:type="ItemIs" ItemType="Appointment" FormType="Read" />
    <Rule xsi:type="ItemHasKnownEntity" EntityType="Address" />
  </Rule> 
</Rule>

Einschränkungen für Regeln und reguläre AusdrückeLimits for rules and regular expressions

Für eine zufriedenstellende Erfahrung mit Outlook-Add-Ins sollten Sie die Richtlinien für die Aktivierung und die API-Verwendung befolgen. In der folgenden Tabelle sind die allgemeinen Einschränkungen für reguläre Ausdrücke und Regeln dargestellt, es gibt jedoch spezifische Regeln für unterschiedliche Hosts. Weitere Informationen finden Sie unter Grenzwerte für Aktivierung und JavaScript-API für Outlook-Add-Ins und Problembehandlung für die Aktivierung von Outlook-Add-Ins.To provide a satisfactory experience with Outlook add-ins, you should adhere to the activation and API usage guidelines. The following table shows general limits for regular expressions and rules but there are specific rules for different hosts. For more information, see Limits for activation and JavaScript API for Outlook add-ins and Troubleshoot Outlook add-in activation.

Add-In-ElementAdd-in element RichtlinienGuidelines
ManifestgrößeManifest Size Nicht größer als 32 KBNo larger than 256 KB.
RegelnRules Nicht mehr als 15 Regeln.No more than 15 rules.
ItemHasKnownEntityItemHasKnownEntity Ein Outlook-Rich-Client wendet die Regel auf das erste MB des Elementtexts an, jedoch nicht auf den über diesen Grenzwert hinausgehenden Textkörper.An Outlook rich client will apply the rule against the first 1 MB of the body, and not to the rest of the body.
Reguläre AusdrückeRegular Expressions Für die Regeln ItemHasKnownEntity oder ItemHasRegularExpressionMatch für alle Outlook-Hosts:For ItemHasKnownEntity or ItemHasRegularExpressionMatch rules for all Outlook hosts:
  • Sie können nicht mehr als 5 reguläre Ausdrücke in Aktivierungsregeln in einem Outlook-Add-In angeben. Bei Überschreitung dieses Grenzwerts ist die Installation eines Outlook-Add-Ins nicht möglich.Specify no more than 5 regular expressions in activation rules for an Outlook add-in. You cannot install an add-in if you exceed the that limit.
  • Geben Sie reguläre Ausdrücke an, deren erwartete Ergebnisse vom Aufruf der getRegExMatches-Methode innerhalb der ersten 50 Übereinstimmungen zurückgegeben werden.Specify regular expressions whose anticipated results are returned by the getRegExMatches method call within the first 50 matches.
  • Geben Sie Look-Ahead-Assertionen in regulären Ausdrücken an, jedoch keine Look-Behind-, (?<=text), und negativen Look-Behind-Assertionen (?<!text).Specify look-ahead assertions in regular expressions, but not look-behind, (?<=text), and negative look-behind (?<!text).
  • Geben Sie reguläre Ausdrücke an, deren Übereinstimmungen die Beschränkungen der nachstehenden Tabelle nicht überschreiten.Specify regular expressions whose match does not exceed the limits in the table below.

    Grenzwert für eine Übereinstimmung für einen regulären AusdruckLimit on length of a regex matchOutlook-Rich-ClientsOutlook rich clientsOutlook Web App für GeräteOutlook Web App for Devices
    Elementtext ist Nur-TextItem body is plain text1,5 KB1.5 KB3 KB3 KB
    Elementtext ist HTMLItem body it HTML3 KB3 KB3 KB3 KB

Zusätzliche RessourcenAdditional resources