Configurazione Licenza

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

La licenza viene caricata una volta, durante AddDoconut(). Questo è un cambiamento rispetto alla precedente libreria .NET Standard, dove la licenza veniva passata a un'istanza Viewer o impostata tramite le chiamate statiche Viewer.DoconutLicense(...) / Viewer.SetLicensePlugin(...). Questi metodi non sono un meccanismo di avvio in questa versione — consulta la guida alla migrazione.

Quattro modi per fornire una licenza

Ce ne sono quattro: tre fonti esplicite su DoconutOptions — un flusso, 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 vive Program.cs. Se il percorso non viene risolto, 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 nessuno di LicensePath, LicenseContent o LicenseStream è impostato. I file di licenza per plugin nella stessa cartella (Doconut.Viewer.<Capability>.lic) vengono letti insieme, così LicensePath e AddPlugin<...>() funzionano insieme quando le licenze dei plugin si trovano accanto alla licenza principale.

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

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

Per flusso

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

// Priorità: LicenseStream > LicenseContent > LicensePath > ricerca automatica.
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:

// XML della licenza da un database, variabile d'ambiente o gestore di segreti —
// nessun file su disco. Superato solo da 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 autonomamente:

// Non configurare nulla, e Doconut cerca la licenza da solo, solo in queste due cartelle:
//   1. {CurrentDirectory}/wwwroot
//   2. {AppContext.BaseDirectory}/wwwroot   (wwwroot all'interno della cartella di output della build)
// Cerca prima Doconut.lic, poi Doconut.Viewer.lic, più eventuali per-capability
// File Doconut.Viewer.<Capability>.lic accanto ad esso.
builder.Services.AddDoconut();

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

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

licenza del visualizzatore di base (controllata per prima)

Niente al di fuori di una cartella wwwroot viene letto: un .lic nella cartella di output stessa, o in wwwroot/lib, viene ignorato.

Se in precedenza hai passato un List<string> di percorsi di licenza al costruttore Viewer — uno per capacità — mantieni quei file di supporto accanto a Doconut.Viewer.lic e lascia che la scoperta automatica li rilevi. Non esiste un'opzione lista-di-percorsi su DoconutOptions.

Copia la licenza nella cartella di output

Quando il processo non viene eseguito dalla cartella del progetto — un'app pubblicata, IIS, un contenitore, un runner di test — il primo tentativo fallisce, e il secondo, {AppContext.BaseDirectory}/wwwroot, deve trovare il file. L'app di test del SDK copia le licenze lì ad ogni build con questo target MSBuild:

<Target Name="CopyLicensesToOutput" AfterTargets="Build">
  <ItemGroup>
    <DoconutLicenseFiles Include="$(MSBuildProjectDirectory)\wwwroot\*.lic" />
    <StaleOutputLicenses Include="$(OutDir)wwwroot\*.lic" />
  </ItemGroup>
  <!-- Elimina prima, così rinominare o rimuovere un .lic in wwwroot lo rimuove anche dall'output. -->
  <Delete Files="@(StaleOutputLicenses)" />
  <Copy SourceFiles="@(DoconutLicenseFiles)" DestinationFolder="$(OutDir)wwwroot" />
</Target>

La destinazione deve essere $(OutDir)wwwroot: un .lic copiato nella radice dell'output non viene mai trovato dalla ricerca automatica. Gli esempi LicensePath su questa pagina puntano allo stesso luogo.

Mantieni i file .lic fuori dal controllo di versione — distribuiscili insieme 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 funzionalità opzionale è 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 provoca OpenDocumentAsync a lanciare LicenseException con License.RejectionMessage. Una licenza scaduta per calendario che non ha un messaggio di rifiuto continua in modalità con filigrana.

I plugin richiedono capacità

Registrare un plugin senza l'entitlement corrispondente è diverso: per una licenza mancante, un file legacy TRIAL, o una licenza a pagamento senza quella capacità, AddDoconut() lancia InvalidOperationException, quindi l'app non si avvia. Ad 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 ti indica direttamente la correzione: 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 loro data di scadenza così un'app già configurata può degradare a runtime invece di andare in crash durante il riavvio; una volta scadute, le loro capacità sono comunque revocate.

Verifica la licenza caricata

Usa IDoconutLicenseService, la stessa fonte di verità utilizzata dal SDK, per esporre un endpoint diagnostico autenticato o per gestire i flag delle funzionalità. Non restituire il contenuto della licenza o le chiavi.

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 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 — funzionalità, livelli di licenza e verifica di ciò che è stato caricato in fase di esecuzione.
• Risoluzione dei problemi — filigrane, licenze rifiutate e errori di capacità.