Udostępnij za pośrednictwem

Niestandardowe wizualizatory danych dla debugera programu Visual Studio (.NET)

Ważne

Począwszy od Visual Studio 2022 w wersji 17.9, wizualizatory można teraz pisać na platformie .NET 6.0+, które działają poza procesem przy użyciu nowego modelu VisualStudio.Extensibility. Aby uzyskać rozszerzenia utworzone przy użyciu nowego modelu, zobacz dokumentację w temacie Tworzenie wizualizatorów debugera programu Visual Studio . Jeśli potrzebujesz obsługiwać starsze wersje programu Visual Studio lub chcesz dostarczyć niestandardowe wizualizatory w ramach biblioteki DLL, skorzystaj z informacji w tym artykule, które dotyczą tylko starszego modelu programowania rozszerzeń (VSSDK).

Wizualizator jest częścią interfejsu użytkownika debugera programu Visual Studio, który wyświetla zmienną lub obiekt w sposób odpowiedni dla jego typu danych. Na przykład wizualizator mapy bitowej interpretuje strukturę mapy bitowej i wyświetla grafikę, która reprezentuje. Niektóre wizualizatory umożliwiają modyfikowanie, a także wyświetlanie danych. W debugerze wizualizator jest reprezentowany przez ikonę lupy VisualizerIcon. Możesz wybrać ikonę w oknie DataTip, debugger Watch lub QuickWatch , a następnie wybrać odpowiedni wizualizator dla odpowiedniego obiektu.

Oprócz standardowych wbudowanych wizualizatorów więcej wizualizatorów może być dostępnych do pobrania z firmy Microsoft, innych firm i społeczności. Możesz również napisać własne wizualizatory i zainstalować je w debugerze programu Visual Studio.

Ten artykuł zawiera ogólne omówienie tworzenia wizualizatora. Aby uzyskać szczegółowe instrukcje, zobacz następujące artykuły:

Uwaga / Notatka

Niestandardowe wizualizatory nie są obsługiwane w przypadku aplikacji platformy uniwersalnej systemu Windows (UWP) i systemu Windows 8.x.

Przegląd

Można napisać niestandardowy wizualizator dla obiektu dowolnej klasy zarządzanej z wyjątkiem Object i Array.

Architektura wizualizatora debugera ma dwie części:

  • Strona debugera jest uruchamiana w debugerze programu Visual Studio i tworzy i wyświetla interfejs użytkownika wizualizatora.

    Ponieważ program Visual Studio jest wykonywany w środowisku uruchomieniowym programu .NET Framework, ten składnik musi być napisany dla programu .NET Framework. Z tego powodu nie można zapisać go dla platformy .NET Core.

  • Strona debuggee działa w procesie debugowanym przez program Visual Studio (czyli w samym debuggee). Obiekt danych do wizualizacji (na przykład obiekt String) istnieje w procesie debuggee. Strona debugowania wysyła obiekt do strony debugera, który wyświetla go w utworzonym interfejsie użytkownika.

    Środowisko uruchomieniowe, dla którego kompilujesz ten składnik, powinno być zgodne z tym, w którym zostanie uruchomiony proces debugowania, czyli .NET Framework lub .NET Core.

Strona debugera odbiera obiekt danych od dostawcy obiektów , który implementuje IVisualizerObjectProvider interfejs. Strona debugowana wysyła obiekt za pośrednictwem źródła obiektu, które pochodzi z VisualizerObjectSource.

Dostawca obiektów może również wysyłać dane z powrotem do źródła obiektów, co umożliwia napisanie wizualizatora, który może edytować dane. Zastępujesz dostawcę obiektów, aby nawiązać komunikację z ewaluatorem wyrażeń i źródłem obiektów.

Strona debuggee i strona debuggera komunikują się za pośrednictwem metod Stream, które serializują obiekt danych do Stream, a następnie deserializują Stream z powrotem do obiektu danych.

Wizualizator dla typu ogólnego można napisać tylko wtedy, gdy typ jest typem otwartym. To ograniczenie jest takie samo jak ograniczenie podczas używania atrybutu DebuggerTypeProxy . Aby uzyskać szczegółowe informacje, zobacz Use the DebuggerTypeProxy attribute (Używanie atrybutu DebuggerTypeProxy).

Niestandardowe wizualizatory mogą mieć zagadnienia dotyczące zabezpieczeń. Zobacz Zagadnienia dotyczące zabezpieczeń wizualizatora.

Tworzenie interfejsu użytkownika po stronie debugera

Aby utworzyć interfejs użytkownika wizualizatora po stronie debugera, należy utworzyć klasę dziedziczącą po DialogDebuggerVisualizer, i nadpisać metodę Microsoft.VisualStudio.DebuggerVisualizers.DialogDebuggerVisualizer.Show w celu wyświetlenia interfejsu. Za pomocą IDialogVisualizerService funkcji wizualizatora można wyświetlać formularze, okna dialogowe i kontrolki systemu Windows.

  1. Użyj IVisualizerObjectProvider metod , aby uzyskać wizualizowany obiekt po stronie debugera.

  2. Utwórz klasę, która dziedziczy po DialogDebuggerVisualizer.

Uwaga / Notatka

