„On-Send“-Funktion für Outlook-Add-Ins

  • Artikel

Das On-Send-Feature für Outlook-Add-Ins bietet eine Möglichkeit, eine Nachricht oder ein Besprechungselement zu verarbeiten oder Benutzer für bestimmte Aktionen zu blockieren, und ermöglicht es einem Add-In, bestimmte Eigenschaften beim Senden festzulegen.

Hinweis

Das On-Send-Feature wird in Add-Ins, die das einheitliche Manifest für Microsoft 365 (Vorschau) verwenden, nicht unterstützt. Erzielen Sie ähnliche Effekte, indem Sie die ereignisbasierte Aktivierung verwenden und einen Handler für das OnMessageSend - oder OnAppointmentSend-Ereignis oder beides implementieren.

Verwenden Sie beispielsweise das On-Send-Feature für Folgendes:

  • Sie können verhindern, dass Benutzer vertrauliche Informationen senden oder die Betreffzeile leer lassen.
  • Fügen Sie einen bestimmten Empfänger zur CC-Zeile in Nachrichten oder zur optionalen Empfängerzeile in Besprechungen hinzu.

Das On-Send-Feature wird vom Ereignistyp ItemSend (Item senden) ausgelöst und verfügt über keine eigene Benutzeroberfläche.

Informationen zu den für die „On-Send“-Funktion geltenden Einschränkungen finden Sie im Abschnitt Einschränkungen weiter unten in diesem Artikel.

Hinweis

Smart Alerts ist eine neuere Version des On-Send-Features. Es wurde im Anforderungssatz 1.12 veröffentlicht und führte die OnMessageSend Ereignisse und OnAppointmentSend ein. Ähnlich wie beim On-Send-Feature ermöglicht es Smart Alerts Ihrem Add-In, zu überprüfen, ob bestimmte Bedingungen erfüllt sind, bevor ein E-Mail-Element gesendet wird. Intelligente Warnungen unterscheiden sich wie folgt vom On-Send-Feature:

Weitere Informationen zu den Unterschieden zwischen smarten Warnungen und dem On-Send-Feature finden Sie unter Unterschiede zwischen smarten Warnungen und dem On-Send-Feature. Wir laden Sie ein, intelligente Warnungen auszuprobieren, indem Sie die exemplarische Vorgehensweise durchgehen.

Unterstützte Clients und Plattformen

In der folgenden Tabelle sind unterstützte Client-Server-Kombinationen für das On-Send-Feature aufgeführt, einschließlich des erforderlichen kumulativen Updates, falls zutreffend. Ausgeschlossene Kombinationen werden nicht unterstützt.

Client Exchange Online: Exchange 2019 lokal
(Kumulatives Update 1 oder höher)		 Exchange 2016 lokal
(Kumulatives Update 6 oder höher)
Webbrowser:
moderne Outlook-Benutzeroberfläche		 Ja – Nicht zutreffend
Webbrowser:
Klassische Outlook-Benutzeroberfläche		 Nicht zutreffend Ja Ja
Windows:
Version 1910 (Build 12130.20272) oder höher		 Ja Ja Ja
Mac:
Version 16.47 oder höher		 Ja Ja Ja

Hinweis

Das On-Send-Feature wurde offiziell im Anforderungssatz 1.8 veröffentlicht (details finden Sie unter Aktueller Server- und Clientsupport ). Beachten Sie jedoch, dass die Unterstützungsmatrix des Features eine Obermenge der Anforderungssätze darstellt.

Wichtig

Add-Ins, die das On-Send-Feature verwenden, sind in AppSource nicht zulässig.

Wie funktioniert die „On-Send“-Funktion?

Mithilfe des On-Send-Features können Sie das synchrone Ereignis ItemSend in Ihr Outlook-Add-In integrieren. Dieses Ereignis erkennt, wenn der Benutzer die Schaltfläche Senden drückt (oder die Schaltfläche Update sendenfür vorhandene Besprechungen) und kann dazu verwendet werden, das Senden des Elements zu blockieren, falls sie die Validierung nicht besteht. Wenn ein Benutzer beispielsweise ein Ereignis des Typs „Nachricht senden“ auslöst, kann ein Outlook-Add-In mit integrierter „On-Send“-Funktion:

  • Lesen und überprüfen Sie den Inhalt der E-Mail-Nachricht.
  • Vergewissern Sie sich, dass die Nachricht eine Betreffzeile enthält.
  • Legen Sie einen vordefinierten Empfänger fest.

