Fehlerbehebung für Fabric-Apps

Diagnostizieren Sie häufige Probleme, wenn Sie ein Fabric Apps-Projekt entwickeln oder bereitstellen. In diesem Artikel werden Probleme mit der Anmeldung, lokalen Diensten, Schemaänderungen, statischem Hosting und der CLI behandelt.

Bereitstellungsprobleme

Die Bereitstellung schlägt mit dem Fehler 401 oder 403 fehl

Symptom: Beim Ausführen wird npx rayfin up ein Authentifizierungsfehler zurückgegeben.

Ursache: Ihre Authentifizierungssitzung ist abgelaufen oder Sie sind nicht angemeldet.

Solution:

Erneutes Authentifizieren und Wiederholen der Bereitstellung:

npx rayfin login
npx rayfin up

Statisches Deployment überschreitet das Größenlimit.

Symptom: Die Bereitstellung statischer Inhalte schlägt mit einem Größengrenzwertfehler fehl.

Ursache: Das komprimierte Archiv überschreitet 100 MB.

Solution:

Reduzieren Sie die Größe der Build-Ausgabe um:

• Source-Maps aus Produktions-Builds ausschließen
• Optimieren oder Entfernen großer Bilder und Videos
• Verschieben von Binärdateien in den Speicher, anstatt sie zu bündeln
• Überprüfen, ob die Bundler-Konfiguration Entwicklungsartefakte ausschließt

Statische Bereitstellung hat keinen entfernten Endpunkt

Symptom: Beim Ausführen von npx rayfin up staticapp deploy wird gemeldet, dass kein Remote-Endpunkt konfiguriert ist.

Ursache: Eine reine statische Bereitstellung aktualisiert eine bestehende Bereitstellung. Die erste Remote-App kann nicht bereitgestellt werden.

Solution:

Führe einmal eine vollständige Bereitstellung aus:

npx rayfin up

Verwenden Sie nach Abschluss der Bereitstellung npx rayfin up staticapp deploy für nachfolgende ausschließlich statische Updates.

Authentifizierungsprobleme

Das Abrufen des Authentifizierungstokens schlägt fehl

Symptom:npx rayfin login oder ein anderer authentifizierter CLI-Befehl meldet Failed to acquire authentication token oder einen Fehler bei der Speicherung der Anmeldedaten.

Ursache: Die CLI ist nicht angemeldet oder die Umgebung bietet keine vom Betriebssystem gestützten Zugangsdatenspeicher.

Solution:

Melden Sie sich erneut an:

npx rayfin login

Für eine eingeschränkte lokale Entwicklungsumgebung ohne Zugangsdatenspeicher können Sie den Verschlüsselungs-Fallback aktivieren:

npx rayfin login --encryption-fallback-enabled

Sitzung nach der Anmeldung nicht beibehalten

Symptom: Benutzer werden unmittelbar nach der Authentifizierung abgemeldet.

Ursache: Der Client ist nicht mit der richtigen Basis-URL oder dem Veröffentlichungsschlüssel konfiguriert.

Solution:

Überprüfen Sie, ob die RayfinClient Konfiguration Ihrem Back-End entspricht:

const client = new RayfinClient({
  baseUrl: import.meta.env.VITE_RAYFIN_API_URL ?? 'http://localhost:5168',
  publishableKey: import.meta.env.VITE_RAYFIN_PUBLISHABLE_KEY,
});

Fabric SSO-Popup blockiert

Symptom: Browser blockiert das Fabric Portalfenster während der Anmeldung.

Ursache:ensureSignedInWithFabric() wurde nicht von einem Benutzergestenhandler aufgerufen.

Solution:

Aufrufen der Funktion aus einem synchronen Ereignishandler:

async function handleClick() {
  await ensureSignedInWithFabric(client.auth, options);
}

// Attach to button click
<button onClick={handleClick}>Sign in</button>

Zeitüberschreitung bei der Fabric-Authentifizierung

Symptom: Die Fabric-Authentifizierung schlägt nach fünf Minuten fehl.

Ursache: Das Fabric-Portal hat den Handoff-Code nicht zurückgegeben, bevor der Flow abgelaufen ist.

Solution:

Bestätigen Sie, dass das returnOrigin mit dem Ursprung Ihrer App übereinstimmt, schließen Sie das Popup und starten Sie den Anmeldeprozess erneut.

Fabric SSO meldet eine Ursprungs-Diskrepanz

