Visual Studio hata ayıklayıcısı görselleştiricileri oluşturma

Hata ayıklayıcı görselleştiricileri, hata ayıklama oturumu sırasında belirli bir .NET türüne ait değişkenler veya nesneler için özel görselleştirme sağlayan bir Visual Studio özelliğidir.

Hata ayıklayıcısı görselleştiricilerine bir değişkenin üzerine gelindiğinde görüntülenen Veri İpucu'ndan veya OtomatikLer, Yerel öğeler ve İzleme pencerelerinden erişilebilir:

İzleme penceresindeki hata ayıklayıcı görselleştiricilerin ekran görüntüsü.

Get started

Başlarken bölümündeki Uzantı projesini oluşturma bölümünü izleyin.

Ardından, DebuggerVisualizerProvider genişleten bir sınıf ekleyin ve VisualStudioContribution özniteliğini uygulayın:

/// <summary>
/// Debugger visualizer provider class for <see cref="System.String"/>.
/// </summary>
[VisualStudioContribution]
internal class StringDebuggerVisualizerProvider : DebuggerVisualizerProvider
{
    /// <summary>
    /// Initializes a new instance of the <see cref="StringDebuggerVisualizerProvider"/> class.
    /// </summary>
    /// <param name="extension">Extension instance.</param>
    /// <param name="extensibility">Extensibility object.</param>
    public StringDebuggerVisualizerProvider(StringDebuggerVisualizerExtension extension, VisualStudioExtensibility extensibility)
        : base(extension, extensibility)
    {
    }

    /// <inheritdoc/>
    public override DebuggerVisualizerProviderConfiguration DebuggerVisualizerProviderConfiguration => new("My string visualizer", typeof(string));

    /// <inheritdoc/>
    public override async Task<IRemoteUserControl> CreateVisualizerAsync(VisualizerTarget visualizerTarget, CancellationToken cancellationToken)
    {
        string targetObjectValue = await visualizerTarget.ObjectSource.RequestDataAsync<string>(jsonSerializer: null, cancellationToken);

        return new MyStringVisualizerControl(targetObjectValue);
    }
}

Önceki kod, türündeki stringnesnelere uygulanan yeni bir hata ayıklayıcısı görselleştiricisi tanımlar:

DebuggerVisualizerProviderConfiguration özelliği, görselleştirici adını ve desteklenen .NET türünü tanımlar.
Kullanıcı CreateVisualizerAsync belirli bir değer için hata ayıklayıcı görselleştiricisinin görüntülenmesini istediğinde yöntemi Visual Studio tarafından çağrılır. CreateVisualizerAsync görselleştirilecek değeri almak için VisualizerTarget nesnesini kullanır ve bu değeri özel bir uzak kullanıcı denetimine iletir (Remote UI belgelerine başvurun). Daha sonra uzak kullanıcı denetimi döndürülür ve Visual Studio'daki bir açılır pencerede gösterilir.

Birden çok türü hedefleme

yapılandırma özelliği, görselleştiricinin uygun olduğunda birden çok türü hedeflemesine olanak tanır. Bu, DataSet Görselleştiricisi'nin, DataSet, DataTable, DataView ve DataViewManager nesnelerinin görselleştirmesini desteklemesiyle mükemmel bir örnektir. Benzer türler aynı kullanıcı arabirimini, görüntüleme modellerini ve görselleştirici nesne kaynağını paylaşabildiğinden bu özellik uzantı geliştirmeyi kolaylaştırır.

    /// <inheritdoc/>
    public override DebuggerVisualizerProviderConfiguration DebuggerVisualizerProviderConfiguration => new DebuggerVisualizerProviderConfiguration(
        new VisualizerTargetType("DataSet Visualizer", typeof(System.Data.DataSet)),
        new VisualizerTargetType("DataTable Visualizer", typeof(System.Data.DataTable)),
        new VisualizerTargetType("DataView Visualizer", typeof(System.Data.DataView)),
        new VisualizerTargetType("DataViewManager Visualizer", typeof(System.Data.DataViewManager)));

    /// <inheritdoc/>
    public override async Task<IRemoteUserControl> CreateVisualizerAsync(VisualizerTarget visualizerTarget, CancellationToken cancellationToken)
    {
        ...
    }

