Instalação

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 declarações em Web.config e uma chamada em Global.asax. Esta página cobre 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 superior. Um projeto 4.7 não pode consumir este pacote; altere o alvo primeiro.
• O site é executado no pipeline integrado (o padrão para pools de aplicativos IIS e IIS Express).

Esta página cobre Doconut.NETFramework 26.9.0 e posteriores. As versões 26.8.0 e anteriores tinham como alvo o .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

Do Console do Gerenciador de Pacotes:

Install-Package Doconut.NETFramework

Ou, em um projeto estilo SDK:

dotnet add package Doconut.NETFramework

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 requer uma licença que o conceda (veja Sistema de Plugins).

Configurar Web.config

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

• DocImage.axd — a página do visualizador, miniatura, busca e ponto de extremidade de anotação, 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:

<configuration>
  <system.web>
    <!-- MVC 5 only: Razor compiles views at run time and needs the netstandard facade. -->
    <compilation targetFramework="4.7.2">
      <assemblies>
        <add assembly="netstandard, Version=2.0.0.0, Culture=neutral, PublicKeyToken=cc7b13ffcd2ddd51" />
      </assemblies>
    </compilation>
    <!-- maxRequestLength is in KILOBYTES: 200 MB. -->
    <httpRuntime targetFramework="4.7.2" maxRequestLength="204800" />
    <!-- Read .cshtml and .aspx files as UTF-8, not as the server's ANSI code page. -->
    <globalization fileEncoding="utf-8" requestEncoding="utf-8" responseEncoding="utf-8" />
  </system.web>
  <system.webServer>
    <security>
      <requestFiltering>
        <!-- maxAllowedContentLength is in BYTES: the same 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 esse verbo, o IIS responde 404 antes que o handler 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 handler 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, de modo que cada caractere não-ASCII chega ao navegador duplamente codificado (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 essa fachada. Uma visualização que faça algo dinâmico além de um simples acesso a membro falha com CS0012 e devolve um 500 vazio, e somente as páginas que a acionam falham. O erro de compilação 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 handler seja executado, portanto um upload acima desses limites é rejeitado pelo IIS com sua própria página de erro. Mantenha maxRequestLength (kilobytes) e maxAllowedContentLength (bytes) alinhados, 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 de 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 no Web.config. Em um projeto estilo SDK, copie-os do bin\<YourApp>.dll.config gerado, pois o ASP.NET clássico lê redirecionamentos apenas do 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 no 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:

// 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 cria os serviços que o manipulador, o módulo de recursos e seu próprio código utilizam. 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.

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.

Doconut.DoconutHost.Initialize(options =>
{
    options.LicensePath     = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
    options.ResourcesPath   = "/doconut-res"; // where the viewer's JS/CSS/images are served from
    options.UnsafeMode      = false;          // keep session security on
    options.ShowDoconutInfo = false;
});
// O endpoint da página não é uma opção aqui: ele é o manipulador DocImage.axd declarado no Web.config.

Próximos passos

• Início Rápido — abra um documento e renderize‑o no navegador, em MVC 5 ou Web Forms.
• Configuração de Licença — onde Doconut procura seu arquivo de licença.