Esta página contém duas migrações: atualizar a versão do pacote dentro do .NET 8 e mover uma integração de um framework Doconut mais antigo (.NET 6, .NET Standard 2.0, .NET Framework 4.7) para a API do .NET 8.

Atualizando a versão do pacote

Atualize o pacote (e quaisquer pacotes de plugins — mantenha as versões alinhadas):

bash

dotnet add package Doconut.NET8
dotnet add package Doconut.NET8.Dicom

Verifique a janela de licença. Uma licença cobre um intervalo de versões. Se a nova versão ficar fora desse intervalo, a abertura é bloqueada — OpenDocumentAsync lança LicenseException (falha rápida); não recorre a uma marca d'água, e IsVersionValid torna‑se false. Renove, substitua o .lic e reinicie a aplicação para que AddDoconut() carregue a nova licença.
Recompile e deixe o NuGet restaurar as versões declaradas das dependências — não fixe novamente System.Text.Json ou System.Drawing.Common (consulte Solução de Problemas para os erros exatos que uma redução de versão causa).
Faça um teste rápido com um documento por família de formato que você utiliza.

Migrando do .NET 6 / .NET Standard 2.0

A API do .NET 8 é um redesign em torno de DI e async. O mapeamento:

Aspecto	.NET 6 / Standard 2.0	.NET 8
Configuração	Construct `Viewer(cache, httpContextAccessor, licensePath)`	`builder.Services.AddDoconut(options => …)` + inject `Viewer`
Licença	Estático `Viewer.DoconutLicense(path)` + `SetLicensePlugin(...)` por plugin	`options.LicensePath` / `LicenseContent` / `LicenseStream` — uma licença, descoberta automática para arquivos de plugin
Abrir	`viewer.OpenDocument(...)` (síncrono)	`await viewer.OpenDocumentAsync(...)`
Fechar	`viewer.CloseDocument()` ou `viewer.Dispose()`	`viewer.CloseDocument(token)` — `Viewer` não é `IDisposable`
Tempo de vida	`Viewer` implementa `IDisposable`, mantém o documento aberto	`Viewer` é sem estado; sessões vivem no cache sob tokens
Conversor	propriedade `viewer.Converter`	O plugin Converter (`AddPlugin<ConverterPlugin>()`) + o serviço `DocumentConverter`
Classes de configuração	namespaces `Doconut.Configs.View.*`	Tudo no namespace `Doconut`
Middleware	Encadeamento manual de manipuladores	`app.UseDoconutResources()` + `app.UseDoconut()`

Um exemplo típico antes/depois:

text

// .NET 6 (API antiga, mostrada para contraste — não válida no .NET 8)
using var viewer = new Viewer(cache, httpContextAccessor, "wwwroot/Doconut.Viewer.lic");
var token = viewer.OpenDocument(path, new PdfConfig { AllowSearch = true }, new DocOptions());

csharp

// .NET 8 — Viewer injetado, licença configurada uma vez em AddDoconut()
var token = await viewer.OpenDocumentAsync(path, new PdfConfig { AllowSearch = true });

Migrando do .NET Framework 4.7 (Web Forms)

O Viewer 4.7 é um WebControl; o .NET 8 substitui o modelo de controle por middleware + um serviço DI:

O controle <doconut:DocViewer runat=server> desaparece — a página hospeda o par de div do widget e seu endpoint devolve o token (Quick Start mostra o padrão).
Métodos de licença estáticos → fontes de licença DoconutOptions.
OpenDocument síncrono → await OpenDocumentAsync.
Viewer.ReferenceScripts() / ReferenceCss() existem em ambos os mundos — as versões do .NET 8 recebem objetos ScriptConfig/CssConfig e são controladas por licença.
Propriedades de controle (ShowThumbs, PageZoom, FixedZoom, …) → os mesmos nomes em ViewerConfig / nas opções JS docViewer.
Métodos de exportação que retornam byte[] → as APIs assíncronas de exportação de anotações no Viewer.

Planeje isso como uma reescrita da camada de hospedagem em torno de um conceito inalterado: abrir → token → widget.

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.

Checklist de migração

Troque os pacotes; alinhe as versões dos pacotes de plugins.
Mova a configuração da licença para AddDoconut(); exclua chamadas de licença estáticas.
Torne as chamadas de abertura assíncronas; substitua Dispose/CloseDocument sem parâmetros por CloseDocument(token).
Substitua os usos de viewer.Converter pelo registro do plugin Converter + DocumentConverter.
Re‑teste o caminho de segurança: AddSession()/UseSession() agora são obrigatórios com a segurança padrão (além de AddDistributedMemoryCache() em um aplicativo minimal‑API).