Een Fabric-app maken met de Rayfin CLI

In deze zelfstudie leert u hoe u de Rayfin CLI gebruikt om een project te maken, het lokaal uit te voeren en te implementeren in Fabric. U gebruikt dezelfde CLI-werkstroom voor nieuwe apps en voor latere updates van uw schema of front-end.

In deze handleiding leert u:

  • Een Fabric Apps-project maken op basis van een sjabloon.
  • Start de app lokaal op.
  • Meld u aan bij Fabric vanuit de CLI.
  • Implementeer de app in een Fabric werkruimte.
  • Controleer de implementatiestatus.

Prerequisites

  • Toegang tot Fabric.
  • Een Fabric werkruimte met inzender-, lid- of beheerdersmachtigingen.
  • De workload Fabric Apps ingeschakeld in uw tenant.
  • Node.js en npm geïnstalleerd.

Maak een app met een AI-prompt

Gebruik de volgende prompt met GitHub Copilot of een andere coding agent om een Fabric-app te maken, verkennen, draaien, aanpassen en uitrolen:

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

Het scaffold-commando levert de projectnaam en sjabloon voor niet-interactieve uitvoering. De agent kan vragen om eventuele resterende werkruimte- of deployment-instellingen. Bekijk gegenereerde bestanden en commando-uitvoer vóór de uitrol.

Maak een nieuwe app aan vanuit CLI

Als u een nieuwe app wilt maken op basis van een sjabloon, gebruikt u npm create:

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

De standaardtemplate blankapp resulteert in Universal App. Het maakt een nieuwe npm-werkruimte aan met backendconfiguratie onder rayfin/, frontendcode in packages/frontend/, runtime datadefinities in packages/data/, en gedeelde contracten in packages/shared/. Data is uitgeschakeld totdat je toestemming geeft.

Ga naar de projectmap:

cd my-app

Tip

Als u al een lege projectmap of bestaande broncode hebt, gebruikt npx rayfin init u in plaats van npm create.

npx rayfin init .

Bekijk het gegenereerde project

Na het genereren van de basisstructuur bevat het project de bestanden die je nodig hebt om te starten met ontwikkelen:

  • rayfin/rayfin.yml slaat app-services en implementatie-instellingen op.
  • rayfin/.env slaat omgevingswaarden op die worden gebruikt door de CLI.
  • packages/frontend/ bevat de UI en frontend build.
  • packages/data/ bevat runtime entity-klassen en schemaregistratie.
  • packages/shared/ bevat klantgerichte record- en schemacontracten.

Schakel gepersisteerde app-gegevens in wanneer nodig:

npm run pack:add -- data-modeling

Deze mogelijkheid schakelt Data in en voegt startgegevens en gedeelde definities toe. Controleer services.data.path en services.staticHosting.path in rayfin/rayfin.yml voordat je bestanden toevoegt. Andere sjablonen kunnen een flat root src/ en rayfin/data/ layout gebruiken; die layouts zijn alternatieven, niet de standaard Universal App-layout.

De CLI houdt actieve deploymentwaarden bij in rayfin/.env en registreert deployments in rayfin/.deployments.json. Publieke RAYFIN_PUBLIC_* waarden worden toegewezen aan de door frontend gegenereerde .env.local; gebruik npx rayfin env --framework vite om deze te regenereren zonder te deployen.

Zie De projectstructuur begrijpen voor een gedetailleerde uitsplitsing van bestanden per bestand.

De app lokaal uitvoeren

Start de lokale ontwikkelomgeving:

npx rayfin dev

Met deze opdracht start u de front-endontwikkelingsserver voor de scaffolded-app en implementeert u de back-end in Fabric. Als u wilt controleren of de app correct wordt gestart, opent u de lokale URL die wordt weergegeven in de terminal.

Implementeer de app in Fabric

Bouw meer functies in uw toepassing. Nadat u de wijzigingen hebt getest, implementeert u deze opnieuw in Fabric.

npx rayfin up

Als u een voorbeeld van de implementatie wilt bekijken zonder wijzigingen aan te brengen, voert u het volgende uit:

npx rayfin up --dry-run

De implementatie controleren

Controleer de huidige implementatiestatus:

npx rayfin up status

Gebruik JSON-uitvoer voor een machineleesbaar antwoord:

npx rayfin up status --json

Na een geslaagde implementatie drukt de CLI de gehoste app-URL en de Fabric portalkoppeling voor het geïmplementeerde item af.

Alleen database- of statische inhoud uitrollen

Als u alleen gegevensmodellen hebt gewijzigd, past u de databasewijzigingen toe zonder dat u de database volledig opnieuw hoeft te implementeren:

npx rayfin up db apply

Als u alleen front-endcode hebt gewijzigd, implementeert u de statische assets opnieuw:

npx rayfin up staticapp deploy

Functies toevoegen

Functies zijn TypeScript-functies die op de server binnen je Fabric-app draaien. Gebruik functies voor logica die niet in de browser mogen draaien, zoals werken met geheimen, toegang krijgen tot bevoorrechte gegevens en het aanroepen van externe diensten met de app-identiteit.

npx rayfin functions init

De initialisator gebruikt services.functions.path indien geconfigureerd, detecteert een werkruimtelocatie zoals packages/functions, of behoudt een bestaand flat rayfin/functions pakket. Gebruik --path <relative-path> om expliciet een locatie te kiezen.

Ingeschakelde functies vereisen services.functions.auth.type: application. Externe aanroepen via ctx.Tokens.* gebruiken de app-identiteit en de bijbehorende permissies, niet de externe resource-rechten van de gebruiker die aanroept. In huidige Fabric-apps is die identiteit de eigenaar van het app-item. Geef het toegang tot elke hulpbron. Daarentegen gebruikt ctx.getDataClient() het Rayfin-token van de aanroep en behoudt het het gegevensbeleid van de aanroeper.

GitHub Copilot kan de benodigde bestanden en componenten genereren en bijwerken. Je kunt de agent ook vragen de app te draaien, lokale functies te debuggen en de app te deployen. Je kunt bijvoorbeeld de volgende prompt gebruiken om een AI-pull request review assistant te bouwen met behulp van functies:

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().

Zie Use Functions en Connect Functions to external resources voor identiteit en implementatiedetails.

Veelvoorkomende problemen oplossen

Inloggen mislukt of uitrol resulteert in fout 401 of 403

Voer het opnieuw uit npx rayfin login en probeer npx rayfin uphet opnieuw.

U moet controleren wat de CLI gaat doen

Voordat u wijzigingen implementeert, voert u de opdracht uit npx rayfin up --dry-run.

De app wordt geïmplementeerd, maar u wijzigt alleen het schema

Als u schemawijzigingen onafhankelijk wilt pushen, gebruikt u npx rayfin up db apply. Als u destructieve wijzigingen uitvoert, zoals het wijzigen van het type kolom of het verwijderen van een kolom, mislukt deze opdracht. Als u uw wijzigingen wilt afdwingen, kunt u de --force vlag gebruiken. Deze actie kan een belangrijke wijziging zijn.

Volgende stappen 

  • Laatst bijgewerkt om