Migrar para .NET Standard 2.1

Doconut tem duas integrações distintas do .NET Standard. Elas usam o mesmo nome de pacote Doconut.NETStandard, portanto identifique a geração a partir da versão e das APIs na aplicação antes de alterar pacotes, inicialização, licenças ou recursos do navegador.

A versão é a bifurcação

Ambas as gerações são publicadas sob o mesmo ID de pacote. Apenas a versão as diferencia:

Aumentar o número da versão é a atualização. Não há um pacote separado para instalar nem um shim de compatibilidade — 26.8.0 possui uma superfície de API diferente. Espere erros de compilação após o aumento; o restante deste guia é a lista desses erros.

Qual integração você está usando?

Se ambas as colunas aparecerem na mesma aplicação, trate a migração como incompleta. Não envie um token de documento através de recursos ou middleware da outra geração.

Verifique o framework host primeiro

Esta é uma barreira rígida, não uma preferência. O pacote atual tem como alvo netstandard2.1:

.NET Framework não pode referenciar uma biblioteca netstandard2.1. Se a aplicação roda em .NET Framework, pare aqui e use o pacote Doconut.NETFramework em vez disso; a partir da 26.9.0 ele requer .NET Framework 4.7.2. Ambas as aplicações de referência para esta versão têm alvo net8.0.

Antes de migrar

1. Crie um branch e um backup implantável da aplicação existente.
2. Registre as versões exatas dos pacotes core e plugin.
3. Faça um inventário de cada chamada new Viewer(...), chamada InitCache(), chamada de carregamento de licença, mapeamento UseDoconutWebFarm, controlador de conversão, script Doconut copiado, ação de barra de ferramentas personalizada, callback do visualizador e endpoint de abertura de documento.
4. Preserve os arquivos .lic atuais e segredos de implantação fora do controle de versão.
5. Capture um conjunto representativo de documentos PDF, Office, imagem, CAD, e‑mail, DICOM, pesquisáveis, protegidos por senha e anotados.
6. Registre o tempo limite da sessão existente, comportamento de segurança, fontes e configurações da plataforma.

Migre um ambiente antes de mudar a produção. A integração atual altera o tempo de vida do serviço, o roteamento de requisições, a propriedade da sessão, a entrega de recursos ao cliente e — se você opera uma fazenda — como as páginas chegam ao navegador.

1. Namespaces: quase tudo movido para a raiz

Os tipos de configuração estavam distribuídos em quatro namespaces. Agora todos estão em Doconut.

Os nomes dos tipos não mudaram: WordConfig, PdfConfig, ExcelConfig, CssConfig, ScriptConfig, CloudUploadConfig, AzureConfig, CDNConfig, FileShareConfig e o resto ainda está presente. Na maioria dos arquivos a edição completa consiste em excluir duas linhas using.

Doconut.Configs.Editor (BaseConfigEditor, PdfConfigEditor) foi removido e não tem substituição neste pacote. Se sua aplicação referenciava esses tipos, planeje essa parte separadamente e não a trate como parte desta migração.

2. Compatibilidade de pacotes e licenças

Substitua ou atualize o pacote principal deliberadamente; não dependa do ID de pacote idêntico para selecionar a nova API. O comando padrão instala a versão estável mais recente:

dotnet add package Doconut.NETStandard

Para uma migração reproduzível para a versão auditada por este guia, passe a versão como uma opção separada:

dotnet add package Doconut.NETStandard --version 26.8.0

Mantenha cada plugin Doconut na mesma versão do pacote principal — Doconut.NETStandard.Converter e Doconut.NETStandard.Dicom. A integração atual carrega licenças uma vez durante AddDoconut(), usando esta precedência:

LicenseStream > LicenseContent > LicensePath > automatic discovery

A descoberta automática procura por Doconut.Viewer.lic e arquivos acompanhantes Doconut.Viewer.<Capability>.lic. As chamadas estáticas anteriores Viewer.DoconutLicense(...) e Viewer.SetLicensePlugin(...) não são um mecanismo de inicialização atual, e nem o List<string> de caminhos de licença que o antigo construtor Viewer aceitava. Mova a licença para DoconutOptions, mantenha os arquivos acompanhantes juntos ao usar a descoberta automática, reinicie após alterar uma licença e verifique as capacidades através de IDoconutLicenseService.

Não presuma que a presença de uma licença de plugin antiga comprova direito para a compilação atual do plugin. Teste Viewer, Search, Annotation, Converter e DICOM separadamente com os artefatos de versão aprovados.

3. Inicialização e injeção de dependência

