برنامج تصحيح الأخطاء

عليك تصحيح أخطاء مشروعك باستخدام Visual Studio Debugger (LLDB) عند استخدام إضافة تطوير ألعاب Android.

تشغيل برنامج تصحيح الأخطاء

قبل أن تتمكن من تشغيل برنامج تصحيح الأخطاء، يجب أن تكون قادرًا على إنشاء لعبتك ونشرها وتشغيلها على Android. راجِع القسم تشغيل النموذج للحصول على التفاصيل.

بعد التأكد من إمكانية تشغيل لعبتك بدون برنامج تصحيح الأخطاء، يمكنك استخدام برنامج تصحيح الأخطاء من خلال الضغط على F5 أو تحديد العنصر بدء تصحيح الأخطاء في قائمة تصحيح الأخطاء. سيظهر لك مربّع حوار أثناء ربط برنامج تصحيح الأخطاء باللعبة.

يستغرق تشغيل برنامج تصحيح الأخطاء مدة تتراوح بين 10 ثوانٍ ودقيقة واحدة أو أكثر بناءً على حجم التطبيق وعدد الرموز التي يجب تحميلها عند بدء التشغيل. ويستغرق الأمر وقتًا أطول عند إرفاق الجهاز بجهاز جديد للمرة الأولى، حيث يضطر برنامج تصحيح الأخطاء إلى تنزيل بعض مكتبات Android من الجهاز إلى الجهاز المضيف. إذا استغرقت أكثر من دقيقة واحدة في أول محاولات باستخدام جهاز جديد، ننصحك بإلغاء جلسة تصحيح الأخطاء، ثم إعادة تشغيلها.

وعند تشغيل برنامج تصحيح الأخطاء بهذه الطريقة، تبدأ اللعبة في وضع انتظار برنامج تصحيح الأخطاء ولن تنفِّذ أي رمز من رموز لعبتك ما لم يتم الاتصال ببرنامج تصحيح الأخطاء. ويتيح لك ذلك أيضًا تصحيح الأخطاء في قسم الإعداد في لعبتك.

يمكنك الاطّلاع على مزيد من المعلومات حول ميزات محددة لبرنامج تصحيح الأخطاء في Visual Studio من خلال قراءة مستندات Visual Studio.

إرفاق عملية

إذا أردت تصحيح الأخطاء في لعبة يتم تشغيلها على جهاز مادي أو افتراضي، يمكنك إرفاق برنامج تصحيح الأخطاء بالعملية من Visual Studio.

في Visual Studio، تأكّد من أن أحد حلول Android مفتوح، وأن:

  1. انتقِل إلى قائمة تصحيح الأخطاء واختَر إرفاق للمعالجة....
  2. من القائمة المنسدلة النقل، اختَر إضافة تطوير ألعاب Android.
  3. من القائمة المنسدلة المؤهِّل، اختَر جهاز Android الخاص بك.
  4. اختَر عملية اللعبة من قائمة العمليات المتاحة، وانقر على إرفاق.

إرفاق للمعالجة

تنفيذ أوامر LLDB.Shell

عندما تكون جلسة تصحيح الأخطاء نشطة، استخدِم نافذة الأوامر في Visual Studio لتشغيل أوامر LLDB.Shell.

تنسيق الأمر:

LLDB.Shell [command]

مثال:

>LLDB.Shell expr myIntVariable = 9
Status:  Success
Output Message:
(int) $2 = 9

العرض المرئي للبيانات

محددات التنسيق

يمكنك تغيير التنسيق الذي يتم عرض القيمة به في نوافذ Autos وLocals ومشاهدة ومتغيرة من DataTip باستخدام محددات التنسيق.

توجد محددات التنسيق في نهاية التعبيرات. تبدأ بفاصلة متبوعة بسلسلة قصيرة. على سبيل المثال، سينسق محدد ,x في التعبير _myInt,x myInt كقيمة سداسية عشرية صغيرة.

يمكن استخدام محددات التنسيق مباشرةً في نافذة مشاهدة أو في نوافذ Autos وLocals وDataTip من خلال إضافتها إلى تعبيرات Natvis. راجِع Natvis للاطّلاع على مزيد من المعلومات.

قائمة محددات الدعم

