Instalação

Adicionar Doconut ao seu projeto .NET 8

O visualizador base Doconut para .NET 8 é 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

O pacote funciona nas seguintes plataformas:

PlataformaSuportado
Windows x64 / x86Sim
Linux x64, glibc-based (Debian, Ubuntu, a imagem oficial mcr.microsoft.com/dotnet/aspnet:8.0)Sim
Alpine and other musl-based distributionsNã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 precisa: as bibliotecas nativas que ele usa são enviadas dentro do pacote NuGet, e libgdiplus não é necessário. 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.NET8

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.NET8 --version 26.10.0

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

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() é middleware terminal, portanto chamá‑lo primeiro faz com que toda requisição a um recurso /doconut-res nunca alcance o 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 de 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 valores padrão abaixo se aplicam quando uma propriedade permanece sem definição.

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 de UseDoconut() e o BasePath do cliente.
ResourcesPath"/doconut-res"De onde os recursos incorporados de 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 busca 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 fluxo, lida uma vez na inicialização.
ResetLicensefalseFlag de compatibilidade reservada. Os serviços atuais do .NET 8 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 é encerrada. Sessões normais de visualizador nunca são contadas. 0 ou um valor negativo significa sem limite.
EditorSnapshotEveryOps50Com a persistência do editor habilitada (AddDoconutEditorPersistence), captura instantânea do documento ao vivo a cada N alterações registradas. 0 ou um valor negativo nunca captura instantaneamente durante a sessão. Sem efeito quando a persistência está desativada.

Prioridade da licença quando mais de uma fonte está configurada: LicenseStream tem precedência sobre LicenseContent, que tem precedência sobre LicensePath, que tem precedência sobre busca 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/imagens 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?