„On Send“-Funktion für Outlook-Add-InsOn send feature for Outlook add-ins

Die „On Send“-Funktion für Outlook-Add-Ins bietet Ihnen die Möglichkeit, E-Mails zu behandeln und bestimmte Aktionen für E-Mail-Benutzer zu blockieren. Darüber hinaus können Add-Ins mit ihrer Hilfe bestimmte Elemente zum Zeitpunkt des Sendens festlegen. Hier zwei Anwendungsbeispiele für die „On Send“-Funktion:The on send feature for Outlook add-ins provides a way to handle email or block email users from certain actions, and allows an add-in to set certain items on send. For example, you can use the on send feature to:

  • Sie können verhindern, dass Benutzer vertrauliche Informationen senden oder die Betreffzeile leer lassen.Prevent a user from sending sensitive information or leaving the subject line blank.
  • Sie können der CC-Zeile einen spezifischen Empfänger hinzufügen.Add a specific recipient to the CC line.

Hinweis

Das On-Send-Feature wird derzeit für Outlook im Web nur in Office 365 unterstützt. Unterstützung für andere Plattformen wird in Kürze bereitgestellt. Add-ins, die das On-Send-Feature verwenden, sind im Office Store nicht zulässig.The on send feature is currently supported for Outlook on the web in Office 365 only. Support for other platforms is coming soon. Add-ins that use the on send feature aren't allowed in the Office Store.

Die „On Send“-Funktion wird von Ereignissen ausgelöst. Aktuell unterstützt die Funktion den Ereignistyp ItemSend. Mithilfe von Ereignissen in Outlook-Add-Ins können Sie Benutzeraktionen behandeln, überprüfen oder blockieren, auf die bestimmte Bedingungen zutreffen. Beispielsweise können Sie mit Ereignissen:The on send feature is triggered by events. Currently, the feature supports the ItemSend event type. Events in Outlook add-ins enable you to handle, check, or block user actions when something of interest occurs. For example, events provide ways to:

  • Benutzeraktionen steuernControl user actions
  • Änderungen behandelnHandle changes
  • Benutzeraktionen wie Klicks auf Schaltflächen signalisierenSignal user actions such as button clicks
  • Von Benutzern eingegebene Daten überprüfenVerify user data input
  • Nachrichteninhalte validierenValidate content in a message

Informationen zu den für die „On Send“-Funktion geltenden Einschränkungen finden Sie im Abschnitt Einschränkungen weiter unten in diesem Artikel.For information about limitations related to the on send feature, see Limitations later in this article.

Wie funktioniert die „On Send“-Funktion?How does the on send feature work?

Mithilfe der „On Send“-Funktion 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 sie anklickt, und kann dazu verwendet werden, das Senden der E-Mail-Nachricht 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:You can use the on send feature to build an Outlook add-in that integrates the ItemSend synchronous event. This event detects that the user is pressing the Send button and can be used to block the email from sending if the message validation fails. For example, when a user triggers a message send event, an Outlook add-in that uses the on send feature can:

  • Den Inhalt der E-Mail-Nachricht auslesen und validierenRead and validate the email message contents
  • Überprüfen, ob die Nachricht eine Betreffzeile enthältVerify that the message includes a subject line
  • Einen vordefinierten Empfänger festlegenSet a predetermined recipient

Die Überprüfung erfolgt auf dem Client in Outlook im Web beim Auslösen des Ergebnisses. Bei Nichtbestehen der Validierung wird das Senden der E-Mail blockiert, und es wird eine Fehlermeldung mit einer Informationsleiste angezeigt, die den Benutzer zu einer bestimmten Handlung auffordert.Validation is done on the client side in Outlook on the web, on trigger of the send event. If validation fails, the sending of the email is blocked, and an error message with an information bar is displayed that prompts the user to take action.

Der folgende Screenshot zeigt eine Informationsleiste, die den Absender auffordert, eine Betreffzeile hinzuzufügen:The following screenshot shows an information bar that notifies the sender to add a subject.


Screenshot mit einer Fehlermeldung, die den Benutzer zur Eingabe der fehlenden Betreffzeile auffordert