Ze względu na problemy z zabezpieczeniami opisane w poniższej sekcji, począwszy od programu Visual Studio 2022 w wersji 17.11, wizualizatorzy nie będą mogli określić Legacy zasad formatatora w konstruktorze klasy bazowej. Od tej pory wizualizatory mogą używać tylko serializacji JSON do komunikowania się między składnikami debugera i po stronie debuggee.

  1. Zastąp metodę Microsoft.VisualStudio.DebuggerVisualizers.DialogDebuggerVisualizer.Show, aby wyświetlić interfejs. Użyj IDialogVisualizerService metod do wyświetlania formularzy, okien dialogowych i kontrolek systemu Windows w interfejsie.

  2. Zastosuj DebuggerVisualizerAttributeelement , nadając mu wizualizator do wyświetlania (DialogDebuggerVisualizer).

Specjalne zagadnienia dotyczące strony debugera dla platformy .NET 5.0 lub nowszej

Niestandardowe wizualizatory przesyłają dane między stroną debugowanej aplikacji a stroną debugera poprzez serializację binarną, używając domyślnie klasy BinaryFormatter. Jednak ten rodzaj serializacji jest ograniczany na platformie .NET 5 i nowszych ze względu na obawy związane z bezpieczeństwem dotyczące nienaprawialnych luk w zabezpieczeniach. Ponadto została oznaczona jako całkowicie przestarzała w ASP.NET Core 5, a jej użycie będzie zgłaszane zgodnie z opisem w dokumentacji ASP.NET Core. W tej sekcji opisano kroki, które należy wykonać, aby upewnić się, że wizualizator jest nadal obsługiwany w tym scenariuszu.

  • Ze względów zgodności metoda, która została omówiona w poprzedniej sekcji, nadal przyjmuje element IVisualizerObjectProvider. Jednak począwszy od programu Visual Studio 2019 w wersji 16.10, jest to faktycznie typ IVisualizerObjectProvider3. Z tego powodu oddaj objectProvider obiekt do zaktualizowanego interfejsu.

  • Podczas wysyłania obiektów, takich jak polecenia lub dane, do strony debuggee, użyj metody IVisualizerObjectProvider2.Serialize, aby przekazać je do strumienia; określi najlepszy format serializacji do użycia na podstawie środowiska uruchomieniowego procesu debugowanego. Następnie przekaż strumień do metody IVisualizerObjectProvider2.TransferData.

  • Jeśli składnik wizualizatora po stronie debugowanego musi zwrócić jakąkolwiek wartość do strony debuggera, zostanie ona umieszczona w obiekcie Stream zwróconym przez metodę TransferData. Użyj metody IVisualizerObjectProvider2.GetDeserializableObjectFrom , aby pobrać wystąpienie z IDeserializableObject i przetworzyć je zgodnie z potrzebami; lub użyj DeserializeFromJson, jeśli jest to typ, który potrafisz deserializować.

Proszę zapoznaj się z sekcją Specjalne uwagi dla procesu debugowania po stronie platformy .NET 5.0+, aby dowiedzieć się, jakie inne zmiany są wymagane po stronie debuggee, gdy serializacja binarna nie jest obsługiwana.

Uwaga / Notatka

Jeśli chcesz uzyskać więcej informacji na temat problemu, zobacz Przewodnik zabezpieczeń BinaryFormatter.

Utwórz źródło obiektu wizualizatora dla strony debugowanej

W kodzie po stronie debugera zmodyfikuj DebuggerVisualizerAttribute, przypisując mu typ do wizualizacji (źródło obiektu po stronie debuggowanego) (VisualizerObjectSource). Właściwość Target ustawia źródło obiektu. Jeśli pominięto źródło obiektu, wizualizator użyje domyślnego źródła obiektu.

Kod boczny debuggee zawiera źródło obiektu, które jest wizualizowane. Obiekt danych może zastąpić metody VisualizerObjectSource. Biblioteka DLL po stronie debugowania jest niezbędna, jeśli chcesz utworzyć autonomiczny wizualizator.

W kodzie po stronie debugowania:

  • Aby umożliwić wizualizatorowi edytowanie obiektów danych, źródło obiektu musi dziedziczyć po VisualizerObjectSource i nadpisywać metody TransferData lub CreateReplacementObject.

  • Jeśli musisz obsługiwać wiele środowisk docelowych w wizualizatorze, możesz użyć następujących identyfikatorów Target Framework Monikers (TFMs) w pliku projektu debugowanego.

    <TargetFrameworks>net20;netstandard2.0;netcoreapp2.0</TargetFrameworks>

    Są to jedyne obsługiwane maszyny TFM.

Specjalne zagadnienia dotyczące strony debugowania dla platformy .NET 5.0 lub nowszej

Ważne

Aby wizualizator działał w środowisku .NET 5.0, może być konieczne wykonanie dodatkowych kroków ze względu na obawy dotyczące zabezpieczeń podstawowej metody serializacji binarnej używanej domyślnie. Przed kontynuowaniem przeczytaj tę sekcję .

  • Jeśli wizualizator implementuje metodę TransferData , użyj nowo dodanej GetDeserializableObject metody, która jest dostępna w najnowszej wersji programu VisualizerObjectSource. Zwracana wartość IDeserializableObject pomaga określić format serializacji obiektu (binarny lub JSON) i zdeserializować leżący u podstaw obiekt, aby mógł być używany.

  • Jeśli strona debugowanej aplikacji zwraca dane do strony debugera w ramach wywołania TransferData, zserializuj odpowiedź do strumienia strony debugera za pomocą metody Serialize.

Treści powiązane