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 e a precedência exata quando mais de uma está definida.

A licença é carregada uma vez, durante AddDoconut(). Isso é uma mudança em relação à biblioteca .NET Standard anterior, onde a licença era passada para uma instância Viewer ou definida através das chamadas estáticas Viewer.DoconutLicense(...) / Viewer.SetLicensePlugin(...). Esses métodos não são um mecanismo de inicialização nesta versão — veja o guia de migração.

Quatro maneiras de fornecer uma licença

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

LicenseStream supera LicenseContent supera LicensePath supera pesquisa automática.

Por caminho

LicensePath é passado para File.Exists exatamente como fornecido. Um caminho relativo é resolvido em relação ao diretório de trabalho atual do processo — não à pasta do seu projeto, e não à pasta onde Program.cs está. Se o caminho não for resolvido, o Doconut não lança exceção e não recorre à pesquisa automática — simplesmente não carrega nenhuma licença e o visualizador adiciona marcas d'água. A pesquisa automática só é executada quando nenhum de LicensePath, LicenseContent ou LicenseStream está definido. Os arquivos de licença por plugin na mesma pasta (Doconut.Viewer.<Capability>.lic) são lidos junto com ela, de modo que LicensePath e AddPlugin<...>() funcionam juntos quando as licenças dos plugins ficam ao lado da licença base.

Prefira um caminho absoluto (por exemplo construído a partir de IWebHostEnvironment.WebRootPath ou AppContext.BaseDirectory), ou ignore LicensePath completamente e confie na descoberta automática abaixo.

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

Por fluxo

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

// Prioridade: LicenseStream > LicenseContent > LicensePath > pesquisa automática.
builder.Services.AddDoconut(options =>
{
    options.LicenseStream = licenseStream;
});

Por conteúdo

LicenseContent aceita o próprio texto da licença — de uma variável de ambiente, de um banco de dados ou de um gerenciador de segredos:

// License XML de um banco de dados, variável de ambiente ou gerenciador de segredos —
// nenhum arquivo no disco. Superado apenas por LicenseStream.
builder.Services.AddDoconut(options =>
{
    options.LicenseContent = Environment.GetEnvironmentVariable("DOCONUT_LICENSE") ?? "";
});

Descoberta automática

Não configure nenhuma das três fontes explícitas, e o Doconut procura a licença por conta própria:

// Não configure nada, e Doconut procura a própria licença, apenas nestas duas pastas:
//   1. {CurrentDirectory}/wwwroot
//   2. {AppContext.BaseDirectory}/wwwroot   (wwwroot dentro da pasta de saída da compilação)
// Ele procura primeiro Doconut.lic, depois Doconut.Viewer.lic, além de quaisquer arquivos por capacidade
// Arquivos Doconut.Viewer.<Capability>.lic ao lado dele.
builder.Services.AddDoconut();

As pastas de sondagem, em ordem, e os nomes de arquivo procurados em cada uma:

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

Nada fora de uma pasta wwwroot é lido: um .lic na própria pasta de saída, ou em wwwroot/lib, é ignorado.

Se você anteriormente passou um List<string> de caminhos de licença para o construtor Viewer — um por capacidade — mantenha esses arquivos acompanhantes ao lado de Doconut.Viewer.lic e deixe a descoberta automática selecioná-los. Não há opção de lista de caminhos em DoconutOptions.

Copie a licença para a sua pasta de saída

Quando o processo não é executado a partir da pasta do projeto — um aplicativo publicado, IIS, um contêiner, um executor de testes — a primeira sondagem falha, e a segunda, {AppContext.BaseDirectory}/wwwroot, precisa encontrar o arquivo. O próprio aplicativo de teste do SDK copia as licenças para lá em cada compilação com este alvo MSBuild:

<Target Name="CopyLicensesToOutput" AfterTargets="Build">
  <ItemGroup>
    <DoconutLicenseFiles Include="$(MSBuildProjectDirectory)\wwwroot\*.lic" />
    <StaleOutputLicenses Include="$(OutDir)wwwroot\*.lic" />
  </ItemGroup>
  <!-- Excluir primeiro, para que renomear ou remover um .lic em wwwroot também o remova da saída. -->
  <Delete Files="@(StaleOutputLicenses)" />
  <Copy SourceFiles="@(DoconutLicenseFiles)" DestinationFolder="$(OutDir)wwwroot" />
</Target>

O destino deve ser $(OutDir)wwwroot: um .lic copiado para a raiz da saída nunca é encontrado pela pesquisa automática. Os exemplos LicensePath nesta página apontam para o mesmo local.

Mantenha os arquivos .lic fora do controle de versão — implante-os ao lado do aplicativo, ou injete a licença através de LicenseContent ou LicenseStream a partir do seu cofre secreto.

O que acontece sem uma licença

Uma licença ausente não gera exceção. AddDoconut() tem sucesso, o aplicativo inicia, e o visualizador funciona — mas cada página contém 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, lista negra, ou uma compilação fora da janela de versão da licença faz com que OpenDocumentAsync lance LicenseException com License.RejectionMessage. Uma licença expirada por calendário que não tem mensagem de rejeição continua no modo com marca d'água.

Plugins precisam de capacidades

Registrar um plugin sem a permissão correspondente é diferente: para uma licença ausente, um arquivo legado TRIAL, ou uma licença paga sem essa capacidade, AddDoconut() lança InvalidOperationException, portanto o aplicativo não inicia. Por exemplo, registrar o plugin Converter sem uma licença que 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.

A mensagem indica a correção diretamente: remova a chamada options.AddPlugin<...>() para esse plugin, ou instale uma licença paga ou uma licença Temporária/Demo (NFR) ativa que conceda a capacidade. Registros temporários podem sobreviver à data de expiração para que um aplicativo já configurado possa degradar em tempo de execução em vez de falhar durante a reinicialização; uma vez expiradas, suas capacidades ainda são revogadas.

Verifique a licença carregada

Use IDoconutLicenseService, a mesma fonte de verdade usada pelo SDK, para expor um endpoint de diagnóstico autenticado ou para controlar bandeiras de recursos. Não retorne o conteúdo da licença ou chaves.

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

A licença é lida durante o registro AddDoconut(). ResetLicense é atualmente uma propriedade de compatibilidade sem caminho de recarregamento ativo, portanto substituir um arquivo de licença requer reiniciar o aplicativo.

Matriz de solução de problemas

Próximos passos

• Licenciamento — recursos, níveis de licença e verificação do que foi carregado em tempo de execução.
• Resolução de Problemas — marcas d'água, licenças rejeitadas e erros de recursos.