Aktivierungsregeln für kontextbezogene 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. Anschließend kann der Benutzer das Add-In in der Outlook-Benutzeroberfläche auswählen, um es für das aktuelle Element zu starten.

Wichtig

Entitätsbasierte kontextbezogene Outlook-Add-Ins werden im 2. Quartal 2024 eingestellt. Die Arbeiten zur Einstellung dieses Features beginnen im Mai und werden bis Ende Juni fortgesetzt. Nach Juni können Kontext-Add-Ins keine Entitäten mehr in E-Mail-Elementen erkennen, um Aufgaben für sie auszuführen. Die folgenden APIs werden ebenfalls eingestellt.

• Office.context.mailbox.item.getEntities()
• Office.context.mailbox.item.getEntitiesByType(entityType)
• Office.context.mailbox.item.getFilteredEntitiesByName(name)
• Office.context.mailbox.item.getSelectedEntities()

Um potenzielle Unterbrechungen zu minimieren, werden die folgenden Elemente weiterhin unterstützt, nachdem entitätsbasierte Kontext-Add-Ins eingestellt wurden.

• Eine alternative Implementierung der Schaltfläche " An Besprechung teilnehmen ", die von Onlinebesprechungs-Add-Ins aktiviert wird, wird entwickelt. Sobald die Unterstützung für entitätsbasierte Kontext-Add-Ins endet, werden Onlinebesprechungs-Add-Ins automatisch zur alternativen Implementierung übergehen, um die Schaltfläche An Besprechung teilnehmen zu aktivieren.
• Regeln für reguläre Ausdrücke werden weiterhin unterstützt, nachdem entitätsbasierte Kontext-Add-Ins eingestellt wurden. Es wird empfohlen, Ihr Kontext-Add-In zu aktualisieren, um Regeln für reguläre Ausdrücke als alternative Lösung zu verwenden. Anleitungen zum Implementieren dieser Regeln finden Sie unter Verwenden von Aktivierungsregeln für reguläre Ausdrücke zum Anzeigen eines Outlook-Add-Ins.

Weitere Informationen finden Sie unter Außerbetriebnahme entitätsbasierter kontextbezogener Outlook-Add-Ins.

Angeben von Aktivierungsregeln in einem Manifest

Hinweis

Outlook-Add-In-Features, die von Aktivierungsregeln abhängen, werden nicht unterstützt, wenn das Add-In ein einheitliches Manifest für Microsoft 365 (Vorschau) verwendet.

Damit Outlook ein Add-In für bestimmte Bedingungen aktiviert, geben Sie Aktivierungsregeln im Add-In-Manifest an, indem Sie eines der folgenden Rule Elemente verwenden.

• Rule-Element (MailApp complexType) – Gibt eine einzelne Regel an.
• Rule-Element (RuleCollection complexType) – Kombiniert mehrere Regeln mithilfe von logischen Operationen.

Hinweis

Das Rule Element, das Sie zum Angeben einer einzelnen Regel verwenden, ist vom abstrakten komplexen Rule-Typ . Jeder der folgenden Regeltypen erweitert diesen abstrakten Rule komplexen Typ. 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 beispielsweise eine ItemIs-Regel . <Rule xsi:type="ItemIs" ItemType="Message" />

Das FormType -Attribut gilt für Aktivierungsregeln im Manifest v1.1, ist aber nicht in VersionOverrides v1.0 definiert. Daher kann es nicht verwendet werden, wenn ItemIs im VersionOverrides Knoten verwendet wird.

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.

Regelname	Anwendbare Formulare	Beschreibung
ItemIs	Lesen, Verfassen	Überprüft, ob das aktuelle Element vom angegebenen Typ (Nachricht oder Termin) ist. Kann auch die Elementklasse und den Formulartyp und optional die Elementnachrichtenklasse überprüfen.
ItemHasAttachment	Lesen	Überprüft, ob das ausgewählte Element über einen Anhang verfügt.
ItemHasKnownEntity	Lesen	Überprüft, ob das ausgewählte Element über eine oder mehrere allgemein bekannte Entitäten verfügt. Weitere Informationen: Abgleichen von Zeichenfolgen in einem Outlook-Element als bekannte Entitäten.
ItemHasRegularExpressionMatch	Lesen	Ü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.
RuleCollection	Lesen, Verfassen	Kombiniert einen Satz von Regeln, damit Sie komplexere Regeln erstellen können.

ItemIs-Regel

