Instalação

Adicionar Doconut ao seu projeto .NET Standard 2.1

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

Verifique primeiro o framework do host

A biblioteca tem como alvo netstandard2.1. Esse é um contrato mais restrito que a compilação netstandard2.0 anterior, e é a primeira coisa a ser verificada:

HostSuportado
.NET Core 3.0 ou posterior, incluindo .NET 5/6/7/8Sim
.NET Framework (qualquer versão)Não — netstandard2.1 não pode ser consumido pelo .NET Framework

O pacote funciona apenas em Windows. Para um host Linux, use Doconut.NET8 ou Doconut.NET6.

Se a aplicação roda no .NET Framework, este não é o pacote correto. Use Doconut.NETFramework em vez disso; a partir da 26.9.0 ele requer .NET Framework 4.7.2.

Instalar o pacote

bash
dotnet add package Doconut.NETStandard

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

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

O número da versão indica a geração

Isso importa mais aqui do que o nome do pacote. Ambas as gerações da biblioteca .NET Standard são publicadas sob o mesmo ID de pacote, e somente a versão as diferencia:

VersãoAlvoAPI
26.7.0 e abaixonetstandard2.0a integração anterior
26.8.0 e acimanetstandard2.1a integração documentada aqui

Não há camada de compatibilidade nem pacote lado a lado. Atualizar a versão é a atualização, e o compilador reportará as diferenças de API imediatamente.

Não selecione a documentação apenas pelo nome do pacote:

  • new Viewer(_cache, _accessor, …), UnSafeMode, synchronous OpenDocument(...), viewer.InitCache(), UseDoconutWebFarm, e scripts de visualizador copiados manualmente identificam a integração anterior;
  • AddDoconut(), UseDoconutResources(), um Viewer injetado, e OpenDocumentAsync(...) identificam a integração atual documentada aqui.

O manual de configuração anterior traduzido continua disponível. Use o guia de migração para mudar de geração; uma atualização de 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() é middleware terminal, então chamá‑lo primeiro significa que toda requisição a um recurso /doconut-res nunca chega ao manipulador de recursos e gera 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());

Namespaces

Os tipos de configuração não estão mais distribuídos em quatro namespaces. Nesta versão quase tudo reside no namespace raiz Doconut:

csharp
using Doconut;                       // Viewer, DoconutOptions, DocOptions, todas as configurações de formato
using Doconut.Middleware;            // AddDoconut, UseDoconut, UseDoconutResources
using Doconut.Clouds;                // configurações de nuvem e compartilhamento de arquivos
using Doconut.Configs.Conversion;    // ConversionTarget

Os nomes dos tipos em si não mudaram — PdfConfig, WordConfig, ExcelConfig, CssConfig, ScriptConfig e o resto ainda estão presentes. Se você está migrando uma aplicação existente, a maioria dos arquivos precisa apenas de duas linhas using deletadas; veja o guia de migração.

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, pula a verificação de segurança da sessão ASP.NET nas requisições de página. Desative em produção. Observe a grafia — a biblioteca anterior chamava isso de UnSafeMode.
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 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 um stream, lida uma vez na inicialização.
ResetLicensefalseFlag de compatibilidade reservada. A licença é lida 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), faça snapshot do documento ao vivo a cada N alterações registradas. 0 ou um valor negativo nunca faz snapshot durante a sessão. Sem efeito quando a persistência está desativada.

Precedência de licença quando mais de uma fonte está definida: LicenseStream tem prioridade sobre LicenseContent, que tem prioridade sobre LicensePath, que tem prioridade 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 app e o BasePath do cliente
    options.ResourcesPath   = "/doconut-res"; // de onde o JS/CSS/imagens do viewer 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?