Görselleştirici nesne kaynağı

Görselleştirici nesne kaynağı, hata ayıklanırken hata ayıklayıcı tarafından yüklenen bir .NET sınıfıdır. Ayıklayıcı görselleştirici, VisualizerTarget.ObjectSource tarafından sağlanan yöntemleri kullanarak görselleştirici nesne kaynağından veri alabilir.

Varsayılan görselleştirici nesne kaynağı, hata ayıklayıcı görselleştiricilerinin RequestDataAsync<T>(JsonSerializer?, CancellationToken) yöntemini çağırarak görselleştirilecek nesnenin değerini almasına olanak tanır. Varsayılan görselleştirici nesne kaynağı, değeri seri hale getirmek için Newtonsoft.Json kullanır ve VisualStudio.Extensibility kitaplıkları da seri durumdan çıkarmak için Newtonsoft.Json kullanır. Alternatif olarak, RequestDataAsync(CancellationToken) kullanarak serileştirilmiş değeri JToken olarak alabilirsiniz.

Newtonsoft.Json tarafından yerel olarak desteklenen bir .NET türünü görselleştirmek veya kendi türünüzü görselleştirmek ve serileştirilebilir hale getirmek istiyorsanız, önceki yönergeler basit bir hata ayıklayıcı görselleştiricisi oluşturmak için yeterlidir. Daha karmaşık türleri desteklemek veya daha gelişmiş özellikler kullanmak istiyorsanız okumaya devam edin.

Özel görselleştirici nesne kaynağı kullanma

Görselleştirilecek tür Newtonsoft.Json tarafından otomatik olarak serileştirilemiyorsa, serileştirmeyi işlemek için özel bir görselleştirici nesne kaynağı oluşturabilirsiniz.

Yeni bir .NET sınıf kitaplığı projesi oluşturun, hedef netstandard2.0. Görselleştirilecek nesneyi seri hale getirmek için gerekirse daha belirli bir .NET Framework veya .NET sürümünü (örneğin, net472 veya net6.0) hedefleyebilirsiniz.
17.6 veya daha yeni bir sürüm için DebuggerVisualizers paket bağlantısı ekleyin.
VisualizerObjectSource sınıfını genişletin ve target serileştirilmiş değerini outgoingData akışına yazarak GetData geçersiz kılın.

public class MyObjectSource : VisualizerObjectSource
{
    /// <inheritdoc/>
    public override void GetData(object target, Stream outgoingData)
    {
        MySerializableType result = Convert(match);
        SerializeAsJson(outgoingData, result);
    }

    private static MySerializableType Convert(object target)
    {
        // Add your code here to convert target into a type serializable by Newtonsoft.Json
        ...
    }
}

Özel serileştirme kullanma

Newtonsoft.Json kullanarak kütüphanenize Newtonsoft.Json başvurusu eklemeden bir nesneyi VisualizerObjectSource.SerializeAsJson olarak serileştirmek için Stream yöntemini kullanabilirsiniz. SerializeAsJson çağırmak, yansıma kullanarak, hata ayıklanan işleme Newtonsoft.Json derlemesinin bir sürümünü yükler.

Newtonsoft.Json'a başvurmanız gerekiyorsa, paket tarafından başvurulan aynı sürümü kullanmanız gerekir, ancak Newtonsoft.Json türlerine güvenmek yerine, nesne serileştirmeyi desteklemek için DataContract ve DataMember özniteliklerini kullanmanız tercih edilir.

Alternatif olarak, outgoingData'ye doğrudan yazarak kendi özel serileştirme işleminizi (örneğin, ikili serileştirme) uygulayabilirsiniz.

Uzantıya görselleştirici nesne kaynağı DLL'sini ekleme

Görselleştirici nesne kaynak kitaplığı projesine ekleyerek uzantı dosyasını değiştirin. Bu, uzantı paketlenmeden önce görselleştirici nesne kaynak kitaplığının derlendiğinden emin olur.

