تمكين Snapshot Debugger لتطبيقات .NET في Azure Service Fabric والخدمات السحابية والأجهزة الظاهرية

  • مقالة

إذا كان تطبيق ASP.NET أو ASP.NET Core يعمل في Azure App Service ويتطلب تكوين Snapshot Debugger مخصصا أو إصدار معاينة من .NET Core، فابدأ بتمكين Snapshot Debugger لتطبيقات .NET في Azure App Service.

إذا كان تطبيقك يعمل في Azure Service Fabric أو Azure Cloud Services أو Azure Virtual Machines أو الأجهزة المحلية، يمكنك تخطي تمكين Snapshot Debugger على App Service واتباع الإرشادات الواردة في هذه المقالة.

قبل البدء

ضبط مجموعة لقطات لتطبيقات ASP.NET

عند إضافة حزمة Microsoft.ApplicationInsights.SnapshotCollector NuGet إلى التطبيق الخاص بك، SnapshotCollectorTelemetryProcessor يجب إضافة تلقائيا إلى TelemetryProcessors قسم ApplicationInsights.config.

إذا كنت لا ترى SnapshotCollectorTelemetryProcessor في ApplicationInsights.config، أو إذا كنت تريد تخصيص تكوين Snapshot Debugger، يمكنك تحريره يدويا. ومع ذلك، قد تتم الكتابة فوق هذه التعديلات إذا قمت لاحقا بالترقية إلى إصدار أحدث من حزمة Microsoft.ApplicationInsights.SnapshotCollector NuGet.

يوضح المثال التالي تكوينا مكافئا للتكوين الافتراضي:

<TelemetryProcessors>
  <Add Type="Microsoft.ApplicationInsights.SnapshotCollector.SnapshotCollectorTelemetryProcessor, Microsoft.ApplicationInsights.SnapshotCollector">
    <!-- The default is true, but you can disable Snapshot Debugging by setting it to false -->
    <IsEnabled>true</IsEnabled>
    <!-- Snapshot Debugging is usually disabled in developer mode, but you can enable it by setting this to true. -->
    <!-- DeveloperMode is a property on the active TelemetryChannel. -->
    <IsEnabledInDeveloperMode>false</IsEnabledInDeveloperMode>
    <!-- How many times we need to see an exception before we ask for snapshots. -->
    <ThresholdForSnapshotting>1</ThresholdForSnapshotting>
    <!-- The maximum number of examples we create for a single problem. -->
    <MaximumSnapshotsRequired>3</MaximumSnapshotsRequired>
    <!-- The maximum number of problems that we can be tracking at any time. -->
    <MaximumCollectionPlanSize>50</MaximumCollectionPlanSize>
    <!-- How often we reconnect to the stamp. The default value is 15 minutes.-->
    <ReconnectInterval>00:15:00</ReconnectInterval>
    <!-- How often to reset problem counters. -->
    <ProblemCounterResetInterval>1.00:00:00</ProblemCounterResetInterval>
    <!-- The maximum number of snapshots allowed in ten minutes.The default value is 1. -->
    <SnapshotsPerTenMinutesLimit>3</SnapshotsPerTenMinutesLimit>
    <!-- The maximum number of snapshots allowed per day. -->
    <SnapshotsPerDayLimit>30</SnapshotsPerDayLimit>
    <!-- Whether or not to collect snapshot in low IO priority thread. The default value is true. -->
    <SnapshotInLowPriorityThread>true</SnapshotInLowPriorityThread>
    <!-- Agree to send anonymous data to Microsoft to make this product better. -->
    <ProvideAnonymousTelemetry>true</ProvideAnonymousTelemetry>
    <!-- The limit on the number of failed requests to request snapshots before the telemetry processor is disabled. -->
    <FailedRequestLimit>3</FailedRequestLimit>
  </Add>
</TelemetryProcessors>

يتم تجميع اللقطات فقط على الاستثناءات التي تم الإبلاغ عنها إلى Application Insights. في بعض الحالات (على سبيل المثال، الإصدارات الأقدم من منصة .NET)، قد تحتاج إلىضبط مجموعة الاستثناءاتلمشاهدة استثناءات مع لقطات في المدخل.

تكوين مجموعة اللقطات لتطبيقات ASP.NET الأساسية أو خدمات العامل

المتطلبات الأساسية

يجب أن يشير تطبيقك بالفعل إلى إحدى حزم Application Insights NuGet التالية:

إضافة حزمة NuGet

أضف حزمة Microsoft.ApplicationInsights.SnapshotCollector NuGet إلى تطبيقك.

تحديث مجموعة الخدمات

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

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddApplicationInsightsTelemetry();
builder.Services.AddSnapshotCollector();

تكوين Snapshot Collector

بالنسبة لمعظم الحالات، تكون الإعدادات الافتراضية كافية. إذا لم يكن الأمر كما هو، فقم بتخصيص الإعدادات عن طريق إضافة التعليمات البرمجية التالية قبل الاستدعاء إلى AddSnapshotCollector()

