Konfiguracja licencji

Bez licencji Doconut nadal renderuje dokumenty — każda strona po prostu 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ń, 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, które przeważa nad LicensePath, które przeważa nad auto-search.

Po ścieżce

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 i nie folderu, w którym znajduje się Program.cs. Jeśli ścieżka nie zostanie rozwiązana, Doconut nie zgłasza wyjątku i nie przechodzi do automatycznego wyszukiwania — po prostu nie ładuje żadnej licencji, a przeglądarka dodaje znak wodny. Automatyczne wyszukiwanie uruchamia się tylko wtedy, gdy żadne z LicensePath, LicenseContent ani LicenseStream nie jest ustawione.

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, "Doconut.Viewer.lic");
});

Po strumieniu

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

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

Po 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 skonfiguruj żadnego z trzech explicite źródeł, a Doconut sam wyszukuje 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 auto-wyszukiwaniu wymagają, aby plik .lic znajdował się obok zbudowanej aplikacji — nie tylko w twoim źródłowym wwwroot. Testowa aplikacja SDK kopiuje go przy każdym buildzie przy użyciu 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 twojego tajnego magazynu.

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 sytuacja. Nieprawidłowy podpis, manipulacja, wpisanie na czarną listę lub build poza oknem wersji licencji powodują, że OpenDocumentAsync zgłasza LicenseException z License.RejectionMessage. Licencja wygasła kalendarzowo, która nie ma komunikatu odrzucenia, kontynuuje działanie w trybie znakowanym.

Wtyczki potrzebują uprawnień

Rejestrowanie wtyczki bez odpowiedniego uprawnienia jest inne: w przypadku brakującej 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 bezpośrednio rozwiązanie: usuń wywołanie options.AddPlugin<...>() dla tej wtyczki lub zainstaluj płatną licencję lub aktywną tymczasową/licencję demonstracyjną (NFR), która przyznaje tę funkcję. Tymczasowe rejestracje mogą przetrwać po dacie wygaśnięcia, aby już skonfigurowana aplikacja mogła degradować się w czasie działania zamiast się zawiesić 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

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ń.