Die Überprüfung erfolgt auf der Clientseite in Outlook, wenn das Sendeereignis ausgelöst wird, und das Add-In hat bis zu 5 Minuten Zeit, bevor ein Zeitüberschreitung auftritt. Wenn die Überprüfung fehlschlägt, wird das Senden des Elements blockiert, und eine Fehlermeldung wird in einer Informationsleiste angezeigt, die den Benutzer auffordert, Maßnahmen zu ergreifen.

Hinweis

Wenn in Outlook im Web das On-Send-Feature in einer Nachricht ausgelöst wird, die auf der Outlook-Browserregisterkarte erstellt wird, wird das Element in ein eigenes Browserfenster oder eine eigene Registerkarte eingeklallt, um die Überprüfung und andere Verarbeitung abzuschließen.

Der folgende Screenshot zeigt eine Informationsleiste, die den Absender auffordert, eine Betreffzeile hinzuzufügen:

Eine Fehlermeldung, die den Benutzer auffordert, eine fehlende Betreffzeile einzugeben.

Der folgende Screenshot zeigt eine Informationsleiste, die den Absender darauf hinweist, dass blockierte Wörter gefunden wurden.

Eine Fehlermeldung, die dem Benutzer mitteilt, dass blockierte Wörter gefunden wurden.

Einschränkungen

Aktuell gelten für das On-Send-Feature die folgenden Einschränkungen.

  • Funktion "Append-on-Send ": Wenn Sie item.body.AppendOnSendAsync im On-Send-Handler aufrufen, wird ein Fehler zurückgegeben.

  • AppSource : Sie können keine Outlook-Add-Ins, die das On-Send-Feature verwenden, in AppSource veröffentlichen, da die AppSource-Überprüfung fehlschlägt. Add-Ins, die das On-Send-Feature verwenden, sollten von Administratoren bereitgestellt werden. Wenn Sie die Option zum Veröffentlichen Ihres Add-Ins in AppSource verwenden möchten, sollten Sie stattdessen intelligente Warnungen verwenden, bei der es sich um eine neuere Version des On-Send-Features handelt. Weitere Informationen zu intelligenten Warnungen und zum Bereitstellen dieser Add-Ins finden Sie unter Verwenden von intelligenten Warnungen und den OnMessageSend- und OnAppointmentSend-Ereignissen in Ihrem Outlook-Add-In und den AppSource-Auflistungsoptionen für Ihr ereignisbasiertes Outlook-Add-In.

    Wichtig

    Wenn Sie ausführen npm run validate , um das Manifest Ihres Add-Ins zu überprüfen, erhalten Sie die Fehlermeldung "Postfach-Add-In mit ItemSend-Ereignis ist ungültig. Das Postfach-Add-In-Manifest enthält das ItemSend-Ereignis in VersionOverrides, das nicht zulässig ist." Diese Meldung wird angezeigt, da Add-Ins, die das ItemSend Ereignis verwenden, das für diese Version des On-Send-Features erforderlich ist, nicht in AppSource veröffentlicht werden können. Sie können Ihr Add-In weiterhin querladen und ausführen, sofern keine anderen Überprüfungsfehler gefunden werden.

  • Manifest : Pro Add-In wird nur ein ItemSend Ereignis unterstützt. Wenn Sie zwei oder mehr ItemSend-Ereignisse im Manifest angeben, besteht das Manifest die Validierung nicht.

  • Leistung : Mehrere Roundtrips zum Webserver, der das Add-In hostet, können sich auf die Leistung des Add-Ins auswirken. Berücksichtigen Sie die Auswirkungen auf die Leistung, wenn Sie Add-Ins erstellen, die mehrere nachrichten- oder besprechungsbasierte Vorgänge erfordern.

  • Später senden (nur Mac): Wenn On-Send-Add-Ins vorhanden sind, ist das Feature Später senden nicht verfügbar.

Außerdem wird davon abgeraten, im On-Send-Ereignishandler aufzurufen item.close() , da das Schließen des Elements nach Abschluss des Ereignisses automatisch erfolgen sollte.

Einschränkungen hinsichtlich des Postfachtyps/-modus

Das On-Send-Feature wird nur für Benutzerpostfächer in Outlook im Web, Windows und Mac unterstützt. Zusätzlich zu Situationen, in denen Add-Ins nicht wie im Abschnitt Postfachelemente für Add-Ins verfügbar auf der Übersichtsseite für Outlook-Add-Ins angegeben aktiviert werden, wird die Funktionalität derzeit nicht für den Offlinemodus unterstützt, in dem dieser Modus verfügbar ist.

