Tauri와 함께 winapp CLI 사용

이 가이드에서는 Tauri 애플리케이션에서 CLI를 사용하여 winapp 패키지 ID로 디버그하고 애플리케이션을 MSIX로 패키지하는 방법을 보여 줍니다.

패키지 ID는 Windows app 모델의 핵심 개념입니다. 이를 통해 애플리케이션은 알림, 보안, AI API 등과 같은 특정 Windows API에 액세스하고, 깨끗한 설치/제거 환경 등을 사용할 수 있습니다.

전체 작업 예제를 보려면 이 리포지토리의 Tauri 샘플을 확인하세요.

필수 조건

  1. Windows 11
  2. Node.js - winget install OpenJS.NodeJS --source winget
  3. Rust 도구 체인 - rustup을 사용하거나 winget install Rustlang.Rustup --source winget로 Rust를 설치하세요.
  4. winapp CLI - winget install microsoft.winappcli --source winget

Tip

이미 설치되어 있는 경우 어쨌든 명령을 실행 winget install 하여 업데이트를 확인합니다.

1. 새 Tauri 앱 만들기

먼저 공식 스캐폴딩 도구를 사용하여 새 Tauri 애플리케이션을 만듭니다.

npm create tauri-app@latest

프롬프트를 따릅니다.

  • Project 이름: tauri-app(또는 원하는 이름)
  • 프런트 엔드 언어: JavaScript
  • 패키지 관리자: npm
  • UI 템플릿: Vanilla
  • UI 형태: JavaScript

project 디렉터리로 이동하여 종속성을 설치합니다.

cd tauri-app
npm install

앱을 실행하여 모든 것이 작동하는지 확인합니다.

npm run tauri dev

2. ID를 확인하도록 코드 업데이트

패키지 ID를 사용하여 실행되는지 확인하도록 앱을 업데이트합니다. Rust 백 엔드의 windows 상자를 사용하여 Windows API에 액세스하고 프런트 엔드에 노출합니다.

백엔드 변경 내용 (Rust)

  1. 종속성 추가: 파일 끝에 다음 줄을 열고 src-tauri/Cargo.toml 추가합니다. 그러면 패키지 ID를 확인할 수 있도록 Windows API 바인딩이 추가됩니다.

    [target.'cfg(windows)'.dependencies]
windows = { version = "0.58", features = ["ApplicationModel"] }

  2. 명령 추가: src-tauri/src/lib.rs을(를) 열고 get_package_family_name 함수를 추가합니다. pub fn run() 함수 앞에 배치하십시오.

    #[tauri::command]
fn get_package_family_name() -> String {
    #[cfg(target_os = "windows")]
    {
        use windows::ApplicationModel::Package;
        match Package::Current() {
            Ok(package) => {
                match package.Id() {
                    Ok(id) => match id.FamilyName() {
                        Ok(name) => name.to_string(),
                        Err(_) => "Error retrieving Family Name".to_string(),
                    },
                    Err(_) => "Error retrieving Package ID".to_string(),
                }
            }
            Err(_) => "No package identity".to_string(),
        }
    }
    #[cfg(not(target_os = "windows"))]
    {
        "Not running on Windows".to_string()
    }
}

  3. 명령 등록: 동일한 파일(src-tauri/src/lib.rs)에서 함수를 run 업데이트하여 새 명령을 등록합니다.

    pub fn run() {
    tauri::Builder::default()
        .plugin(tauri_plugin_opener::init())
        .invoke_handler(tauri::generate_handler![greet, get_package_family_name]) // Add get_package_family_name here
        .run(tauri::generate_context!())
        .expect("error while running tauri application");
}

프런트 엔드 변경 내용(JavaScript)

  1. HTML 업데이트: 결과를 표시하는 단락을 열고 src/index.html 추가합니다.

    <!-- ... inside <main> ... -->
<p id="pfn-msg"></p>

  2. 업데이트 논리: 명령을 호출하고 결과를 표시하기 위해 열기 src/main.js :

    const { invoke } = window.__TAURI__.core;

// ... existing code ...

async function checkPackageIdentity() {
  const pfn = await invoke("get_package_family_name");
  const pfnMsgEl = document.querySelector("#pfn-msg");

  if (pfn !== "No package identity" && !pfn.startsWith("Error")) {
    pfnMsgEl.textContent = `Package family name: ${pfn}`;
  } else {
    pfnMsgEl.textContent = `Not running with package identity`;
  }
}

