Configurazione della licenza

Senza una licenza, Doconut continua a renderizzare i documenti — ogni pagina mostra 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.

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

Ci 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 è esatta:

LicenseStream batte LicenseContent batte LicensePath batte 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 un'eccezione 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 con essa, così LicensePath e AddPlugin<...>() funzionano insieme quando le licenze dei plugin si trovano accanto alla licenza base (controllata per prima).

Preferisci un percorso assoluto (ad esempio costruito da IWebHostEnvironment.WebRootPath o AppContext.BaseDirectory), oppure ometti completamente LicensePath e fai affidamento sulla 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 piuttosto che 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 controllati 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

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 accompagnamento 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 container, 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 in questa pagina puntano allo stesso luogo.

Mantieni i file .lic fuori dal controllo di versione — distribuiscili insieme all'app, oppure 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 mostra una filigrana di valutazione e nessuna funzionalità opzionale è concessa.

Un file di licenza che viene trovato ma rifiutato è diverso. Una firma non valida, manomissione, inserimento in blacklist o una build al di fuori della finestra di versione della licenza fa sì che OpenDocumentAsync lanci 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 il relativo diritto è 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 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à sono comunque revocate.

Verifica la licenza caricata

Usa IDoconutLicenseService, la stessa fonte di verità utilizzata dall'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 — capacità, livelli di licenza e verifica di ciò che è stato caricato a runtime.
• Risoluzione dei problemi — filigrane, licenze rifiutate e errori di capacità.