GroupDocs.Annotation kullanarak .NET’te önizleme oluşturma

Önizleme oluşturma deneyimi üretmek, modern belge‑odaklı uygulamaların temel taşlarından biridir. önizleme oluşturma ile GroupDocs.Annotation for .NET PDF küçük resimlerini oluşturabilir, güvenli belge önizleme akışları üretebilir ve mobil cihazlarda bile kullanıcı arayüzünü hızlı tutabilirsiniz. Bu rehberde önizleme oluşturmanın neden önemli olduğunu keşfedecek, yaygın uygulama senaryolarını inceleyecek ve kendi çözümlerinizde yüksek kaliteli önizlemeler eklemek için bir yol haritası elde edeceksiniz.

Hızlı yanıtlar

AnnotationApi sınıfı, belgeleri yükleyen ve önizleme görüntüleri oluşturan GroupDocs.Annotation’ın temel bileşenidir. GetPages yöntemi, işlenmiş sayfa görüntülerini bayt dizileri olarak döndürür. HideAnnotations bayrağı, işlenmiş görüntüden tüm açıklama katmanlarını kaldırır.

  • PDF küçük resmi oluşturmanın en hızlı yolu nedir? AnnotationApi ile PDF’yi yükleyin, DPI = 150 olarak ayarlayın ve GetPages metodunu çağırın – ilk sayfa, 2 MB bir dosya için 200 ms’den kısa sürede PNG olarak döndürülür.
  • Önizlemede tüm açıklamaları gizleyebilir miyim? Evet – temiz bir görünüm elde etmek için render etmeden önce HideAnnotations bayrağını kullanın.
  • Önizleme oluşturma iş parçacığı‑güvenli mi? API durum‑sızdır; birden fazla önizleme görevini paralel olarak güvenle çalıştırabilirsiniz.
  • Üretim kullanımında lisansa ihtiyacım var mı? Sınırsız önizleme oluşturma için geçerli bir GroupDocs.Annotation lisansı gereklidir.
  • Hangi .NET sürümleri destekleniyor? .NET Framework 4.6+, .NET Core 3.1+, .NET 5/6/7.

Belge önizlemesi nedir?

Belge önizlemesi, bir dosyanın hafif görsel temsili—genellikle bir görüntü veya bir dizi görüntü—olup, kullanıcıların tam belgeyi indirmeden içeriğe göz atmasını sağlar. Kullanıcı deneyimini iyileştirir, bant genişliğini azaltır ve yalnızca render etmeye karar verdiğiniz içeriği göstererek bir güvenlik katmanı ekler.

Neden güvenli belge önizlemesi kullanılmalı?

Güvenli belge önizlemesi, hassas meta verilerin, gizli katmanların veya kısıtlı açıklamaların sunucudan asla çıkmamasını sağlar. GroupDocs.Annotation, önizleme akışını şifreler ve açıkça izin vermediğiniz tüm işaretlemeleri kaldırır, böylece son kullanıcıların ne gördüğü üzerinde tam kontrol sahibi olursunuz. Sayısal iddia: kütüphane 30+ dosya formatını destekler ve varsayılan 150 DPI kullanıldığında standart 8 çekirdekli bir sunucuda 500 sayfalık PDF’leri 2 saniyeden kısa sürede önizleme oluşturabilir.

PDF küçük resmi nasıl oluşturulur?

AnnotationApi ile PDF’yi yükleyin, net metin için DPI 150‑300 aralığını belirleyin ve ilk sayfayı PNG olarak isteyin. Bu iki adımlı yaklaşım, tarayıcıya doğrudan akıtabileceğiniz veya diskte önbelleğe alabileceğiniz bir bayt dizisi döndürür. Daha yüksek DPI (ör. 300) metin ağırlıklı belgelerde okunabilirliği artırırken, daha düşük DPI (ör. 72) küçük resim ızgaraları için dosya boyutunu azaltır.

Önkoşullar

  • .NET Framework 4.6+ veya .NET Core 3.1+ yüklü.
  • Geçerli bir GroupDocs.Annotation lisansı (geçici lisans değerlendirme için çalışır).
  • Önizleme yapmayı planladığınız PDF, Word, Excel veya diğer desteklenen dosyalara erişim.

Adım adım önizleme oluşturma

Önizleme oluşturmak için GroupDocs.Annotation paketini kurmanız, API’yi lisansınızla başlatmanız, önizleme seçeneklerini yapılandırmanız, görüntüyü üretmeniz ve isteğe bağlı olarak sonucu önbelleğe almanız gerekir. Aşağıdaki bölümler, her adımı kod örnekleriyle göstererek açıklama katmanlarını gizleme, DPI ayarlama ve büyük dosyaları verimli bir şekilde işleme konularını ele alır.

Adım 1: NuGet paketini kurun

