Configurazione della licenza

Dove Doconut cerca il tuo file di 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.

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 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 nessuno di LicensePath, LicenseContent o LicenseStream è impostato. I file di licenza per plugin nella stessa cartella (Doconut.Viewer.<Capability>.lic) vengono letti con essa, quindi LicensePath e AddPlugin<...>() funzionano insieme quando le licenze dei plugin si trovano accanto alla licenza di base.

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.

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

Per flusso

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

csharp
// 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:

csharp
// License XML 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 da solo:

csharp
// 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; se manca, Doconut.Viewer.lic più qualsiasi
// file Doconut.Viewer.<Capability>.lic per plugin.
builder.Services.AddDoconut();

Cartelle di ricerca, in ordine, e i nomi dei file, in ordine (ognuno cercato prima nella cartella 1, poi nella cartella 2):

text
1. {CurrentDirectory}/wwwroot
2. {AppContext.BaseDirectory}/wwwroot

Filenames, in order (each one looked for in folder 1, then folder 2):
  Doconut.lic                          — legacy all-in-one license; if found, nothing else is read
  Doconut.Viewer.lic                   — base viewer license
  Doconut.Viewer.<Capability>.lic      — per-plugin licenses, read only when Doconut.Viewer.lic was found

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

Copia la licenza nella tua 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 sondaggio fallisce, e il secondo, {AppContext.BaseDirectory}/wwwroot, deve trovare il file. Questo target MSBuild copia le licenze lì ad ogni build:

xml
<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 accanto all'app, o inietta la licenza tramite LicenseContent o LicenseStream dal tuo archivio segreto.

Cosa succede senza licenza

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

Un file di licenza trovato ma rifiutato è diverso. Una firma non valida, manomissione, inserimento in lista nera o una build al di fuori della finestra di versione della licenza fa sì che OpenDocumentAsync lanci LicenseException con License.RejectionMessage. Una licenza Temporanea scaduta continua in modalità con filigrana. Una licenza a pagamento la cui data di sottoscrizione è passata continua a funzionare, pulita e con le sue capacità, su ogni build rilasciata prima di quella data.

I plugin necessitano di capacità

Registrare un plugin senza l'entitlement corrispondente è diverso: per una licenza mancante, un file legacy TRIAL, o una licenza a pagamento priva di quella capacità, AddDoconut() genera InvalidOperationException, quindi l'app non si avvia. Ad esempio, registrare il plugin Converter senza una licenza che conceda Converter:

text
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 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 dall'SDK, per esporre un endpoint diagnostico autenticato o per gestire i flag delle funzionalità. Non restituire contenuti o chiavi della licenza.

csharp
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

SintomoProbabile causaVerifica
Il visualizzatore funziona ma ogni pagina è contrassegnata da filigranaNessuna licenza è stata caricata, o la licenza Temporanea è scadutaRisolvi IDoconutLicenseService; verifica la directory di output e la directory di lavoro del processo
AddDoconut() genera un'eccezione per un pluginLa licenza non concede quella capacità al pluginVerifica IsCapabilityGranted(...) e rimuovi le registrazioni che non hai acquistato
Un percorso relativo configurato funziona localmente ma non in IIS/containerLa directory di lavoro del processo è cambiataUsa AppContext.BaseDirectory o un percorso assoluto
Il file .lic sostituito non ha effettoIl servizio di licenza singleton era già stato creatoRiavvia l'applicazione
OpenDocumentAsync genera LicenseExceptionFirma, dominio, finestra di versione, blacklist o gate di runtime del plugin hanno rifiutato la licenzaLeggi il messaggio di eccezione/rifiuto senza esporlo a client non attendibili

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

Questa pagina è stata utile?