window.addEventListener("DOMContentLoaded", () => {
  // ... existing code ...
  checkPackageIdentity();
});

  3. 이제 평소와 같이 앱을 실행합니다.

    npm run tauri dev

    앱 창에 "패키지 ID를 사용하여 실행되지 않음"이 표시됩니다. 그러면 패키지 ID 없이 표준 개발 빌드가 실행 중임을 확인합니다.

3. winapp CLI를 사용하여 Project 초기화

이 winapp init 명령은 앱 매니페스트 및 자산 등 필요한 모든 항목을 한 번으로 설정합니다. 매니페스트는 Windows API 액세스 권한을 부여하는 데 사용하는 앱의 ID(이름, 게시자, 버전)를 정의합니다.

다음 명령을 실행하고 프롬프트를 따릅니다.

winapp init

프롬프트가 표시되면

  • 패키지 이름: Enter 키를 눌러 기본값 적용(tauri-app)
  • Publisher 이름: Enter 키를 눌러 기본값을 적용하거나 이름을 입력합니다.
  • 버전: Enter 키를 눌러 1.0.0.0 허용
  • 진입점: Enter 키를 눌러 기본값(tauri-app.exe)을 적용합니다.
  • SDK 설정: "SDK 설정 안 함"을 선택합니다(Tauri는 C++ SDK 헤더가 아닌 Rust의 windows 상자를 사용합니다.)

이 명령은 다음을 수행합니다.

  • 만들기 Package.appxmanifest - 앱의 ID를 정의하는 매니페스트
  • 폴더 만들기 Assets - MSIX 패키징 및 스토어 제출에 필요한 아이콘

메모

SDK 패키지는 관리되지 않으므로 생성되지 않습니다winapp.yaml. Tauri는 Cargo를 통해 Rust의 windows 상자를 사용하므로 추적할 항목이 없습니다winapp restore/update.

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

4. ID를 사용하여 디버그

ID를 사용하여 디버그하려면 Rust 백 엔드를 빌드하고 실행해야 합니다 winapp run. npm run tauri dev 프로세스 수명 주기를 관리하므로 ID를 삽입하기가 더 어렵습니다. 대신 사용자 지정 스크립트를 만듭니다. 디버깅에 인증서 또는 서명이 필요하지 않습니다.

  1. 스크립트 추가: 새 스크립트 package.json열기 및 추가:tauri:dev:withidentity

    "scripts": {
  "tauri": "tauri",
  "tauri:dev:withidentity": "cargo build --manifest-path src-tauri/Cargo.toml && (if not exist dist mkdir dist) && copy /Y src-tauri\\target\\debug\\tauri-app.exe dist\\ >nul && winapp run .\\dist"
}

    이 스크립트가 수행하는 작업:

    • cargo build ...: Rust 백 엔드를 다시 컴파일합니다.
    • copy ... dist\\: exe 파일만 dist 폴더로 이동합니다(target\debug 폴더는 중간 빌드 아티팩트가 포함되어 있으며, 이는 앱의 일부가 아닙니다).
    • winapp run .\\dist: 실제 MSIX 설치와 마찬가지로 느슨한 레이아웃 패키지를 등록하고 앱을 시작합니다.

  2. 스크립트를 실행합니다.

    npm run tauri:dev:withidentity

Tip

앱 창 뒤에 터미널/콘솔 창이 나타날 수 있습니다. 이는 Tauri 디버그 빌드(Rust 프로세스의 콘솔)에 대해 정상입니다.

이제 앱이 열리고 "패키지 패밀리 이름"이 표시되면, 이는 앱이 ID를 가지고 실행되고 있음을 확인하는 것입니다. 이제 알림 또는 Phi Silica와 같은 새로운 AI API와 같은 패키지 ID가 필요한 API를 사용하고 디버깅할 수 있습니다.

Tip

winapp run 또한 시스템에 패키지를 등록합니다. 따라서 나중에 5단계에서 설치하려고 할 때 MSIX가 "이미 설치됨"으로 표시될 수 있습니다. 완료되면 개발 패키지를 정리하는 데 사용합니다 winapp unregister .

