Debugowanie przy użyciu tożsamości pakietu

Wiele interfejsów API Windows (powiadomień wypychanych, zadań w tle, udostępniania miejsca docelowego, zadań uruchamiania, interfejsów API sztucznej inteligencji Windows) wymaga, aby aplikacja miała tożsamość package. Podczas programowania nie chcesz kompilować pełnego instalatora MSIX za każdym razem, gdy testujesz — aplikacja winapp udostępnia dwa polecenia umożliwiające nadanie tożsamości aplikacji na bieżąco.

Korzystanie z Visual Studio z projektem do pakowania? Jeśli używasz już Visual Studio dla spakowanego projektu, prawdopodobnie nie potrzebujesz aplikacji winapp do debugowania. Visual Studio obsługuje już rejestrację pakietów, tożsamość, aktywację AUMID, załącznik debugera i debugowanie kodu aktywacji — wszystko z poziomu F5. Oferuje również → Debugowanie innych celów debugowania → Debugowanie zainstalowanego pakietu aplikacji na potrzeby zaawansowanych scenariuszy. Poniższe przepływy pracy są najbardziej przydatne dla użytkowników programu VS Code, przepływów pracy opartych na terminalach i struktur, których program VS nie pakuje natywnie (Rust, Flutter, Tauri, Electron, plain C++).

Dwa podejścia: winapp run vs create-debug-identity

winapp run create-debug-identity
Co rejestruje Pełny nieskompresowany pakiet układu (cały folder) Pakiet rozrzedny (pojedynczy plik exe)
Jak aplikacja jest uruchamiana Uruchomione przez winapp (alias aktywacji lub uruchamiania AUMID) Uruchamiasz plik exe samodzielnie (wiersz polecenia, środowisko IDE itp.)
Symuluje instalację MSIX Tak — najbliżej zachowania produkcyjnego Nie — tylko rzadka tożsamość
Pliki pozostają na miejscu Skopiowane do katalogu układu AppX Tak — plik exe pozostaje w oryginalnej ścieżce
Zakres tożsamości Cała zawartość folderu (exe, biblioteki DLL, zasoby) Pojedynczy plik wykonywalny
Przyjazny dla debugera Dołącz do identyfikatora PID po uruchomieniu lub użyj polecenia --no-launch , a następnie uruchom za pomocą aliasu Uruchom bezpośrednio z debuggera IDE — plik exe zachowuje tożsamość niezależnie od tego
Obsługa aplikacji konsolowych --with-alias utrzymuje stdin/stdout w terminalu Uruchamianie pliku exe bezpośrednio w terminalu
Najlepsze dla Większość struktur (.NET, C++, Rust, Flutter, Tauri) Elektron lub gdy potrzebujesz pełnej kontroli debugera IDE (F5)

Kiedy należy użyć którego

Ustawienie domyślne: winapp run

Użyj winapp run dla większości procesów deweloperskich. Symulacja prawdziwej instalacji MSIX — aplikacja uzyskuje tę samą tożsamość, możliwości i skojarzenia plików, jakie miałaby w środowisku produkcyjnym.

# Build your app, then:
winapp run .\build\output

Użyj create-debug-identity, gdy:

  • Plik exe jest oddzielony od danych wyjściowych kompilacji — np. aplikacji Electron, w których electron.exe znajduje się node_modules/
  • Musisz debugować kod uruchamiania i nie można dołączyć debugera wystarczająco szybko po uruchomieniu identyfikatora AUMID
  • W przypadku niektórych debugerów, w których nie można rozpocząć działania z użyciem identyfikatora AUMID a proces musi mieć swoją tożsamość — create-debug-identity rejestruje plik 'exe', aby miał tożsamość bez względu na sposób jego uruchomienia.
  • Przeprowadzasz testy zachowania pakietu rzadkiego w szczególności: (AllowExternalContent, TrustedLaunch)
# Register identity for an exe, then launch it however you want:
winapp create-debug-identity .\bin\Debug\myapp.exe
.\bin\Debug\myapp.exe   # or F5 in your IDE

Scenariusze debugowania

Scenariusz A: Po prostu działaj w ramach tożsamości

Najprostszy przepływ pracy — kompilacja, uruchamianie z tożsamością, gotowe.

winapp run .\build\Debug

