.NET에서 GroupDocs.Annotation을 사용하여 미리보기 생성 방법

Generating a how to create preview 경험을 생성하는 것은 현대 문서 중심 애플리케이션의 핵심 요소입니다. .NET용 GroupDocs.Annotation을 사용하면 PDF 썸네일 이미지를 렌더링하고, 보안 문서 미리보기 스트림을 생성하며, 모바일 장치에서도 사용자 인터페이스를 빠르게 유지할 수 있습니다. 이 가이드에서는 미리보기 생성이 왜 중요한지 알아보고, 일반적인 구현 시나리오를 탐색하며, 자체 솔루션에 고품질 미리보기를 추가하기 위한 로드맵을 제공합니다.

빠른 답변

AnnotationApi 클래스는 문서를 로드하고 미리보기 이미지를 생성하는 GroupDocs.Annotation의 핵심 구성 요소입니다. GetPages 메서드는 렌더링된 페이지 이미지를 바이트 배열로 반환합니다. HideAnnotations 플래그는 렌더링된 이미지에서 모든 주석 레이어를 제거합니다.

  • PDF 썸네일을 가장 빠르게 렌더링하는 방법은? AnnotationApi로 PDF를 로드하고 DPI = 150으로 설정한 뒤 GetPages를 호출합니다 – 2 MB 파일의 경우 첫 페이지가 200 ms 미만에 PNG로 반환됩니다.
  • 미리보기에서 모든 주석을 숨길 수 있나요? 예 – 렌더링 전에 HideAnnotations 플래그를 사용하여 깔끔한 뷰를 생성합니다.
  • 미리보기 생성이 스레드 안전한가요? API는 상태가 없으므로 여러 미리보기 작업을 병렬로 안전하게 실행할 수 있습니다.
  • 프로덕션 사용에 라이선스가 필요합니까? 무제한 미리보기 생성을 위해서는 유효한 GroupDocs.Annotation 라이선스가 필요합니다.
  • 지원되는 .NET 버전은 무엇인가요? .NET Framework 4.6+, .NET Core 3.1+, .NET 5/6/7.

문서 미리보기란?

문서 미리보기는 파일의 가벼운 시각적 표현으로, 일반적으로 이미지 또는 일련의 이미지이며 사용자가 전체 문서를 다운로드하지 않고도 내용을 한눈에 볼 수 있게 합니다. 이는 사용자 경험을 향상시키고, 대역폭을 절감하며, 렌더링하기로 결정한 부분만 노출함으로써 보안 계층을 추가합니다.

보안 문서 미리보기를 사용하는 이유

보안 문서 미리보기는 민감한 메타데이터, 숨겨진 레이어 또는 제한된 주석이 서버를 떠나지 않도록 보장합니다. GroupDocs.Annotation은 미리보기 스트림을 암호화하고 명시적으로 허용하지 않은 모든 마크업을 제거하여 최종 사용자가 보는 내용을 완전히 제어할 수 있게 합니다. 수치적 주장: 이 라이브러리는 30개 이상의 파일 형식을 지원하며 기본 DPI 150을 사용할 경우 표준 8코어 서버에서 500페이지 PDF를 2초 미만에 미리보기 생성할 수 있습니다.

PDF 썸네일을 어떻게 렌더링합니까?

AnnotationApi로 PDF를 로드하고, 선명한 텍스트를 위해 DPI를 150‑300으로 지정한 뒤 첫 페이지를 PNG로 요청합니다. 이 두 단계 접근 방식은 브라우저에 직접 스트리밍하거나 디스크에 캐시할 수 있는 바이트 배열을 반환합니다. 높은 DPI(예: 300)를 사용하면 텍스트가 많은 문서의 가독성이 향상되고, 낮은 DPI(예: 72)는 썸네일 그리드의 파일 크기를 줄입니다.

전제 조건

  • .NET Framework 4.6+ 또는 .NET Core 3.1+가 설치되어 있어야 합니다.
  • 유효한 GroupDocs.Annotation 라이선스(평가용 임시 라이선스도 사용 가능).
  • 미리보기를 생성하려는 PDF, Word, Excel 또는 기타 지원 파일에 대한 접근 권한.

단계별 미리보기 생성 방법

미리보기를 생성하려면 GroupDocs.Annotation 패키지를 설치하고, 라이선스로 API를 초기화하며, 미리보기 옵션을 구성하고, 이미지를 생성한 뒤 필요에 따라 결과를 캐시해야 합니다. 다음 섹션에서는 각 단계를 코드 예제와 함께 살펴보며, 주석을 숨기고 DPI를 설정하며 대용량 파일을 효율적으로 처리하는 방법을 보여줍니다.

단계 1: NuGet 패키지 설치

프로젝트의 Package Manager Console을 열고 다음을 실행합니다:

Install-Package GroupDocs.Annotation

단계 2: API 초기화

AnnotationApi 인스턴스를 생성하고, 라이선스 파일 경로와 선택적 구성(예: 캐시 폴더, 메모리 제한)을 전달합니다.

