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.

Quatro maneiras de fornecer uma licença

Existem quatro: três fontes explícitas em DoconutOptions — um stream, 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 auto-search.

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 o Program.cs está. Se o caminho não for resolvido, o Doconut não lança exceção e não recorre à busca automática — ele simplesmente não carrega nenhuma licença e o visualizador exibe marcas d'água. A busca automática só é executada quando nenhum de LicensePath, LicenseContent ou LicenseStream está definido.

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

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

Por stream

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

// Precedence: LicenseStream > LicenseContent > LicensePath > auto-search.
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 from a database, environment variable, or secret manager —
// no file on disk. Beaten only by 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:

// Configure nothing, and Doconut searches for the license itself:
//   1. {CurrentDirectory}/wwwroot
//   2. {CurrentDirectory}/wwwroot/lib
//   3. AppContext.BaseDirectory  (the build output folder)
// It looks for Doconut.Viewer.lic plus any per-plugin
// Doconut.Viewer.<Capability>.lic files alongside it.
builder.Services.AddDoconut();

Os diretórios de sondagem, em ordem, e os nomes de arquivos procurados em cada um:

1. {CurrentDirectory}/wwwroot
2. {CurrentDirectory}/wwwroot/lib
3. AppContext.BaseDirectory

Filenames (checked in each directory above, in order):
  Doconut.Viewer.lic                   — base viewer license
  Doconut.Viewer.<Capability>.lic      — per-plugin license, alongside Doconut.Viewer.lic

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

LicensePath e a sondagem AppContext.BaseDirectory da busca automática, ambos precisam que o arquivo .lic exista ao lado do aplicativo compilado — não apenas em seu wwwroot de origem. O próprio aplicativo de teste do SDK copia-o em cada compilação com este alvo MSBuild:

<Target Name="CopyLicensesToOutput" AfterTargets="Build">
  <ItemGroup>
    <DoconutLicenseFiles Include="$(MSBuildProjectDirectory)\wwwroot\*.lic" />
  </ItemGroup>
  <Copy SourceFiles="@(DoconutLicenseFiles)" DestinationFolder="$(OutDir)" SkipUnchangedFiles="true" />
</Target>

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 armazenamento 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 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, 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 aquela 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 degrade em tempo de execução em vez de falhar durante a reinicialização; após a expiração, 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 flags 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 — capacidades, níveis de licença e verificação do que foi carregado em tempo de execução.
• Solução de problemas — marcas d'água, licenças rejeitadas e erros de capacidade.