networkSetup/docs/code-design/11-generic-exe-msix-architecture.md

범용 설치 패키지 제작과 EXE·MSIX 출력

2026-10-19 실행 범위 변경: 이 문서의 “두 형식 모두 필수”는 장기 확장 구조다. 최신 사용자 요청에 따라 MSIX를 먼저 완성하고 EXE는 후속으로 이월한다. 두 형식 동시 완성을 첫 출시의 조건으로 사용하지 않는다. Store 제출 프로필도 후속이다. 현재 설계 참조.

결정일: 2026-10-19. 사용자 의도에 따라 제품 범위를 정정한다. 이 문서는 기존 문서의 EG-BIM 전용 가정과 MSIX 후속 검토 분류를 대체한다. 아직 구현·설치 시험을 완료한 것은 아니다.

제품과 배포의 경계

개발 대상은 여러 Windows 제품의 설치 프로젝트를 작성하고 EXE 또는 MSIX를 생성하는 범용 제작기다. 제작기는 두 형식을 모두 필수 지원하며, 각 프로젝트는 EXE만, MSIX만, 두 형식을 함께 선택할 수 있다. EG-BIM은 기존 InstallShield 전환을 검증하는 적용 사례다. 제품명·제조사·경로·실행 파일·레지스트리·런타임·서명자는 프로젝트 입력이며 엔진에 고정하지 않는다.

Microsoft Store는 생성된 파일을 등록하는 배포 대상이다. Store 계정이나 등록 없이도 EXE와 직접 배포용 MSIX를 만들 수 있어야 한다. Store 심사 통과와 특정 고객의 전환 완료는 범용 제작기의 패키지 생성 성공 조건이 아니다.

flowchart TD
    P[제품별 프로젝트와 원본 파일] --> C[Rust 공통 검증·스냅샷·출력 계획]
    C --> E[EXE 백엔드: WiX MSI + Burn]
    C --> M[MSIX 백엔드: Manifest + MakeAppx]
    E --> EA[EXE와 필요한 MSI/CAB/런타임]
    M --> MA[MSIX]
    EA --> D[직접 배포·네트워크 배포]
    MA --> D
    EA --> S[Store 제출용 내보내기·검사]
    MA --> S
    S --> R[별도 Store 등록·심사·공개]

축	설정과 책임
출력 형식 format	exe 또는 msix; 제작기 필수 지원
전달 구성 delivery	EXE: offline-singlefile, offline-layout, network; MSIX: package, appinstaller
배포 대상 distribution	direct 또는 store; 형식을 결정하지 않음
공개 정책	자체 서버 그룹 승인, Store 제출/공개 등 별도 운영 시스템의 책임

허용 조합은 EXE 직접 배포의 세 delivery, EXE Store의 offline-singlefile, MSIX 직접 배포의 package/appinstaller, MSIX Store의 package다. Store 대상의 network·offline-layout·appinstaller와 형식에 맞지 않는 조합은 계획 단계에서 차단한다.

network는 제3의 패키지 형식이 아니다. EXE는 원격 payload를 받는 부트스트래퍼, MSIX는 필요할 때 HTTPS 패키지를 참조하는 .appinstaller로 전달한다. .appinstaller는 설치 패키지 자체가 아닌 배포 설명 파일이다. Microsoft App Installer 개요

백엔드와 최초 지원 범위

공통 PackageBackend 포트는 capabilities, validate, plan, build, inspect 계약을 제공한다. WixBackend와 MsixBackend를 주입하고 서명·저장·작업 취소는 공통 서비스가 조정한다. 프로젝트 검증과 실제 출력 검사 모두 백엔드별 규칙을 사용한다. 도구 버전과 해시는 잠금 파일에 고정한다.

기능	EXE / WiX·Burn	MSIX
설치 위치	프로젝트 기본 경로와 허용된 사용자 선택	OS 관리; 임의 설치 폴더 입력 제공 안 함
최종 사용자 화면	표준 테마, 사용자 정의 BA, 설치 단계 편집	Windows/Store 설치 UI; manifest 표시명·아이콘 등 앱 메타데이터 편집
파일·설정	디렉터리·MSI 컴포넌트·명시적 레지스트리	패키지 내부 경로·지원 manifest 선언; 임의 HKLM 작업으로 변환하지 않음
런타임	번들에 포함하거나 검증된 원격 payload 사용	지원 프레임워크 의존성 또는 앱의 자체 포함 구성 검증
업데이트	MSI 기준 상태별 MSP, 검증된 전체 업그레이드	동일 계열의 버전 증가 MSIX; 직접 배포/App Installer 또는 Store
기존 설치 전환	명시적 탐지·백업·제거·복원 정책	별도 전환 계획; 기존 EXE 자동 제거를 가정하지 않음