In Fällen, in denen Outlook-Add-Ins nicht aktiviert werden, wird das On-Send-Add-In nicht ausgeführt, und die Nachricht wird gesendet.

Wenn das On-Send-Feature aktiviert und verfügbar ist, das Postfachszenario jedoch nicht unterstützt wird, lässt Outlook das Senden nicht zu.

Mehrere „On-Send“-Add-Ins

Sind mehrere On-Send-Add-Ins installiert, werden die Add-Ins in der Reihenfolge ihres Empfangs durch die API getAppManifestCall oder getExtensibilityContext ausgeführt. Wenn das erste Add-In das Senden erlaubt, kann das zweite Add-In eine Änderung vornehmen, die beim ersten Add-In eigentlich eine Blockierung des Sendens ausgelöst hätte. Das erste Add-In wird jedoch nicht wieder ausgeführt, wenn alle installierten Add-Ins das Senden erlaubt haben.

Ein Beispiel: Add-In 1 und Add-In 2 verwenden beide die „On-Send“-Funktion. Add-In 1 wurde zuerst installiert, Add-In 2 danach. Add-In 1 überprüft als Bedingung für die Sendeerlaubnis, ob das Wort „Fabrikam“ in der Nachricht vorkommt. Add-In 2 jedoch entfernt alle Vorkommen des Wortes „Fabrikam“. Die Nachricht wird gesendet, sobald alle Vorkommen des Wortes „Fabrikam“ entfernt wurden (aufgrund der Installationsreihenfolge von Add-In 1 und Add-In 2).

Bereitstellen von Outlook-Add-Ins mit integriertem On-Send-Feature

Es empfiehlt sich, Outlook-Add-Ins, die die „On-Send“-Funktion verwenden, von einem Administrator bereitstellen zu lassen. Der Administrator muss sicherstellen, dass das „On-Send“-Add-In:

  • Immer vorhanden ist, wenn ein Verfassen-Element geöffnet wird (E-Mail: neue Nachricht, Antworten oder Weiterleiten).
  • Vom Benutzer weder geschlossen noch deaktiviert werden kann.

Installieren von Outlook mit integriertem On-Send-Feature

Um das On-Send-Feature in Outlook nutzen zu können, müssen Add-Ins für die verschiedenen Typen von Sendeereignissen konfiguriert sein. Wählen Sie die Plattform aus, die Sie konfigurieren möchten.

Add-Ins für Outlook im Web (klassisch), die das On-Send-Feature verwenden, werden für Benutzer ausgeführt, denen eine Outlook im Web Postfachrichtlinie zugewiesen ist, für die das OnSendAddinsEnabled-Flag auf truefestgelegt ist.

Führen Sie die folgenden Exchange Online PowerShell-Cmdlets aus, um ein neues Add-In zu installieren:

$Data=Get-Content -Path '.\Contoso Message Body Checker.xml' -Encoding Byte –ReadCount 0

New-App -OrganizationApp -FileData $Data -DefaultStateForUser Enabled

Hinweis

Wie Sie über die Remote-PowerShell eine Verbindung mit Exchange Online herstellen können, erfahren Sie unter Herstellen einer Verbindung mit Exchange Online PowerShell.

Aktivieren der Funktion „On-Send“

Die „On-Send“-Funktion ist standardmäßig deaktiviert. Administratoren können die „On-Send“-Funktion mithilfe von Exchange Online PowerShell-Cmdlets aktivieren.

So aktivieren Sie „On-Send“-Add-Ins für alle Benutzer:

  1. Erstellen Sie eine neue Outlook im Web-Postfachrichtlinie.

     New-OWAMailboxPolicy OWAOnSendAddinAllUserPolicy

    Hinweis

    Administratoren können eine vorhandene Richtlinie verwenden; die „On-Send“-Funktion wird jedoch nur für bestimmte Postfachtypen unterstützt. Für nicht unterstützte Postfächer wird das Senden in Outlook im Web standardmäßig blockiert.

  2. Aktivieren der Funktion „On-Send“.

     Get-OWAMailboxPolicy OWAOnSendAddinAllUserPolicy | Set-OWAMailboxPolicy –OnSendAddinsEnabled:$true

  3. Weisen Sie die Richtlinie Benutzern zu.

     Get-User -Filter {RecipientTypeDetails -eq 'UserMailbox'}|Set-CASMailbox -OwaMailboxPolicy OWAOnSendAddinAllUserPolicy

Aktivieren des On-Send-Features für eine Benutzergruppe