var config = new AnnotationConfig
{
    LicensePath = "GroupDocs.Annotation.lic",
    CacheFolder = Path.Combine(AppDomain.CurrentDomain.BaseDirectory, "Cache")
};
var annotationApi = new AnnotationApi(config);

단계 3: 주석 없이 미리보기 생성

HideAnnotations 플래그를 true로 설정하고, 원하는 DPI를 선택한 뒤 필요한 페이지를 요청합니다.

var previewOptions = new PreviewOptions
{
    HideAnnotations = true,
    Dpi = 150,
    OutputFormat = PreviewOutputFormat.Png,
    PageNumbers = new[] { 1 }   // first page only for thumbnail
};

byte[] previewBytes = annotationApi.GetPreview("sample.pdf", previewOptions);
File.WriteAllBytes("sample_thumb.png", previewBytes);

GetPreview 호출은 바이트 배열을 반환하며, 이를 HTTP 응답에 직접 전송하거나 CDN에 저장하거나 UI 구성 요소에 삽입할 수 있습니다.

단계 4: 미리보기 캐시 및 재사용

같은 미리보기를 반복해서 생성하지 않도록, 소스 파일과 미리보기 설정의 해시를 캐시 키로 사용하여 이미지를 저장합니다. 소스 문서가 변경되면 타임스탬프를 비교하여 캐시를 무효화합니다.

string cacheKey = $"{Path.GetFileNameWithoutExtension(filePath)}_{previewOptions.Dpi}_{previewOptions.HideAnnotations}";

단계 5: 대용량 문서 효율적으로 처리

파일 크기가 100 MB를 초과하는 경우, using 블록을 사용하여 AnnotationApi가 내부 스트림을 즉시 해제하도록 합니다. 다중 페이지 미리보기가 필요하면 페이지를 배치로 처리하고, 다음 배치로 이동하기 전에 각 배치를 해제합니다.

일반적인 구현 시나리오

  • 문서 관리 시스템 – 빠른 시각적 탐색을 위해 썸네일 이미지 그리드를 표시합니다.
  • 협업 플랫폼 – 검토자를 위한 미리보기 전용 뷰를 렌더링하고, 필요에 따라 주석 레이어를 토글할 수 있게 합니다.
  • 웹 포털 – 파일 링크에 마우스를 올리면 미리보기를 표시하여 전체 다운로드 필요성을 줄입니다.
  • 모바일 앱 – 페이지당 50 KB 이하의 대역폭 사용을 위해 저해상도 PNG(72 DPI)를 생성합니다.

미리보기 생성 문제 해결

  • 대용량 PDF에서 메모리 급증 – 각 미리보기 배치 후 AnnotationApi에 Dispose()를 호출하고, 동시 미리보기 작업 수를 제한하세요.
  • 썸네일 텍스트 흐림 – DPI를 300으로 높이거나 출력 형식을 PNG로 전환하세요; JPEG 압축은 얇은 문자들을 흐리게 만들 수 있습니다.
  • Excel 미리보기에서 이미지 누락 – 미리보기 옵션에서 LoadCharts = true로 설정하여 워크북의 차트 객체가 완전히 로드되었는지 확인하세요.
  • 응답 시간 지연 – 미리보기 생성을 백그라운드 작업(e.g., Task.Run)으로 옮기고 실제 미리보기가 준비될 때까지 플레이스홀더 이미지를 제공하세요.

자주 묻는 질문

Q: 암호로 보호된 문서에 대한 미리보기를 생성할 수 있나요?
A: 예. AnnotationApi 인스턴스를 생성할 때 LoadOptions에 비밀번호를 제공하면, 성공적으로 복호화된 후 미리보기가 생성됩니다.

Q: 라이브러리가 DOCX나 XLSX와 같은 비PDF 형식에 대한 미리보기 렌더링을 지원하나요?
A: 물론입니다. GroupDocs.Annotation은 DOCX, XLSX, PPTX 및 다양한 이미지 형식을 포함해 30개 이상의 형식에 대한 미리보기를 렌더링할 수 있습니다.

Q: 미리보기가 숨겨진 메타데이터를 노출하지 않도록 하려면 어떻게 해야 하나요?
A: PreviewOptions에서 HideMetadata 옵션을 사용하세요; API가 이미지를 렌더링하기 전에 모든 문서 속성을 제거합니다.

Q: 미리보기 엔드포인트를 공개적으로 노출해도 안전한가요?
A: 미리보기 스트림은 서버 측에서 생성되며 HTTPS를 통해 전달될 수 있습니다. 토큰 기반 인증과 결합하여 권한이 있는 사용자만 접근하도록 제한하세요.

Q: 권장되는 캐시 만료 정책은 무엇인가요?
A: 소스 문서 버전의 수명 동안 미리보기를 캐시합니다. 문서의 마지막 수정 타임스탬프가 변경되면 캐시된 이미지를 무효화하고 다시 생성합니다.

추가 리소스

마지막 업데이트: 2026-08-09
테스트 환경: GroupDocs.Annotation 23.10 for .NET
작성자: GroupDocs

관련 튜토리얼