Einrichten der Entwicklungsumgebung

Dieser Leitfaden führt Sie durch die Einrichtung Ihrer Electron-Entwicklungsumgebung für die Entwicklung von Windows-API. Sie installieren die erforderlichen Tools, initialisieren Ihre project und konfigurieren Windows-SDKs.

Voraussetzungen

Bevor Sie beginnen, stellen Sie sicher, dass Sie folgendes haben:

• Windows 11
• Node.js - winget install OpenJS.NodeJS --source winget
• .NET SDK v10 - winget install Microsoft.DotNet.SDK.10 --source winget
• Visual Studio mit der nativen Desktop-Workload - winget install --id Microsoft.VisualStudio.Community --source winget --override "--add Microsoft.VisualStudio.Workload.NativeDesktop --includeRecommended --passive --wait"

Schritt 1: Erstellen einer neuen Elektronen-App

Wir beginnen mit einer frischen Electron-App mit Electron Forge, die hervorragende Werkzeug- und Verpackungsunterstützung bietet. Wenn Sie mit einer vorhandenen App beginnen, können Sie diesen Schritt überspringen.

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

Wenn Sie von Electron Forge aufgefordert werden:

• Bundler: Keine auswählen (empfohlen – systemeigene Addons funktionieren ohne zusätzliche Konfiguration)
• Sprache: JavaScript auswählen (in diesem Leitfaden wird JS verwendet; TypeScript funktioniert ebenfalls)
• Electron-Version: Neueste Auswählen
• Initialisieren von Git: Ihre Vorliebe

Überprüfen Sie, ob die App ausgeführt wird:

npm start

Das Standardfenster "Electron Forge" sollte angezeigt werden. Schließen Sie es, und fügen wir Windows Funktionen hinzu!

Schritt 2: Installieren der winapp CLI

Der Electron-Workflow erfordert das npm-Paket (@microsoft/winappcli) anstelle der eigenständigen CLI, die von Winget installiert wurde. Das npm-Paket enthält Node.js-spezifische Hilfsprogramme (wie add-electron-debug-identity und create-addon), die in der nativen CLI nicht verfügbar sind. Wenn Sie winapp bereits von winget installiert haben, ist das in Ordnung – das npm-Paket fügt Node.js-spezifischen Tools als Projektabhängigkeit hinzu und führt keinen Konflikt mit Ihrer Systeminstallation.

npm install --save-dev @microsoft/winappcli

Schritt 3: Initialisieren Sie das Projekt für Windows-Entwicklung

Der winapp init Befehl richtet alles ein, was Sie benötigen: App-Manifest, Ressourcen und SDKs.

Führen Sie den folgenden Befehl aus, und folgen Sie den Eingabeaufforderungen:

npx winapp init .

Wenn Sie dazu aufgefordert werden:

• Paketname: Drücken Sie die EINGABETASTE, um die Standardeinstellung zu akzeptieren (my-windows-app)
• Publisher Name: Drücken Sie die EINGABETASTE, um die Standardeinstellung zu akzeptieren oder Ihren Namen einzugeben.
• Version: Drücken Sie die EINGABETASTE, um 1.0.0.0 zu akzeptieren.
• Einstiegspunkt: Drücken Sie die EINGABETASTE, um die Standardeinstellung zu übernehmen (my-windows-app.exe)
• Setup-SDKs: Wählen Sie "Stabile SDKs" aus.

Was macht winapp init das?

Mit diesem Befehl wird alles eingerichtet, was Sie für die Windows-Entwicklung benötigen:

1. Erstellt .winapp/ einen Ordner , der Folgendes enthält:

   • Header und Bibliotheken aus dem Windows SDK
   • Kopfzeilen und Bibliotheken aus dem Windows App SDK
   • NuGet-Pakete mit den erforderlichen Binärdateien

2. Generiert Package.appxmanifest – Das App-Manifest, das für die App-Identität und das MSIX-Paket erforderlich ist

3. Erstellt Assets/ ordner – Enthält App-Symbole und visuelle Ressourcen für Ihre App

4. Creates winapp.yaml – Verfolgt SDK-Versionen und Projektkonfiguration

5. Installs Windows App SDK runtime – Notwendige Laufzeitkomponenten für moderne APIs

6. Enables-Entwicklermodus in Windows – Erforderlich für das Debuggen unserer Anwendung

Sie können Package.appxmanifest öffnen, um Eigenschaften wie den Anzeigenamen, den Herausgeber und die Funktionen weiter anzupassen.

Schritt 4: Hinzufügen der Wiederherstellung zur Buildpipeline

Um sicherzustellen, dass die Windows SDKs verfügbar sind, wenn andere Entwickler Ihr Projekt oder in CI/CD-Pipelines klonen, fügen Sie Ihrem postinstall ein skript package.json hinzu:

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

Dieses Skript wird automatisch nach npm install ausgeführt und erledigt zwei Aufgaben:

1. winapp restore – Lädt alle Windows SDK-Pakete herunter und stellt sie im Ordner .winapp/ wieder her.
2. winapp node add-electron-debug-identity - Registriert Ihre Electron-App mit Debugidentität (mehr dazu in den nächsten Schritten)

Führen Sie nun npm install aus, um das Postinstall-Skript auszulösen und die Windows Umgebung zu konfigurieren:

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"
  }
}

Schritt 5: Grundlegendes zur Debugidentität

Die npm install Ausführung in Schritt 4 hat das postinstall Skript ausgelöst, das winapp node add-electron-debug-identity ausführt. Dadurch erhält Ihre App eine temporäre Debugidentität, sodass Sie Windows APIs testen können, die app-Identität während der Entwicklung erfordern.

Was ist die Funktion der Debug-Identität?

Dieser Befehl:

1. Liest Ihre Package.appxmanifest, um Details und Funktionen der App abzurufen.
2. Registriert electron.exe in Ihrem node_modules mit einer temporären Identität.
3. Ermöglicht es Ihnen, identitätsrelevante APIs zu testen, ohne ein vollständiges MSIX-Paket zu erstellen.

Die Debug-Identität wurde automatisch angewendet, als Sie npm install in Schritt 4 ausgeführt haben. In Zukunft wird es erneut angewendet, wenn npm install ausgeführt wird.

Wann Debug-Identität manuell aktualisieren

Sie müssen diesen Befehl immer dann manuell ausführen, wenn Sie Package.appxmanifest (Funktionen, Identität oder Eigenschaften ändern) oder eines der verknüpften Objekte (Symbole, mcp.json usw.) ändern.

npx winapp node add-electron-debug-identity

Testen des Setups

Sie können jetzt Ihre Electron-App mit der angewendeten Debugidentität testen:

npm start

Es sollte ein Desktopanwendungsfenster (keine Browserregisterkarte) angezeigt werden — so werden Electron-Apps ausgeführt.

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

npx winapp node clear-electron-debug-identity

Nächste Schritte

Nachdem Ihre Entwicklungsumgebung eingerichtet ist, können Sie systemeigene Addons erstellen und Windows-APIs aufrufen:

• Erstellen eines Phi-Silikat-Addon – Erfahren Sie, wie Sie ein C#-Addon erstellen, das die Phi-Silika-KI-API aufruft
• Creating a WinML Addon – Erfahren Sie, wie Sie ein C#-Addon erstellen, das Windows Machine Learning verwendet.
• Verpackung für Verteilung – Erstellen eines MSIX-Pakets für die Verteilung

Oder kehren Sie zur Übersicht über die ersten Schritte zurück.