Tip

고급 디버깅 워크플로(디버거 연결, IDE 설정, 시작 디버깅)는 디버깅 가이드를 참조하세요.

5. MSIX를 사용하여 패키지

앱을 배포할 준비가 되면 애플리케이션에 패키지 ID를 제공하는 MSIX로 패키지할 수 있습니다.

먼저 package.json에 pack:msix 스크립트를 추가하십시오.

"scripts": {
  "tauri": "tauri",
  "tauri:dev:withidentity": "...",
  "pack:msix": "npm run tauri -- build && (if not exist dist mkdir dist) && copy /Y src-tauri\\target\\release\\tauri-app.exe dist\\ >nul && winapp pack .\\dist --cert .\\devcert.pfx"
}

이 스크립트가 수행하는 작업:

  • npm run tauri -- build: 릴리스 모드에서 Rust 백 엔드를 빌드합니다.
  • copy ... dist\\: exe 파일만 dist 폴더로 이동합니다(target\release 폴더는 중간 빌드 아티팩트가 포함되어 있으며, 이는 앱의 일부가 아닙니다).
  • winapp pack .\\dist --cert .\\devcert.pfx: 앱을 MSIX로 패키지하고 서명합니다.

개발 인증서 생성

MSIX 패키지에 서명해야 합니다. 로컬 테스트의 경우 자체 서명된 개발 인증서를 생성합니다.

winapp cert generate --if-exists skip

Tip

인증서의 발행자는 Package.appxmanifest에서 Publisher와 일치해야 합니다. 이 cert generate 명령은 매니페스트에서 자동으로 읽습니다.

빌드, 스테이지 및 패키지

npm run pack:msix

Tip

이 pack 명령은 현재 디렉터리의 Package.appxmanifest를 자동으로 사용하고 패키징하기 전에 대상 폴더에 복사합니다. 생성된 .msix 파일은 현재 디렉터리에 있습니다.

인증서 설치

MSIX 패키지를 설치하려면 컴퓨터에서 개발 인증서를 신뢰해야 합니다. 관리자 권한으로 이 명령을 실행합니다(인증서당 한 번만 수행하면 됨).

winapp cert install .\devcert.pfx

설치 및 실행

Tip

4단계에서 사용한 winapp run 경우 패키지가 시스템에 이미 등록되어 있을 수 있습니다. winapp unregister 먼저 개발 등록을 제거한 다음 릴리스 패키지를 설치합니다.

생성된 .msix 파일을 두 번 클릭하거나 PowerShell을 사용하여 패키지를 설치합니다.

Add-AppxPackage .\tauri-app.msix

Tip

MSIX 파일 이름에는 버전 및 아키텍처(예: tauri-app_1.0.0.0_x64.msix)가 포함됩니다. 디렉터리에서 정확한 파일 이름을 확인합니다. 코드 변경 후 패키지를 다시 만들어야 하는 경우, Version 내부의 Package.appxmanifest를 증가시켜야 합니다. Windows에서는 설치된 패키지를 업데이트하기 위해 더 높은 버전 번호가 필요합니다.

설치되면 시작 메뉴에서 앱을 시작할 수 있습니다. 앱이 신원을 사용하여 실행되는 것을 볼 수 있습니다.

팁

  1. 배포할 준비가 되면 사용자가 자체 서명된 인증서를 설치할 필요가 없도록 인증 기관의 코드 서명 인증서로 MSIX에 서명할 수 있습니다.
  2. Microsoft Store 제출 전에 서명할 필요 없이 MSIX에 서명합니다.
  3. 지원하는 각 아키텍처(x64, Arm64)에 대해 하나씩 여러 MSIX 패키지를 만들어야 할 수 있습니다.

다음 단계

  • winget을 통한 배포: MSIX를 Windows 패키지 관리자 커뮤니티 리포지토리
  • Microsoft Store에 게시: winapp store를 사용하여 패키지를 제출하십시오.
  • CI/CD 설정: setup-WinAppCli GitHub 작업을 사용하여 파이프라인에서 패키징 자동화
  • Explore Windows API들: 패키지 ID로, 이제 알림, 기기 내 AI 및 기타 ID에 의존하는 API을 사용할 수 있습니다.
  • Last updated on