Doconut 뷰어는 PDF, Office, CAD, 이미지 및 기타 지원되는 문서군을 애플리케이션 내부에 배치하도록 설계된 .NET 문서 보기 라이브러리입니다. 건전한 Doconut 통합은 가장 짧은 코드를 찾는 것이 아니라 애플리케이션, 뷰어, 브라우저 사이에 깔끔한 경계를 선택하는 데 중점을 둡니다.

Doconut 문서 허브는 지원되는 .NET 프로젝트 유형에 대한 유지 관리된 설정 경로를 연결합니다. 애플리케이션에 설치된 버전에 맞는 가이드를 사용하고, 주변 페이지, 신원 확인 및 접근 워크플로를 팀이 소유하는 애플리케이션 코드로 취급하세요.

통합 경계부터 시작하기

문서 미리보기를 제품에 배치하는 일반적인 방법은 세 가지가 있습니다. 올바른 선택은 누가 탐색, 인증 및 뷰어 수명 주기를 소유하느냐에 따라 달라집니다.

패턴	가장 적합한 경우	주요 트레이드오프
Application view	제품 컨트롤 옆에 뷰어를 렌더링하는 .NET 페이지	통합이 긴밀하지만 페이지와 뷰어 수명 주기가 결합됨
Application-owned iframe	호스트 UI와 미리보기 라우트 사이에 격리가 필요한 포털	경계가 명확하지만 통신을 명시적으로 설계해야 함
Framework component around a server route	.NET 애플리케이션을 백엔드로 하는 React, Angular, Vue 셸	친숙한 프런트엔드 구성, 관리해야 할 수명 주기 상태가 더 많음

iframe 패턴은 공개 문서 URL을 가리킬 필요가 없습니다. 자체 애플리케이션의 인증된 라우트를 가리킬 수 있으며, 해당 라우트는 접근을 검증하고 저장 경로를 호스트 페이지에 노출하지 않고 뷰어 페이지를 렌더링합니다.

안정적이고 반응형인 미리보기 표면 만들기

예시 블로그 스니펫을 따라 뷰어 마크업이나 초기화를 재구성하지 마세요. Doconut은 각 지원 .NET 라인에 맞는 파일, 미들웨어 단계, 네임스페이스 및 뷰어 설정을 제공합니다. 예를 들어, 공식 .NET 6 이상 설정 가이드에서는 서버 미들웨어, 뷰어 객체, 문서 옵션, 렌더링 구성 및 필요한 클라이언트 자산을 설명합니다.

버전별 자료를 사용해 뷰어를 생성하고, 자체 레이아웃에서 호스트 영역에 안정적인 너비와 높이를 지정하세요. 로드 전에 충분한 공간을 확보해 주변 페이지가 점프하지 않도록 하고, 제품이 지원하는 실제 브레이크포인트에서 툴바와 첫 페이지를 테스트하십시오.

구성을 확정하기 전에 공식 Doconut 라이브 데모와 비교해 보세요. 데모는 여러 .NET 및 프런트엔드 통합 스타일을 다루며, 전용 iframe 예시도 포함하고 있어 공식 지원 경로와 보기 좋은 스니펫을 구분하는 데 도움이 됩니다.

접근 결정은 서버에서 수행하기

호스트 페이지가 사용자가 문서를 볼 수 있는지를 판단해서는 안 됩니다. 미리보기 라우트를 렌더링하기 전에 애플리케이션은 다음을 수행해야 합니다:

요청을 인증한다.
요청된 문서와 테넌트에 대해 사용자를 권한 부여한다.
서버가 제어하는 식별자를 통해 문서를 해결한다.
해당 검증이 통과된 후에만 뷰어를 통해 연다.
저장소 세부 정보를 누출하지 않고 일반적인 not-found 또는 forbidden 상태를 반환한다.

불투명 식별자는 URL 위생을 개선하지만 권한 부여는 아닙니다. 페이지, 썸네일, 검색, 주석, 내보내기 및 인쇄 요청에도 동일한 검증을 적용하십시오.

호스트와 뷰어 간 통신 방식 결정하기

Application view는 자체 컴포넌트를 직접 호출할 수 있습니다. iframe은 더 좁은 계약이 필요합니다. 호스트가 실제로 필요로 하는 이벤트만 정의하세요, 예를 들어:

