Início Rápido
Renderize seu primeiro documento em minutos
Este tutorial leva um aplicativo ASP.NET Core de um Program.cs vazio a um documento renderizado no navegador: registro do servidor, o pacote completo do Viewer (barra de ferramentas do Viewer, montagem do Viewer e fitas opcionais de Busca/Anotação), referências de recursos, inicialização do cliente, abertura do documento e execução.
Configuração do servidor
AddDoconut() registra os serviços; UseDoconutResources() e UseDoconut() conectam o middleware. A chamada de recursos deve vir primeiro. UseDoconut() responde a cada solicitação que o alcança, portanto monte‑o em seu próprio ramo com app.Map. As chamadas de sessão também são necessárias — a segurança de documento padrão do Doconut valida cada solicitação de página contra o estado de sessão do ASP.NET. O estado de sessão precisa de um cache: AddDistributedMemoryCache() fornece um. Um aplicativo MVC ou Razor Pages já o registra, mas um aplicativo minimal‑API não, e sem ele o aplicativo para na inicialização com Unable to resolve service for type 'IDistributedCache'. Já registrou o Doconut durante a Instalação? Avance para a próxima seção.
builder.Services.AddDoconut(options =>
{
options.LicensePath = "Doconut.Viewer.lic";
});
builder.Services.AddDistributedMemoryCache(); // o estado de sessão precisa de um cache (MVC/Razor Pages já adicionam um)
builder.Services.AddSession(); // A segurança de documentos Doconut depende do estado de sessão do ASP.NET
app.UseSession(); // chame UseSession() antes de UseDoconut()
app.UseDoconutResources(); // deve ser registrado antes de UseDoconut()
app.Map("/doconut", branch => branch.UseDoconut());Para um layout de caminho ao estilo de produção, mapeie o middleware de documento para um ramo explícito e mantenha as quatro configurações de caminho alinhadas:
builder.Services.AddDoconut(options =>
{
options.LicensePath = Path.Combine(AppContext.BaseDirectory, "wwwroot", "Doconut.Viewer.lic");
options.MiddlewarePath = "/doconut";
options.ResourcesPath = "/doconut-res";
options.UnsafeMode = false;
});
builder.Services.AddDistributedMemoryCache();
builder.Services.AddSession();
app.UseRouting();
app.UseSession();
app.UseDoconutResources();
app.Map("/doconut", branch => branch.UseDoconut());MiddlewarePath é um valor de coordenação; ele não mapeia um ramo do ASP.NET Core por si só. Neste exemplo o host mapeia /doconut, então o cliente usa BasePath: 'doconut'. ResourcesPath serve o pacote incorporado em /doconut-res, e o caminho do recurso de imagem do widget é, portanto, ResPath: 'doconut-res/images'. Escreva ambos sem uma barra inicial: o viewer adiciona uma automaticamente, então '/doconut' se tornaria //doconut/DocImage.axd, que o navegador interpreta como uma solicitação a um host chamado doconut, e o viewer falha com "The viewer handler could not be reached".
Adicionar o visualizador à página
O Viewer é o núcleo obrigatório da página. Sua superfície de renderização usa dois divs aninhados:
<div id="divDocViewer">
<div id="div_ctlDoc"></div>
</div>Trate a barra de ferramentas, as montagens de módulos e a superfície do Viewer como uma única composição de página. Busca e Anotação injetam suas fitas incorporadas em montagens opcionais, mas esses módulos nunca são independentes: eles sempre se anexam ao Viewer na mesma página. Use esta ordem:
<nav id="toolbar" aria-label="Document viewer controls">
<!-- Botões de navegação, zoom, Pesquisa e Anotação do Viewer -->
</nav>
<div id="searchBarMount"></div>
<div id="annBarMount"></div>
<div id="divDocViewer">
<div id="div_ctlDoc"></div>
</div>Referenciar os recursos do visualizador
Em uma visualização Razor, o serviço Viewer injetado emite as tags <link> e <script> do viewer em ordem de dependência — o widget é um plugin jQuery, portanto o jQuery deve ser carregado antes dos scripts do viewer:
@inject Doconut.Viewer Viewer
@Html.Raw(Viewer.ReferenceCss(new CssConfig
{
IncludeBootstrapCss = true,
IncludeViewerCss = true
}))
@Html.Raw(Viewer.ReferenceScripts(new ScriptConfig
{
IncludeJQuery = true,
IncludeBootstrap = true,
IncludeViewerScripts = true
}))Para o pacote completo do Viewer, solicite os recursos do Viewer e do módulo juntos:
@Html.Raw(Viewer.ReferenceCss(new CssConfig
{
IncludeBootstrapCss = true,
IncludeViewerCss = true,
IncludeSearchCss = true,
IncludeAnnotationCss = true
}))
@Html.Raw(Viewer.ReferenceScripts(new ScriptConfig
{
IncludeJQuery = true,
IncludeBootstrap = true,
IncludeViewerScripts = true,
IncludeSearchScripts = true,
IncludeSearchBar = true,
IncludeAnnotationScripts = true,
IncludeAnnotationBar = true
}))IncludeViewerCss e IncludeViewerScripts são as flags centrais obrigatórias. Nunca publique um exemplo de fita de Busca ou Anotação sem eles, a montagem do Viewer e uma instância docViewer. ReferenceCss e ReferenceScripts omitem os recursos de um módulo opcional quando a licença atual não concede essa capacidade; o Viewer central ainda inicia.
Inicializar o visualizador
O widget do lado do cliente é um plugin jQuery. Este é um conjunto mínimo de opções reais de inicialização (não pseudocódigo):
let searchBar = null;
let annBar = null;
const objViewer = $('#div_ctlDoc').docViewer({
showThumbs: true,
autoLoad: false,
pageZoom: 100,
FitType: 'width',
BasePath: 'doconut', // sem '/' no início
ResPath: 'doconut-res/images', // sem '/' no início
onViewerReady: function () {
// as páginas estão visíveis; é seguro ocultar um spinner de carregamento aqui
},
// Encaminhar eventos do ciclo de vida da anotação para a ribbon incorporada quando ela estiver presente.
onAnnLoaded: () => annBar?.handleAnnLoaded(),
onAnnSaved: () => annBar?.handleAnnSaved(),
onAnnSaveError: () => annBar?.handleAnnSaveError(),
onAnnClosed: () => annBar?.handleAnnClosed(),
onError: function (message) {
console.error('Doconut viewer error:', message);
}
});A capitalização das opções é realmente misturada — showThumbs, autoLoad e pageZoom estão em camelCase, mas FitType, BasePath e ResPath estão em PascalCase. Não há regra consistente; se a capitalização estiver errada, a opção será ignorada silenciosamente (o widget recairá para seu padrão em vez de lançar um erro).
Mais quatro detalhes falham sem uma mensagem de erro:
BasePathnão tem barra inicial.'doconut'solicita/doconut/DocImage.axd;'/doconut'produz//doconut/DocImage.axd, que o navegador interpreta como uma solicitação a outro host.ResPath: 'doconut-res/images'— os ícones estão uma pasta abaixo da raiz de recursos. Com'doconut-res', cada ícone devolve 404: sem glifos da barra de ferramentas e sem spinner de carregamento, enquanto o próprio documento ainda é renderizado. Uma barra inicial quebra da mesma forma queBasePath.- Callbacks são opções.
onViewerReady,onErrore o resto vão no objeto passado paradocViewer(...). Uma função global nomeada após o visualizador, comoctlDoc_ViewerReady, nunca é chamada. - Mantenha o visualizador, então chame
Viewseparadamente.docViewer(...)devolve o objeto comZoom,NexteFitType;View(...)devolve outra coisa.var objViewer = $('#div_ctlDoc').docViewer({...}).View(token)renderiza o documento, então falha comobjViewer.Zoom is not a functionno primeiro clique da barra de ferramentas.
Montar o pacote completo do Visualizador
Uma página completa do visualizador instala as seguintes partes juntas:
| Parte do pacote | Requisito | Como está conectado |
|---|---|---|
Recursos do visualizador, montagem e objViewer | Obrigatório | Renderizador central de documentos |
| Barra de ferramentas do visualizador | Obrigatório para uma página completa | Marcação do host; botões chamam o mesmo objViewer |
| Faixa de pesquisa | Opcional, módulo licenciado | doconutSearchBar(...).attach(objViewer) |
| Faixa de anotação | Opcional, módulo licenciado | doconutAnnotationBar(...).attach(objViewer) |
Embora a barra de ferramentas principal do Visualizador seja marcação do host, ela é instalada ao lado do Visualizador e nunca deve ser documentada como um controle isolado. Isso mantém seu layout, rótulos, ícones e regras de autorização sob o controle da sua aplicação, enquanto cada botão controla a mesma instância do Visualizador:
<nav id="toolbar" aria-label="Document viewer controls">
<button type="button" onclick="objViewer.GotoPage(1)">First</button>
<button type="button" onclick="objViewer.Next(false)">Previous</button>
<button type="button" onclick="objViewer.Next(true)">Next</button>
<button type="button" onclick="objViewer.GotoPage(objViewer.TotalPages())">Last</button>
<button type="button" onclick="objViewer.Zoom(false)">Zoom out</button>
<button type="button" onclick="objViewer.Zoom(true)">Zoom in</button>
<button type="button" onclick="objViewer.FitType('width')">Fit width</button>
<button type="button" onclick="objViewer.FitType('height')">Fit height</button>
<button type="button" id="openSearch">Search</button>
<button type="button" id="openAnnotations">Annotations</button>
</nav>Os auxiliares de rotação, miniatura, impressão, tela cheia, layout e estado dos botões pertencem ao seu próprio script de barra de ferramentas, que chama o mesmo objViewer. Carregue‑o após Viewer.ReferenceScripts(...) e mantenha‑o junto com sua marcação <nav id="toolbar">.
Mantenha esta ordem de inicialização:
- Emita CSS para o Visualizador e módulos licenciados.
- Renderize a barra de ferramentas do Visualizador, as montagens de Pesquisa/Anotação e a montagem do Visualizador juntos.
- Emita scripts para o Visualizador e módulos licenciados.
- Carregue o script auxiliar da barra de ferramentas da própria aplicação host.
- Inicialize
docViewere mantenha oobjViewerresultante. - Inicialize cada Faixa de Pesquisa ou Anotação licenciada.
- Chame
attach(objViewer)em cada Faixa. - Abra o documento e retenha seu token para solicitações do Visualizador e dos módulos.
Em uma implantação distribuída, o valor de solicitação adicional access e as configurações de tentativa de renderização assíncrona pertencem ao transporte; eles não alteram como o Visualizador, a barra de ferramentas ou as Faixas são montados.
As proteções do lado do servidor são importantes: quando uma capacidade opcional não está disponível, seu script não é emitido, portanto sua função de plug‑in jQuery não existe.
<script>
let token = '';
const refitViewer = () =>
requestAnimationFrame(() => objViewer.Refit());
@if (Viewer.IsSearchEnabled)
{
<text>
searchBar = $('#searchBarMount').doconutSearchBar({
docId: 'ctlDoc',
getRequestParams: () => ({ token }),
onLayout: refitViewer
});
searchBar.attach(objViewer);
</text>
}
@if (Viewer.IsAnnotationEnabled)
{
<text>
annBar = $('#annBarMount').doconutAnnotationBar({
docId: 'ctlDoc',
getRequestParams: () => ({ token }),
onLayout: refitViewer
});
annBar.attach(objViewer);
</text>
}
document.getElementById('openSearch').addEventListener('click', () => {
if (!searchBar) return;
searchBar.isOpen() ? searchBar.close() : searchBar.open();
});
document.getElementById('openAnnotations').addEventListener('click', () => {
if (!annBar) return;
annBar.isOpen() ? annBar.close() : annBar.open();
});
</script>Ambos os componentes incorporados geram seu próprio DOM de Faixa. A Pesquisa contém os grupos Encontrar, Opções e Resultados. A Anotação contém suas ferramentas de autoria, controles de estilo, ações de salvamento e ações opcionais de exportação/imagem. As faixas expõem open(), close(), reset() e isOpen(); sempre chame attach(objViewer) uma vez após criá‑las.
O exemplo acima omite callbacks opcionais do host e endpoints de exportação/imagem da Anotação para manter a inicialização mínima. Veja Pesquisa e Anotações para a configuração completa específica de recursos, ou Temas Personalizados para estilizar ou substituir a barra de ferramentas do Visualizador de propriedade do host.
Abrir um documento
O lado do servidor tem um único endpoint: o serviço injetado Viewer abre o documento e devolve um token de sessão.
app.MapPost("/api/open", async (Viewer viewer) =>
{
// O token é opaco — entregue-o ao widget, nunca registre ou persista-o.
string token = await viewer.OpenDocumentAsync("wwwroot/files/Sample.pdf");
return Results.Ok(new { token });
});O cliente obtém esse token e o entrega ao widget com objViewer.View(token):
fetch('/api/open', { method: 'POST' })
.then(resp => resp.json())
.then(data => {
token = data.token;
objViewer.View(token);
});Fechar o documento
Chame objViewer.Close(true) quando o usuário sai do visualizador ou abre um documento de substituição: ele limpa o widget e envia uma solicitação de fechamento ao servidor. objViewer.Close() sem argumento limpa apenas o widget. Em fluxos de trabalho controlados pelo servidor, viewer.CloseDocument(token) remove imediatamente a sessão em cache, descarta o motor de renderização, exclui seu marcador de segurança e revoga o token. A expiração deslizante eventualmente realiza a mesma limpeza, mas o fechamento explícito é recomendado para documentos grandes.
O fluxo completo de requisição é:
AddDoconut + middleware
-> render CSS/scripts and mount div
-> initialize docViewer
-> OpenDocumentAsync
-> return opaque token
-> objViewer.View(token)
-> page/search/annotation requests
-> Close / CloseDocumentTrate o token como uma credencial de portador: nunca o registre, nunca o persista, entregue‑o apenas ao widget. Ele identifica uma sessão de documento ativa no servidor e deixa de funcionar quando essa sessão expira — reabra o documento para obter um novo.
Executar
Coloque um PDF em wwwroot/files/Sample.pdf, execute dotnet run e abra a página que hospeda o widget. A primeira página é renderizada no visualizador, com um painel de miniaturas à esquerda. Se isso não acontecer, consulte Solução de Problemas.
O que você obtém sem licença
A falta de licença não gera erro. O visualizador renderiza normalmente, mas cada página contém uma marca d'água de avaliação. Consulte Configuração de Licença para saber como o Doconut encontra uma licença e o que muda quando isso ocorre.
Esta página foi útil?