Natvis çerçevesini kullanarak hata ayıklayıcıda C++ nesnelerinin özel görünümlerini oluşturma

Visual Studio Natvis çerçevesi, yerel türlerin Locals ve Watch pencereleri gibi hata ayıklayıcı değişken pencerelerinde ve Veri İpuçları'nde görünme şeklini özelleştirir. Natvis görselleştirmeleri, oluşturduğunuz türleri hata ayıklama sırasında daha görünür hale getirmenize yardımcı olabilir.

Natvis, Visual Studio'nun önceki sürümlerindeki autoexp.dat dosyasını XML söz dizimi, daha iyi tanılama, sürüm oluşturma ve birden çok dosya desteğiyle değiştirir.

Not

Natvis özelleştirmeleri sınıflarla ve yapılarla çalışır, ancak tür tanımlarıyla çalışmaz.

Natvis görselleştirmeleri

Natvis çerçevesini, geliştiricilerin hata ayıklama sırasında bunları daha kolay görebilmesi için oluşturduğunuz türler için görselleştirme kuralları oluşturmak için kullanırsınız.

Örneğin, aşağıdaki çizimde özel görselleştirmeler uygulanmadan hata ayıklayıcı penceresinde türündeki bir değişken gösterilmektedir: Windows::UI::XAML::Controls::TextBox.

TextBox varsayılan görselleştirmeTextBox varsayılan görselleştirmeTextBox default visualizationTextBox default visualization

Vurgulanan satır, Text sınıfının TextBox özelliğini gösterir. Karmaşık sınıf hiyerarşisi bu özelliği bulmayı zorlaştırır. Hata ayıklayıcısı özel dize türünü nasıl yorumlayabileceğinizi bilmediğinden metin kutusunun içinde tutulan dizeyi göremezsiniz.

Aynı TextBox, Natvis özel görselleştirici kuralları uygulandığında değişken penceresinde çok daha basit görünür. Sınıfın önemli üyeleri birlikte görünür ve hata ayıklayıcı özel dize türünün temel dize değerini gösterir.

TextBox verilerini görselleştirici kullanarak görselleştirici kullanarak TextBox verileri

C++ projelerinde .natvis dosyalarını kullanma

Natvis, görselleştirme kurallarını belirtmek için .natvis dosyaları kullanır. .natvis dosyası, .natvis uzantısına sahip bir XML dosyasıdır. Natvis şeması <VS Yükleme Klasörü>\Xml\Schemas\1033\natvis.xsdiçinde tanımlanır.

.natvis dosyasının temel yapısı, görselleştirme girdilerini temsil eden bir veya daha fazla Type öğesidir. Her Type öğesinin tam adı Name özniteliğinde belirtilir.

<?xml version="1.0" encoding="utf-8"?>
<AutoVisualizer xmlns="http://schemas.microsoft.com/vstudio/debugger/natvis/2010">
  <Type Name="MyNamespace::CFoo">
    .
    .
  </Type>

  <Type Name="...">
    .
    .
  </Type>
</AutoVisualizer>

Visual Studio, bazı .natvis dosyalarını <VS Yükleme Klasörü>\Common7\Packages\Debugger\Visualizers klasöründe sağlar. Bu dosyalar birçok yaygın tür için görselleştirme kurallarına sahiptir ve yeni türler için görselleştirme yazmak için örnek olarak kullanılabilir.

C++ projesine .natvis dosyası ekleme

Herhangi bir C++ projesine .natvis dosyası ekleyebilirsiniz.

Yeni bir .natvis dosyası eklemek için:

Çözüm Gezgini'nde C++ proje düğümünü seçin ve Proje>Yeni öğe ekle'yı seçin veya projeye sağ tıklayıp Ekle>Yeni öğe'yi seçin.

Tüm öğe şablonlarını görmüyorsanız Tüm Şablonları Gösterseçin.
Yeni Öğe Ekle iletişim kutusunda Visual C++>Yardımcı Programı>Hata Ayıklayıcısı görselleştirme dosyası (.natvis)öğesini seçin.
Dosyayı adlandırın ve Ekleseçin.

Yeni dosya Çözüm Gezginieklenir ve Visual Studio belge bölmesinde açılır.

Visual Studio hata ayıklayıcısı, C++ projelerinde .natvis dosyalarını otomatik olarak yükler ve varsayılan olarak bunları proje oluşturulduğunda .pdb dosyasına da ekler. Oluşturulan uygulamada hata ayıklarsanız, proje açık olmasa bile hata ayıklayıcı .pdb dosyasından .natvis dosyasını yükler. .natvis dosyasının .pdbeklenmesini istemiyorsanız, bunu yerleşik .pdb dosyasından dışlayabilirsiniz.

Bir .natvis dosyasını .pdbdosyasından hariç tutmak için:

Çözüm Gezgini.natvis dosyasını seçin ve Özellikler simgesini seçin veya dosyaya sağ tıklayıp Özelliklerseçin.
Derlemeden Dışlanan yanındaki açılan oka tıklayın, ardından Evetöğesini ve son olarak da Tamam'ı seçin.

Not

Yürütülebilir projelerde hata ayıklamak için çözüm öğelerini kullanarak .pdb'de bulunmayan tüm .natvis dosyalarını ekleyin, çünkü kullanılabilir C++ projesi yoktur.

Not

.pdb yüklenen Natvis kuralları yalnızca .pdb başvurduğu modüllerdeki türlere uygulanır. Örneğin, module1.pdb Testadlı bir tür için Natvis girdisi varsa, yalnızca Testiçindeki sınıfı için geçerlidir. Başka bir modül de adlı Testbir sınıf tanımlarsa Module1.pdb Natvis girdisi buna uygulanmaz.

VSIX paketi aracılığıyla bir .natvis dosyası yüklemek ve kaydetmek için:

