Instalacja

Dodaj Doconut do swojego projektu .NET 6

Podstawowa przeglądarka Doconut dla .NET 6 jest dostarczana jako pojedynczy pakiet NuGet, który integruje się z dowolną aplikacją ASP.NET Core. Opcjonalne wtyczki używają oddzielnych pakietów. Ta strona instaluję podstawowy pakiet i rejestruje middleware — minimalne wymagania przed pierwszym renderowaniem.

Wymagania

Pakiet działa na następujących platformach:

PlatformaObsługiwane
Windows x64 / x86Tak
Linux x64, glibc-based (Debian, Ubuntu, the official mcr.microsoft.com/dotnet/aspnet:6.0-bookworm-slim image)Tak
Alpine and other musl-based distributionsNie
macOSNie

W systemie Linux zainstaluj bibliotekę konfiguracyjną czcionek przed otwarciem pierwszego dokumentu:

bash
apt-get update && apt-get install -y libfontconfig1

W dystrybucjach RHEL, Fedora i podobnych pakiet jest fontconfig (dnf install -y fontconfig). To jedyny pakiet systemowy, którego potrzebuje Doconut: natywne biblioteki, z których korzysta, są dostarczane wewnątrz pakietu NuGet, a libgdiplus nie jest wymagany.
W Dockerze preferuj aspnet:6.0-bookworm-slim (Debian 12): domyślny tag aspnet:6.0 to Debian 11, którego lustrzane repozytoria pakietów mogą nie udać się zainstalować libfontconfig1. Strony są renderowane z czcionkami zainstalowanymi na serwerze, więc zobacz Rozwiązywanie problemów w celu uzyskania informacji o czcionkach i komunikatach błędów systemu Linux.

Zainstaluj pakiet

bash
dotnet add package Doconut.NET6

Polecenie bez wersji instaluję najnowsze stabilne wydanie. Aby przypiąć wersję opisaną w tej dokumentacji, przekaż wersję jako oddzielną opcję:

bash
dotnet add package Doconut.NET6 --version 26.10.0

Doconut.NET6 jest identyfikatorem pakietu. Przyrostek wersji należy do pobranego pliku Doconut.NET6.<version>.nupkg i nie jest częścią identyfikatora.

Zidentyfikuj integrację przed aktualizacją

Identyfikator pakietu Doconut.NET6 był używany zarówno w klasycznej, jak i bieżącej integracji .NET 6. Nie wybieraj dokumentacji wyłącznie na podstawie nazwy pakietu:

  • DocImage.axd, new Viewer(_cache, _accessor, ...), synchroniczne OpenDocument(...) oraz ręcznie skopiowane skrypty przeglądarki identyfikują klasyczną integrację;
  • AddDoconut(), UseDoconutResources(), wstrzyknięty Viewer oraz OpenDocumentAsync(...) identyfikują bieżącą integrację opisaną tutaj.

Przetłumaczona klasyczna instrukcja konfiguracji jest nadal dostępna. Skorzystaj z przewodnika migracji, aby zmienić generacje; zwykła aktualizacja pakietu nie konwertuje automatycznie uruchamiania, czasu życia przeglądarki ani zasobów przeglądarki.

Zarejestruj Doconut

AddDoconut() jest jedynym punktem wejścia rejestracji — istnieje pojedyncze przeciążenie, które podłącza usługę Viewer, usługę licencji oraz infrastrukturę renderowania do kontenera DI.

Dwa wywołania middleware kończą konfigurację i ich kolejność ma znaczenie: UseDoconutResources() musi być uruchomione przed UseDoconut(). UseDoconut() jest middleware'em końcowym, więc wywołanie go jako pierwszego powoduje, że każde żądanie do zasobu /doconut-res nigdy nie dociera do obsługi zasobów i zwraca 404. UseDoconut() odpowiada na każde żądanie, które do niego dotrze, więc zamontuj go w osobnej gałęzi z app.Map. Połączenie sesji jest również wymagane — domyślne zabezpieczenie dokumentu Doconut weryfikuje każde żądanie strony względem stanu sesji ASP.NET.

csharp
builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
});
builder.Services.AddDistributedMemoryCache(); // stan sesji wymaga pamięci podręcznej (MVC/Razor Pages już dodają jedną)
builder.Services.AddSession(); // Bezpieczeństwo dokumentów Doconut opiera się na stanie sesji ASP.NET

app.UseSession();          // wywołaj UseSession() przed UseDoconut()
app.UseDoconutResources(); // musi być zarejestrowane przed UseDoconut()
app.Map("/doconut", branch => branch.UseDoconut());

Wszystkie opcje

DoconutOptions akceptuje następujące konfigurowalne właściwości. Każda z nich jest opcjonalna — poniższe wartości domyślne mają zastosowanie, gdy właściwość nie zostanie ustawiona.

WłaściwośćDomyślnieOpis
ShowDoconutInfofalseGdy true, żądanie bez token zwraca baner wersji zamiast 404. Przydatne jako szybka kontrola; wyłącz w produkcji.
UnsafeModefalseGdy true, pomija sprawdzenie bezpieczeństwa sesji ASP.NET przy żądaniach stron. Wyłącz w produkcji.
MiddlewarePath"/doconut"Wartość koordynacji dla punktu końcowego page-image. Jest walidowana, ale nie montuje gałęzi samodzielnie; utrzymuj ją zgodną z rzeczywistym mapowaniem UseDoconut() i klientem BasePath.
ResourcesPath"/doconut-res"Skąd serwowane są osadzone zasoby JS/CSS/obrazki.
LicensePath"" (empty string)Ścieżka do pliku licencji. Pusty oznacza przejście do następnego źródła, a następnie automatyczne wyszukiwanie.
LicenseContent"" (empty string)Surowa zawartość licencji — z zmiennej środowiskowej, menedżera tajemnic lub bazy danych.
LicenseStreamnullLicencja jako strumień, odczytana raz przy uruchomieniu.
ResetLicensefalseZarezerwowany znacznik kompatybilności. Bieżące usługi .NET 6 odczytują licencję podczas AddDoconut(); uruchom aplikację ponownie po wymianie licencji.
MaxConcurrentEditorSessions200Maksymalna liczba aktywnych sesji edytora (dokumentów otwartych za pomocą DocOptions.EditMode). Po przekroczeniu, najstarsza nieużywana sesja edytora jest zamykana. Normalne sesje przeglądarki nie są liczone. 0 lub wartość ujemna oznacza brak limitu.
EditorSnapshotEveryOps50Gdy włączona jest trwałość edytora (AddDoconutEditorPersistence), twórz migawkę dokumentu po każdej N zarejestrowanej zmianie. 0 lub wartość ujemna nigdy nie tworzy migawki w trakcie sesji. Brak efektu, gdy trwałość jest wyłączona.

Priorytet licencji, gdy ustawiono więcej niż jedno źródło: LicenseStream ma pierwszeństwo przed LicenseContent, przed LicensePath, przed automatycznym wyszukiwaniem — zobacz Konfigurację licencji.

csharp
builder.Services.AddDoconut(options =>
{
    options.LicensePath     = "Doconut.Viewer.lic";
    options.MiddlewarePath  = "/doconut";     // koordynuj z mapowaniem aplikacji i BasePath klienta
    options.ResourcesPath   = "/doconut-res"; // skąd serwowane są pliki JS/CSS/obrazy viewer'a
    options.UnsafeMode      = false;          // zachowaj włączone bezpieczeństwo sesji
    options.ShowDoconutInfo = false;
});

Kolejne kroki

Czy ta strona była pomocna?