DoconutExtensions

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.UseDoconutResources(); // BEFORE UseDoconut()
app.UseDoconut();

AddDoconut

IServiceCollection AddDoconut(this IServiceCollection services, Action<DoconutOptions>? configure = null)

Tworzy DoconutOptions, waliduje je natychmiastowo (zobacz DoconutOptions → Walidacja uruchamiania) i rejestruje pełny graf usług:

Nie ma równoważnego wywołania w poprzedniej bibliotece .NET Standard. Biblioteka budowała new Viewer(cache, accessor) przy każdym żądaniu i przekazywała opcje do middleware; oba te elementy zostały zastąpione jedną rejestracją.

Dwa zachowania warte poznania:

• Konwerter wymaga swojego pluginu. Rozwiązywanie DocumentConverter bez options.AddPlugin<ConverterPlugin>() powoduje wyrzucenie:

InvalidOperationException: No IDocumentConverter is registered. Add the converter plugin: options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>().

• Uprawnienia pluginu są walidowane przy uruchamianiu. Brak licencji, starszy plik TRIAL lub płatna licencja bez zarejestrowanej możliwości pluginu powodują błąd w czasie wywołania AddDoconut(). Rejestracje tymczasowe/Demo przetrwają po upływie daty ważności, natomiast 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 mieć stan licencji w swoim endpointzie zdrowia:

app.MapHealthChecks("/health");

UseDoconut

IApplicationBuilder UseDoconut(this IApplicationBuilder app)

Dodaje middleware Doconut obsługujący obrazy stron. Odpowiada na każde żądanie zawierające parametr zapytania ?token= — strony, miniatury, wyszukiwanie, annotacje, akcje stron (pełna tabela żądań znajduje się w Core Concepts → How the Viewer Works). Gdy UnsafeMode jest ustawione na false, warstwa zabezpieczeń dokumentu jest automatycznie podłączana przed nim.

Nie przyjmuje żadnych argumentów. Przekazywanie tutaj instancji DoconutOptions było kształtem poprzedniej biblioteki i już nie kompiluje się.

Przykładowy kod referencyjny kieruje żądania widgetu przez gałąź ścieżki, zachowując historyczny kształt żądania:

app.MapWhen(
    ctx => ctx.Request.Path.Value?.EndsWith("DocImage.axd", StringComparison.OrdinalIgnoreCase) == true,
    branch => branch.UseDoconut());

UseDoconutResources

IApplicationBuilder UseDoconutResources(this IApplicationBuilder app)

Udostępnia 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 pokazuje 404 dla /doconut-res/..., to wywołanie jest brakujące lub umieszczone w niewłaściwym miejscu.

Jest to wspierane zastąpienie ręcznego podłączania middleware obsługującego zasoby osadzone przy pomocy app.UseMiddleware<EmbeddedResourceMiddleware>().

Serving from shared storage

Dwie dodatkowe rejestracje istnieją dla wdrożeń, w których węzeł renderujący dokument nie jest koniecznie tym, który serwuje jego strony. Obie są omówione od początku do końca w Distributed Deployments; ich sygnatury to:

IServiceCollection AddDoconutDistributedAsyncPublish(...)   // opt-in background publish queue
IServiceCollection AddDoconutDistributedWidgets(...)        // shared backing store for widget uploads

Strona odczytu jest osobnym middleware z pakietu Doconut.Clouds:

IApplicationBuilder UseDoconutCloud<THandler>(
    this IApplicationBuilder app,
    Action<CloudOptions>? configure = null,
    string pathPrefix = "/doconut-cloud")
    where THandler : BaseCloudHandler

UseDoconutWebFarm(...) i WebFarmOptions nie istnieją w tej wersji. Zobacz migration guide po szczegółowe mapowanie ustawień.

Ordering recap

app.UseRouting();
app.UseSession();          // required when UnsafeMode = false
app.UseDoconutResources(); // 1st Doconut call
app.UseDoconut();          // 2nd Doconut call (or via a MapWhen branch)