Übung – Erstellen benutzerdefinierter Aufgabenmodule in Microsoft Teams mit adaptiven Karten

Abgeschlossen 200 XP

In dieser Übung verwenden Sie adaptive Karten zum Implementieren benutzerdefinierter Aufgabenmodule in Microsoft Teams. Aufgabenmodule werden in Microsoft Teams als Dialogfelder zum Anzeigen oder Sammeln von Informationen von Benutzern verwendet.

Eines ist eine standardmäßige HTML-Seite, welche die ID eines Videos auf YouTube akzeptiert. Wenn das Aufgabenmodul aufgerufen wird, zeigt es das Video mithilfe des eingebetteten YouTube-Players in einer HTML-Seite an. Dieses Aufgabenmodul erhält die Video-ID aus der Abfragezeichenfolge, aber es müssen keine Informationen an die Registerkarte zurückgegeben werden.

Screenshot des Aufgabenmoduls „YouTube Player“.

Das andere Aufgabenmodul wird mit einer adaptiven Karte implementiert. Dieses Aufgabenmodul ermöglicht dem Benutzer, die ID des YouTube-Videos anzugeben, das angezeigt werden soll. Sobald der Benutzer seine Änderungen gespeichert hat, wird der Rückruf verwendet, um die neue ID zurück an die Registerkarte zu senden.

Screenshot der Adaptiven Karte, dargestellt in einem Aufgabenmodul.

Voraussetzungen

Die Entwicklung von Microsoft Teams-Apps setzt einen Office 365-Mandanten voraus, ein für die Entwicklung konfiguriertes Microsoft Teams voraus, sowie dass die notwendigen Tools auf Ihrer Arbeitsstation installiert sind.

Für den Office 365-Mandanten folgen Sie den Anweisungen zu Microsoft Teams: Bereiten Sie Ihren Office 365 Mandant darauf vor, einen Entwicklermandanten zu erhalten, wenn Sie derzeit kein Office 365-Konto haben. Stellen Sie sicher, dass Sie auch Microsoft Teams für Ihre Organisation aktiviert haben.

Microsoft Teams muss so konfiguriert sein, dass benutzerdefinierte Apps zugelassen sind und auf Ihren Mandanten hochgeladen werden können, um benutzerdefinierte Apps für Microsoft Teams zu erstellen. Befolgen Sie die Anweisungen auf der zuvor erwähnten Seite Vorbereiten Ihres Office 365-Mandanten .

In diesem Modul Node.js verwenden sie, um eine benutzerdefinierte Microsoft Teams-Registerkarten zu erstellen. Bei den Übungen in diesem Modul wird vorausgesetzt, dass die folgenden Tools auf Ihrer Entwicklerarbeitsstation installiert sind.

Wichtig

In den meisten Fällen ist die Installation der neuesten Versionen folgender Tools die beste Option. Die hier aufgeführten Versionen wurden verwendet, als dieses Modul veröffentlicht und zuletzt getestet wurde.

*Auf Ihrer Workstation müssen die Mindestversionen dieser Voraussetzungen installiert sein.

Erstellen der Microsoft Teams-App

Öffnen Sie die Eingabeaufforderung, navigieren Sie zu dem Verzeichnis, in dem Sie Ihre Arbeit speichern möchten, erstellen Sie einen neuen Ordner learn-msteams-taskmodules, und wechseln Sie dann in diesen Ordner.

Führen Sie den folgenden Befehl aus, um den Yeoman-Generator für Microsoft Teams auszuführen:

Konsole
yo teams

Yeoman wird gestartet und stellt Ihnen eine Reihe von Fragen. Beantworten Sie die Fragen mit den folgenden Werten:

  • Wie lautet der Name Ihrer Lösung?: YouTubePlayer
  • Wo möchten Sie die Dateien platzieren?: aktuellen Ordner verwenden
  • Titel Ihres Microsoft Teams App-Projektes?: Aufgabenmodule für adaptive Karten
  • Ihr (Firmen-)Name? (max. 32 Zeichen): Contoso
  • Welche Manifestversion möchten Sie verwenden?: v1.15 (mit Unterstützung für die Erweiterung von Teams-Apps auf andere Teile des Microsoft 365-Ökosystems)
  • Schnelle Gerüsterstellung: Ja
  • Welche Features möchten Sie Ihrem Projekt hinzufügen?: Eine Registerkarte
  • Die URL, in der Sie diese Lösung hosten möchten?: Übernehmen Sie die Standardoption.
  • Möchten Sie eine Leseanzeige anzeigen, wenn Ihre App/Tab geladen wird? Nein
  • Standardregisterkartenname? (max. 16 Zeichen): YouTube Player
  • Welche Art von Registerkarte möchten Sie erstellen?: Persönlich (für Teams, Outlook und Office)
  • Benötigen Sie Unterstützung für das einmalige Anmelden von Microsoft Entra für die Registerkarte? Nein