Symptom: Die Fabric SSO-Übergabe lehnt die Antwort ab, weil ihr Ursprung nicht übereinstimmt.

Verursacht:returnOrigin, allowedRedirectUris, oder fabricPortalUrl passt nicht zur Umgebung, in der die App und das Fabric-Portal laufen.

Solution:

1. Setze returnOrigin auf den reinen Ursprung deiner App.
2. Bestätigen Sie, dass der Ursprung in services.auth.allowedRedirectUris angezeigt wird.
3. Verwenden Sie die URL des Fabric-Portals für die korrekte Produktions-, Vorschau- oder Entwicklungsumgebung.
4. Führen Sie npx rayfin up nach dem Ändern von rayfin.yml aus.

Weitere Informationen finden Sie unter Konfigurieren von Umleitungs-URIs für die Authentifizierung.

initEmbeddedAuth() gibt null zurück.

Symptom: Eingebettete Authentifizierung erzeugt keine Sitzung.

Ursache: Das SDK hat nicht erkannt, dass die App innerhalb von Fabric läuft.

Solution:

Fügen Sie ?fabricEmbedded=true in die App-URL ein oder legen Sie fabricEmbedded: true in FabricAuthOptions fest.

Die Fabric-Authentifizierung meldet eine Zustands-Fehlanpassung

Symptom: Das Anmelden schlägt fehl, weil der Antwortstatus nicht mit dem Anfragezustand übereinstimmt.

Ursache: Die Antwort gehört zu einem abgelaufenen Flow oder einem vorherigen Anmeldeversuch.

Solution:

Schließen Sie das Fabric-Popup und starten Sie den Anmeldeprozess neu. Verwenden Sie keine Callback-URLs oder Zustandswerte aus einem früheren Versuch.

Datenmodellprobleme

Die Daten-API liefert nach der Bereitstellung einen internen Serverfehler zurück

Symptom:npx rayfin up oder npx rayfin up db apply ist erfolgreich, aber die GraphQL- oder REST-Daten-API gibt einen internen Serverfehler zurück.

Ursache: Auf Microsoft SQL Server generiert ein @text() Feld ohne max eine SpalteNVARCHAR(MAX), die die GraphQL-Schemagenerierung verhindern kann.

Solution:

Fügen Sie jedem betroffenen Textfeld eine explizite maximale Länge hinzu:

@text({ max: 200 })
title!: string;

Dann überprüfen und wenden Sie die Schemaänderung an:

npx rayfin up db apply --force

Datendienst benötigt einen Dialekt

Symptom: Die Bereitstellung schlägt mit einer HTTP-400-Antwort fehl und meldet Dialect is required when Data module is enabled.

Ursache:services.data.enabled ist true, definiert rayfin.yml aber keinen Dialekt.

Solution:

Microsoft SQL Server konfigurieren:

services:
  data:
    enabled: true
    dialect: mssql

Die neue Entität ist nach der Bereitstellung nicht verfügbar

Symptom: Die Bereitstellung gelingt, aber Abfragen gegen eine neue oder veränderte Entität schlagen fehl oder verhalten sich, als ob die Entität nicht existiert.

Ursache: Das Datenbankschema könnte noch angewendet werden, oder das Frontend verwendet möglicherweise veraltete generierte Typen oder zwischengespeicherte Konfigurationen.

Solution:

1. Überprüfen Sie den Einsatz:

   npx rayfin up status
   

2. Warte, bis der Einsatz gesund ist.

3. Erneuere oder baue das Frontend neu auf.

4. Wenn die Entität weiterhin fehlschlägt, wenden Sie das Schema explizit an:

   npx rayfin up db apply
   

Für den vollständigen Arbeitsablauf siehe Schemaänderungen anwenden und überprüfen.

Beziehungen, die nicht in der API angezeigt werden

Symptom: Verwandte Entitätsfelder sind beim Abfragen nicht verfügbar.

Ursache: Der Navigationsdekoror fehlt, oder das Schema wurde nicht angewendet.

Solution:

1. Überprüfen Sie, ob die Beziehungsdekoratoren vorhanden sind:

   @one(() => Notebook) notebook?: Notebook;
   

2. Erneutes Anwenden des Schemas.

Autorisierungsrichtlinie funktioniert nicht

Symptom: Benutzer können auf Datensätze zugreifen, die sie nicht sehen sollten.

