Guida introduttiva: Creare un'app con Copilot Managed Runtime SDK

Questa guida introduttiva illustra come eseguire lo scaffolding, eseguire e spedire un'app Hello World dal terminale usando l'interfaccia della riga di comando di Copilot Managed Runtime (@microsoft/cmr-cli) e l'SDK di Copilot Managed Runtime (@microsoft/cmr-apps). Alla fine, l'app Hello World è in esecuzione in locale, visualizzata in anteprima su un URL ospitato e distribuita in tempo reale agli utenti, il tutto dal terminale, con il controllo del codice sorgente gestito da un repository gestito dalla piattaforma.

I passaggi principali coprono il percorso end-to-end predefinito. La sezione Varianti illustra l'associazione a un repository GitHub esistente, la conversione di un progetto Web esistente e il pull di un'app in un nuovo computer.

Prerequisiti

Prima di iniziare, assicurarsi che nel computer siano installati e configurati gli strumenti seguenti:

  • Node.js (versione LTS).
  • Git, con un gestore delle credenziali configurato.
  • Un terminale a scelta (terminale integrato di Visual Studio Code, Terminale Windows, iTerm e così via).

Procedura

La tabella seguente descrive il processo da seguire.

Ordina Passaggio Descrizione
1 Installare l'interfaccia della riga di comando di Copilot Managed Runtime Installa l'interfaccia della riga di comando globalmente e conferma che il ms comando è disponibile.
2 Accesso Autentica l'interfaccia della riga di comando con il tenant usando l'identità di Microsoft Entra.
3 Creare l'app Crea una nuova app e impalca i file di progetto in una nuova cartella.
4 Creare ed eseguire l'app in locale Installa le dipendenze e avvia il ciclo di sviluppo locale per testare rapidamente le modifiche.
5 Aggiungere un connettore (facoltativo) Individua e aggiunge un connettore di dati regolati all'app, se sono necessari dati esterni.
6 Esegui il commit, crea e invia in anteprima Esegue il commit delle modifiche locali e le esegue il push in modo che l'anteprima possa compilare il commit più recente.
7 Riprodurre l'app in modalità anteprima Apre l'esperienza di anteprima ospitata e convalida lo stato della build per il commit inviato.
8 Distribuire per live Promuove la versione dell'app convalidata dall'anteprima al live per gli utenti finali.

Installare l'interfaccia della riga di comando di Copilot Managed Runtime

Installare l'interfaccia della riga di comando globalmente in modo che il ms comando sia disponibile in qualsiasi progetto:

npm install -g @microsoft/cmr-cli

Consiglio

È inoltre possibile utilizzare questo comando per aggiornare l'interfaccia della riga di comando alla versione più recente.

Verifica l'installazione:

ms --version

Accesso

Autenticare l'interfaccia della riga di comando con il tenant usando ms auth login. Questa configurazione una tantum per computer usa l'identità di Microsoft Entra per tutto ciò che segue.

ms auth login

Si apre una finestra del browser per l'accesso. Dopo l'accesso, il terminale conferma l'identità autenticata.

Creare l'app

Creare una nuova app e eseguire lo scaffolding del progetto con ms app create. Questo comando crea l'app sulla piattaforma, configura automaticamente un repository Git gestito dalla piattaforma e esegue lo scaffolding dei file di progetto.

ms app create hello-world --display-name "Hello World"
cd hello-world

Poiché la piattaforma gestisce il repository, non è necessario configurare il proprio controllo del codice sorgente per iniziare. La piattaforma effettua automaticamente il provisioning, protegge e connette il repository alla pipeline di compilazione e distribuzione.

Creare ed eseguire l'app in locale

Compila ed esegui l'app in locale per il tuo ciclo di sviluppo interno. Questo approccio consente di visualizzare immediatamente le modifiche mentre si modifica il codice. Rimani in modalità locale per tutte le iterazioni: scrittura di funzionalità, ottimizzazione dell'interfaccia utente, debug della logica, prova delle chiamate al connettore. Passa a una build della piattaforma quando l'app si comporta nel modo desiderato in locale e sei pronto per convalidarla in un ambiente ospitato.

Installa le dipendenze una volta, quindi avvia il ciclo di sviluppo locale con ms app dev:

npm install
ms app dev

