Delen via


Electron instellen voor Windows API-ontwikkeling

Deze handleiding begeleidt u bij het instellen van uw Electron-ontwikkelomgeving voor Windows API-ontwikkeling. U installeert de benodigde hulpprogramma's, initialiseert uw project en configureert Windows SDK's.

Aan het einde van deze handleiding hebt u een Electron-app die:

  • Roept moderne Windows-API's (Windows SDK en Windows App SDK) aan
  • Kan systeemeigen invoegtoepassingen gebruiken met AI-mogelijkheden (Phi Silica of WinML)
  • Wordt uitgevoerd met app-identiteit voor het testen van beveiligde API's
  • Kan worden verpakt als een ondertekende MSIX voor distributie

Vereiste voorwaarden

  • Windows 11 (Copilot+ PC als u Phi Silicium gebruikt)
  • Node.js - winget install OpenJS.NodeJS --source winget
  • .NET SDK v10 - winget install Microsoft.DotNet.SDK.10 --source winget
  • Visual Studio met de Native Desktop-ontwikkelingstaak - winget install --id Microsoft.VisualStudio.Community --source winget --override "--add Microsoft.VisualStudio.Workload.NativeDesktop --includeRecommended --passive --wait"

Stap 1: Een nieuwe Electron-app maken

Begin met een nieuwe Electron-app met Electron Forge. Als u een bestaande app hebt, kunt u deze stap overslaan.

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

Controleer of de app wordt uitgevoerd:

npm start

Stap 2: Winapp CLI installeren

npm install --save-dev @microsoft/winappcli

Stap 3: de project voor Windows-ontwikkeling initialiseren

npx winapp init

Wanneer u hierom wordt gevraagd:

  • Pakketnaam: Druk op Enter om de standaardwaarde te accepteren (mijn-windows-app)
  • Publisher naam: Druk op Enter om de standaardinstelling te accepteren of voer uw naam in
  • Versie: Druk op Enter om 1.0.0.0 te accepteren
  • Toegangspunt: Druk op Enter om de standaardwaarde (my-windows-app.exe) te accepteren
  • Installatie-SDK's: Selecteer "Stabiele SDK's"

Wat doet winapp init?

Met deze opdracht stelt u alles in wat u nodig hebt voor Windows-ontwikkeling:

  1. Creates .winapp/ folder met headers en bibliotheken uit de Windows SDK en Windows App SDK
  2. Genereert appxmanifest.xml - Het app-manifest dat is vereist voor app-identiteit en MSIX-pakketten
  3. Aanmaken van de Assets/ map - Bevat app-pictogrammen en visuele assets
  4. Creates winapp.yaml - Houdt SDK-versies en project configuratie bij
  5. Installs Windows App SDK runtime - Vereiste runtime-onderdelen voor moderne API's
  6. Hiermee schakelt u de ontwikkelaarsmodus in Windows in: vereist voor foutopsporing

Opmerking

De .winapp/ map wordt automatisch toegevoegd aan .gitignore en mag niet worden ingecheckt bij broncodebeheer.

Stap 4: 'Restore' toevoegen aan uw build-pijplijn

Voeg een postinstall-script toe aan uw package.json om ervoor te zorgen dat de Windows-SDK's beschikbaar zijn wanneer andere ontwikkelaars uw project klonen:

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

Dit script wordt uitgevoerd na npm install en:

  1. winapp restore - Downloadt en herstelt alle Windows SDK-pakketten
  2. winapp node add-electron-debug-identity - Registreert uw Electron-app met foutopsporingsidentiteit

Voor platformoverschrijdende projecten maakt u scripts/postinstall.js:

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.');
  }
} else {
  console.log('Skipping Windows-specific setup on non-Windows platform.');
}

Werk vervolgens het volgende bij package.json:

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

Stap 5: Begrijpen van foutopsporingsidentiteit

De opdracht winapp node add-electron-debug-identity doet het volgende:

  1. Leest uw appxmanifest.xml gegevens voor het ophalen van app-details en -mogelijkheden
  2. Registreert electron.exe in uw node_modules met een tijdelijke identiteit
  3. Hiermee kunt u api's testen die vereist zijn voor identiteiten zonder een volledig MSIX-pakket te maken

Voer deze opdracht handmatig uit wanneer u assets wijzigt appxmanifest.xml of koppelt:

npx winapp node add-electron-debug-identity

Test uw installatie:

npm start

Opmerking

Er is een bekende Windows-bug met sparse-verpakking van Electrontoepassingen die crashes of lege vensters kan veroorzaken. Voeg als tijdelijke oplossing toe --no-sandbox aan uw startscript: "start": "electron-forge start -- --no-sandbox". Dit probleem heeft geen invloed op volledige MSIX-pakketten. Als u foutopsporingsidentiteit ongedaan wilt maken, voert u het volgende uit npx winapp node clear-electron-debug-identity.

Volgende stappen 

Nu uw ontwikkelomgeving is ingesteld, maakt u systeemeigen invoegtoepassingen en roept u Windows-API's aan: