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.

O aplicativo host deve direcionar um runtime que suporte netstandard2.1 — .NET Core 3.0 ou superior.

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 requisição que o alcança, portanto monte‑o em seu próprio branch 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 requisiçã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 o faz, e sem ele o aplicativo falha na inicialização com Unable to resolve service for type 'IDistributedCache'. Já registrou o Doconut durante a Instalação? Pule adiante para a próxima seção.

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á adiciona 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());

Esta configuração mantém o formato histórico da requisição DocImage.axd e monta o middleware de documento em um branch correspondente. Esta é a disposição a ser copiada quando você está avançando um aplicativo .NET Standard existente, porque o cliente continua chamando a mesma URL que sempre usou:

csharp
builder.Services.AddDoconut(options =>
{
    options.UnsafeMode      = false;   // mantenha a verificação de sessão do Doconut habilitada
    options.ShowDoconutInfo = false;
});
builder.Services.AddDistributedMemoryCache(); // o estado da sessão precisa de um cache (MVC/Razor Pages já adiciona um)
builder.Services.AddSession(options =>
{
    options.IdleTimeout        = TimeSpan.FromSeconds(3600);
    options.Cookie.HttpOnly    = true;
    options.Cookie.IsEssential = true;
});

// Necessário para codificações multibyte em alguns formatos de documento.
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);

app.UseStaticFiles();
app.UseRouting();
app.UseSession();
app.UseDoconutResources();   // ANTES do ramo do documento
app.MapWhen(
    context => context.Request.Path.Value?.EndsWith("DocImage.axd", StringComparison.OrdinalIgnoreCase) == true,
    branch => branch.UseDoconut());

UseDoconut() não aceita opções nesta versão — tudo foi movido para AddDoconut(). MiddlewarePath é um valor de coordenação; ele não mapeia um branch do ASP.NET Core por si mesmo. Com o branch DocImage.axd acima, o cliente usa BasePath: '/'; com app.Map("/doconut", ...) da configuração mínima, ele 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'.

Adicionar o visualizador a uma página

O Viewer é o núcleo obrigatório da página. Sua superfície de renderização usa dois divs aninhados:

html
<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 autônomos: eles sempre se anexam ao Viewer na mesma página.

html
<nav id="toolbar" aria-label="Document viewer controls">
    <!-- Botões de navegação, zoom, pesquisa e anotação do visualizador -->
</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 injetado Viewer emite as tags <link> e <script> do visualizador em ordem de dependência — o widget é um plugin jQuery, portanto o jQuery deve ser carregado antes dos scripts do visualizador:

html
@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 Visualizador, solicite os recursos do Visualizador e do módulo juntos:

html
@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 Search ou Annotation Ribbon sem eles, a montagem do Visualizador 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 Visualizador central ainda inicia.

Essas chamadas substituem arquivos de script copiados manualmente. Se a aplicação ainda carregar seus próprios docViewer.js, documentLinks.js ou docViewer.UI.js, remova essas tags assim que a página funcionar a partir dos recursos emitidos — veja o guia de migração.

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):

javascript
let searchBar = null;
let annBar = null;

const objViewer = $('#div_ctlDoc').docViewer({
    showThumbs: true,
    autoLoad:   false,
    pageZoom:   100,
    FitType:    'width',
    BasePath:   '/',                   // o ramo DocImage.axd; 'doconut' com app.Map("/doconut", ...)
    ResPath:    'doconut-res/images',
    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);
    }
});

Quatro detalhes determinam se esta página funciona de fato:

  • Callbacks são opções. onViewerReady, onViewerBusy, onCopy e onAutoLoadStatus são passados no objeto de opções. O visualizador anterior derivava nomes de funções globais a partir do id do contêiner e as chamava; este não o faz. Um manipulador declarado apenas como função global nunca é executado, e nada é relatado.
  • ResPath aponta para o prefixo dos recursos, não para a raiz da aplicação. Com o padrão ResourcesPath, esse valor é doconut-res/images. Se você alterou ResourcesPath, use seu próprio prefixo. Os ícones ficam uma pasta abaixo da raiz dos recursos: com 'doconut-res', cada ícone retorna 404 enquanto o próprio documento ainda é renderizado.
  • BasePath não tem barra inicial exceto o valor da raiz do site '/'. 'doconut' solicita /doconut/DocImage.axd; '/doconut' produz //doconut/DocImage.axd, que o navegador interpreta como uma solicitação para outro host.
  • Mantenha o visualizador, então chame View separadamente. docViewer(...) retorna o objeto com Zoom, Next e FitType; View(...) retorna outra coisa. var objViewer = $('#div_ctlDoc').docViewer({...}).View(token) renderiza o documento, então falha com objViewer.Zoom is not a function no primeiro clique da barra de ferramentas.

Todas essas falham silenciosamente — veja Solução de Problemas e o guia de migração.

A capitalização das opções é realmente mista — showThumbs, autoLoad e pageZoom estão em camelCase, mas FitType, BasePath e ResPath estão em PascalCase. Não há regra consistente; errar a capitalização faz com que a opção seja ignorada silenciosamente (o widget recorre ao seu padrão em vez de gerar erro).

Montar o pacote completo do Viewer

Uma página completa do visualizador instala as seguintes partes juntas:

Parte do pacoteRequisitoComo está conectado
Recursos do Viewer, montagem e objViewerObrigatórioRenderizador de documento principal
Barra de ferramentas do ViewerObrigatório para uma página completaMarcação do host; botões chamam o mesmo objViewer
Faixa de pesquisaOpcional, módulo licenciadodoconutSearchBar(...).attach(objViewer)
Faixa de anotaçãoOpcional, módulo licenciadodoconutAnnotationBar(...).attach(objViewer)

Embora a barra de ferramentas principal do Viewer seja marcação do host, ela é instalada ao lado do Viewer 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 aciona a mesma instância do Viewer:

html
<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>

Mantenha esta ordem de inicialização:

  1. Emita CSS para o Viewer e módulos licenciados.
  2. Renderize a barra de ferramentas do Viewer, as montagens de Pesquisa/Anotação e a montagem do Viewer juntos.
  3. Emita scripts para o Viewer e módulos licenciados.
  4. Carregue o script auxiliar da barra de ferramentas da própria aplicação host.
  5. Inicialize docViewer e mantenha o objViewer resultante.
  6. Inicialize cada Faixa de Pesquisa ou Anotação licenciada.
  7. Chame attach(objViewer) em cada Faixa.
  8. Abra o documento e retenha seu token para solicitações do Viewer e dos módulos.

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.

html
<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 barras 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 Viewer 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. A abertura é assíncrona nesta versão.

csharp
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):

javascript
fetch('/api/open', { method: 'POST' })
    .then(resp => resp.json())
    .then(data => {
        token = data.token;
        objViewer.View(token);
    });

Não há nada a preparar antes da primeira abertura. Se você estiver avançando uma aplicação, exclua qualquer chamada InitCache() e a bandeira que a protege — o método não existe mais.

Fechar o documento

Chame objViewer.Close(true) quando o usuário sair do visualizador ou abrir 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 de solicitação completo é:

text
AddDoconut + middleware
    -> render CSS/scripts and mount div
    -> initialize docViewer
    -> OpenDocumentAsync
    -> return opaque token
    -> objViewer.View(token)
    -> page/search/annotation requests
    -> Close / CloseDocument

Trate 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 não acontecer, veja 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 exibe uma marca d'água de avaliação. Veja 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?