Vorgehensweise: Hinzufügen einer Dataverse-Aktion oder -Funktion zu Ihrer Code-App

In diesem Handbuch erfahren Sie, wie Sie Dataverse-Vorgänge (Aktionen und Funktionen) mithilfe der Befehle find-dataverse-api und add-dataverse-api CLI einer Power Apps Code-App ermitteln und hinzufügen.

Voraussetzungen

• Eine Power Apps-Code-App, die mit npx power-apps init initialisiert wurde
• @microsoft/power-apps Version 1.1.1 oder später in Ihrem package.json
• Authentifizierte CLI-Sitzung (npx power-apps Aufforderungen bei Bedarf)
• Zugriff auf die Dataverse-Umgebung mit dem Vorgang, den Sie verwenden möchten

Schritt 1: Ermitteln verfügbarer Vorgänge

Verwenden Sie find-dataverse-api, um nach Vorgängen in Ihrer Umgebung nach Namen zu suchen.

npx power-apps find-dataverse-api --search "WhoAmI"

In der Ausgabe werden übereinstimmende Vorgänge mit ihrer Art (Action oder Function), Parametern, Bindungsentität (falls vorhanden) und Rückgabetyp aufgelistet:

====================================================================================================
Dataverse Operations
====================================================================================================

  WhoAmI  (Function)
  Returns: mscrm.WhoAmIResponse

----------------------------------------------------------------------------------------------------
Total: 1 operation(s)
====================================================================================================

Sie können auch nach Aktionen suchen. Um beispielsweise die Aktion AddToQueue zu finden:

npx power-apps find-dataverse-api --search "AddToQueue"

====================================================================================================
Dataverse Operations
====================================================================================================

  AddToQueue  (Action)
  Bound to: mscrm.queue
  Parameters:
    - Target: mscrm.crmbaseentity
    - SourceQueue?: mscrm.queue
    - QueueItemProperties?: mscrm.queueitem
  Returns: mscrm.AddToQueueResponse

----------------------------------------------------------------------------------------------------
Total: 1 operation(s)
====================================================================================================

Um den rohen JSON-Code zu erhalten (nützlich für Scripting und für Coding-Agents), fügen Sie Folgendes hinzu --json:

npx power-apps find-dataverse-api --search "WhoAmI" --json

Bei der Suche handelt es sich um eine Teilzeichenfolge-Suche des Vorgangsnamen, unabhängig von Groß- und Kleinschreibung.

Schritt 2: Hinzufügen des Vorgangs zu Ihrer App

Nachdem Sie den Vorgangsnamen gefunden haben, führen Sie den folgenden Befehl aus:

npx power-apps add-dataverse-api --api-name WhoAmI
# or using the short alias:
npx power-apps add-dataverse-api -n WhoAmI

Der Befehl:

1. Ruft die Vorgangsdefinition aus dem Dataverse $metadataIhrer Umgebung ab.
2. Schreibt eine Schema-Datei bei <schemaPath>/dataverse/WhoAmI.Schema.json.
3. Speichert Schemadateien für alle Dataverse-Entitäten, auf die durch die Parameter des Vorgangs oder den Rückgabetyp verwiesen wird (überspringt, wenn sie bereits vorhanden sind).
4. Updates power.config.json:
   • Fügt hinzu databaseReferences["default.cds"] , falls noch nicht vorhanden.
   • Bei gebundenen Vorgängen wird die Bindungsentität zu dataSources hinzugefügt, wenn sie noch nicht vorhanden ist.
5. Regeneriert dataSourcesInfo.ts, um den neuen Vorgang einzuschließen.
6. Generiert ein TypeScript-Modell und eine Dienstklasse unter <codeGenPath>/generated/.

Bei Erfolg sehen Sie:

Dataverse API 'WhoAmI' added successfully.
Hint: Run 'npx power-apps run' to test locally, or 'npx power-apps push' to deploy.

Schritt 3: Verwenden des generierten Diensts im App-Code

Der Befehl generiert eine dedizierte <ApiName>Service Klasse für den Vorgang. Beispiel: Nach dem Hinzufügen WhoAmI, Importieren WhoAmIService aus dem generierten Dienstverzeichnis:

import { WhoAmIService } from './generated/services/WhoAmIService';

Der Dienst macht eine typierte statische Methode verfügbar, die nach dem Vorgang benannt ist. Beispiel:

const result = await WhoAmIService.WhoAmI();
// result.value contains: { BusinessUnitId: string, UserId: string, OrganizationId: string }

Bei einer gebundenen Aktion wie AddToQueue ist das erste Argument immer die GUID des Datensatzes, auf den operiert werden soll:

import { AddToQueueService } from './generated/services/AddToQueueService';

const result = await AddToQueueService.AddToQueue(
  queueId,    // string (GUID of the destination queue)
  target,     // Record<string, unknown> (the activity to add)
  sourceQueue,         // Record<string, unknown> | undefined
  queueItemProperties  // Record<string, unknown> | undefined
);
// result.value contains: { QueueItemId: string }

Parameter- und Rückgabetypen stammen aus dem Dataverse-Schema:

• GUID-Parameter werden als Typ string angegeben.
• Nachschlageparameter, die auf eine Dataverse-Entität verweisen, werden als Typ Record<string, unknown> eingegeben.
• Vorgänge ohne Rückgabewert erzeugen Promise<IOperationResult<void>>.
• Vorgänge, die einen Skalar zurückgeben (z. B. boolean, number), produzieren Promise<IOperationResult<T>> mit dem entsprechenden TypeScript-Typ.
• Vorgänge, die einen komplexen Typ oder eine Entität zurückgeben, erzeugen Promise<IOperationResult<Record<string, unknown>>>.

Erneutes Ausführen für denselben Vorgang

Das erneute Ausführen von add-dataverse-api mit demselben --api-name ist sicher und idempotent.

• Mit dem Befehl wird die Schemadatei mit der neuesten Definition von Dataverse überschrieben.
• Es regeneriert dataSourcesInfo.ts.
• Es entfernt doppelte Einträge in power.config.json - es werden keine Duplikate hinzugefügt.
• Entitätsschemadateien, die bereits vorhanden sind, werden nicht überschrieben.

Verwenden Sie diesen Befehl, um Änderungen an der Signatur eines Vorgangs nach einer Aktualisierung in der Umgebung zu übernehmen.

Erstellte oder geänderte Dateien

Der add-dataverse-api Befehl erstellt oder aktualisiert die folgenden Dateien in Ihrem Projekt:

Gebundene und ungebundene Vorgänge

Gebundene Vorgänge sind auf einen bestimmten Entitätsdatensatz begrenzt. Die generierte Methode verwendet immer einen id: string Parameter als erstes Argument, bei dem es sich um die GUID des Datensatzes handelt, der ausgeführt werden soll.

Ungebundene Vorgänge sind umgebungsweit und erfordern keine Datensatz-ID. Ihre Methoden verwenden nur die deklarierten Parameter.

Beide Arten werden mit demselben Befehl hinzugefügt. Die CLI erkennt den Vorgangstyp automatisch.

Problembehandlung

"Keine Vorgänge gefunden" – die Suche ist substringbasiert und unabhängig von der Groß-/Kleinschreibung, stimmt jedoch nur mit dem Vorgangsnamen überein. Probieren Sie einen kürzeren oder anderen Ausdruck aus. --json wird verwendet, um die unformatierte Antwort zu bestätigen.

Veraltete generierte Dateien – wenn Sie einen Vorgang umbenannt oder entfernt haben und die alten generierten Dateien verbleiben, löschen Sie sie manuell, und führen Sie den Vorgang add-dataverse-api erneut aus, um es erneut zu generieren.

pac code add-data-source überspringt die Aktion oder Funktion – die von add-dataverse-api generierten Schemadateien verwenden einen Microsoft.PowerApps/dataverseOperation-Typ, der von der PAC CLI nicht erkannt wird. Wenn Operationsschemadateien im Dataverse-Schemaordner vorhanden sind, pac code add-data-source überspringt sie mit:

Skipping unsupported Dataverse operation schema '...AddRecurrence.Schema.json':

Dieses Verhalten bedeutet, dass die PAC CLI den Schema-Typ Microsoft.PowerApps/dataverseOperation nicht unterstützt, sodass diese Dateien übersprungen werden, anstatt fehlzuschlagen. Die PAC CLI unterstützt weiterhin die anderen Schemadateien, die Dataverse-Entitätsdatenquellen oder Connectoren darstellen, und Sie können sie mit pac code add-data-source hinzufügen.

Verwandte Artikel

Web-API-Aktionen verwenden
Nutzen von Web-API-Funktionen