Der folgende Screenshot zeigt eine Informationsleiste, die den Absender darauf hinweist, dass blockierte Wörter gefunden wurden.The following screenshot shows an information bar that notifies the sender that blocked words were found.


Screenshot mit einer Fehlermeldung, die den Benutzer darauf hinweist, dass blockierte Wörter gefunden wurden

EinschränkungenLimitations

Aktuell gelten für die „On Send“-Funktion die folgenden Einschränkungen:The on send feature currently has the following limitations:

  • Office Store: – Outlook-Add-Ins, die die „On Send“-Funktion verwenden, dürfen nicht im Office Store veröffentlicht werden. Add-Ins, die das „On Send“-Ereignis verwenden, bestehen die Office Store-Validierung nicht.Office Store – You can't publish Outlook add-ins that use the on send feature to the Office Store. Add-ins that use the on send event will fail Office Store validation.
  • Manifest: – Pro Add-In wird nur ein einziges ItemSend-Ereignis unterstützt. Wenn Sie zwei oder mehr ItemSend-Ereignisse im Manifest angeben, besteht das Manifest die Validierung nicht.Manifest – Only one ItemSend event is supported per add-in. If you have two or more ItemSend events in a manifest, the manifest will fail validation.
  • Leistung: – Mehrere Roundtrips zum Webserver, der das Add-In hostet, können die Add-In-Leistung beeinträchtigen. Berücksichtigen Sie mögliche negative Auswirkungen auf die Leistung, wenn Sie Add-Ins erstellen, die mehrere E-Mail-basierte Vorgänge erfordern.Performance – Multiple roundtrips to the web server that hosts the add-in can affect the performance of the add-in. Consider the effects on performance when you create add-ins that require multiple email message-based operations.

Einschränkungen hinsichtlich des PostfachtypsMailbox type limitations

Die On-Send-Funktionalität wir nur für Benutzerpostfächer in Outlook im Web unterstützt. Die Funktionalität wird derzeit nicht für die folgenden Postfachtypen unterstützt:On send functionality is only supported for user mailboxes in Outlook on the web. The functionality is not currently supported for the following mailbox types:

  • Freigegebene PostfächerShared mailboxes
  • Postfächer im OfflinemodusOffline mode
  • GruppenpostfächerGroup mailboxes

Outlook im Web lässt das Senden nicht zu, wenn das On-Send-Feature für diese Postfachtypen aktiviert ist. Wenn ein Benutzer auf eine E-Mail in einem Gruppenpostfach antwortet, wird das On-Send-Add-In nicht ausgeführt und die Nachricht wird gesendet.Outlook on the web won't allow sending if the on send feature is enabled for these mailbox types. If a user responds to an email in a group mailbox, the on send add-in won't run and the message will be sent.

Mehrere „On Send“-Add-InsMultiple on send add-ins

Sind mehrere „On Send“-Add-Ins installiert, werden die Add-Ins in der Reihenfolge ausgeführt, in der sie installiert wurden. 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.If more than one on send add-in is installed, the add-ins will run in the order in which they were installed. If the first add-in allows sending, the second add-in can change something that would make the first one block sending. However, the first add-in won't run again if all installed add-ins have allowed sending.

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).For example, Add-in1 and Add-in2 both use the on send feature. Add-in1 is installed first, and Add-in2 is installed second. Add-in1 verifies that the word Fabrikam appears in the message as a condition for the add-in to allow send. However, Add-in2 removes any occurrences of the word Fabrikam. The message will send with all instances of Fabrikam removed (due to the order of installation of Add-in1 and Add-in2).

Bereitstellen von Outlook-Add-Ins mit integrierter „On Send“-FunktionDeploying Outlook add-ins that use on send

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:We recommend that administrators deploy Outlook add-ins that use the on send feature. Administrators have to ensure that the on send add-in:

  • Immer vorhanden ist, wenn ein Verfassen-Element geöffnet wird (E-Mail, neue Nachricht, Antwort oder Weiterleitung)Is always present any time a compose item is opened (for email, new, reply, or forward).
  • Vom Benutzer weder geschlossen noch deaktiviert werden kannCan't be closed or disabled by the user.