ms app dev Avvia il processo di sviluppo del progetto. Le impostazioni dell'app e del runtime provengono da ms.config.json, mentre il comando di sviluppo locale proviene da package.json, che deve definire scripts.dev. L'interfaccia della riga di comando rileva npm, pnpm, yarn o bun dai metadati del pacchetto o dai file di blocco ed esegue il comando del gestore di run dev pacchetti. È necessario eseguire di nuovo l'esecuzione npm install solo dopo la modifica delle dipendenze. Apri l'URL di gioco locale stampato nel terminale per vedere il modello Hello World servito dal tuo computer tramite il giocatore ospitato.

Importante

Aprire l'URL nello stesso profilo del browser del tenant.

Nota

Restrizioni di accesso alla rete locale

Da dicembre 2025, i browser Chrome e Microsoft Edge bloccano le richieste da origini pubbliche agli endpoint locali per impostazione predefinita. Poiché l'app si connette a localhost durante lo sviluppo, potrebbe essere necessario concedere l'autorizzazione del browser o configurare i criteri aziendali. Per gli scenari incorporati, includere allow="local-network-access" nei tag iframe.

Altre informazioni sulle restrizioni di accesso alla rete locale:

Aggiungere un connettore (facoltativo)

Se l'app richiede dati, aggiungere un connettore. Per iniziare, scopri cosa è disponibile nel tuo ambiente con ms connector list:

ms connector list [--search <query>]

L'interfaccia della riga di comando stampa i connettori corrispondenti con l'ID, il contrassegno tabulare e lo stato dei criteri unificati. L'individuazione include connettori bloccati per impostazione predefinita; pass --only-allowed per eliminarle. La prevenzione della perdita dei dati e i criteri avanzati dei connettori sono regole definite dall'amministratore che regolano i connettori che l'app può utilizzare. Esaminare lo stato prima di selezionare un connettore per evitare di creare dati su un'origine dati che i criteri bloccano in fase di distribuzione o esecuzione.

Selezionare uno dei connettori elencati e aggiungerlo all'app con ms app add data-source:

ms app add data-source --connector <connector>

In modalità interattiva, l'interfaccia della riga di comando guida l'utente attraverso la configurazione completa: scegliere una connessione esistente o crearne una nuova, selezionare un set di dati (ad esempio, un sito di SharePoint) e quindi selezionare una tabella. L'interfaccia della riga di comando genera automaticamente modelli e servizi fortemente tipizzati senza generated/ bisogno di comandi aggiuntivi.

Esegui il commit, crea e invia in anteprima

Ora che l'app viene eseguita in locale, eseguire il commit del lavoro ed eseguirne il push. Questo push carica il commit più recente nel repository gestito dalla piattaforma. Non attiva una compilazione da solo. La piattaforma crea l'app su richiesta quando si apre l'URL di anteprima.

git add .
git commit -m "first pass"
git push

Riprodurre l'app in modalità anteprima

Quando l'app funziona nel modo desiderato in locale e sei pronto per testarla in un ambiente ospitato, aprila in modalità anteprima con ms app play:

ms app play --mode preview

Se non si specifica un ID app, il comando predefinito è il progetto app della directory corrente.

Quando riproduci l'app in modalità anteprima, la piattaforma avvia una build per l'ultimo commit push. Se è la prima volta che si accede all'anteprima dopo un push, viene visualizzato uno di questi stati nell'anteprima:

  1. Banner Build in progress : la piattaforma sta creando il tuo ultimo commit.
  2. Compilazione completata. La nuova versione dell'app è pronta. : selezionare Aggiorna per caricare la build più recente.
  3. Banner di compilazione non riuscito : si è verificato un problema durante la creazione. Esegui ms app build-status[--commit <sha>] per ottenere i dettagli completi dell'errore, in modo da poter correggere il codice ed eseguire nuovamente il push. Se ometti il commit SHA, il comando predefinito è l'attuale Git HEADlocale, non l'ultimo commit compilato. Passare esplicitamente lo SHA del commit push se il checkout è stato spostato.

Consiglio

