開発環境の設定

このガイドでは、Windows API 開発用に Electron 開発環境を設定する手順について説明します。 必要なツールをインストールし、projectを初期化して、Windows SDK を構成します。

[前提条件]

始める前に、以下のことを確認してください:

• Windows 11
• Node.js - winget install OpenJS.NodeJS --source winget
• .NET SDK v10 - winget install Microsoft.DotNet.SDK.10 --source winget
• Visual Studio のネイティブ デスクトップ ワークロード - winget install --id Microsoft.VisualStudio.Community --source winget --override "--add Microsoft.VisualStudio.Workload.NativeDesktop --includeRecommended --passive --wait"

手順 1: 新しい Electron アプリを作成する

優れたツールとパッケージのサポートを提供する Electron Forge を使用した新しい Electron アプリから始めます。 既存のアプリから開始する場合は、この手順をスキップできます。

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

Electron Forge からプロンプトが表示された場合:

• Bundler: [なし] を選択します (推奨 — ネイティブ アドオンは追加の構成なしで動作します)
• 言語: JavaScript を選択します (このガイドでは JS を使用します。TypeScript も機能します)
• Electron バージョン: 最新の選択
• git を初期化する: ユーザー設定

アプリの実行を確認します。

npm start

既定の [Electron Forge] ウィンドウが表示されます。 それを閉じて、Windows機能を追加しましょう。

手順 2: winapp CLI をインストールする

Electron ワークフローには、winget からインストールされたスタンドアロン CLI ではなく 、npm パッケージ (@microsoft/winappcli) が必要です。 npm パッケージには、ネイティブ CLI で使用できない Node.js固有のヘルパー ( add-electron-debug-identity や create-addonなど) が含まれています。 winget から winapp が既にインストールされている場合は問題ありません。npm パッケージはプロジェクトの依存関係として Node.js固有のツールを追加し、システムのインストールと競合しません。

npm install --save-dev @microsoft/winappcli

手順 3: Windows 開発用にprojectを初期化する

winapp init コマンドは、アプリ マニフェスト、アセット、SDK など、必要なものをすべて一度に設定します。

次のコマンドを実行し、プロンプトに従います。

npx winapp init .

プロンプトが表示されたら、次を実行します。

• パッケージ名: Enter キーを押して既定値をそのまま使用します (my-windows-app)
• Publisher名: Enter キーを押して既定値をそのまま使用するか、名前を入力します
• バージョン: Enter キーを押して 1.0.0.0 を受け入れる
• エントリ ポイント: Enter キーを押して既定値 (my-windows-app.exe) をそのまま使用します。
• SDK のセットアップ: [安定した SDK] を選択する
• JS/TypeScript バインドの追加: Enter キーを押して既定値 (はい) をそのまま使用して、Windows アプリ SDK API の JS バインドを生成します

winapp initは何をしますか?

このコマンドは、Windows 開発に必要なすべてのものを設定します。

1. 以下の内容を含む.winapp/フォルダーを作成します。

   • Windows SDK からのヘッダーとライブラリ
   • Windows アプリ SDK のヘッダーとライブラリ
   • 必要なバイナリを含む NuGet パッケージ

2. Package.appxmanifestを生成します- アプリ ID と MSIX パッケージ化に必要なアプリ マニフェスト

3. Assets/ フォルダーを作成する - アプリのアイコンとビジュアルアセットが含まれます

4. Creates winapp.yaml - SDK のバージョンとproject構成を追跡します

5. Windows アプリ SDK ランタイムのインストール - 最新の API に必要なランタイム コンポーネント

6. Windows - アプリケーションのデバッグに必要

7. JS バインディングを生成する - オプトインすると、次のようになります。

   • package.json に winapp.jsBindings ブロックを書き込みます。
   • @microsoft/dynwinrt-codegenにdevDependenciesを追加します。バインドを生成するビルド時ツール (初回実行時にレジストリのlatest バージョンにピン留めされ、その後は単独で)
   • @microsoft/dynwinrtにdependenciesを追加します。生成されたバインディングが実行時にインポートするランタイム (ABI の互換性を保証するために、インストールされている codegen によってバージョンが選択されます)
   • WINDOWS APP SDK API の JS バインドを生成します。.winapp/bindings/