Anteriormente o visualizador era construído por requisição e as opções eram passadas para o middleware:

// Integração anterior — apenas para contraste; não compile isto contra o SDK atual.
var viewer = new Viewer(_cache, _accessor);
// …
appBranch.UseDoconut(new DoconutOptions { UnSafeMode = false, ShowDoconutInfo = false });

A integração atual registra Doconut uma única vez e recebe Viewer por injeção de dependência:

builder.Services.AddDoconut(options =>
{
    options.UnsafeMode      = false;   // observe a mudança de ortografia: UnSafeMode → UnsafeMode
    options.ShowDoconutInfo = false;
    options.LicensePath     = "Doconut.Viewer.lic";
});
builder.Services.AddDistributedMemoryCache(); // o estado da sessão precisa de um cache (MVC/Razor Pages já adicionam um)
builder.Services.AddSession();

app.UseSession();
app.UseDoconutResources();
app.UseDoconut();

Viewer é um serviço transitório. O gerenciador de sessão de documento e seu cache possuem o estado de documento de vida mais longa, não a instância injetada específica Viewer.

Três coisas a manter:

• new Viewer(cache, accessor) foi removido. Injete Doconut.Viewer no seu controlador, ou use @inject Doconut.Viewer Viewer em uma visualização Razor.
• UseDoconutResources() substitui a conexão manual app.UseMiddleware<EmbeddedResourceMiddleware>(), e deve ser executado antes do ramo do documento.
• UnSafeMode → UnsafeMode. Uma renomeação de um caractere que o compilador detectará.

Quando UnsafeMode está false o SDK valida o token de sessão contra a requisição de origem, portanto AddSession() / UseSession() ainda devem estar no pipeline, UseSession() antes do ramo.

Métodos que não existem mais

4. Middleware e roteamento de recursos

UseDoconut() agora não recebe argumentos. A forma do ramo MapWhen em si não precisa mudar — apenas o middleware dentro dele:

app.UseDoconutResources();   // ANTES do branch

app.MapWhen(
    ctx => ctx.Request.Path.Value?.EndsWith("DocImage.axd", StringComparison.OrdinalIgnoreCase) == true,
    branch => branch.UseDoconut());

No pipeline atual:

1. chame UseSession() antes do Doconut enquanto a segurança de sessão está habilitada;
2. chame UseDoconutResources() antes do UseDoconut();
3. mantenha ResourcesPath, as URLs de recursos geradas, e o cliente ResPath alinhados;
4. mantenha o ramo que você mapeia e o cliente BasePath alinhados.

MiddlewarePath é configuração validada; não cria um ramo ASP.NET Core por si só.

5. Construção e tempo de vida do visualizador

Remova caches de propriedade da aplicação de objetos Viewer. Não resta nada em um Viewer que valha a pena manter: ele não contém estado de documento, e o cache de sessão possui tudo que sobrevive a uma requisição. Injete‑o em um endpoint, página Razor, controlador ou serviço de aplicação com escopo:

app.MapPost("/api/open", async (Viewer viewer) =>
{
    var token = await viewer.OpenDocumentAsync("wwwroot/files/Sample.pdf");
    return Results.Ok(new { token });
});

O token retornado identifica uma sessão de documento no lado do servidor. Trate‑o como uma credencial de portador: não o registre, não o persista, nem o coloque em análises.

6. Abrindo e fechando documentos

Substitua o OpenDocument(...) síncrono por OpenDocumentAsync(...):

// Integração atual: Viewer vem do DI e a abertura do documento é assíncrona.
var token = await viewer.OpenDocumentAsync(path, new PdfConfig { AllowSearch = true });

As sobrecargas atuais aceitam um caminho de arquivo ou stream, uma configuração de formato opcional, DocOptions opcional e um token de cancelamento. Feche a sessão do servidor explicitamente quando o navegador não precisar mais dela:

viewer.CloseDocument(token);

Exclua qualquer chamada InitCache() e a flag que a protege — não há nada para pré‑carregar manualmente. Não reutilize um token gerado pela biblioteca anterior após a transição: abra cada documento novamente através da API atual.

7. Web farm → distribuído: a maior mudança

UseDoconutWebFarm e WebFarmOptions não existem mais. Se seu aplicativo os chama, esta seção é sua atualização; se não, pule para §8.

Anteriormente um middleware fazia tudo: ele servia imagens pré‑renderizadas de uma pasta compartilhada, e consultava enquanto outro nó ainda as escrevia.

