Instalação

Adicione Doconut à sua aplicação web .NET Framework 4.7.2

Doconut.NETFramework hospeda o visualizador Doconut em uma aplicação ASP.NET clássica no .NET Framework 4.7.2 — IIS ou IIS Express, MVC 5 ou Web Forms. A configuração tem três partes: o pacote NuGet, duas registragens em Web.config e uma chamada em Global.asax. Esta página cobre todas as três; Início Rápido então coloca um documento em uma página.

Requisitos

  • O projeto web tem como alvo .NET Framework 4.7.2 ou posterior. Um projeto 4.7 não pode consumir este pacote; altere o alvo primeiro.
  • O site executa no pipeline integrado (o padrão para pools de aplicativos IIS e IIS Express).
  • O servidor executa Windows. O pacote é exclusivo para Windows.

Esta página cobre Doconut.NETFramework 26.9.0 e posteriores. Versões 26.8.0 e anteriores visavam .NET Framework 4.7 com uma API diferente; essa linha foi descontinuada. Atualizar uma aplicação existente através desse limite é abordado em Migração.

Instalar o pacote

A partir do Console do Gerenciador de Pacotes:

powershell
Install-Package Doconut.NETFramework

Ou, em um projeto no estilo SDK:

bash
dotnet add package Doconut.NETFramework

Os comandos sem versão instalam a versão estável mais recente. Para fixar a versão que esta documentação descreve, passe a versão:

powershell
Install-Package Doconut.NETFramework -Version 26.10.0
bash
dotnet add package Doconut.NETFramework --version 26.10.0

O mecanismo de renderização está incorporado no pacote: não há um assembly de mecanismo separado para referenciar, copiar ou implantar. Capacidades opcionais são distribuídas como seus próprios pacotes — por exemplo Doconut.NETFramework.Converter e Doconut.NETFramework.Dicom — e cada um precisa de uma licença que o conceda (veja Sistema de Plugins).

Configurar Web.config

