Poradnik: 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 obecny model integracji w .NET 8. AddDoconut() rejestruje Viewer przy użyciu wstrzykiwania zależności, a endpointy aplikacji otrzymują usługę zamiast wywoływać konstruktor.

Ten poradnik opisuje bieżący 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. Zmapowana ś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ś ją o emisję znaczników zasobów w 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>

Zainicjalizuj 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 normalizowania ich do jednego stylu.

3. Wstrzyknij Viewer i otwórz dokument

Viewer jest zarejestrowany jako usługa przejściowa. Rozwiąż go poprzez wstrzykiwanie w endpointzie, wstrzykiwanie w konstruktorze lub równoważną funkcję 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 pliku, 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 otwarcia 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ż wycofać znany token explicite:

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

Jawne 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, sprawdzanie 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 niepoprawny 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()
Synchronizowane przykłady OpenDocument(...)	Użyj OpenDocumentAsync(...)
Zewnętrzny lub wymyślony CDN przeglądarki	Emituj wbudowane zasoby przy użyciu ReferenceCss i ReferenceScripts
Ogólne API JavaScript init()	Zainicjalizuj $('#div_ctlDoc').docViewer(...)
Przechowywanie tokenu przeglądarki	Przechowuj identyfikator dokumentu; traktuj token jako tymczasowy

Użyj oficjalnej dokumentacji Doconut i zweryfikuj przykłady względem zainstalowanej wersji pakietu przed dostosowaniem ich do kodu produkcyjnego.