MSIX 최초 범위는 패키징 가능한 일반 데스크톱 앱의 파일, 실행 항목, 로고, 최소 OS, 의존성, 허용 capability/extension 선언이다. 서비스·드라이버·임의 custom action·복잡한 CAD/COM 연동은 초기 지원 목록 밖으로 두고 지원되지 않는 설정을 빌드 전에 차단한다. 이는 모든 MSIX가 해당 기능을 원천 지원하지 않는다는 뜻이 아니다. 앱별 호환성을 검토하고 검증된 매핑을 추가한다. MSIX 준비 사항

MSIX는 완성된 설치 EXE를 확장자만 바꿔 만드는 결과물이 아니다. 제품 payload와 선언적 설정에서 각 형식을 생성한다. 기존 설치기를 실행해 변경을 캡처하는 자동 변환 기능은 별도 후속 범위다. 한 제품의 EXE 지원이 곧 그 제품의 MSIX 호환성을 의미하지 않는다.

프로젝트 v2 계약

공통 필드는 schemaVersion, product, sources, files, formats, targets다. 2026-10-27 결정으로 별도 프로젝트 ID를 제거했다. 제품 표시 버전은 공통으로 두되 실제 MSI/MSIX 버전은 형식별로 명시하고 검증한다. 설계용 예제는 두 형식과 배포 대상을 독립 선택하는 구조를 보여 준다.

• formats.exe: MSI 버전·UpgradeCode·설치 범위·기본 경로, 레지스트리, 런타임, MSP 정책, installationFlow, installerUi.
• formats.msix: Identity Name·Publisher·Version·Architecture, 애플리케이션 실행 경로·로고, 최소 OS, 의존성과 capabilities/extensions. MSI GUID나 Burn 페이지를 요구하지 않는다.
• targets[]: 안정적인 id, format, delivery, distribution, signingProfileRef, 필요 시 불변 payload URL 또는 Store identity 참조. 네트워크 URL·인증서·Store 이름이 미확정이면 해당 대상만 계획에서 차단한다.
• identity.lock.json: EXE의 MSI/Burn 계열과 MSIX의 패키지 계열을 분리한다. MSIX Publisher 변경을 MSI UpgradeCode 교체로 처리하지 않는다.
• ReleaseRecord.targets[]: 대상별 실제 식별자·산출물·서명 결과·검증 증빙·상태를 저장한다. MSI/MSP 필드는 해당 형식에만 존재한다.

v1 EG-BIM 예제는 이전 EXE 전용 설계 입력으로 보존한다. v1→v2 가져오기는 백업과 변경 보고서를 만들고 EXE 필드를 이동한다. MSIX publisher나 Store identity를 임의 생성하지 않으며 사용자 입력 전에는 MSIX 대상을 활성화하지 않는다. store-singlefile은 format=exe, delivery=offline-singlefile, distribution=store로 명시적으로 변환한다. 알 수 없는 필드/버전과 손실되는 변환은 오류다.

제품 릴리스 하나에 EXE·MSIX를 함께 요청하면 출력 계획에 두 대상이 고정된다. 한쪽 실패는 전체 성공으로 표시하지 않는다. 성공한 대상은 개별 보존할 수 있으나 전체 요청은 PartialFailed로 기록하고 통합 배포 준비 상태를 부여하지 않는다. 실패 대상 재시도는 새 buildId를 사용하며 이미 확정한 파일을 덮어쓰지 않는다.

생성·서명·내보내기

공통 검증 → 입력 스냅샷 → 대상별 호환성 검사 → 백엔드 빌드 → 대상 정책에 따른 서명/검증 → 최종 해시·불변 저장 순서다.