Ayrıca uzantının alt klasörüne görselleştirici nesne kaynak kitaplığı DLL'sini Content içeren bir netstandard2.0 öğe ekleyin.

  <ItemGroup>
    <Content Include="pathToTheObjectSourceDllBinPath\$(Configuration)\netstandard2.0\MyObjectSourceLibrary.dll" Link="netstandard2.0\MyObjectSourceLibrary.dll">
      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
    </Content>
  </ItemGroup>

  <ItemGroup>
    <ProjectReference Include="..\MyObjectSourceLibrary\MyObjectSourceLibrary.csproj" />
  </ItemGroup>

Alternatif olarak, .NET Framework veya .NET'i hedefleyen görselleştirici nesne kaynak kitaplığını derlediyseniz net4.6.2 veya netcoreapp alt klasörlerini kullanabilirsiniz. Görselleştirici nesne kaynak kitaplığının farklı sürümlerine sahip üç alt klasörü de ekleyebilirsiniz, ancak yalnızca netstandard2.0 hedeflemek daha iyi olur.

Görselleştirici nesne kaynak kitaplığı DLL'sinin bağımlılık sayısını en aza indirmeyi denemelisiniz. Görselleştirici nesne kaynak kitaplığınızda microsoft.VisualStudio.DebuggerVisualizers dışında bağımlılıklar varsa ve zaten hata ayıklanan işlemde yüklenmesi garanti edilen kitaplıklar varsa, bu DLL dosyalarını görselleştirici nesne kaynak kitaplığı DLL'si ile aynı alt klasöre de eklediğinizden emin olun.

Özel görselleştirici nesne kaynağını kullanmak için hata ayıklayıcı görselleştirici sağlayıcısını güncelleştirin

Ardından özel görselleştirici nesne kaynağınıza başvurmak için yapılandırmanızı DebuggerVisualizerProvider güncelleştirebilirsiniz:

    public override DebuggerVisualizerProviderConfiguration DebuggerVisualizerProviderConfiguration => new("My visualizer", typeof(TypeToVisualize))
    {
        VisualizerObjectSourceType = new(typeof(MyObjectSource)),
    };

    public override async Task<IRemoteUserControl> CreateVisualizerAsync(VisualizerTarget visualizerTarget, CancellationToken cancellationToken)
    {
        MySerializableType result = await visualizerTarget.ObjectSource.RequestDataAsync<MySerializableType>(jsonSerializer: null, cancellationToken);
        return new MyVisualizerUserControl(result);
    }

Büyük ve karmaşık nesnelerle çalışma

Görselleştirici nesne kaynağından veri alma işlemi tek bir parametresiz çağrısıyla RequestDataAsyncyapılamıyorsa, bunun yerine birden çok kez çağırıp RequestDataAsync<TMessage, TResponse>(TMessage, JsonSerializer?, CancellationToken) görselleştirici nesne kaynağına farklı iletiler göndererek görselleştirici nesne kaynağıyla daha karmaşık bir ileti değişimi gerçekleştirebilirsiniz. hem ileti hem de yanıt, Newtonsoft.Json kullanılarak VisualStudio.Genişletilebilirlik altyapısı tarafından serileştirilir. RequestDataAsync diğer geçersiz kılmaları, JToken nesneleri kullanmanıza veya özel serileştirme ve seri durumdan çıkarmayı gerçekleştirmenize olanak sağlar.

Görselleştirici nesne kaynağından bilgi almak için farklı iletiler kullanarak herhangi bir özel protokolü uygulayabilirsiniz. Bu özelliğin en yaygın kullanım örneği, büyük olabilecek bir nesnenin alınmasını zaman aşımını önlemek için birden çok çağrıya bölmektir.

Büyük olabilecek bir koleksiyonun içeriğine teker teker nasıl erişebileceğinizi gösteren bir örnek:

for (int i = 0; ; i++)
{
    MySerializableType? collectionEntry = await visualizerTarget.ObjectSource.RequestDataAsync<int, MySerializableType?>(i, jsonSerializer: null, cancellationToken);
    if (collectionEntry is null)
    {
        break;
    }

    observableCollection.Add(collectionEntry);
}

