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 in Global.asax, dove Doconut cerca quando non ne fornisci alcuna, e cosa succede quando manca la licenza di un plugin.

Quattro modi per fornire una licenza

Esistono tre fonti esplicite su DoconutOptions — un percorso file, uno stream o contenuto grezzo — più la scoperta automatica quando nessuna di esse è impostata. Tutte vengono lette una sola volta, in DoconutHost.Initialize. Quando ne sono impostate più di una, la precedenza è esatta:

LicenseStream ha precedenza su LicenseContent ha precedenza su LicensePath ha precedenza sulla scoperta automatica.

Per percorso

Fornisci a LicensePath un percorso completo. Un percorso relativo viene risolto rispetto alla directory corrente del processo, e sotto IIS questa è la cartella del processo worker, non quella del tuo sito. HostingEnvironment.MapPath trasforma un percorso relativo al sito in uno completo:

Doconut.DoconutHost.Initialize(options =>
{
    options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
});

Se il file non esiste, Doconut non genera eccezione e non ricade sulla scoperta automatica: non carica alcuna licenza e il visualizzatore aggiunge la filigrana. I file di licenza per plugin nella stessa cartella (Doconut.Viewer.<Capability>.lic) vengono letti insieme, quindi LicensePath e AddPlugin<...>() funzionano insieme quando le licenze dei plugin si trovano accanto alla licenza base.

Per stream

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

// Precedence: LicenseStream > LicenseContent > LicensePath > auto-search.
Doconut.DoconutHost.Initialize(options =>
{
    options.LicenseStream = licenseStream;
});

Per contenuto

LicenseContent prende il testo della licenza stesso — da una variabile d'ambiente, un database o un archivio segreto — così non è necessario distribuire un file di licenza con il sito.

// License XML from a database, an environment variable or a secret store -
// no file on disk. Beaten only by LicenseStream.
Doconut.DoconutHost.Initialize(options =>
{
    options.LicenseContent = Environment.GetEnvironmentVariable("DOCONUT_LICENSE") ?? "";
});

Scoperta automatica

Non impostare nessuna delle tre, e Doconut cercherà la licenza da solo:

// Configure nothing, and Doconut searches for the license itself, in this order:
//   1. {CurrentDirectory}\wwwroot
//   2. {AppContext.BaseDirectory}\wwwroot   (under IIS: the site's root folder)
// It looks for Doconut.lic first, then Doconut.Viewer.lic, plus any per-plugin
// Doconut.Viewer.<Capability>.lic files alongside it.
Doconut.DoconutHost.Initialize();

Le due cartelle, in ordine, e i file cercati:

1. {CurrentDirectory}\wwwroot
2. {AppContext.BaseDirectory}\wwwroot

In each folder:
  Doconut.lic                        — if found, this is the only file read
  Doconut.Viewer.lic                 — base viewer license
  Doconut.Viewer.<Capability>.lic    — per-plugin licenses, read only next to Doconut.Viewer.lic

Sotto IIS e IIS Express, AppContext.BaseDirectory è la cartella radice del sito — quella che contiene Web.config — non la sua cartella bin. Quindi la licenza deve trovarsi in wwwroot sotto la radice del sito:

MySite\
  Web.config
  Global.asax
  bin\
  wwwroot\
    Doconut.Viewer.lic
    Doconut.Viewer.Converter.lic

Nel progetto, mantieni wwwroot\*.lic accanto a Web.config e distribuisci la cartella con il sito. Non è necessario alcun passaggio di build per copiarla da qualche parte. Un .lic altrove — in bin\, accanto a Web.config, o in una sottocartella di wwwroot — non viene mai letto.

Mantieni i file .lic fuori dal controllo di versione. Distribuiscili accanto al sito, o fornisci la licenza tramite LicenseContent o LicenseStream dal tuo archivio segreto.

Cosa succede senza una licenza

Una licenza mancante non genera eccezione. DoconutHost.Initialize ha successo, il sito si avvia e il visualizzatore funziona, ma ogni pagina mostra una filigrana di valutazione e nessuna capacità opzionale è concessa.

Un file di licenza trovato ma rifiutato è diverso. Una firma non valida, una manomissione o una compilazione al di fuori della finestra di versione della licenza fanno sì che OpenDocumentAsync generi LicenseException con il motivo.

I plugin necessitano della loro licenza all'avvio

Registrare un plugin la cui capacità non è concessa da alcuna licenza interrompe l'applicazione all'avvio. DoconutHost.Initialize genera un'eccezione in Application_Start:

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.

Sotto System.Web, non vedi quel messaggio nel browser. Ogni richiesta al sito risponde con un 500 vuoto — nessuna pagina di errore, nessuno stack trace, nulla nel log di IIS. L'eccezione viene registrata solo nel log eventi di Windows (log Applicazione, origine ASP.NET). Se l'intero sito smette di rispondere subito dopo aver aggiunto una riga AddPlugin, controlla i file di licenza in wwwroot prima del codice: il file .lic del plugin Doconut.Viewer.<Capability>.lic deve trovarsi accanto a Doconut.Viewer.lic, e senza la licenza base i file del plugin non vengono letti affatto.

Verifica la licenza caricata

IDoconutLicenseService è la stessa fonte di verità usata SDK. Risolvila da DoconutHost.Services per esporre un endpoint diagnostico autenticato o per guidare i flag di funzionalità — non restituire mai il contenuto della licenza:

// GET /License/Status
public ActionResult Status()
{
    var license = Doconut.DoconutHost.Services.GetRequiredService<IDoconutLicenseService>();

    return Json(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
    }, JsonRequestBehavior.AllowGet);
}

La licenza viene letta una sola volta, in DoconutHost.Initialize. Dopo aver sostituito un file di licenza, ricicla il pool di applicazioni (o tocca Web.config) affinché Application_Start venga eseguito nuovamente.

Risoluzione dei problemi

Prossimi passi

• Licenze — capacità, e come verificarle a runtime.
• Risoluzione dei problemi — filigrane, errori all'avvio e altri sintomi.