Erstellen einer Fabric-App mit der Rayfin CLI

In diesem Lernprogramm erfahren Sie, wie Sie mit der Rayfin CLI ein Projekt erstellen, lokal ausführen und in Fabric bereitstellen. Sie verwenden den gleichen CLI-Workflow für neue Apps und für spätere Aktualisierungen ihres Schemas oder Frontends.

In diesem Tutorial lernen Sie:

  • Erstellen Sie ein Fabric Apps-Projekt aus einer Vorlage.
  • Starten Sie die App lokal.
  • Melden Sie sich bei Fabric von der CLI an.
  • Stellen Sie die App in einem Fabric Arbeitsbereich bereit.
  • Überprüfen Sie den Bereitstellungsstatus.

Voraussetzungen

  • Zugriff auf Fabric.
  • Ein Fabric Arbeitsbereich, in dem Sie über Berechtigungen "Mitwirkender", "Mitglied" oder "Administrator" verfügen.
  • Die in Ihrem Mandanten aktivierte Fabric-App-Workload.
  • Node.js und npm installiert.

Erstellen Sie eine App mit einem KI-Prompt

Verwenden Sie die folgende Eingabeaufforderung mit GitHub Copilot oder einem anderen Coding-Agenten, um eine Fabric-App zu erstellen, zu erkunden, auszuführen, anzupassen und bereitzustellen:

Set up a new Fabric App project called "rayfin-app-ws".

1. Run: npx -y @microsoft/create-rayfin@latest --project-name rayfin-app-ws --template blankapp
2. Open the scaffolded project directory.
3. Explore the project structure and understand the Rayfin app framework.
4. Run: npm run dev
5. Make changes to the app based on my instructions.
6. When ready, deploy with: npx rayfin up

Der Scaffold-Befehl liefert den Projektnamen und die Vorlage für nicht-interaktive Ausführung. Der Agent kann nach einem verbleibenden Arbeitsbereich oder Bereitstellungseinstellungen fragen. Überprüfen Sie generierte Dateien und Befehlsausgaben vor der Bereitstellung.

Erstellen Sie eine neue App über CLI

Um ein Gerüst für eine neue App aus einer Vorlage zu erstellen, verwenden Sie Folgendes npm create:

npm create @microsoft/rayfin@latest -- my-app --workspace <workspacename>

Die Standardvorlage blankapp ergibt Universal App. Es erstellt einen neuen npm-Arbeitsbereich mit Backend-Konfiguration unter rayfin/, Frontendcode in packages/frontend/, Laufzeitdatendefinitionen in packages/data/, und geteilten Verträgen in packages/shared/. Daten sind deaktiviert, bis du zustimmst.

Wechseln Sie zum Projektverzeichnis:

cd my-app

Tipp

Wenn Sie bereits über einen leeren Projektordner oder vorhandenen Quellcode verfügen, verwenden Sie npx rayfin init anstelle von npm create.

npx rayfin init .

Überprüfen Sie das generierte Projekt

Nach dem Erstellen des Gerüsts enthält das Projekt die Dateien, die Sie zum Entwickeln benötigen:

  • rayfin/rayfin.yml speichert App-Dienste und Bereitstellungseinstellungen.
  • rayfin/.env speichert Umgebungswerte, die von der CLI verwendet werden.
  • packages/frontend/ enthält die Benutzeroberfläche und den Frontend-Build.
  • packages/data/ enthält Laufzeit-Entitätsklassen und Schema-Registrierung.
  • packages/shared/ enthält clientseitige Datensatz- und Schema-Schnittstellenverträge.

Aktivieren Sie gespeicherte App-Daten bei Bedarf:

npm run pack:add -- data-modeling

Diese Funktion aktiviert Data und fügt Starterdaten sowie gemeinsame Definitionen hinzu. Überprüfen Sie services.data.path und checken Sie services.staticHosting.path in rayfin/rayfin.yml ein, bevor Sie Dateien hinzufügen. Andere Vorlagen können ein flaches Root-Layout mit src/ und rayfin/data/ verwenden; diese Layouts sind Alternativen, nicht das Standard-Universal-App-Layout.

Die CLI speichert aktive Deployment-Werte in rayfin/.env und zeichnet Deployments in rayfin/.deployments.json auf. Öffentliche RAYFIN_PUBLIC_* Werte werden in das vom Frontend generierte .env.local abgebildet; npx rayfin env --framework vite verwenden Sie, um es ohne Deployment neu zu generieren.

Eine detaillierte Datei-nach-Datei-Aufschlüsselung finden Sie unter "Grundlegendes zur Projektstruktur".

Lokales Ausführen der App

