no italics except on definition

This commit is contained in:
Gordon Hogenson 2023-03-23 16:30:28 -07:00
Родитель be2fa4e08f
Коммит f0d74dc2b5
1 изменённых файлов: 14 добавлений и 14 удалений

Просмотреть файл

@ -55,15 +55,15 @@ The previous code defines a new debugger visualizer which applies to objects of
## The visualizer object source
The *visualizer object source* is a .NET class that is loaded by the debugger in the process being debugged. The debugger visualizer can retrieve data from the *visualizer object source* using methods exposed by `VisualizerTarget.ObjectSource`.
The *visualizer object source* is a .NET class that is loaded by the debugger in the process being debugged. The debugger visualizer can retrieve data from the visualizer object source using methods exposed by `VisualizerTarget.ObjectSource`.
The default *visualizer object source* allows debugger visualizers to retrieve the value of the object to be visualized by calling the [`RequestDataAsync<T>(JsonSerializer?, CancellationToken)`](../../api/Microsoft.VisualStudio.Extensibility.md#M-Microsoft-VisualStudio-Extensibility-DebuggerVisualizers-VisualizerObjectSourceClient-RequestDataAsync``1-Newtonsoft-Json-JsonSerializer,System-Threading-CancellationToken-) method. The default *visualizer object source* uses [Newtonsoft.Json](https://www.nuget.org/packages/Newtonsoft.Json) to serialize the value, and the VisualStudio.Extensibility libraries also use Newtonsoft.Json for the deserialization. Alternatively you can use [`RequestDataAsync(CancellationToken)`](../../api/Microsoft.VisualStudio.Extensibility.md#M-Microsoft-VisualStudio-Extensibility-DebuggerVisualizers-VisualizerObjectSourceClient-RequestDataAsync-System-Threading-CancellationToken-) to retrieve the serialized value as a `JToken`.
The default visualizer object source allows debugger visualizers to retrieve the value of the object to be visualized by calling the [`RequestDataAsync<T>(JsonSerializer?, CancellationToken)`](../../api/Microsoft.VisualStudio.Extensibility.md#M-Microsoft-VisualStudio-Extensibility-DebuggerVisualizers-VisualizerObjectSourceClient-RequestDataAsync``1-Newtonsoft-Json-JsonSerializer,System-Threading-CancellationToken-) method. The default visualizer object source uses [Newtonsoft.Json](https://www.nuget.org/packages/Newtonsoft.Json) to serialize the value, and the VisualStudio.Extensibility libraries also use Newtonsoft.Json for the deserialization. Alternatively you can use [`RequestDataAsync(CancellationToken)`](../../api/Microsoft.VisualStudio.Extensibility.md#M-Microsoft-VisualStudio-Extensibility-DebuggerVisualizers-VisualizerObjectSourceClient-RequestDataAsync-System-Threading-CancellationToken-) to retrieve the serialized value as a `JToken`.
If you want to visualize a .NET type that is natively supported by Newtonsoft.Json, or you want to visualize your own type and you can make it serializable, the instructions above are sufficient to create a simple debugger visualizer. Read on if you want to support more complex types or to leverage more advanced features.
## Use a custom visualizer object source
If the type to be visualized cannot be automatically serialized by Newtonsoft.Json, you can create a custom *visualizer object source* to handle the serialization.
If the type to be visualized cannot be automatically serialized by Newtonsoft.Json, you can create a custom visualizer object source to handle the serialization.
- Create a new .NET class library project targeting `netstandard2.0`. You can target a more specific version of .NET Framework or .NET (E.g, `net472` or `net6.0`) if necessary to serialize the object to be visualized.
- Add a package reference to [Microsoft.VisualStudio.DebuggerVisualizers](https://www.nuget.org/packages/Microsoft.VisualStudio.DebuggerVisualizers) version 17.6 or newer.
@ -97,9 +97,9 @@ Alternatively, you can implement your own custom serialization (such as binary s
### Add the visualizer object source DLL to the extension
Modify the extension *.csproj* file adding a `ProjectReference` to the *visualizer object source* library project, which makes sure that the *visualizer object source* library is built before the extension is packaged.
Modify the extension *.csproj* file adding a `ProjectReference` to the visualizer object source library project, which makes sure that the visualizer object source library is built before the extension is packaged.
Also add a `Content` item including the *visualizer object source* library DLL into the `netstandard2.0` subfolder of the extension.
Also add a `Content` item including the visualizer object source library DLL into the `netstandard2.0` subfolder of the extension.
```xml
<ItemGroup>
@ -113,13 +113,13 @@ Also add a `Content` item including the *visualizer object source* library DLL i
</ItemGroup>
```
Alternatively, you can use the `net4.6.2` or `netcoreapp` subfolders if you built the *visualizer object source* library targeting .NET Framework or .NET. You can even include all three subfolders with different versions of the *visualizer object source* library, but it's better to target `netstandard2.0` only.
Alternatively, you can use the `net4.6.2` or `netcoreapp` subfolders if you built the visualizer object source library targeting .NET Framework or .NET. You can even include all three subfolders with different versions of the visualizer object source library, but it's better to target `netstandard2.0` only.
You should try to minimize the number of dependencies of the *visualizer object source* library DLL. If your *visualizer object source* library has dependencies other than [Microsoft.VisualStudio.DebuggerVisualizers](https://www.nuget.org/packages/Microsoft.VisualStudio.DebuggerVisualizers) and libraries already guaranteed to be loaded in the process being debugged, make sure to also include those DLL files into the same subfolder as the *visualizer object source* library DLL.
You should try to minimize the number of dependencies of the visualizer object source library DLL. If your visualizer object source library has dependencies other than [Microsoft.VisualStudio.DebuggerVisualizers](https://www.nuget.org/packages/Microsoft.VisualStudio.DebuggerVisualizers) and libraries already guaranteed to be loaded in the process being debugged, make sure to also include those DLL files into the same subfolder as the visualizer object source library DLL.
### Update the debugger visualizer provider to use the custom visualizer object source
You can then update your `DebuggerVisualizerProviderConfiguration` configuration to reference your custom *visualizer object source*:
You can then update your `DebuggerVisualizerProviderConfiguration` configuration to reference your custom visualizer object source:
```csharp
public override DebuggerVisualizerProviderConfiguration DebuggerVisualizerProviderConfiguration => new("My visualizer", typeof(TypeToVisualize))
@ -136,9 +136,9 @@ You can then update your `DebuggerVisualizerProviderConfiguration` configuration
## Work with large and complex objects
If the retrieval of data from the *visualizer object source* cannot be done with a single parameterless call to `RequestDataAsync`, you can instead perform a more complex message exchange with the *visualizer object source* by invoking [RequestDataAsync<TMessage, TResponse>(TMessage, JsonSerializer?, CancellationToken)](../../api/Microsoft.VisualStudio.Extensibility.md#M-Microsoft-VisualStudio-Extensibility-DebuggerVisualizers-VisualizerObjectSourceClient-RequestDataAsync``2-``0,Newtonsoft-Json-JsonSerializer,System-Threading-CancellationToken-) multiple times and sending different *messages* to the *visualizer object source*. Both the message and response is serialized by the VisualStudio.Extensibility infrastructure using Newtonsoft.Json. Other overrides of `RequestDataAsync` allow you to use `JToken` objects or implement custom serialization and deserialization.
If the retrieval of data from the visualizer object source cannot be done with a single parameterless call to `RequestDataAsync`, you can instead perform a more complex message exchange with the visualizer object source by invoking [RequestDataAsync<TMessage, TResponse>(TMessage, JsonSerializer?, CancellationToken)](../../api/Microsoft.VisualStudio.Extensibility.md#M-Microsoft-VisualStudio-Extensibility-DebuggerVisualizers-VisualizerObjectSourceClient-RequestDataAsync``2-``0,Newtonsoft-Json-JsonSerializer,System-Threading-CancellationToken-) multiple times and sending different *messages* to the visualizer object source. Both the message and response is serialized by the VisualStudio.Extensibility infrastructure using Newtonsoft.Json. Other overrides of `RequestDataAsync` allow you to use `JToken` objects or implement custom serialization and deserialization.
You can implement any custom protocol using different messages to retrieve information from the *visualizer object source*. The most common use case for this feature is breaking the retrieval of a potentially large object into multiple calls to avoid `RequestDataAsync` timing out.
You can implement any custom protocol using different messages to retrieve information from the visualizer object source. The most common use case for this feature is breaking the retrieval of a potentially large object into multiple calls to avoid `RequestDataAsync` timing out.
This is an example of how you can retrieve the content of a potentially large collection one item at a time:
@ -155,7 +155,7 @@ for (int i = 0; ; i++)
}
```
The code above uses a simple index as message for the `RequestDataAsync` calls. The corresponding *visualizer object source* code would override the `TransferData` method (instead of `GetData`):
The code above uses a simple index as message for the `RequestDataAsync` calls. The corresponding visualizer object source code would override the `TransferData` method (instead of `GetData`):
```csharp
public class MyCollectionTypeObjectSource : VisualizerObjectSource
@ -183,9 +183,9 @@ public class MyCollectionTypeObjectSource : VisualizerObjectSource
}
```
The *visualizer object source* above leverages the `VisualizerObjectSource.DeserializeFromJson` method to deserialize the message sent by the visualizer provider from `incomingData`.
The visualizer object source above leverages the `VisualizerObjectSource.DeserializeFromJson` method to deserialize the message sent by the visualizer provider from `incomingData`.
When implementing a debugger visualizer provider that performs complex message interaction with the *visualizer object source*, it's usually better to pass the `VisualizerTarget` to the visualizer's `RemoteUserControl` so that the message exchange can happen asynchronously while the control is loaded. This also allow to send messages to the *visualizer object source* to retrieve data based on the user's interactions with the visualizer's UI.
When implementing a debugger visualizer provider that performs complex message interaction with the visualizer object source, it's usually better to pass the `VisualizerTarget` to the visualizer's `RemoteUserControl` so that the message exchange can happen asynchronously while the control is loaded. This also allow to send messages to the visualizer object source to retrieve data based on the user's interactions with the visualizer's UI.
```csharp
public override Task<IRemoteUserControl> CreateVisualizerAsync(VisualizerTarget visualizerTarget, CancellationToken cancellationToken)
@ -217,7 +217,7 @@ internal class MyVisualizerUserControl : RemoteUserControl
If `VisualizerTarget.IsTargetReplaceable` is true, the debugger visualizer can use the [ReplaceTargetObjectAsync](../../api/Microsoft.VisualStudio.Extensibility.md#M-Microsoft-VisualStudio-Extensibility-DebuggerVisualizers-VisualizerObjectSourceClient-ReplaceTargetObjectAsync``1-``0,Newtonsoft-Json-JsonSerializer,System-Threading-CancellationToken-) method to update the value of the visualized object in the process being debugged.
The *visualizer object source* must override the `CreateReplacementObject` method:
The visualizer object source must override the `CreateReplacementObject` method:
```csharp
public override object CreateReplacementObject(object target, Stream incomingData)