È possibile eseguire ms app build[--commit <sha>] in qualsiasi momento per attivare la creazione di una piattaforma. Se non si fornisce un commit SHA, l'impostazione predefinita è l'attuale Git HEADlocale. Esegui il push di quel commit prima della compilazione o usalo --commit <sha> per una particolare revisione push. Nella maggior parte dei casi, basta spingere e premere l'URL di anteprima. Usa questo comando solo se vuoi avviare una build della piattaforma prima di aprire l'anteprima, ad esempio per riscaldare la build in modo che l'anteprima venga caricata immediatamente quando viene condivisa o per verificare che una build della piattaforma abbia esito positivo senza uscire dal terminale.

Distribuire per live

Quando l'anteprima è corretta, promuovi a un'app live con ms app deploy:

ms app deploy

Per distribuire uno specifico commit precedente, passa --commit <id>:

ms app deploy --commit <commit-id>

In caso di esito positivo, l'interfaccia della riga di comando restituisce l'URL dell'app live. Aprirlo per verificare che l'app sia in esecuzione per gli utenti come app Copilot Managed Runtime, governata da Microsoft Entra ID, Accesso condizionale e criteri ACP, con telemetria e integrità operativa che fluiscono attraverso gli strumenti dell'interfaccia di amministrazione.

Congratulazioni! È stata distribuita la prima app Copilot Managed Runtime.

Variazioni

Utilizzare questi percorsi facoltativi se si desidera connettere un repository di origine diverso, eseguire l'onboarding di un progetto esistente o continuare lo sviluppo da un altro computer.

Automatizzare la distribuzione con GitHub Actions

Per compilare e distribuire automaticamente l'app da un flusso di lavoro di GitHub Actions anziché dal terminale, creare l'app per la distribuzione di artefatti esterni con ms app create--repo none, quindi seguire Distribuire app di runtime gestite di Microsoft Copilot con GitHub Actions. La distribuzione di artefatti esterni non è consentita per impostazione predefinita. Consulta Distribuzione di artefatti esterni.

Bring your own GitHub repository

Se il tuo team utilizza GitHub, crea un repository esterno vuoto, quindi associa la tua app a tale repository al momento della creazione passando --repo. Il repository non deve contenere file rilevati, incluso un README o una licenza. Anche la directory di destinazione locale deve essere vuota, senza file nascosti:

ms app create hello-world --display-name "Hello World" --repo https://contoso.ghe.com/team/hello-world

La piattaforma crea, analizza e distribuisce dal repository GitHub come unica fonte di verità. I criteri di filiale esistenti e le revisioni delle richieste pull continuano ad essere applicati.

Per un repository che contiene già il codice sorgente, clonarlo ed git clone <repository-url> eseguirlo ms app init nel checkout invece di ms app create.

Nota

Il repository deve essere di proprietà di un'organizzazione su GitHub Enterprise Cloud. I repository possono usare un host o un github.com*.ghe.com host di residenza dei dati. GitHub Enterprise Server e i repository di proprietà di account personali o organizzazioni che non sono in GitHub Enterprise Cloud non sono supportati.

Passare un URL di repository completo https:// . I moduli bare-host come contoso.ghe.com/team/hello-world quelli vengono rifiutati. Configura la visibilità del repository e altri criteri di gestione del repository in GitHub Enterprise Cloud. Per ulteriori informazioni, vedere Applicazione dei criteri di gestione dell'archivio nell'azienda.

Convertire un progetto Web esistente

Per trasformare un progetto già esistente in un'applicazione, eseguitelo ms app init all'interno della directory del progetto invece di ms app create:

cd my-existing-web-app
ms app init --display-name "My App"

ms app init esegue il provisioning di un record dell'app, scrive ms.config.jsone crea un repository Git gestito dalla piattaforma o mantiene il Git esistente remoto, a seconda di ciò che rileva nella directory di lavoro.

Clonare un'app in un nuovo computer

Per lavorare su un'app esistente con Git gestito dalla piattaforma da un nuovo computer, installare gli strumenti dei prerequisiti, accedere e usare ms app clone. Questo comando configura l'autenticazione Git gestita dalla piattaforma per il clone iniziale e le successive operazioni di recupero e push:

ms auth login
ms app clone --app <app-id>
cd <app-directory>
npm install
ms app dev

Consente ms app list --permission edit di trovare l'ID di un'app modificabile. Per i repository GitHub esterni, ottieni l'accesso al repository separatamente in GitHub e utilizza git clone <repository-url> invece. Consulta Collaborare a un'app.