Freigeben über

Verwenden von Fluid mit Teams

  • Artikel

Am Ende dieses Tutorials können Sie jede Fluid-basierte Anwendung in Teams integrieren und in Echtzeit mit anderen zusammenarbeiten.

In diesem Abschnitt lernen Sie die folgenden Konzepte kennen:

  1. Integrieren sie einen Fluid-Client in die Teams-Registerkartenanwendung.
  2. Führen Sie Ihre Teams-Anwendung aus, und verbinden Sie sie mit einem Fluid-Dienst (Azure Fluid Relay).
  3. Erstellen Und abrufen Sie Fluidcontainer, und übergeben Sie sie an eine React Komponente.

Weitere Informationen zum Erstellen komplexer Anwendungen finden Sie unter FluidExamples.

Voraussetzungen

Für dieses Tutorial müssen Sie mit den folgenden Konzepten und Ressourcen vertraut sein:

Erforderliche Komponenten installieren

Erstellen des Projekts

  1. Öffnen Sie eine Eingabeaufforderung, und navigieren Sie zu dem übergeordneten Ordner, in dem Sie das Projekt erstellen möchten, /My Microsoft Teams Projectsz. B. .

  2. Erstellen Sie eine Teams-Registerkartenanwendung, indem Sie den folgenden Befehl ausführen und eine Kanalregisterkarte erstellen:

    yo teams

  3. Navigieren Sie nach dem Erstellen mit dem folgenden Befehl cd <your project name>zum Projekt.

  4. Das Projekt verwendet die folgenden Bibliotheken:

    Bibliothek Beschreibung
    fluid-framework Enthält den IFluidContainer und andere verteilte Datenstrukturen , die Daten clientübergreifend synchronisieren.
    @fluidframework/azure-client Definiert das Startschema für den Fluid-Container.
    @fluidframework/test-client-utils Definiert den , der InsecureTokenProvider zum Erstellen der Verbindung mit einem Fluid-Dienst erforderlich ist.

    Führen Sie den folgenden Befehl aus, um die Bibliotheken zu installieren:

    npm install @fluidframework/azure-client fluid-framework @fluidframework/test-client-utils

Programmieren des Projekts

  1. Öffnen Sie die Datei /src/client/<your tab name> in Ihrem Code-Editor.

  2. Erstellen Sie als eine neue Datei, Util.ts und fügen Sie die folgenden Importanweisungen hinzu:

    //`Util.ts

import { IFluidContainer } from "fluid-framework";
import { AzureClient, AzureClientProps } from "@fluidframework/azure-client";
import { InsecureTokenProvider } from "@fluidframework/test-client-utils";

Definieren von Fluid-Funktionen und -Parametern

Diese App soll im Kontext von Microsoft Teams mit allen Fluid-bezogenen Importen, Initialisierungen und Funktionen verwendet werden. Dies bietet eine verbesserte Benutzererfahrung und erleichtert die Verwendung in Der Zukunft. Sie können den Importanweisungen den folgenden Code hinzufügen:

// TODO 1: Define the parameter key(s).
// TODO 2: Define container schema.
// TODO 3: Define connectionConfig (AzureClientProps).
// TODO 4: Create Azure client.
// TODO 5: Define create container function.
// TODO 6: Define get container function.

Hinweis

