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

Doconut tem duas integrações distintas do .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 do .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 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 do pacote principal e dos 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 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 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 principal 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 principal. 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 pelos arquivos Doconut.Viewer.lic e pelos arquivos acompanhantes 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 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 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:

// Classic integration — contrast only; do not compile this against the current SDK.
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ão de documentos e seu cache possuem o estado de documento de vida mais longa, não a instância injetada específica de Viewer.

Middleware e roteamento de recursos

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

// Classic integration — remove during the cutover.
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 de UseDoconut();
3. mantenha ResourcesPath, as URLs de recursos geradas, e o ResPath do cliente alinhados;
4. ao mapear UseDoconut() para um ramo, mantenha esse ramo e o BasePath do cliente alinhados.

MiddlewarePath é uma configuração validada; não cria um ramo 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 ciclo de vida do Viewer

Remova caches de objetos Viewer pertencentes à aplicação. Injete Viewer em um endpoint, página Razor, controller 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.

Abrindo e fechando documentos

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

// Current .NET 6 integration: Viewer comes from DI and document opening is asynchronous.
var token = await viewer.OpenDocumentAsync(path, new PdfConfig { AllowSearch = true });

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 migração. Abra cada documento novamente através da API atual.

Classes de configuração

A API atual separa as preocupações:

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 todos os padrões em vez de assumir que uma configuração clássica tem o mesmo comportamento.

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 scripts do Viewer e módulos licenciados com ReferenceScripts;
5. carregue o viewerToolbar.js próprio da aplicação;
6. inicialize um objViewer;
7. inicialize as Faixas (Ribbons) 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 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 plugins

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 dos plugins registrados na inicialização. Converter e DICOM são plugins lançados para .NET 6. 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 padrão UnsafeMode = false, 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 solicitaçõ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 Visualizador 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 que contém texto e o estado não pesquisável de um arquivo somente de imagem;
• carregamento, salvamento, exportação e controle de capacidade 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 reversão

Mantenha o artefato de implantação clássico, 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 clássico com scripts atuais nem um servidor atual com chamadas clássicas de DocImage.axd.

Antes da troca, documente:

• o slot ou artefato de implantação usado para a reversão;
• o impacto no banco de dados/cache, se houver;
• como as sessões de documento ativas serão invalidadas;
• o teste de integridade 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 clássico traduzido continua disponível em Configuração Legacy .NET 6. O novo Gateway de integração Classic explica os mesmos sinais de identificação e links 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.