Hinweis

Die meisten Antworten auf diese Fragen können nach der Erstellung des Projekts geändert werden. So ist beispielsweise die URL, unter der das Projekt gehostet wird, zum Zeitpunkt der Erstellung oder des Tests des Projekts nicht wichtig.

Nach der Beantwortung der Fragen des Generators erstellt dieser das Gerüst für das Projekt und führt dann npm install aus, wodurch alle für das Projekt erforderlichen Abhängigkeiten heruntergeladen werden.

Testen der persönlichen Registerkarte

Bevor Sie die Registerkarte anpassen, testen Sie die Registerkarte, um die anfängliche Entwicklertestumgebung anzuzeigen.

Navigieren Sie über die Befehlszeile zum Stammordner des Projekts, und führen Sie den folgenden Befehl aus:

Konsole
gulp ngrok-serve --debug

Dieser gulp-Task führt viele andere Tasks aus, die alle in der Befehlszeilenkonsole angezeigt werden. Die Aufgabe ngrok-serve erstellt Ihr Projekt und startet einen lokalen Webserver (http://localhost:3007). Dann startet er ngrok mit einer zufälligen Unterdomäne, die eine sichere URL zu Ihrem lokalen Webserver erstellt.

Hinweis

Microsoft Teams setzt voraus, dass der gesamte auf einer Registerkarte angezeigte Inhalt aus einer HTTPS-Anforderung geladen wird. In der Entwicklung kann dies mit dem Tool ngrok erreicht werden, das eine sichere, rotierbare URL zu Ihrem lokalen HTTP-Webserver erstellt. Ngrok ist im Projekt als Abhängigkeit enthalten, sodass nichts eingerichtet oder konfiguriert werden muss.

Screenshot: „ngrok-serve“ von gulp.

Öffnen Sie einen Browser, und navigieren Sie zur in der Konsole angezeigten ngrok-URL.

Wichtig

Der erste Teil der in der Konsole angezeigten URL ändert sich jedes Mal, wenn Ngrok gestartet wird. Die in den vorhergehenden und nachfolgenden Screenshots angezeigten Adresse ist bei Ihrer Ausführung anders.

Screenshot der lokalen Web-App, die das Teams-Registerkartenprojekt hostet.

Aktualisieren Sie die URL im Browser so, dass die vom Gerüsterstellungsprozess erstellte Registerkarte geladen wird. Hier können Sie sehen, dass die Seite feststellen kann, dass sie nicht innerhalb des Microsoft Teams-Clients ausgeführt wird.

Screenshot der lokalen Web-App, die das Teams-Registerkartenprojekt hostet, er zeigt die Registerkarte an.

Nun wird die Registerkarte in Microsoft Teams geladen. Navigieren Sie im Browser zu https://teams.microsoft.com, und melden Sie sich mit den Anmeldeinformationen eines Geschäfts-, Schul- oder Unikontos an.

Hinweis

Microsoft Teams steht zur Verwendung als Webclient, als Desktopclient und als mobiler Client zur Verfügung. In diesem Modul verwenden wir den Webclient, aber es kann jeder der Clients verwendet werden.

Wählen Sie im Navigationsmenü der App-Leiste die Schaltfläche Weitere hinzugefügte Apps aus. Wählen Sie dann Weitere Einstellungen aus.

Screenshot des Dialogfelds „Weitere hinzugefügte Apps“ in Microsoft Teams.

Wählen Sie auf der Seite Apps unten in der Liste der App-Kategorien die Option Apps verwalten und dann App> hochladenBenutzerdefinierte App hochladen aus.

Wählen Sie im daraufhin angezeigten Dialogfeld das Microsoft Teams-Paket in Ihrem Projekt aus. Dieses App-Paket ist eine ZIP-Datei, die sich im Ordner ./package des Projekts befindet.

Hinweis

Wenn der Ordner „./package“ nicht vorhanden ist, bedeutet dies, dass Sie von einem Fehler im Yoteams-Bereitstellungspaket betroffen sind. So lösen Sie das Problem:

  • Beenden Sie den lokalen Webserver, indem Sie in der Konsole CTRL+C drücken.
  • Installieren der Vorschauversion des Yoteams-Bereitstellungspakets mithilfe des Befehls npm install yoteams-deploy@preview
  • Starten Sie den Serverprozess neu: gulp ngrok-serve --debug

Sobald das Paket hochgeladen wurde, zeigt Microsoft Teams eine Zusammenfassung der App an. Hier sehen Sie einige zu erledigende Aufgabenelemente („ToDos“). Keins dieser Aufgabenelemente ist für diese Übung wichtig, also lassen Sie sie unverändert.

Screenshot der Microsoft Teams-App.

Wählen Sie die Schaltfläche Hinzufügen aus, um die App zu installieren, wodurch Ihrem Dialogfeld Weitere hinzugefügte Apps eine neue persönliche Registerkarte hinzugefügt wird:

Screenshot der installierten Microsoft Teams-App im Dialogfeld „Weitere hinzugefügte Apps“.

Wählen Sie die App aus, um zur neuen Registerkarte zu navigieren:

Screenshot der persönlichen Registerkarte der installierten Microsoft Teams-App

Beachten Sie Folgendes: Wenn die Inhaltsseite auf einer Registerkarte im Microsoft Teams-Client geladen wird, wird der Wert der Eigenschaft entityId der Registerkarte und nicht die Meldung „Dies wird in Microsoft Teams nicht gehostet“ angezeigt, wie Sie beim Anzeigen der Inhaltsseite im Browser schon festgestellt haben. Die Registerkarte kann nicht erkennen, ob sie mithilfe des Microsoft Teams JavaScript SDK im Microsoft Teams-Client geladen wurde.

Der nächste Schritt besteht darin, einige Änderungen am Projekt vorzunehmen.

Stoppen Sie als Nächstes die Aktivität des lokalen Webservers, indem Sie in der Konsole STRG+C drücken, um den laufenden Prozess anzuhalten.

Implementieren der Benutzeroberfläche der persönlichen Registerkarte

Jetzt können Sie die Benutzeroberfläche für die Registerkarte implementieren. Die Registerkarte „Simple“ hat eine einfache Benutzeroberfläche.

Suchen Sie die Datei mit der im Projekt verwendeten React-Komponente, und öffnen Sie sie: ./src/app/scripts/youTubePlayerTab/YouTubePlayerTab.tsx.

Aktualisieren Sie die Import-Anweisungen in dieser Datei so, dass Komponenten aus der Fluent-UI-React-Bibliothek hinzugefügt werden. Suchen Sie die folgende Import-Anweisung ganz oben in der Datei, durch die Komponenten aus der Fluent-UI-React-Bibliothek importiert werden:

TypeScript
import { Provider, Flex, Text, Button, Header } from "@fluentui/react-northstar";

Ersetzen Sie die vorherige Anweisung durch die folgende Importanweisung:

TypeScript
import { Provider, Flex, Text, Button, Header, Input } from "@fluentui/react-northstar";

Aktualisieren Sie den Zustand der Komponente, sodass sie eine Video-ID enthält. Fügen Sie die folgende Anweisung nach den vorhandenen useState-Anweisungen in der YouTubePlayerTab-Funktion ein:

TypeScript
const [youTubeVideoId, setYouTubeVideoId] = useState<string | undefined>("jugBQqE_2sM");

Fügen Sie die folgenden Methoden zur Komponente YouTubePlayerTab hinzu. Mit diesen Methoden wird der Status aktualisiert, wenn bestimmte Ereignisse in dem Formular auftreten, die Sie der Komponente hinzufügen:

TypeScript
const onChangeVideo = (): void => {
};

const onShowVideo = ():  void => {
};

Suchen Sie die return-Anweisung, und aktualisieren Sie sie auf den folgenden Code. Die Komponente zeigt nun den Zustand mit einer kurzen Aussage zum Urheberrecht an:

tsx
return (
  <Provider theme={theme}>
    <Flex fill={true} column styles={{
      padding: ".8rem 0 .8rem .5rem"
    }}>
      <Flex.Item>
        <Header>Task Module Demo</Header>
      </Flex.Item>
      <Flex.Item>
        <div>
          <div>
            <Text>YouTube Video ID:</Text>
            <Input value={youTubeVideoId} disabled></Input>
          </div>
          <div>
            <Button content="Change Video ID" onClick={onChangeVideo}></Button>
            <Button content="Show Video" primary onClick={onShowVideo}></Button>
          </div>
        </div>
      </Flex.Item>
      <Flex.Item styles={{
        padding: ".8rem 0 .8rem .5rem"
      }}>
        <Text content="(C) Copyright Contoso" size="smaller"></Text>
      </Flex.Item>
    </Flex>
  </Provider>
);

Testen der persönlichen Registerkarte

Unsere Microsoft Teams-App ist jetzt als benutzerdefinierte persönliche Registerkarte eingerichtet und funktioniert. Überprüfen Sie dies, indem Sie ngrok erneut starten und die Microsoft Teams-Benutzeroberfläche aktualisieren.

Navigieren Sie über die Befehlszeile zum Stammordner des Projekts, und führen Sie den folgenden Befehl aus:

Konsole
gulp ngrok-serve --debug

Die ngrok-Subdomäne ändert sich, wenn der ngrok-Prozess neu gestartet wird. Wiederholen Sie den Vorgang zum Hinzufügen der App zu Teams, indem Sie die gleichen Schritte wie zuvor ausführen:

  • Wählen Sie im Navigationsmenü der App-Leiste die Schaltfläche Weitere hinzugefügte Apps aus. Wählen Sie dann Weitere Einstellungen aus.
  • Wählen Sie auf der Seite Apps die Option Apps verwalten> Eine App veröffentlichen> Eine benutzerdefinierte App hochladen. Wählen Sie im daraufhin angezeigten Dialogfeld das Microsoft Teams-Paket in Ihrem Projekt aus. (Dieses App-Paket ist eine ZIP-Datei, die sich im Ordner ./package des Projekts befindet.)
  • Sobald das Paket hochgeladen wurde, zeigt Microsoft Teams eine Zusammenfassung der App an. Wählen Sie die Schaltfläche Hinzufügen aus, um die App zu installieren, wodurch Ihrem Dialogfeld Weitere hinzugefügte Apps eine neue persönliche Registerkarte hinzugefügt wird.
  • Wählen Sie die App aus, um zur neuen Registerkarte zu navigieren.

Screenshot der aktualisierten Registerkarte „YouTube-Player“.

Jetzt können Sie das Projekt aktualisieren und Aufgabenmodule zur benutzerdefinierten Microsoft Teams-App hinzufügen.

Hinzufügen des Videoplayer-Aufgabenmoduls

Ein Aufgabenmodul kann eine Webseite sein, die mit HTML und JavaScript implementiert wurde. Erstellen Sie das Aufgabenmodul „Videoplayer“, indem Sie in Ihrem Projekt im Ordner ./src/app/web/youTubePlayerTab die neue Datei player.html erstellen.

Fügen Sie den folgenden HTML-Code zur player.html-Datei hinzu:

HTML
<!DOCTYPE html>
<html lang="en">

<head>
  <title>YouTube Player Task Module</title>
  <style>
    #embed-container iframe {
      position: absolute;
      top: 0;
      left: 0;
      width: 95%;
      height: 95%;
      padding-left: 20px;
      padding-right: 20px;
      padding-top: 10px;
      padding-bottom: 10px;
      border-style: none;
    }
  </style>
