Migração

Esta página cobre a atualização de uma aplicação ASP.NET existente de Doconut.NETFramework 26.8.0 ou anterior (.NET Framework 4.7) para 26.9.0 e posteriores (.NET Framework 4.7.2). O pacote de exemplos Doconut contém o guia completo de migração e os exemplos clássicos portados para a nova API — MVC 5, um farm web e Web Forms. Comparar sua aplicação com o exemplo de origem é o caminho mais rápido.

Um pacote, duas versões

Ambas as bibliotecas são publicadas sob o mesmo ID de pacote, Doconut.NETFramework. A versão as diferencia:

Atualizar o pacote é a atualização. Não há um pacote separado para instalar nem camada de compatibilidade: 26.9.0 tem uma superfície de API diferente, portanto espere erros de compilação após a atualização — o resto desta página. A linha .NET Framework 4.7 foi descontinuada e 26.8.0 é sua última versão. Você pode permanecer nela — nada aqui é uma correção de segurança que você perderia — mas novas versões, plugins, o modo distribuído e os widgets incorporados chegam apenas em 26.9.0 e posteriores.

1. Redirecionar e atualizar o pacote

Redirecione o projeto web para .NET Framework 4.7.2 primeiro: um projeto que ainda tem como alvo 4.7 não pode instalar 26.9.0, e o NuGet recusa a atualização. Em seguida, atualize Doconut.NETFramework e adicione os pacotes de plugins que você usa (Doconut.NETFramework.Converter, Doconut.NETFramework.Dicom, …). Cada plugin precisa de uma licença que o conceda.

Se o projeto usar packages.config, a atualização executa a etapa de desinstalação da versão anterior, que remove o manipulador DocImage de Web.config, e 26.9.0 não o adiciona novamente. Registre‑o novamente conforme mostrado na etapa 3; até fazer isso, DocImage.axd responde 404 e nenhuma página é renderizada.

2. Namespaces: quase tudo movido para a raiz

Os nomes dos tipos não mudaram: WordConfig, PdfConfig, ExcelConfig, CssConfig, ScriptConfig, FileShareConfig e o restante ainda estão presentes. Na maioria dos arquivos, a edição completa consiste em excluir linhas using.

3. Inicialização: DoconutHost.Initialize e duas entradas no Web.config

O pacote clássico construía seu visualizador por requisição, com opções como propriedades daquela instância. O novo pacote tem uma raiz de composição, construída uma única vez em Application_Start, e o visualizador é um serviço que você resolve:

// Antes - Doconut.NETFramework 26.8.0 e anteriores, por solicitação
var viewer = new Viewer
{
    ID = "ctlDoc",
    IncludeJQuery = true,
    BasePath = "/",
    FitType = "width"
};

// Doconut.NETFramework 26.9.0\u002B - Viewer resolvido a partir de DoconutHost, licença configurada uma vez em DoconutHost.Initialize()
var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();
var token  = await viewer.OpenDocumentAsync(path, new PdfConfig { AllowSearch = true });

DoconutHost.Initialize vai em Application_Start e DoconutHost.Shutdown em Application_End, e Web.config ganha o manipulador DocImage.axd e o módulo de recursos — ambos estão em Instalação. As configurações de aparência por página (FitType, FixedZoom, ShowHyperlinks, …) foram movidas da instância do visualizador para as opções do widget, ou para um ViewerConfig passado para Viewer.RenderViewer (veja ConfiguraçãoDoVisualizador). new Viewer() ainda compila depois que DoconutHost.Initialize for executado, portanto o código-behind migrado pode manter essa linha enquanto você move as configurações.

A segurança funciona como antes. Abrir um documento concede à sessão ASP.NET atual acesso às suas páginas, e DocImage.axd recusa todos os demais. A configuração de aplicativo DoconutUnSafeMode que desativava isso agora é options.UnsafeMode em DoconutHost.Initialize — deixe‑a false. Veja Sessões & Segurança.

A falha de inicialização que derruba todo o site. Um plugin registrado cuja capacidade nenhuma licença concede lança uma exceção em Application_Start, e a aplicação então responde com um 500 vazio a cada requisição — sem página de erro, nada no log do IIS, apenas uma entrada no log de eventos do Windows (fonte ASP.NET). Licenças são lidas de wwwroot sob a raiz do site e em nenhum outro lugar, e o Doconut.Viewer.lic base deve estar presente ou as licenças do plugin ao lado não são lidas. Veja Configuração de Licença.