Gehen Sie wie unten beschrieben vor, um die „On-Send“-Funktion für eine bestimmte Gruppe von Benutzern zu aktivieren. In diesem Beispiel möchte der Administrator die „On-Send“-Add-In-Funktion in Outlook im Web nur in einer Umgebung für Benutzer des Typs „Finance“ aktivieren (also Benutzer aus der Finanzabteilung).

  1. Erstellen Sie eine neue Outlook im Web-Postfachrichtlinie für die Gruppe.

     New-OWAMailboxPolicy FinanceOWAPolicy

    Hinweis

    Administratoren können eine vorhandene Richtlinie verwenden; die „On-Send“-Funktion wird jedoch nur für bestimmte Postfachtypen unterstützt (siehe Einschränkungen hinsichtlich des Postfachtyps weiter oben in diesem Artikel). Für nicht unterstützte Postfächer wird das Senden in Outlook im Web standardmäßig blockiert.

  2. Aktivieren der Funktion „On-Send“.

     Get-OWAMailboxPolicy FinanceOWAPolicy | Set-OWAMailboxPolicy –OnSendAddinsEnabled:$true

  3. Weisen Sie die Richtlinie Benutzern zu:

     $targetUsers = Get-Group 'Finance'|select -ExpandProperty members
 $targetUsers | Get-User -Filter {RecipientTypeDetails -eq 'UserMailbox'}|Set-CASMailbox -OwaMailboxPolicy FinanceOWAPolicy

Hinweis

Es kann bis zu 60 Minuten dauern, bis die Richtlinie wirksam wird. Warten Sie, oder starten Sie die Internetinformationsdienste (IIS) neu. Sobald die Richtlinie wirksam wird, wird die „On-Send“-Funktion für die Gruppe aktiviert.

Deaktivieren des On-Send-Features

Führen Sie die nachfolgenden Cmdlets aus, um die „On-Send“-Funktion für einen Benutzer zu deaktivieren oder eine Outlook im Web-Postfachrichtlinie zuzuweisen, für die das Flag nicht aktiviert ist. In diesem Beispiel ist die Postfachrichtlinie ContosoCorpOWAPolicy.

Get-CASMailbox joe@contoso.com | Set-CASMailbox –OWAMailboxPolicy "ContosoCorpOWAPolicy"

Hinweis

Weitere Informationen dazu, wie Sie mit dem Cmdlet Set-OwaMailboxPolicy vorhandene Outlook im Web-Postfachrichtlinien konfigurieren können, finden Sie unter Set-OwaMailboxPolicy.

Führen Sie die folgenden Cmdlets aus, um die „On-Send“-Funktion für alle Benutzer zu deaktivieren, denen eine spezifische Outlook im Web-Postfachrichtlinie zugewiesen ist.

Get-OWAMailboxPolicy OWAOnSendAddinAllUserPolicy | Set-OWAMailboxPolicy –OnSendAddinsEnabled:$false

Anwendungsszenarien für die „On-Send“-Funktion

Nachfolgend sind die unterstützten sowie die nicht unterstützten Anwendungsszenarien für Add-Ins beschrieben, die die „On-Send“-Funktion verwenden.

Ereignishandler werden dynamisch definiert

Die Ereignishandler Ihres Add-Ins müssen durch den Zeitpunkt Office.initialize oder Office.onReady() den Aufruf definiert werden (weitere Informationen finden Sie unter Starten eines Outlook-Add-Ins und Initialisieren Ihres Office-Add-Ins). Wenn Ihr Handlercode während der Initialisierung durch bestimmte Umstände dynamisch definiert wird, müssen Sie eine Stubfunktion erstellen, um den Handler aufzurufen, sobald er vollständig definiert ist. Auf die Stubfunktion muss im <Attribut des Event-Elements> Ihres Manifests verwiesen werden.FunctionName Diese Problemumgehung stellt sicher, dass Ihr Handler definiert ist und bereit ist, einmal Office.initialize oder Office.onReady() ausgeführt zu werden.

Wenn ihr Handler nach der Initialisierung des Add-Ins nicht definiert ist, wird der Absender über eine Informationsleiste im E-Mail-Element benachrichtigt, dass "die Rückruffunktion nicht erreichbar ist".

Benutzerpostfach mit aktivierter „On-Send“-Add-In-Funktion, aber ohne installierte Add-Ins

In diesem Szenario kann der Benutzer Nachrichten und Besprechungselemente senden, ohne dass Add-Ins ausgeführt werden.

