Konfiguracja licencji

Bez licencji Doconut nadal renderuje dokumenty — każda strona zawiera znak wodny oceny. Ta strona opisuje cztery sposoby dostarczenia licencji oraz dokładny priorytet, gdy ustawionych jest więcej niż jeden.

Cztery sposoby dostarczenia licencji

Istnieją cztery: trzy explicite źródła w DoconutOptions — strumień, surową treść lub ścieżkę do pliku — oraz automatyczne wykrywanie, gdy żadne z nich nie jest ustawione. Gdy ustawionych jest więcej niż jedno, priorytet jest następujący:

LicenseStream ma wyższy priorytet niż LicenseContent, które ma wyższy priorytet niż LicensePath, które ma wyższy priorytet niż auto-search.

Za pomocą ścieżki

LicensePath jest przekazywany do File.Exists dokładnie tak, jak podano. Ścieżka względna jest rozwiązywana względem bieżącego katalogu roboczego procesu — nie folderu projektu, ani folderu, w którym znajduje się Program.cs. Jeśli ścieżka nie zostanie znaleziona, Doconut nie zgłasza wyjątku i nie przechodzi do auto-wyszukiwania — po prostu nie ładuje licencji i podgląd zostaje oznaczony znakiem wodnym. Auto-wyszukiwanie uruchamia się tylko wtedy, gdy żadne z LicensePath, LicenseContent ani LicenseStream nie jest ustawione. Pliki licencji per‑plugin w tym samym folderze (Doconut.Viewer.<Capability>.lic) są odczytywane razem z nimi, więc LicensePath i AddPlugin<...>() działają razem, gdy licencje wtyczek znajdują się obok licencji podstawowej.

Zaleca się użycie ścieżki bezwzględnej (na przykład zbudowanej z IWebHostEnvironment.WebRootPath lub AppContext.BaseDirectory), lub całkowite pominięcie LicensePath i poleganie na automatycznym wykrywaniu poniżej.

builder.Services.AddDoconut(options =>
{
    options.LicensePath = Path.Combine(AppContext.BaseDirectory, "wwwroot", "Doconut.Viewer.lic");
});

Za pomocą strumienia

LicenseStream jest odczytywany raz przy uruchomieniu — przydatny, gdy licencja pochodzi z tajnego magazynu, a nie z pliku na dysku.

// Priorytet: LicenseStream > LicenseContent > LicensePath > auto-search.
builder.Services.AddDoconut(options =>
{
    options.LicenseStream = licenseStream;
});

Za pomocą treści

LicenseContent przyjmuje samą treść licencji — z zmiennej środowiskowej, bazy danych lub menedżera tajemnic:

// XML licencji z bazy danych, zmiennej środowiskowej lub menedżera tajemnic —
// brak pliku na dysku. Pokonany tylko przez LicenseStream.
builder.Services.AddDoconut(options =>
{
    options.LicenseContent = Environment.GetEnvironmentVariable("DOCONUT_LICENSE") ?? "";
});

Automatyczne wykrywanie

Skonfiguruj żadne z trzech explicite źródeł, a Doconut samodzielnie wyszukuje licencję:

// Nie konfigurować nic, a Doconut wyszukuje licencję samodzielnie, tylko w tych dwóch folderach:
//   1. {CurrentDirectory}/wwwroot
//   2. {AppContext.BaseDirectory}/wwwroot   (wwwroot wewnątrz folderu wyjściowego kompilacji)
// Najpierw szuka Doconut.lic, potem Doconut.Viewer.lic, oraz wszelkich per‑plugin
// // plików Doconut.Viewer.<Capability>.lic obok niego.
builder.Services.AddDoconut();

Foldery przeszukiwania, w kolejności, oraz nazwy plików poszukiwane w każdym z nich:

1. {CurrentDirectory}/wwwroot
2. {AppContext.BaseDirectory}/wwwroot

Filenames (checked in each folder above, in order):
  Doconut.lic                          — base viewer license (checked first)
  Doconut.Viewer.lic                   — base viewer license
  Doconut.Viewer.<Capability>.lic      — per-plugin license, alongside the base license

Nic poza folderem wwwroot nie jest odczytywane: .lic w samym folderze wyjściowym lub w wwwroot/lib jest ignorowane.

Skopiuj licencję do folderu wyjściowego

