Condividi tramite

Guida dettagliata all'installazione

Dopo aver ottenuto l'accesso al codice (in Codespaces o localmente) seguendo la guida introduttiva, seguire questa procedura:

Suggerimento

Se non si vuole seguire manualmente i passaggi, chiedere a GitHub Copilot di eseguire il lavoro. Il repository Starter-Kit è abilitato per l'intelligenza artificiale e Copilot può guidare in modo interattivo il processo di configurazione. Prova questo prompt: "Aiutami a iniziare con questo repository ed eseguire l'esempio HelloWorld."

Passaggio 1: Eseguire lo script di installazione

Lo script di installazione automatizza la maggior parte della configurazione (registrazione dell'app, impostazioni predefinite e così via).

# From the repo root
pwsh ./scripts/Setup/Setup.ps1 -WorkloadName "Org.MyWorkload"

Note sullo script di installazione:

  • WorkloadName deve seguire il modello Organization.WorkloadName. Per lo sviluppo, utilizzare Org.[YourWorkloadName].
  • Se si riutilizza un'applicazione Microsoft Entra esistente, assicurarsi che gli URI di reindirizzamento SPA siano configurati come descritto nella guida alla configurazione manuale dei repository.
  • In macOS/Linux usare pwsh per eseguire script.
  • Assicurarsi che i criteri di esecuzione di PowerShell siano impostati su Senza restrizioni e che i file vengano sbloccati se viene chiesto se devono essere avviati i file di PowerShell.
  • Seguire le indicazioni fornite da Script per ottenere tutte le impostazioni

Lo script di installazione può essere eseguito più volte. Se i valori sono già presenti, viene chiesto se devono essere sovrascritti. Se si desidera sovrascrivere tutti gli elementi, usare il parametro Force.

Annotazioni

Se si verificano errori di installazione, vedere l'errore di installazione di PowerShell nella sezione relativa alla risoluzione dei problemi seguente.

Suggerimento

Se si verificano problemi con lo script di installazione automatica, è possibile seguire la Guida all'installazione manuale per la configurazione manuale.

Passaggio 2: Avviare l'ambiente di sviluppo

Eseguire il server di sviluppo (front-end + API) e registrare l'istanza locale con Fabric tramite DevGateway.

# Terminal 1: start local dev server
pwsh ./scripts/Run/StartDevServer.ps1

# Terminal 2: start DevGateway to register your local instance with Fabric
pwsh ./scripts/Run/StartDevGateway.ps1

Passaggio 3: Abilitare le funzionalità di sviluppo in Fabric

Navigare al portale di Fabric e configurare le impostazioni necessarie:

3.1 Configurare le impostazioni del tenant nel portale di amministrazione:

Passare alle impostazioni del portale di amministrazione e abilitare le impostazioni del tenant seguenti:

  • Gli amministratori e i collaboratori della capacità possono aggiungere e rimuovere carichi di lavoro aggiuntivi
  • Gli amministratori dell'area di lavoro possono sviluppare carichi di lavoro dei partner
  • Gli utenti possono visualizzare e usare carichi di lavoro aggiuntivi non convalidati da Microsoft

Screenshot delle impostazioni del tenant.

3.2 Attivare la modalità sviluppatore di Fabric:

Navigare alle Fabric Developer Settings (Impostazioni sviluppatore Fabric) e abilitare la modalità sviluppatore Fabric.

Screenshot della modalità sviluppatore di Fabric.

A questo punto è possibile creare il primo elemento Hello World in Fabric.

Passaggio 4: Testare l'elemento HelloWorld

È possibile accedere al carico di lavoro dall'hub del carico di lavoro (cercare il nome del carico di lavoro) o spostarsi direttamente. Creare quindi un elemento Hello World.

Steps:

  1. Hub del carico di lavoro Open Fabric: Individua il carico di lavoro, ad esempio Org.MyWorkload.

    • Navigazione diretta: https://app.fabric.microsoft.com/workloadhub/detail/<WORKLOAD_NAME>?experience=fabric-developer
    • Sostituire <WORKLOAD_NAME> con il nome effettivo del carico di lavoro (ad esempio, Org.MyWorkload)

  2. Crea un nuovo elemento: selezionare il tipo di elemento Hello World e scegliere l'area di lavoro di sviluppo.

  3. Verifica funzionalità: viene aperto l'editor; verificare che l'elemento funzioni come previsto e venga visualizzato come un artefatto nativo nell'area di lavoro.

Congratulazioni! Hai creato il tuo primo elemento dal tuo ambiente di sviluppo.

Passaggio 5: Iniziare a scrivere codice

Ora che si è tutti configurati, è possibile iniziare a creare elementi personalizzati. Seguire la guida completa per informazioni su come creare elementi di Fabric personalizzati:

📖 Guida alla creazione di elementi di tessuto personalizzati - questa guida fornisce due approcci per la creazione di elementi:

  • Approccio AI-Assistito: utilizzare GitHub Copilot per guida interattiva (consigliata per i nuovi sviluppatori)
  • Approccio con script manuali: usare script di PowerShell automatizzati per la configurazione rapida (consigliato per sviluppatori esperti)

Opzioni di avvio rapido:

  • Aggiornare l'editor HelloWorld esistente: Workload/app/items/HelloWorldItem/HelloWorldItemEditor.tsx
  • In alternativa, scaffoldare un nuovo elemento con lo script: ./scripts/Setup/CreateNewItem.ps1

Buon codice! 🚀

Procedure consigliate

  • Creare una copia tramite fork del repository: creare una copia tramite fork del repository Starter-Kit e usare il fork come base del progetto.
  • Mantieni sincronizzato: Assicurati che il fork sia sincronizzato con l'upstream per raccogliere i miglioramenti.
  • Mantenere la coerenza della struttura del progetto: mantenere i modelli di progetto e organizzazione dello Starter-Kit per garantire la compatibilità con gli aggiornamenti futuri e mantenere la chiarezza del codice.
  • Integrazione regolare Starter-Kit: integrare regolarmente le modifiche del codice dal Starter-Kit al progetto per trarre vantaggio dalle correzioni di bug, dalle nuove funzionalità e dagli aggiornamenti della sicurezza. Configurare un processo per esaminare e unire le modifiche upstream a intervalli regolari (mensile o trimestrale).
  • Convalidare i manifesti in anticipo: convalidare il manifesto del carico di lavoro in anticipo e seguire le autorizzazioni con privilegi minimi.
  • Usare i contenitori di sviluppo: usare un contenitore di sviluppo o Codespaces per un ambiente coerente e eliminabile.
  • Usare gli script forniti: usare gli script forniti (programma di installazione, StartDevServer, StartDevGateway) per automatizzare la configurazione e il flusso di lavoro giornaliero.

Risoluzione dei problemi comuni

Errore di installazione di PowerShell

Se si verifica un errore durante l'esecuzione dello script di installazione, assicurarsi di avere installato e configurato la versione più recente di PowerShell nell'ambiente in cui si esegue lo script.

Screenshot dell'errore di installazione di PowerShell.

Errore dei criteri di esecuzione dello script

Se incontri: cannot be loaded because the execution policy is unrestricted

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

La porta 5173 è in uso

Se il DevServer non può essere avviato sulla porta 5173, trovate e terminate il processo.

# Find process using port
Get-Process -Id (Get-NetTCPConnection -LocalPort 5173).OwningProcess

# Terminate process
Stop-Process -Id <ProcessId> -Force

Errori di dipendenze

Se si verificano errori relativi alle dipendenze mancanti:

# From Workload folder
cd Workload
npm install

Problemi di autenticazione di DevGateway

Se l'autenticazione non riesce all'avvio di DevGateway:

  1. Verificare gli URI di reindirizzamento della registrazione dell'app in Microsoft Entra
  2. Verificare che le impostazioni del tenant consentano le funzionalità di sviluppo necessarie
  3. Assicurarsi di aver eseguito l'accesso al tenant corretto in DevGateway

Per informazioni complete sulla risoluzione dei problemi, vedere readme del repositoryStarter-Kit.

Note importanti

Nuove restrizioni di accesso alla rete locale chrome

Google ha introdotto nuove restrizioni di accesso alla rete locale (LNA) in Chrome che interromperanno lo sviluppo locale con DevServer. Queste restrizioni impediscono ai siti Web di accedere alle risorse di rete locali senza autorizzazioni esplicite per l'utente.

Azione necessaria per lo sviluppo locale: è necessario modificare la configurazione di Chrome per continuare a sviluppare carichi di lavoro in locale:

  1. Navigare all'indirizzo chrome://flags/#local-network-access-check in Chrome
  2. Impostare il flag su "Disabilitato"
  3. Riavviare Chrome

Perché è necessario: le nuove restrizioni bloccano la comunicazione tra il carico di lavoro in esecuzione in Fabric e il server DevGateway locale, essenziale per il flusso di lavoro di sviluppo.

Risorse aggiuntive:

Importante

Senza disabilitare questo flag, lo sviluppo locale con DevGateway non funzionerà in Chrome. Questa modifica di configurazione è necessaria solo per gli ambienti di sviluppo.

Passaggi successivi

  • Last updated on