Configurazione della licenza

Senza una licenza, Doconut continua a renderizzare i documenti — ogni pagina presenta semplicemente una filigrana di valutazione. Questa pagina descrive i quattro modi per fornire una licenza e la precedenza esatta quando ne è impostata più di una.

Quattro modi per fornire una licenza

Ce ne sono quattro: tre fonti esplicite su DoconutOptions — un stream, contenuto grezzo o un percorso file — più la scoperta automatica quando nessuna di esse è impostata. Quando ne è impostata più di una, la precedenza è precisa:

LicenseStream supera LicenseContent supera LicensePath supera la ricerca automatica.

Per percorso

LicensePath viene passato a File.Exists esattamente così com'è. Un percorso relativo viene risolto rispetto alla directory di lavoro corrente del processo — non alla cartella del tuo progetto, e non alla cartella in cui si trova Program.cs. Se il percorso non si risolve, Doconut non genera eccezioni e non ricade nella ricerca automatica — semplicemente non carica alcuna licenza e il visualizzatore aggiunge la filigrana. La ricerca automatica viene eseguita solo quando né LicensePath, né LicenseContent né LicenseStream sono impostati.

Preferisci un percorso assoluto (ad esempio costruito da IWebHostEnvironment.WebRootPath o AppContext.BaseDirectory), oppure ometti completamente LicensePath e affidati alla scoperta automatica descritta di seguito.

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

Per stream

LicenseStream viene letto una sola volta all'avvio — utile quando la licenza proviene da un archivio segreto anziché da un file su disco.

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

Per contenuto

LicenseContent accetta il testo della licenza stesso — da una variabile d'ambiente, un database o un gestore di segreti:

// 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") ?? "";
});

Scoperta automatica

Non configurare nessuna delle tre fonti esplicite, e Doconut cercherà la licenza da solo:

// 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();

Le directory di ricerca, in ordine, e i nomi file cercati in ciascuna:

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

Copia la licenza nella cartella di output

LicensePath e la ricerca automatica tramite AppContext.BaseDirectory richiedono entrambi che il file .lic esista accanto all'app compilata — non solo nella tua cartella sorgente wwwroot. L'app di test dell'SDK copia il file ad ogni build con questo target MSBuild:

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

Mantieni i file .lic fuori dal controllo di versione — distribuiscili accanto all'app, o inietta la licenza tramite LicenseContent o LicenseStream dal tuo archivio segreto.

Cosa succede senza una licenza

Una licenza mancante non genera eccezioni. AddDoconut() ha successo, l'app si avvia e il visualizzatore funziona — ma ogni pagina presenta una filigrana di valutazione e nessuna capacità opzionale viene concessa.

Un file di licenza trovato ma rifiutato è diverso. Una firma non valida, manomissione, inserimento in blacklist o una build al di fuori della finestra di versione della licenza provocano il lancio di LicenseException da parte di OpenDocumentAsync con License.RejectionMessage. Una licenza scaduta per calendario che non ha messaggio di rifiuto continua in modalità con filigrana.

I plugin richiedono capacità

Registrare un plugin senza il relativo diritto è diverso: per una licenza mancante, un file legacy TRIAL o una licenza a pagamento priva di quella capacità, AddDoconut() lancia InvalidOperationException, quindi l'app non si avvia. Per esempio, registrare il plugin Converter senza una licenza che conceda 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.

Il messaggio indica direttamente la soluzione: rimuovere la chiamata options.AddPlugin<...>() per quel plugin, oppure installare una licenza a pagamento o una licenza Temporanea/Demo (NFR) attiva che conceda la capacità. Le registrazioni temporanee possono sopravvivere alla data di scadenza in modo che un'app già configurata possa degradare a runtime invece di andare in crash durante il riavvio; una volta scadute, le loro capacità vengono comunque revocate.

Verifica la licenza caricata

Utilizza IDoconutLicenseService, la stessa fonte di verità usata dall'SDK, per esporre un endpoint diagnostico autenticato o per gestire i flag delle funzionalità. Non restituire i contenuti o le chiavi della licenza.

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

La licenza viene letta durante la registrazione di AddDoconut(). ResetLicense è attualmente una proprietà di compatibilità senza un percorso di ricarica attivo, quindi sostituire un file di licenza richiede il riavvio dell'applicazione.

Matrice di risoluzione dei problemi

Prossimi passi

• Licenze — capacità, livelli di licenza e verifica di ciò che è stato caricato a runtime.
• Risoluzione dei problemi — filigrane, licenze rifiutate e errori di capacità.