اسم التنسيق المحدِّد(المحدِّدات) الوصف
منطقية B إظهار ذلك على أنه صحيح/خطأ، باستخدام القاعدة الاعتيادية القائلة بأن 0 هو خطأ وكل شيء آخر صحيح
برنامج ثنائي b إظهار ذلك كسلسلة من وحدات البت
ثنائي، بدون 0b بادئة bb عرض ذلك كتسلسل من وحدات البت بدون البادئة 0b
بايت y اعرض وحدات البايت، لكن جرب عرضها أيضًا كأحرف ASCII
على سبيل المثال (int *) c.sp.x = 50 f8 bf 5f ff 7f 00 00 P.._....
بايت باستخدام ASCII Y اعرض وحدات البايت، لكن جرب عرضها أيضًا كأحرف ASCII
على سبيل المثال (int *) c.sp.x = 50 f8 bf 5f ff 7f 00 00 P.._....
حرف c عرض وحدات البايت على شكل أحرف ASCII
مثلاً: (int *) c.sp.x = P\xf8\xbf_\xff\x7f\0\0
رمز قابل للطباعة C عرض وحدات البايت على شكل أحرف ASCII قابلة للطباعة
على سبيل المثال (int *) c.sp.x = P.._....
عدد عائم معقد F يُرجى تفسير هذه القيمة على أنّها جزء حقيقي وتخيلي لرقم النقطة العائمة المركّبة
على سبيل المثال (int *) c.sp.x = 2.76658e+19 + 4.59163e-41i.
علامة عشرية د، ط إظهار هذا كعدد صحيح مُوقَّع (لا يؤدي ذلك إلى تنفيذ عملية بث، بل يؤدي ببساطة إلى عرض وحدات البايت كعدد صحيح مع علامة)
التعداد E,en إظهار ذلك كتعداد، أو طباعة اسم القيمة إذا كان متاحًا أو قيمة العدد الصحيح بخلاف ذلك
على سبيل المثال (enum enumType) val_type = eValue2
النظام السداسي العشري - صغير x، h إظهار هذا بتدوين سداسي عشري صغير (لا يؤدي هذا إلى تنفيذ عملية إرسال، بل يعرض وحدات البايت فقط على شكل سداسي عشري)
نظام سداسي عشري - أحرف كبيرة س، ح إظهار ذلك بتدوين سداسي عشري بأحرف كبيرة (لا يؤدي هذا إلى تنفيذ إرسال، بل يؤدي فقط إلى عرض وحدات البايت على شكل سداسي عشري)
النظام السداسي العشري - حالة صغيرة، بدون 0x بادئ xb وhb إظهار ذلك بتدوين سداسي عشري صغير بدون البادئة 0x (لا يؤدي هذا إلى إرسال وحدات البايت، بل يُظهر وحدات البايت على شكل سداسي عشري)
نظام سداسي عشري - أحرف كبيرة، بدون 0x في البداية Xb ، Hb إظهار ذلك بتدوين سداسي عشري بأحرف كبيرة بدون البادئة 0x (لا يؤدي هذا إلى إرسال وحدات البايت، بل يُظهر وحدات البايت على شكل سداسي عشري)
عائم f عرض هذا كرقم نقطة عائمة (لا يؤدي هذا إلى تنفيذ عملية بث، بل يفسر وحدات البايت على أنها قيمة النقطة العائمة IEEE754)
النظام الثماني o عرض ذلك بالترميز الثماني
نوع نظام التشغيل O إظهار هذا على هيئة MacOS OSType
على سبيل المثال (float) x = '\n\x1f\xd7\n'
سلسلة - سلسلة C s عرض هذا على شكل سلسلة C حرف 0
مثل "hello world"
سلسلة - سلسلة C، بدون علامات اقتباس sb عرض هذا على شكل سلسلة C تم إنهاؤها بدون علامات اقتباس،
مثال: hello world
سلسلة - UTF-8 s8 سيعرض ذلك على شكل سلسلة UTF-8 منتهية الصلاحية
على سبيل المثال: u8"hello world 🎂"
سلسلة - UTF-8، بدون علامات اقتباس s8b عرض ذلك على شكل سلسلة UTF-8 تم إنهاؤها بدون علامة اقتباس
مثلاً، hello world 🎂
سلسلة: UTF-16 su اعرض هذا الخيار على شكل سلسلة UTF-16 يتم إنهاؤها بدون إنهاء
على سبيل المثال، u"hello world 🎂"
سلسلة: UTF-16، بدون علامات اقتباس sub عرض ذلك على شكل سلسلة UTF-16 يتم إنهاؤها بدون علامات اقتباس
مثلاً، hello world 🌈
سلسلة: UTF-32 s32 وتعرض ذلك على شكل سلسلة UTF-32 بدون إنهاء
على سبيل المثال: U"hello world 🎂"
سلسلة: UTF-32، بدون علامات اقتباس s32b عرض ذلك على شكل سلسلة UTF-32 تم إنهاؤها بدون علامات اقتباس
مثلاً، hello world 👏
يونيكود16 U تعرض ذلك على هيئة أحرف UTF-16
على سبيل المثال (عدد عائم) x = 0xd70a 0x411f
يونيكود 32 U32 اعرض هذا على هيئة أحرف UTF-32
على سبيل المثال، (عدد عشري) x = 0x411fd70a
علامة عشرية بدون توقيع u إظهار هذا كعدد صحيح غير موقَّع (لا يؤدي ذلك إلى تنفيذ عملية بث، بل يؤدي ببساطة إلى عرض وحدات البايت كعدد صحيح غير مُوقَّع)
مؤشر p إظهار ذلك كمؤشر أصلي (ما لم يكن هذا المؤشر حقًا، فمن المحتمل أن يكون العنوان الناتج غير صالح)
عدد صحيح مركّب I يجب تفسير هذه القيمة على أنّها جزء حقيقي وتخيلي لعدد صحيح مركّب
على سبيل المثال، المؤشر (int *) = 1048960 + 1i.
مصفوفة الأحرف a إظهار ذلك في صورة مصفوفة من الأحرف
على سبيل المثال (char) *c.sp.z = {X}
عرض أوّلي ! تنسيق أوّلي، مع تجاهل أي تخصيص لطرق عرض نوع البيانات

