ECO2/claudedocs/WebView2_Deployment_Guide.md

WebView2 Fixed Version 배포 가이드

개요

ECO2 프로그램은 WebView2 Fixed Version 방식을 사용하여 오프라인 환경에서도 매뉴얼 뷰어를 사용할 수 있습니다.

Fixed Version 다운로드

1. 다운로드 위치

https://developer.microsoft.com/microsoft-edge/webview2/#download-section

"Fixed Version" 섹션에서 다운로드합니다.

2. 버전 선택

• 플랫폼: x86 (32-bit) - ECO2는 x86 타겟입니다
• 추천 버전: 최신 Stable 버전
• 파일 크기: 약 100-150MB

3. 다운로드 파일 예시

• Microsoft.WebView2.FixedVersionRuntime.{version}.x86.cab
• 또는 압축 해제된 폴더 형태

배포 방법

1. 폴더 구조

{프로그램 설치 폴더}/
├── ECO2_2025V1.exe
├── WebView2Runtime/          ← Fixed Version 런타임 폴더
│   ├── msedge.exe
│   ├── msedgewebview2.exe
│   └── [기타 WebView2 파일들]
└── WebView2Data/             ← 사용자 데이터 폴더 (자동 생성됨)
    └── [캐시, 쿠키 등]

2. 설치 단계

방법 1: 수동 배포 (개발/테스트)

1. Fixed Version CAB 파일 또는 폴더 다운로드
2. CAB 파일인 경우 압축 해제
3. 압축 해제된 내용을 WebView2Runtime 폴더로 복사
4. WebView2Runtime 폴더를 프로그램 실행 파일과 같은 위치에 배치

방법 2: 설치 프로그램 포함 (프로덕션)

Setup1 프로젝트에 WebView2Runtime 폴더를 포함:

1. Setup1.vdproj 열기
2. WebView2Runtime 폴더를 프로젝트에 추가
3. 설치 시 Application Folder에 복사되도록 설정

동작 방식

런타임 검색 순서

1. Fixed Version 우선: {실행폴더}\WebView2Runtime 폴더 검색
2. 시스템 런타임 폴백: 시스템에 설치된 WebView2 Runtime 사용
3. 없을 경우: 매뉴얼 기능 사용 시 오류 메시지 표시

프로그램 시작 시 검사

• MdiMain 로드 시 CheckWebView2Runtime() 메서드가 Fixed Version 존재 여부 확인
• Debug.WriteLine으로 경고 출력 (사용자에게는 미표시)
• 실제 사용 시점(매뉴얼 열기)에만 오류 표시

오프라인 환경

• Fixed Version이 배포되어 있으면 인터넷 연결 불필요
• 모든 런타임 파일이 로컬에 포함되어 있음
• 폐쇄망 환경에서도 정상 작동

버전 업데이트

Fixed Version 업데이트 방법

1. 새 Fixed Version 다운로드
2. 기존 WebView2Runtime 폴더 백업 (선택사항)
3. 새 버전으로 WebView2Runtime 폴더 교체
4. 프로그램 재시작

주의사항

• WebView2Runtime 폴더는 약 100-150MB이므로 Git에 커밋하지 않음
• .gitignore에 이미 추가되어 있음
• 설치 프로그램에는 반드시 포함해야 함

테스트 방법

1. Fixed Version 테스트

1. WebView2Runtime 폴더가 있는 상태에서 프로그램 실행
2. "Manual" 메뉴 클릭
3. http://localhost:58123/ 페이지가 정상적으로 로드되는지 확인

2. 폴백(Fallback) 테스트

1. WebView2Runtime 폴더 임시 이름 변경 (예: WebView2Runtime_backup)
2. 프로그램 실행 (시스템 런타임 사용 시도)
3. "Manual" 메뉴 클릭
4. 시스템에 런타임이 있으면 정상 작동, 없으면 오류 메시지

3. 오프라인 테스트

1. 네트워크 연결 끊기
2. Fixed Version 배포된 상태에서 프로그램 실행
3. 매뉴얼 기능이 정상 작동하는지 확인

문제 해결

"WebView2 구성 요소를 찾을 수 없습니다" 오류

원인: Fixed Version도 없고 시스템 런타임도 설치되지 않음

해결:

1. WebView2Runtime 폴더가 실행 파일과 같은 위치에 있는지 확인
2. WebView2Runtime 폴더 내에 msedgewebview2.exe 파일이 있는지 확인
3. 또는 시스템에 WebView2 Runtime 설치: https://go.microsoft.com/fwlink/p/?LinkId=2124703

페이지 로딩 실패

원인: 로컬 웹서버(http://localhost:58123/)가 실행되지 않음

해결:

1. 로컬 웹서버가 실행 중인지 확인
2. 포트 58123이 열려 있는지 확인
3. Frm_WebManual.vb의 Navigate URL 수정 필요 시 수정

WebView2Data 폴더 문제

원인: 캐시 또는 쿠키 문제

해결:

1. 프로그램 종료
2. WebView2Data 폴더 삭제
3. 프로그램 재시작 (자동으로 새 폴더 생성됨)

참고 자료

• WebView2 공식 문서: https://learn.microsoft.com/microsoft-edge/webview2/
• Fixed Version 배포 가이드: https://learn.microsoft.com/microsoft-edge/webview2/concepts/distribution
• WebView2 다운로드: https://developer.microsoft.com/microsoft-edge/webview2/