EXE는 기존 MSI/CAB/Burn 생성·서명 파이프라인을 사용한다. MSIX는 파일 매핑과 AppxManifest.xml 생성 → SDK manifest/자산 검사 → MakeAppx pack → 패키지 내용/identity 검사 → 대상별 서명 → 검증 순서다. MakeAppx의 검증을 우회해 성공 처리하지 않는다. .msix 생성이 최초 필수이며 다중 아키텍처 .msixbundle은 확장 범위다. MakeAppx만으로 .msixupload까지 생성된다고 가정하지 않는다. MakeAppx 공식 문서

직접 배포 MSIX는 대상 PC가 신뢰할 수 있는 인증서로 서명하고, manifest Publisher와 인증서 Subject 일치를 검증한다. 개발 인증서 결과와 일반 사용자 배포 준비 상태를 구분한다. 개인 키는 패키지에 포함하지 않는다. MSIX 인증서 요건

Store MSIX 출력은 Partner Center의 제품 identity에 맞춘 제출용 결과로 관리한다. Store의 배포 서명은 이후 단계이므로 서명되지 않은 제출 파일을 직접 설치 가능으로 표시하지 않는다. 직접 배포용 서명본과 제출용 파일은 대상별 해시로 구별한다. Store는 .msix 등의 패키지를 받으며 제출·심사·공개는 제작기 빌드 상태와 별도다. Store 업로드 형식

Store EXE 출력은 단일 완전 오프라인 설치 파일·무인 인자·서명·고정 HTTPS URL 등 제출 요건을 추가 검증한다. 직접 배포용 offline-layout이나 network 성공만으로 Store 준비 완료를 선언하지 않는다. Store EXE 패키지 요건

버전·업데이트·공존

MSI의 3부분 버전/GUID/MSP 정책은 EXE 백엔드 전용이다. MSIX는 4부분 숫자 버전을 검증한다. Store 대상은 첫 부분 0 금지와 마지막 부분 0 등 Store 버전 요건도 적용한다. 공통 표시 버전 문자열을 무검증으로 복사하지 않는다. Store MSIX 버전 규칙

MSIX 업데이트에 MSP를 생성하거나 설치 폴더에 자체 패치를 덮어쓰지 않는다. 버전 증가 패키지를 제공하고 Windows 배포 기능을 이용한다. 직접 배포의 App Installer 설정과 Store 관리 업데이트는 별도 정책이다. 재설치·제거·업데이트 실패와 앱 데이터 보존을 각각 VM에서 확인한다.

동일 제품의 EXE↔MSIX는 자동 상호 업그레이드가 아니다. 기본은 서로 독립된 설치로 취급하고 공존 허용 여부, 앱 데이터 소유권, 파일 연결, 실행 항목 충돌을 프로젝트에서 결정한다. 전환 기능을 제공하려면 기존 제품 탐지·백업·복원·실패 복구를 별도 검증한다. Publisher/Store identity 차이도 자동 통합하지 않는다.

제작 화면과 완료 기준

제작기는 공통 제품·파일 화면 뒤에 출력 대상 편집을 제공한다. EXE 탭에서는 설치 경로·레지스트리·과정/마법사·MSP를, MSIX 탭에서는 manifest·앱 자산·identity·capabilities·업데이트 정책을 편집한다. 출력 대상별 미지원 설정을 이유와 필드 위치로 표시하며 조용히 무시하지 않는다. MSIX 선택 화면에 EXE 설치 경로/마법사 편집을 그대로 노출하지 않는다.

최소 두 개의 독립된 가상 제품으로 이름·게시자·실행 파일·경로가 하드코딩되지 않았음을 검증한다. 각 제품에서 EXE와 MSIX 생성, 직접 설치, 실행, 업데이트, 제거, 데이터 보존을 시험한다. Store 계정·자체 배포 서버 없이 이 시험을 수행할 수 있어야 한다. 잘못된 Publisher·누락 런타임/자산·미지원 기능·한쪽 출력 실패도 검사한다. EG-BIM의 실제 전환과 Store 제출은 별도 적용 증빙으로 관리한다. 계정 없는 공통 시험에서는 가상 Store identity로 제출 규칙과 오류 처리를 검증한다. 실제 Partner Center identity가 확인되지 않은 출력은 StoreSubmissionReady로 표시하지 않는다.

구현은 BL-46~53, 일정은 단독 개발 기준선 v2, 변경 사유는 변경 기록을 따른다.