개발 환경 설정

이 가이드에서는 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 Forge를 사용하는 새로운 Electron 앱부터 시작하겠습니다. 기존 앱에서 시작하는 경우 이 단계를 건너뛸 수 있습니다.

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

Electron Forge에서 메시지가 표시되면 다음을 수행합니다.

• 번들러: 없음 선택(권장 - 추가 구성 없이 네이티브 추가 기능 작동)
• 언어: JavaScript 선택(이 가이드에서는 JS 사용; TypeScript도 작동합니다.
• 전자 버전: 최신 선택
• 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" 선택

무엇을 합니까 winapp init ?

이 명령은 Windows 개발에 필요한 모든 항목을 설정합니다.

1. 다음을 포함하는 폴더를 만듭니다.winapp/.

   • Windows SDK의 헤더 및 라이브러리
   • Windows 앱 SDK의 헤더 및 라이브러리
   • 필요한 이진 파일이 있는 NuGet 패키지

2. 생성 Package.appxmanifest - 앱 ID 및 MSIX 패키징에 필요한 앱 매니페스트

3. 폴더 만들기 Assets/ - 앱에 대한 앱 아이콘 및 시각적 자산 포함

4. 생성winapp.yaml - SDK 버전 및 프로젝트 구성 추적

5. Windows 앱 SDK 런타임 설치 - 최신 API를 위한 필수 런타임 구성 요소

6. Windows 개발자 모드 활성화 - 애플리케이션 디버깅에 필요

열 Package.appxmanifest는 표시 이름, 게시자 및 기능과 같은 속성을 추가로 사용자 지정하는 데 사용할 수 있습니다.

4단계: 빌드 파이프라인에 복원 추가

다른 개발자가 프로젝트를 복제하거나 CI/CD 파이프라인에서 Windows SDK를 사용할 수 있도록 하려면 postinstallpackage.json 스크립트를 추가합니다.

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

이 스크립트는 다음 두 가지 작업을 수행한 후 npm install 자동으로 실행됩니다.

1. winapp restore - 모든 Windows SDK 패키지를 다운로드하여 .winapp/ 폴더로 복원합니다.
2. winapp node add-electron-debug-identity - 디버그 ID를 사용하여 Electron 앱을 등록합니다(다음 단계에서 자세히 설명).

이제 npm install 실행하여 사후 설치 스크립트를 트리거하고 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"
  }
}

5단계: 디버그 ID 이해

npm install을 4단계에서 실행하여 postinstall 스크립트를 트리거했고, 이 스크립트가 winapp node add-electron-debug-identity를 실행했습니다. 이렇게 하면 앱에 임시 디버그 ID가 제공되므로 개발 중에 앱 ID가 필요한 Windows API를 테스트할 수 있습니다.

디버그 ID는 무엇을 합니까?

이 명령은 다음과 같습니다.

1. Package.appxmanifest 앱 세부 정보 및 기능을 가져오기 위해 읽습니다.
2. electron.exe를 임시 ID를 사용하여 node_modules에 등록합니다.
3. 전체 MSIX 패키지를 만들지 않고 ID 필수 API를 테스트할 수 있습니다.

디버그 ID는 4단계에서 실행 npm install 했을 때 자동으로 적용되었습니다. 앞으로는 누구나 실행할 npm install때마다 다시 적용됩니다.

디버그 ID를 수동으로 업데이트하는 경우

수정(기능, ID 또는 속성 변경) 또는 연결된 자산(아이콘, mcp.json등)을 수정 Package.appxmanifest 할 때마다 이 명령을 수동으로 실행해야 합니다.

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

다음 단계

이제 개발 환경이 설정되었으므로 네이티브 추가 기능을 만들고 Windows API를 호출할 준비가 되었습니다.

• Phi Silica Addon 만들기 - Phi Silica AI API를 호출하는 C# 추가 기능을 만드는 방법 알아보기
• WinML 추가 기능 만들기 - Windows Machine Learning 사용하는 C# 추가 기능을 만드는 방법을 알아봅니다.
• 배포용 패키징 - 배포를 위한 MSIX 패키지 만들기

또는 시작 개요로 돌아갑니다.