Installieren von Outlook-Add-Ins mit integrierter „On Send“-FunktionInstalling Outlook add-ins that use on send

Das On-Send-Feature in Outlook im Web erfordert, dass Add-Ins für die Senden-Ereignistypen konfiguriert sind. Add-ins für Outlook im Web, die das On-Send-Feature verwenden, werden für Benutzer ausgeführt, denen eine Outlook im Web-Postfachrichtlinie zugeordnet ist, bei denen das OnSendAddinsEnabled-Flag auf truefestgelegt wurde.The on send feature in Outlook on the web requires that add-ins are configured for the send event types. Add-ins for Outlook on the web that use the on send feature will run for users who are assigned an Outlook on the web mailbox policy that has the OnSendAddinsEnabled flag set to true.

Führen Sie die folgenden Exchange Online PowerShell-Cmdlets aus, um ein neues Add-In zu installieren:To install a new add-in, run the following Exchange Online PowerShell cmdlets.

$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.To learn how to use remote PowerShell to connect to Exchange Online, see Connect to Exchange Online PowerShell.

Aktivieren der „On Send“-FunktionEnabling the on send feature

Die „On Send“-Funktion ist standardmäßig deaktiviert. Administratoren können die „On Send“-Funktion mithilfe von Exchange Online PowerShell-Cmdlets aktivieren.By default, on send functionality is disabled. Administrators can enable on send by running Exchange Online PowerShell cmdlets.

So aktivieren Sie „On Send“-Add-Ins für alle Benutzer:To enable on send add-ins for all users:

  1. Erstellen Sie eine neue Outlook im Web-Postfachrichtlinie:Create a new Outlook on the web mailbox policy.

     New-OWAMailboxPolicy OWAOnSendAddinAllUserPolicy
    

    Hinweis

    Administratoren können eine vorhandene Richtlinie verwenden, jedoch wird die On-Send-Funktionalität nur für bestimmte Postfachtypen unterstützt. Das standardmäßige Senden in Outlook im Web von nicht unterstützten Postfächern wird blockiert.Administrators can use an existing policy, but on send functionality is only supported on certain mailbox types. Unsupported mailboxes will be blocked from sending by default in Outlook on the web.

  2. Aktivieren Sie die „On Send“-Funktion:Enable the on send feature.

     Get-OWAMailboxPolicy OWAOnSendAddinAllUserPolicy | Set-OWAMailboxPolicy –OnSendAddinsEnabled:$true
    
  3. Weisen Sie die Richtlinie Benutzern zu:Assign the policy to users.

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

Aktivieren der „On Send“-Funktion für eine BenutzergruppeEnabling the on send feature for a group of users

Zum Aktivieren des On-Send-Features für eine bestimmte Gruppe von Benutzern sind die Schritte wie folgt. 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).To enable the on send feature for a specific group of users the steps are as follows. In this example, an administrator only wants to enable an Outlook on the web on send add-in feature in an environment for Finance users (where the Finance users are in the Finance Department).

  1. Erstellen Sie eine neue Outlook im Web-Postfachrichtlinie für die Gruppe:Create a new Outlook on the web mailbox policy for the group.

     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 Postfachtyp weiter oben in diesem Artikel). Das standardmäßige Senden in Outlook im Web von nicht unterstützten Postfächern wird blockiert.Administrators can use an existing policy, but on send functionality is only supported on certain mailbox types (see Mailbox type limitations earlier in this article for more information). Unsupported mailboxes will be blocked from sending by default in Outlook on the web.

  2. Aktivieren Sie die „On Send“-Funktion:Enable the on send feature.

     Get-OWAMailboxPolicy FinanceOWAPolicy | Set-OWAMailboxPolicy –OnSendAddinsEnabled:$true
    
  3. Weisen Sie die Richtlinie Benutzern zu:Assign the policy to users.

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

Hinweis

Warten Sie bis zu 60 Minuten, damit die Richtlinie wirksam wird, oder starten Sie Internetinformationsdienste (Internet Information Services, IIS) neu. Wenn die Richtlinie wirksam wird, ist das auf On-Send-Feature für die Gruppe aktiviert.Wait up to 60 minutes for the policy to take effect, or restart Internet Information Services (IIS). When the policy takes effect, the on send feature will be enabled for the group.

