Configurazione dell'ambiente di sviluppo

Questa guida illustra come configurare l'ambiente di sviluppo Electron per lo sviluppo di API Windows. Si installeranno gli strumenti necessari, si inizializzeranno i project e si configureranno gli SDK di Windows.

Prerequisiti

Prima di iniziare, assicurati di avere:

• Windows 11
• Node.js - winget install OpenJS.NodeJS --source winget
• .NET SDK v10 - winget install Microsoft.DotNet.SDK.10 --source winget
• Visual Studio con il workload desktop nativo - winget install --id Microsoft.VisualStudio.Community --source winget --override "--add Microsoft.VisualStudio.Workload.NativeDesktop --includeRecommended --passive --wait"

Passaggio 1: Creare una nuova app Electron

Inizieremo con una nuova app Electron usando Electron Forge, che offre un eccellente supporto per strumenti e pacchetti. Se si inizia da un'app esistente, è possibile ignorare questo passaggio.

npm create electron-app@latest my-windows-app
cd my-windows-app

Quando richiesto da Electron Forge:

• Bundler: selezionare Nessuno (scelta consigliata: i componenti aggiuntivi nativi funzionano senza configurazione aggiuntiva)
• Linguaggio: selezionare JavaScript (questa guida usa JS; TypeScript funziona anche)
• Versione di Electron: selezionare la versione più recente
• Inizializza Git: la tua preferenza

Verificare che l'app funzioni correttamente:

npm start

Dovrebbe essere visualizzata la finestra predefinita Electron Forge. Chiudilo e aggiungiamo le funzionalità di Windows!

Passaggio 2: Installare il CLI di winapp

Il flusso di lavoro Electron richiede il pacchetto npm (@microsoft/winappcli) anziché l'interfaccia della riga di comando autonoma installata da winget. Il pacchetto npm include helper specifici per Node.js (come, ad esempio, add-electron-debug-identity e create-addon) non disponibili nella CLI nativa. Se winapp è già installato da winget, va bene — il pacchetto npm aggiunge gli strumenti specifici di Node.js come dipendenza del progetto e non è in conflitto con l'installazione del sistema.

npm install --save-dev @microsoft/winappcli

Passaggio 3: Inizializzare il project per lo sviluppo di Windows

Il winapp init comando configura tutti gli elementi necessari in un'unica operazione: manifesto dell'app, asset e SDK.

Eseguire il comando seguente e seguire i prompt:

npx winapp init .

Quando richiesto:

• Nome pacchetto: premere INVIO per accettare il valore predefinito (my-windows-app)
• Publisher nome: premere INVIO per accettare il valore predefinito o immettere il nome
• Versione: premere INVIO per accettare 1.0.0.0
• Punto di ingresso: premere INVIO per accettare il valore predefinito (my-windows-app.exe)
• SDK di installazione: selezionare "SDK stabili"

Che cosa fa winapp init ?

Questo comando configura tutto ciò che serve per lo sviluppo di Windows:

1. Crea .winapp/ una cartella contenente:

   • Intestazioni e librerie di Windows SDK
   • Intestazioni e librerie del SDK per app di Windows
   • Pacchetti NuGet con i file binari necessari

2. Genera Package.appxmanifest - Manifesto dell'app necessario per l'identità dell'app e la creazione di pacchetti MSIX

3. Crea Assets/ la cartella : contiene icone dell'app e asset visivi per l'app

4. Crea winapp.yaml - Tiene traccia delle versioni dell'SDK e della configurazione del progetto

5. Installa SDK per app di Windows runtime - Componenti di runtime necessari per le API moderne

6. Attiva la Modalità sviluppatore in Windows - Obbligatorio per il debug della nostra applicazione

È possibile aprire Package.appxmanifest per personalizzare ulteriormente le proprietà, ad esempio il nome visualizzato, l'editore e le funzionalità.

Passaggio 4: Aggiungi 'Restore' alla tua pipeline di compilazione

Per assicurarsi che gli SDK di Windows siano disponibili quando altri sviluppatori clonano il progetto o nelle pipeline CI/CD, aggiungere uno script postinstall al package.json:

{
  "scripts": {
    "postinstall": "winapp restore && winapp node add-electron-debug-identity"
  }
}

Questo script viene eseguito automaticamente dopo npm install e esegue due operazioni:

1. winapp restore - Scarica e ripristina tutti i pacchetti SDK di Windows nella cartella .winapp/
2. winapp node add-electron-debug-identity - Registra l'app Electron con l'identità di debug (maggiori dettagli nei passaggi seguenti)

Eseguire ora npm install per attivare lo script di postinstallazione e configurare l'ambiente Windows:

npm install

if (process.platform === 'win32') {
  const { execSync } = require('child_process');
  try {
    execSync('npx winapp restore && npx winapp cert generate --if-exists skip && npx winapp node add-electron-debug-identity', {
      stdio: 'inherit'
    });
  } catch (error) {
    console.warn('Warning: Windows-specific setup failed. If you are not developing Windows features, you can ignore this.');
  }
} else {
  console.log('Skipping Windows-specific setup on non-Windows platform.');
}

{
  "scripts": {
    "postinstall": "node scripts/postinstall.js"
  }
}

Passaggio 5: Informazioni sull'identità di debug

Il npm install eseguito nel passaggio 4 ha attivato il postinstall script, che ha eseguito winapp node add-electron-debug-identity. In questo modo l'app offre un'identità di debug temporanea in modo da poter testare Windows API che richiedono l'identità dell'app durante lo sviluppo.

Che cosa fa il debug dell'identità?

Questo comando:

1. Legge il tuo Package.appxmanifest per ottenere i dettagli e le funzionalità dell'app
2. Registra electron.exe nel node_modules con un'identità temporanea.
3. Consente di testare le API necessarie per l'identità senza creare un pacchetto MSIX completo

L'identità di debug è stata applicata automaticamente quando è stata eseguita npm install nel passaggio 4. In futuro, verrà riapplicata ogni volta che chiunque esegue npm install.

Quando è necessario aggiornare manualmente l'identità di debug

È necessario eseguire questo comando manualmente ogni volta che si modificano Package.appxmanifest (modifica funzionalità, identità o proprietà) o qualsiasi asset collegato (icone, mcp.jsone così via)

npx winapp node add-electron-debug-identity

Test della configurazione

È ora possibile testare l'app Electron con l'identità di debug applicata:

npm start

Dovrebbe essere visualizzata una finestra dell'applicazione desktop aperta (non una scheda del browser): questo è il modo in cui vengono eseguite le app Electron.

{
  "scripts": {
    "start": "electron-forge start -- --no-sandbox"
  }
}

npx winapp node clear-electron-debug-identity

Operazioni successive

Ora che l'ambiente di sviluppo è configurato, è possibile creare componenti aggiuntivi nativi e chiamare le API Windows:

• Creazione di un componente aggiuntivo Phi Silica - Informazioni su come creare un componente aggiuntivo C# che chiama l'API Di intelligenza artificiale Phi Silica
• Creating a WinML Addon - Informazioni su come creare un componente aggiuntivo C# che usa Windows Machine Learning
• Creazione di pacchetti per la distribuzione - Creare un pacchetto MSIX per la distribuzione

In alternativa, tornare alla Panoramica introduttiva.