ناتفيس

يسمح لك إطار عمل Natvis بتخصيص طريقة عرض Visual Studio للأنواع الأصلية في نوافذ متغيرات برنامج تصحيح الأخطاء. على سبيل المثال، يمكنك استخدام Natvis لتخصيص شاشات العرض لنوافذ مشاهدة وLocals ونصائح البيانات.

يتم تفعيل ميزة Natvis تلقائيًا ولكن يمكن إيقافها من Visual Studio من خلال ضبط العلامة الأدوات > الخيارات > إضافة تطوير ألعاب Android > Natvis على معطَّلة.

جارٍ تحميل ملفات Natvis

تحمِّل Visual Studio ملفات Natvis من المواقع الثلاثة المدرجة أدناه، وتعيد تحميلها في كل مرة تبدأ فيها جلسة تصحيح أخطاء. يجب أن تلتزم الملفات بمخطط Natvis 2017 من Visual Studio.

  • .natvis من الملفات التي تشكّل جزءًا من مشروع تم تحميله أو عنصر حل من المستوى الأعلى
  • الدليل الخاص بالمستخدم (%USERPROFILE%\Documents\Visual Studio 2017\Visualizers)
  • الدليل على مستوى النظام (%VSINSTALLDIR%\Common7\Packages\Debugger\Visualizers)
إعادة تحميل ملفات Natvis

أعِد تحميل ملفات Natvis أثناء جلسة تصحيح الأخطاء من خلال تقييم .natvisreload في نافذة الأوامر أو نافذة المشاهدة.

نموذج ملف Natvis

