De ontwikkelomgeving instellen

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.

Vereiste voorwaarden

Voordat u begint, moet u ervoor zorgen dat u het volgende heeft:

  • Windows 11
  • 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

We beginnen met een nieuwe Electron-app met Electron Forge, die uitstekende hulpmiddelen en verpakkingsondersteuning biedt. Als u begint met een bestaande app, kunt u deze stap overslaan.

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

Wanneer u hierom wordt gevraagd door Electron Forge:

  • Bundler: Selecteer Geen (aanbevolen - systeemeigen invoegtoepassingen werken zonder extra configuratie)
  • Taal: Selecteer JavaScript (in deze handleiding wordt JS gebruikt; TypeScript werkt ook)
  • Electron-versie: Selecteer de meest recente
  • Initialiseer Git: Uw voorkeur

Controleer of de app wordt uitgevoerd:

npm start

U zou het standaardvenster van Electron Forge moeten zien. Sluit deze en laten we Windows mogelijkheden toevoegen.

Stap 2: Winapp CLI installeren

De Electron-werkstroom vereist het npm-pakket (@microsoft/winappcli) in plaats van de zelfstandige CLI die vanuit winget is geïnstalleerd. Het npm-pakket bevat Node.js-specifieke helpers (zoals add-electron-debug-identity en create-addon) die niet beschikbaar zijn in de systeemeigen CLI. Als u winapp al hebt geïnstalleerd vanuit winget, is dat prima: het npm-pakket voegt Node.js-specifieke hulpprogramma's toe als projectafhankelijkheid en conflicteren niet met uw systeeminstallatie.

npm install --save-dev @microsoft/winappcli

Stap 3: de project voor Windows-ontwikkeling initialiseren

Met de winapp init opdracht stelt u alles in dat u in één gebruik nodig hebt: app-manifest, assets en SDK's.

Voer de volgende opdracht uit en volg de aanwijzingen:

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. Hiermee maakt u .winapp/ een map met:

    • Headers en bibliotheken van de Windows SDK
    • Headers en bibliotheken uit de Windows App SDK
    • NuGet-pakketten met de vereiste binaire bestanden

  2. Genereert Package.appxmanifest - Het app-manifest dat is vereist voor app-identiteit en MSIX-pakketten

  3. Map maken Assets/ - Bevat app-pictogrammen en visuele assets voor uw app

  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. Enables Developer Mode in Windows - Vereist voor foutopsporing van onze toepassing

Opmerking

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

U kunt openen Package.appxmanifest om eigenschappen zoals de weergavenaam, uitgever en mogelijkheden verder aan te passen.

Tip

Over de SDK's van de Windows:

  • Windows SDK : een ontwikkelplatform waarmee u Win32/desktop-apps kunt bouwen. Het is ontworpen rond Windows-API's die zijn gekoppeld aan bepaalde versies van het besturingssysteem. Gebruik dit voor toegang tot kern-Win32-API's, zoals bestandssysteem, netwerken en systeemservices.

  • Windows App SDK - Een nieuw ontwikkelplatform waarmee u moderne bureaublad-apps kunt bouwen die kunnen worden geïnstalleerd in Windows versies (tot Windows 10 1809). Het biedt een handige, losgekoppelde abstractie van het besturingssysteem rond de uitgebreide catalogus met Windows OS-API's. De Windows App SDK bevat WinUI 3 en biedt toegang tot moderne functies zoals AI-mogelijkheden (PhiSilium), meldingen, vensterbeheer en meer die regelmatig updates ontvangen, onafhankelijk van Windows os-releases.

Meer informatie: Wat is het verschil tussen de Windows App SDK en de Windows SDK?

Stap 4: Herstel toevoegen aan uw buildpipeline

Als u ervoor wilt zorgen dat de Windows SDK's beschikbaar zijn wanneer andere ontwikkelaars uw project of in CI/CD-pijplijnen klonen, voegt u een postinstall-script toe aan uw package.json:

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