Aplikacja Winapp rejestruje folder jako luźny pakiet układu i uruchamia aplikację. API wymagające tożsamości działają natychmiast. Obejmuje to większość scenariuszy tworzenia i testowania.

W przypadku aplikacji konsolowych , które wymagają stdin/stdout w bieżącym terminalu, dodaj polecenie --with-alias:

winapp run .\build\Debug --with-alias

Scenariusz B: dołączanie debugera do uruchomionej aplikacji

Uruchom winapp run, zanotuj identyfikator PID, a następnie przyłącz debuger środowiska IDE.

winapp run .\build\Debug
# Output: Process ID: 12345

Następnie w środowisku IDE:

Ograniczenie: Pominiesz kod uruchamiany przed dołączeniem. Do debugowania uruchamiania użyj scenariusza D (create-debug-identity).

Scenariusz C: Rejestrowanie tożsamości, a następnie uruchamianie za pomocą identyfikatora AUMID lub aliasu ze środowiska IDE

Użyj polecenia --no-launch, aby zarejestrować pakiet, a następnie uruchom aplikację za pomocą identyfikatora AUMID (zgłoszonego przez run) lub aliasu egzekucji ze środowiska IDE.

Krok 1: Zarejestruj pakiet bez uruchamiania:

winapp run .\build\Debug --no-launch

Krok 2. Skonfiguruj środowisko IDE do uruchamiania za pośrednictwem identyfikatora AUMID lub aliasu wykonywania (a nie bezpośrednio pliku exe).

  • Uruchamianie za pomocą identyfikatora AUMID: użyj polecenia start shell:AppsFolder\<AUMID>. winapp run zwraca identyfikator AUMID po zarejestrowaniu aplikacji.
  • Uruchamianie z aliasem: alias musi być zdefiniowany w manifeście (Package.appxmanifest preferowany, appxmanifest.xml również obsługiwany).

Ważne: Po prostu uruchomienie pliku exe w folderze kompilacji nie da mu tożsamości. Aplikacja musi zostać uruchomiona za pośrednictwem aktywacji AUMID lub jej aliasu wykonawczego. Tak działają luźne pakiety układów — tożsamość jest powiązana ze ścieżką aktywacji, a nie z plikiem exe.

Scenariusz D: Uruchamianie z środowiska IDE przy użyciu tożsamości (debugowanie startowe)

Jest to najlepsze podejście do debugowania kodu startowego z pełną kontrolą środowiska IDE — debuger środowiska IDE kontroluje proces z pierwszej instrukcji, a plik exe ma tożsamość niezależnie od sposobu jego uruchomienia.

winapp create-debug-identity .\build\Debug\myapp.exe

Teraz uruchom plik exe w dowolny sposób — z terminalu, za pomocą F5 w Visual Studio Code lub ze skryptu. Plik exe ma tożsamość, ponieważ Windows zarejestrował pakiet sparse wskazujący go bezpośrednio.

Czym różni się od winapp run: przy użyciu create-debug-identity tożsamość jest powiązana z samym plikiem exe przez Add-AppxPackage -ExternalLocation. W przypadku użycia winapp run, tożsamość jest związana z pakietem nietrwałego układu — aplikacja musi zostać uruchomiona za pomocą identyfikatora AUMID lub aliasu. Ten wybór sprawia, że create-debug-identity jest lepszym rozwiązaniem, gdy potrzebujesz, aby twoje środowisko IDE bezpośrednio uruchamiało i debugowało plik exe.

Jest to również najlepsze podejście dla aplikacji Electron , w których ścieżka exe różni się od katalogu źródłowego.

Scenariusz E: przechwytywanie danych wyjściowych debugowania i diagnostyki awarii

Przechwyć komunikaty OutputDebugString i wyjątki pierwszej szansy w linii. Szum ramowy (wewnętrzne śledzenia WinUI, COM, DirectX) jest filtrowany z konsoli, więc pojawiają się tylko komunikaty debugowania twojej aplikacji. Wszystko jest nadal zapisywane w pliku dziennika w celu pełnego zbadania.

Jeśli aplikacja ulegnie awarii, minidump zostanie przechwycony i przeanalizowany automatycznie:

winapp run .\build\Debug --debug-output