using Microsoft.ApplicationInsights.SnapshotCollector;
...
builder.Services.Configure<SnapshotCollectorConfiguration>(builder.Configuration.GetSection("SnapshotCollector"));

بعد ذلك، أضف مقطعا SnapshotCollector إلى appsettings.json حيث يمكنك تجاوز الإعدادات الافتراضية. يوضح المثال التالي تكوينا مكافئا للتكوين الافتراضي:

{
  "SnapshotCollector": {
    "IsEnabledInDeveloperMode": false,
    "ThresholdForSnapshotting": 1,
    "MaximumSnapshotsRequired": 3,
    "MaximumCollectionPlanSize": 50,
    "ReconnectInterval": "00:15:00",
    "ProblemCounterResetInterval":"1.00:00:00",
    "SnapshotsPerTenMinutesLimit": 1,
    "SnapshotsPerDayLimit": 30,
    "SnapshotInLowPriorityThread": true,
    "ProvideAnonymousTelemetry": true,
    "FailedRequestLimit": 3
  }
}

إذا كنت بحاجة إلى تخصيص سلوك Snapshot Collector يدويا، دون استخدام appsettings.json، فاستخدم التحميل الزائد AddSnapshotCollector الذي يأخذ مفوضا. على سبيل المثال:

builder.Services.AddSnapshotCollector(config => config.IsEnabledInDeveloperMode = true);

ضبط مجموعة لقطات لتطبيقات .NET أخرى

يتم تجميع اللقطات فقط في استثناءات يتم إبلاغها إلى Application Insights. بالنسبة ASP.NET والتطبيقات الأساسية ASP.NET، يقوم Application Insights SDK تلقائيا بالإبلاغ عن الاستثناءات غير المعالجة التي تهرب من أسلوب وحدة تحكم أو معالج مسار نقطة النهاية. بالنسبة للتطبيقات الأخرى، قد تحتاج إلى تعديل التعليمات البرمجية للإبلاغ عنها. تعتمد التعليمات البرمجية لمعالجة الاستثناء على بنية التطبيق الخاص بك. إليك مثال:

using Microsoft.ApplicationInsights;
using Microsoft.ApplicationInsights.DataContracts;
using Microsoft.ApplicationInsights.Extensibility;

internal class ExampleService
{
  private readonly TelemetryClient _telemetryClient;

  public ExampleService(TelemetryClient telemetryClient)
  {
    // Obtain the TelemetryClient via dependency injection.
    _telemetryClient = telemetryClient;
  }

  public void HandleExampleRequest()
  {
    using IOperationHolder<RequestTelemetry> operation = 
        _telemetryClient.StartOperation<RequestTelemetry>("Example");
    try
    {
      // TODO: Handle the request.
      operation.Telemetry.Success = true;
    }
    catch (Exception ex)
    {
      // Report the exception to Application Insights.
      operation.Telemetry.Success = false;
      _telemetryClient.TrackException(ex);
      // TODO: Rethrow the exception if desired.
    }
  }
}

يستخدم ILogger المثال التالي بدلا من TelemetryClient. يفترض هذا المثال أنك تستخدم موفر مسجل Application Insights. كما يوضح المثال، عند معالجة استثناء، تأكد من تمرير الاستثناء كمعلمة أولى إلى LogError.

using Microsoft.Extensions.Logging;

internal class LoggerExample
{
  private readonly ILogger _logger;

  public LoggerExample(ILogger<LoggerExample> logger)
  {
    _logger = logger;
  }

  public void HandleExampleRequest()
  {
    using IDisposable scope = _logger.BeginScope("Example");
    try
    {
      // TODO: Handle the request
    }
    catch (Exception ex)
    {
      // Use the LogError overload with an Exception as the first parameter.
      _logger.LogError(ex, "An error occurred.");
    }
  }
}

إشعار

بشكل افتراضي، يقوم Application Insights Logger (ApplicationInsightsLoggerProvider) بإعادة توجيه الاستثناءات إلى Snapshot Debugger عبر TelemetryClient.TrackException. يتم التحكم في هذا السلوك عبر الخاصية TrackExceptionsAsExceptionTelemetry في ApplicationInsightsLoggerOptions الفئة . إذا قمت بتعيين TrackExceptionsAsExceptionTelemetry إلى false عند تكوين Application Insights Logger، فلن يقوم المثال السابق بتشغيل Snapshot Debugger. في هذه الحالة، قم بتعديل التعليمات البرمجية لاستدعاء TrackException يدويا.

إشعار

في 31 مارس 2025، سينتهي دعم إدخال مفاتيح الأجهزة. سيستمر استيعاب مفتاح الأجهزة في العمل ولكننا لن نقوم بتوفير تحديثات أو أي دعم للميزة. الانتقال إلى سلاسل الاتصال للاستفادة من الإمكانات الجديدة.

الخطوات التالية