System wtyczek

Rozszerz przeglądarkę o wtyczki

Rdzeń Doconut pozostaje lekki; opcjonalna funkcjonalność jest dostarczana jako wtyczki — oddzielne pakiety NuGet, które dostarczają przeglądarki lub usługi i są włączane na podstawie Twojej licencji. Ta strona wyjaśnia model rejestracji, co się dzieje przy uruchamianiu, gdy licencja nie obejmuje wtyczki, oraz jak podłączyć własną przeglądarkę.

Rejestrowanie wtyczki

Każdy pakiet wtyczki udostępnia jedną klasę wtyczki. Zarejestruj ją raz, w Application_Start:

csharp
Doconut.DoconutHost.Initialize(options =>
{
    options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
    options.AddPlugin<Doconut.Plugins.Dicom.DicomPlugin>();
});
// Zarejestrowana wtyczka, której licencja jest brakująca, rzuca tutaj, w Application_Start, i
// strona następnie odpowiada na każde żądanie pustym kodem 500. Powód znajduje się w dzienniku zdarzeń Windows.

AddPlugin<TPlugin>() tworzy wtyczkę i pozwala jej zarejestrować swoje wkłady przy użyciu DoconutOptions. Wszystko, co wtyczka wnosi, jest oznaczone wymagana zdolność wtyczki, a DoconutHost.Initialize sprawdza każdą zarejestrowaną wtyczkę względem licencji przed obsłużeniem pierwszego żądania przez witrynę.

Brak licencji na wtyczkę zatrzymuje witrynę

Gdy żadna aktywna licencja nie przyznaje zdolności zarejestrowanej wtyczki — brak licencji, starszy plik TRIAL, lub płatna licencja bez tej zdolności — DoconutHost.Initialize wyrzuca InvalidOperationException z Application_Start:

text
The Converter plugin is registered via AddPlugin but no active license grants Converter.
Remove the AddPlugin<...>() call or install a license (or trial/demo) that includes Converter.

W System.Web, wyjątek w Application_Start nie generuje strony błędu. Każde żądanie zwraca pusty 500, dziennik IIS nie pokazuje nic przydatnego, a komunikat pojawia się tylko w dzienniku zdarzeń Windows (dziennik aplikacji, źródło ASP.NET). Gdy witryna przestaje odpowiadać zaraz po dodaniu linii AddPlugin, najpierw sprawdź pliki licencji w wwwroot — zobacz Konfiguracja licencji.

Umowa

Wtyczka implementuje celowo mały interfejs:

csharp
public interface IDoconutPlugin
{
    string Name { get; }                          // np. "Doconut DICOM Viewer"
    LicenseCapability RequiredCapability { get; } // brama licencyjna
    void Register(IDoconutPluginBuilder builder); // dodaj przeglądarki/usługi
}

Wewnątrz Register, konstruktor akceptuje dwa rodzaje wkładu:

  • builder.RegisterViewer(extension, factory) — przeglądarka dla rozszerzenia pliku; fabryka zwraca IFormatViewer (wtyczka DICOM rejestruje .dcm i .ima w ten sposób),
  • builder.RegisterService<TContract>(() => …) — typowana usługa, którą inne części potoku mogą wyszukać.

Zdolności i ograniczenia

Zdolności są jednostkami licencyjnymi. Converter, Dicom i Signer są dostarczane jako wtyczki opcjonalne; Search i Annotation to wbudowane funkcje ograniczane w ten sam sposób. Podstawowa przeglądarka nie jest zdolnością — jest warunkiem wstępnym, udostępnianym jako IsViewerLicensed w usłudze licencji.

Walidacja przy uruchamianiu zazwyczaj trzyma nielicencjonowaną wtyczkę poza potokiem żądań. Fabryka przeglądarki stosuje również dwie zasady obronne, które mają znaczenie, jeśli uprawnienia zmieniają się w trakcie działania witryny:

  • Wtyczka, która nadpisuje wbudowaną przeglądarkę (twierdzi, że obsługuje rozszerzenie, które obsługuje również wbudowana przeglądarka): przy licencjonowanej zdolności przeglądarka wtyczki wygrywa; bez niej Doconut przełącza się na wbudowaną przeglądarkę. Użytkownicy nadal widzą swój dokument; po prostu nie otrzymują zachowania wtyczki.
  • Format dostępny tylko w wtyczce (.dcm i .ima — DICOM nie ma wbudowanej przeglądarki): bez zdolności otwieranie kończy się niepowodzeniem:
text
LicenseException: This document type requires the 'Dicom' plugin license.

Aktywna tymczasowa licencja przyznaje wszystkie zdolności. To klasyczna niespodzianka przy uruchomieniu: te same linie AddPlugin, które działały podczas oceny, zatrzymują witrynę, gdy zakupiona licencja pomija jedną z tych zdolności. Porównaj IsCapabilityGranted(...) z tym, co kupiłeś przed wdrożeniem. Przy braku jakiejkolwiek licencji, nic nie jest przyznane — brak licencji nie jest tymczasową licencją.

To samo ograniczenie dociera do przeglądarki: Viewer.ReferenceScripts() i ReferenceCss() emitują pliki dla funkcji ograniczonych licencją (Search, Annotation) tylko gdy licencja je przyznaje, więc strona nigdy nie oferuje funkcji, którą serwer odmówi.

Mapa funkcji i wtyczek

FunkcjaJak jest włączaneZdolnośćWnosi
AnnotationWbudowane w przeglądarkę; zawiera zasoby adnotacjiAnnotationTworzenie w przeglądarce, utrzymanie sesji, eksporty wbudowane
SearchWbudowane w przeglądarki formatów przeszukiwalnych; zawiera zasoby wyszukiwaniaSearchNatywny indeks tekstu, podświetlenia, nawigacja wyników
ConverterZainstaluj Doconut.NETFramework.Converter i zarejestruj ConverterPluginConverterUsługa konwersji C# oraz opcjonalny widget internetowy
DICOMZainstaluj Doconut.NETFramework.Dicom i zarejestruj DicomPluginDicomWyświetlanie obrazów medycznych dla .dcm i .ima
SignerZainstaluj Doconut.NETFramework.Signer i zarejestruj SignerPluginSignerWidoczne podpisy i cyfrowe pieczęcie dla PDF i Word: usługa podpisywania C# oraz opcjonalny widget internetowy

Annotation i Search nie używają AddPlugin<TPlugin>(). Converter, DICOM i Signer mają każda stronę w sekcji Plugins z ich konfiguracją i użyciem. W tym pakiecie DICOM renderuje strony, ramki i animacje, ale nie odczytuje metadanych technicznych — zobacz Wtyczka DICOM.

Niestandardowe przeglądarki — Twój własny obsługiwacz formatu

Możesz podłączyć przeglądarkę do potoku bez tworzenia pakietu wtyczki, bezpośrednio w Application_Start:

csharp
Doconut.DoconutHost.Initialize(options =>
{
    options.RegisterViewer(
        ".myext",
        () => new MyCustomViewer(),                        // implementuje IFormatViewer
        () => new ImageConfig { ImageResolution = 150 });  // opcjonalna domyślna konfiguracja
});

// Obsługa formatu tworzona przez fabrykę. Zastąp te elementy własnym renderowaniem.
public sealed class MyCustomViewer : Doconut.Core.Interfaces.IFormatViewer
{
    public ViewerType ViewerType => ViewerType.None;
    public int TotalPages => 0;
    public int DefaultWidth => 0;
    public int DefaultHeight => 0;
    public bool PreferOcr => false;

    public Task LoadAsync(Stream documentStream, BaseConfig config, CancellationToken ct = default)
        => Task.CompletedTask;

    public Task<byte[]> GetPageImageAsync(int pageNumber, CancellationToken ct = default)
        => Task.FromResult(Array.Empty<byte>());

    public void Dispose() { }
}

Niestandardowe przeglądarki mają pierwszeństwo przed wszystkim — zarówno wbudowanymi, jak i wtyczkami — i nie są ograniczane licencją: to Twój kod. Gdy nie dostarczysz domyślnej konfiguracji, fabryka używa ImageConfig.

Wnioski

  • Wtyczki są rejestrowane jawnie w DoconutHost.Initialize, a ich zdolności są tam weryfikowane; brak uprawnienia zatrzymuje witrynę z pustym 500, którego przyczyna znajduje się w dzienniku zdarzeń Windows.
  • Wtyczki typu override działają łagodnie; formaty dostępne tylko w wtyczkach kończą się niepowodzeniem z LicenseException.
  • Aktywna tymczasowa licencja odblokowuje wszystko; produkcyjna odblokowuje to, co kupiłeś. Sprawdź z IDoconutLicenseService przed wypuszczeniem.

Czy ta strona była pomocna?