VSIX paketi .natvis dosyalarını yükleyebilir ve kaydedebilir. Nerede yüklendiklerine bakılmaksızın, tüm kayıtlı .natvis dosyaları hata ayıklama sırasında otomatik olarak alınır.

.natvis dosyasını VSIX paketine ekleyin. Örneğin, aşağıdaki proje dosyası için:

<?xml version="1.0" encoding="utf-8"?>
<Project DefaultTargets="Build" xmlns="http://schemas.microsoft.com/developer/msbuild/2003" ToolsVersion="14.0">
  <ItemGroup>
    <VSIXSourceItem Include="Visualizer.natvis" />
  </ItemGroup>
</Project>

.natvis dosyasını source.extension.vsixmanifest dosyasına kaydedin:

<?xml version="1.0" encoding="utf-8"?>
<PackageManifest Version="2.0.0" xmlns="http://schemas.microsoft.com/developer/vsx-schema/2011" xmlns:d="http://schemas.microsoft.com/developer/vsx-schema-design/2011">
  <Assets>
    <Asset Type="NativeVisualizer" Path="Visualizer.natvis"  />
  </Assets>
</PackageManifest>

Natvis dosya konumları

.natvis dosyalarını birden çok proje için geçerli olmasını istiyorsanız, kullanıcı dizininize veya bir sistem dizinine ekleyebilirsiniz.

.natvis dosyaları aşağıdaki sırayla değerlendirilir:

Yüklenen projede aynı adda bir dosya bulunmuyorsa, hata ayıklamakta olduğunuz .pdb dosyasına eklenmiş tüm .natvis dosyaları.
Yüklenen bir C++ projesinde veya üst düzey çözümde bulunan tüm .natvis dosyaları. Bu grup, sınıf kitaplıkları dahil olmak üzere tüm yüklü C++ projelerini içerir, ancak diğer dillerdeki projeleri içermez.
VSIX paketi aracılığıyla yüklenen ve kaydedilen tüm .natvis dosyaları.

Kullanıcıya özgü Natvis dizini (örneğin, \Documents\Visual Studio 2022\Visualizers %USERPROFILE%).

Kullanıcıya özgü Natvis dizini (örneğin, \Documents\Visual Studio 2019\Visualizers %USERPROFILE%).

Sistem genelinde Natvis dizini (<Microsoft Visual Studio Yükleme Klasörü>\Common7\Packages\Debugger\Visualizers). Bu dizin, Visual Studio ile yüklenen .natvis dosyalarına sahiptir. Yönetici izinleriniz varsa bu dizine dosya ekleyebilirsiniz.

Hata ayıklarken .natvis dosyalarını değiştirme

IDE'deki bir .natvis dosyasını projesinde hata ayıklarken değiştirebilirsiniz. Dosyayı hata ayıkladığınız Visual Studio örneğinde açın, değiştirin ve kaydedin. Dosya kaydedilir kaydedilmez, Watch ve Locals pencereleri değişikliği yansıtacak şekilde güncellenir.

Ayrıca hata ayıkladığınız bir çözümde .natvis dosyaları ekleyebilir veya silebilirsiniz ve Visual Studio ilgili görselleştirmeleri ekler veya kaldırır.

Hata ayıklarken .pdb dosyalarına eklenmiş .natvis dosyalarını güncelleştiremezsiniz.

.natvis dosyasını Visual Studio dışında değiştirirseniz, değişiklikler otomatik olarak geçerli olmaz. Hata ayıklayıcı pencerelerini güncelleştirmek için, Anında penceresinde .natvisreload komutunu yeniden değerlendirebilirsiniz. Değişiklikler hata ayıklama oturumunu yeniden başlatmadan geçerlilik kazanır.

ayrıca .natvis dosyasını daha yeni bir sürüme yükseltmek için .natvisreload komutunu kullanın. Örneğin, .natvis dosyası kaynak denetiminde denetlenebilir ve başka birinin yaptığı son değişiklikleri almak isteyebilirsiniz.

İfadeler ve biçimlendirme

Natvis görselleştirmeleri, görüntülenecek veri öğelerini belirtmek için C++ ifadelerini kullanır. hata ayıklayıcıdaki C++ ifadelerinin iyileştirmelerine ve sınırlamalarına ek olarak, Bağlam işleci (C++)'de açıklananlara dikkat edin.

Natvis ifadeleri, geçerli yığın çerçevesi değil görselleştirilen nesne bağlamında değerlendirilir. Örneğin, natvis ifadesindeki x, geçerli işlevdeki x adlı yerel değişkene değil, görselleştirilen nesnedeki x adlı alana başvurur. Natvis ifadelerindeki yerel değişkenlere erişemezsiniz, ancak genel değişkenlere erişebilirsiniz.
Natvis ifadeleri işlev değerlendirmesine veya yan etkilere izin vermez. İşlev çağrıları ve atama işleçleri yoksayılır. hata ayıklayıcı iç işlevleri yan etki içermediğinden, diğer işlev çağrılarına izin verilmese bile herhangi bir Natvis ifadesinden serbestçe çağrılabilir.
İfadenin nasıl görüntüleyebileceğinizi denetlemek için, C++ Biçim tanımlayıcılarında açıklanan biçim tanımlayıcılarından herhangi birini kullanabilirsiniz. Bir girdi Natvis tarafından dahili olarak kullanıldığında, Size ifadesi gibi biçim tanımlayıcıları, ArrayItems genişletmeiçin yoksayılır.

Not

Natvis belgesi XML olduğundan, ifadeleriniz doğrudan büyük, küçük veya vardiya işleçlerini kullanamaz. Hem öğe gövdesinde hem de koşul deyimlerinde bu karakterlerden kaçmalısınız. Mesela:
\<Item Name="HiByte"\>(byte)(_flags \>\> 24),x\</Item\>
\<Item Name="HiByteStatus" Condition="(_flags \& 0xFF000000) == 0"\>"None"\</Item\>
\<Item Name="HiByteStatus" Condition="(_flags \& 0xFF000000) != 0"\>"Some"\</Item\>