Package.appxmanifestを開いて、表示名、発行元、機能などのプロパティをさらにカスタマイズできます。

手順 4: ビルド パイプラインに復元を追加する

他の開発者がプロジェクトを複製するとき、または CI/CD パイプラインでWindows SDK を使用できるようにするには、postinstall スクリプトを package.json に追加します。

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

このスクリプトは、 npm install 後に自動的に実行され、次の 2 つの処理を実行します。

1. winapp restore - Windows SDK パッケージをすべて .winapp/ フォルダーにダウンロードして復元します
2. winapp node add-electron-debug-identity - Electron アプリをデバッグ ID に登録します (詳細については、次の手順で説明します)。

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

次に、npm install を実行して、ポストインストール スクリプトをトリガーし、Windows環境を構成します。

npm install

if (process.platform === 'win32') {
  const { execSync } = require('child_process');
  const fs = require('fs');
  const path = require('path');

  // Electron 42+ ships an `install-electron` bin and skips the postinstall download.
  // Run it only when present, and use `--no-install` so npx never silently fetches
  // anything from the registry.
  const installElectronBin = path.join(
    'node_modules', '.bin',
    process.platform === 'win32' ? 'install-electron.cmd' : 'install-electron'
  );
  const steps = [];
  if (fs.existsSync(installElectronBin)) {
    steps.push('npx --no-install install-electron');
  }
  steps.push(
    'npx winapp restore',
    'npx winapp cert generate --if-exists skip',
    'npx winapp node add-electron-debug-identity'
  );

  try {
    execSync(steps.join(' && '), { 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"
  }
}

手順 5: デバッグ ID について

手順 4 で実行した npm install によって、 postinstall スクリプトがトリガーされ、 winapp node add-electron-debug-identityが実行されました。 これにより、アプリに一時的なデバッグ ID が提供されるため、開発中にアプリ ID を必要とする API Windowsテストできます。

デバッグ ID は何をしますか？

このコマンド:

1. Package.appxmanifestを読み取り、アプリの詳細と機能を取得します
2. electron.exe内でnode_modulesを一時的な ID で登録します
3. 完全な MSIX パッケージを作成せずに、ID が必要な API をテストできます

デバッグ ID は、手順 4 で npm install を実行したときに自動的に適用されました。 今後、誰かが npm install実行するたびに再適用されます。

デバッグ ID を手動で更新するタイミング

Package.appxmanifest (機能、ID、プロパティの変更) またはリンクされた資産 (アイコン、mcp.jsonなど) を変更するたびに、このコマンドを手動で実行する必要があります。

npx winapp node add-electron-debug-identity

セットアップのテスト

デバッグ ID を適用して Electron アプリをテストできるようになりました。

npm start

デスクトップ アプリケーション ウィンドウ (ブラウザー タブではなく) が開いていることがわかります。これは、Electron アプリの実行方法です。

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

npx winapp node clear-electron-debug-identity

次のステップ

開発環境が設定されたので、ネイティブ コードが必要なときに、JavaScript から Windows API を呼び出すか、ネイティブ アドオンを作成する準備ができました。

• JavaScript から Windows API を呼び出す - JS バインディングを使用して Windows アプリ SDK API を呼び出し、それを介して Windows SDK API で拡張するwinapp.jsBindings
• JavaScript からの通知の表示 - JS バインドを使用してネイティブ アドオンなしでWindows アプリ SDK通知を表示する
• JavaScript から Phi Silica を呼び出す - JS バインドを使用してローカル言語モデルでテキストを集計する
• JavaScript からの WinML の実行 - ONNX 推論の onnxruntime-node で JS バインドを使用する
• Phi Silica アドオンの作成 - Phi Silica AI API を呼び出す C# アドオンを作成する方法について説明します
• WinML アドオンの作成 - Windows Machine Learningを使用する C# アドオンを作成する方法について説明します
• 配布用パッケージ - 配布用 の MSIX パッケージを作成する

または、 概要に戻ります。