Benutzerpostfach mit aktivierter „On-Send“-Add-In-Funktion und installierten sowie aktivierten Add-Ins mit „On-Send“-Unterstützung

Bei Eintritt des Sendeereignisses werden Add-Ins ausgeführt, die das Senden entweder zulassen oder blockieren.

Postfachstellvertretung: Postfach 1 mit vollständigem Satz an Zugriffsberechtigungen für Postfach 2

Webbrowser – klassisches Outlook

Szenario On-Send-Feature im Postfach 1 On-Send-Feature im Postfach 2 Outlook-Websitzung (klassisch) Ergebnis Unterstützt?
1 Aktiviert Aktiviert Neue Sitzung Postfach 1 kann kein Nachrichten- oder ein Besprechungselement aus Postfach 2 senden. Zurzeit nicht unterstützt. Verwenden Sie Szenario 3 als Umgehungslösung.
2 Deaktiviert Aktiviert Neue Sitzung Postfach 1 kann kein Nachrichten- oder ein Besprechungselement aus Postfach 2 senden. Zurzeit nicht unterstützt. Verwenden Sie Szenario 3 als Umgehungslösung.
3 Aktiviert Aktiviert Selbe Sitzung Zum Zeitpunkt des Sendens werden die Postfach 1 zugewiesenen „On-Send“-Add-Ins ausgeführt. Unterstützt
4 Aktiviert Deaktiviert Neue Sitzung Keine „On-Send“-Add-Ins werden ausgeführt; Nachrichten- oder Besprechungselement wurde gesendet. Unterstützt

Webbrowser (modernes Outlook), Windows, Mac

Um „On-Send“ zu erzwingen, sollten Administratoren sicherstellen, dass die Richtlinie für beide Postfächer aktiviert wurde. Informationen zum Unterstützen des Stellvertretungszugriffs in einem Add-In finden Sie unter Aktivieren von Szenarien für freigegebene Ordner und freigegebene Postfächer.

Benutzerpostfach mit aktiviertem/r On-Send-Add-In-Feature/-Richtlinie, installierten und aktivierten Add-Ins mit On-Send-Unterstützung und aktiviertem Offlinemodus

On-Send-Add-Ins werden gemäß dem Onlinestatus des Benutzers, des Add-In-Back-Ends und von Exchange ausgeführt.

Status des Benutzers

Wenn der Benutzer online ist, werden die „On-Send“-Add-Ins zum Zeitpunkt des Sendens ausgeführt. Ist der Benutzer offline, werden die „On Send“-Add-Ins zum Zeitpunkt des Sendens nicht ausgeführt, und das Nachrichten- oder Besprechungselement wird nicht gesendet.

Status des Add-In-Back-Ends

Ein On-Send-Add-In wird ausgeführt, wenn sein Back-End online und erreichbar ist. Wenn das Back-End offline ist, wird das Senden deaktiviert.

Status von Exchange

Das On-Send-Add-In wird beim Senden ausgeführt, wenn der Exchange-Sever online und erreichbar ist. Wenn das On-Send-Add-In Exchange nicht erreichen kann und die entsprechende Richtlinie bzw. das Cmdlet aktiviert ist, wird das Senden deaktiviert.

Hinweis

Auf einem Mac ist die Schaltfläche Senden (oder die Schaltfläche Update senden für vorhandene Besprechungen) in jedem Offlinezustand deaktiviert, und es wird eine Benachrichtigung angezeigt, die besagt, dass die Organisation das senden nicht zulässt, wenn der Benutzer offline ist.

Benutzer können ein Element bearbeiten, während On-Send-Add-Ins daran arbeiten

Während On-Send-Add-Ins ein Element verarbeiten, kann der Benutzer das Element bearbeiten, indem er beispielsweise unangemessenen Text oder Anlagen hinzufügt. Wenn Sie verhindern möchten, dass der Benutzer das Element bearbeitet, während das Add-In beim Senden verarbeitet wird, können Sie eine Problemumgehung mithilfe eines Dialogfelds implementieren. Diese Problemumgehung kann in Outlook im Web (klassisch), Windows und Mac verwendet werden.

Wichtig

Moderne Outlook im Web: Um zu verhindern, dass der Benutzer das Element bearbeitet, während das Add-In beim Senden verarbeitet wird, sollten Sie das OnSendAddinsEnabled-Flag auf true festlegen, wie weiter oben in diesem Artikel im Abschnitt Installieren von Outlook-Add-Ins, die on-send verwenden beschrieben wird.