Natvis görünümleri

Türleri farklı şekillerde görüntülemek için farklı Natvis görünümleri tanımlayabilirsiniz. Örneğin, aşağıdaki kod parçacığı, std::vector adlı ve simple basitleştirilmiş bir görünümü tanımlayan bir görselleştirme göstermektedir. DisplayString ve ArrayItems öğeleri varsayılan görünümde ve simple görünümünde, [size] ve [capacity] öğeleri ise simple görünümünde gösterilmez.

<Type Name="std::vector&lt;*&gt;">
    <DisplayString>{{ size={_Mylast - _Myfirst} }}</DisplayString>
    <Expand>
        <Item Name="[size]" ExcludeView="simple">_Mylast - _Myfirst</Item>
        <Item Name="[capacity]" ExcludeView="simple">_Myend - _Myfirst</Item>
        <ArrayItems>
            <Size>_Mylast - _Myfirst</Size>
            <ValuePointer>_Myfirst</ValuePointer>
        </ArrayItems>
    </Expand>
</Type>

İzle penceresinde, alternatif bir görünüm belirtmek için ,view biçim tanımlayıcısını kullanın. Basit görünüm vec,view(simple)olarak görünür:

Basit görünüme sahip izleme penceresi

Natvis hataları

Hata ayıklayıcı bir görselleştirme girdisinde hatalarla karşılaştığında, bunları yoksayar. Türü ham biçiminde görüntüler veya başka bir uygun görselleştirme seçer. Natvis tanılama araçlarını, hata ayıklayıcının bir görselleştirme girdisini neden görmezden geldiğini anlamak ve altta yatan söz dizimi ile ayrıştırma hatalarını görmek için kullanabilirsiniz.

Natvis tanılamasını açmak için:

Araçlar>Seçenekleri bölmesini açın ve Tüm Ayarlar>Hata Ayıklama>Genel bölümünü genişletin. Hata Ayıklama>Seçenekleri işlemi, pencereyi aynı bölüme açar.
Çıkış Penceresi>Genel Çıkış Ayarları'nın altında Natvis tanılama iletileri (yalnızca C++) seçeneğini Hata, Uyarı veya Ayrıntılı olarak ayarlayın.

Araçlar>Seçenekleri iletişim kutusunu açın ve Hata Ayıklama>Genel bölümünü genişletin. Hata Ayıklama>Seçenekleri işlemi, iletişim kutusunu aynı bölüme açar.
Çıkış Penceresi>Genel Çıkış Ayarları'nın altında Natvis tanılama iletileri (yalnızca C++) seçeneğini Hata, Uyarı veya Ayrıntılı olarak ayarlayın.
Tamam'ı seçin.

Hatalar Çıktı penceresinde görüntülenir.

Natvis söz dizimi referansı

Natvis dosyasında aşağıdaki öğeler ve öznitelikler kullanılabilir.

AutoVisualizer öğesi

AutoVisualizer öğesi, .natvis dosyasının kök düğümüdür ve ad alanı xmlns: özniteliğini içerir.

<?xml version="1.0" encoding="utf-8"?>
<AutoVisualizer xmlns="http://schemas.microsoft.com/vstudio/debugger/natvis/2010">
.
.
</AutoVisualizer>

AutoVisualizer öğesinde Type, HResult, UIVisualizerve CustomVisualizer alt öğeleri olabilir.

Tip öğesi

Temel bir Type aşağıdaki örneğe benzer:

<Type Name="[fully qualified type name]">
  <DisplayString Condition="[Boolean expression]">[Display value]</DisplayString>
  <Expand>
    ...
  </Expand>
</Type>

Type öğesi aşağıdakileri belirtir:

Görselleştirmenin hangi tür için kullanılması gerekir (Name özniteliği).
Bu türdeki bir nesnenin değeri nasıl görünmelidir (DisplayString öğesi).
Kullanıcı türü bir değişken penceresinde (Expand düğümü) genişlettiğinde türün üyeleri nasıl görünmelidir?

Şablonlu sınıflar

Name öğesinin Type özniteliği, şablonlu sınıf adları için kullanılabilecek joker karakter olarak yıldız işareti * kabul eder.

Aşağıdaki örnekte, nesne bir CAtlArray<int> veya CAtlArray<float>olsa da aynı görselleştirme kullanılır. Eğer bir CAtlArray<float>için belirli bir görselleştirme girişi varsa, bu, genel olana göre önceliklidir.

<Type Name="ATL::CAtlArray&lt;*&gt;">
    <DisplayString>{{Count = {m_nSize}}}</DisplayString>
</Type>

$T 1, $T 2 vb. makroları kullanarak görselleştirme girdisindeki şablon parametrelerine başvurabilirsiniz. Bu makroların örneklerini bulmak için Visual Studio ile birlikte gelen .natvis dosyalarına bakın.

Görselleştirici türü eşleştirme

Görselleştirme girdisi doğrulanamıyorsa, bir sonraki kullanılabilir görselleştirme kullanılır.

Devralınabilir öznitelik

İsteğe bağlı Inheritable özniteliği, görselleştirmenin yalnızca bir temel türe mi yoksa temel türe ve türetilmiş tüm türlere mi uygulandığını belirtir. Inheritable varsayılan değeri truedeğeridir.

Aşağıdaki örnekte görselleştirme yalnızca BaseClass türü için geçerlidir:

<Type Name="Namespace::BaseClass" Inheritable="false">
    <DisplayString>{{Count = {m_nSize}}}</DisplayString>
</Type>

Öncelik özniteliği

İsteğe bağlı Priority özniteliği, bir tanım ayrıştırılamazsa alternatif tanımların hangi sırada kullanılacağını belirtir. Priority olası değerleri şunlardır: Low, MediumLow,Medium, MediumHighve High. Varsayılan değer Medium. Priority özniteliği yalnızca aynı .natvis dosyasındaki öncelikleri birbirinden ayırır.

Aşağıdaki örnek ilk olarak 2015 STL ile eşleşen girişi ayrıştırmaktadır. Bu ayrıştırılamazsa, STL'nin 2013 sürümü için alternatif girişi kullanır:

<!-- VC 2013 -->
<Type Name="std::reference_wrapper&lt;*&gt;" Priority="MediumLow">
     <DisplayString>{_Callee}</DisplayString>
    <Expand>
        <ExpandedItem>_Callee</ExpandedItem>
    </Expand>
</Type>

<!-- VC 2015 -->
<Type Name="std::reference_wrapper&lt;*&gt;">
    <DisplayString>{*_Ptr}</DisplayString>
    <Expand>
        <Item Name="[ptr]">_Ptr</Item>
    </Expand>
</Type>

İsteğe bağlı öznitelik

Herhangi bir düğüme Optional özniteliği koyabilirsiniz. İsteğe bağlı bir düğüm içindeki bir alt ifade ayrıştırılamazsa, hata ayıklayıcı bu düğümü yoksayar, ancak Type kurallarının geri kalanını uygular. Aşağıdaki türdeki [State] isteğe bağlı değildir, ancak [Exception] isteğe bağlıdır. MyNamespace::MyClass _M_exceptionHolderadlı bir alana sahipse hem [State] düğümü hem de [Exception] düğümü görüntülenir, ancak _M_exceptionHolder alanı yoksa yalnızca [State] düğümü görüntülenir.

<Type Name="MyNamespace::MyClass">
    <Expand>
      <Item Name="[State]">_M_State</Item>
      <Item Name="[Exception]" Optional="true">_M_exceptionHolder</Item>
    </Expand>
</Type>

Condition özniteliği

İsteğe bağlı Condition özniteliği birçok görselleştirme öğesi için kullanılabilir ve görselleştirme kuralının ne zaman kullanılacağını belirtir. condition özniteliği içindeki ifade falseolarak çözümlanırsa görselleştirme kuralı geçerli değildir. değerlendirme true ise veya Condition özniteliği yoksa, görselleştirme uygulanır. Görselleştirme girişlerindeki if-else mantığı için bu özniteliği kullanabilirsiniz.

Örneğin, aşağıdaki görselleştirmede akıllı işaretçi türü için iki DisplayString öğesi vardır. _Myptr üyesi boş olduğunda, formun görüntülenmesi için ilk DisplayString öğesinin koşulu trueolarak çözülür. _Myptr üye boş olmadığında, koşulun sonucu olarak false olarak değerlendirilir ve ikinci DisplayString öğe görüntülenir.

<Type Name="std::auto_ptr&lt;*&gt;">
  <DisplayString Condition="_Myptr == 0">empty</DisplayString>
  <DisplayString>auto_ptr {*_Myptr}</DisplayString>
  <Expand>
    <ExpandedItem>_Myptr</ExpandedItem>
  </Expand>
</Type>

IncludeView ve ExcludeView öznitelikleri

IncludeView ve ExcludeView öznitelikleri, belirli görünümlerde görüntülenecek veya görüntülenmeyen öğeleri belirtir. Örneğin, aşağıdaki std::vectorNatvis belirtiminde simple görünümü [size] ve [capacity] öğelerini görüntülemez.

<Type Name="std::vector&lt;*&gt;">
    <DisplayString>{{ size={_Mylast - _Myfirst} }}</DisplayString>
    <Expand>
        <Item Name="[size]" ExcludeView="simple">_Mylast - _Myfirst</Item>
        <Item Name="[capacity]" ExcludeView="simple">_Myend - _Myfirst</Item>
        <ArrayItems>
            <Size>_Mylast - _Myfirst</Size>
            <ValuePointer>_Myfirst</ValuePointer>
        </ArrayItems>
    </Expand>
</Type>

IncludeView ve ExcludeView özniteliklerini türlerde ve tek tek üyelerde kullanabilirsiniz.

Sürüm öğesi

Version öğesi, görselleştirme girdisinin kapsamını belirli bir modüle ve sürüme göre daraltıyor. Version öğesi ad çakışmalarını önlemeye yardımcı olur, yanlışlıkla uyuşmazlıkları azaltır ve farklı tür sürümleri için farklı görselleştirmelere izin verir.

Farklı modüller tarafından kullanılan ortak başlık dosyası bir tür tanımlarsa, sürüm görselleştirmesi yalnızca tür belirtilen modül sürümündeyken görünür.

Aşağıdaki örnekte, görselleştirme yalnızca sürüm 1.0 ile 1.5 arasında bulunan DirectUI::Border'deki Windows.UI.Xaml.dll türü için geçerlidir.

<Type Name="DirectUI::Border">
  <Version Name="Windows.UI.Xaml.dll" Min="1.0" Max="1.5"/>
  <DisplayString>{{Name = {*(m_pDO->m_pstrName)}}}</DisplayString>
  <Expand>
    <ExpandedItem>*(CBorder*)(m_pDO)</ExpandedItem>
  </Expand>
</Type>

Her ikisine de, yani hem Min'a hem de Max'e, ihtiyacınız yok. Bunlar isteğe bağlı özniteliklerdir. Joker karakter desteklenmez.

Name özniteliği, hello.exe veya some.dllgibi filename.ext biçimindedir. Yol adlarına izin verilmez.

DisplayString öğesi

DisplayString öğesi, değişkenin değeri olarak gösterilecek bir dize belirtir. İfadelerle karıştırılmış rastgele dizeleri kabul eder. Küme ayraçlarının içinde bulunan her şey, bir ifade olarak yorumlanır. Örneğin, aşağıdaki DisplayString girişi:

<Type Name="CPoint">
  <DisplayString>{{x={x} y={y}}}</DisplayString>
</Type>

CPoint türündeki değişkenlerin şu şekilde gösterildiği anlamına gelir:

Bir DisplayString öğesi kullanın

DisplayString ifadesinde, x'ün üyeleri olan y ve CPoint, küme parantezleri içinde yer alır, bu nedenle değerleri değerlendirilir. Örnek ayrıca çift kıvırcık parantez ({{ veya }}) kullanarak bir küme parantezinden kaçmayı nasıl yapabileceğinizi gösterir.

Not

DisplayString öğesi, rastgele dizeleri ve küme ayracı söz dizimini kabul eden tek öğedir. Diğer tüm görselleştirme öğeleri yalnızca hata ayıklayıcının değerlendirebileceği ifadeleri kabul eder.

StringView öğesi

StringView öğesi, hata ayıklayıcının yerleşik metin görselleştiricisine gönderebileceği bir değer tanımlar. Örneğin, ATL::CStringT türü için aşağıdaki görselleştirme göz önünde bulundurulduğunda:

<Type Name="ATL::CStringT&lt;wchar_t,*&gt;">
  <DisplayString>{m_pszData,su}</DisplayString>
</Type>

CStringT nesnesi şu örneğe benzer bir değişken penceresinde görüntülenir:

CStringT DisplayString öğesi

StringView öğesi eklemek hata ayıklayıcıya değeri metin görselleştirmesi olarak görüntüleyebileceğini bildirir.

<Type Name="ATL::CStringT&lt;wchar_t,*&gt;">
  <DisplayString>{m_pszData,su}</DisplayString>
  <StringView>m_pszData,su</StringView>
</Type>

Hata ayıklama sırasında değişkenin yanındaki büyüteç simgesini seçip Metin Görselleştiricisi'ni seçerek m_pszData işaret eden dizeyi görüntüleyebilirsiniz.

StringView görselleştiricisi ile CStringT verilerini

{m_pszData,su} ifadesi, değeri Unicode dizesi olarak görüntülemek için su bir C++ biçim belirticisi içerir. Daha fazla bilgi için bkz. C++ Biçim tanımlayıcıları.

Öğeyi genişlet

İsteğe bağlı Expand düğümü, türü değişken penceresinde genişlettiğinizde görselleştirilmiş bir türün alt öğelerini özelleştirir. Expand düğümü, alt öğeleri tanımlayan alt düğümlerin listesini kabul eder.

Görselleştirme girişinde bir Expand düğümü belirtilmezse, alt öğeler varsayılan genişletme kurallarını kullanır.
Altında alt düğüm olmayan bir Expand düğümü belirtilirse, tür hata ayıklayıcı pencerelerinde genişletilemez.

Öğe genişletme

Item öğesi, Expand düğümündeki en temel ve yaygın öğedir. Item tek bir çocuk öğe tanımlar. Örneğin, CRect, top, leftve right alanları olan bir bottom sınıfı aşağıdaki görselleştirme girdisine sahiptir:

<Type Name="CRect">
  <DisplayString>{{top={top} bottom={bottom} left={left} right={right}}}</DisplayString>
  <Expand>
    <Item Name="Width">right - left</Item>
    <Item Name="Height">bottom - top</Item>
  </Expand>
</Type>

Hata ayıklayıcı penceresinde, CRect türü şu örneğe benzer:

Öğeyle öğe genişletmeli CRect

Hata ayıklayıcı, Width ve Height öğelerinde belirtilen ifadeleri değerlendirir ve değişken penceresinin Değer sütunundaki değerleri gösterir.

Hata ayıklayıcı her özel genişletme için [Raw View] düğümünü otomatik olarak oluşturur. Yukarıdaki ekran görüntüsünde, nesnenin varsayılan ham görünümünün Natvis görselleştirmesinden nasıl farklı olduğunu göstermek için genişletilmiş [Ham Görünüm] düğümü görüntülenir. Varsayılan genişletme, temel sınıf için bir alt ağaç oluşturur ve temel sınıfın tüm veri üyelerini alt öğe olarak listeler.

Not

Öğe öğesinin ifadesi karmaşık bir türe işaret ederse, Öğe düğümü genişletilebilir.

Dizi Öğeleri genişletmesi

Visual Studio hata ayıklayıcının türü dizi olarak yorumlamasını ve tek tek öğelerini görüntülemesini sağlamak için ArrayItems düğümünü kullanın. std::vector görselleştirmesi iyi bir örnektir:

<Type Name="std::vector&lt;*&gt;">
  <DisplayString>{{size = {_Mylast - _Myfirst}}}</DisplayString>
  <Expand>
    <Item Name="[size]">_Mylast - _Myfirst</Item>
    <Item Name="[capacity]">(_Myend - _Myfirst)</Item>
    <ArrayItems>
      <Size>_Mylast - _Myfirst</Size>
      <ValuePointer>_Myfirst</ValuePointer>
    </ArrayItems>
  </Expand>
</Type>

Bir std::vector, değişken penceresinde genişletildiğinde kendi bileşenlerini ayrı ayrı gösterir.

ArrayItems genişletmesini kullanarak std::vector

ArrayItems düğümünde aşağıdakiler olmalıdır:

Hata ayıklayıcısının dizinin uzunluğunu anlaması için bir Size ifadesi (tamsayı olarak değerlendirilmelidir).
İlk öğeye işaret eden bir ValuePointer ifadesi (bu, void* olmayan bir öğe türünün işaretçisi olmalıdır).

Dizinin alt sınırındaki varsayılan değer 0'dır. Değeri geçersiz kılmak için bir LowerBound öğesi kullanın. Visual Studio ile birlikte gönderilen .natvis dosyaları örnekler içerir.

Not

Örneğin [] işlecini, türün kendisi (örneğin ArrayItems) bu işlevi desteklemese bile vector[i] içeren tek boyutlu dizi görselleştirmeleriyle CATLArray kullanabilirsiniz.

Çok boyutlu diziler de belirtebilirsiniz. Bu durumda, alt öğeleri düzgün bir şekilde görüntülemek için hata ayıklayıcı biraz daha fazla bilgiye ihtiyaç duyar:

<Type Name="Concurrency::array&lt;*,*&gt;">
  <DisplayString>extent = {_M_extent}</DisplayString>
  <Expand>
    <Item Name="extent">_M_extent</Item>
    <ArrayItems Condition="_M_buffer_descriptor._M_data_ptr != 0">
      <Direction>Forward</Direction>
      <Rank>$T2</Rank>
      <Size>_M_extent._M_base[$i]</Size>
      <ValuePointer>($T1*) _M_buffer_descriptor._M_data_ptr</ValuePointer>
      <LowerBound>0</LowerBound>
    </ArrayItems>
  </Expand>
</Type>

Direction dizinin satır-ana veya sütun-ana sıralı olup olmadığını belirtir.
Rank dizinin derecesini belirtir.
Size öğesi örtük $i parametresini kabul eder ve bu parametreyi boyut diziniyle değiştirerek bu boyuttaki dizinin uzunluğunu bulur.
- Önceki örnekte, _M_extent.M_base[0] ifadesi 0. boyutun uzunluğunu vermelidir, ilk _M_extent._M_base[1] vb.
LowerBound, dizinin her boyutunun alt sınırlarını belirtir. Çok boyutlu diziler için örtük $i parametresini kullanan bir ifade belirtebilirsiniz. parametresi $i , bu boyuttaki dizinin alt sınırlarını bulmak için boyut diziniyle değiştirilir.
- Önceki örnekte, tüm boyutlar 0'da başlar. Ancak alt sınıra sahipseniz ($i == 1) ? 1000 : 100 , 0. boyut 100'de başlar ve ilk boyut 1000'de başlar.
  - gibi [100, 1000], [100, 1001], [100, 1002], ... [101, 1000], [101, 1001],...

İki boyutlu bir Concurrency::array nesnesi hata ayıklayıcı penceresinde şöyle görünür:

ArrayItems genişletme ile iki boyutlu dizi

IndexListItems genişletmesi

ArrayItems genişletmeyi yalnızca dizi öğeleri bellekte bitişik olarak yerleştirilmişse kullanabilirsiniz. Hata ayıklayıcı, işaretçisini artırarak sonraki öğeye geçer. Dizini değer düğümüyle değiştirmeniz gerekiyorsa IndexListItems düğümleri kullanın. IndexListItems düğümüne sahip bir görselleştirme aşağıdadır:

<Type Name="Concurrency::multi_link_registry&lt;*&gt;">
  <DisplayString>{{size = {_M_vector._M_index}}}</DisplayString>
  <Expand>
    <Item Name="[size]">_M_vector._M_index</Item>
    <IndexListItems>
      <Size>_M_vector._M_index</Size>
      <ValueNode>*(_M_vector._M_array[$i])</ValueNode>
    </IndexListItems>
  </Expand>
</Type>

ArrayItems ile IndexListItems arasındaki tek fark, tam ifadeyi örtük ValueNode parametresiyle i^. öğesine bekleyen $ideğeridir.

Not

Örneğin [] işlecini, türün kendisi (örneğin vector[i]) bu işlecine izin vermese bile IndexListItems kullanan tek boyutlu dizi görselleştirmeleriyle CATLArray kullanabilirsiniz.

LinkedListItems genişlemesi

Görselleştirilmiş tür bir bağlantılı listeyi temsil ederse, hata ayıklama aracı LinkedListItems düğümünü kullanarak alt öğelerini gösterebilir. CAtlList türü için aşağıdaki görselleştirmede LinkedListItemskullanılır:

<Type Name="ATL::CAtlList&lt;*,*&gt;">
  <DisplayString>{{Count = {m_nElements}}}</DisplayString>
  <Expand>
    <Item Name="Count">m_nElements</Item>
    <LinkedListItems>
      <Size>m_nElements</Size>
      <HeadPointer>m_pHead</HeadPointer>
      <NextPointer>m_pNext</NextPointer>
      <ValueNode>m_element</ValueNode>
    </LinkedListItems>
  </Expand>
</Type>

Size öğesi listenin uzunluğuna başvurur. HeadPointer ilk öğeye işaret NextPointer sonraki öğeye, ValueNode ise öğenin değerine başvurur.

Hata ayıklayıcı, NextPointer ve ValueNode ifadelerini üst liste türü değil LinkedListItems düğüm öğesi bağlamında değerlendirir. Yukarıdaki örnekte, CAtlList bağlı listenin düğümü olan bir CNode sınıfı (atlcoll.hiçinde bulunur) vardır. m_pNext ve m_element, CNode sınıfının değil, bu CAtlList sınıfının alanlarıdır.

ValueNode boş bırakılabilir veya this kullanarak LinkedListItems düğümün kendisine başvurabilirsiniz.

CustomListItems genişletmesi

CustomListItems genişletme, karma tablo gibi bir veri yapısından geçiş yapmak için özel mantık yazmanızı sağlar. değerlendirmeniz gereken her şey için C++ ifadelerini kullanabilen, ancak CustomListItems, ArrayItemsveya IndexListItemsiçin tam olarak uymayan veri yapılarını görselleştirmek için LinkedListItems kullanın.

genişletmesinde tanımlanan değişkenleri ve nesneleri kullanarak Exec genişletme içinde kod yürütmek için CustomListItems kullanabilirsiniz. Execile mantıksal işleçler, aritmetik işleçler ve atama işleçleri kullanabilirsiniz. C++ ifade değerlendiricisi tarafından desteklenen Exec dışında, işlevleri değerlendirmek için kullanamazsınız.

CAtlMap için aşağıdaki görselleştirici, CustomListItems'in uygun bir örneği olarak mükemmeldir.

