DoconutExtensions
Rejestracja usług i middleware
DoconutExtensions (namespace Doconut.Middleware) jest statyczną klasą z trzema wywołaniami, które każdy host Doconut wykonuje: jedną rejestrację usługi i dwie rejestracje middleware.
builder.Services.AddDoconut(options => { /* … */ });
// …
app.UseSession(); // wywołaj UseSession() przed UseDoconut()
app.UseDoconutResources(); // musi być zarejestrowane przed UseDoconut()
app.Map("/doconut", branch => branch.UseDoconut());UseDoconut() odpowiada na każde żądanie, które do niego dotrze, więc zamontuj go na własnej gałęzi z app.Map.
AddDoconut
IServiceCollection AddDoconut(this IServiceCollection services, Action<DoconutOptions>? configure = null)Tworzy DoconutOptions, waliduje je natychmiast (zobacz DoconutOptions → walidacja przy starcie) i rejestruje pełny graf usług:
| Usługa | Czas życia | Rola |
|---|---|---|
DoconutOptions | Singleton | Obiekt konfiguracyjny |
| Usługa pamięci podręcznej sesji | Singleton | Token → pamięć podręczna sesji (IMemoryCache jest również zarejestrowany) |
IDoconutLicenseService | Singleton | Licencja ładowana raz przy starcie (priorytet: LicenseStream → LicenseContent → LicensePath → automatyczne wyszukiwanie) |
| Potok obrazów stron | Singleton | Wykonuje przetwarzanie obrazów dla stron (znak wodny, obrót, skalowanie, adnotacje) |
| Bezpieczeństwo dokumentu (magazyn dostępu) | Singleton | Udziela uprawnień do powiązania token‑sesja |
Viewer | Transient | Publiczna fasada otwierania/zamykania |
DocumentConverter | Transient | Fasada konwersji — wymaga wtyczki Converter |
DocumentSigner | Transient | Fasada podpisywania — wymaga wtyczki Signer (zobacz Signer Plugin) |
DistributedDocumentPublisher | Transient | Publikuje artefakty dokumentu w współdzielonym magazynie |
Health check "doconut" | — | Raportuje stan licencji/wygaśnięcia poprzez kontrole zdrowia ASP.NET |
W poprzedniej bibliotece .NET Standard nie ma równoważnego wywołania. Tworzyła ona new Viewer(cache, accessor) na żądanie i przekazywała opcje do middleware; oba są zastąpione tą jedną rejestracją.
Dwa zachowania warte poznania:
- Converter wymaga swojej wtyczki. Rozwiązanie
DocumentConverterbezoptions.AddPlugin<ConverterPlugin>()powoduje wyjątek:
InvalidOperationException: No IDocumentConverter is registered. Add the converter plugin: options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>().DocumentSigner podąża za tą samą zasadą: bez options.AddPlugin<SignerPlugin>() wyrzuca No IDocumentSigner is registered. Add the signing plugin: options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>().
- Uprawnienia wtyczki są weryfikowane przy starcie. Brak licencji, starszy plik
TRIALlub płatna licencja bez zarejestrowanej możliwości wtyczki powoduje niepowodzenie w czasieAddDoconut(). Rejestracje tymczasowe/Demo przetrwają po upływie daty wygaśnięcia, podczas gdy bramki w czasie wykonywania odwołują wygasłe możliwości.
Kontrola zdrowia integruje się ze standardowym mechanizmem ASP.NET Core — zamapuj ją, jeśli chcesz stan licencji na swoim endpointzie zdrowia:
app.MapHealthChecks("/health");UseDoconut
IApplicationBuilder UseDoconut(this IApplicationBuilder app)Dodaje middleware Doconut page-image. Obsługuje każde żądanie zawierające parametr zapytania ?token= — strony, miniatury, wyszukiwanie, adnotacje, akcje stron (pełna tabela żądań znajduje się w Core Concepts → How the Viewer Works) — i odpowiada na każde inne żądanie samodzielnie przy użyciu 404 (lub baneru ShowDoconutInfo): nigdy nie przekazuje żądania dalej w potoku. Zamontuj go na własnej gałęzi, jak w przykładach na tej stronie. Gdy UnsafeMode jest false, warstwa bezpieczeństwa dokumentu jest automatycznie podłączana przed nim.
Nie przyjmuje żadnych argumentów. Przekazanie tutaj instancji DoconutOptions było kształtem poprzedniej biblioteki i już się nie kompiluje.
Typowa konfiguracja zachowuje historyczny kształt żądania DocImage.axd z gałęzią MapWhen (klient następnie używa BasePath: '/'):
app.MapWhen(
ctx => ctx.Request.Path.Value?.EndsWith("DocImage.axd", StringComparison.OrdinalIgnoreCase) == true,
branch => branch.UseDoconut());UseDoconutResources
IApplicationBuilder UseDoconutResources(this IApplicationBuilder app)Serwuje osadzone pliki JS, CSS, obrazy i czcionki pod DoconutOptions.ResourcesPath (domyślnie /doconut-res). Są to pliki, dla których Viewer.ReferenceCss() / ReferenceScripts() generują znaczniki.
Zawsze wywołuj to przed UseDoconut(). Jeśli obszar przeglądarki pozostaje pusty, a konsola przeglądarki wyświetla 404 dla /doconut-res/..., to wywołanie jest brakujące lub źle umieszczone.
To jest wspierane zastępstwo dla ręcznego podłączania middleware obsługującego zasoby osadzone.
Serwowanie ze współdzielonego magazynu
Istnieją dwie dodatkowe rejestracje dla wdrożeń, w których węzeł renderujący dokument nie jest koniecznie węzłem serwującym jego strony. Obie są opisane od początku do końca w Distributed Deployments; sygnatury są następujące:
IServiceCollection AddDoconutDistributedAsyncPublish(this IServiceCollection services, Action<DistributedAsyncPublishOptions>? configure = null) // kolejka publikacji w tle z opcją opt-in
IServiceCollection AddDoconutDistributedWidgets(this IServiceCollection services, Action<DistributedWidgetsOptions> configure) // wspólne repozytorium zapasowe dla przesyłania widgetówStrona odczytu jest oddzielnym middleware z zestawu Doconut.Clouds, który jest dostarczany w tym samym pakiecie:
IApplicationBuilder UseDoconutCloud<THandler>(
this IApplicationBuilder app,
Action<CloudOptions>? configure = null,
string pathPrefix = "/doconut-cloud")
where THandler : BaseCloudHandlerUseDoconutWebFarm(...) i WebFarmOptions nie istnieją w tej wersji. Zobacz migration guide po mapowanie ustawień krok po kroku.
Podsumowanie kolejności
app.UseRouting();
app.UseSession(); // wywołaj UseSession() przed UseDoconut()
app.UseDoconutResources(); // musi być zarejestrowane przed UseDoconut()
app.Map("/doconut", branch => branch.UseDoconut()); // lub gałąź MapWhenCzy ta strona była pomocna?