Migrar da integração clássica .NET 6

Doconut tem duas integrações distintas para .NET 6. Elas podem usar o mesmo nome de pacote Doconut.NET6, portanto identifique a geração a partir das APIs na aplicação antes de alterar pacotes, inicialização, licenças ou recursos do navegador.

Qual integração .NET 6 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.

Por que o nome do pacote NuGet pode não indicar isso

Ambas as gerações foram distribuídas sob o ID de pacote Doconut.NET6. Uma referência de pacote, arquivo de bloqueio ou .nupkg em cache, portanto, não identifica a API de hospedagem por si só. Registre a versão exata do pacote e inspecione Program.cs, a construção do viewer, a abertura de documentos e os scripts do navegador em conjunto.

A versão auditada para este guia é Doconut.NET6 26.7.0. Seus pacotes públicos opcionais são Doconut.NET6.Converter e Doconut.NET6.Dicom, fixados na mesma versão de lançamento que o pacote principal.

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. Inventarie cada mapeamento DocImage.axd, chamada new Viewer(...), chamada de carregamento de licença, script Doconut copiado, ação de barra de ferramentas personalizada 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 PDFs, documentos Office, imagens, CAD, e‑mails, DICOM, pesquisáveis, protegidos por senha e anotados.
6. Registre o timeout de sessão atual, comportamento de segurança, fontes e configurações da plataforma.

Migre um ambiente antes de alterar 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 e a entrega de recursos ao cliente.

Compatibilidade de pacotes e licenças

Substitua ou atualize o pacote core deliberadamente; não confie no 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.NET6

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

dotnet add package Doconut.NET6 --version 26.7.0

Mantenha cada plugin Doconut na mesma versão do pacote core. 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 arquivos Doconut.Viewer.lic e Doconut.Viewer.<Capability>.lic acompanhantes. Uma chamada clássica a Viewer.DoconutLicense(...) ou Viewer.SetLicensePlugin(...) não é um mecanismo de inicialização atual. Mova a licença para DoconutOptions, mantenha os arquivos acompanhantes juntos ao usar 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 a uma compilação de plugin atual. Teste Viewer, Search, Annotation, Converter e DICOM separadamente com os artefatos de lançamento aprovados.

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

Aplicações clássicas constroem Viewer com dependências de cache ASP.NET e accessor de requisição:

// Integração clássica — apenas para contraste; não compile isso contra o SDK atual.
var viewer = new Viewer(_cache, _accessor, licenseFilePath);

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

builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
    options.UnsafeMode = false;
});
builder.Services.AddSession();

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

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

Middleware e roteamento de recursos

Remova o branch clássico MapWhen que detecta DocImage.axd:

// Integração clássica — remover durante a migração.
app.MapWhen(
    context => context.Request.Path.ToString().EndsWith("DocImage.axd"),
    branch => branch.UseDoconut(new DoconutOptions()));

No pipeline da integração atual:

1. chame UseSession() antes de Doconut enquanto a segurança da sessão está habilitada;
2. chame UseDoconutResources() antes de UseDoconut();
3. mantenha ResourcesPath, as URLs de recursos geradas e ResPath do cliente alinhados;
4. ao mapear UseDoconut() para um branch, mantenha esse branch e BasePath do cliente alinhados.

MiddlewarePath é configuração validada; não cria um branch ASP.NET Core por si só. Use o pipeline simples no exemplo de compilação acima ou um arranjo explícito app.Map("/doconut", branch => branch.UseDoconut()) usado consistentemente pelo cliente.

Construção e tempo de vida do Viewer

Remova caches de Viewer de propriedade da aplicação. Injete Viewer 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 credencial de portador: não o registre, persista ou coloque em análises.

Abertura e fechamento de documentos

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

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

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

viewer.CloseDocument(token);

Não reutilize um token clássico após a migração. Abra cada documento novamente através da API atual.

Classes de configuração

A API atual separa as preocupações:

Não carregue DocOptions.ImageResolution adiante como controle de renderização. Está obsoleto; defina BaseConfig.ImageResolution na configuração específica de formato. Revise todos os valores padrão em vez de presumir que uma configuração clássica tem o mesmo comportamento.

Barra de ferramentas do Viewer, Search e Annotation

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 CSS do Viewer e CSS licenciado de Search/Annotation com ReferenceCss;
2. renderize a barra de ferramentas do Viewer de propriedade da aplicação;
3. renderize searchBarMount, annBarMount e o mount do Viewer requerido;
4. emita scripts do Viewer e módulos licenciados com ReferenceScripts;
5. carregue o viewerToolbar.js da própria aplicação;
6. inicialize um objViewer;
7. inicialize as ribbons licenciadas de Search e Annotation;
8. chame attach(objViewer) em cada ribbon;
9. abra o documento e chame objViewer.View(token).

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

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

Registro de plugins

Métodos estáticos clássicos de licença de plugin não registram plugins atuais. Instale e registre cada pacote liberado 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 plugins .NET 6 liberados. Search e Annotation normais são recursos licenciados incorporados, não pacotes AddPlugin<TPlugin>().

Segurança de sessão e documento

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

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. Teste requisições sem token, com token malformado, token expirado e token de uma sessão de navegador diferente.

A aplicação de referência Distributed adiciona tickets de acesso e detalhes de transporte. Essas APIs não são necessárias para uma migração normal de nó único.

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 requisições de imagens de página nos caminhos escolhidos;
• abertura de documento, navegação, zoom, miniaturas, impressão e fechamento explícito;
• Search em documento com texto e estado não pesquisável de arquivo somente de imagem;
• carregamento, salvamento, exportação e controle de capacidade de Annotation;
• descoberta de destino do Converter, saída, download e estado da marca d'água;
• páginas DICOM, quadros e animação; metadados técnicos .NET 6 indisponíveis;
• documentos protegidos por senha, fontes personalizadas, texto não‑latino e timeouts configurados;
• rejeição de token entre sessões e comportamento de sessão expirada;
• dispositivos móveis, modo escuro e caminho de proxy reverso de produção.

Plano de reversão

Mantenha o artefato de implantação clássico, pacotes correspondentes, arquivos de licença e recursos de navegador copiados juntos. Uma reversão segura troca toda a geração da aplicação; não mistura um servidor clássico com scripts atuais nem um servidor atual com chamadas clássicas DocImage.axd.

Antes da migração, documente:

• o slot ou artefato de implantação usado para reversão;
• o impacto no banco de dados/cache, se houver;
• como sessões de documento ativas serão invalidadas;
• o check‑up de saúde e documento de fumaça usado para decidir a reversão;
• quem pode restaurar o conjunto de pacotes e configuração anteriores.

Documentação legada

O manual clássico traduzido continua disponível em Configuração .NET 6 legada. O novo Gateway de integração clássica explica os mesmos sinais de identificação e vincula de volta a este guia de migração.

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