Creare un'app Fabric con l'interfaccia della riga di comando di Rayfin

Questa esercitazione illustra come usare l'interfaccia della riga di comando di Rayfin per creare un progetto, eseguirlo in locale e distribuirlo in Fabric. Si usa lo stesso flusso di lavoro dell'interfaccia della riga di comando per le nuove app e per gli aggiornamenti successivi dello schema o del front-end.

In questa esercitazione, imparerai a:

  • Crea un progetto di app di Fabric da un modello.
  • Avviare l'app in locale.
  • Accedi a Fabric dalla CLI.
  • Distribuire l'app in un'area di lavoro Fabric.
  • Verificare lo stato della distribuzione.

Prerequisiti

  • Accesso a Fabric.
  • Area di lavoro Fabric in cui si dispone delle autorizzazioni Collaboratore, Membro o Amministratore.
  • Node.js e npm sono installati.

Crea un'app con un prompt AI

Usa il seguente prompt con GitHub Copilot o un altro agente di programmazione per creare, esplorare, eseguire, personalizzare e distribuire un'app Fabric:

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

Il comando scaffold fornisce il nome del progetto e il modello per l'esecuzione non interattiva. L'agente può chiedere eventuali impostazioni di spazio di lavoro o deployment rimanenti. Controlla i file generati e l'output dei comandi prima della distribuzione.

Crea una nuova app da CLI

Per eseguire lo scaffolding di una nuova app da un modello, usare npm create:

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

Il template predefinito blankapp si risolve in Universal App. Crea un nuovo workspace npm con configurazione backend sotto rayfin/, codice frontend in packages/frontend/, definizioni dati runtime in packages/data/, e contratti condivisi in packages/shared/. I dati sono disabilitati finché non acconsenti.

Vai alla directory del progetto:

cd my-app

Suggerimento

Se hai già una cartella di progetto vuota o un codice sorgente esistente, usa npx rayfin init anziché npm create.

npx rayfin init .

Rivedi il progetto generato

Dopo la creazione della struttura iniziale del progetto, il progetto include i file necessari per iniziare lo sviluppo:

  • rayfin/rayfin.yml Memorizza i servizi dell'app e le impostazioni di distribuzione.
  • rayfin/.env memorizza i valori dell'ambiente utilizzati dalla CLI.
  • packages/frontend/ contiene la build UI e frontend.
  • packages/data/ Contiene classi di entità in runtime e registrazione dello schema.
  • packages/shared/ contiene contratti di record e schema lato client.

Abilita i dati dell'app persistenti quando necessario:

npm run pack:add -- data-modeling

Questa funzionalità abilita Data e aggiunge dati iniziali e definizioni condivise. Controlla services.data.path e services.staticHosting.path in rayfin/rayfin.yml prima di aggiungere file. Altri template possono usare un layout con radice piatta src/ e rayfin/data/; questi layout sono alternative, non il layout predefinito dell'app universale.

La CLI mantiene i valori di deployment attivi in rayfin/.env e registra i deployment in rayfin/.deployments.json. I valori pubblici RAYFIN_PUBLIC_* sono mappati nel frontend generato .env.local; usa npx rayfin env --framework vite per rigenerarlo senza distribuirlo.

Per una suddivisione dettagliata dei file per file, vedere Informazioni sulla struttura del progetto.

Eseguire l'applicazione localmente

Avviare l'ambiente di sviluppo locale:

npx rayfin dev

Questo comando avvia il server di sviluppo front-end per l'app con scaffolding e distribuisce il back-end in Fabric. Per confermare che l'app viene avviata correttamente, aprire l'URL locale visualizzato nel terminale.

Distribuisci l'app su Fabric

Creare altre funzionalità nell'applicazione. Dopo aver testato le modifiche, eseguire di nuovo la distribuzione in Fabric.

npx rayfin up

Per visualizzare in anteprima la distribuzione senza apportare modifiche, eseguire:

npx rayfin up --dry-run

Verificare la distribuzione

Controllare lo stato di distribuzione corrente:

npx rayfin up status

Per una risposta leggibile dal computer, usare l'output JSON:

npx rayfin up status --json

Dopo aver completato la distribuzione, l'interfaccia della riga di comando stampa l'URL dell'app ospitata e il collegamento Fabric portale per l'elemento distribuito.

Distribuire solo contenuti database o statici

Se sono stati modificati solo i modelli di dati, applicare le modifiche del database senza ridistribuire completamente:

npx rayfin up db apply

Se è stato modificato solo il codice front-end, ridistribuire gli asset statici:

npx rayfin up staticapp deploy

Aggiungi funzioni

Le funzioni sono funzioni TypeScript che girano sul server all'interno della tua app Fabric. Usa funzioni per la logica che non devono essere eseguite nel browser, come lavorare con segreti, accedere a dati privilegiati e chiamare servizi esterni con l'identità dell'app.

npx rayfin functions init

L'inizializzatore usa services.functions.path quando configurato, rileva una posizione dello spazio di lavoro come packages/functions o preserva un pacchetto flat rayfin/functions esistente. Usalo --path <relative-path> per scegliere esplicitamente una location.

Le funzioni abilitate richiedono services.functions.auth.type: application. Le chiamate esterne tramite ctx.Tokens.* usano l'identità dell'app e i relativi permessi, non i permessi delle risorse esterne dell'utente che invoca. Nelle app Fabric attuali, quell'identità è il proprietario dell'oggetto dell'app. Concedigli accesso a ogni risorsa. Al contrario, ctx.getDataClient() utilizza il token Rayfin dell'invocazione e preserva le politiche dati del chiamante.

GitHub Copilot può generare e aggiornare i file e i componenti necessari. Puoi anche chiedere all'agente di eseguire l'app, debugare le funzioni localmente e distribuire l'app. Ad esempio, puoi usare il seguente prompt per costruire un assistente di revisione pull request AI utilizzando funzioni:

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

Vedi Usa Funzioni e Collega Funzioni a risorse esterne per i dettagli di identità e implementazione.

Risolvere i problemi comuni

L'accesso non funziona o la distribuzione restituisce 401 o 403

Eseguire npx rayfin login di nuovo, quindi riprovare npx rayfin up.

È necessario esaminare le operazioni che l'interfaccia della riga di comando eseguirà

Prima di distribuire le modifiche, eseguire npx rayfin up --dry-run.

L'app viene distribuita, ma modifichi solo lo schema

Per eseguire il push delle modifiche dello schema in modo indipendente, usare npx rayfin up db apply. Se si eseguono modifiche distruttive come la modifica del tipo di una colonna o la rimozione di una colonna, questo comando ha esito negativo. Per forzare le modifiche, è possibile usare il --force flag . Questa azione può essere una modifica che causa un'interruzione.

Passaggi successivi