Migrar para .NET Standard 2.1

Doconut tem duas integrações distintas de .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á pacote separado para instalar e nem shim de compatibilidade — 26.8.0 possui uma superfície de API diferente. Espere erros de compilação após o aumento; o resto deste guia é a lista deles.

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

Este é um critério rígido, não uma preferência. O pacote atual tem 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 de plugins.
3. Faça 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 viewer 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 de sessão existente, comportamento de segurança, fontes e configurações da plataforma.

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

1. Namespaces: quase tudo movido para a raiz

Os tipos de configuração estavam espalhados por 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 os demais ainda estão presentes. 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 substituto 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 que o pacote principal — Doconut.NETStandard.Converter e Doconut.NETStandard.Dicom. A integração atual carrega licenças uma única vez durante AddDoconut(), usando esta precedência:

LicenseStream > LicenseContent > LicensePath > descoberta automática

A descoberta automática procura pelos arquivos Doconut.Viewer.lic e pelos arquivos companheiros Doconut.Viewer.<Capability>.lic. As chamadas estáticas anteriores Viewer.DoconutLicense(...) e Viewer.SetLicensePlugin(...) não são mais um mecanismo de inicialização, e nem a List<string> de caminhos de licença que o antigo construtor Viewer aceitava. Mova a licença para DoconutOptions, mantenha os arquivos companheiros 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 comprove direito para uma compilação de plugin atual. Teste Viewer, Search, Annotation, Converter e DICOM separadamente com os artefatos de liberaçã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 ao middleware:

// Integração anterior — apenas para contraste; não compile isso 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 de 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 documentos e seu cache possuem o estado do documento de vida mais longa, não a instância específica de Viewer injetada.

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 view Razor.
• UseDoconutResources() substitui a ligação manual app.UseMiddleware<EmbeddedResourceMiddleware>(), e deve ser executado antes do ramo de 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 precisam estar no pipeline, UseSession() antes do ramo.

Métodos que não existem mais

4. Middleware e roteamento de recursos

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

app.UseDoconutResources();   // ANTES do ramo

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 de UseDoconut();
3. mantenha ResourcesPath, as URLs de recursos geradas e o ResPath do cliente alinhados;
4. mantenha o ramo que você mapeia e o BasePath do cliente alinhados.

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

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

Remova caches de Viewer pertencentes à aplicação. 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 servidor. Trate‑o como uma credencial portadora: não o registre, persista ou inclua em análises.

6. Abrindo e fechando documentos

Substitua 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 });

Os overloads 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 a InitCache() e a bandeira que a protege — não há nada para pré‑carregar manualmente. Não reutilize um token gerado pela biblioteca anterior após a migraçã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 sua aplicação os chama, esta seção é sua atualização; se não, pule para a §8.

Anteriormente, um middleware fazia tudo: 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) na partilha:

var result = await _publisher.PublishAsync(          // DistributedDocumentPublisher, injetado via 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 da partilha:

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 a mesma partilha 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 que a página aparecesse". A substituição é explícita: com FirstPagePriority = true, a página 1 pode ser servida imediatamente e as páginas subsequentes respondem HTTP 202 Accepted até serem gravadas. O visualizador incluído tenta novamente automaticamente quando retryOn409 está definido. Um cliente que não tenta novamente exibirá 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 e, em seguida, 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 aninhado EnTargetFormat — removidos. Agora há um único enum ConversionTarget para cada família.
• viewer.Converter.GetConverter() — removido. Injete Doconut.DocumentConverter.

ConvertAsync devolve um fluxo buscável, de modo que return File(result, mime, name) funciona diretamente — a cópia em MemoryStream que o código antigo precisava é desnecessária. No exemplo distribuído isso eliminou um switch de 68 casos de extensão e dez controladores quase idênticos.

Veja Plugin de 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 escolhido 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 da nova 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 rígida 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. Ela está obsoleta; defina BaseConfig.ImageResolution na configuração específica de formato. Revise todos os valores padrão em vez de assumir que uma configuração anterior tem o mesmo comportamento.

11. O visualizador do lado do cliente — duas mudanças 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,      // era encontrado pelo nome
    onViewerReady:    ctlDoc_OnViewerReady,     // era encontrado pelo nome
    onCopy:           ctlDoc_Copy,              // era ctlDoc_Copy(text)
    onAutoLoadStatus: ctlDoc_AutoLoadStatus     // era ctlDoc_AutoLoadStatus(page)
});

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

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 para clique em link: o tratamento de hiperlinks está embutido, controlado por showHyperlinks.

ResPath deve apontar para o prefixo de recursos

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

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

12. Barra de ferramentas do Viewer, Busca 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. emita o CSS do Viewer e o CSS licenciado de Busca/Anotação com ReferenceCss;
2. renderize a barra de ferramentas do Viewer pertencente à aplicação;
3. renderize searchBarMount, annBarMount e a montagem necessária do Viewer;
4. emita os scripts do Viewer e dos módulos licenciados com ReferenceScripts;
5. carregue o script auxiliar da barra de ferramentas da própria aplicação;
6. inicialize um objViewer;
7. inicialize as Faixas licenciadas de Busca e Anotação;
8. chame attach(objViewer) em cada Faixa;
9. abra o documento e chame objViewer.View(token).

Busca 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 Busca 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 os 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 dos plugins registrados na inicialização. Converter e DICOM são os plugins .NET Standard lançados. Busca 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 padrão UnsafeMode = false, UseDoconut() adiciona segurança de acesso a documentos e o host deve configurar a sessão ASP.NET:

builder.Services.AddDistributedMemoryCache(); // o estado de 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 da página pode chegar a um nó que nunca viu a solicitação inicial, portanto a verificação por sessão a rejeitaria. Esse é o único caso em que UnsafeMode = true é correto — e deve ser combinado com tickets de acesso assinados através de AddDoconutDistributedDocumentSecurity, não distribuído isoladamente. Veja Implantações Distribuídas.

Nota 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 que 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 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 construía, torne OpenDocument assíncrono e exclua InitCache() (§5, §6).
5. Se você usar o farm web, faça §7 — a única parte que é um redesign em vez de uma renomeação.
6. Se você converter documentos, faça §8.
7. Faça §11 — as alterações do 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 de recursos e os callbacks do viewer falham apenas em tempo de execução. Em um farm, verifique que um documento publicado por um nó seja 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;
• Busca em um documento com texto e o estado não pesquisável de um arquivo somente 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 DICOM, quadros e animação; 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 respostas 202 em vez de mostrar blocos quebrados;
• mobile, 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 chamadas new Viewer(...).

Antes da troca, documente:

• o slot de implantação ou artefato usado para a reversão;
• o impacto de 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 documento 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 legada .NET Standard. O Gateway de integração anterior explica os mesmos sinais de identificação e links de volta para este guia de migração.

Mantenha a URL histórica em 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.