Konfiguracja licencji

Bez licencji Doconut nadal renderuje dokumenty — każda strona jest oznaczona znakiem wodnym oceny. Ta strona opisuje cztery sposoby dostarczania licencji oraz dokładny porządek priorytetów, gdy ustawionych jest ich więcej niż jeden.

Cztery sposoby dostarczania licencji

Istnieją cztery: trzy explicite źródła w DoconutOptions — strumień, surowa treść lub ścieżka do pliku — oraz automatyczne wykrywanie, gdy żadne z nich nie jest ustawione. Gdy ustawionych jest ich 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 względem folderu projektu i nie względem 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 automatycznego wyszukiwania — po prostu nie ładuje licencji, a podgląd zostaje oznaczony znakiem wodnym. Automatyczne wyszukiwanie uruchamia się tylko wtedy, gdy żadne z LicensePath, LicenseContent ani LicenseStream nie jest ustawione.

Preferuj ścieżkę bezwzględną (np. zbudowaną z IWebHostEnvironment.WebRootPath lub AppContext.BaseDirectory), albo całkowicie pomiń LicensePath i polegaj na automatycznym wykrywaniu poniżej.

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

Za pomocą strumienia

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

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

Za pomocą treści

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

// License XML from a database, environment variable, or secret manager —
// no file on disk. Beaten only by LicenseStream.
builder.Services.AddDoconut(options =>
{
    options.LicenseContent = Environment.GetEnvironmentVariable("DOCONUT_LICENSE") ?? "";
});

Automatyczne wykrywanie

Nie konfiguruj żadnego z trzech explicite źródeł, a Doconut sam wyszuka licencję:

// Configure nothing, and Doconut searches for the license itself:
//   1. {CurrentDirectory}/wwwroot
//   2. {CurrentDirectory}/wwwroot/lib
//   3. AppContext.BaseDirectory  (the build output folder)
// It looks for Doconut.Viewer.lic plus any per-plugin
// Doconut.Viewer.<Capability>.lic files alongside it.
builder.Services.AddDoconut();

Katalogi przeszukiwania, w kolejności, oraz nazwy plików, które są w nich poszukiwane:

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

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

Skopiuj licencję do folderu wyjściowego

LicensePath oraz przeszukiwanie AppContext.BaseDirectory w trybie automatycznym wymagają, aby plik .lic znajdował się obok zbudowanej aplikacji — nie tylko w źródłowym wwwroot. Testowa aplikacja SDK kopiuje go przy każdym buildzie za pomocą tego celu MSBuild:

<Target Name="CopyLicensesToOutput" AfterTargets="Build">
  <ItemGroup>
    <DoconutLicenseFiles Include="$(MSBuildProjectDirectory)\wwwroot\*.lic" />
  </ItemGroup>
  <Copy SourceFiles="@(DoconutLicenseFiles)" DestinationFolder="$(OutDir)" SkipUnchangedFiles="true" />
</Target>

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

Co się dzieje bez licencji

Brak licencji nie powoduje wyjątku. AddDoconut() kończy się powodzeniem, aplikacja się uruchamia, a podgląd działa — ale każda strona jest oznaczona znakiem wodnym oceny i nie przyznano żadnych opcjonalnych uprawnień.

Plik licencji, który zostanie znaleziony, ale odrzucony, to inna sprawa. Nieprawidłowy podpis, manipulacja, czarna lista lub kompilacja poza okresem wersji licencji powodują, że OpenDocumentAsync zgłasza LicenseException z License.RejectionMessage. Licencja wygasła kalendarzowo, której nie ma komunikatu odrzucenia, kontynuuje działanie w trybie znakowanym wodnym.

Wtyczki wymagają uprawnień

Rejestracja wtyczki bez odpowiadającego jej uprawnienia jest inna: przy brakującej licencji, starszym pliku TRIAL lub płatnej licencji bez tego uprawnienia, AddDoconut() zgłasza InvalidOperationException, więc aplikacja się nie uruchamia. 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 podpowiada rozwiązanie od razu: usuń wywołanie options.AddPlugin<...>() dla tej wtyczki albo zainstaluj płatną licencję lub aktywną licencję tymczasową/Demo (NFR), która przyznaje to uprawnienie. Rejestracje tymczasowe mogą przetrwać datę wygaśnięcia, aby już skonfigurowana aplikacja mogła przejść w tryb ograniczony w czasie działania zamiast awarii przy restarcie; po wygaśnięciu ich uprawnienia są nadal cofane.

Zweryfikuj wczytaną 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, co zostało wczytane w czasie działania.
• Rozwiązywanie problemów — znaki wodne, odrzucone licencje i błędy uprawnień.