Deaktivieren der „On Send“-FunktionDisabling the on send feature

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.To disable the on send feature for a user or assign an Outlook on the web mailbox policy that does not have the flag enabled, run the following cmdlets. In this example, the mailbox policy is 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.For more information about how to use the Set-OwaMailboxPolicy cmdlet to configure existing Outlook on the web mailbox policies, see 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:To disable the on send feature for all users that have a specific Outlook on the web mailbox policy assigned, run the following cmdlets.

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

Anwendungsszenarien für die „On Send“-FunktionOn send feature scenarios

Nachfolgend sind die unterstützten sowie die nicht unterstützten Anwendungsszenarien für Add-Ins beschrieben, die die „On Send“-Funktion verwenden.The following are the supported and unsupported scenarios for add-ins that use the on send feature.

Benutzerpostfach mit aktivierter „On Send“-Add-In-Funktion, aber ohne installierte Add-InsUser mailbox has the on send add-in feature enabled but no add-ins are installed

In diesem Szenario kann der Benutzer E-Mails senden, ohne dass Add-Ins ausgeführt werden.In this scenario the user will be able to send mail without any add-ins executing.

Benutzerpostfach mit aktivierter „On Send“-Add-In-Funktion und installierten sowie aktivierten Add-Ins mit „On Send“-UnterstützungUser mailbox has the on send add-in feature enabled and add-ins that supports on send are installed and enabled

Bei Eintritt des Sendeereignisses werden Add-Ins ausgeführt, die das Senden entweder zulassen oder blockieren.Add-ins will run during the send event, which will then either allow or block the user from sending.

Postfachstellvertretung: Postfach 1 mit vollständigem Satz an Zugriffsberechtigungen für Postfach 2Mailbox delegation, where mailbox 1 has full access permissions to mailbox 2


SzenarioScenario „On Send“-Funktion Postfach 1Mailbox 1 on send feature „On Send“-Funktion Postfach 2Mailbox 2 on send feature Outlook im Web-SitzungOutlook on the web session ErgebnisResult Unterstützt?Supported?
1-1 AktiviertEnabled AktiviertEnabled Neue SitzungNew session Postfach 1 kann keine E-Mails über Postfach 2 senden.Mailbox 1 cannot send an email from mailbox 2. Zurzeit nicht unterstützt. Verwenden Sie Szenario 3 als Umgehungslösung.Not currently supported.As a workaround, use scenario 3.
2-2 DeaktiviertDisabled AktiviertEnabled Neue SitzungNew session Postfach 1 kann keine E-Mails über Postfach 2 senden.Mailbox 1 cannot send an email from mailbox 2. Zurzeit nicht unterstützt. Verwenden Sie Szenario 3 als Umgehungslösung.Not currently supported. As a workaround, use scenario 3.
3-3 AktiviertEnabled AktiviertEnabled Selbe SitzungSame session Zum Zeitpunkt des Sendens werden die Postfach 1 zugewiesenen „On Send“-Add-Ins ausgeführt.On send add-ins assigned to mailbox 1 run on send. UnterstütztSupported.
4-4 AktiviertEnabled DeaktiviertDisabled Neue SitzungNew session Es werden keine „On Send“-Add-Ins ausgeführt. E-Mails werden gesendet.No on send add-ins run; mail is sent. UnterstütztSupported.

Gruppe 1 = modernes Gruppenpostfach, Benutzerpostfach 1 = Mitglied von Gruppe 1Group 1 is a modern group mailbox and user mailbox 1 is a member of Group 1