Starten Sie die lokale Entwicklungsumgebung:

npx rayfin dev

Dieser Befehl startet den Frontend-Entwicklungsserver für die Gerüst-App und stellt das Back-End für Fabric bereit. Um zu bestätigen, dass die App ordnungsgemäß gestartet wird, öffnen Sie die lokale URL, die im Terminal angezeigt wird.

Deploye die App auf Fabric

Erstellen Sie weitere Features in Ihrer Anwendung. Nachdem Sie die Änderungen getestet haben, stellen Sie sie erneut in Fabric bereit.

npx rayfin up

Um eine Vorschau der Bereitstellung anzuzeigen, ohne Änderungen vorzunehmen, führen Sie Folgendes aus:

npx rayfin up --dry-run

Überprüfen Sie die Bereitstellung

Überprüfen Sie den aktuellen Bereitstellungsstatus:

npx rayfin up status

Verwenden Sie für eine maschinenlesbare Antwort DIE JSON-Ausgabe:

npx rayfin up status --json

Nach einer erfolgreichen Bereitstellung druckt die CLI die url der gehosteten App und den Fabric Portallink für das bereitgestellte Element.

Nur Datenbank- oder statische Inhalte bereitstellen

Wenn Sie nur Datenmodelle geändert haben, wenden Sie die Datenbankänderungen ohne vollständige erneute Bereitstellung an:

npx rayfin up db apply

Wenn Sie nur den Frontend-Code geändert haben, stellen Sie die statischen Ressourcen erneut bereit:

npx rayfin up staticapp deploy

Funktionen hinzufügen

Funktionen sind TypeScript-Funktionen, die auf dem Server innerhalb Ihrer Fabric-App laufen. Verwenden Sie Funktionen für Logik, die im Browser nicht ausgeführt werden dürfen, wie das Arbeiten mit Secrets, den Zugriff auf privilegierte Daten und das Aufrufen externer Dienste mit der App-Identität.

npx rayfin functions init

Der Initialisierer verwendet services.functions.path, wenn er konfiguriert ist, erkennt einen Arbeitsbereich wie packages/functions oder behält ein vorhandenes flaches rayfin/functions-Paket bei. Verwenden Sie --path <relative-path>, um einen Ort explizit auszuwählen.

Für aktivierte Funktionen ist services.functions.auth.type: application erforderlich. Externe Aufrufe über ctx.Tokens.* verwenden die App-Identität und deren Berechtigungen, nicht die externen Ressourcenberechtigungen des aufrufenden Benutzers. In aktuellen Fabric-Apps ist diese Identität der Besitzer des App-Elements. Gewähre ihm Zugang zu jeder Ressource. Im Gegensatz dazu verwendet ctx.getDataClient() das Rayfin-Token des Aufrufs und behält die Datenrichtlinien des Aufrufers bei.

GitHub Copilot kann die erforderlichen Dateien und Komponenten generieren und aktualisieren. Du kannst den Agenten auch bitten, die App auszuführen, die Funktionen lokal zu debuggen und die App zu deployen. Zum Beispiel können Sie die folgende Eingabeaufforderung verwenden, um mithilfe von Funktionen einen KI-Pull-Request-Review-Assistenten zu erstellen:

Build an app that lets me view all pull requests for the repository
<repoURL>, chat with my Azure AI Foundry agent <agentName> to review
pull requests, and post review comments. Use Functions with application
authentication to connect to Azure AI Foundry and Azure DevOps. Grant the
app identity the required resource permissions, and preserve the caller's
Rayfin data policies when using ctx.getDataClient().

Siehe Funktionen verwenden und Funktionen mit externen Ressourcen verbinden für Identitäts- und Bereitstellungsdetails.

Häufige Probleme beheben

Die Anmeldung schlägt fehl, oder die Bereitstellung gibt 401 oder 403 zurück.

Führen Sie npx rayfin login den Vorgang erneut aus, und versuchen Sie es npx rayfin updann erneut.

Sie müssen prüfen, was die CLI tun wird

Führen Sie npx rayfin up --dry-run vor der Bereitstellung von Änderungen aus.

Die App wird bereitgestellt, aber Sie ändern nur das Schema

Verwenden Sie npx rayfin up db apply, um Schemaänderungen unabhängig zu übernehmen. Wenn Sie destruktive Änderungen wie das Ändern des Typs einer Spalte oder das Entfernen einer Spalte ausführen, schlägt dieser Befehl fehl. Um Ihre Änderungen zu erzwingen, können Sie die --force Kennzeichnung verwenden. Diese Aktion kann eine bahnbrechende Änderung sein.

Nächste Schritte

  • Zuletzt aktualisiert um