Ursache: Der Richtlinienausdruck ist falsch, oder die Anspruchsnamen stimmen nicht überein.

Solution:

1. Überprüfen Sie, ob die Richtlinie die richtigen Anspruchsnamen verwendet (sub, email, role):

   policy: (claims, item) => claims.sub.eq(item.user_id)
   

2. Protokollieren Sie die dekodierte JWT, um zu überprüfen, ob die Claim-Werte mit Ihrem Code übereinstimmen.

Veraltete API-Antworten

Symptom: Frontend gibt veraltete Daten-Shapes nach Schemaänderungen zurück.

Ursache: Die generierte Konfiguration wird zwischengespeichert.

Solution:

1. Stoppen Sie das Backend.

2. Löschen Sie das .temp/ Verzeichnis in rayfin/:

   rm -rf rayfin/.temp/
   

3. Starten Sie die Dienste neu und wenden Sie das Schema erneut an.

CLI-Probleme

Befehl nicht gefunden

Symptom: Wird ausgeführt npx rayfin , wird "Befehl nicht gefunden" zurückgegeben.

Ursache: Die CLI ist nicht installiert, oder npm befindet sich nicht in Ihrem PATH.

Solution:

1. Überprüfen Sie, Node.js und npm installiert sind:

   node --version
   npm --version
   

2. Installieren Sie Abhängigkeiten neu:

   npm install
   

CLI-Versionskonflikt

Symptom: CLI-Befehle schlagen nach dem Aktualisieren mit unerwarteten Fehlern fehl.

Ursache: Die zwischengespeicherte CLI-Version ist veraltet.

Solution:

Aktualisieren und erneutes Installieren:

npm update --save
npm install
npx rayfin --version

Globale und lokale Missübereinstimmung der CLI-Versionen

Symptom: CLI-Befehle schlagen bei unerwarteten Fehlern in Projekten fehl.

Ursache: Globale und lokale Installation der CLI-Versionen und stimmen nicht überein.

Lösung: Überprüfen der lokalen Version npm list @microsoft/rayfin-cli. Dies zeigt die Version im node_modules Ihres aktuellen Projekts an. Überprüfen Sie die globale Version npm list -g @microsoft/rayfin-cli. Dies zeigt die systemweit installierte Version an. Verwenden Sie npm uninstall -g das Rayfin CLI-Paket, um die globale Version zu entfernen und Ihre lokalen Versionen zu verwenden.

Probleme der Geheimnisverwaltung

Geheimer Befehl fordert nicht auf

Symptom:npx rayfin secret set <NAME> wird beendet, ohne zur Eingabe eines Werts aufzufordern.

Ursache: Standardeingabe ist kein interaktives Terminal, oder die CI Umgebungsvariable ist auf truegesetzt. Der Befehl verwendet eine maskierte interaktive Eingabeaufforderung.

Solution:

Nutzen Sie eine der folgenden unterstützten Alternativen für die Erstellung nicht-interaktiver Geheimnisse:

• Lege ein Secret fest, indem du seinen Wert per Pipe an den Befehl übergibst:

  Get-Content .\secret.txt | npx rayfin secret set <NAME> --stdin
  

• Setze mehrere Geheimnisse aus einer Umgebungsdatei:

  npx rayfin secret set --env-file .\secrets.env
  

Halte geheime Werte aus deinem Shell-Verlauf heraus und committe secret.txt oder .\secrets.env nicht in die Versionsverwaltung.

Geheimbefehl liefert „Zugriff verweigert“ zurück

Symptom:npx rayfin secret set oder npx rayfin secret list gibt einen Berechtigungsfehler zurück.

Ursache: Die App ist nicht bereitgestellt oder das angemeldete Konto hat keinen Zugriff auf den Ziel-Fabric-Arbeitsbereich.

Solution:

1. Führen Sie npx rayfin up aus, um die App bereitzustellen.
2. Starte npx rayfin login und wähle ein Konto mit Zugriff auf den Arbeitsbereich aus.
3. Versuchen Sie es erneut mit dem geheimen Befehl.

Weitere Informationen finden Sie unter Funktionsgeheimnisse verwalten.

Build- und Paketierungsprobleme

Buildbefehl schlägt fehl

Symptom: Fehler bei der statischen Hostingbereitstellung, da der Buildbefehl keine Ausgabe erzeugt hat.

Ursache: Buildfehler oder falsch konfigurierter Buildbefehl.

