Migracja z klasycznej integracji .NET 6

Doconut ma dwie odrębne integracje .NET 6. Mogą używać tej samej nazwy pakietu Doconut.NET6, więc przed zmianą pakietów, uruchamianiem, licencjami lub zasobami przeglądarki należy określić, z której generacji pochodzą API w aplikacji.

Którą integrację .NET 6 używasz?

Jeśli obie kolumny pojawiają się w tej samej aplikacji, traktuj migrację jako niekompletną. Nie przesyłaj jednego tokenu dokumentu przez zasoby lub middleware z drugiej generacji.

Dlaczego nazwa pakietu NuGet może nie wystarczyć

Obie generacje były dystrybuowane pod identyfikatorem pakietu Doconut.NET6. Odwołanie do pakietu, plik blokady lub zbuforowany plik .nupkg nie identyfikuje więc samego API hostującego. Zanotuj dokładną wersję pakietu i przeanalizuj Program.cs, konstrukcję viewer’a, otwieranie dokumentów oraz skrypty przeglądarki razem.

Obecnie audytowaną wersją tego przewodnika jest Doconut.NET6 26.7.0. Jej opcjonalne publiczne pakiety to Doconut.NET6.Converter i Doconut.NET6.Dicom, zablokowane do tej samej wersji co pakiet podstawowy.

Przed migracją

1. Utwórz gałąź i wykonalną kopię zapasową istniejącej aplikacji.
2. Zanotuj dokładne wersje pakietu podstawowego i wtyczek.
3. Zrób inwentaryzację każdego mapowania DocImage.axd, wywołania new Viewer(...), wywołania ładowania licencji, skopiowanego skryptu Doconut, niestandardowej akcji paska narzędzi oraz punktu końcowego otwierania dokumentu.
4. Zachowaj bieżące pliki .lic oraz sekrety wdrożeniowe poza kontrolą wersji.
5. Zbierz reprezentatywny zestaw dokumentów PDF, Office, obrazów, CAD, e‑mail, DICOM, przeszukiwalnych, zabezpieczonych hasłem i anotowanych.
6. Zanotuj aktualny limit czasu sesji, zachowanie zabezpieczeń, czcionki i ustawienia platformy.

Migruj najpierw jedno środowisko, zanim zmienisz produkcję. Bieżąca integracja zmienia czas życia usług, trasowanie żądań, własność sesji oraz dostarczanie zasobów po stronie klienta.

Zgodność pakietów i licencji

Zamień lub zaktualizuj pakiet podstawowy świadomie; nie polegaj na identycznym identyfikatorze pakietu, aby wybrać nowe API. Domyślne polecenie instaluje najnowsze stabilne wydanie:

dotnet add package Doconut.NET6

Aby uzyskać powtarzalną migrację do wersji audytowanej w tym przewodniku, podaj wersję jako oddzielną opcję:

dotnet add package Doconut.NET6 --version 26.7.0

Utrzymuj każdą wtyczkę Doconut w tej samej wersji co pakiet podstawowy. Bieżąca integracja ładuje licencje raz podczas AddDoconut(), używając następującego priorytetu:

LicenseStream > LicenseContent > LicensePath > automatyczne wykrywanie

Automatyczne wykrywanie szuka plików Doconut.Viewer.lic oraz powiązanych Doconut.Viewer.<Capability>.lic. Klasyczne wywołanie Viewer.DoconutLicense(...) lub Viewer.SetLicensePlugin(...) nie jest już mechanizmem uruchamiania. Przenieś licencję do DoconutOptions, trzymaj powiązane pliki razem przy użyciu automatycznego wykrywania, uruchom ponownie po zmianie licencji i zweryfikuj możliwości przez IDoconutLicenseService.

Nie zakładaj, że obecność starej licencji wtyczki uprawnia do bieżącej kompilacji wtyczki. Testuj osobno Viewer, Search, Annotation, Converter i DICOM przy użyciu zatwierdzonych artefaktów wydania.

Uruchamianie i wstrzykiwanie zależności

Klasyczne aplikacje konstruują Viewer z zależności cache ASP.NET i request‑accessor:

// Classic integration — contrast only; do not compile this against the current SDK.
var viewer = new Viewer(_cache, _accessor, licenseFilePath);