In Ihrem On-Send-Handler:

  1. Rufen Sie displayDialogAsync auf, um ein Dialogfeld zu öffnen, sodass Mausklicks und Tastaturanschläge deaktiviert werden.

    Wichtig

    Um dieses Verhalten in klassischen Outlook im Web zu erhalten, sollten Sie die displayInIframe-Eigenschaft im options -Parameter des displayDialogAsync Aufrufs auf true festlegen.

  2. Implementieren Sie die Verarbeitung des Elements.

  3. Schließen Sie das Dialogfeld. Behandeln Sie außerdem, was geschieht, wenn der Benutzer das Dialogfeld schließt.

Codebeispiele

Die folgenden Codebeispiele demonstrieren, wie Sie ein einfaches „On-Send“-Add-In erstellen können. Das Codebeispiel, auf dem diese Beispiele basieren, finden Sie unter Outlook-Add-in-On-Send.

Tipp

Wenn Sie ein Dialogfeld mit dem On-Send-Ereignis verwenden, stellen Sie sicher, dass Sie den Dialog schließen, bevor Sie das Ereignis abschließen.

Manifest, Versionsüberschreibung und Ereignis

Das Codebeispiel Outlook-Add-in-On-Send umfasst zwei Manifeste:

  • Contoso Message Body Checker.xml – Zeigt, wie der Text einer Nachricht beim Senden auf eingeschränkte Wörter oder vertrauliche Informationen überprüft wird.

  • Contoso Subject and CC Checker.xml – Zeigt, wie Sie der CC-Zeile einen Empfänger hinzufügen und überprüfen, ob die Nachricht beim Senden eine Betreffzeile enthält.

In der Manifestdatei Contoso Message Body Checker.xml geben Sie die Funktionsdatei und den Funktionsnamen an, die bei Eintreten des Ereignisses ItemSend aufgerufen werden sollen. Der Vorgang wird synchron ausgeführt.

<Hosts>
    <Host xsi:type="MailHost">
        <DesktopFormFactor>
            <!-- The functionfile and function name to call on message send.  -->
            <!-- In this case, the function validateBody will be called within the JavaScript code referenced in residUILessFunctionFileUrl. -->
            <FunctionFile resid="residUILessFunctionFileUrl" />
            <ExtensionPoint xsi:type="Events">
                <Event Type="ItemSend" FunctionExecution="synchronous" FunctionName="validateBody" />
            </ExtensionPoint>
        </DesktopFormFactor>
    </Host>
</Hosts>

Wichtig

Wenn Sie Visual Studio 2019 zum Entwickeln Ihres On-Send-Add-Ins verwenden, erhalten Sie möglicherweise eine Validierungswarnung wie die folgende: "Dies ist ein ungültiger xsi:type 'http://schemas.microsoft.com/office/mailappversionoverrides/1.1:Events'.". Um dies zu umgehen, benötigen Sie eine neuere Version der MailAppVersionOverridesV1_1.xsd, die als GitHub-Gist in einem Blog zu dieser Warnung bereitgestellt wurde.

Im folgenden Beispiel sehen Sie für die Manifestdatei Contoso Subject and CC Checker.xml die Funktionsdatei und den Funktionsname, die bei Eintreten eines Ereignisses des Typs „Nachricht senden“ aufgerufen werden sollen.

<Hosts>
    <Host xsi:type="MailHost">
        <DesktopFormFactor>
            <!-- The functionfile and function name to call on message send.  -->
            <!-- In this case the function validateSubjectAndCC will be called within the JavaScript code referenced in residUILessFunctionFileUrl. -->
            <FunctionFile resid="residUILessFunctionFileUrl" />
            <ExtensionPoint xsi:type="Events">
                <Event Type="ItemSend" FunctionExecution="synchronous" FunctionName="validateSubjectAndCC" />
            </ExtensionPoint>
        </DesktopFormFactor>
    </Host>
</Hosts>

Die On-Send-API erfordert VersionOverrides v1_1. Unten sehen Sie, wie Sie Ihrem Manifest den Knoten VersionOverrides hinzufügen können.

 <VersionOverrides xmlns="http://schemas.microsoft.com/office/mailappversionoverrides" xsi:type="VersionOverridesV1_0">
     <!-- On-send requires VersionOverridesV1_1 -->
     <VersionOverrides xmlns="http://schemas.microsoft.com/office/mailappversionoverrides/1.1" xsi:type="VersionOverridesV1_1">
         ...
     </VersionOverrides>
</VersionOverrides>

Hinweis

