Öğretici: .NET 8'de Enjekte Edilen Doconut Görüntüleyici ile Belgeleri Açma

Giriş

Eski Doconut örnekleri, Viewer'ı doğrudan önbellek, HTTP bağlamı ve lisans yolu argümanlarıyla oluşturabilir. Bu, mevcut .NET 8 entegrasyon modeli değildir. AddDoconut() Viewer'ı bağımlılık enjeksiyonu ile kaydeder ve uygulama uç noktaları bir yapıcı çağırmak yerine hizmeti alır.

Belge görüntüleme yüzeyine opak bir oturum token'ı geçiren soyut sunucu bileşenleri

Bu öğretici, mevcut istek akışını takip eder: hizmetleri ve ara katmanı kaydedin, gömülü görüntüleyici kaynaklarını yayınlayın, bir belgeyi OpenDocumentAsync ile açın, opak bir oturum token'ı döndürün ve bu token'ı tarayıcı widget'ına iletin.

1. Doconut'ı Kurun ve Kaydedin

.NET 8 paketini ekleyin:

dotnet add package Doconut.NET8

Doconut ve ASP.NET oturum hizmetlerini kaydedin:

builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
    options.MiddlewarePath = "/doconut";
    options.ResourcesPath = "/doconut-res";
    options.UnsafeMode = false;
});

builder.Services.AddSession();

Orta katmanı gerekli sırada bağlayın. Kaynak orta katmanı, terminal belge orta katmanından önce çalışmalıdır:

app.UseRouting();
app.UseSession();
app.UseDoconutResources();
app.Map("/doconut", branch => branch.UseDoconut());

MiddlewarePath yapılandırmayı koordine eder ancak tek başına ASP.NET dalını oluşturmaz. Eşlenen /doconut yolu, widget'ın BasePath'iyle eşleşmelidir.

2. Görüntüleyici yüzeyini ve kaynaklarını ekleyin

Doconut tarayıcı görüntüleyicisi bir jQuery eklentisidir. Bir Razor sayfasında, Viewer'ı enjekte edin ve ona kaynak etiketlerini bağımlılık sırasına göre oluşturmasını isteyin:

@inject Doconut.Viewer Viewer

@Html.Raw(Viewer.ReferenceCss(new CssConfig
{
    IncludeViewerCss = true
}))

@Html.Raw(Viewer.ReferenceScripts(new ScriptConfig
{
    IncludeJQuery = true,
    IncludeViewerScripts = true
}))

<div id="divDocViewer">
    <div id="div_ctlDoc"></div>
</div>

Widget'ı sunucu kaydıyla eşleşen yollarla başlatın:

const objViewer = $('#div_ctlDoc').docViewer({
    showThumbs: true,
    autoLoad: false,
    pageZoom: 100,
    FitType: 'width',
    BasePath: '/doconut',
    ResPath: '/doconut-res/images',
    onError: function (message) {
        console.error('Doconut viewer error:', message);
    }
});

Seçeneklerin büyük/küçük harf duyarlılığı önemlidir. Normalleştirerek tek bir stile dönüştürmek yerine, yüklü sürümde gösterilen adları kullanın.

3. Viewer'ı Enjekte Edin ve Bir Belge Açın

Viewer geçici bir hizmet olarak kaydedilir. Bunu uç nokta enjeksiyonu, yapıcı enjeksiyonu veya ASP.NET Core uygulamanızdaki eşdeğer mekanizma ile çözün.

app.MapPost("/api/open", async (
    Viewer viewer,
    CancellationToken ct) =>
{
    string token = await viewer.OpenDocumentAsync(
        "wwwroot/files/Sample.pdf",
        ct: ct);

    return Results.Ok(new { token });
});

Bir yükleme için, akışı ve uzantısı kaynak formatı belirten bir FileInfo nesnesini sağlayın:

app.MapPost("/api/open-upload", async (
    IFormFile file,
    Viewer viewer,
    CancellationToken ct) =>
{
    await using var stream = file.OpenReadStream();
    string token = await viewer.OpenDocumentAsync(
        stream,
        new FileInfo(file.FileName),
        ct: ct);

    return Results.Ok(new { token });
});

Kullanıcı tarafından sağlanan içeriği açmadan önce yükleme boyutunu, uzantısını ve yetkilendirmeyi doğrulayın. Gönderilen dosya adını bir sunucu yoluna dönüştürmeyin.

4. Token'ı Widget'a Geçirin

Açma uç noktasını alın ve dönen token'ı objViewer.View'a iletin:

fetch('/api/open', { method: 'POST' })
    .then(response => {
        if (!response.ok) throw new Error('The document could not be opened.');
        return response.json();
    })
    .then(data => objViewer.View(data.token))
    .catch(error => console.error(error));

Token'ı canlı bir belge oturumu için taşıyıcı kimlik bilgisi olarak ele alın:

Bunu kaydetmeyin veya kalıcı hale getirmeyin.
Yalnızca yetkili bir istemciye geri döndürün.
Kaynak dosya yolunu ifşa etmeyin.
Bir oturum süresi dolduğunda belgeyi yeniden açın.
Belge artık gerekmediğinde oturumu kapatın.

5. Sunucu Tarafı Oturumları Bilinçli Olarak Kapatın

Kullanıcı görüntüleyiciden ayrıldığında istemci kodu objViewer.Close() çağırabilir. Sunucu iş akışları da bilinen bir token'ı açıkça iptal edebilir:

app.MapPost("/api/close", (string token, Viewer viewer) =>
{
    viewer.CloseDocument(token);
    return Results.NoContent();
});

Açık kapanış özellikle büyük belgeler için faydalıdır. Oturum süresi dolması bir yedek olarak kalır, öngörülebilir uygulama yaşam döngüsü yönetiminin yerine geçmez.

6. Çekirdek Çalıştıktan Sonra İsteğe Bağlı Modülleri Ekleyin

Arama ve açıklamalar aynı başlatılmış görüntüleyiciye eklenir. CSS, scriptler, montajlar, lisans kontrolleri ve yaşam döngüsü geri çağırmalarını yalnızca temel akış başarılı olduğunda ekleyin:

AddDoconut + session services
    -> UseSession
    -> UseDoconutResources
    -> mapped UseDoconut branch
    -> viewer resources and mount
    -> initialize docViewer
    -> OpenDocumentAsync
    -> objViewer.View(token)

Bu sıra, çekirdek render hatalarını isteğe bağlı modül yapılandırmasından ayrı tutar.

Yaygın Göç Hataları

Eski veya hatalı desen	Mevcut .NET 8 yönü
`new Viewer(cache, accessor, licensePath)`	`AddDoconut()` sonrası `Viewer`'ı enjekte edin
İstek kodunda statik lisans yükleme çağrıları	`AddDoconut()` içinde lisans girişini yapılandırın
Eşzamanlı `OpenDocument(...)` örnekleri	`OpenDocumentAsync(...)` kullanın
Harici veya uydurulmuş bir görüntüleyici CDN'i	`ReferenceCss` ve `ReferenceScripts` ile gömülü kaynakları yayınlayın
Genel bir JavaScript `init()` API'si	`$('#div_ctlDoc').docViewer(...)` ile başlatın
Görüntüleyici token'ını kalıcı hale getirme	Belge kimliğinizi kalıcı hale getirin; token'ı geçici olarak ele alın

Resmi Doconut belgelerini kullanın ve örnekleri üretim koduna uyarlamadan önce yüklü paket sürümüyle doğrulayın.