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ż jedna.

Licencja jest ładowana jednokrotnie, podczas AddDoconut(). To zmiana w porównaniu do poprzedniej biblioteki .NET Standard, gdzie licencja była przekazywana do instancji Viewer lub ustawiana poprzez statyczne wywołania Viewer.DoconutLicense(...) / Viewer.SetLicensePlugin(...). Te metody nie są mechanizmem startowym w tej wersji — zobacz przewodnik migracji.

Cztery sposoby dostarczenia licencji

Istnieją cztery: trzy jawne ź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 więcej niż jedno, priorytet jest następujący:

LicenseStream przeważa nad LicenseContent przeważa nad LicensePath przeważa nad automatycznym wyszukiwaniem.

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 automatycznego wyszukiwania — po prostu nie ładuje licencji i podgląd zostaje oznaczony znakiem wodnym. Automatyczne wyszukiwanie uruchamia się tylko wtedy, gdy żadne z LicensePath, LicenseContent lub LicenseStream nie jest ustawione. Pliki licencji per‑plugin w tym samym folderze (Doconut.Viewer.<Capability>.lic) są odczytywane razem z nim, więc LicensePath i AddPlugin<...>() działają razem, gdy licencje wtyczek znajdują się obok licencji podstawowej.

Preferuj ścieżkę bezwzględną (na przykład zbudowaną z IWebHostEnvironment.WebRootPath lub AppContext.BaseDirectory), lub całkowicie pomiń LicensePath i polegaj 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 jednorazowo przy uruchomieniu — przydatny, gdy licencja pochodzi z tajnego magazynu, a nie z pliku na dysku.

// Priorytet: LicenseStream > LicenseContent > LicensePath > auto-wyszukiwanie.
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:

// XML licencji z bazy danych, zmiennej środowiskowej lub menedżera sekretów —
// brak pliku na dysku. Zastępowany jedynie przez LicenseStream.
builder.Services.AddDoconut(options =>
{
    options.LicenseContent = Environment.GetEnvironmentVariable("DOCONUT_LICENSE") ?? "";
});

Automatyczne wykrywanie

Nie skonfiguruj żadnego z trzech jawnych źródeł, a Doconut samodzielnie wyszukuje licencję:

// Nie konfiguruj niczego, a Doconut sam wyszukuje licencję, 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 plików specyficznych dla danej możliwości
// pliki Doconut.Viewer.<Capability>.lic obok niego.
builder.Services.AddDoconut();

Foldery przeszukiwane, 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-capability license, alongside the base license

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

Jeśli wcześniej przekazałeś List<string> ścieżek licencji do konstruktora Viewer — po jednej na możliwość — zachowaj te pliki towarzyszące obok Doconut.Viewer.lic i pozwól automatycznemu wykrywaniu je pobrać. Opcja listy ścieżek nie istnieje w DoconutOptions.

Skopiuj licencję do folderu wyjściowego

Gdy proces nie uruchamia się z folderu projektu — opublikowana aplikacja, IIS, kontener, uruchamiacz testów — pierwsze sprawdzenie nie udaje się, a drugie, {AppContext.BaseDirectory}/wwwroot, musi znaleźć plik. Własna aplikacja testowa SDK kopiuje licencje tam przy każdym buildzie za pomocą tego celu MSBuild:

<Target Name="CopyLicensesToOutput" AfterTargets="Build">
  <ItemGroup>
    <DoconutLicenseFiles Include="$(MSBuildProjectDirectory)\wwwroot\*.lic" />
    <StaleOutputLicenses Include="$(OutDir)wwwroot\*.lic" />
  </ItemGroup>
  <!-- Najpierw usuń, aby zmiana nazwy lub usunięcie .lic w wwwroot również wykluczyło go z wyjścia. -->
  <Delete Files="@(StaleOutputLicenses)" />
  <Copy SourceFiles="@(DoconutLicenseFiles)" DestinationFolder="$(OutDir)wwwroot" />
</Target>

Miejsce docelowe musi być $(OutDir)wwwroot: .lic skopiowany do katalogu wyjściowego nigdy nie zostanie znaleziony przez automatyczne 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ę przez 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 ma znak wodny oceny i nie przyznano żadnych opcjonalnych funkcji.

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

Wtyczki wymagają uprawnień

Rejestrowanie wtyczki bez odpowiadającego uprawnienia jest inne: przy brakującej licencji, starszym pliku TRIAL lub płatnej licencji bez tej funkcji, AddDoconut() rzuca 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 od razu: albo usuń wywołanie options.AddPlugin<...>() dla tej wtyczki, albo zainstaluj płatną licencję lub aktywną licencję Tymczasową/Demonstracyjną (NFR), która przyznaje tę funkcję. Tymczasowe rejestracje mogą przetrwać po dacie wygaśnięcia, aby już skonfigurowana aplikacja mogła przejść w tryb degradacji 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 zamiana pliku licencji wymaga ponownego uruchomienia aplikacji.

Macierz rozwiązywania problemów

Następne 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 związane z możliwościami.