Bieżąca integracja rejestruje Doconut raz i otrzymuje Viewer z wstrzykiwania zależności:

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

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

Viewer jest usługą przejściową. Menedżer sesji dokumentu i jego cache posiadają długotrwały stan dokumentu, nie konkretna wstrzyknięta instancja Viewer.

Middleware i trasowanie zasobów

Usuń klasyczną gałąź MapWhen, która wykrywa DocImage.axd:

// Classic integration — remove during the cutover.
app.MapWhen(
    context => context.Request.Path.ToString().EndsWith("DocImage.axd"),
    branch => branch.UseDoconut(new DoconutOptions()));

W bieżącym potoku:

1. wywołaj UseSession() przed Doconut, gdy zabezpieczenia sesji są włączone;
2. wywołaj UseDoconutResources() przed UseDoconut();
3. utrzymuj ResourcesPath, generowane URL‑e zasobów i klienta ResPath w zgodzie;
4. przy mapowaniu UseDoconut() do gałęzi, utrzymuj tę gałąź i BasePath klienta w zgodzie.

MiddlewarePath jest walidowaną konfiguracją; nie tworzy samodzielnie gałęzi ASP.NET Core. Użyj albo prostego potoku z przykładu powyżej, albo wyraźnego app.Map("/doconut", branch => branch.UseDoconut()), stosowanego konsekwentnie przez klienta.

Konstrukcja Viewer’a i jego czas życia

Usuń własnościowe cache obiektów Viewer. Wstrzyknij Viewer do punktu końcowego, strony Razor, kontrolera lub usługi o zasięgu scoped:

app.MapPost("/api/open", async (Viewer viewer) =>
{
    var token = await viewer.OpenDocumentAsync("wwwroot/files/Sample.pdf");
    return Results.Ok(new { token });
});

Zwrócony token identyfikuje sesję dokumentu po stronie serwera. Traktuj go jako poświadczenie typu bearer: nie loguj go, nie przechowuj i nie umieszczaj w analizach.

Otwieranie i zamykanie dokumentów

Zastąp synchroniczne OpenDocument(...) wywołaniem OpenDocumentAsync(...):

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

Bieżące przeciążenia przyjmują ścieżkę pliku lub strumień, opcjonalną konfigurację formatu, opcjonalny DocOptions oraz token anulowania. Zamknij sesję serwera explicite, gdy przeglądarka już jej nie potrzebuje:

viewer.CloseDocument(token);

Nie używaj ponownie klasycznego tokenu po przejściu. Otwieraj każdy dokument ponownie przy użyciu bieżącego API.

Klasy konfiguracyjne

Bieżące API rozdziela obszary odpowiedzialności:

Nie przenoś DocOptions.ImageResolution jako kontroli renderowania. Jest przestarzałe; ustaw BaseConfig.ImageResolution w konfiguracji specyficznej dla formatu. Przejrzyj wszystkie domyślne wartości zamiast zakładać, że klasyczna konfiguracja zachowuje się tak samo.

Pasek narzędzi Viewer’a, Search i Annotation

Nie migruj starych skryptów pojedynczo. Bieżące aplikacje referencyjne kompilują jeden kompletny pakiet strony:

1. emituj CSS Viewer’a oraz licencjonowany CSS Search/Annotation przy pomocy ReferenceCss;
2. renderuj pasek narzędzi Viewer’a własny dla aplikacji;
3. renderuj searchBarMount, annBarMount oraz wymaganą instancję Viewer’a;
4. emituj skrypty Viewer’a i licencjonowanych modułów przy pomocy ReferenceScripts;
5. załaduj własny skrypt aplikacji viewerToolbar.js;
6. zainicjuj jednego objViewer;
7. zainicjuj licencjonowane wstążki Search i Annotation;
8. wywołaj attach(objViewer) na każdej wstążce;
9. otwórz dokument i wywołaj objViewer.View(token).

Search i Annotation są modułami dołączonymi do tego samego Viewer’a, a nie niezależnymi paskami narzędzi. Główny pasek narzędzi należy do aplikacji‑gospodarza; wstążki Search i Annotation są wbudowanymi, ograniczonymi zasobami.

