Een Microsoft Fabric App bouwen en deployen met Rayfin

Fabric Apps zijn geen Power BI organizational apps. Het zijn code-first webapplicaties die binnen Fabric draaien, met Fabric authentication, een managed backend, een SQL database en optionele static hosting.

De tool in deze walkthrough is Rayfin. De flow is gevalideerd in een Fabric trial-workspace met de naam blog_fabric_app. Fabric Apps zijn preview technology, dus controleer de actuele CLI en het gegenereerde project voordat je dit in production gebruikt.

Het resultaat

React + Vite frontend
        |
        v
Rayfin CLI
        |
        +--> Fabric App item
        +--> Fabric SQL database
        +--> Fabric authentication
        +--> protected static website

Vereisten

Je hebt nodig:

1. Node.js en npm.
2. Een Fabric-workspace op actieve capacity.
3. Contributor-, Member- of Admin-toegang tot die workspace.
4. Fabric Apps (preview) ingeschakeld voor de tenant.

Een administrator kan de workload inschakelen via OneLake catalog > Govern > Configurations > Workloads.

Maak of selecteer:

blog_fabric_app

1. Scaffold het project

npm create @microsoft/rayfin@latest -- fabric-orders-app --workspace blog_fabric_app
cd fabric-orders-app

Voor een bestaande applicatie:

npx rayfin init .

Het gegenereerde project bevat:

rayfin/rayfin.yml   # services and deployment settings
rayfin/data/        # TypeScript data models
src/                # frontend source
package.json        # scripts and Rayfin package versions

2. Controleer de serviceconfiguratie

Een minimale rayfin/rayfin.yml is:

id: fabricordersapp
name: FabricOrdersApp
version: 1.0.0
services:
  auth:
    enabled: true
    fabric:
      enabled: true
    allowedRedirectUris:
      - http://localhost:5173
  data:
    enabled: true
    dialect: mssql
  staticHosting:
    enabled: true
    folder: dist
    buildCommand: npm run build:fabric
    indexDocument: index.html

Deployed apps ondersteunen door Fabric bemiddelde Microsoft Entra SSO. Gebruik lokale email/password authentication niet als identity design voor production. Dat is voor lokale development.

3. Draai en bouw lokaal

npx rayfin dev

Draai vóór deployment de eigen controles van het project:

npm run build
npm test

Als het template geen tests heeft, is de build nog steeds een bruikbare minimale gate. Tijdens de validatierun compileerde het React/Vite-project succesvol naar dist.

4. Bekijk de deployment vooraf

npx rayfin login
npx rayfin login status
npx rayfin up --workspace blog_fabric_app --dry-run --verbose

De dry run moet workspace resolution, het maken of bijwerken van de Fabric App, runtime settings, het databasemodel en de upload van static content tonen.

5. Deploy en verifieer

npx rayfin up --workspace blog_fabric_app
npx rayfin up status
npx rayfin up status --json

Een geslaagde deployment meldt de Fabric-workspace en het item, de onderliggende SQL database, de Fabric portal URL en de hosted app URL. De gevalideerde app gaf een beveiligde *.webapp.fabricapps.net-URL terug. Anonieme toegang toonde Sign in to continue, het verwachte resultaat voor protected hosting.

De packageversieval

De eerste live deployment maakte de Fabric App, maar mislukte bij static hosting:

Static hosting requires Rayfin CLI version 1.35.0-alpha.1413 or later.

Alleen de CLI bijwerken was niet genoeg. Rayfin-packages worden als compatibele set uitgebracht en een gemengde installatie werd bij de volgende poging geweigerd. Werk de CLI en runtime-packages samen bij:

npm install --save-dev @microsoft/rayfin-cli@latest
npm install \
  @microsoft/rayfin-auth-provider-fabric@latest \
  @microsoft/rayfin-client@latest \
  @microsoft/rayfin-core@latest \
  @microsoft/rayfin-data@latest

Na een nieuwe build deployde npx rayfin up --workspace blog_fabric_app de frontend, authentication service en SQL database.

Houd alle @microsoft/rayfin-*-packages gelijk. Dat is een beperking uit de previewfase die je beter controleert voordat je de applicatie zelf debugt.

Kleinere updatecommando’s

# Apply data-model changes only
npx rayfin up db apply

# Rebuild and deploy static frontend content only
npx rayfin up staticapp deploy

# Initialize server-side TypeScript functions
npx rayfin functions init

Rayfin blokkeert potentieel destructieve databasewijzigingen standaard. Gebruik npx rayfin up db apply --force alleen nadat je het voorgestelde dataverlies hebt beoordeeld.

Wat rayfin up echt deployt

Het commando:

1. maakt of hergebruikt een Fabric App item;
2. synchroniseert runtime- en authentication settings;
3. past het Rayfin data-model schema toe;
4. bouwt en verpakt de static frontend;
5. uploadt de applicatie; en
6. legt deploymentmetadata vast voor latere updates.

Dat is nuttig omdat app, identity, backend en datamodel één deploymentpad delen. Het betekent ook dat een groene frontendbuild niet hetzelfde is als een volledige deployment.

Voordat je de app deelt

• Houd secrets uit frontendcode en Git.
• Schakel Fabric authentication in rayfin.yml in.
• Draai eerst een dry run.
• Beoordeel dependency- en npm audit-output.
• Test met een gebruiker die alleen de bedoelde Fabric-permissions heeft.
• Houd het gecomprimeerde static archive onder de gedocumenteerde limiet van 100 MB.
• Versioneer het project in Git.

Bronnen

• Een Fabric app maken met de Rayfin CLI
• Een Fabric app deployen naar Fabric
• Rayfin CLI-reference

Rayfin maakt de cyclus scaffold-build-dry-run-deploy concreet, maar Fabric Apps zijn nog steeds preview technology. Houd het project klein, lijn packageversies uit en verifieer de beveiligde deployment in plaats van te stoppen zodra het item in de workspace staat.