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 beats LicenseContent beats LicensePath beats 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 à sua pasta de projeto, e não à pasta onde Program.cs está. Se o caminho não for resolvido, Doconut não lança exceção e não recorre à busca automática — simplesmente não carrega nenhuma licença e o visualizador exibe a marca d'água. A busca 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 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 omita LicensePath completamente e confie na descoberta automática abaixo.

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

Por stream

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

// Precedência: 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 de um banco de dados, variável de ambiente ou gerenciador de segredos —
// sem 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 Doconut procura a licença por conta própria, apenas nestas duas pastas:

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

As pastas de sondagem, em ordem, e os nomes de arquivos 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-plugin 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.

Copie a licença para 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>
  <!-- Delete first, so renaming or removing a .lic in wwwroot also takes it out of the output. -->
  <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 busca automática. Os exemplos de 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 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 expirado por calendário que não possui 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, permitindo que um aplicativo já configurado degrade em tempo de execução ao invés de falhar na reinicialização; após a expiração, suas capacidades ainda são revogadas.

Verificar 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 recarga ativo, portanto substituir um arquivo de licença requer reiniciar a aplicação.

Matriz de solução de problemas

Próximos passos

• Licensing — capacidades, níveis de licença e verificação do que foi carregado em tempo de execução.
• Troubleshooting — marcas d'água, licenças rejeitadas e erros de capacidade.