Configuração de Licença

Sem uma licença, o Doconut ainda renderiza documentos — cada página apenas exibe uma marca d'água de avaliação. Esta página cobre as quatro maneiras de fornecer uma licença em Global.asax, onde o Doconut procura quando você não fornece nenhuma, e o que acontece quando a licença de um plugin está ausente.

Quatro maneiras de fornecer uma licença

Existem três fontes explícitas em DoconutOptions — um caminho de arquivo, um fluxo ou conteúdo bruto — além da descoberta automática quando nenhuma delas está definida. Todas são lidas uma única vez, em DoconutHost.Initialize. Quando mais de uma está definida, a precedência é exata:

LicenseStream vence LicenseContent vence LicensePath vence descoberta automática.

Por caminho

Defina LicensePath com um caminho completo. Um caminho relativo é resolvido em relação ao diretório atual do processo, e no IIS isso é a própria pasta do processo de trabalho, não a do seu site. HostingEnvironment.MapPath converte um caminho relativo ao site em um caminho completo:

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

Se o arquivo não existir, o Doconut não lança exceção e não recorre à descoberta automática: ele não carrega nenhuma licença, e o visualizador aplica marcas d'água. Os arquivos de licença por plugin na mesma pasta (Doconut.Viewer.<Capability>.lic) são lidos junto, portanto LicensePath e AddPlugin<...>() funcionam juntos quando as licenças dos plugins ficam ao lado da licença base.

Por fluxo

LicenseStream é lido uma única vez, na inicialização — útil quando a licença vem de um recurso incorporado ou de um armazenamento secreto em vez de um arquivo no disco.

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

Por conteúdo

LicenseContent recebe o próprio texto da licença — de uma variável de ambiente, de um banco de dados ou de um armazenamento secreto — portanto nenhum arquivo de licença precisa ser implantado com o site.

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

Descoberta automática

Não configure nenhum dos três, e o Doconut procura a licença por conta própria:

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

As duas pastas, em ordem, e os arquivos procurados:

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

No IIS e no IIS Express, AppContext.BaseDirectory é a pasta raiz do site — aquela que contém Web.config — não a sua pasta bin. Portanto a licença deve estar em wwwroot sob a raiz do site:

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

No projeto, mantenha wwwroot\*.lic ao lado de Web.config e implante a pasta com o site. Nenhuma etapa de compilação precisa copiá-la para outro lugar. Um .lic em qualquer outro local — em bin\, ao lado de Web.config, ou em uma subpasta de wwwroot — nunca é lido.

Mantenha os arquivos .lic fora do controle de versão. Implante-os ao lado do site, ou forneça a licença através de LicenseContent ou LicenseStream a partir do seu armazenamento secreto.

O que acontece sem uma licença

Uma licença ausente não gera exceção. DoconutHost.Initialize tem sucesso, o site inicia, e o visualizador funciona, mas cada página exibe uma marca d'água de avaliação e nenhuma capacidade opcional é concedida.

Um arquivo de licença que é encontrado mas rejeitado é diferente. Uma assinatura inválida, adulteração ou uma compilação fora da janela de versão da licença faz com que OpenDocumentAsync lance LicenseException com a razão.

Plugins precisam de sua licença na inicialização

Registrar um plugin cuja capacidade não é concedida por nenhuma licença interrompe a aplicação na inicialização. DoconutHost.Initialize lança exceção em 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.

No System.Web, você não vê essa mensagem no navegador. Cada requisição ao site responde com um 500 vazio — sem página de erro, sem rastreamento de pilha, nada no log do IIS. A exceção é registrada apenas no log de eventos do Windows (log de Aplicação, origem ASP.NET). Se todo o site parar de responder logo após você adicionar uma linha AddPlugin, verifique os arquivos de licença em wwwroot antes do código: o Doconut.Viewer.<Capability>.lic do plugin deve estar ao lado de Doconut.Viewer.lic, e sem a licença base os arquivos do plugin não são lidos.

Verificar a licença carregada

IDoconutLicenseService é a mesma fonte de verdade que o SDK usa. Resolva-a a partir de DoconutHost.Services para expor um endpoint de diagnóstico autenticado ou controlar flags de recursos — nunca retorne o conteúdo da licença:

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

A licença é lida uma única vez, em DoconutHost.Initialize. Após substituir um arquivo de licença, recicle o pool de aplicativos (ou altere Web.config) para que Application_Start seja executado novamente.

Solução de Problemas

Próximos passos

• Licenciamento — capacidades, e como verificá-las em tempo de execução.
• Resolução de Problemas — marcas d'água, falhas na inicialização e outros sintomas.