<Type Name="ATL::CAtlMap&lt;*,*,*,*&gt;">
    <AlternativeType Name="ATL::CMapToInterface&lt;*,*,*&gt;"/>
    <AlternativeType Name="ATL::CMapToAutoPtr&lt;*,*,*&gt;"/>
    <DisplayString>{{Count = {m_nElements}}}</DisplayString>
    <Expand>
      <CustomListItems MaxItemsPerView="5000" ExcludeView="Test">
        <Variable Name="iBucket" InitialValue="-1" />
        <Variable Name="pBucket" InitialValue="m_ppBins == nullptr ? nullptr : *m_ppBins" />
        <Variable Name="iBucketIncrement" InitialValue="-1" />

        <Size>m_nElements</Size>
        <Exec>pBucket = nullptr</Exec>
        <Loop>
          <If Condition="pBucket == nullptr">
            <Exec>iBucket++</Exec>
            <Exec>iBucketIncrement = __findnonnull(m_ppBins + iBucket, m_nBins - iBucket)</Exec>
            <Break Condition="iBucketIncrement == -1" />
            <Exec>iBucket += iBucketIncrement</Exec>
            <Exec>pBucket = m_ppBins[iBucket]</Exec>
          </If>
          <Item>pBucket,na</Item>
          <Exec>pBucket = pBucket->m_pNext</Exec>
        </Loop>
      </CustomListItems>
    </Expand>
</Type>

TreeItems genişletmesi

Görselleştirilmiş tür bir ağacı temsil ediyorsa, hata ayıklayıcı, TreeItems düğümünü kullanarak ağaçta gezinebilir ve alt öğelerini görüntüleyebilir. std::map düğümü kullanan TreeItems türünün görselleştirmesi aşağıdadır:

<Type Name="std::map&lt;*&gt;">
  <DisplayString>{{size = {_Mysize}}}</DisplayString>
  <Expand>
    <Item Name="[size]">_Mysize</Item>
    <Item Name="[comp]">comp</Item>
    <TreeItems>
      <Size>_Mysize</Size>
      <HeadPointer>_Myhead->_Parent</HeadPointer>
      <LeftPointer>_Left</LeftPointer>
      <RightPointer>_Right</RightPointer>
      <ValueNode Condition="!((bool)_Isnil)">_Myval</ValueNode>
    </TreeItems>
  </Expand>
</Type>

Söz dizimi LinkedListItems düğümüne benzer. LeftPointer, RightPointerve ValueNode, ağaç düğümü sınıfı bağlamında değerlendirilir. ValueNode boş bırakılabilir veya this düğümün kendisine başvurmak için TreeItems kullanabilirsiniz.

ExpandedItem'in genişlemesi

ExpandedItem öğesi, temel sınıfların veya veri üyelerinin özelliklerini görselleştirilmiş türün alt öğeleriymiş gibi görüntüleyerek toplu bir alt görünüm oluşturur. Hata ayıklayıcı belirtilen ifadeyi değerlendirir ve sonucun alt düğümlerini görselleştirilmiş türün alt listesine ekler.

Örneğin, auto_ptr<vector<int>> akıllı işaretçi türü genellikle şu şekilde görüntülenir:

auto_ptr<vektör<int>> varsayılan genişletme

Vektörün değerlerini görmek için değişken penceresindeki _Myptr üyesinden geçerek iki düzeyin detayına derinlemesine inmeniz gerekir. bir ExpandedItem öğesi ekleyerek hiyerarşiden _Myptr değişkenini ortadan kaldırıp vektör öğelerini doğrudan görüntüleyebilirsiniz:

<Type Name="std::auto_ptr&lt;*&gt;">
  <DisplayString>auto_ptr {*_Myptr}</DisplayString>
  <Expand>
    <ExpandedItem>_Myptr</ExpandedItem>
  </Expand>
</Type>

auto_ptr<vektör<int>> ExpandedItem genişletme

Aşağıdaki örnekte, türetilmiş bir sınıftaki temel sınıftan özelliklerin nasıl toplandığı gösterilmektedir. CPanel sınıfının CFrameworkElementtüretilmiş olduğunu varsayalım. CFrameworkElement düğüm görselleştirmesi, temel ExpandedItem sınıfından gelen özellikleri yinelemek yerine bu özellikleri CPanel sınıfının alt listesine ekler.

<Type Name="CPanel">
  <DisplayString>{{Name = {*(m_pstrName)}}}</DisplayString>
  <Expand>
    <Item Name="IsItemsHost">(bool)m_bItemsHost</Item>
    <ExpandedItem>*(CFrameworkElement*)this,nd</ExpandedItem>
  </Expand>
</Type>

Türetilmiş sınıf için görselleştirme eşleştirmeyi kapatan nd biçim tanımlayıcısı burada gereklidir. Aksi takdirde, *(CFrameworkElement*)this ifadesi CPanel görselleştirmenin yeniden uygulanmasına neden olur çünkü varsayılan görselleştirme türü eşleştirme kuralları bunu en uygun olan olarak kabul eder. Hata ayıklayıcıya temel sınıf görselleştirmesini kullanmasını bildirmek için nd biçim tanımlayıcısını veya temel sınıfın görselleştirmesi yoksa varsayılan genişletmeyi kullanın.

Yapay nesne genişletme

ExpandedItem öğesi hiyerarşileri ortadan kaldırarak verilerin daha düz bir görünümünü sağlarken, Synthetic düğümü tam tersini yapar. İfadenin sonucu olmayan bir yapay alt öğe oluşturmanıza olanak tanır. Yapay öğe kendi çocuk öğelerine sahip olabilir. Aşağıdaki örnekte, Concurrency::array türünün görselleştirmesi kullanıcıya tanılama iletisi göstermek için bir Synthetic düğümü kullanır:

<Type Name="Concurrency::array&lt;*,*&gt;">
  <DisplayString>extent = {_M_extent}</DisplayString>
  <Expand>
    <Item Name="extent" Condition="_M_buffer_descriptor._M_data_ptr == 0">_M_extent</Item>
    <ArrayItems Condition="_M_buffer_descriptor._M_data_ptr != 0">
      <Rank>$T2</Rank>
      <Size>_M_extent._M_base[$i]</Size>
      <ValuePointer>($T1*) _M_buffer_descriptor._M_data_ptr</ValuePointer>
    </ArrayItems>
    <Synthetic Name="Array" Condition="_M_buffer_descriptor._M_data_ptr == 0">
      <DisplayString>Array members can be viewed only under the GPU debugger</DisplayString>
    </Synthetic>
  </Expand>
</Type>

Concurrency::Array ile Yapay öğe genişletme

İç genişleme

bir ifadeden çağrılabilen özel bir iç işlev. bir <Intrinsic> öğesine, işlevi IDkmIntrinsicFunctionEvaluator140 arabirimi aracılığıyla uygulayan bir hata ayıklayıcısı bileşeni eşlik etmelidir. Özel iç işlevi uygulama hakkında daha fazla bilgi için bkz. NatVis özel iç işlevini uygulama.

<Type Name="std::vector&lt;*&gt;">
  <Intrinsic Name="size" Expression="(size_t)(_Mypair._Myval2._Mylast - _Mypair._Myval2._Myfirst)" />
  <Intrinsic Name="capacity" Expression="(size_t)(_Mypair._Myval2._Myend - _Mypair._Myval2._Myfirst)" />
  <DisplayString>{{ size={size()} }}</DisplayString>
  <Expand>
    <Item Name="[capacity]" ExcludeView="simple">capacity()</Item>
    <Item Name="[allocator]" ExcludeView="simple">_Mypair</Item>
    <ArrayItems>
      <Size>size()</Size>
      <ValuePointer>_Mypair._Myval2._Myfirst</ValuePointer>
    </ArrayItems>
  </Expand>
</Type>

HResult öğesi

HResult öğesi, hata ayıklayıcı pencerelerindeki HRESULT için gösterilen bilgileri özelleştirmenize olanak tanır. HRValue öğesi, özelleştirilecek HRESULT 32 bit değerini içermelidir. HRDescription öğesi, hata ayıklayıcı penceresinde gösterilecek bilgileri içerir.


<HResult Name="MY_E_COLLECTION_NOELEMENTS">
  <HRValue>0xABC0123</HRValue>
  <HRDescription>No elements in the collection.</HRDescription>
</HResult>

UIVisualizer öğesi

UIVisualizer öğesi, bir grafik görselleştirici eklentisini hata ayıklayıcıya kaydeder. Grafik görselleştirici, değişken veya nesneyi veri türüyle tutarlı bir şekilde gösteren bir iletişim kutusu veya başka bir arabirim oluşturur. Görselleştirici eklentisi, VSPackageolarak yazılmalıdır ve hata ayıklayıcının kullanabileceği bir hizmeti kullanıma sunmalıdır. .natvis dosyası eklentinin adı, kullanıma sunulan hizmetin genel benzersiz tanımlayıcısı (GUID) ve görselleştirebileceği türler gibi kayıt bilgilerini içerir.

UiVisualizer öğesinin bir örneği aşağıda verilmiştir:

<?xml version="1.0" encoding="utf-8"?>
<AutoVisualizer xmlns="http://schemas.microsoft.com/vstudio/debugger/natvis/2010">
    <UIVisualizer ServiceId="{5452AFEA-3DF6-46BB-9177-C0B08F318025}"
        Id="1" MenuName="Vector Visualizer"/>
    <UIVisualizer ServiceId="{5452AFEA-3DF6-46BB-9177-C0B08F318025}"
        Id="2" MenuName="List Visualizer"/>
.
.
</AutoVisualizer>

ServiceId - Id öznitelik çifti bir UIVisualizertanımlar. ServiceId, görselleştirici paketinin açığa çıkardığı hizmetin GUID'sidir. Id, bir hizmet birden fazla hizmet sağlıyorsa görselleştiricileri ayırt eden benzersiz bir tanımlayıcıdır. Yukarıdaki örnekte, aynı görselleştirici hizmeti iki görselleştirici sağlar.
MenuName özniteliği, hata ayıklayıcıdaki büyüteç simgesinin yanındaki açılan listede görüntülenecek bir görselleştirici adı tanımlar. Mesela:

.natvis dosyasında tanımlanan her tür, bunu görüntüleyebilen tüm ui görselleştiricilerini açıkça listelemelidir. Hata ayıklayıcı, tür girişlerindeki görselleştirici başvurularını kayıtlı görselleştiricilerle eşleştirir. Örneğin, std::vector için aşağıdaki tür girdisi, önceki örnekte yer alan UIVisualizer'e atıfta bulunmaktadır.

<Type Name="std::vector&lt;int,*&gt;">
  <UIVisualizer ServiceId="{5452AFEA-3DF6-46BB-9177-C0B08F318025}" Id="1" />
</Type>

Bellek içi bit eşlemleri görüntülemek için kullanılan UIVisualizer uzantısında bir örneği görebilirsiniz.

CustomVisualizer öğesi

CustomVisualizer, Visual Studio Code'daki görselleştirmeleri denetlemek için yazdığınız VSIX uzantısını belirten bir genişletilebilirlik noktasıdır. VSIX uzantıları yazma hakkında daha fazla bilgi için bkz. visual studio SDK .

Özel görselleştirici yazmak XML Natvis tanımından çok daha fazla iştir, ancak Natvis'in ne yaptığı veya desteklemediğiyle ilgili kısıtlamalardan kurtulmuş olursunuz. Özel görselleştiriciler, hata ayıklama işlemi sorgulayıp değiştirebilen veya Visual Studio'nun diğer bölümleriyle iletişim kurabilen hata ayıklayıcı genişletilebilirlik API'lerinin tamamına erişebilir.

Condition öğelerinde IncludeView, ExcludeViewve CustomVisualizer özniteliklerini kullanabilirsiniz.

Sınırlama