W przypadku awarii dane wyjściowe zawierają typ wyjątku, komunikat i ślad stosu z plikiem źródłowym i numerami wierszy (rozpoznawane z plików PDB w folderze danych wyjściowych kompilacji). Awarie zarządzane (.NET) są analizowane natychmiast bez narzędzi zewnętrznych. Awarie natywne (C++/WinRT) pokazują nazwy modułów i przesunięcia; dodaj --symbols , aby pobrać symbole PDB dla pełnych nazw funkcji:

winapp run .\build\Debug --debug-output --symbols

Ważne: Spowoduje to dołączenie aplikacji winapp jako debugera. Windows zezwala tylko na jeden debuger na proces, więc nie można również dołączać Visual Studio, VS Code lub WinDbg.

Analiza wyjątków stowed w WinUI

Większość awarii WinUI zaczyna się w procedurze obsługi zdarzeń XAML i ujawnia się jako odłożony wyjątek (0xC000027B), który jest później zgłaszany ponownie przez dyspozytora, więc zwykły stos wywołań nie wskazuje już rzeczywistej przyczyny. Gdy została załadowana aplikacja, która uległa awarii, Microsoft.UI.Xaml.dllwinapp automatycznie uruchamia dodatkowy etap analizy wstępnej, który dekoduje odłożony wyjątek oraz natywny łańcuch wywołań dyspozytora XAML (Microsoft.UI.Xaml → CXcpDispatcher → CoreMessagingXP → host CLR). Wynik jest dołączany do dziennika debugowania. Nie jest wymagana flaga — jest ona włączona automatycznie dla zrzutów WinUI. Dodaj --symbols dla w pełni określonych nazw funkcji w łańcuchu wywołań.

Aby to zadziałało, winapp przechwytuje zrzut awarii wraz z rekordem kończącego wyjątku odłożonego (oraz jego parametrami, które wskazują na tablicę odłożonych wyjątków), zachowując przy tym kontekst wątku z pierwszej szansy, dzięki czemu standardowa analiza kodu zarządzanego nadal odzyskuje oryginalną ramkę użytkownika i etap analizy wstępnej może zlokalizować odłożony wyjątek.

Ten etap obsługuje DbgEng z rozszerzeniem WinDbg JavaScript zespołu WinUI. Natywny silnik debugowania (dbgeng.dll i powiązane składniki) pochodzi z NuGet, a JsProvider.dll — host skryptów JavaScript, który nie jest dostępny w NuGet — jest pobierany przy pierwszym użyciu bezpośrednio z oficjalnego pakietu do pobrania WinDbg (odczytywane jest tylko potrzebne kilkaset kilobajtów, a nie cały pakiet). Ponieważ JsProvider.dll musi mieć tę samą kompilację co silnik — wczytanie niezgodnego dostawcy powoduje awarię debugera przy uruchamianiu — jest on przypięty do konkretnego pakietu WinDbg, którego kompilacja odpowiada kompilacji silnika NuGet (a nie do zmiennego wydania „current”), a po pobraniu porównuje się obie kompilacje: w przypadku niezgodności dostawca jest odrzucany, a triage jest pomijane z jasno podanym powodem, zamiast powodować cichą awarię. Pakiety debugera mają przypięte wersje i przed wyodrębnieniem oraz załadowaniem dowolnej z ich natywnych bibliotek DLL są weryfikowane względem wkompilowanego skrótu zawartości SHA-512 (a rozszerzenie — względem przypiętego skrótu); JsProvider.dll musi dodatkowo posiadać prawidłowy podpis Microsoft Authenticode, sprawdzany z pełną weryfikacją unieważnienia w całym łańcuchu certyfikatów (z przejściem awaryjnym do sprawdzania wyłącznie podpisu, gdy w trybie offline nie można uzyskać dostępu do danych o unieważnieniu, ale z zawsze obowiązkowym odrzuceniem unieważnionego certyfikatu). Pobrane pliki są najpierw zapisywane do pliku tymczasowego, weryfikowane, a następnie atomowo umieszczane w pamięci podręcznej, dzięki czemu równolegle uruchomiony proces nigdy nie napotka częściowo zapisanej ani nieweryfikowanej biblioteki DLL. Przy każdym uruchomieniu zbuforowane pliki binarne są ponownie sprawdzane (weryfikowana jest zgodność sygnatury JsProvider.dll i kompilacji silnika oraz to, czy biblioteki DLL silnika mają poprawny obraz PE), dzięki czemu przycięta lub nieaktualna pamięć podręczna samoczynnie się naprawia przez ponowne pobranie plików, zamiast kończyć się błędem przy każdym uruchomieniu. Oznacza to, że dublowane lub naruszone źródło danych nie może zastąpić zmienionych plików binarnych — każda awaria pomija klasyfikację, a nie ładuje niezweryfikowanego kodu. Wszystkie elementy są buforowane w katalogu globalnym winapp, więc kolejne uruchomienia są w trybie offline. Jeśli środowisko blokuje te pliki do pobrania, zainstaluj narzędzia debugowania dla Windows (za pośrednictwem zestawu SDK Windows) lub ustaw WINAPP_DBGTOOLS_DIR zmienną środowiskową na katalog debugera, który już zawiera dbgeng.dll i JsProvider.dll. Gdy ustawiono WINAPP_DBGTOOLS_DIR, ma ono charakter autorytatywny — sprawdzany jest tylko ten katalog — więc jeśli jest on niekompletny, w dzienniku wskazywany jest konkretny brakujący składnik (dbgeng.dll i/lub JsProvider.dll), zamiast sugerować ustawienie zmiennej, która została już ustawiona. Gdy wstępna analiza zakończy się powodzeniem, konsola wyświetla jednozdaniowy werdykt (kod błędu/komunikat odłożonego wyjątku); gdy nie można uzyskać plików binarnych, etap wstępnej analizy jest pomijany (standardowa analiza kodu zarządzanego/natywnego nadal jest wykonywana), konsola informuje o tym, a dziennik wyjaśnia dlaczego.