Die Kommentare definieren alle Funktionen und Konstanten, die für die Interaktion mit dem Fluid-Dienst und -Container erforderlich sind.

  1. Ersetzen Sie TODO 1: durch den folgenden Code:

    export const containerIdQueryParamKey = "containerId";

    Die Konstante wird exportiert, wenn sie in den contentUrl Microsoft Teams-Einstellungen an das angefügt wird, und später zum Analysieren der Container-ID auf der Inhaltsseite. Es ist ein gängiges Muster, wichtige Abfrageparameterschlüssel als Konstanten zu speichern, anstatt die unformatierte Zeichenfolge jedes Mal einzugeben.

    Bevor der Client Container erstellen kann, benötigt er eine containerSchema , die die freigegebenen Objekte definiert, die in dieser Anwendung verwendet werden. In diesem Beispiel wird eine SharedMap als initialObjectsverwendet, aber jedes freigegebene Objekt kann verwendet werden.

    Hinweis

    ist map die ID des SharedMap Objekts und muss innerhalb des Containers eindeutig sein wie alle anderen DDSes.

  2. Ersetzen Sie TODO: 2 durch den folgenden Code:

    const containerSchema = {
    initialObjects: { map: SharedMap }
};

  3. Ersetzen Sie TODO: 3 durch den folgenden Code:

    const connectionConfig : AzureClientProps =
{
    connection: {
        type: "local",
        tokenProvider: new InsecureTokenProvider("foobar", { id: "user" }),
        endpoint: "http://localhost:7070"
    }
};

    Bevor der Client verwendet werden kann, benötigt er eine AzureClientProps , die den Verbindungstyp definiert, den der Client verwendet. Die connectionConfig -Eigenschaft ist erforderlich, um eine Verbindung mit dem Dienst herzustellen. Der lokale Modus des Azure-Clients wird verwendet. Um die Zusammenarbeit über alle Clients hinweg zu ermöglichen, ersetzen Sie sie durch Fluid Relay Service-Anmeldeinformationen. Weitere Informationen finden Sie unter Einrichten des Azure Fluid Relay-Diensts.

  4. Ersetzen Sie TODO: 4 durch den folgenden Code:

    const client = new AzureClient(connectionConfig);

  5. Ersetzen Sie TODO: 5 durch den folgenden Code:

    export async function createContainer() : Promise<string> {
    const { container } = await client.createContainer(containerSchema);
    const containerId = await container.attach();
    return containerId;
};

    Wenn Sie den Container auf der Konfigurationsseite erstellen und an die contentUrl Einstellung in Teams anfügen, müssen Sie die Container-ID nach dem Anfügen des Containers zurückgeben.

  6. Ersetzen Sie TODO: 6 durch den folgenden Code:

    export async function getContainer(id : string) : Promise<IFluidContainer> {
    const { container } = await client.getContainer(id, containerSchema);
    return container;
};

    Wenn Sie den Fluid-Container abrufen, müssen Sie den Container zurückgeben, da Ihre Anwendung auf der Inhaltsseite mit dem Container und den darin enthaltenen DDS-Instanzen interagieren muss.

Erstellen eines Fluidcontainers auf der Konfigurationsseite

  1. Öffnen Sie die Datei src/client/<your tab name>/<your tab name>Config.tsx in Ihrem Code-Editor.

    Der Standardmäßige Teams-Registerkartenanwendungsflow wechselt von der Konfiguration zur Inhaltsseite. Um die Zusammenarbeit zu ermöglichen, ist die Beibehaltung des Containers beim Laden auf die Inhaltsseite von entscheidender Bedeutung. Die beste Lösung zum Beibehalten des Containers besteht darin, die Container-ID als Abfrageparameter an und contentUrlwebsiteUrlanzufügen, die URLs der Inhaltsseite. Die Schaltfläche "Speichern" auf der Teams-Konfigurationsseite ist das Gateway zwischen der Konfigurationsseite und der Inhaltsseite. Hier können Sie den Container erstellen und die Container-ID in den Einstellungen anfügen.

  2. Fügen Sie die folgende Importanweisung hinzu:

    import { createContainer, containerIdQueryParamKey } from "./Util";

  3. Ersetzen Sie die onSaveHandler-Methode durch den folgenden Code. Die einzigen hier hinzugefügten Zeilen sind das Aufrufen der zuvor in Utils.ts definierten Create-Containermethode und das anschließende Anfügen der zurückgegebenen Container-ID an und contentUrlwebsiteUrl als Abfrageparameter.

    const onSaveHandler = async (saveEvent: microsoftTeams.settings.SaveEvent) => {
    const host = "https://" + window.location.host;
    const containerId = await createContainer();
    microsoftTeams.settings.setSettings({
        contentUrl: host + "/<your tab name>/?" + containerIdQueryParamKey + "=" + containerId + "&name={loginHint}&tenant={tid}&group={groupId}&theme={theme}",
        websiteUrl: host + "/<your tab name>/?" + containerIdQueryParamKey + "=" + containerId + "&name={loginHint}&tenant={tid}&group={groupId}&theme={theme}",
        suggestedDisplayName: "<your tab name>",
        removeUrl: host + "/<your tab name>/remove.html?theme={theme}",
        entityId: entityId.current
    });
    saveEvent.notifySuccess();
};

    Stellen Sie sicher, dass Sie durch den Namen der Registerkarte aus Ihrem Projekt ersetzen <your tab name> .

    Warnung

    Da die Inhaltsseiten-URL zum Speichern der Container-ID verwendet wird, wird dieser Datensatz entfernt, wenn die Registerkarte Teams gelöscht wird. Darüber hinaus kann jede Inhaltsseite nur eine Container-ID unterstützen.

Inhaltsseite umgestalten, um die Fluid-Anwendung widerzuspiegeln

  1. Öffnen Sie die Datei src/client/<your tab name>/<your tab name>.tsx in Ihrem Code-Editor. Eine typische Fluid-basierte Anwendung besteht aus einer Ansicht und einer Fluid-Datenstruktur. Konzentrieren Sie sich auf das Abrufen/Laden des Fluid-Containers, und belassen Sie alle Fluid-bezogenen Interaktionen in einer React Komponente.

  2. Fügen Sie auf der Inhaltsseite die folgenden Importanweisungen hinzu:

    import { IFluidContainer } from "fluid-framework";