Solution:

1. Führen Sie den Buildbefehl manuell aus:

   npm run build
   

2. Beheben Sie alle gemeldeten Fehler.

3. Überprüfen Sie, ob der Ausgabeordner Dateien enthält.

Leerer statischer Ordner

Symptom: Die statische Bereitstellung schlägt mit dem Fehler "Leerer Ordner" fehl.

Ursache: Der konfigurierte folder Pfad ist falsch.

Solution:

Überprüfen Sie, ob der Pfad folder in rayfin.yml mit Ihrer Build-Ausgabe übereinstimmt:

services:
  staticHosting:
    folder: dist  # Verify this matches your build output
    buildCommand: npm run build

Datenbankprobleme

Anwenden des Datenbankschemas schlägt fehl

Symptom: Das Ausführen von npx rayfin up db apply oder npx rayfin up db apply --force schlägt fehl.

Ursache: Das Schema in der entfernten Datenbank und das im App-Code definierte Schema sind nicht synchron. Der App-Code ist die Wahrheitsquelle für eine Fabric-App.

Ändern Sie das entfernte Datenbankschema nicht über das Fabric-Portal, SQL Server Management Studio (SSMS), die SQL Server-Erweiterung für Visual Studio Code oder andere SQL-Tools. Die folgenden Änderungen an Spalten in einer Datenentität werden nicht unterstützt:

• Eine Kolumne umbenennen.
• Änderung des Datentyps einer Spalte.
• Eine Säule entfernen.

Das Hinzufügen einer Spalte wird unterstützt. Das Entfernen oder Ändern einer bestehenden Spalte kann die App und ihre Bereitstellung auf Fabric beeinträchtigen.

Solution:

1. Setze alle manuellen Änderungen am entfernten Datenbankschema so zurück, dass es mit dem Schema im App-Code übereinstimmt.

2. Wenn ein Codieragent eine nicht unterstützte Schemaänderung im App-Code vorgenommen hat, beauftragen Sie den Agenten, diese Änderung rückgängig zu machen.

3. Führe den Befehl schema apply erneut aus:

   npx rayfin up db apply
   

   Beim Umbenennen einer Spalte könnte --force die Schemaaktualisierung abschließen lassen:

   npx rayfin up db apply --force
   

   Vorsicht

   Die Verwendung --force kann zu einem dauerhaften Datenverlust führen. Überprüfen Sie die vorgeschlagenen Operationen und bestätigen Sie, dass Sie das Datenverlustrisiko akzeptieren, bevor Sie fortfahren.

Verbindung verweigert

Symptom: Datenvorgänge schlagen mit Verbindungsfehlern fehl.

Ursache: Der Datenbankcontainer läuft nicht, oder die Zustandsprüfungen sind fehlgeschlagen.

Solution:

1. Überprüfen von Containerprotokollen:

   docker compose logs -f
   

2. Starten Sie Dienste neu.

Datenverlust nach dem Neustart

Symptom: Daten verschwinden nach dem Beenden und Neustarten von Diensten.

Ursache: Volumes wurden mit --purge gelöscht.

Solution:

Verwenden Sie --down anstelle von --purge, um Daten zu erhalten.

Bekannte Einschränkungen

Aktuelle Einschränkungen und empfohlene Problemumgehungen finden Sie unter:

• count() ist im Fluent GraphQL-Client nicht verfügbar – verwenden Sie results.length.
• Viele-zu-viele-Beziehungen werden nicht unterstützt – verwenden Sie eine explizite Join-Entität.
• Sitzungsobjekte sind opak – prüfen Sie die Eigenschaften isAuthenticated oder user.
• Nachdem Sie die Authentifizierung in rayfin.yml aktiviert oder deaktiviert haben, starten Sie das Backend neu.

Hilfe erhalten

Falls das Problem weiterhin besteht:

1. Lesen Sie die Dokumentation Fabric Apps.
2. Überprüfen Sie das Repository GitHub auf bekannte Probleme.
3. Erstellen Sie einen Fehlerbericht mit detaillierten Protokollen und Reproduktionsschritten.

Verwandte Inhalte

• CLI-Referenz
• Schemaänderungen anwenden und überprüfen
• Konfigurieren Sie Authentifizierungs-Redirect-URIs.
• Verwalten Sie Funktionsgeheimnisse.
• In Fabric bereitstellen
• Authentifizierung konfigurieren