Der ItemIs komplexe Typ definiert eine Regel, die ergibt true , ob das aktuelle Element mit dem Elementtyp übereinstimmt, und optional die Elementnachrichtenklasse, wenn sie in der Regel angegeben ist.

Geben Sie einen der folgenden Elementtypen im ItemType -Attribut einer Regel an ItemIs . Sie können mehr als eine ItemIs Regel in einem Manifest angeben. Der Elementtyp „simpleType“ definiert die Typen von Outlook-Elementen, die Outlook-Add-Ins unterstützen.

Wert	Beschreibung
Termin	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:
Meldung	Gibt eines der folgenden Elemente an, die normalerweise im Posteingang empfangen werden. Eine E-Mail-Nachricht. Entspricht der Nachrichtenklasse "IPM.Note" in Outlook. Eine Besprechung, Antwort oder ein Abbruch. Dies entspricht den folgenden Nachrichtenklassen in Outlook. IPM.Schedule.Meeting.Request IPM.Schedule.Meeting.Neg IPM.Schedule.Meeting.Pos IPM.Schedule.Meeting.Tent IPM.Schedule.Meeting.Canceled

Das FormType -Attribut wird verwendet, um den Modus (Lesen oder Verfassen) anzugeben, in dem das Add-In aktiviert werden soll.

Hinweis

Das ItemIs-Attribut FormType wird in Schema v1.1 und höher, aber nicht in VersionOverrides v1.0 definiert. Schließen Sie das Attribut beim Definieren von FormType Add-In-Befehlen nicht ein.

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.

Sie können optional das ItemClass -Attribut verwenden, um die Nachrichtenklasse des Elements anzugeben, und das IncludeSubClasses -Attribut, um anzugeben, ob die Regel sein true soll, wenn das Element eine Unterklasse der angegebenen Klasse ist.

Weitere Informationen zu Nachrichtenklassen finden Sie unter Elementtypen und Meldungsklassen.

Das folgende Beispiel ist eine ItemIs Regel, mit der Benutzer das Add-In in der Outlook-Add-In-Leiste anzeigen können, wenn der Benutzer eine Nachricht liest.

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

Das folgende Beispiel ist eine ItemIs Regel, mit der Benutzer das Add-In in der Outlook-Add-In-Leiste anzeigen können, wenn der Benutzer eine Nachricht oder einen Termin liest.

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

ItemHasAttachment-Regel

Der ItemHasAttachment komplexe Typ definiert eine Regel, die überprüft, ob das ausgewählte Element eine Anlage enthält.

<Rule xsi:type="ItemHasAttachment" />

"ItemHasKnownEntity"-Regel

Bevor ein Element für ein Add-In verfügbar gemacht wird, untersucht der Server es, um festzustellen, ob der Betreff und der Text Text enthalten, der wahrscheinlich eine der bekannten Entitäten ist. Wenn eine dieser Entitäten gefunden wird, wird sie in einer Sammlung bekannter Entitäten platziert, auf die Sie mithilfe der -Methode oder getEntitiesByType der getEntities -Methode dieses Elements zugreifen.

Sie können eine Regel mit angeben, die ItemHasKnownEntity ihr Add-In anzeigt, wenn eine Entität des angegebenen Typs im Element vorhanden ist. Sie können die folgenden bekannten Entitäten im EntityType -Attribut einer ItemHasKnownEntity Regel angeben.

• Adresse
• Kontakt
• EmailAddress
• MeetingSuggestion
• PhoneNumber
• TaskSuggestion
• URL

Optional können Sie einen regulären Ausdruck in das RegularExpression Attribut einschließen, sodass Das Add-In nur angezeigt wird, wenn eine Entität vorhanden ist, die dem regulären Ausdruck entspricht. Um Übereinstimmungen mit regulären Ausdrücken zu erhalten, die in ItemHasKnownEntity Regeln angegeben sind, können Sie die - oder getFilteredEntitiesByName -getRegExMatchesMethode für das aktuell ausgewählte Outlook-Element verwenden.

Das folgende Beispiel zeigt eine Auflistung von Rule Elementen, die das Add-In anzeigen, wenn eine der angegebenen bekannten Entitäten in der Nachricht vorhanden ist.

<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>

Das folgende Beispiel zeigt eine ItemHasKnownEntity Regel mit einem RegularExpression Attribut, das das Add-In aktiviert, wenn eine URL mit dem Wort "contoso" in einer Nachricht vorhanden ist.

<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.