import { getContainer, containerIdQueryParamKey } from "./Util";

  3. Entfernen Sie den gesamten Code unterhalb der Importanweisungen auf der Inhaltsseite, und ersetzen Sie ihn durch Folgendes:

    export const <your tab name> = () => {
  // TODO 1: Initialize Microsoft Teams.
  // TODO 2: Initialize inTeams boolean.
  // TODO 3: Define container as a React state.
  // TODO 4: Define a method that gets the Fluid container
  // TODO 5: Get Fluid container on content page startup.
  // TODO 6: Pass the container to the React component as argument.
}

    Stellen Sie sicher, dass Sie durch den Namen der Registerkarte ersetzen <your tab name> , den Sie für Ihr Projekt definieren.

  4. Ersetzen Sie TODO 1 durch den folgenden Code:

    microsoftTeams.initialize();

    Um die Inhaltsseite in Teams anzuzeigen, müssen Sie die Microsoft Teams JavaScript-Clientbibliothek einschließen und einen Aufruf einschließen, um sie nach dem Laden der Seite zu initialisieren.

  5. Ersetzen Sie TODO 2 durch den folgenden Code:

    const [{ inTeams }] = useTeams();

    Da die Teams-Anwendung nur eine IFrame-Einschleusung einer Webseite ist, müssen Sie die inTeams boolesche Konstante initialisieren, um zu wissen, ob sich die Anwendung in Teams befindet oder nicht, und ob die Teams-Ressourcen, z contentUrl. B. , verfügbar sind.

  6. Ersetzen Sie TODO 3 durch den folgenden Code:

    const [fluidContainer, setFluidContainer] = useState<IFluidContainer | undefined>(undefined);

    Verwenden Sie einen React Zustand für den Container, da er die Möglichkeit bietet, den Container und die darin enthaltenen Datenobjekte dynamisch zu aktualisieren.

  7. Ersetzen Sie TODO 4 durch den folgenden Code:

    const getFluidContainer = async (url : URLSearchParams) => {
    const containerId = url.get(containerIdQueryParamKey);
    if (!containerId) {
        throw Error("containerId not found in the URL");
    }
    const container = await getContainer(containerId);
    setFluidContainer(container);
};

    Analysieren Sie die URL, um die durch containerIdQueryParamKeydefinierte Abfrageparameterzeichenfolge abzurufen, und rufen Sie die Container-ID ab. Mit der Container-ID können Sie den Container laden. Sobald Sie den Container haben, legen Sie den fluidContainer React Status fest. Weitere Informationen finden Sie im vorherigen Schritt.

  8. Ersetzen Sie TODO 5 durch den folgenden Code:

    useEffect(() => {
    if (inTeams === true) {
        microsoftTeams.settings.getSettings(async (instanceSettings) => {
            const url = new URL(instanceSettings.contentUrl);
            getFluidContainer(url.searchParams);
        });
        microsoftTeams.appInitialization.notifySuccess();
    }
}, [inTeams]);

    Nachdem Sie definiert haben, wie der Fluid-Container abgerufen werden soll, müssen Sie React anweisen, beim Laden aufzurufengetFluidContainer, und dann das Ergebnis im Zustand speichern, je nachdem, ob sich die Anwendung in Teams befindet. React useState-Hook stellt den erforderlichen Speicher bereit, und useEffect ermöglicht es Ihnen, beim Rendern aufzurufen getFluidContainer und den zurückgegebenen Wert an setFluidContainerzu übergeben.

    Durch Hinzufügen inTeams des Abhängigkeitsarrays am Ende von useEffectstellt die App sicher, dass diese Funktion nur beim Laden der Inhaltsseite aufgerufen wird.

  9. Ersetzen Sie TODO 6 durch den folgenden Code:

    if (inTeams === false) {
  return (
      <div>This application only works in the context of Microsoft Teams</div>
  );
}

if (fluidContainer !== undefined) {
  return (
      <FluidComponent fluidContainer={fluidContainer} />
  );
}

return (
  <div>Loading FluidComponent...</div>
);

    Hinweis

    Es ist wichtig, sicherzustellen, dass die Inhaltsseite in Teams geladen wird und dass der Fluid-Container definiert ist, bevor Sie ihn an die React-Komponente übergeben (definiert als FluidComponent, siehe unten).

Erstellen React Komponente für fluide Ansicht und Daten

