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

Doconut tem duas integrações .NET 6 distintas. 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 hospedada por si só. Registre a versão exata do pacote e inspecione Program.cs, a construção do visualizador, a abertura de documentos e os scripts do navegador juntos.

A versão atual 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 os 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, o comportamento de segurança, as fontes e as configurações da plataforma.

Migre um ambiente antes de alterar a produção. A integração atual altera a vida útil 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 uma 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 > automatic discovery

A descoberta automática procura por arquivos Doconut.Viewer.lic e arquivos complementares Doconut.Viewer.<Capability>.lic. 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 complementares 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 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 cache ASP.NET e dependências de request-accessor:

// Integração clássica — apenas 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.AddDistributedMemoryCache();
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 de documento de vida mais longa, não a instância injetada específica Viewer.

Middleware e roteamento de recursos

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

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

No pipeline atual:

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

MiddlewarePath é uma configuração validada; não cria um ramo ASP.NET Core por si só. Use ou 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 ciclo de vida do visualizador

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

Abrindo e fechando documentos

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

// Integração atual .NET 6: Viewer vem de DI e a abertura de 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);

Não reutilize um token clássico após a transiçã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 o 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 clássica tem o mesmo comportamento.

Barra de ferramentas do visualizador, 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 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 necessário;
4. emita os scripts do Viewer e do módulo licenciado com ReferenceScripts;
5. carregue o viewerToolbar.js próprio da 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 capacidades.

Remova arquivos clássicos 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.

Registro de plugin

Os métodos clássicos de licença estática de plugins não registram os 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 plugins .NET 6 lançados. Busca Normal e Anotação 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 o UnsafeMode = false padrão, UseDoconut() adiciona segurança de acesso a documentos e o host deve configurar a sessão ASP.NET:

builder.Services.AddDistributedMemoryCache(); // 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. Teste solicitações sem token, com token malformado, token expirado e token de uma sessão de navegador diferente.

O aplicativo 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 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 contendo texto e o estado não pesquisável de um arquivo somente de imagem;
• Carregamento, salvamento, exportação e controle de capacidades de Anotação;
• Descoberta de destino do Converter, saída, download e estado da marca d'água;
• Páginas, quadros e animação DICOM; metadados técnicos do .NET 6 não estão disponíveis;
• 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;
• modo móvel, modo escuro e o caminho de reverse-proxy de produção.

Plano de rollback

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

Antes da transição, documente:

• o slot ou artefato de implantação usado para rollback;
• o impacto no banco de dados/cache, se houver;
• 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 o rollback;
• quem pode restaurar o conjunto de pacotes e a configuração anteriores.

Documentação legada

O manual clássico traduzido continua disponível em Legacy .NET 6 setup. O novo Classic integration gateway explica os mesmos sinais de identificação e links de volta para este guia de migração.

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