Jeśli proces nie uruchamia się z folderu projektu — opublikowana aplikacja, IIS, kontener, uruchamiacz testów — pierwsze przeszukiwanie nie znajduje pliku, a drugie, {AppContext.BaseDirectory}/wwwroot, musi go znaleźć. Własna aplikacja testowa SDK kopiuje licencje tam przy każdym buildzie przy użyciu tego celu MSBuild:

<Target Name="CopyLicensesToOutput" AfterTargets="Build">
  <ItemGroup>
    <DoconutLicenseFiles Include="$(MSBuildProjectDirectory)\wwwroot\*.lic" />
    <StaleOutputLicenses Include="$(OutDir)wwwroot\*.lic" />
  </ItemGroup>
  <!-- Delete first, so renaming or removing a .lic in wwwroot also takes it out of the output. -->
  <Delete Files="@(StaleOutputLicenses)" />
  <Copy SourceFiles="@(DoconutLicenseFiles)" DestinationFolder="$(OutDir)wwwroot" />
</Target>

Docelowy folder musi być $(OutDir)wwwroot: .lic skopiowany do katalogu wyjściowego nigdy nie zostanie znaleziony przez auto-wyszukiwanie. Przykłady LicensePath na tej stronie wskazują to samo miejsce.

Trzymaj pliki .lic poza kontrolą wersji — wdrażaj je razem z aplikacją lub wstrzykuj licencję poprzez LicenseContent lub LicenseStream z twojego magazynu tajemnic.

Co się dzieje bez licencji

Brak licencji nie powoduje wyjątku. AddDoconut() kończy się sukcesem, aplikacja się uruchamia, a przeglądarka działa — ale każda strona zawiera znak wodny wersji ewaluacyjnej i nie przyznano żadnych opcjonalnych funkcji.

Plik licencji, który zostaje znaleziony, ale odrzucony, to inna sytuacja. Nieprawidłowy podpis, manipulacja, wpisanie na czarną listę lub kompilacja poza okresem wersji licencji powodują, że OpenDocumentAsync zgłasza LicenseException z License.RejectionMessage. Licencja wygasła kalendarzowo, ale nie posiada komunikatu odrzucenia, kontynuuje działanie w trybie z znakiem wodnym.

Wtyczki wymagają uprawnień

Rejestrowanie wtyczki bez odpowiadającego uprawnienia jest inne: w przypadku braku licencji, starszego pliku TRIAL lub płatnej licencji bez tej funkcji, AddDoconut() zgłasza InvalidOperationException, więc aplikacja się nie uruchamia. Na przykład rejestracja wtyczki Converter bez licencji przyznającej Converter:

InvalidOperationException: 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.

Komunikat podaje rozwiązanie bezpośrednio: albo usuń wywołanie options.AddPlugin<...>() dla tej wtyczki, albo zainstaluj płatną licencję lub aktywną licencję tymczasową/Demo (NFR), która przyznaje tę funkcję. Rejestracje tymczasowe mogą przetrwać datę wygaśnięcia, dzięki czemu już skonfigurowana aplikacja może degradować się w czasie działania zamiast awarii przy ponownym uruchomieniu; po wygaśnięciu ich uprawnienia są nadal cofane.

Zweryfikuj załadowaną licencję

Użyj IDoconutLicenseService, tego samego źródła prawdy używanego przez SDK, aby udostępnić uwierzytelniony punkt diagnostyczny lub sterować flagami funkcji. Nie zwracaj treści licencji ani kluczy.

app.MapGet("/api/doconut/license", (IDoconutLicenseService license) => Results.Ok(new
{
    viewer = license.IsViewerLicensed || license.IsTemporary,
    temporary = license.IsTemporary,
    search = license.IsCapabilityGranted(LicenseCapability.Search),
    annotation = license.IsCapabilityGranted(LicenseCapability.Annotation),
    converter = license.HasConverter,
    dicom = license.HasDicom
}));

Licencja jest odczytywana podczas rejestracji AddDoconut(). ResetLicense jest obecnie właściwością kompatybilności bez aktywnej ścieżki przeładowania, więc zastąpienie pliku licencji wymaga ponownego uruchomienia aplikacji.

Macierz rozwiązywania problemów

Kolejne kroki

• Licencjonowanie — możliwości, poziomy licencji i weryfikacja tego, co zostało załadowane w czasie działania.
• Rozwiązywanie problemów — znaki wodne, odrzucone licencje i błędy uprawnień.