Projenizin Package Manager Console’ını açın ve şu komutu çalıştırın:

Install-Package GroupDocs.Annotation

Adım 2: API’yi başlatın

AnnotationApi örneği oluşturun, lisans dosyası yolunuzu ve isteğe bağlı yapılandırmayı (ör. önbellek klasörü, bellek limiti) geçirin.

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

Adım 3: Açıklama katmanları olmadan önizleme oluşturun

HideAnnotations bayrağını true olarak ayarlayın, istediğiniz DPI’yi seçin ve ihtiyacınız olan sayfa(ları) isteyin.

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 çağrısı, doğrudan bir HTTP yanıtına gönderebileceğiniz, bir CDN’de depolayabileceğiniz veya bir UI bileşenine yerleştirebileceğiniz bir bayt dizisi döndürür.

Adım 4: Önizlemeleri önbelleğe al ve yeniden kullan

Aynı önizlemeyi tekrar tekrar oluşturmayı önlemek için, görüntüyü kaynak dosyanın ve önizleme ayarlarının bir hash’iyle önbellek anahtarı olarak depolayın. Kaynak belge değiştiğinde, zaman damgalarını karşılaştırarak önbelleği geçersiz kılın.

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

Adım 5: Büyük belgeleri verimli bir şekilde işleyin

100 MB’den büyük dosyalar için, AnnotationApi‘nin iç akışlarını hızlıca serbest bırakmasını sağlamak amacıyla bir using bloğu kullanın. Çok sayfalı önizlemeler gerektiğinde sayfaları partiler halinde işleyin, bir sonraki partiye geçmeden önce her partiyi serbest bırakın.

Yaygın uygulama senaryoları

  • Document management systems – hızlı görsel gezinme için küçük resim ızgarası gösterir.
  • Collaboration platforms – gözden geçirenler için sadece önizleme görünümleri render eder, ardından istek üzerine açıklama katmanlarının açılıp kapatılmasına izin verir.
  • Web portals – dosya bağlantıları için üzerine gelince önizleme gösterir, tam indirme ihtiyacını azaltır.
  • Mobile apps – sayfa başına 50 KB’nin altında bant genişliği kullanımı sağlamak için düşük çözünürlüklü PNG’ler (72 DPI) üretir.

Önizleme oluşturma sorun giderme

  • Memory spikes with large PDFs – her önizleme partisinden sonra AnnotationApi üzerinde Dispose() çağırdığınızdan ve eşzamanlı önizleme görevlerinin sayısını sınırladığınızdan emin olun.
  • Blurry text in thumbnails – DPI’yi 300’e yükseltin veya çıktı formatını PNG’ye değiştirin; JPEG sıkıştırması ince karakterleri yumuşatabilir.
  • Missing images in Excel previews – önizleme seçeneklerinde LoadCharts = true ayarlayarak çalışma kitabının grafik nesnelerinin tam yüklendiğinden emin olun.
  • Slow response times – önizleme oluşturmayı bir arka plan işçisine (ör. Task.Run) taşıyın ve gerçek önizleme hazır olana kadar bir yer tutucu görüntü sunun.

Sıkça Sorulan Sorular

S: Parola korumalı belgeler için önizleme oluşturabilir miyim?
C: Evet. AnnotationApi örneğini oluştururken LoadOptions içinde parolayı sağlayın; önizleme başarılı bir şekilde şifre çözüldükten sonra oluşturulur.

S: Kütüphane, DOCX veya XLSX gibi PDF dışı formatlar için önizleme oluşturmayı destekliyor mu?
C: Kesinlikle. GroupDocs.Annotation, DOCX, XLSX, PPTX ve birçok görüntü türü dahil olmak üzere 30‘dan fazla farklı format için önizleme oluşturabilir.

S: Önizlemenin gizli meta verileri ortaya çıkarmadığından nasıl emin olabilirim?
C: PreviewOptions içinde HideMetadata seçeneğini kullanın; API, görüntüyü render etmeden önce tüm belge özelliklerini kaldırır.

S: Önizleme uç noktasını halka açık olarak yayınlamak güvenli mi?
C: Önizleme akışı sunucu tarafında oluşturulur ve HTTPS üzerinden teslim edilebilir. Erişimi yalnızca yetkili kullanıcılara sınırlamak için token‑tabanlı kimlik doğrulama ile birleştirin.

S: Önerilen önbellek süresi politikası nedir?
C: Önizlemeleri, kaynak belge sürümünün ömrü boyunca önbellekte tutun. Belgenin son‑değiştirilme zaman damgası değiştiğinde, önbellekteki görüntüyü geçersiz kılın ve yeniden oluşturun.

Ek kaynaklar

Son Güncelleme: 2026-08-09
Test Edilen Versiyon: GroupDocs.Annotation 23.10 for .NET
Yazar: GroupDocs

İlgili Eğitimler