// Integração anterior — uma chamada, coordenação implícita através do sistema de arquivos.
appBranch.UseDoconutWebFarm(new WebFarmOptions
{
    Path                = Path.Combine(env.WebRootPath, "webfarm"),
    PageWaitTimeSeconds = 180,
    StartWaitFromPage   = 5,
});

A mesma tarefa agora está dividida em duas metades explícitas. Lado de escrita — o nó que abre o documento publica todo o conjunto de artefatos (páginas, informações do documento, índice de busca, metadados) no compartilhamento:

var result = await _publisher.PublishAsync(          // DistributedDocumentPublisher, injetado do DI
    pathToFile,
    new FileShareConfig
    {
        Location              = CloudLocation.FileShare,
        RootPath              = @"\\fileserver\doconut",   // a mesma pasta que você usa hoje
        UsePerTokenSubfolders = true,
    },
    config,
    documentOptions,
    new DistributedDocumentPublishOptions
    {
        CleanUpStagingDirectory = true,
        FirstPagePriority       = true,
    });

return Content(result.Token);

Lado de leitura — qualquer nó serve a partir do compartilhamento:

app.MapWhen(
    ctx => ctx.Request.Path.Value?.EndsWith("DocImage.axd", StringComparison.OrdinalIgnoreCase) == true,
    branch => branch.UseDoconutCloud<FileShareCloudHandler>(options =>
    {
        options.Location          = CloudLocation.FileShare;
        options.CloudUploadConfig = /* o MESMO FileShareConfig acima */;
    }, "/"));

Sua topologia não muda. Aponte RootPath para o mesmo compartilhamento UNC e cada nó continuará funcionando como hoje. O que muda é que a publicação é uma operação que você chama, em vez de um efeito colateral da renderização.

Ambas as metades devem concordar. Se RootPath ou UsePerTokenSubfolders diferirem entre o publicador e o manipulador, o outro nó responderá 404. Construa a configuração em um helper e chame‑a de ambos os lados.

PageWaitTimeSeconds = 180 significava "bloquear até três minutos esperando a página aparecer". A substituição é explícita: com FirstPagePriority = true, a página 1 pode ser servida imediatamente e as páginas posteriores respondem HTTP 202 Accepted até serem escritas. O visualizador incluído tenta novamente automaticamente quando retryOn409 está definido. Um cliente que não tenta novamente mostrará blocos quebrados para páginas ainda em renderização.

A configuração completa, incluindo publicação em segundo plano e tickets de acesso, está em Implantações Distribuídas.

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

Registre o plugin, então injete a fachada DocumentConverter:

builder.Services.AddDoconut(o => o.AddPlugin<ConverterPlugin>());

// Integração anterior
var converter = viewer.Converter.GetConverter();
var config    = new WordConfigConverter { TargetFormat = WordConfigConverter.EnTargetFormat.PDF };
var result    = converter.Convert(stream, SourceFormatConverter.DOCX, config);

// Integração atual
var result = await _converter.ConvertAsync(stream, ".docx", ConversionTarget.Pdf, null, ct);

O que isso substitui:

• SourceFormatConverter — removido. Passe a extensão do arquivo como uma string, incluindo o ponto.
• Os tipos *ConfigConverter por família (WordConfigConverter, ExcelConfigConverter, …), cada um com um enum EnTargetFormat aninhado — removido. Agora há um enum ConversionTarget para cada família.
• viewer.Converter.GetConverter() — removido. Injete Doconut.DocumentConverter.

ConvertAsync retorna um fluxo buscável, então return File(result, mime, name) funciona diretamente — a MemoryStream cópia do código antigo necessária é desnecessária. No exemplo fornecido isso eliminou uma troca de extensão com 68 casos e dez controladores quase idênticos.

Veja Plugin Conversor para a interface completa.

9. Provedores de nuvem

UseDoconutCloud tornou-se genérico. O provedor é o argumento de tipo em vez de um valor Location usado dentro do middleware:

// Integração anterior
appBranch.UseDoconutCloud(new CloudOptions { Location = CloudLocation.CDN, ... });

// Integração atual
branch.UseDoconutCloud<CDNCloudHandler>(options =>
{
    options.Location          = CloudLocation.CDN;
    options.CloudUploadConfig = new CDNConfig { DoconutCdnUrl = "..." };
}, "/");

As classes de configuração permanecem inalteradas, exceto pelo namespace (Doconut.Configs.Cloud → Doconut.Clouds): AzureConfig, AmazonConfig, GoogleCloudConfig, DropBoxConfig, RedisConfig, CDNConfig, FTPConfig, além do novo FileShareConfig. Os manipuladores são nomeados <Provider>CloudHandler.