Etap triage jest uruchamiany w krótkotrwałym procesie podrzędnym. Jest to konieczne: główny proces winapp ładuje system dbghelp.dll podczas przechwytywania i analizowania zrzutu, a nowoczesny silnik dbgeng.dll nie może powiązać się z tą starszą, już załadowaną do pamięci kopią — nowy proces zapewnia silnikowi czysty stan ładowania. Dekodowanie struktur wyjątków stowed wymaga również symboli systemu operacyjnego (combase.dll), które są pobierane przez --symbols z publicznego serwera symboli firmy Microsoft; w kompilacjach, których symbole nie są tam publikowane, przebieg triage nadal identyfikuje wyjątek stowed, ale nie może w pełni go rozwinąć.

Konfiguracja środowiska IDE

VS Code

Rozszerzenie winApp VS Code udostępnia niestandardowy winapp typ debugowania, który uruchamia aplikację przy użyciu tożsamości pakietu i dołącza debuger — wszystko z jednego naciśnięcia klawisza F5. Zainstaluj go z Visual Studio Marketplace; jego kod źródłowy i narzędzie do śledzenia zgłoszeń znajdują się w repozytorium microsoft/WinAppVSCE.

Jednym naciśnięciem klawisza F5 możliwość debugowania z wykorzystaniem tożsamości

Dodaj konfigurację uruchamiania winapp do .vscode/launch.json:

{
    "version": "0.2.0",
    "configurations": [
        {
            "type": "winapp",
            "request": "launch",
            "name": "WinApp: Launch and Attach"
        }
    ]
}

Po naciśnięciu klawisza F5:

  1. Rozszerzenie skanuje obszar roboczy pod kątem katalogów wyjściowych kompilacji zawierających .exe pliki.
  2. Wybierz folder kompilacji do uruchomienia (lub ustaw opcję inputFolder pominięcia monitu).
  3. Uruchamia aplikację za pomocą polecenia winapp run , aby nadać jej tożsamość pakietu.
  4. Podrzędna sesja debugowania jest dołączana do uruchomionego procesu przy użyciu określonego debugera.

Po dołączeniu debugera uzyskasz pełne środowisko debugowania programu VS Code — ustaw punkty przerwania, klikając margines, przechodząc przez kod wiersz po wierszu (F10), wchodzenie do funkcji (F11), sprawdzanie zmiennych w okienku Zmienne i ocenianie wyrażeń w Konsola debugowania. Aplikacja działa z tożsamością pakietu w całym środowisku, więc interfejsy API zależne od tożsamości zachowują się dokładnie tak, jak w środowisku produkcyjnym.

Ważne:winapp Typ debugowania nie kompiluje projektu automatycznie. Po wprowadzeniu zmian w kodzie, zbuduj go ponownie przed naciśnięciem klawisza F5.

