Instalação

Adicionar Doconut ao seu projeto .NET 6

O visualizador base Doconut para .NET 6 é distribuído como um único pacote NuGet que se integra a qualquer aplicação ASP.NET Core. Plugins opcionais utilizam pacotes separados. Esta página instala o pacote base e registra o middleware — o mínimo necessário antes da sua primeira renderização.

Requisitos

PlataformaSuportado
Windows x64 / x86Sim
Linux x64, baseado em glibc (Debian, Ubuntu, a imagem oficial mcr.microsoft.com/dotnet/aspnet:6.0-bookworm-slim)Sim
Alpine e outras distribuições baseadas em muslNão
macOSNão

No Linux, instale a biblioteca de configuração de fontes antes que o primeiro documento seja aberto:

bash
apt-get update && apt-get install -y libfontconfig1

No RHEL, Fedora e distribuições semelhantes, o pacote é fontconfig (dnf install -y fontconfig). Esse é o único pacote do sistema que Doconut necessita: as bibliotecas nativas que ele usa são enviadas dentro do pacote NuGet, e libgdiplus não é necessário. No Docker, prefira aspnet:6.0-bookworm-slim (Debian 12): a tag padrão aspnet:6.0 é Debian 11, cujos espelhos de pacotes podem falhar ao instalar libfontconfig1. As páginas são renderizadas com as fontes instaladas no servidor, portanto veja Solução de Problemas para fontes e mensagens de erro do Linux.

Instalar o pacote

bash
dotnet add package Doconut.NET6

O comando sem versão instala a versão estável mais recente. Para fixar a versão descrita nesta documentação, passe a versão como uma opção separada:

bash
dotnet add package Doconut.NET6 --version 26.10.0

Doconut.NET6 é o ID do pacote. O sufixo de versão pertence ao nome de arquivo Doconut.NET6.<version>.nupkg baixado e não faz parte do ID.

Identificar a integração antes de atualizar

O ID de pacote Doconut.NET6 foi usado tanto pela integração clássica quanto pela atual .NET 6. Não selecione a documentação apenas pelo nome do pacote:

  • DocImage.axd, new Viewer(_cache, _accessor, ...), síncrono OpenDocument(...), e scripts de visualizador copiados manualmente identificam a integração clássica;
  • AddDoconut(), UseDoconutResources(), um Viewer injetado, e OpenDocumentAsync(...) identificam a integração atual documentada aqui.

O manual de configuração clássico traduzido continua disponível. Use o guia de migração para mudar de geração; uma atualização normal do pacote não converte automaticamente a inicialização, o tempo de vida do visualizador ou os recursos do navegador.

Registrar Doconut

AddDoconut() é o único ponto de entrada de registro — há uma única sobrecarga, e ele conecta o serviço Viewer, o serviço de licença e a infraestrutura de renderização ao contêiner DI.

Duas chamadas de middleware completam a configuração, e sua ordem importa: UseDoconutResources() deve ser executado antes de UseDoconut(). UseDoconut() é um middleware terminal, portanto chamá‑lo primeiro faz com que toda requisição a um recurso /doconut-res nunca chegue ao manipulador de recursos e resulte em 404. UseDoconut() responde a toda requisição que o alcança, então monte‑o em seu próprio ramo com app.Map. A conexão da sessão também é necessária — a segurança de documento padrão do Doconut valida cada requisição de página contra o estado de sessão do ASP.NET.

csharp
builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
});
builder.Services.AddDistributedMemoryCache(); // o estado da sessão precisa de um cache (MVC/Razor Pages já adicionam um)
builder.Services.AddSession(); // A segurança de documentos Doconut depende do estado da sessão ASP.NET

app.UseSession();          // chame UseSession() antes de UseDoconut()
app.UseDoconutResources(); // deve ser registrado antes de UseDoconut()
app.Map("/doconut", branch => branch.UseDoconut());

Todas as opções

DoconutOptions aceita as seguintes propriedades configuráveis. Cada uma é opcional — os padrões abaixo se aplicam quando uma propriedade não é definida.

PropriedadePadrãoDescrição
ShowDoconutInfofalseQuando true, uma requisição sem token retorna um banner de versão em vez de um 404. Útil como verificação rápida; desative em produção.
UnsafeModefalseQuando true, ignora a verificação de segurança da sessão ASP.NET nas requisições de página. Desative em produção.
MiddlewarePath"/doconut"Valor de coordenação para o endpoint page-image. É validado, mas não monta um ramo por si só; mantenha alinhado com o mapeamento real UseDoconut() e o cliente BasePath.
ResourcesPath"/doconut-res"De onde os recursos incorporados JS/CSS/imagem são servidos.
LicensePath"" (empty string)Caminho para o arquivo de licença. Vazio significa passar para a próxima fonte, então pesquisa automática.
LicenseContent"" (empty string)Conteúdo bruto da licença — de uma variável de ambiente, um gerenciador de segredos ou um banco de dados.
LicenseStreamnullLicença como um stream, lida uma vez na inicialização.
ResetLicensefalseFlag de compatibilidade reservada. Os serviços .NET 6 atuais leem a licença durante AddDoconut(); reinicie o aplicativo após substituir uma licença.
MaxConcurrentEditorSessions200Número máximo de sessões de editor ao vivo (documentos abertos com DocOptions.EditMode). Acima disso, a sessão de editor ociosa menos recentemente usada é fechada. Sessões normais do visualizador nunca são contadas. 0 ou um valor negativo significa sem limite.
EditorSnapshotEveryOps50Com a persistência do editor habilitada (AddDoconutEditorPersistence), capture um instantâneo do documento ao vivo a cada N alterações registradas. 0 ou um valor negativo nunca captura instantâneos durante a sessão. Sem efeito quando a persistência está desativada.

Prioridade de licença quando mais de uma fonte está definida: LicenseStream tem precedência sobre LicenseContent, que tem precedência sobre LicensePath, que tem precedência sobre a pesquisa automática — veja Configuração de Licença.

csharp
builder.Services.AddDoconut(options =>
{
    options.LicensePath     = "Doconut.Viewer.lic";
    options.MiddlewarePath  = "/doconut";     // coordene com o mapeamento do aplicativo e o BasePath do cliente
    options.ResourcesPath   = "/doconut-res"; // de onde os JS/CSS/images do visualizador são servidos
    options.UnsafeMode      = false;          // mantenha a segurança da sessão ativada
    options.ShowDoconutInfo = false;
});

Próximos passos

Esta página foi útil?