Dit script wordt automatisch uitgevoerd na npm install en voert twee dingen uit:

  1. winapp restore - Downloadt en herstelt alle Windows SDK-pakketten naar de map .winapp/
  2. winapp node add-electron-debug-identity - Registreert uw Electron-app met foutopsporingsidentiteit (meer hierover in de volgende stappen)

Voer nu npm install uit om het script na de installatie te activeren en de Windows-omgeving te configureren:

npm install

Opmerking

Het postinstall script wordt automatisch uitgevoerd na elke npm install. Dit betekent dat de Windows-omgeving automatisch wordt geconfigureerd wanneer iemand uw project kloont en npm install uitvoert.

💡 Platformoverschrijdende ontwikkeling (klik om uit te vouwen)

Als u een platformoverschrijdende Electron-app bouwt en ontwikkelaars aan macOS of Linux laat werken, moet u de Windows-specifieke installatie voorwaardelijk uitvoeren. Dit is de aanbevolen aanpak:

Maken 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. If you are not developing Windows features, you can ignore this.');
  }
} else {
  console.log('Skipping Windows-specific setup on non-Windows platform.');
}

Werk vervolgens het volgende bij package.json:

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

Dit zorgt ervoor dat Windows-specifieke installatie alleen wordt uitgevoerd op Windows machines, zodat ontwikkelaars op andere platforms zonder fouten aan het project kunnen werken.

Stap 5: Begrip van foutopsporingsidentiteit

De npm install die je in stap 4 uitvoerde, heeft het postinstall script geactiveerd, dat vervolgens winapp node add-electron-debug-identity werd uitgevoerd. Dit geeft uw app een tijdelijke foutopsporingsidentiteit, zodat u Windows API's kunt testen waarvoor app-identiteit is vereist tijdens de ontwikkeling.

Wat doet foutopsporingsidentiteit?

Deze opdracht:

  1. Leest uw Package.appxmanifest 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

De foutopsporingsidentiteit is automatisch toegepast toen u npm install uitvoerde in stap 4. In de toekomst wordt het opnieuw toegepast wanneer npm install door iemand wordt uitgevoerd.

Wanneer moet u de foutopsporingsidentiteit handmatig bijwerken

U moet dit commando handmatig uitvoeren wanneer u Package.appxmanifest wijzigt (mogelijkheden, identiteit of eigenschappen) of een van de gelinkte elementen (pictogrammen, mcp.json, enzovoort).

npx winapp node add-electron-debug-identity

Uw installatie testen

U kunt nu uw Electron-app testen met de toegepaste foutopsporingsidentiteit:

npm start

U ziet nu dat er een bureaubladtoepassingsvenster is geopend (geen browsertabblad) - dit is hoe Electron-apps worden uitgevoerd.

⚠️ Bekend probleem: app-crashes of een leeg venster (klik om uit te vouwen)

Er is een bekende Windows-bug bij sparse packaging van Electron-toepassingen die ervoor zorgt dat de app vastloopt bij het starten of geen webinhoud weergeeft. Het probleem is opgelost in Windows, maar is nog niet doorgegeven aan alle apparaten.

Symptomen:

  • App loopt vast direct na het starten
  • Venster wordt geopend, maar er wordt een leeg/wit scherm weergegeven
  • Webinhoud kan niet worden weergegeven

Tijdelijke oplossing:

Voeg de --no-sandbox vlag toe aan uw startscript in package.json. Dit werkt om het probleem door de sandbox van Chromium uit te schakelen, wat veilig is voor ontwikkelingsdoeleinden.

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

Belangrijk: Dit probleem heeft geen invloed op volledige MSIX-pakketten: alleen foutopsporing van identiteiten tijdens de ontwikkeling.

Foutopsporingsidentiteit ongedaan maken (indien nodig voor probleemoplossing):

npx winapp node clear-electron-debug-identity

Hiermee herstelt u het oorspronkelijke Electron-uitvoerbare bestand zonder de foutopsporingsidentiteit.

Volgende stappen

Nu uw ontwikkelomgeving is ingesteld, kunt u systeemeigen invoegtoepassingen maken en Windows API's aanroepen:

Of ga terug naar het Overzicht Aan de slag.

  • Last updated on