</head>

<body>
  <div id="embed-container"></div>
</body>

</html>

Im Aufgabenmodul „Videoplayer“ verwendet den eingebetteten YouTube-Player, um das angegebene Video anzuzeigen. Das Video wird in der Abfragezeichenfolge definiert, wenn die Datei player.html geladen wird.

Implementieren Sie den eingebetteten <iframe> Videoplayer, indem Sie das folgende JavaScript vor dem </body>-Endtag in der Datei player.html hinzufügen:

HTML
<script>
  function getUrlParameter(name) {
    name = name.replace(/[\[]/, '\\[').replace(/[\]]/, '\\]');
    var regex = new RegExp('[\\?&]' + name + '=([^&#]*)');
    var results = regex.exec(location.search);
    return results === null ? '' : decodeURIComponent(results[1].replace(/\+/g, ' '));
  };

  var element = document.createElement("iframe");
  element.src = "https://www.youtube.com/embed/" + getUrlParameter("vid");
  element.width = "1000";
  element.height = "700";
  element.frameborder = "0";
  element.allow = "autoplay; encrypted-media";
  element.allowfullscreen = "";

  document.getElementById("embed-container").appendChild(element);
</script>

Implementieren Sie nun das Aufgabenmodul auf der persönlichen Registerkarte.

Suchen und öffnen Sie die Datei ./src/app/scripts/YouTubePlayerTab/YouTubePlayerTab.tsx.

Aktualisieren Sie zunächst die Import-Anweisung in dieser Datei, um Namespaces aus dem Microsoft Teams SDK hinzuzufügen. Suchen Sie die folgende Import-Anweisung am Anfang der Datei:

TypeScript
import { app } from "@microsoft/teams-js";

Ersetzen Sie die vorherige Anweisung durch die folgende Importanweisung:

TypeScript
import { app, dialog, tasks } from "@microsoft/teams-js";

Fügen Sie als Nächstes der Komponente die YouTubePlayerTab folgende Hilfsmethode hinzu:

TypeScript
const appRoot = (): string => {
  if (typeof window === "undefined") {
    return "https://{{HOSTNAME}}";
  } else {
    return window.location.protocol + "//" + window.location.host;
  }
};

Fügen Sie den folgenden Code zur onShowVideo-Methode hinzu:

TypeScript
const onShowVideo = (): void => {
  const dialogInfo = {
    title: "YouTube Player",
    url: appRoot() + `/youTubePlayerTab/player.html?vid=${youTubeVideoId}`,
    size: {
      width: 1000,
      height: 700
    }
  };
  dialog.url.open(dialogInfo);
};

