Instalacja

Dodaj Doconut do swojego projektu .NET Standard 2.1

Podstawowa przeglądarka Doconut dla .NET Standard jest dostarczana jako pojedynczy pakiet NuGet, który podłącza się do dowolnej aplikacji ASP.NET Core. Opcjonalne wtyczki używają oddzielnych pakietów. Ta strona instaluję podstawowy pakiet, potwierdza, że Twój host może go używać, i rejestruje middleware — minimalne wymagania przed pierwszym renderowaniem.

Sprawdź najpierw framework hosta

Biblioteka celuje w netstandard2.1. To węższy kontrakt niż poprzednia wersja netstandard2.0 i jest to pierwsza rzecz do zweryfikowania:

HostObsługiwane
.NET Core 3.0 lub nowszy, w tym .NET 5/6/7/8Tak
.NET Framework (dowolna wersja)Nie — netstandard2.1 nie może być używany przez .NET Framework

Pakiet działa wyłącznie na Windows. Dla hosta Linux użyj Doconut.NET8 lub Doconut.NET6.

Jeśli aplikacja działa na .NET Framework, to nie jest właściwy pakiet. Użyj Doconut.NETFramework zamiast tego; od wersji 26.9.0 wymaga .NET Framework 4.7.2.

Zainstaluj pakiet

bash
dotnet add package Doconut.NETStandard

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

bash
dotnet add package Doconut.NETStandard --version 26.10.0

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

Numer wersji określa generację

To ma większe znaczenie tutaj niż nazwa pakietu. Obie generacje biblioteki .NET Standard publikowane są pod tym samym identyfikatorem pakietu, a tylko wersja je odróżnia:

WersjaCelAPI
26.7.0 i niżejnetstandard2.0poprzednia integracja
26.8.0 i wyżejnetstandard2.1integracja opisana tutaj

Nie ma warstwy kompatybilności ani pakietu równoległego. Zwiększenie wersji jest aktualizacją, a kompilator natychmiast zgłosi różnice w API.

Nie wybieraj dokumentacji wyłącznie na podstawie nazwy pakietu:

  • new Viewer(_cache, _accessor, …), UnSafeMode, synchroniczny OpenDocument(...), viewer.InitCache(), UseDoconutWebFarm, oraz ręcznie skopiowane skrypty przeglądarki identyfikują poprzednią integrację;
  • AddDoconut(), UseDoconutResources(), wstrzyknięty Viewer oraz OpenDocumentAsync(...) identyfikują bieżącą integrację opisaną tutaj.

Przetłumaczony poprzedni podręcznik konfiguracji pozostaje dostępny. Użyj przewodnika migracji, aby zmienić generacje; 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 i 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 uruchomić się 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 na własnej 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());

Przestrzenie nazw

Typy konfiguracyjne nie są już rozproszone po czterech przestrzeniach nazw. W tym wydaniu prawie wszystko znajduje się w głównej przestrzeni nazw Doconut:

csharp
using Doconut;                       // Viewer, DoconutOptions, DocOptions, wszystkie konfiguracje formatów
using Doconut.Middleware;            // AddDoconut, UseDoconut, UseDoconutResources
using Doconut.Clouds;                // konfiguracje chmury i udostępniania plików
using Doconut.Configs.Conversion;    // ConversionTarget

Nazwy typów same w sobie nie uległy zmianie — PdfConfig, WordConfig, ExcelConfig, CssConfig, ScriptConfig i reszta nadal istnieją. Jeśli przenosisz istniejącą aplikację, większość plików wymaga jedynie dwóch usuniętych linii using; zobacz przewodnik migracji.

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 jest ustawiona.

WłaściwośćDomyślnaOpis
ShowDoconutInfofalseGdy true, żądanie bez token zwraca baner wersji zamiast 404. Przydatne jako szybka kontrola; wyłącz w środowisku produkcyjnym.
UnsafeModefalseGdy true, pomija sprawdzanie bezpieczeństwa sesji ASP.NET przy żądaniach stron. Wyłącz w produkcji. Zwróć uwagę na pisownię — poprzednia biblioteka nazywała to UnSafeMode.
MiddlewarePath"/doconut"Wartość koordynacji dla punktu końcowego page-image. Jest walidowana, ale nie montuje własnej gałęzi; utrzymuj ją zgodną z rzeczywistym mapowaniem UseDoconut() oraz klientem BasePath.
ResourcesPath"/doconut-res"Skąd serwowane są osadzone zasoby JS/CSS/obrazki.
LicensePath"" (empty string)Ścieżka do pliku licencji. Pusty ciąg oznacza przejście do następnego źródła, a następnie auto‑wyszukiwanie.
LicenseContent"" (empty string)Surowa zawartość licencji — z zmiennej środowiskowej, menedżera sekretów lub bazy danych.
LicenseStreamnullLicencja jako strumień, odczytywana raz przy uruchomieniu.
ResetLicensefalseZarezerwowany znacznik kompatybilności. Licencja jest odczytywana podczas AddDoconut(); uruchom aplikację ponownie po wymianie licencji.
MaxConcurrentEditorSessions200Maksymalna liczba aktywnych sesji edytora (dokumenty otwarte przy użyciu DocOptions.EditMode). Po przekroczeniu, najdłużej 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 migawki żywego dokumentu co N zarejestrowanych zmian. 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 auto‑wyszukiwaniem — zobacz Konfiguracja 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ą JS/CSS/obrazy viewer
    options.UnsafeMode      = false;          // zachowaj bezpieczeństwo sesji
    options.ShowDoconutInfo = false;
});

Kolejne kroki

Czy ta strona była pomocna?