O manipulador CDN é somente leitura — ele serve o que já está no CDN; não faz upload.

10. Objetos de configuração que mudaram de nome

DocOptions também ganha IsSecured.

A API atual também separa as preocupações de forma mais rigorosa que a anterior, portanto verifique se cada configuração está no objeto que agora a possui:

Não continue usando DocOptions.ImageResolution como controle de renderização. Ele está obsoleto; defina BaseConfig.ImageResolution na configuração específica de formato. Revise todas as configurações padrão em vez de assumir que uma configuração anterior tem o mesmo comportamento.

11. O visualizador do lado do cliente — duas alterações que falham SILENCIOSAMENTE

Ambas deixam o servidor funcionando perfeitamente. Seu documento é renderizado, a página parece correta e nada aparece no console do navegador. Leia esta seção mesmo que seu C# compile na primeira tentativa.

Callbacks do visualizador são opções agora, não funções globais

O visualizador anterior chamava seus manipuladores pelo nome, derivando o nome da função global a partir do id do contêiner. Declarar function ctlDoc_OnViewerReady() em uma página com <div id="div_ctlDoc"> era suficiente. O visualizador atual aceita callbacks explícitos no objeto de opções e não procura mais esses globais:

objctlDoc = $("#div_ctlDoc").docViewer({
    // ... suas opções existentes ...
    onViewerBusy:     ctlDoc_OnViewerBusy,      // foi encontrado por nome
    onViewerReady:    ctlDoc_OnViewerReady,     // foi encontrado por nome
    onCopy:           ctlDoc_Copy,              // foi ctlDoc_Copy(text)
    onAutoLoadStatus: ctlDoc_AutoLoadStatus     // foi ctlDoc_AutoLoadStatus(page)
});

Por que isso é problemático: a chamada antiga era envolvida em um catch vazio, que engolia tudo. Agora suas funções simplesmente nunca são executadas e nada relata um erro. O sintoma usual é um spinner ativo que nunca para — porque a função que o ocultava era ctlDoc_OnViewerReady. O documento por trás dele está ok.

A lista completa de opções é onPageLoading, onPageLoaded, onThumbnailClicked, onPageClicked, onDoubleClick, onViewerBusy, onViewerReady, onViewerError, onCopy, onAnnSaved, onAnnSaveError, onAnnLoaded, onAnnClosed, onAutoLoadStatus, onThumbsShown e onError. Não há callback de clique em link: o tratamento de hyperlinks está embutido, acionado por showHyperlinks.

ResPath deve apontar para o prefixo do recurso

ResPath: '',                      // ANTES — os recursos vinham da raiz da aplicação
ResPath: 'doconut-res/images',    // AGORA    — o prefixo UseDoconutResources() monta

Se você alterou o prefixo via DoconutOptions.ResourcesPath, use esse valor em vez disso.

12. Barra de ferramentas do Viewer, Pesquisa e Anotação

Não migre os scripts antigos um a um. As aplicações de referência atuais compõem um pacote de página completo:

1. emitir o CSS do Viewer e o CSS licenciado de Pesquisa/Anotação com ReferenceCss;
2. renderizar a barra de ferramentas do Viewer de propriedade da aplicação;
3. renderizar searchBarMount, annBarMount e a montagem necessária do Viewer;
4. emitir scripts do Viewer e módulos licenciados com ReferenceScripts;
5. carregar o script auxiliar da barra de ferramentas da própria aplicação;
6. inicializar um objViewer;
7. inicializar as Faixas de Pesquisa e Anotação licenciadas;
8. chamar attach(objViewer) em cada Faixa;
9. abrir o documento e chamar objViewer.View(token).

Pesquisa e Anotação são módulos anexados ao mesmo Viewer, não barras de ferramentas independentes. A barra de ferramentas principal pertence à aplicação host; as Faixas de Pesquisa e Anotação são recursos incorporados, controlados por capacidades.

Remova arquivos copiados manualmente, como documentLinks.js e docViewer.UI.js, somente depois que a página atual funcionar com recursos emitidos por ReferenceCss e ReferenceScripts.

13. Registro de plugins

Métodos estáticos de licença de plugin não registram plugins atuais. Instale e registre cada pacote lançado explicitamente:

builder.Services.AddDoconut(options =>
{
    options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
    options.AddPlugin<Doconut.Plugins.Dicom.DicomPlugin>();
});

