Migracja z klasycznej integracji .NET 6
Przenieś istniejącą aplikację Doconut.NET6 do bieżącego DI i asynchronicznego API
Doconut ma dwie odrębne integracje .NET 6. Mogą używać tej samej Doconut.NET6 nazwy pakietu, więc zidentyfikuj generację na podstawie API w aplikacji przed zmianą pakietów, uruchamiania, licencji lub zasobów przeglądarki.
Którą integrację .NET 6 używasz?
| Jeśli projekt zawiera… | Generacja |
|---|---|
app.MapWhen(... "DocImage.axd" ...) | Starsza / klasyczna |
new Viewer(_cache, _accessor, ...) | Starsza / klasyczna |
Viewer.DoconutLicense(...) lub Viewer.SetLicensePlugin(...) | Starsza / klasyczna |
Ręcznie skopiowane docViewer.js, documentLinks.js, lub docViewer.UI.js | Starsza / klasyczna |
builder.Services.AddDoconut(...) | Bieżąca integracja |
app.UseDoconutResources() plus app.UseDoconut() | Bieżąca integracja |
Viewer dostarczany przez wstrzykiwanie zależności | Bieżąca integracja |
await viewer.OpenDocumentAsync(...) | Bieżąca integracja |
Jeśli obie kolumny pojawiają się w tej samej aplikacji, traktuj migrację jako niekompletną. Nie wysyłaj jednego tokenu dokumentu przez zasoby lub middleware z innej generacji.
Dlaczego nazwa pakietu NuGet może nie wystarczyć
Obie generacje zostały opublikowane pod identyfikatorem pakietu Doconut.NET6. Odwołanie do pakietu, plik lock lub buforowany .nupkg nie identyfikuje więc API hostującego samodzielnie. Zanotuj dokładną wersję pakietu i sprawdź Program.cs, konstrukcję viewer, otwieranie dokumentów oraz skrypty przeglądarki razem.
Obecne wydanie audytowane dla tego przewodnika to Doconut.NET6 26.7.0. Jego opcjonalne publiczne pakiety to Doconut.NET6.Converter i Doconut.NET6.Dicom, przypięte do tej samej wersji wydania co pakiet podstawowy.
Przed migracją
- Utwórz gałąź i wdrażalną kopię zapasową istniejącej aplikacji.
- Zanotuj dokładne wersje pakietu podstawowego i wtyczek.
- Inwentaryzuj każde mapowanie
DocImage.axd, wywołanienew Viewer(...), wywołanie ładowania licencji, skopiowany skrypt Doconut, niestandardową akcję paska narzędzi oraz punkt końcowy otwierania dokumentu. - Zachowaj bieżące pliki
.lici sekrety wdrożeniowe poza kontrolą wersji. - Zbierz reprezentatywny zestaw dokumentów PDF, Office, obrazów, CAD, e‑mail, DICOM, przeszukiwalnych, chronionych hasłem i anotowanych.
- Zanotuj istniejące limity czasu sesji, zachowanie zabezpieczeń, czcionki i ustawienia platformy.
Migruj jedno środowisko przed zmianą produkcji. Bieżąca integracja zmienia czas życia usług, trasowanie żądań, własność sesji oraz dostarczanie zasobów klienta.
Zgodność pakietów i licencji
Zamień lub zaktualizuj pakiet podstawowy celowo; nie polegaj na identycznym identyfikatorze pakietu, aby wybrać nowe API. Domyślne polecenie instaluję najnowsze stabilne wydanie:
dotnet add package Doconut.NET6Aby uzyskać powtarzalną migrację do wydania audytowanego w tym przewodniku, przekaż wersję jako oddzielną opcję:
dotnet add package Doconut.NET6 --version 26.9.0Utrzymuj każdą wtyczkę Doconut w tej samej wersji co pakiet podstawowy. Bieżąca integracja ładuje licencje raz podczas AddDoconut(), używając tego priorytetu:
LicenseStream > LicenseContent > LicensePath > automatic discoveryAutomatyczne wykrywanie szuka Doconut.Viewer.lic i towarzyszących plików Doconut.Viewer.<Capability>.lic. Klasyczne wywołanie Viewer.DoconutLicense(...) lub Viewer.SetLicensePlugin(...) nie jest bieżącym mechanizmem uruchamiania. Przenieś licencję do DoconutOptions, trzymaj pliki towarzyszące 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 dowodzi uprawnienia do bieżącej wersji wtyczki. Testuj osobno Viewer, Search, Annotation, Converter i DICOM przy użyciu zatwierdzonych artefaktów wydania.
Rozruch i wstrzykiwanie zależności
Klasyczne aplikacje tworzą Viewer z pamięcią podręczną ASP.NET oraz zależnościami request-accessor:
// Klasyczna integracja — tylko kontrast; nie kompiluj tego z bieżącym SDK.
var viewer = new Viewer(_cache, _accessor, licenseFilePath);Obecna 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.AddDistributedMemoryCache();
builder.Services.AddSession();
app.UseSession();
app.UseDoconutResources();
app.UseDoconut();Viewer jest usługą przejściową. Menedżer sesji dokumentu i jego pamięć podręczna posiadają długotrwały stan dokumentu, a nie konkretną wstrzykniętą instancję Viewer.
Middleware i trasowanie zasobów
Usuń klasyczną gałąź MapWhen, która wykrywa DocImage.axd:
// Klasyczna integracja — usuń podczas przejścia.
app.MapWhen(
context => context.Request.Path.ToString().EndsWith("DocImage.axd"),
branch => branch.UseDoconut(new DoconutOptions()));W bieżącym potoku:
- wywołaj
UseSession()przed Doconut, gdy zabezpieczenie sesji jest włączone; - wywołaj
UseDoconutResources()przedUseDoconut(); - utrzymaj
ResourcesPath, wygenerowane adresy URL zasobów oraz klientaResPathw zgodzie; - przy mapowaniu
UseDoconut()na gałąź, zachowaj tę gałąź i klientaBasePathw zgodzie.
MiddlewarePath jest zweryfikowaną konfiguracją; nie tworzy ona samodzielnie gałęzi ASP.NET Core. Użyj albo prostego potoku w powyższym przykładzie kompilacji, albo wyraźnego układu app.Map("/doconut", branch => branch.UseDoconut()) stosowanego konsekwentnie przez klienta.
Konstrukcja i cykl życia Viewera
Usuń pamięci podręczne własności aplikacji dla obiektów Viewer. Wstrzyknij Viewer do punktu końcowego, strony Razor, kontrolera lub usługi aplikacji o zasięgu:
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 rejestruj go, nie przechowuj ani nie umieszczaj w analizach.
Otwieranie i zamykanie dokumentów
Zastąp synchroniczny OpenDocument(...) przez OpenDocumentAsync(...):
// Aktualna integracja .NET 6: Viewer pochodzi z DI i otwieranie dokumentu jest asynchroniczne.
var token = await viewer.OpenDocumentAsync(path, new PdfConfig { AllowSearch = true });Obecne przeciążenia akceptują ś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. Otwórz każdy dokument ponownie za pomocą bieżącego API.
Klasy konfiguracji
Obecne API rozdziela obszary:
| Zagadnienie | Obecny typ |
|---|---|
| Ścieżki middleware, licencjonowanie, rejestracja wtyczek | DoconutOptions |
| Hasło, limit czasu, bezpieczeństwo, znak wodny | DocOptions |
| Renderowanie formatu i DPI | PdfConfig, WordConfig, ExcelConfig, i inne typy BaseConfig |
| Domyślne ustawienia widgetu przeglądarki | ViewerConfig lub równoważne opcje JavaScript |
| Wygenerowane CSS i skrypty | CssConfig i ScriptConfig |
Nie przenoś DocOptions.ImageResolution jako kontrolki renderowania. Jest ona przestarzała; ustaw BaseConfig.ImageResolution w konfiguracji specyficznej dla formatu. Przejrzyj wszystkie domyślne ustawienia zamiast zakładać, że klasyczna konfiguracja zachowuje się tak samo.
Pasek narzędzi Viewera, wyszukiwanie i adnotacje
Nie migruj starych skryptów pojedynczo. Obecne aplikacje referencyjne tworzą kompletny pakiet strony:
- wyemituj CSS Viewera oraz licencjonowany CSS Search/Annotation przy użyciu
ReferenceCss; - renderuj pasek narzędzi Viewera należący do aplikacji;
- renderuj
searchBarMount,annBarMountoraz wymaganą montaż Viewera; - wyemituj skrypty Viewera i licencjonowane moduły przy użyciu
ReferenceScripts; - załaduj własny
viewerToolbar.jsaplikacji; - zainicjuj jeden
objViewer; - zainicjuj licencjonowane wstążki Search i Annotation;
- wywołaj
attach(objViewer)na każdej wstążce; - otwórz dokument i wywołaj
objViewer.View(token).
Search i Annotation są modułami podłączonymi do tego samego Viewera, a nie niezależnymi paskami narzędzi. Główny pasek narzędzi należy do aplikacji hosta; wstążki Search i Annotation są osadzone, jako zasoby zależne od możliwości.
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 wyemitowanymi przez ReferenceCss i ReferenceScripts.
Rejestracja wtyczki
Klasyczne statyczne metody licencjonowania wtyczek nie rejestrują bieżących wtyczek. Zainstaluj i zarejestruj każdy wydany pakiet wyraźnie:
builder.Services.AddDoconut(options =>
{
options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
options.AddPlugin<Doconut.Plugins.Dicom.DicomPlugin>();
});AddDoconut() weryfikuje zarejestrowane możliwości wtyczek przy uruchamianiu. Converter i DICOM są wydanymi wtyczkami .NET 6. Normal Search i Annotation są wbudowanymi funkcjami licencjonowanymi, a nie pakietami AddPlugin<TPlugin>().
Bezpieczeństwo sesji i dokumentu
Obecna integracja wiąże dokumenty z nieprzezroczystymi tokenami i buforowanymi sesjami. Z domyślnym UnsafeMode = false, UseDoconut() dodaje bezpieczeństwo dostępu do dokumentu i host musi skonfigurować sesję ASP.NET:
builder.Services.AddDistributedMemoryCache(); // stan sesji wymaga pamięci podręcznej (MVC/Razor Pages już dodają jedną)
builder.Services.AddSession();
app.UseSession();Zachowaj DocOptions.IsSecured = true, chyba że przeglądany projekt wymaga inaczej. Nigdy nie używaj UnsafeMode = true jako skrótu migracji. Testuj żądania bez tokenu, z uszkodzonym tokenem, z wygasłym tokenem oraz z tokenem z innej sesji przeglądarki.
Rozproszona aplikacja referencyjna dodaje bilety dostępu i szczegóły transportu. Te interfejsy API nie są wymagane przy normalnej migracji jednowęzłowej.
Testowanie migracji
Co najmniej, zweryfikuj:
- uruchomienie aplikacji z licencją produkcyjną i każdą zarejestrowaną wtyczką;
- CSS/skrypty przeglądarki i wszystkie żądania obrazów stron w wybranych ścieżkach;
- otwieranie dokumentu, nawigację, przybliżanie, miniatury, drukowanie i wyraźne zamknięcie;
- wyszukiwanie w dokumencie zawierającym tekst oraz stan nieprzeszukiwalny pliku tylko z obrazem;
- ładowanie, zapisywanie, eksportowanie adnotacji oraz kontrola możliwości;
- odkrywanie celu konwertera, wyjście, pobieranie i stan znaku wodnego;
- strony, klatki i animacje DICOM; metadane techniczne .NET 6 są niedostępne;
- dokumenty chronione hasłem, własne czcionki, tekst niełaciński i skonfigurowane limity czasu;
- odrzucanie tokenów między sesjami oraz zachowanie przy wygasłej sesji;
- mobilny, tryb ciemny i ścieżka odwróconego proxy produkcji.
Plan przywracania
Zachowaj klasyczny artefakt wdrożeniowy, pasujące pakiety, pliki licencji i skopiowane zasoby przeglądarki razem. Bezpieczne przywrócenie przełącza całą generację aplikacji; nie miesza klasycznego serwera z bieżącymi skryptami ani bieżącego serwera z klasycznymi wywołaniami DocImage.axd.
Przed przełączeniem, udokumentuj:
- slot wdrożeniowy lub artefakt używany do przywracania;
- wpływ na bazę danych/pamięć podręczną, jeśli istnieje;
- jak aktywne sesje dokumentów będą unieważniane;
- kontrolę zdrowia i dokument testowy używany do podjęcia decyzji o przywróceniu;
- kto może przywrócić poprzedni zestaw pakietów i konfigurację.
Dokumentacja starsza
Przetłumana klasyczna instrukcja pozostaje dostępna pod adresem Starsza konfiguracja .NET 6. Nowy Brama integracji klasycznej wyjaśnia te same sygnały identyfikacyjne i odsyła do tego przewodnika migracji.
Zachowaj historyczny URL w zakładkach i zgłoszeniach wsparcia, dopóki klasyczne instalacje nadal istnieją. Dokumentuje on inną generację i nie jest przekierowywany do bieżącego API.
Czy ta strona była pomocna?