Mit diesem Code wird ein neues taskInfo-Objekt mit den Details des Aufgabenmoduls erstellt. Anschließend wird das Aufgabenmodul gestartet. Dieses Aufgabenmodul tut nichts anderes, als Informationen anzuzeigen. Deshalb müssen Sie den Rückruf nicht implementieren.

Testen des Videoplayer-Aufgabenmoduls

Navigieren Sie über die Befehlszeile zum Stammordner des Projekts, und führen Sie den folgenden Befehl aus:

Konsole
gulp ngrok-serve --debug

Wiederholen Sie den Vorgang des Hinzufügens der App zu Teams erneut. Wählen Sie die Schaltfläche Video anzeigen aus. Microsoft Teams lädt das Videoplayer-Aufgabenmodul mit dem angegebenen Video, das im eingebetteten Player geladen wird:

Screenshot des Aufgabenmoduls „YouTube Player“.

Stoppen Sie die Aktivität des lokalen Webservers, indem Sie in der Konsole STRG+C drücken, um den laufenden Prozess anzuhalten.

Hinzufügen eines auf einer adaptiven Karte gerenderten Aufgabenmoduls

Erstellen Sie eine neue JSON-Datei (YouTubeSelectorCard.json) im folgenden Ordner im vorhandenen Projekt ./src/app/scripts/youTubePlayerTab/. Fügen Sie den folgenden JSON-Code hinzu. Dieser JSON-Code definiert die adaptive Karte, die zur Erfassung der ID verwendet wird, die das YouTube-Video anzeigen soll:

JSON
{
  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "type": "AdaptiveCard",
  "version": "1.5",
  "body": [
    {
      "type": "Container",
      "items": [
        {
          "type": "TextBlock",
          "text": "YouTube Video Selector",
          "weight": "bolder",
          "size": "extraLarge"
        }
      ]
    },
    {
      "type": "Container",
      "items": [
        {
          "type": "TextBlock",
          "text": "Enter the ID of a YouTube video to show in the task module player.",
          "wrap": true
        },
        {
          "type": "Input.Text",
          "id": "youTubeVideoId",
          "value": ""
        }
      ]
    }
  ],
  "actions": [
    {
      "type": "Action.Submit",
      "title": "Update"
    }
  ]
}