Automatyzowanie kompilacji za pomocą polecenia preLaunchTask

Aby uniknąć zapomnienia o ponownym zbudowaniu, dodaj preLaunchTask, który buduje projekt przed każdą sesją debugowania.

  1. Zdefiniuj zadanie kompilacji w .vscode/tasks.json (na przykład .NET):
    {
    "version": "2.0.0",
    "tasks": [
        {
            "label": "build",
            "command": "dotnet",
            "type": "process",
            "args": ["build", "${workspaceFolder}"],
            "problemMatcher": "$msCompile"
        }
    ]
}
  2. Odwołaj się do niego w pliku launch.json: 
    {
    "type": "winapp",
    "request": "launch",
    "name": "WinApp: Launch and Attach",
    "preLaunchTask": "build"
}

Właściwości konfiguracji

Majątek Typ Wartość domyślna Description
inputFolder ciąg Ścieżka do folderu wyjściowego kompilacji zawierającego pliki binarne aplikacji (np. ${workspaceFolder}/bin/Debug/net8.0-windows10.0.22621). Jeśli nie zostanie ustawiona, zostanie wyświetlony monit o wybranie folderu.
manifest ciąg Ścieżka do pliku manifestu AppX (np. AppxManifest.xml, lub Package.appxmanifestappxmanifest.xml). Jeśli nie zostanie ustawione, CLI automatycznie wykryje folder wejściowy lub bieżący katalog.
debuggerType ciąg coreclr Podstawowy debuger do użycia (coreclr, cppvsdbglub node).
workingDirectory ciąg folder obszaru roboczego Katalog roboczy aplikacji.
args ciąg Argumenty wiersza poleceń, które należy przekazać aplikacji.
outputAppxDirectory ciąg Katalog wyjściowy pakietu w układzie swobodnym. Domyślnie jest to AppX folder wewnątrz folderu wejściowego.
port number 9229 (node tylko) Port używany dla odbiornika Node.js --inspect i połączenia dołączania. Zastąpij, gdy domyślny port jest już używany.

Obsługiwane debugery

debuggerType Język Wymagane rozszerzenie
coreclr (ustawienie domyślne) C# /.NET Zestaw deweloperski C#
cppvsdbg C/ C++ C/C++
node Node.js / Elektron Wbudowana

Przykład dla projektu C++:

{
    "type": "winapp",
    "request": "launch",
    "name": "WinApp: Launch C++ App",
    "debuggerType": "cppvsdbg"
}

Debugowanie początkowe za pomocą Create Debug Identity

Jeśli musisz debugować kod startowy od samej pierwszej instrukcji, podejście polegające na użyciu opcji F5 do dołączenia debuggera może przegapić wczesny kod. Zamiast tego użyj polecenia WinApp: Utwórz tożsamość debugowania z Palety Poleceń (Ctrl+Shift+P), aby zarejestrować pakiet rozrzedzony dla pliku wykonywalnego, a następnie uruchom go przy użyciu standardowego debugera:

{
    "name": "Launch (with identity)",
    "type": "coreclr",
    "request": "launch",
    "program": "${workspaceFolder}/bin/Debug/net8.0-windows10.0.22621/myapp.exe"
}

Ponieważ create-debug-identity rejestruje tożsamość w samym pliku exe, aplikacja ma tożsamość niezależnie od sposobu jej uruchomienia — w tym ze standardowej konfiguracji uruchamiania programu VS Code.

Dołączanie do uruchomionego procesu

Jeśli wolisz uruchomić z winapp run w terminalu, a następnie podłączyć, użyj standardowej konfiguracji podłączania:

{
    "name": "Attach to Process",
    "type": "coreclr",
    "request": "attach",
    "processId": "${command:pickProcess}"
}

W przypadku języka C++/Rust użyj ( "type": "cppvsdbg" MSVC) lub "type": "lldb" (LLDB):

{
    "name": "Attach (C++)",
    "type": "cppvsdbg",
    "request": "attach",
    "processId": "${command:pickProcess}"
}

Czyszczenie

Po zakończeniu testowania uruchom WinApp: Wyrejestruj pakiet z Palety poleceń, aby usunąć wczytane pakiety deweloperskie bez opuszczania programu VS Code.

  • Last updated on