يتضمن نموذج ملف Natvis هذا جميع العلامات والسمات المتوافقة حاليًا.

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

  <Type Name="demo::Vector&lt;*&gt;">
    <AlternativeType Name="MySimilarVectorType&lt;*&gt;"/>

    <!-- Included to show the <SmartPointer> feature is supported. -->
    <SmartPointer Optional="true" Usage="Minimal">ptr</SmartPointer>

    <!-- Included to show the <DisplayString> feature is supported. -->
    <DisplayString Condition="_size == 0" Optional="true">()</DisplayString>
    <DisplayString Condition="_size == 1">(x={_items[0]})</DisplayString>
    <DisplayString Condition="_size == 2">(x={_items[0]}, y={_items[1]})</DisplayString>
    <DisplayString Condition="_size == 3">(x={_items[0]}, y={_items[1]}, z={_items[2]})</DisplayString>
    <DisplayString>[Size={_size,x}] (x={_items[0]}, y={_items[1]}, z={_items[2]}, ...)</DisplayString>

    <!-- Included to show the <StringView> feature is supported. -->
    <StringView Condition="true" Optional="true">_stringViewText</StringView>

    <Expand HideRawView="false">
      <!-- Included to show the <Item> feature is supported. -->
      <Item Name="X" Condition="_size &lt; 4 &amp;&amp; _size &gt;= 1" Optional="true">_items[0]</Item>
      <Item Name="Y" Condition="_size &lt; 4 &amp;&amp; _size &gt;= 2" Optional="true">_items[1]</Item>
      <Item Name="Z" Condition="_size &lt; 4 &amp;&amp; _size &gt;= 3" Optional="true">_items[2]</Item>

      <!-- Included to show the <ArrayItems> feature is supported. -->
      <ArrayItems Condition="_size >= 4" Optional="true">
        <Size Condition="true" Optional="true">_size</Size>
        <ValuePointer Condition="true">_items</ValuePointer>
      </ArrayItems>

      <!-- Included to show the <IndexListItems> feature is supported. -->
      <IndexListItems Condition="true" Optional="true">
        <Size Condition="true" Optional="true">_listSize</Size>
        <ValueNode Condition="true">_list[%i]</ValueNode>
      </IndexListItems>

      <!-- Included to show the <LinkedListItems> feature is supported. -->
      <LinkedListItems Condition="true" Optional="true">
        <Size Optional="true">_listSize</Size>
        <HeadPointer>_head</HeadPointer>
        <NextPointer>_next</NextPointer>
        <ValueNode>_value</ValueNode>
      </LinkedListItems>

      <!-- Included to show the <ExpandedItem> feature is supported. -->
      <ExpandedItem Condition="true" Optional="true">_childVar</ExpandedItem>

      <!-- Included to show the <Synthetic> feature is supported. -->
      <Synthetic Name="[Size]" Condition="true" Optional="true">
        <DisplayString>_size</DisplayString>
        <Expand HideRawView="true">
          <!-- Any supported <Expand> sub-tags. -->
        </Expand>
      </Synthetic>

      <!-- Included to show the <TreeItems> feature is supported. -->
      <TreeItems Condition="true" Optional="true">
        <Size>_treeSize</Size>
        <HeadPointer>_head</HeadPointer>
        <LeftPointer>_left</LeftPointer>
        <RightPointer>_right</RightPointer>
        <ValueNode>_value</ValueNode>
      </TreeItems>

      <!-- Included to show format specifiers are supported. -->
      <Item Name="[Hex Dump at {_index,x}]">myInt[_index],x</Item>
    </Expand>
  </Type>
</AutoVisualizer>

تأليف ملفات Natvis

تتيح Visual Studio إنشاء ملفات Natvis الخاصة بك. لمزيد من المعلومات حول تخصيص نوافذ متغيرات برنامج تصحيح الأخطاء، يُرجى الاطّلاع على MSDN.

تصحيح أخطاء ملفات Natvis

في بعض الحالات، ستظهر الأخطاء على أنّها قيمة أحد المتغيّرات (على سبيل المثال، في نوافذ Auto ومشاهدة وما إلى ذلك). مثال: <error: use of undeclared identifier 'missingVar'>

يمكنك الوصول إلى مزيد من التفاصيل حول الخطأ من خلال فتح ملف GoogleAndroid.log من شريط أدوات إضافة تطوير ألعاب Android.

القيود المعروفة

  • إذا لم تكن العلامة أو السمة مدرَجة في نموذج الملف أعلاه، يعني ذلك أنّها غير متاحة حاليًا. تتجاهل Visual Studio العلامات والسمات غير المتوافقة، لذا يمكنك تركها في ملف Natvis الحالي وسوف يعمل الملف طالما أنه يستخدم مخططنا.

  • على الرغم من أنّ السمة Usage مطلوبة في المخطط، لا يمكن استخدامها في <SmartPointer>. ومع ذلك، لا تحظر LLDB الوصول إلى العوامل المعرّفة في C++ ، بحيث يمكن تحديد أي عامل مطلوب في C++ بدلاً من ذلك.