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 jednorazowo, podczas AddDoconut(). Jest to zmiana w stosunku do poprzedniej biblioteki .NET Standard, w której licencję przekazywano do instancji Viewer lub ustawiano za pomocą statycznych wywołań Viewer.DoconutLicense(...) / Viewer.SetLicensePlugin(...). Te metody nie są mechanizmem uruchamiania w tej wersji — zobacz przewodnik migracji.

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 przeważa LicenseContent przeważa LicensePath przeważa automatyczne wyszukiwanie.

Według ś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, 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 żadnej licencji, a przeglądarka wyświetla znak wodny. Automatyczne 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 tym, więc LicensePath i AddPlugin<...>() współpracują, gdy licencje pluginów znajdują się obok licencji bazowej.

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

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

Według strumienia

LicenseStream jest odczytywany jednorazowo przy uruchomieniu — przydatny, gdy licencja pochodzi z magazynu sekretów, a nie z pliku na dysku.

// Priorytet: LicenseStream > LicenseContent > LicensePath > automatyczne wyszukiwanie.
builder.Services.AddDoconut(options =>
{
    options.LicenseStream = licenseStream;
});

Według treści

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

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

Automatyczne wykrywanie

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

// Nie konfigurować nic, a Doconut samodzielnie 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 możliwości
// 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

Nazwy plików (sprawdzane w każdym folderze powyżej, w kolejności):
  Doconut.lic                          — licencja podstawowego przeglądarki (sprawdzana jako pierwsza)
  Doconut.Viewer.lic                   — licencja podstawowego przeglądarki
  Doconut.Viewer.<Capability>.lic      — licencja specyficzna dla możliwości, obok licencji podstawowej

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

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

Skopiuj licencję do folderu wyjściowego

When the process does not run from the project folder — a published app, IIS, a container, a test runner — the first probe misses, and the second one, {AppContext.BaseDirectory}/wwwroot, has to find the file. The SDK's own test app copies the licenses there on every build with this MSBuild target:

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

The destination must be $(OutDir)wwwroot: a .lic copied to the output root is never found by auto-search. The LicensePath examples on this page point at the same place.

Keep .lic files out of source control — deploy them alongside the app, or inject the license through LicenseContent or LicenseStream from your secret store.

Co się dzieje bez licencji

A missing license does not throw. AddDoconut() succeeds, the app starts, and the viewer runs — but every page carries an evaluation watermark and no optional capability is granted.

A license file that is found but rejected is different. An invalid signature, tampering, blacklisting, or a build outside the license's version window causes OpenDocumentAsync to throw LicenseException with License.RejectionMessage. A calendar-expired license that has no rejection message continues in watermarked mode.

Wtyczki wymagają uprawnień

Registering a plugin with no corresponding entitlement is different: for a missing license, a legacy TRIAL file, or a paid license without that capability, AddDoconut() throws InvalidOperationException, so the app does not start. For example, registering the Converter plugin without a license that grants 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.

The message tells you the fix directly: either remove the options.AddPlugin<...>() call for that plugin, or install a paid license or an active Temporary/Demo (NFR) license that grants the capability. Temporary registrations are allowed to survive their expiry date so an already configured app can degrade at runtime instead of crashing during restart; once expired, their capabilities are still revoked.

Zweryfikuj załadowaną licencję

Use IDoconutLicenseService, the same source of truth used by the SDK, to expose an authenticated diagnostic endpoint or to drive feature flags. Do not return license contents or keys.

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
}));

The license is read during AddDoconut() registration. ResetLicense is currently a compatibility property with no active reload path, so replacing a license file requires restarting the application.

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 możliwości.