Erstellen eines neuen Aufgabenmoduls, das die adaptive Karte verwendet

Nach der Erstellung der adaptiven Karte ist der nächste Schritt, ein Aufgabenmodul zu erstellen, mit dem sie angezeigt wird, und die Übermittlungsaktion zu verarbeiten.

Suchen Sie im vorhandenen Microsoft Teams-App-Projekt die Datei ./src/app/scripts/youTubePlayerTab/YouTubePlayerTab.tsx, die die benutzerdefinierte persönliche Registerkarte enthält.

Aktualisieren Sie anschließend den vorhandenen onChangeVideo-Handler in der YouTubePlayerTab-Klasse so, dass er den folgenden Code enthält:

TypeScript
const onChangeVideo = (): void => {
  const taskModuleInfo = {
    title: "YouTube Video Selector",
    width: 350,
    height: 250
  };

  const submitHandler = (err: string, result: any): void => {
  };

  tasks.startTask(taskModuleInfo, submitHandler);
};

Der erste Schritt besteht darin, die adaptive Karte zu laden und den Wert der Video-ID festzulegen, die beim Laden angezeigt wird. Fügen Sie den folgenden Code im oberen Bereich der onChangeVideo()-Methode hinzu:

TypeScript
// load adaptive card
const adaptiveCard: any = require("./YouTubeSelectorCard.json");
// update card with current video ID
adaptiveCard.body.forEach((container: any) => {
  if (container.type === "Container") {
    container.items.forEach((item: any) => {
      if (item.id && item.id === "youTubeVideoId") {
        item.value = youTubeVideoId;
      }
    });
  }
});

Implementieren Sie als Nächstes den Rückruf. Wenn die adaptive Karte die Übermittlungsaktion ausführt, sendet sie ein Objekt mit allen Eingabeobjekten als Eigenschaften zurück. Fügen Sie den folgenden Code zur vorhandenen submitHandler() in der onChangeVideo()-Funktion hinzu. Mit diesem Code wird der Status mit dem Wert der in der adaptiven Karte angegebenen Video-ID aktualisiert:

TypeScript
const submitHandler = (err: string, result: any): void => {
  if (err) {
    console.log(err);
  }
  setYouTubeVideoId(result.youTubeVideoId);
};

Fügen Sie dem taskModuleInfo-Objekt eine neue card-Eigenschaft hinzu, und legen Sie den Wert auf die adaptive Karte fest. Das resultierende taskModuleInfo sollte wie der folgende Code aussehen:

TypeScript
const taskModuleInfo = {
  title: "YouTube Video Selector",
  card: adaptiveCard,
  width: 350,
  height: 250
};

Testen des Aufgabenmoduls „Adaptive Karte“

Navigieren Sie über die Befehlszeile zum Stammordner des Projekts, und führen Sie den folgenden Befehl aus:

Konsole
gulp ngrok-serve --debug

Aktualisieren Sie die Benutzeroberfläche von Microsoft Teams, und wählen Sie die Schaltfläche Video-ID ändern aus. Microsoft Teams öffnet ein Aufgabenmodul mit der gerenderten adaptiven Karte:

Screenshot der Adaptiven Karte, dargestellt in einem Aufgabenmodul.

Ersetzen Sie die Video-ID im Eingabefeld, und wählen Sie Aktualisieren aus. Beachten Sie, dass die auf der Registerkarte angezeigte Video-ID mit diesem neuen Wert aktualisiert wurde.

Zusammenfassung

In dieser Übung haben Sie adaptive Karten zum Implementieren benutzerdefinierter Aufgabenmodule in Microsoft Teams verwendet.

Testen Sie Ihr Wissen

1.

Welche der folgenden Aussagen bezieht sich auf die Verwendung von adaptiven Karten in Microsoft Teams-Aufgabenmodulen?

2.

Wie erhält eine Registerkarte den/die Wert(e) aus der Submit-Aktion einer adaptiven Karte?


Nächste Lektion: Zusammenfassung

Vorherige Nächste