4. Fazenda web: de uma bandeira para o modo distribuído

O modelo clássico era viewer.IsWebfarm = true mais ExportToPng(path). O novo modelo é registrado uma única vez: cada nó compartilha um armazenamento e uma chave de assinatura, e um ticket assinado vinculado ao navegador substitui “qualquer nó que responda”:

Doconut.DoconutHost.Initialize(
    options => options.UnsafeMode = false,
    services => services.AddDoconutDistributed(d =>
    {
        d.Store             = CloudLocation.FileShare;
        d.FileShareRootPath = @"\\fileserver\doconut-shared";   // WebfarmPath é um alias
        d.SigningKey        = farmKey;                           // >= 32 bytes, o mesmo em cada nó
    }));

Em seguida, abra documentos normalmente, vinculando o navegador (DocOptions.BrowserId = DoconutFarmBinding.EnsureBrowserId(...)) e passando viewer.AccessToken para o widget com o token. Sessions & Security tem as etapas; o exemplo de web-farm é um nó completo. IsWebfarm e WebfarmPath ainda compilam, mas não ativam mais nada.

Duas coisas que parecem sucesso mas não são: DistributedDocumentPublisher.PublishAsync grava os arquivos renderizados de um documento mas não abre sessão, então um visualizador apontado para um token publicado recebe a imagem de erro de ~2 KB com status 200; e um cliente de teste sem o cookie doconut-client recebe a mesma imagem, não um 401. Diferencie uma página real da imagem de erro pelo tamanho.

5. Conversão é um plugin, e muito menor

O enum SourceFormatConverter, as doze classes *ConfigConverter e seus enums de destino aninhados são substituídos por um único enum, ConversionTarget, e uma única chamada:

using System.IO;
using System.Threading;
using Doconut;
using Doconut.Configs.Conversion;

// Assuma que DoconutHost já está inicializado e um CancellationToken chamado ct está disponível.
var provider = DoconutHost.Services;
var converter = (DocumentConverter)provider.GetService(typeof(DocumentConverter));
Stream source = /* seu fluxo de entrada */;
var result = await converter.ConvertAsync(source, ".dwg", ConversionTarget.Pdf, null, ct);

O formato de origem vem da extensão que você fornece. Não há camada de compatibilidade: cada referência a SourceFormatConverter gera um erro de compilação que você resolve excluindo-a. Os objetos de opções por formato não sobreviveram — WordConfigConverter.HtmlOptions e CadConfigConverter.CadOptions.ShowColor não têm equivalente via ConvertAsync. No Web Forms, nunca bloqueie em ConvertAsync — veja Converter Plugin.

6. Armazenamento em nuvem: acesse‑o como uma pasta compartilhada

Os tipos de configuração da nuvem foram movidos para Doconut.Clouds sem alterações. Os manipuladores de requisição da nuvem, porém, são componentes ASP.NET Core, e uma aplicação clássica não possui pipeline para executá‑los. A partir de um site System.Web, acesse o armazenamento em nuvem como uma pasta compartilhada — no Azure, um compartilhamento Azure Files montado em cada nó — endereçado através de FileShareConfig.

7. As mudanças do lado do cliente que falham silenciosamente

Cada item abaixo compila, executa, não registra nada e faz a coisa errada:

Mais três: o visualizador não desenha sua própria barra de ferramentas (sua página conecta Zoom, Next, GotoPage e o resto aos seus próprios botões); um visualizador criado dentro de um modal Bootstrap oculto mede 0×0 e não pinta nada até que você dê ao seu contêiner uma altura explícita e o ajuste novamente em shown.bs.modal; e AllowSearch tem como padrão false para PDF, então um documento é renderizado perfeitamente enquanto toda busca não retorna nada.

8. O que desaparece

Ordem sugerida de trabalho

1. Redirecionar, trocar o pacote e fazer Global.asax compilar com DoconutHost.Initialize e as duas inscrições Web.config. O site deve iniciar.
2. Uma página de visualizador: obter um documento para renderizar, então trabalhar pela seção 7 até que a barra de ferramentas, a pesquisa e as anotações funcionem. Verificar em um navegador real — nada nessa seção gera um erro.
3. Conversão (seção 5): mecânica, e a maioria dos erros de compilação.
4. As páginas restantes, usando as amostras portadas como alvo de diferença.
5. A fazenda web (seção 4), se você tiver uma. Teste com dois nós e um navegador, ou um cliente que mantém cookies.