"ItemHasRegularExpressionMatch"-Regel

Der ItemHasRegularExpressionMatch komplexe Typ definiert eine Regel, die einen regulären Ausdruck verwendet, um den Inhalt 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. Sie können die getRegExMatches - oder getRegExMatchesByName -Methode des -Objekts verwenden, das das aktuell ausgewählte Element darstellt, um Übereinstimmungen für den angegebenen regulären Ausdruck abzurufen.

Das folgende Beispiel zeigt eine ItemHasRegularExpressionMatch , die das Add-In aktiviert, wenn der Text des ausgewählten Elements "Apfel", "Banane" oder "Kokosnuss" enthält, wobei die Groß-/Kleinschreibung ignoriert wird.

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

Weitere Informationen zur Verwendung der ItemHasRegularExpressionMatch Regel finden Sie unter Verwenden von Aktivierungsregeln für reguläre Ausdrücke zum Anzeigen eines Outlook-Add-Ins.

RuleCollection-Regel

Der RuleCollection komplexe Typ kombiniert mehrere Regeln in einer einzelnen Regel. Mithilfe des -Attributs können Sie angeben, ob die Regeln in der Auflistung mit einem logischen OR oder einem logischen AND Mode kombiniert werden sollen.

Wird ein logisches AND angegeben, muss ein Element mit allen in der Sammlung angegebenen Regeln übereinstimmen, damit das Add-In angezeigt wird. Wenn ein logisches OR angegeben wird, zeigt ein Element, das einer der angegebenen Regeln in der Auflistung entspricht, das Add-In an.

Sie können Regeln kombinieren, um komplexe Regeln zu bilden RuleCollection . 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.

<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.

<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ücke

Für eine zufriedenstellende Erfahrung mit Outlook-Add-Ins sollten Sie die Richtlinien für die Aktivierung und die API-Verwendung befolgen. Die folgende Tabelle enthält allgemeine Grenzwerte für reguläre Ausdrücke und Regeln, aber es gibt spezifische Regeln für verschiedene Anwendungen. 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.

Add-In-Element	Richtlinien
Manifestgröße	Nicht größer als 32 KB
Regeln	Nicht mehr als 15 Regeln.
ItemHasKnownEntity	Outlook unter Windows und auf Mac wendet die Regel auf die ersten 1 MB des Texts und nicht auf den Rest des Texts an.
Reguläre Ausdrücke	Für ItemHasKnownEntity- oder ItemHasRegularExpressionMatch-Regeln für alle Outlook-Anwendungen: Geben Sie nicht mehr als fünf reguläre Ausdrücke in Aktivierungsregeln für ein Outlook-Add-In an. Sie können ein Add-In nicht installieren, wenn Sie diesen Grenzwert überschreiten. Geben Sie reguläre Ausdrücke an, deren erwartete Ergebnisse vom Aufruf der getRegExMatches-Methode innerhalb der ersten 50 Übereinstimmungen zurückgegeben werden. Wichtig: Text wird basierend auf Zeichenfolgen hervorgehoben, die sich aus der Übereinstimmung mit dem regulären Ausdruck ergeben. Die hervorgehobenen Vorkommen stimmen jedoch möglicherweise nicht genau mit dem überein, was sich aus tatsächlichen Assertionen regulärer Ausdrücke wie negativem Look-Ahead (?!text), Look-Behind (?<=text)und negativem Look-Behind (?<!text)ergeben sollte. Wenn Sie beispielsweise den regulären Ausdruck under(?!score) für "Like under, under score, and unterstrich" verwenden, wird die Zeichenfolge "under" für alle Vorkommen hervorgehoben, anstatt nur die ersten beiden. Geben Sie reguläre Ausdrücke an, deren Übereinstimmung die Grenzwerte in der folgenden Tabelle nicht überschreitet. Längengrenzwert für eine Übereinstimmung für einen regulären Ausdruck Outlook unter Windows und auf Mac Outlook für iOS und Android Elementtext ist Nur-Text 1,5 KB 3 KB Elementtext ist HTML 3 KB 3 KB

Siehe auch

• Erstellen von Outlook-Add-Ins für Entwurfsvorlagen
• Einschränkungen für die Aktivierung und die JavaScript-API für Outlook-Add-Ins
• Verwenden regulärer Ausdrücke für Aktivierungsregeln zum Anzeigen eines Outlook-Add-Ins
• Erkennen bestimmter Zeichenfolgen in einem Outlook-Element als bekannte Entitäten