Weitere Informationen zu Manifesten für Outlook-Add-Ins finden Sie unter Office-Add-Ins-Manifest.

Event- und item-Objekte sowie body.getAsync- und body.setAsync-Methoden

Verwenden Sie den Namespace Office.context.mailbox.item, um auf das aktuell ausgewählte Nachrichten- oder Besprechungselement zuzugreifen (in diesem Beispiel die neu verfasste Nachricht). Das ItemSend Ereignis wird automatisch vom On-Send-Feature an die im Manifest angegebene Funktion übergeben, in diesem Beispiel die validateBody -Funktion.

let mailboxItem;

Office.initialize = function (reason) {
    mailboxItem = Office.context.mailbox.item;
}

// Entry point for Contoso Message Body Checker add-in before send is allowed.
// <param name="event">ItemSend event is automatically passed by on-send code to the function specified in the manifest.</param>
function validateBody(event) {
    mailboxItem.body.getAsync("html", { asyncContext: event }, checkBodyOnlyOnSendCallBack);
}

Die validateBody Funktion ruft den aktuellen Text im angegebenen Format (HTML) ab und übergibt das ItemSend Ereignisobjekt, auf das der Code in der Rückruffunktion zugreifen möchte. Neben der Methode getAsync stellt das Objekt Body auch die Methode setAsync bereit, mit der Sie den Nachrichtentext durch einen angegebenen Text ersetzen können.

Hinweis

Weitere Informationen finden Sie unter Event-Objekt und Body.getAsync.

NotificationMessages-Objekt und event.completed-Methode

Die Funktion checkBodyOnlyOnSendCallBack verwendet einen regulären Ausdruck, um zu ermitteln, ob der Nachrichtentext blockierte Wörter enthält. Findet die Funktion Wörter, die im Array mit den verbotenen Wörtern definiert sind, blockiert sie das Senden der E-Mail und benachrichtigt den Absender über die Informationsleiste. Dazu wird die notificationMessages -Eigenschaft des Item -Objekts verwendet, um ein NotificationMessages-Objekt zurückzugeben. Anschließend ruft sie wie im Beispiel unten dargestellt die Methode addAsync auf, um dem Element eine Benachrichtigung hinzuzufügen.

// Determine whether the body contains a specific set of blocked words. If it contains the blocked words, block email from being sent. Otherwise allow sending.
// <param name="asyncResult">ItemSend event passed from the calling function.</param>
function checkBodyOnlyOnSendCallBack(asyncResult) {
    const listOfBlockedWords = new Array("blockedword", "blockedword1", "blockedword2");
    const wordExpression = listOfBlockedWords.join('|');

    // \b to perform a "whole words only" search using a regular expression in the form of \bword\b.
    // i to perform case-insensitive search.
    const regexCheck = new RegExp('\\b(' + wordExpression + ')\\b', 'i');
    const checkBody = regexCheck.test(asyncResult.value);

    if (checkBody) {
        mailboxItem.notificationMessages.addAsync('NoSend', { type: 'errorMessage', message: 'Blocked words have been found in the body of this email. Please remove them.' });
        // Block send.
        asyncResult.asyncContext.completed({ allowEvent: false });
    }

    // Allow send.
    asyncResult.asyncContext.completed({ allowEvent: true });
}

Im Folgenden sind die Parameter für die -Methode aufgeführt addAsync .

  • NoSend – Eine Zeichenfolge, bei der es sich um einen vom Entwickler angegebenen Schlüssel handelt, der auf eine Benachrichtigungsnachricht verweist. Mit seiner Hilfe können Sie die Nachricht später ändern. Der Schlüssel darf nicht länger als 32 Zeichen sein.
  • type – Eine der Eigenschaften des JSON-Objektparameters. Sie stellt den Typ der Nachricht dar. Die Typen entsprechen den Werten der Enumeration Office.MailboxEnums.ItemNotificationMessageType. Mögliche Werte sind Statusanzeige, Informationsnachricht und Fehlermeldung. In diesem Beispiel ist type eine Fehlermeldung.
  • message – Eine der Eigenschaften des JSON-Objektparameters. In diesem Beispiel ist message der Text der Benachrichtigung.

Um zu signalisieren, dass das Add-In die Verarbeitung des durch den ItemSend Sendevorgang ausgelösten Ereignisses abgeschlossen hat, rufen Sie die methode event.completed({allowEvent:Boolean}) auf. Die Eigenschaft allowEvent ist ein boolescher Wert. Ist sie auf true festgelegt, darf gesendet werden. Ist sie auf false festgelegt, wird das Senden der E-Mail-Nachricht blockiert.