SzenarioScenario „On Send“-Funktion Postfach 1Mailbox 1 on send feature „On Send“-Add-Ins aktiviert?On send add-ins enabled? Postfach 1-AktionMailbox 1 action ErgebnisResult Unterstützt?Supported?
1-1 AktiviertEnabled JaYes Postfach 1 verfasst eine neue Nachricht an Gruppe 1.Mailbox 1 composes new message to Group 1. „On Send“-Add-Ins werden zum Zeitpunkt des Sendens ausgeführt.On send add-ins run during send. JaYes
2-2 AktiviertEnabled JaYes Postfach 1 verfasst eine neue Nachricht an Gruppe 1 im Outlook im Web-Gruppenfenster von Gruppe 1.Mailbox 1 composes a new message to Group 1 within Group 1’s group window in Outlook on the web. Zum Zeitpunkt des Sendens werden keine „On Send“-Add-Ins ausgeführt.On send add-ins do not run during send. Zurzeit nicht unterstützt. Verwenden Sie Szenario 1 als Umgehungslösung.Not currently supported. As a workaround, use scenario 1.

Benutzerpostfach mit aktivierter „On Send“-Add-In-Funktion, installierten sowie aktivierten Add-Ins mit „On Send“-Unterstützung und aktiviertem OfflinemodusUser mailbox with on send add-in feature enabled, add-ins that support on send are installed and enabled and offline mode is enabled

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 die E-Mail wird nicht gesendet.The on send add-ins will run during send if the user is online. If the user is offline, the on send add-ins will not run during send and the email will not be sent.

CodebeispieleCode examples

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.The following code examples show you how to create a simple on send add-in. To download the code sample that these examples are based on, see Outlook-Add-in-On-Send.

Manifest, Versionsüberschreibung und EreignisManifest, version override, and event

Das Codebeispiel Outlook-Add-in-On-Send umfasst zwei Manifeste:The Outlook-Add-in-On-Send code sample includes two manifests:

  • Contoso Message Body Checker.xml – Demonstriert, wie Sie beim Senden den Text einer Nachricht auf verbotene Wörter oder vertrauliche Informationen überprüfen können.Contoso Message Body Checker.xml – Shows how to check the body of a message for restricted words or sensitive information on send.

  • Contoso Subject and CC Checker.xml – Demonstriert, wie Sie beim Senden der CC-Zeile einen Empfänger hinzufügen und überprüfen können, ob die Nachricht eine Betreffzeile hat.Contoso Subject and CC Checker.xml – Shows how to add a recipient to the CC line and verify that the message includes a subject line on send.

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.In the Contoso Message Body Checker.xml manifest file, you include the function file and function name that should be called on the ItemSend event. The operation runs synchronously.

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


Im Beispiel unten sehen Sie den Ausschnitt aus der Manifestdatei Contoso Subject and CC Checker.xml, in dem die Funktionsdatei und der Funktionsname angegeben sind, die bei Eintreten eines Ereignisses des Typs „Nachricht senden“ aufgerufen werden sollen:For the Contoso Subject and CC Checker.xml manifest file, the function file and function name to call on message send event is shown in the following example.

<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:The on send API requires VersionOverrides v1_1. The following shows you how to add the VersionOverrides node in your manifest.

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

Hinweis

Weitere Informationen erhalten Sie unter den folgenden Themen:For more information, see the following:

Methoden „Event“, „item“, „body getAsync“ und „setAsync“Event, item, body getAsync, and setAsync methods

Verwenden Sie den Namespace Office.context.mailbox.item, um auf die aktuell ausgewählte Nachricht zuzugreifen (in diesem Beispiel die neu verfasste Nachricht). Das Ereignis ItemSend wird von der „On Send“-Funktion automatisch an die im Manifest angegebene Funktion übergeben; —in diesem Beispiel ist das die Funktion validateBody.To access the currently selected message (in this example, the newly composed message), use the Office.context.mailbox.item namespace. The ItemSend event is automatically passed by the on send feature to the function specified in the manifest—in this example, the validateBodyfunction.

 var 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 Funktion validateBody ruft den aktuellen Text im angegebenen Format (HTML) ab und übergibt das Ereignisobjekt ItemSend, auf das der Code in der Rückrufmethode zugreifen will. 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.The validateBody function gets the current body in the specified format (HTML) and passes the ItemSend event object that the code wants to access in the callback method. In addition to the getAsync method, the Body object also provides a setAsync method that you can use to replace the body with the specified text.

Hinweis

Weitere Informationen finden Sie unter Event-Objekt und Body.getAsync.For more information, see Event Object and Body.getAsync.