Usuń ręcznie skopiowane klasyczne pliki, takie jak documentLinks.js i docViewer.UI.js, dopiero po tym, jak bieżąca strona będzie działać z zasobami emitowanymi przez ReferenceCss i ReferenceScripts.

Rejestracja wtyczek

Klasyczne statyczne metody licencjonowania wtyczek nie rejestrują bieżących wtyczek. Zainstaluj i zarejestruj każdy wydany pakiet explicite:

builder.Services.AddDoconut(options =>
{
    options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
    options.AddPlugin<Doconut.Plugins.Dicom.DicomPlugin>();
});

AddDoconut() waliduje zarejestrowane możliwości wtyczek przy starcie. Converter i DICOM są wydanymi wtyczkami .NET 6. Normalny Search i Annotation są wbudowanymi, licencjonowanymi funkcjami, a nie pakietami AddPlugin<TPlugin>().

Sesja i bezpieczeństwo dokumentu

Bieżąca integracja wiąże dokumenty z nieprzezroczystymi tokenami i buforowanymi sesjami. Przy domyślnym UnsafeMode = false, UseDoconut() dodaje zabezpieczenie dostępu do dokumentu i host musi skonfigurować sesję ASP.NET:

builder.Services.AddSession();
app.UseSession();

Utrzymuj DocOptions.IsSecured = true, chyba że przeglądany projekt wymaga inaczej. Nigdy nie używaj UnsafeMode = true jako obejścia migracji. Testuj żądania bez tokenu, z uszkodzonym tokenem, z wygasłym tokenem i z tokenem pochodzącym z innej sesji przeglądarki.

Aplikacja referencyjna Distributed dodaje bilety dostępu i szczegóły transportu. Te API nie są wymagane przy normalnej migracji jednowęzłowej.

Testowanie migracji

Co najmniej sprawdź:

• uruchomienie aplikacji z produkcyjną licencją i wszystkimi zarejestrowanymi wtyczkami;
• CSS/Skrypty Viewer’a oraz wszystkie żądania obrazów pod wybranymi ścieżkami;
• otwieranie dokumentu, nawigację, zoom, miniatury, druk oraz explicite zamknięcie;
• Search w dokumencie tekstowym oraz brak możliwości wyszukiwania w pliku wyłącznie obrazkowym;
• ładowanie, zapisywanie, eksport oraz ograniczenia możliwości Annotation;
• wykrywanie celu konwertera, wynik, pobieranie i stan znaku wodnego;
• strony DICOM, klatki i animacje; metadane techniczne .NET 6 nie są dostępne;
• dokumenty zabezpieczone hasłem, niestandardowe czcionki, tekst niełaciński i skonfigurowane limity czasu;
• odrzucenie tokenu między sesjami oraz zachowanie przy wygasłej sesji;
• obsługa mobilna, tryb ciemny oraz ścieżka reverse‑proxy w produkcji.

Plan wycofania

Zachowaj klasyczny artefakt wdrożeniowy, dopasowane pakiety, pliki licencji i skopiowane zasoby przeglądarki razem. Bezpieczne wycofanie przełącza całą generację aplikacji; nie miesza klasycznego serwera z bieżącymi skryptami ani bieżącego serwera z klasycznymi wywołaniami DocImage.axd.

Przed przejściem, udokumentuj:

• slot wdrożeniowy lub artefakt używany do wycofania;
• wpływ na bazę danych/cache, jeśli istnieje;
• sposób unieważnienia aktywnych sesji dokumentów;
• kontrolkę zdrowia i dokument testowy używany do podjęcia decyzji o wycofaniu;
• kto może przywrócić poprzedni zestaw pakietów i konfigurację.

Dokumentacja klasyczna

Klasyczny podręcznik pozostaje dostępny pod adresem
Klasyczna konfiguracja .NET 6. Nowy
Brama klasycznej integracji wyjaśnia te same sygnały identyfikacyjne i odsyła z powrotem do tego przewodnika migracji.

Zachowaj historyczny URL w zakładkach i zgłoszeniach wsparcia, dopóki istnieją klasyczne instalacje. Dokumentuje on inną generację i nie jest przekierowywany do bieżącego API.