Samouczek: Otwieranie dokumentów przy użyciu wstrzykniętego Doconut Viewer w .NET 8

Wprowadzenie

Starsze przykłady Doconut mogą tworzyć Viewer bezpośrednio z argumentami cache, kontekstu HTTP i ścieżki licencji. To nie jest aktualny model integracji .NET 8. AddDoconut() rejestruje Viewer w kontenerze wstrzykiwania zależności, a punkty końcowe aplikacji otrzymują usługę zamiast wywoływać konstruktor.

Ten samouczek opisuje aktualny przepływ żądania: rejestrację usług i middleware, emisję wbudowanych zasobów przeglądarki, otwarcie dokumentu za pomocą OpenDocumentAsync, zwrócenie nieprzezroczystego tokenu sesji oraz przekazanie tego tokenu do widżetu przeglądarki.

---

1. Instalacja i rejestracja Doconut

Dodaj pakiet .NET 8:

dotnet add package Doconut.NET8

Zarejestruj Doconut i usługi sesji ASP.NET:

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

builder.Services.AddSession();

Połącz middleware w wymaganej kolejności. Middleware zasobów musi działać przed końcowym middleware dokumentu:

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

MiddlewarePath koordynuje konfigurację, ale nie tworzy gałęzi ASP.NET samodzielnie. Mapowana ścieżka /doconut musi odpowiadać BasePath widżetu.

2. Dodaj powierzchnię przeglądarki i zasoby

Przeglądarka przeglądarki Doconut jest wtyczką jQuery. W stronie Razor wstrzyknij Viewer i poproś go o wygenerowanie znaczników zasobów w odpowiedniej kolejności zależności:

@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>

Zainicjuj widżet ze ścieżkami odpowiadającymi rejestracji serwera:

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

Wielkość liter opcji ma znaczenie. Używaj nazw wyświetlanych przez zainstalowaną wersję, zamiast normalizować je do jednego stylu.

3. Wstrzyknij Viewer i otwórz dokument

Viewer jest zarejestrowany jako usługa przejściowa. Rozwiąż go poprzez wstrzykiwanie w punktach końcowych, wstrzykiwanie w konstruktorze lub równoważny mechanizm w aplikacji ASP.NET Core.

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

W przypadku przesyłania, podaj strumień oraz FileInfo, którego rozszerzenie identyfikuje format źródłowy:

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

Zweryfikuj rozmiar przesyłanego pliku, rozszerzenie i uprawnienia przed otwarciem treści dostarczonej przez użytkownika. Nie przekształcaj przesłanej nazwy pliku w ścieżkę serwera.

4. Przekaż token do widżetu

Pobierz endpoint otwierania i przekaż zwrócony token do objViewer.View:

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

Traktuj token jako poświadczenie nosiciela dla aktywnej sesji dokumentu:

• Nie loguj ani nie przechowuj go.
• Zwracaj go wyłącznie autoryzowanemu klientowi.
• Nie ujawniaj ścieżki pliku źródłowego.
• Otwórz ponownie dokument, gdy sesja wygaśnie.
• Zamknij sesję, gdy dokument nie jest już potrzebny.

5. Celowe zamykanie sesji po stronie serwera

Kod po stronie klienta może wywołać objViewer.Close(), gdy użytkownik opuszcza przeglądarkę. Przepływy po stronie serwera mogą również wyraźnie unieważnić znany token:

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

Wyraźne zamknięcie jest szczególnie przydatne przy dużych dokumentach. Wygaśnięcie sesji pozostaje rozwiązaniem awaryjnym, a nie zamiennikiem przewidywalnego zarządzania cyklem życia aplikacji.

6. Dodaj opcjonalne moduły dopiero po działaniu rdzenia

Wyszukiwanie i adnotacje przyłączają się do tej samej zainicjowanej przeglądarki. Dodaj ich CSS, skrypty, montowanie, kontrole licencji i wywołania zwrotne cyklu życia dopiero po pomyślnym zakończeniu podstawowego przepływu:

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

Ta kolejność utrzymuje awarie renderowania rdzenia oddzielnie od konfiguracji opcjonalnych modułów.

Typowe błędy migracji

Stary lub nieprawidłowy wzorzec	Obecny kierunek .NET 8
new Viewer(cache, accessor, licensePath)	Wstrzyknij Viewer po AddDoconut()
Statyczne wywołania ładowania licencji w kodzie żądania	Skonfiguruj wprowadzanie licencji w AddDoconut()
Synchroniczne przykłady OpenDocument(...)	Użyj OpenDocumentAsync(...)
Zewnętrzny lub wymyślony CDN przeglądarki	Wygeneruj wbudowane zasoby za pomocą ReferenceCss i ReferenceScripts
Ogólne API JavaScript init()	Zainicjuj $('#div_ctlDoc').docViewer(...)
Przechowywanie tokenu przeglądarki	Przechowuj identyfikator dokumentu; traktuj token jako tymczasowy

Użyj oficjalnej dokumentacji Doconut(Doconut documentation) i zweryfikuj przykłady względem zainstalowanej wersji pakietu przed ich adaptacją do kodu produkcyjnego.