Görüntüleyici
Ana belge görüntüleyici sınıfı
Viewer (namespace Doconut) genel giriş noktasıdır Razor sayfalarından, MVC denetleyicilerinden, Blazor bileşenlerinden veya minimal API'lerden belge açmak için. sealeddır, AddDoconut() tarafından transient hizmet olarak kaydedilir ve yapıcı enjeksiyonu üzerinden çözülür — doğrudan oluşturulmaz.
Önceki .NET Standard kitaplığı, bellek önbelleğini, HTTP bağlam erişicisini ve bir veya daha fazla lisans yolunu alan public constructor sunuyordu. Bu yapıcı kaldırıldı; service graph bu bağımlılıkları sağlar.
Viewer hiçbir istek‑başına durum tutmaz ve kasıtlı olarak implement etmez IDisposable: belge oturumları oturum önbelleğinde bağımsız olarak yaşar, bu yüzden hizmetin dispose edilmesi açık bir belgeyi asla kapatamaz (bkz. Core Concepts → How the Viewer Works).
OpenDocumentAsync
Bir belge açar ve istemci widget'ının sonraki tüm isteklerde kullandığı oturum jetonunu döndürür. Her açma işlemi asenkroniktir — senkron bir OpenDocument yoktur.
| Aşırı Yükleme | Ne zaman kullanılmalı |
|---|---|
Task<string> OpenDocumentAsync(string filePath, DocOptions? options = null, CancellationToken ct = default) | Diskten otomatik format algılaması ve formatın varsayılan yapılandırmasıyla açma |
Task<string> OpenDocumentAsync(string filePath, BaseConfig? config, DocOptions? options = null, CancellationToken ct = default) | Format‑özel render seçeneklerine ihtiyacınız var (PdfConfig, WordConfig, …) |
Task<string> OpenDocumentAsync(Stream stream, FileInfo fileInfo, BaseConfig? config = null, DocOptions? options = null, CancellationToken ct = default) | Belge disk üzerindeki bir dosya değil (yükleme, veritabanı, blob). fileInfo doğru uzantıyı taşımalıdır — format algılamasını yönlendirir |
// Basit aç
string token = await viewer.OpenDocumentAsync(path);
// Biçim başına yapılandırma ve seçeneklerle
token = await viewer.OpenDocumentAsync(
path,
new PdfConfig { AllowSearch = true, AllowCopy = true },
new DocOptions { TimeOut = 30 });
// Yüklemeden
await using var ms = new MemoryStream();
await file.CopyToAsync(ms);
ms.Position = 0;
token = await viewer.OpenDocumentAsync(ms, new FileInfo(file.FileName));Ele alınması gereken istisnalar:
LicenseException— bulunan bir lisans reddedilir (mesaj reddetme nedenini taşır) veya format artık sağlanmayan bir eklenti yeteneğine ihtiyaç duyar. Reddetme mesajı olmadan takvim süresi dolduğunda, su işaretiyle rendera düşer.FormatNotSupportedException—Document format '<extension>' is not supported.InvalidDataException— dosya içeriği bozuk veya uzantısıyla eşleşmiyor.
CloseDocument
void CloseDocument(string token)Oturumu önbellekten kaldırır (belge motorunu hemen dispose eder), güvenlik işaretçisini siler ve erişim iznini iptal eder. İsteğe bağlıdır — kayan son kullanma süresi aynı temizlik işlemini yapar — ancak büyük belgeler için önerilir.
GetPageCount
int GetPageCount(string token)Açık oturumun toplam sayfa sayısı. Jeton bilinmiyorsa veya süresi dolmuşsa InvalidOperationException (Document session not found. Please re-open document.) fırlatır, boş bir jeton için ise ArgumentException fırlatır.
GetPageDimensions
(int Width, int Height) GetPageDimensions(string token, int page = 1)Belgenin %100 yakınlaştırmadaki varsayılan render edilmiş sayfa boyutu — kod içinde oluşturulan ek açıklamalar için koordinat alanı. Uyumluluk için page kabul edilir; sonuç belge varsayılanıdır. Jeton bilinmiyorsa veya süresi dolmuşsa InvalidOperationException (Document session not found. Please re-open document.) fırlatır, boş bir jeton için ise ArgumentException fırlatır.
Çalışma Sayfası Adlarını Al
IReadOnlyList<string> GetWorksheetNames(string token)Açık bir elektronik tablonun çalışma sayfası adlarını, çalışma kitabı sırasına göre döndürür; açık belge bir elektronik tablo değilse boş bir liste döner.
Yalnızca render edilen çalışma sayfaları listelenir: gizli ve boş çalışma sayfaları dışlanır ve ExcelConfig.SheetNames renderı kısıtladığında yalnızca o çalışma sayfaları görünür. Bir çalışma sayfası her zaman tek bir sayfa değildir — çok büyük bir sayfa birkaç sayfaya render edilir. Token bilinmiyorsa veya süresi dolmuşsa InvalidOperationException (Document session not found. Please re-open document.) fırlatır ve boş bir token için ArgumentException fırlatır.
26.9.0 sürümünde eklendi.
Yetkinlik bayrakları
| Üye | Anlam |
|---|---|
bool IsSearchEnabled | Mevcut lisans Search sağlar |
bool IsAnnotationEnabled | Mevcut lisans Annotation sağlar |
Bunları bir Razor görünümünde, sunucunun gerçekten sunacağı zaman lisanslı bir Ribbon render etmek için kullanın — bkz. Hızlı Başlangıç.
DocOptions
Açılış başına, format bağımsız seçenekler (namespace Doconut):
| Tür | Özellik | Varsayılan | Açıklama |
|---|---|---|---|
string | Password | "" | Korunan belgeler için şifre (format yapılandırmasına otomatik olarak kopyalanır). |
int | ImageResolution | 0 | Eski. Yalnızca uyumluluk için tutulur — bunun yerine format yapılandırmasında ImageResolution ayarlayın. |
string | Watermark | "" | Render edilen sayfalara çizilen özel filigran metni. Biçim dizesi: "^Text~Color~FontSize~FontName~Opacity~Angle", ör. "^Sample Copy~Red~24~Verdana~80~-45". |
int | TimeOut | 60 | Oturum kaydırmalı süresi dakikalar içinde. |
bool | IsSecured | true | Şu anda uygulanmıyor — ayrılmış. Token bağlama, DoconutOptions.UnsafeMode tarafından küresel olarak kontrol edilir (bkz. Core Concepts → Sessions & Security). |
Sınıf ayrıca, normal tek sunucu görüntüleme akışının dışındaki özel özellikleri de sunar:
| Tür | Özellik | Varsayılan | Açıklama |
|---|---|---|---|
bool | IsWebFarm | false | Eski — etkisi yok. Belgeyi DistributedDocumentPublisher.PublishAsync (veya IDistributedPublishQueue.EnqueueAsync) ile yayınlayın ve bunun yerine FileShareConfig.RootPath ayarlayın. Büyük/küçük harfe dikkat edin — önceki kütüphane bunu IsWebfarm olarak yazıyordu. |
string | WebFarmPath | "" | Eski — etkisi yok. Dağıtılmış Dağıtımlar içinde açıklandığı gibi FileShareConfig.RootPath kullanın. Önceden WebfarmPath olarak yazılmıştı. |
bool | EditMode | false | Ayrı dağıtılan bir düzenleme iş akışı için ayrılmış; standart görüntüleyici için false bırakın. |
Özel filigran
DocOptions.Watermark altı tilde ile ayrılmış alan kullanır. İsteğe bağlı bir ön ^ tüm köşe düzenini talep eder:
^Text~Color~FontSize~FontName~Opacity~Anglestring token = await viewer.OpenDocumentAsync(
path,
new PdfConfig(),
new DocOptions
{
Watermark = "^Confidential~Red~24~Verdana~80~-45",
TimeOut = 30
});| Alan | Örnek | Anlam |
|---|---|---|
Ön ^ | ^ | İsteğe bağlı tüm köşe düzeni. Olmazsa, normal filigran konumu kullanılır. |
| Metin | Confidential | Her sayfada render edilen metin. Boş olmamalıdır. |
| Renk | Red | Çizim katmanı tarafından anlaşılan adlandırılmış renk. |
| YazıBoyutu | 24 | Yazı tipi boyutu; geçersiz sayısal giriş render varsayılanına geri döner. |
| YazıTipiAdı | Verdana | Talep edilen yazı tipi ailesi. Dağıtım ortamına kurulu olduğundan emin olun. |
| Saydamlık | 80 | 0 ile 255 arasında bir bayt değeri. Başarıyla ayrıştırılmalıdır. |
| Açı | -45 | Derece cinsinden dönüş açısı; geçersiz sayısal giriş varsayılana geri döner. |
Ayrıştırıcı, isteğe bağlı ^ sonrası tam altı alan bekler. Geçersiz bir tanım, sessizce kaybolmak yerine SDK'nın görünür Invalid Watermark geri dönüşüyle değiştirilir.
Lisans kararı
| Lisans durumu | Sağlanan özel değer | Oluşturulan sonuç |
|---|---|---|
| Geçerli ücretli görüntüleyici lisansı | Hayır | Temiz sayfa |
| Geçerli ücretli görüntüleyici lisansı | Evet | Özel filigran |
| Etkin Geçici/Demo temel görüntüleyici | Hayır | Temiz temel-görüntüleyici sayfası |
| Etkin Geçici/Demo temel görüntüleyici | Evet | Temiz temel-görüntüleyici yolu uygulandığında özel filigran |
| Eksik, reddedilmiş, süresi dolmuş, yanlış sürüm veya geçersiz alan adı lisansı | Her ikisi | Uygulama/değerlendirme filigranı; özel değer bunu geçersiz kılmaz |
| Değerlendirme kuralları altında eklenti render'ı | Her ikisi | Değerlendirme filigranı |
Aynı karar, sunulan sayfa görüntülerine ve ek açıklama dışa aktarmalarına uygulanır. Hareketli GIF çıktısı çerçeve çerçeve damgalanır. Bu nedenle özel bir filigran, lisanslı bir uygulama özelliğidir, değerlendirme filigranını değiştirmek veya bastırmak için bir yol değildir.
Açıklama API'si
Sunucu tarafı açıklama yükleme ve dışa aktarma. Tam kılavuz Guides → Annotations içinde bulunur; özet şu şekildedir:
| Üye | Amaç |
|---|---|
AnnotationManager GetAnnotationManager(string token) | Açık oturumun sayfa boyutlarına bağlı yönetici |
AnnotationManager GetAnnotationManager(string token, int pageWidth, int pageHeight) | Açık sayfa boyutlarıyla yönetici |
AnnotationManager GetAnnotationManager(int pageWidth, int pageHeight) | Oturum bağımsız yönetici |
void LoadAnnotationData(string token, AnnotationManager manager) | C#'ta oluşturulan açıklamaları oturuma yükle |
void LoadAnnotationData(string token, string annotationData) | AnnotationManager.GetAnnotationData() tarafından döndürülen kodlanmış sayfa/Base64 zarfından açıklamaları yükle |
void LoadAnnotationXML(string token, XmlDocument annotationXml) | XML'den açıklamaları yükle |
XmlDocument GetAnnotationXML(string token) | Oturumun açıklamalarını XML olarak dışa aktar |
Task<byte[]> ExportAnnotationsToPdfAsync(string token, int zoom = 100, CancellationToken ct = default) | Açıklamaları gömülü PDF |
Task<int> ExportAnnotationsToPngAsync(string token, string directoryPath, int zoom = 100, CancellationToken ct = default) | Sayfa başına bir PNG, açıklamaları gömülü, directoryPath'a yazılır (eksikse oluşturulur); yazılan görüntü sayısını döndürür |
Task<byte[]> ExportAnnotationsToPngZipAsync(string token, int zoom = 100, CancellationToken ct = default) | Açıklamaları gömülü sayfa başı PNG'lerin ZIP'i |
Bunların her biri oturum token'ını alır. Önceki kütüphanenin oturum-olmayan GetAnnotationManager(pageWidth, pageHeight) şekli, oturum dışı açıklama oluşturmak için hâlâ vardır, ancak bunları yüklemek yine bir token gerektirir.
DICOM meta verileri
Task<DicomMetadata?> GetDicomMetadataAsync(string token, CancellationToken ct = default)Bu yöntem API uyumu için mevcuttur, ancak bu paket teknik DICOM etiketlerini sağlayamaz: meta veri okuyucu yalnızca .NET 8 derlemesiyle gelir. DICOM ve DICOM olmayan oturumlar için null döndürür; bir DICOM oturumunda ayrıca platform sınırlamasını açıklayan tek seferlik bir uyarı yazar. Sayfa, çerçeve ve animasyon render'ı desteklenmeye devam eder.
Kaynak yardımcıları — ReferenceCss / ReferenceScripts
UseDoconutResources() tarafından sunulan gömülü kaynaklar için doğru bağımlılık sırasıyla <link>/<script> etiketlerini oluştur. Arama ve açıklama gibi lisans kısıtlamalı özellikler için paketler yalnızca lisans bunları etkinleştirdiğinde oluşturulur, böylece istemci UI'si sunucu davranışıyla tutarlı kalır.
string ReferenceCss(CssConfig? config = null) // null → Bootstrap + görüntüleyici + arama + açıklama
string ReferenceScripts(ScriptConfig? config = null)CssConfig bayrakları: IncludeBootstrapCss, IncludeViewerCss, IncludeSearchCss (arama kısıtlamalı), IncludeAnnotationCss (açıklama kısıtlamalı).
ScriptConfig bayrakları: IncludeJQuery (tüm diğerleri tarafından gereklidir), IncludeBootstrap, IncludeViewerScripts (çekirdek: docViewer.js + bölücü + bağlantılar), IncludeSearchScripts ve IncludeSearchBar (arama kısıtlamalı), IncludeAnnotationScripts ve IncludeAnnotationBar (açıklama kısıtlamalı), EmitFeatureFlags (varsayılan true: ayrıca satır içi window.Doconut.features = { search, annotation, editor } betiği yazar; satır içi betiği engelleyen bir Content-Security-Policy altında false olarak ayarlayın).
@inject Doconut.Viewer Viewer
@Html.Raw(Viewer.ReferenceCss(new CssConfig { IncludeBootstrapCss = true, IncludeViewerCss = true }))
@Html.Raw(Viewer.ReferenceScripts(new ScriptConfig { IncludeJQuery = true, IncludeViewerScripts = true }))Bu yardımcılar, tarayıcı kaynaklarını teslim etmenin desteklenen yoludur. docViewer.js, documentLinks.js ve docViewer.UI.js'ı wwwroot içine kopyalayan uygulamalar, sayfa oluşturulan etiketlerden yüklendikten sonra bu kopyaları kaldırmalıdır.
Bu sayfa yardımcı oldu mu?