Sie haben den grundlegenden Erstellungsflow von Teams und Fluid integriert. Sie können jetzt eine eigene React Komponente erstellen, die die Interaktionen zwischen der Anwendungsansicht und Fluid-Daten verarbeitet. Ab jetzt verhalten sich die Logik und der Fluss genau wie andere fluidbetriebene Anwendungen. Nachdem die grundlegende Struktur eingerichtet wurde, können Sie jedes der Fluid-Beispiele als Teams-Anwendung erstellen, indem Sie die ContainerSchema Interaktion der Anwendungsansicht und mit den DDS-Objekten/Datenobjekten auf der Inhaltsseite ändern.

Starten sie den Fluid-Server, und führen Sie die Anwendung aus.

Wenn Sie Ihre Teams-Anwendung lokal im lokalen Azure-Clientmodus ausführen, stellen Sie sicher, dass Sie den folgenden Befehl an der Eingabeaufforderung ausführen, um den Fluid-Dienst zu starten:

npx @fluidframework/azure-local-service@latest

Um die Teams-Anwendung auszuführen und zu starten, öffnen Sie ein weiteres Terminal, und befolgen Sie die Anweisungen zum Ausführen des Anwendungsservers.

Warnung

HostNames mit ngrokkostenlosen Tunneln von werden nicht beibehalten. Jede Ausführung generiert eine andere URL. Wenn ein neuer ngrok Tunnel erstellt wird, kann nicht mehr auf den älteren Container zugegriffen werden. Informationen zu Produktionsszenarien finden Sie unter Verwenden von AzureClient mit Azure Fluid Relay.

Hinweis

Installieren Sie eine zusätzliche Abhängigkeit, um diese Demo mit Webpack 5 kompatibel zu machen. Wenn sie einen Kompilierungsfehler im Zusammenhang mit einem Pufferpaket erhalten, führen Sie aus npm install -D buffer , und versuchen Sie es erneut. Dies wird in einer zukünftigen Version von Fluid Framework behoben.

Nächste Schritte

Verwenden von AzureClient mit Azure Fluid Relay

Da es sich um eine Teams-Registerkartenanwendung handelt, stehen Zusammenarbeit und Interaktion im Standard Fokus. Ersetzen Sie den zuvor bereitgestellten lokalen Modus AzureClientProps durch nicht lokale Anmeldeinformationen aus Ihrem Azure-Dienst instance, damit andere Benutzer in der Anwendung teilnehmen und mit Ihnen interagieren können. Erfahren Sie , wie Sie Ihren Azure Fluid Relay-Dienst bereitstellen.

Wichtig

Es ist wichtig, die Anmeldeinformationen, an die Sie übergeben AzureClientProps , vor einem versehentlichen Commit an die Quellcodeverwaltung auszublenden. Das Teams-Projekt enthält eine .env Datei, in der Sie Ihre Anmeldeinformationen als Umgebungsvariablen speichern können, und die Datei selbst ist bereits im .gitignoreenthalten. Informationen zur Verwendung der Umgebungsvariablen in Teams finden Sie unter Festlegen und Abrufen von Umgebungsvariablen.

Warnung

InsecureTokenProvider ist eine bequeme Möglichkeit, die Anwendung lokal zu testen. Es liegt in Ihrer Verantwortung, alle Benutzerauthentifizierungen zu verarbeiten und ein sicheres Token für jede Produktionsumgebung zu verwenden.

Festlegen und Abrufen der Umgebungsvariablen

Um eine Umgebungsvariable festzulegen und in Teams abzurufen, können Sie die integrierte .env Datei nutzen. Der folgende Code wird verwendet, um die Umgebungsvariable in .envfestzulegen:

# .env

TENANT_KEY=foobar

Um den Inhalt der .env Datei an unsere clientseitige App zu übergeben, müssen Sie sie webpack.config.js in so konfigurieren, dass webpack sie zur Laufzeit darauf zugreifen können. Verwenden Sie den folgenden Code, um die Umgebungsvariable aus .envhinzuzufügen:

// webpack,config.js

webpack.EnvironmentPlugin({
    PUBLIC_HOSTNAME: undefined,
    TAB_APP_ID: null,
    TAB_APP_URI: null,
    REACT_APP_TENANT_KEY: JSON.stringify(process.env.TENANT_KEY) // Add environment variable here
}),

Sie können in auf die Umgebungsvariable zugreifen. Util.ts

// Util.ts

tokenProvider: new InsecureTokenProvider(JSON.parse(process.env.REACT_APP_TENANT_KEY!), { id: "user" }),

Tipp

Wenn Sie Änderungen am Code vornehmen, wird das Projekt automatisch neu erstellt, und der Anwendungsserver wird neu geladen. Wenn Sie jedoch Änderungen am Containerschema vornehmen, werden diese nur wirksam, wenn Sie den Anwendungsserver schließen und neu starten. Wechseln Sie dazu zur Eingabeaufforderung, und drücken Sie zweimal STRG+C. Führen Sie dann oder gulp ngrok-serve erneut ausgulp serve.

Siehe auch