Yukarıdaki kod, RequestDataAsync çağrıları için mesaj olarak basit bir dizini kullanır. Karşılık gelen görselleştirici nesne kaynak kodu, GetData yerine TransferData yöntemini geçersiz kılar.

public class MyCollectionTypeObjectSource : VisualizerObjectSource
{
    public override void TransferData(object target, Stream incomingData, Stream outgoingData)
    {
        var index = (int)DeserializeFromJson(incomingData, typeof(int))!;

        if (target is MyCollectionType collection && index < collection.Count)
        {
            var result = Convert(collection[index]);
            SerializeAsJson(outgoingData, result);
        }
        else
        {
            SerializeAsJson(outgoingData, null);
        }
    }

    private static MySerializableType Convert(object target)
    {
        // Add your code here to convert target into a type serializable by Newtonsoft.Json
        ...
    }
}

Yukarıdaki görselleştirici nesnesinin kaynağı, görselleştirici sağlayıcısı tarafından gönderilen iletiyi seri durumdan çıkarmak için VisualizerObjectSource.DeserializeFromJson yönteminden yararlanır.incomingData

Görselleştirici nesne kaynağı ile karmaşık mesaj etkileşimini gerçekleştiren bir hata ayıklayıcı görselleştirici sağlayıcısını uygularken, mesaj alışverişinin kontrol yüklenirken zaman uyumsuz olarak gerçekleşebilmesi için VisualizerTarget’yi görselleştiricinin RemoteUserControl’sine geçirmek genellikle daha iyidir. Geçiş VisualizerTarget ayrıca, kullanıcının görselleştiricinin kullanıcı arabirimiyle etkileşimlerine dayanarak verileri almak için görselleştirici nesne kaynağına mesaj göndermenize olanak tanır.

public override Task<IRemoteUserControl> CreateVisualizerAsync(VisualizerTarget visualizerTarget, CancellationToken cancellationToken)
{
    return Task.FromResult<IRemoteUserControl>(new MyVisualizerUserControl(visualizerTarget));
}

internal class MyVisualizerUserControl : RemoteUserControl
{
    private readonly VisualizerTarget visualizerTarget;

    public MyVisualizerUserControl(VisualizerTarget visualizerTarget)
        : base(new MyDataContext())
    {
        this.visualizerTarget = visualizerTarget;
    }

    public override async Task ControlLoadedAsync(CancellationToken cancellationToken)
    {
        // Start querying the VisualizerTarget here
        ...
    }
    ...

Görselleştiricileri Araç Pencereleri olarak açma

Varsayılan olarak, tüm hata ayıklayıcı görselleştirici uzantıları Visual Studio'nun ön planında mod pencereleri olarak açılır. Bu nedenle, kullanıcı IDE ile etkileşime devam etmek istiyorsa görselleştiricinin kapatılması gerekir. Ancak Style özelliği ToolWindow olarak DebuggerVisualizerProviderConfiguration özelliğinde ayarlanırsa, görselleştirici, hata ayıklama oturumunun geri kalanı sırasında açık kalabilen modal olmayan bir araç penceresi olarak açılır. Hiçbir stil bildirilmemişse, varsayılan değer ModalDialog kullanılır.

    public override DebuggerVisualizerProviderConfiguration DebuggerVisualizerProviderConfiguration => new("My visualizer", typeof(TypeToVisualize))
    {
        Style = VisualizerStyle.ToolWindow
    };