Doconut serve dois tipos de requisição, e o IIS roteia ambos através de Web.config:

  • DocImage.axd — a página do visualizador, miniatura, busca e ponto final de anotações, servidos por Doconut.DocImageHandler.
  • /doconut-res/* — os próprios scripts, folhas de estilo e ícones do visualizador, incorporados no assembly e servidos por Doconut.DoconutResourceModule.

Adicione ambos, mais as configurações das quais dependem:

xml
<configuration>
  <system.web>
    <!-- Apenas MVC 5: Razor compila visualizações em tempo de execução e precisa da fachada netstandard. -->
    <compilation targetFramework="4.7.2">
      <assemblies>
        <add assembly="netstandard, Version=2.0.0.0, Culture=neutral, PublicKeyToken=cc7b13ffcd2ddd51" />
      </assemblies>
    </compilation>
    <!-- maxRequestLength está em KILOBYTES: 200 MB. -->
    <httpRuntime targetFramework="4.7.2" maxRequestLength="204800" />
    <!-- Leia arquivos .cshtml e .aspx como UTF-8, não como a página de código ANSI do servidor. -->
    <globalization fileEncoding="utf-8" requestEncoding="utf-8" responseEncoding="utf-8" />
  </system.web>
  <system.webServer>
    <security>
      <requestFiltering>
        <!-- maxAllowedContentLength está em BYTES: os mesmos 200 MB. -->
        <requestLimits maxAllowedContentLength="209715200" />
      </requestFiltering>
    </security>
    <modules runAllManagedModulesForAllRequests="true">
      <add name="DoconutResourceModule" type="Doconut.DoconutResourceModule, Doconut" />
    </modules>
    <handlers>
      <add name="DocImage" verb="GET,HEAD,POST" path="DocImage.axd"
           type="Doconut.DocImageHandler, Doconut" />
    </handlers>
  </system.webServer>
</configuration>

Cada linha impede uma falha que não gera exceção:

  • verb="GET,HEAD,POST" — mantenha HEAD. O visualizador envia uma requisição HEAD para a página 1 para detectar imagens animadas. Sem o verbo, o IIS responde 404 antes que o manipulador seja executado: os documentos ainda são exibidos, mas a detecção de animação nunca funciona e o console do navegador se enche de 404s.
  • runAllManagedModulesForAllRequests="true" — /doconut-res/*.js, .css e .png parecem arquivos estáticos, e o IIS os entregaria ao seu manipulador de arquivos estáticos antes que o módulo de recursos os veja. O resultado é um visualizador sem scripts ou ícones.
  • <globalization fileEncoding="utf-8"> — arquivos de página salvos como UTF-8 sem marca de ordem de bytes são lidos com a página de código ANSI do servidor, então cada caractere não-ASCII chega ao navegador codificado duas vezes (um travessão aparece como —). O arquivo está correto no disco, e a página ainda declara <meta charset="utf-8">.
  • O assembly netstandard (MVC 5) — Razor compila as visualizações quando são solicitadas pela primeira vez, com sua própria lista de referências que não inclui esta fachada. Uma visualização que faça algo dinâmico além de um simples acesso a membro falha então com CS0012 e responde um 500 vazio, e somente as páginas que a acionam falham. O erro do compilador aparece apenas no log de eventos do Windows (fonte ASP.NET). Aplicações Web Forms não precisam desta linha.
  • Limites de upload — ASP.NET lê todo o corpo da requisição antes que qualquer manipulador seja executado, então um upload acima desses limites é rejeitado pelo IIS com sua própria página de erro. Mantenha maxRequestLength (kilobytes) e maxAllowedContentLength (bytes) em conformidade, e acima do maior arquivo que seus usuários abram ou enviem.

Mais duas configurações são importantes, e ambas geralmente já estão corretas:

  • O estado da sessão permanece ativo. Por padrão, uma página é servida apenas para a sessão ASP.NET que abriu o documento, portanto o site não deve definir <sessionState mode="Off" />. Veja Sessões e Segurança.
  • Redirecionamentos de binding. Mantenha os redirecionamentos de binding <runtime> que o NuGet grava em Web.config. Em um projeto no estilo SDK, copie-os do bin\<YourApp>.dll.config gerado, porque o ASP.NET clássico lê redirecionamentos apenas de Web.config. Um redirecionamento que nomeia uma versão ausente de bin\ interrompe toda a aplicação com um 500 vazio na inicialização.

Registrar Doconut em Global.asax

Não há construtor nem pipeline de middleware em System.Web. Doconut é composto uma vez por processo de trabalho por DoconutHost.Initialize em Application_Start, e liberado por DoconutHost.Shutdown em Application_End:

csharp
// Global.asax.cs
protected void Application_Start()
{
    Doconut.DoconutHost.Initialize(options =>
    {
        options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
    });
}

protected void Application_End()
{
    Doconut.DoconutHost.Shutdown();
}

DoconutHost.Initialize constrói os serviços, o manipulador, o módulo de recursos e o uso do seu próprio código. Seu código os acessa através de DoconutHost.Services (veja DoconutHost). Apenas a primeira chamada configura algo; uma segunda chamada é ignorada. Em uma aplicação MVC, mantenha também os dois caminhos Doconut fora do roteamento — Início Rápido mostra o Application_Start completo.

Todas as opções

DoconutOptions aceita as seguintes propriedades configuráveis. Cada uma é opcional.

PropriedadePadrãoDescrição
UnsafeModefalseQuando false, DocImage.axd serve uma página apenas para a sessão ASP.NET que abriu o documento. Quando true, qualquer solicitação que contenha o token é atendida. Deixe false.
ShowDoconutInfofalseQuando true, uma solicitação DocImage.axd sem token responde com um banner de versão em vez de 404. Útil como verificação rápida; deixe desativado em produção.
ResourcesPath"/doconut-res"Onde o módulo de recursos serve os scripts, estilos e ícones incorporados. Altere isso apenas junto com o ResPath do visualizador e qualquer IgnoreRoute do MVC.
LicensePath""Caminho completo para o arquivo de licença. Vazio significa passar para a próxima fonte, depois para a descoberta automática.
LicenseContent""Conteúdo bruto da licença — de uma variável de ambiente, um armazenamento secreto ou um banco de dados.
LicenseStreamnullLicença como fluxo, lida uma vez na inicialização.
MiddlewarePath"/doconut"Não usado neste pacote. O ponto de extremidade da página é o manipulador DocImage.axd declarado em Web.config, seja qual for a configuração. Ainda é validado: deve começar com / e diferir de ResourcesPath.
ResetLicensefalseNão usado neste pacote. A licença é lida uma vez, em DoconutHost.Initialize; recicle o pool de aplicativos após substituir um arquivo de 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 persistência do editor habilitada (AddDoconutEditorPersistence), capture instantâneos 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.

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

csharp
Doconut.DoconutHost.Initialize(options =>
{
    options.LicensePath     = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
    options.ResourcesPath   = "/doconut-res"; // de onde os JS/CSS/imagens do visualizador são servidos
    options.UnsafeMode      = false;          // manter a segurança da sessão ativada
    options.ShowDoconutInfo = false;
});
// O endpoint da página não é uma opção aqui: é o manipulador DocImage.axd declarado no Web.config.

Próximos passos

Esta página foi útil?