replaceAsync-, removeAsync- und getAllAsync-Methoden

Zusätzlich zur Methode addAsync enthält das NotificationMessages-Objekt auch die Methoden replaceAsync, removeAsync und getAllAsync. Diese Methoden werden in diesem Codebeispiel nicht verwendet. Weitere Informationen finden Sie unter NotificationMessages.

Betreff- und CC-Überprüfungscode

Das folgende Codebeispiel veranschaulicht, wie Sie beim Senden der CC-Zeile einen Empfänger hinzufügen und überprüfen, ob die Nachricht eine Betreffzeile hat. In diesem Beispiel wird die „On-Send“-Funktion verwendet, um das Senden der E-Mail zu erlauben oder zu unterbinden.

// Invoke by Contoso Subject and CC Checker add-in before send is allowed.
// <param name="event">ItemSend event is automatically passed by on-send code to the function specified in the manifest.</param>
function validateSubjectAndCC(event) {
    shouldChangeSubjectOnSend(event);
}

// Determine whether the subject should be changed. If it is already changed, allow send. Otherwise change it.
// <param name="event">ItemSend event passed from the calling function.</param>
function shouldChangeSubjectOnSend(event) {
    mailboxItem.subject.getAsync(
        { asyncContext: event },
        function (asyncResult) {
            addCCOnSend(asyncResult.asyncContext);
            //console.log(asyncResult.value);
            // Match string.
            const checkSubject = (new RegExp(/\[Checked\]/)).test(asyncResult.value)
            // Add [Checked]: to subject line.
            subject = '[Checked]: ' + asyncResult.value;

            // Determine whether a string is blank, null, or undefined.
            // If yes, block send and display information bar to notify sender to add a subject.
            if (asyncResult.value === null || (/^\s*$/).test(asyncResult.value)) {
                mailboxItem.notificationMessages.addAsync('NoSend', { type: 'errorMessage', message: 'Please enter a subject for this email.' });
                asyncResult.asyncContext.completed({ allowEvent: false });
            }
            else {
                // If can't find a [Checked]: string match in subject, call subjectOnSendChange function.
                if (!checkSubject) {
                    subjectOnSendChange(subject, asyncResult.asyncContext);
                    //console.log(checkSubject);
                }
                else {
                    // Allow send.
                    asyncResult.asyncContext.completed({ allowEvent: true });
                }
            }
        });
}

// Add a CC to the email. In this example, CC contoso@contoso.onmicrosoft.com
// <param name="event">ItemSend event passed from calling function</param>
function addCCOnSend(event) {
    mailboxItem.cc.setAsync(['Contoso@contoso.onmicrosoft.com'], { asyncContext: event });
}

// Determine whether the subject should be changed. If it is already changed, allow send, otherwise change it.
// <param name="subject">Subject to set.</param>
// <param name="event">ItemSend event passed from the calling function.</param>
function subjectOnSendChange(subject, event) {
    mailboxItem.subject.setAsync(
        subject,
        { asyncContext: event },
        function (asyncResult) {
            if (asyncResult.status == Office.AsyncResultStatus.Failed) {
                mailboxItem.notificationMessages.addAsync('NoSend', { type: 'errorMessage', message: 'Unable to set the subject.' });

                // Block send.
                asyncResult.asyncContext.completed({ allowEvent: false });
            }
            else {
                // Allow send.
                asyncResult.asyncContext.completed({ allowEvent: true });
            }
        });
}

Weitere Informationen zum Hinzufügen eines Empfängers zur CC-Zeile und zum Überprüfen, ob die E-Mail-Nachricht beim Senden eine Betreffzeile enthält, und um die APIs anzuzeigen, die Sie verwenden können, finden Sie im Outlook-Add-in-On-Send-Beispiel. Der Code ist gut kommentiert.

Debuggen von Outlook-Add-Ins, die on-send verwenden

Anweisungen zum Debuggen Ihres On-Send-Add-Ins finden Sie unter Debuggen von Funktionsbefehlen in Outlook-Add-Ins.

Tipp

Wenn der Fehler "Die Rückruffunktion ist nicht erreichbar" angezeigt wird, wenn Ihre Benutzer Ihr Add-In ausführen und der Ereignishandler Ihres Add-Ins dynamisch definiert ist, müssen Sie als Problemumgehung eine Stubfunktion erstellen. Weitere Informationen finden Sie unter Ereignishandler werden dynamisch definiert .

Siehe auch