Objekt „NotificationMessages“ und Methode „event.completed“NotificationMessages object and event.completed method

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 gibt sie über die Eigenschaft notificationMessages des Objekts Item ein NotificationMessages-Objekt zurück. Anschließend ruft sie wie im Beispiel unten dargestellt die Methode addAsync auf, um dem Element eine Benachrichtigung hinzuzufügen:The checkBodyOnlyOnSendCallBack function uses a regular expression to determine whether the message body contains blocked words. If it finds a match against an array of restricted words, it then blocks the email from being sent and notifies the sender via the information bar. To do this, it uses the notificationMessages property of the Item object to return a NotificationMessages object. It then adds a notification to the item by calling the addAsync method, as shown in the following example.

  // 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) {
        var listOfBlockedWords = new Array("blockedword", "blockedword1", "blockedword2");
        var 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.
        var regexCheck = new RegExp('\\b(' + wordExpression + ')\\b', 'i');
        var 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 });
    }

Für die Methode addAsync sind folgende Parameter verfügbar:The following are the parameters for the addAsync method:

  • NoSend – Eine Zeichenfolge, bei der es sich um einen entwicklerspezifischen Schlüssel zur Referenzierung einer Benachrichtigung handelt. Mit seiner Hilfe können Sie die Nachricht später ändern. Der Schlüssel darf höchstens 32 Zeichen haben.NoSend – A string that is a developer-specified key to reference a notification message. You can use it to modify this message later. The key can’t be longer than 32 characters.
  • 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 als Fehlermeldung festgelegt.type – One of the properties of the JSON object parameter. Represents the type of a message; the types correspond to the values of the Office.MailboxEnums.ItemNotificationMessageType enumeration. Possible values are progress indicator, information message, or error message. In this example, type is an error message.
  • message – Eine der Eigenschaften des JSON-Objektparameters. In diesem Beispiel ist message der Text der Benachrichtigung.message – One of the properties of the JSON object parameter. In this example, message is the text of the notification message.

Um zu signalisieren, dass das Add-In die Verarbeitung des durch den Sendevorgang ausgelösten ItemSend-Ereignisses abgeschlossen hat, rufen Sie die Methode event.completed({allowEvent:Boolean} auf. Die Eigenschaft allowEvent ist ein boolescher Wert. Ist er auf true gesetzt, darf gesendet werden. Ist er auf false gesetzt, wird das Senden der E-Mail-Nachricht blockiert.To signal that the add-in has finished processing the ItemSend event triggered by the send operation, call the event.completed({allowEvent:Boolean} method. The allowEvent property is a Boolean. If set to true, send is allowed. If set to false, the email message is blocked from sending.

Hinweis

Weitere Informationen finden Sie unter notificationMessages und completed.For more information, see notificationMessages and completed.

Methoden „replaceAsync“, „removeAsync“ und „getAllAsync“replaceAsync, removeAsync, and getAllAsync methods

Neben der Methode addAsync stellt das NotificationMessages-Objekt außerdem die Methoden „replaceAsync“, „removeAsync“ und „getAllAsync“ bereit. Diese Methoden werden in diesem Codebeispiel nicht verwendet. Weitere Informationen finden Sie unter NotificationMessages.In addition to the addAsync method, the NotificationMessages object also includes replaceAsync, removeAsync and getAllAsync methods. These methods are not used in this code sample. For more information, see NotificationMessages.

Betreff- und CC-ÜberprüfungSubject and CC checker

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.The following code example shows you how to add a recipient to the CC line and verify that the message includes a subject on send. This example uses the on send feature to allow or disallow an email from sending.

    // 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.
                var 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 dazu, wie Sie beim Senden der CC-Zeile einen Empfänger hinzufügen und überprüfen können, ob die E-Mail-Nachricht eine Betreffzeile enthält, finden Sie im Codebeispiel unter Outlook-Add-in-On-Send. Dort finden Sie außerdem einen Überblick über die APIs, die Sie verwenden können. Der Code ist ausführlich kommentiert.To learn more about how to add a recipient to the CC line and verify that the email message includes a subject line on send, and to see the APIs you can use, see the Outlook-Add-in-On-Send sample. The code is well commented.

Siehe auchSee also