AddDoconut() valida as capacidades de plugins registradas na inicialização. Converter e DICOM são os plugins .NET Standard lançados. Pesquisa e Anotação normais são recursos licenciados incorporados, não pacotes AddPlugin<TPlugin>().

14. Segurança de sessão e documento

A integração atual vincula documentos a tokens opacos e sessões em cache. Com o UnsafeMode = false padrão, UseDoconut() adiciona segurança de acesso ao documento e o host deve configurar a sessão ASP.NET:

builder.Services.AddDistributedMemoryCache(); // o estado da sessão precisa de um cache (MVC/Razor Pages já adiciona um)
builder.Services.AddSession();
app.UseSession();

Mantenha DocOptions.IsSecured = true a menos que um design revisado exija o contrário. Nunca use UnsafeMode = true como atalho de migração em um único nó. Teste solicitações sem token, com token malformado, token expirado e token de uma sessão de navegador diferente.

Em um farm, a solicitação de página pode chegar a um nó que nunca viu a solicitação inicial, então a verificação por sessão a rejeitaria. Esse é o único caso em que UnsafeMode = true está correto — e deve ser combinado com tickets de acesso assinados através de AddDoconutDistributedDocumentSecurity, não enviados isoladamente. Veja Implantações Distribuídas.

Observação sobre nomenclatura

Em todos os frameworks a classe é Viewer. Se você encontrar DocumentViewer em trechos antigos ou artigos de terceiros, esse tipo nunca existiu no SDK.

15. Ordem sugerida de trabalho

1. Confirme se o framework host pode consumir netstandard2.1. Se não puder, pare.
2. Atualize o pacote para 26.8.0 e compile. Resolva os erros de compilação — a maioria são as linhas using na §1.
3. Mova a inicialização para AddDoconut() e as chamadas de middleware para a nova ordem (§3, §4).
4. Injete Viewer onde você o estava construindo, torne OpenDocument assíncrono e exclua InitCache() (§5, §6).
5. Se você usar o farm web, faça §7 — a única parte que é uma reformulação em vez de uma renomeação.
6. Se você converter documentos, faça §8.
7. Faça §11 — as alterações no lado do cliente. São elas que não se anunciarão.
8. Abra um documento real em um navegador e observe o spinner de carregamento. Uma compilação verde não prova nada aqui: licenciamento, registro de plugins, o caminho do recurso e os callbacks do viewer falham apenas em tempo de execução. Para um farm, verifique se um documento publicado por um nó é servido por outro.

Testando a migração

No mínimo, verifique:

• inicialização da aplicação com a licença de produção e todos os plugins registrados;
• CSS/scripts do Viewer e todas as solicitações de página-imagem nos caminhos escolhidos;
• abertura de documento, navegação, zoom, miniaturas, impressão e fechamento explícito;
• pesquisa em um documento contendo texto e o estado não pesquisável de um arquivo apenas de imagem;
• carregamento, salvamento, exportação de anotações e controle de recursos;
• descoberta de destino do conversor, saída, download e estado da marca d'água;
• páginas, quadros e animação DICOM; metadados técnicos não estão disponíveis neste pacote;
• documentos protegidos por senha, fontes personalizadas, texto não latino e tempos limite configurados;
• rejeição de token entre sessões e comportamento de sessão expirada;
• para um farm: publicar em um nó, solicitar uma página tardia de outro e confirmar que o viewer tenta novamente as respostas 202 em vez de mostrar blocos quebrados;
• modo móvel, modo escuro e o caminho de reverse-proxy de produção.

Plano de reversão

Mantenha o artefato de implantação anterior, os pacotes correspondentes, arquivos de licença e recursos de navegador copiados juntos. Uma reversão segura troca toda a geração da aplicação; ela não mistura um servidor de geração anterior com scripts atuais, ou um servidor atual com locais de chamada new Viewer(...).

Antes da transição, documente:

• o slot ou artefato de implantação usado para a reversão;
• o impacto no armazenamento compartilhado, se houver — artefatos publicados por 26.8.0 não são consumidos pelo middleware da web-farm anterior;
• como as sessões de documentos ativas serão invalidadas;
• a verificação de saúde e o documento de fumaça usados para decidir a reversão;
• quem pode restaurar o conjunto de pacotes e a configuração anteriores.

Documentação legada

O manual anterior traduzido continua disponível em Configuração Legacy .NET Standard. O Gateway de integração anterior explica os mesmos sinais de identificação e linka de volta a este guia de migração.

Mantenha a URL histórica nos favoritos e tickets de suporte enquanto instalações netstandard2.0 ainda existirem. Ela documenta uma geração diferente e não é redirecionada para a API atual.