미리보기 준비 완료
문서 열기 실패
현재 페이지 변경
세션 만료
사용자가 미리보기를 닫으려 함

postMessage를 사용할 경우 event.origin과 메시지 형태를 모두 검증하십시오. 프로덕션에서는 와일드카드 오리진을 허용하지 말고, 자격 증명, 저장소 위치 또는 원시 문서 내용을 메시지를 통해 절대 전달하지 마세요.

브라우저 제한을 방어 깊이로 활용하기

iframe이 자동으로 격리되는 것은 아닙니다. sandbox 속성은 기능을 제한할 수 있지만, 과도하게 엄격한 값은 뷰어 스크립트, 다운로드 또는 동일 출처 동작을 깨뜨릴 수 있습니다. 통합에 대해 문서화된 최소 기능 집합부터 시작하고, Content Security Policy와 함께 테스트하세요.

또한 다음을 검토하십시오:

미리보기 라우트에 대한 frame-ancestors 또는 X-Frame-Options
호스트 페이지에 대한 frame-src
iframe에 세션이 필요한 경우 Same-site 쿠키 동작
라우팅 식별자를 포함하는 URL에 대한 Referrer 정책
민감한 자료를 표시하는 페이지에 대한 Cache 헤더

이러한 제어는 주변 애플리케이션 및 인프라에 속합니다. 뷰어 컴포넌트가 테넌시와 위협 모델에 맞는 정책을 스스로 선택할 수 없습니다.

로딩, 오류 및 만료 상태 설계하기

빈 사각형은 유용한 오류 메시지가 아닙니다. 호스트 페이지에 권한 실패, 지원되지 않는 입력, 손상된 파일, 타임아웃 및 세션 만료에 대한 명시적 상태를 제공하십시오. 내부 경로나 예외 세부 정보를 노출하지 않으면서도 실행 가능한 문구를 유지하세요.

긴 문서의 경우 첫 페이지가 준비되는 동안 뷰어 컨테이너를 유지하십시오. 사용자가 페이지를 떠나지 않고 문서를 전환할 수 있다면, 오래된 요청을 취소하고 다음 항목을 로드하기 전에 표시 제목, 페이지 수 및 포커스를 재설정하세요.

접근성 및 키보드 동작

각 iframe에 유용한 title을 부여하십시오. 키보드로 미리보기에 접근할 수 있게 하고, 호스트 페이지로 포커스를 반환할 수 있는 눈에 보이는 방법을 제공하며, 커스텀 오버레이 안에 포커스가 갇히지 않도록 하세요. 뷰어가 자체 키보드 단축키를 가지고 있다면, 제품 셸에서 사용하는 단축키와 충돌이 없도록 문서화하십시오.

접근 가능한 폴백은 비즈니스 규칙이 허용하는 경우 제어된 다운로드 또는 대체 표현을 제공할 수 있습니다. 단순히 공개 파일 링크를 폴백으로 추가하지 마세요.

실용적인 검증 체크리스트

릴리스 전에 초기 페이지 로드만이 아니라 전체 요청 경로를 검증하십시오:

권한이 부여된 사용자는 허용된 문서를 열 수 있다.
다른 테넌트 사용자는 미리보기 URL을 재사용할 수 없다.
뷰어 관련 엔드포인트에 대한 직접 요청도 동일한 권한 검증을 받는다.
새로 고침, 뒤로 가기 탐색 및 세션 만료 시 이해 가능한 상태를 제공한다.
미리보기가 지원되는 뷰포트 크기와 줌 레벨에서 사용 가능하다.
브라우저 콘솔 오류와 실패한 네트워크 요청이 모니터링에 표시된다.
저장소 및 애플리케이션 로그에 비밀이나 전체 문서 URL이 기록되지 않는다.

결론

가장 유지보수가 쉬운 Doconut 임베드는 작고 명시적인 계약을 가진 경우입니다. Doconut이 버전별 문서에 설명된 문서 보기 역할을 담당하도록 하고, 애플리케이션이 신원 확인, 권한 부여, 라우팅, 보존, 브라우저 정책 및 사용자 피드백을 소유하도록 하세요. 로컬에서 패키지 예제를 평가할 준비가 되면, 관련 없는 기사에서 소스를 복사하기보다 공식 Doconut 다운로드 리소스를 사용하십시오.