    public override async Task<IRemoteUserControl> CreateVisualizerAsync(VisualizerTarget visualizerTarget, CancellationToken cancellationToken)
    {
        // The control will be in charge of calling the RequestDataAsync method from the visualizer object source and disposing of the visualizer target.
        return new MyVisualizerUserControl(visualizerTarget);
    }

Bir görselleştirici ToolWindow olarak açılmayı tercih ettiğinde, VisualizerTarget öğesinin StateChanged olayına abone olması gerekir. Görselleştirici bir araç penceresi halinde açıldığında, kullanıcının hata ayıklama oturumunu devam ettirmesini engellemez. Bu nedenle, hata ayıklama hedefinin durumu her değiştiğinde, yukarıda belirtilen olay hata ayıklayıcı tarafından tetiklenir. Görselleştirici hedefi yalnızca hata ayıklama oturumu etkin olduğunda ve hata ayıklama hedefi duraklatıldığında kullanılabildiğinden, görselleştirici uzantısı yazarlarının bu bildirimlere özellikle dikkat etmesi gerekir. Görselleştirici hedefi kullanılabilir olmadığında, ObjectSource yöntemlerine yapılan çağrılar VisualizerTargetUnavailableException ile başarısız olur.

internal class MyVisualizerUserControl : RemoteUserControl
{
    private readonly VisualizerDataContext dataContext;

#pragma warning disable CA2000 // Dispose objects before losing scope
    public MyVisualizerUserControl(VisualizerTarget visualizerTarget)
        : base(dataContext: new VisualizerDataContext(visualizerTarget))
#pragma warning restore CA2000 // Dispose objects before losing scope
    {
        this.dataContext = (VisualizerDataContext)this.DataContext!;
    }

    protected override void Dispose(bool disposing)
    {
        if (disposing)
        {
            this.dataContext.Dispose();
        }
    }

    [DataContract]
    private class VisualizerDataContext : NotifyPropertyChangedObject, IDisposable
    {
        private readonly VisualizerTarget visualizerTarget;
        private MySerializableType? _value;
        
        public VisualizerDataContext(VisualizerTarget visualizerTarget)
        {
            this.visualizerTarget = visualizerTarget;
            visualizerTarget.StateChanged += this.OnStateChangedAsync;
        }

        [DataMember]
        public MySerializableType? Value
        {
            get => this._value;
            set => this.SetProperty(ref this._value, value);
        }

        public void Dispose()
        {
            this.visualizerTarget.Dispose();
        }

        private async Task OnStateChangedAsync(object? sender, VisualizerTargetStateNotification args)
        {
            switch (args)
            {
                case VisualizerTargetStateNotification.Available:
                case VisualizerTargetStateNotification.ValueUpdated:
                    Value = await visualizerTarget.ObjectSource.RequestDataAsync<MySerializableType>(jsonSerializer: null, CancellationToken.None);
                    break;
                case VisualizerTargetStateNotification.Unavailable:
                    Value = null;
                    break;
                default:
                    throw new NotSupportedException("Unexpected visualizer target state notification");
            }
        }
    }
}

Bildirim Available oluşturulduktan sonra RemoteUserControl ve yeni oluşturulan görselleştirici araç penceresinde görünür hale getirilmeden hemen önce alınır. Görselleştirici açık kaldığı sürece, hata ayıklama hedefi durumunu her değiştirişinde diğer VisualizerTargetStateNotification değerler alınabilir. Bildirim ValueUpdated , görselleştirici tarafından açılan son ifadenin hata ayıklayıcının durduğu yerde başarıyla yeniden değerlendirildiğini ve kullanıcı arabirimi tarafından yenilenmesi gerektiğini belirtmek için kullanılır. Öte yandan, hata ayıklama hedefi devam ettirildiğinde veya durduktan sonra ifade yeniden değerlendirilemediğinde Unavailable bildirimi alınacaktır.

Görselleştirilmiş nesne değerini güncelleştirme

VisualizerTarget.IsTargetReplaceable doğru ise, hata ayıklayıcı görselleştiricisi, hata ayıklanan işlemde görselleştirilmiş nesnenin değerini güncelleştirmek için bu yöntemi ReplaceTargetObjectAsync kullanabilir.

Görselleştirici kaynağı CreateReplacementObject yöntemini geçersiz kılmalıdır.

public override object CreateReplacementObject(object target, Stream incomingData)
{
    // Use DeserializeFromJson to read from incomingData
    // the new value of the object being visualized
    ...
    return newValue;
}

RegexMatchDebugVisualizer Bu teknikleri çalışırken görmek için örneği deneyin.

Last updated on 2025-10-31

Aracılığıyla paylaş