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

Giriş

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

Bu öğretici, mevcut istek akışını izler: hizmetleri ve ara katmanı kaydet, gömülü görüntüleyici kaynaklarını yayınla, OpenDocumentAsync ile bir belge aç, opak bir oturum tokeni döndür ve bu tokeni tarayıcı widget'ına ilet.

---

1. Doconut'u Yükleyin 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();

Ara katmanı gerekli sırada bağlayın. Kaynak ara katmanı, terminal belge ara 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 ile eşleşmelidir.

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

Doconut tarayıcı görüntüleyicisi bir jQuery eklentisidir. Bir Razor sayfasında, Viewer'yi enjekte edin ve ona bağımlılık sırasına göre kaynak etiketlerini yayınlaması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çenek büyük/küçük harf duyarlılığı önemlidir. Tek bir stile normalleştirmek yerine yüklü sürüm tarafından gösterilen adları kullanın.

3. Görüntüleyiciyi 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 aracılığıyla çö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, bir akış ve uzantısı kaynak formatı tanımlayan bir FileInfo 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. Tokeni Widget'a iletin

Açma uç noktasını alın ve dönen tokeni objViewer.View'ye verin:

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));

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

• Bunu kaydetmeyin veya kalıcı hale getirmeyin.
• Sadece yetkili bir istemciye geri döndürün.
• Kaynak dosya yolunu ifşa etmeyin.
• Bir oturum sona erdiğinde belgeyi yeniden açın.
• Belge artık ihtiyaç duyulmadığında oturumu kapatın.

5. Sunucu tarafı oturumları kasıtlı olarak kapatın

Kullanıcı görüntüleyiciden ayrıldığında istemci kodu objViewer.Close()'yi çağırabilir. Sunucu iş akışları da bilinen bir tokeni 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üresinin dolması bir geri dönüş olarak kalır, öngörülebilir uygulama yaşam döngüsü yönetiminin yerini almaz.

6. Çekirdek çalıştıktan sonra isteğe bağlı modülleri ekleyin

Arama ve açıklamalar aynı başlatılmış görüntüleyiciye eklenir. CSS, betikler, bağlamalar, 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 geçiş hataları

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

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