Application Insights لتطبيقات ASP.NET Core

مقالة
01/31/2024

توضح هذه المقالة كيفية تمكين Application Insights وتكوينه لتطبيق ASP.NET Core.

إشعار

تعتمد الوثائق التالية على واجهة برمجة تطبيقات Application Insights الكلاسيكية. الخطة طويلة الأجل ل Application Insights هي جمع البيانات باستخدام OpenTelemetry. لمزيد من المعلومات، راجع تمكين Azure Monitor OpenTelemetry لتطبيقات .NET Node.js وPython وJava.

يمكن لـ Application Insights جمع بيانات تتبع الاستخدام التالية من تطبيق ASP.NET Core:

الطلبات
التبعيات
استثناءات
عدادات الأداء
رسائل كشف أخطاء الاتصال
السجلات

نستخدم مثال تطبيق MVC. إذا كنت تستخدم خدمة العامل، فاستخدم الإرشادات الموجودة في Application Insights لتطبيقات خدمة العامل.

يتوفر عرض .NET المستند إلى OpenTelemetry. لمزيد من المعلومات، راجع نظرة عامة على OpenTelemetry.

إشعار

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

إشعار

إذا كنت تريد استخدام موفر ILogger مستقل، فاستخدم Microsoft.Extensions.Logging.ApplicationInsight.

السيناريوهات المدعومة

يمكن لـ Application Insights SDK لـ ASP.NET Core مراقبة تطبيقاتك بغض النظر عن مكان تشغيلها أو كيفية تشغيلها. إذا كان التطبيق الخاص بك قيد التشغيل ولديه اتصال بالشبكة بـ Azure ، فيمكن جمع بيانات القياس عن بُعد. يتم دعم مراقبة Application Insights في كل مكان يتم دعم NET Core فيه وتغطي السيناريوهات التالية:

نظام التشغيل: Windows أو Linux أو Mac
طريقة الاستضافة: في العملية أو خارج العملية
طريقة النشر: تعتمد على الإطار أو قائمة بذاتها
خادم الويب: خادم معلومات الإنترنت (IIS) أو Kestrel
منصة الاستضافة: ميزة تطبيقات الويب لخدمة تطبيقات Azure وأجهزة Azure الظاهرية وDocker وخدمة Azure Kubernetes (AKS)
إصدار .NET: جميع إصدارات .NET المدعومة رسميا والتي ليست قيد المعاينة
IDE: Visual Studio أو Visual Studio Code أو سطر الأوامر

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

تحتاج إلى

تطبيق ASP.NET Core يعمل. إذا كنت بحاجة إلى إنشاء تطبيق ASP.NET Core، فاتبع هذاالبرنامج التعليمي لـASP.NET Core.
مرجع إلى إصدار مدعوم من حزمة Application Insights NuGet.
سلسلة اتصال Application Insights صالحة. هذا المفتاح مطلوب لإرسال أيّ بيانات تتبع إلى Application Insights. إذا كنت بحاجة إلى إنشاء مورد Application Insights جديد للحصول على سلسلة اتصال، فراجع إنشاء مورد Application Insights.

تمكين القياس عن بعد من جانب الخادم Application Insights (Visual Studio)

بالنسبة لبرنامج Visual Studio لـMac، استخدم التوجيه اليدوي. يدعم إصدار Windows من Visual Studio فقط هذا الإجراء.

افتح مشروعك في Visual Studio
انتقل إلى Project>Add Application Insights Telemetry.
حدد Azure Application Insights>Next.
اختر اشتراكك ومثيل Application Insights. أو يمكنك إنشاء مثيل جديد باستخدام Create new. حدد التالي.
إضافة سلسلة الاتصال Application Insights أو تأكيده. يجب أن تكون محجوبة مسبقا بناء على اختيارك في الخطوة السابقة. حدد إنهاء.
بعد إضافة Application Insights إلى مشروعك، تحقق للتأكد من أنك تستخدم أحدث إصدار ثابت من SDK. انتقل إلى Project>إدارة حزم NuGet>Microsoft.ApplicationInsights.AspNetCore. إذا كنت بحاجة إلى ذلك، فحدد «تحديث».

تمكين القياس عن بعد من جانب الخادم Application Insights (بدون Visual Studio)

قم بتثبيت حزمة Application Insights SDK NuGet لـ ASP.NET Core.

نوصي باستخدام أحدث إصدار ثابت دائمًا. ابحث عن ملاحظات الإصدار الكاملة لـ SDK على GitHub repo مفتوح المصدر.

يظهر نموذج التعليمات البرمجية التالي التغييرات التي يجب إضافتها إلى ملف مشروعك .csproj :
```
<ItemGroup>
    <PackageReference Include="Microsoft.ApplicationInsights.AspNetCore" Version="2.21.0" />
</ItemGroup>
```

أضف AddApplicationInsightsTelemetry() إلى الصف أو program.cs الخاص بكstartup.cs. يعتمد الاختيار على إصدار .NET Core.

ASP.NET Core 6 والإصدارات الأحدث
ASP.NET Core 5 والإصدارات السابقة

أضف builder.Services.AddApplicationInsightsTelemetry(); إلى الأسلوب WebApplication.CreateBuilder() في فئة Program الخاصة بك، كما في هذا المثال:

// This method gets called by the runtime. Use this method to add services to the container.
var builder = WebApplication.CreateBuilder(args);

// The following line enables Application Insights telemetry collection.
builder.Services.AddApplicationInsightsTelemetry();

// This code adds other services for your application.
builder.Services.AddMvc();

var app = builder.Build();

إضافة services.AddApplicationInsightsTelemetry(); إلى الأسلوب في ConfigureServices()Startup الفئة الخاصة بك، كما في هذا المثال:

// This method gets called by the runtime. Use this method to add services to the container.
public void ConfigureServices(IServiceCollection services)
{
    // The following line enables Application Insights telemetry collection.
    services.AddApplicationInsightsTelemetry();

    // This code adds other services for your application.
    services.AddMvc();
}

إشعار

لم يعد إصدار .NET هذا مدعوما.

تثبيت سلسلة الاتصال.

على الرغم من أنه يمكنك توفير سلسلة الاتصال كجزء من الوسيطة ApplicationInsightsServiceOptions إلى AddApplicationInsightsTelemetry، نوصي بتحديد سلسلة الاتصال في التكوين. يوضح نموذج التعليمات البرمجية التالي كيفية تحديد سلسلة اتصال في appsettings.json. تأكد من نسخهappsettings.json إلى المجلد الجذر للتطبيق أثناء النشر.
```
{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "AllowedHosts": "*",
  "ApplicationInsights": {
    "ConnectionString": "Copy connection string from Application Insights Resource Overview"
  }
}
```
بدلا من ذلك، حدد سلسلة الاتصال في APPLICATIONINSIGHTS_CONNECTION_STRING متغير البيئة أو ApplicationInsights:ConnectionString في ملف تكوين JSON.

على سبيل المثال:
- SET ApplicationInsights:ConnectionString = <Copy connection string from Application Insights Resource Overview>
- SET APPLICATIONINSIGHTS_CONNECTION_STRING = <Copy connection string from Application Insights Resource Overview>
- عادة ما APPLICATIONINSIGHTS_CONNECTION_STRING يتم استخدام في تطبيقات الويب. كما يمكن استخدامه في جميع الأماكن التي يتم فيها دعم SDK هذا.
إشعار

يفوز سلسلة الاتصال المحدد في التعليمات البرمجية على متغير APPLICATIONINSIGHTS_CONNECTION_STRINGالبيئة ، والذي يفوز على الخيارات الأخرى.

أسرار المستخدم وموفري التكوين الآخرين

إذا كنت ترغب في تخزين سلسلة الاتصال في بيانات مستخدم ASP.NET Core السرية أو استردادها من موفر تكوين آخر، يمكنك استخدام التحميل الزائد مع المعلمة Microsoft.Extensions.Configuration.IConfiguration. معلمة المثال هي services.AddApplicationInsightsTelemetry(Configuration);.

في Microsoft.ApplicationInsights.AspNetCore الإصدار 2.15.0 والإصدارات الأحدث، يقرأ الاتصال services.AddApplicationInsightsTelemetry() تلقائيا سلسلة الاتصال من Microsoft.Extensions.Configuration.IConfiguration التطبيق. ليست هناك حاجة لتوفير IConfigurationبشكل صريح .

إذا قام IConfiguration بتحميل التكوين من موفرين متعددين، فعندئذ يعطي services.AddApplicationInsightsTelemetry الأولوية للتكوين من appsettings.json، بغض النظر عن الترتيب الذي تتم إضافة الموفرين به. services.AddApplicationInsightsTelemetry(IConfiguration) استخدم الأسلوب لقراءة التكوين من IConfiguration دون هذه المعاملة التفضيلية ل appsettings.json.

تشغيل التطبيق الخاص بك

قم بتشغيل التطبيق الخاص بك وتقديم الطلبات إليه. يجب أن يتدفق القياس عن بُعد الآن إلى Application Insights. يقوم تطبيق Insights SDK بتجميع طلبات الويب الواردة إلى التطبيق الخاص بك تلقائيًا، بالإضافة إلى القياس عن بعد التالي.

القياسات المباشرة

يمكن استخدام المقاييس المباشرة للتحقق بسرعة من تكوين مراقبة Application Insights بشكل صحيح. قد يستغرق ظهور التتبع عن بُعد في البوابة الإلكترونية والتحليلات بضع دقائق ، لكن Live Metrics تُظهر استخدام وحدة المعالجة المركزية للعملية الجارية في الوقت الفعلي تقريبًا. كما يمكن أن يظهر بيانات تتبع الاستخدام الأخرى مثل الطلبات والتبعيات والتتبعات.

سجلات ILogger

يقوم التكوين الافتراضي تجميع سجلات ILoggerWarning وسجلات أكثر شدة. لمزيد من المعلومات، راجع كيف أعمل تخصيص مجموعة سجلات ILogger؟.

التبعيات

يتم تمكين مجموعة التبعية بشكل افتراضي. يشرح تتبع التبعية في Application Insights التبعيات التي يتم جمعها تلقائيا ويحتوي أيضا على خطوات للقيام بالتتبع اليدوي.

عدادات الأداء

دعم عدادات الأداء في ASP.NET Core محدود:

تجمع إصدارات SDK 2.4.1 والإصدارات الأحدث عدادات الأداء إذا كان التطبيق قيد التشغيل في Web Apps (Windows).
تجمع إصدارات SDK 2.7.1 والإصدارات الأحدث عدّادات الأداء إذا كان التطبيق قيد التشغيل في Windows ويستهدف netstandard2.0 أو إصدارات أحدث.
بالنسبة للتطبيقات التي تستهدف .NET Framework، تدعم جميع إصدارات SDK عدادات الأداء.
تدعم إصدارات SDK 2.8.0 والإصدارات الأحدث عداد وحدة المعالجة المركزية/الذاكرة في Linux. لا يوجد عدّاد آخر مدعوم في Linux. للحصول على عدادات النظام في Linux والبيئات الأخرى غير Windows، استخدم EventCounters.

EventCounter

يتم تمكينهEventCounterCollectionModule افتراضيًا. لمعرفة كيفية تكوين قائمة العدادات التي سيتم تجميعها، راجع مقدمة EventCounters.

إثراء البيانات من خلال HTTP

HttpContext.Features.Get<RequestTelemetry>().Properties["myProp"] = someData

تفعيل التتبع عن بعد من جانب العميل لتطبيقات الويب

الخطوات السابقة كافية لمساعدتك على البدء في جمع التتبع عن بعد من جانب الخادم. إذا كان التطبيق الخاص بك يحتوي على مكونات من جانب العميل، فاتبع الخطوات التالية لبدء جمع بيانات تتبع الاستخدام باستخدام حقن برنامج JavaScript (Web) SDK Loader Script حسب التكوين.

في _ViewImports.cshtml ، أضف الحقن:

@inject Microsoft.ApplicationInsights.AspNetCore.JavaScriptSnippet JavaScriptSnippet

في _Layout.cshtml ، إدراج في HtmlHelper نهاية القسم ولكن قبل أي برنامج نصي <head> آخر. إذا كنت تريد الإبلاغ عن أي تتبع JavaScript مخصص عن بُعد من الصفحة، فأدخله بعد هذه القصاصة البرمجية:
```
@Html.Raw(JavaScriptSnippet.FullScript)
</head>
```

كبديل لاستخدام FullScript، ScriptBody يتوفر بدءا من Application Insights SDK ل ASP.NET Core الإصدار 2.14. استخدم ScriptBody إذا كنت بحاجة إلى التحكم في العلامة <script> لتعيين نهج أمان المحتوى:

<script> // apply custom changes to this script tag.
 @Html.Raw(JavaScriptSnippet.ScriptBody)
</script>

أسماء .cshtmlالملفات المشار إليها سابقًا مأخوذة من قالب تطبيق MVC افتراضي. في النهاية، إذا كنت تريد تمكين المراقبة من جانب العميل للتطبيق الخاص بك بشكل صحيح، يجب أن يظهر برنامج JavaScript JavaScript JavaScript (Web) SDK Loader Script في <head> قسم كل صفحة من التطبيق الخاص بك التي تريد مراقبتها. أضف JavaScript JavaScript (Web) SDK Loader Script إلى _Layout.cshtml في قالب تطبيق لتمكين المراقبة من جانب العميل.

إذا لم يتضمن _Layout.cshtmlمشروعك ، فلا يزال بإمكانك إضافة مراقبة من جانب العميل عن طريق إضافة برنامج JavaScript JavaScript (Web) SDK Loader Script إلى ملف مكافئ يتحكم في <head> جميع الصفحات داخل تطبيقك. بدلا من ذلك، يمكنك إضافة برنامج JavaScript (Web) SDK Loader Script إلى صفحات متعددة، ولكننا لا نوصي بذلك.

إشعار

يوفر حقن JavaScript تجربة تكوين افتراضية. إذا كنت بحاجة إلى تكوين يتجاوز إعداد سلسلة الاتصال، فأنت مطالب بإزالة الحقن التلقائي كما هو موضح وإضافة JavaScript SDK يدويا.

قم بتكوين Application Insights SDK

يمكنك تخصيص Application Insights SDK لـ ASP.NET Core لتغيير التكوين الافتراضي. قد يكون مستخدمو Application Insights ASP.NET SDK على دراية بتغيير التكوين باستخدام ApplicationInsights.config أو عن طريق تعديل TelemetryConfiguration.Active. بالنسبة لـASP.NET Core ، قم بإجراء جميع تغييرات التكوين تقريبًا في طريقة ConfigureServices()الفئةStartup.cs، ما لم يتم توجيهك بخلاف ذلك. تقدم الأقسام التالية المزيد من المعلومات.

إشعار

في تطبيقات ASP.NET Core، لا يتمTelemetryConfiguration.Active دعم تغيير التكوين عن طريق التعديل.

استخدام ApplicationInsightsServiceOptions

يمكنك تعديل بعض الإعدادات الشائعة عن طريق التمرير ApplicationInsightsServiceOptions إلى، كما في هذا AddApplicationInsightsTelemetry المثال:

ASP.NET Core 6 والإصدارات الأحدث
ASP.NET Core 5 والإصدارات السابقة

var builder = WebApplication.CreateBuilder(args);

var aiOptions = new Microsoft.ApplicationInsights.AspNetCore.Extensions.ApplicationInsightsServiceOptions();

// Disables adaptive sampling.
aiOptions.EnableAdaptiveSampling = false;

// Disables QuickPulse (Live Metrics stream).
aiOptions.EnableQuickPulseMetricStream = false;

builder.Services.AddApplicationInsightsTelemetry(aiOptions);
var app = builder.Build();

public void ConfigureServices(IServiceCollection services)
{
    Microsoft.ApplicationInsights.AspNetCore.Extensions.ApplicationInsightsServiceOptions aiOptions
                = new Microsoft.ApplicationInsights.AspNetCore.Extensions.ApplicationInsightsServiceOptions();
    // Disables adaptive sampling.
    aiOptions.EnableAdaptiveSampling = false;

    // Disables QuickPulse (Live Metrics stream).
    aiOptions.EnableQuickPulseMetricStream = false;
    services.AddApplicationInsightsTelemetry(aiOptions);
}

إشعار

لم يعد إصدار .NET هذا مدعوما.

يحتوي هذا الجدول على ApplicationInsightsServiceOptionsالقائمة الكاملة للإعدادات:

الإعدادات	‏‏الوصف	الإعداد الافتراضي
EnablePerformanceCounterCollectionModule	تمكين/تعطيل`PerformanceCounterCollectionModule`	صواب
EnableRequestTrackingTelemetryModule	تمكين/تعطيل`RequestTrackingTelemetryModule`	صواب
EnableEventCounterCollectionModule	تمكين/تعطيل`EventCounterCollectionModule`	صواب
EnableDependencyTrackingTelemetryModule	تمكين/تعطيل`DependencyTrackingTelemetryModule`	صواب
EnableAppServicesHeartbeatTelemetryModule	تمكين/تعطيل`AppServicesHeartbeatTelemetryModule`	صواب
EnableAzureInstanceMetadataTelemetryModule	تمكين/تعطيل`AzureInstanceMetadataTelemetryModule`	صواب
تمكين QuickPulseMetricStream	تمكين/تعطيل ميزة LiveMetrics.	صواب
EnableAdaptiveSampling	تمكين/تعطيل أخذ العينات التكيفية.	صواب
EnableHeartbeat	تمكين/تعطيل ميزة رسالة كشف أخطاء الاتصال. يرسل بشكل دوري (افتراضي 15 دقيقة) مقياسا مخصصا يسمى `HeartbeatState` بمعلومات حول وقت التشغيل مثل إصدار .NET ومعلومات بيئة Azure، إن أمكن.	صواب
AddAutoCollectedMetricExtractor	تمكين/تعطيل `AutoCollectedMetrics extractor`. يرسل معالج بيانات تتبع الاستخدام هذا مقاييس مجمعة مسبقا حول الطلبات/التبعيات قبل أخذ العينات.	صواب
طلبCollectionOptions.TrackExceptions	تمكين/تعطيل الإبلاغ عن تتبع الاستثناء غير المعالج بواسطة وحدة مجموعة الطلب.	خطأ في `netstandard2.0` (لأنه يتم تعقب الاستثناءات باستخدام `ApplicationInsightsLoggerProvider`). صحيح خلاف ذلك.
EnableDiagnosticsTelemetryModule	تمكين/تعطيل`DiagnosticsTelemetryModule` يؤدي تعطيل إلى تجاهل الإعدادات التالية: `EnableHeartbeat`و `EnableAzureInstanceMetadataTelemetryModule`و.`EnableAppServicesHeartbeatTelemetryModule`	صواب

للحصول على أحدث قائمة، راجع الإعدادات القابلة للتكوين بتنسيق ApplicationInsightsServiceOptions.

توصية التكوين لـMicrosoft.ApplicationInsights.AspNetCore SDK 2.15.0 والأحدث

في Microsoft.ApplicationInsights.AspNetCore SDK الإصدار 2.15.0 والإصدارات الأحدث، قم بتكوين كل إعداد متوفر في ، بما في ApplicationInsightsServiceOptionsذلك ConnectionString. استخدم مثيل التطبيق IConfiguration . يجب أن تكون الإعدادات ضمن القسم ApplicationInsights، كما هو موضح في المثال التالي. يقوم القسم التالي من appsettings.json بتكوين سلسلة الاتصال وتعطيل أخذ العينات التكيفية وجمع عداد الأداء.

{
    "ApplicationInsights": {
    "ConnectionString": "Copy connection string from Application Insights Resource Overview",
    "EnableAdaptiveSampling": false,
    "EnablePerformanceCounterCollectionModule": false
    }
}

إذا تم استخدام builder.Services.AddApplicationInsightsTelemetry(aiOptions) لـ ASP.NET Core 6.0 أو services.AddApplicationInsightsTelemetry(aiOptions) لـ ASP.NET Core 3.1 والإصدارات السابقة، فإنه يتجاوز الإعدادات من Microsoft.Extensions.Configuration.IConfiguration.

أخذ عينات

يدعم Application Insights SDK لـ ASP.NET Core أخذ العينات بمعدل ثابت ومعدل تكيفي. يتم تمكين أخذ العينات التكيفية بشكل افتراضي.

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

إضافة TelemetryInitializers

عندما تريد إثراء بيانات تتبع الاستخدام بمزيد من المعلومات، استخدم مهيئات بيانات تتبع الاستخدام.

إضافة أي جديد TelemetryInitializer إلى DependencyInjection الحاوية كما هو موضح في التعليمات البرمجية التالية. تلتقط SDK تلقائيًاTelemetryInitializerأية إضافة إلى DependencyInjection الحاوية.

ASP.NET Core 6 والإصدارات الأحدث
ASP.NET Core 5 والإصدارات السابقة

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddSingleton<ITelemetryInitializer, MyCustomTelemetryInitializer>();

var app = builder.Build();

إشعار

builder.Services.AddSingleton<ITelemetryInitializer, MyCustomTelemetryInitializer>();يعمل على التهيئة البسيطة. بالنسبة للآخرين، builder.Services.AddSingleton(new MyCustomTelemetryInitializer() { fieldName = "myfieldName" }); مطلوب.

public void ConfigureServices(IServiceCollection services)
{
    services.AddSingleton<ITelemetryInitializer, MyCustomTelemetryInitializer>();
}

إشعار

services.AddSingleton<ITelemetryInitializer, MyCustomTelemetryInitializer>();يعمل على التهيئة البسيطة. بالنسبة للآخرين، services.AddSingleton(new MyCustomTelemetryInitializer() { fieldName = "myfieldName" }); مطلوب. لم يعد إصدار .NET هذا مدعوما.

إزالة TelemetryInitializers

افتراضيًا، توجد مُهيئات بيانات تتبع الاستخدام عن بُعد. لإزالة جميع بيانات تتبع الاستخدام أو المُحددة منها، استخدم نموذج التعليمات البرمجية التالي بعد الاتصال AddApplicationInsightsTelemetry().

ASP.NET Core 6 والإصدارات الأحدث
ASP.NET Core 5 والإصدارات السابقة

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddApplicationInsightsTelemetry();

// Remove a specific built-in telemetry initializer
var tiToRemove = builder.Services.FirstOrDefault<ServiceDescriptor>
                    (t => t.ImplementationType == typeof(AspNetCoreEnvironmentTelemetryInitializer));
if (tiToRemove != null)
{
    builder.Services.Remove(tiToRemove);
}

// Remove all initializers
// This requires importing namespace by using Microsoft.Extensions.DependencyInjection.Extensions;
builder.Services.RemoveAll(typeof(ITelemetryInitializer));

var app = builder.Build();

public void ConfigureServices(IServiceCollection services)
{
    services.AddApplicationInsightsTelemetry();

    // Remove a specific built-in telemetry initializer
    var tiToRemove = services.FirstOrDefault<ServiceDescriptor>
                        (t => t.ImplementationType == typeof(AspNetCoreEnvironmentTelemetryInitializer));
    if (tiToRemove != null)
    {
        services.Remove(tiToRemove);
    }

    // Remove all initializers
    // This requires importing namespace by using Microsoft.Extensions.DependencyInjection.Extensions;
    services.RemoveAll(typeof(ITelemetryInitializer));
}

إشعار

لم يعد إصدار .NET هذا مدعوما.

إضافة معالجات بيانات تتبع الاستخدام

يمكنك إضافة معالجات بيانات تتبع الاستخدامTelemetryConfigurationباستخدام طريقة الامتدادAddApplicationInsightsTelemetryProcessor فيIServiceCollection. تستخدم معالجات بيانات تتبع الاستخدام في سيناريوهات التصفية المتقدمة. استخدم المثال التالي:

ASP.NET Core 6 والإصدارات الأحدث
ASP.NET Core 5 والإصدارات السابقة

var builder = WebApplication.CreateBuilder(args);

// ...
builder.Services.AddApplicationInsightsTelemetry();
builder.Services.AddApplicationInsightsTelemetryProcessor<MyFirstCustomTelemetryProcessor>();

// If you have more processors:
builder.Services.AddApplicationInsightsTelemetryProcessor<MySecondCustomTelemetryProcessor>();

var app = builder.Build();

public void ConfigureServices(IServiceCollection services)
{
    // ...
    services.AddApplicationInsightsTelemetry();
    services.AddApplicationInsightsTelemetryProcessor<MyFirstCustomTelemetryProcessor>();

    // If you have more processors:
    services.AddApplicationInsightsTelemetryProcessor<MySecondCustomTelemetryProcessor>();
}

إشعار

لم يعد إصدار .NET هذا مدعوما.

تكوين أو إزالة الوحدات الافتراضية لبيانات تتبع الاستخدام

يجمع Application Insights تلقائيًا بيانات تتبع الاستخدام حول أحمال عمل معينة دون الحاجة إلى تتبع يدوي من قبل المستخدم.

بشكل افتراضي، يتم تمكين الوحدات النمطية التالية التجميع التلقائي. هذه الوحدات مسؤولة عن بيانات تتبع الاستخدام تلقائيًا. يمكنك تعطيلها أو تكوينها لتغيير سلوكها الافتراضي.

RequestTrackingTelemetryModule: يجمع RequestTelemetry من طلبات الويب الواردة.
DependencyTrackingTelemetryModule: يجمع DependencyTelemetry من مكالمات HTTP الصادرة ومكالمات SQL.
PerformanceCollectorModule: يجمع Windows PerformanceCounters.
QuickPulseTelemetryModule: يجمع بيانات تتبع الاستخدام لإظهارها في مدخل Live Metrics.
AppServicesHeartbeatTelemetryModule: يجمع رسائل كشف أخطاء الاتصال (التي يتم إرسالها كمقاييس مخصصة)، حول بيئة App Service حيث تتم استضافة التطبيق.
AzureInstanceMetadataTelemetryModule: يجمع رسائل كشف أخطاء الاتصال (التي يتم إرسالها كمقاييس مخصصة)، حول بيئة Azure VM حيث تتم استضافة التطبيق.
EventCounterCollectionModule: يجمع EventCounters. هذه الوحدة النمطية هي ميزة جديدة ومتاحة في الإصدار 2.8.0 من SDK والإصدارات الأحدث.

لتكوين أي افتراضي TelemetryModule، استخدم أسلوب ConfigureTelemetryModule<T> الملحق على IServiceCollection، كما هو موضح في المثال التالي:

ASP.NET Core 6 والإصدارات الأحدث
ASP.NET Core 5 والإصدارات السابقة

using Microsoft.ApplicationInsights.DependencyCollector;
using Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddApplicationInsightsTelemetry();

// The following configures DependencyTrackingTelemetryModule.
// Similarly, any other default modules can be configured.
builder.Services.ConfigureTelemetryModule<DependencyTrackingTelemetryModule>((module, o) =>
        {
            module.EnableW3CHeadersInjection = true;
        });

// The following removes all default counters from EventCounterCollectionModule, and adds a single one.
builder.Services.ConfigureTelemetryModule<EventCounterCollectionModule>((module, o) =>
        {
            module.Counters.Add(new EventCounterCollectionRequest("System.Runtime", "gen-0-size"));
        });

// The following removes PerformanceCollectorModule to disable perf-counter collection.
// Similarly, any other default modules can be removed.
var performanceCounterService = builder.Services.FirstOrDefault<ServiceDescriptor>(t => t.ImplementationType == typeof(PerformanceCollectorModule));
if (performanceCounterService != null)
{
    builder.Services.Remove(performanceCounterService);
}

var app = builder.Build();

using Microsoft.ApplicationInsights.DependencyCollector;
using Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector;

public void ConfigureServices(IServiceCollection services)
{
    services.AddApplicationInsightsTelemetry();

    // The following configures DependencyTrackingTelemetryModule.
    // Similarly, any other default modules can be configured.
    services.ConfigureTelemetryModule<DependencyTrackingTelemetryModule>((module, o) =>
            {
                module.EnableW3CHeadersInjection = true;
            });

    // The following removes all default counters from EventCounterCollectionModule, and adds a single one.
    services.ConfigureTelemetryModule<EventCounterCollectionModule>(
            (module, o) =>
            {
                module.Counters.Add(new EventCounterCollectionRequest("System.Runtime", "gen-0-size"));
            }
        );

    // The following removes PerformanceCollectorModule to disable perf-counter collection.
    // Similarly, any other default modules can be removed.
    var performanceCounterService = services.FirstOrDefault<ServiceDescriptor>(t => t.ImplementationType == typeof(PerformanceCollectorModule));
    if (performanceCounterService != null)
    {
        services.Remove(performanceCounterService);
    }
}

إشعار

لم يعد إصدار .NET هذا مدعوما.

في الإصدارات 2.12.2 والإصدارات الأحدثApplicationInsightsServiceOptions، يتضمن خيارًا سهلًا لتعطيل أي من الوحدات النمطية الافتراضية.

كوّن قناة بيانات تتبع الاستخدام

قناة بيانات تتبع الاستخدامالافتراضية هي ServerTelemetryChannel. يوضح المثال التالي كيفية تجاوزها.

ASP.NET Core 6 والإصدارات الأحدث
ASP.NET Core 5 والإصدارات السابقة

using Microsoft.ApplicationInsights.Channel;

var builder = WebApplication.CreateBuilder(args);

// Use the following to replace the default channel with InMemoryChannel.
// This can also be applied to ServerTelemetryChannel.
builder.Services.AddSingleton(typeof(ITelemetryChannel), new InMemoryChannel() {MaxTelemetryBufferCapacity = 19898 });

builder.Services.AddApplicationInsightsTelemetry();

var app = builder.Build();

using Microsoft.ApplicationInsights.Channel;

public void ConfigureServices(IServiceCollection services)
{
    // Use the following to replace the default channel with InMemoryChannel.
    // This can also be applied to ServerTelemetryChannel.
    services.AddSingleton(typeof(ITelemetryChannel), new InMemoryChannel() {MaxTelemetryBufferCapacity = 19898 });

    services.AddApplicationInsightsTelemetry();
}

إشعار

لم يعد إصدار .NET هذا مدعوما.

إشعار

إذا كنت تريد مسح المخزن المؤقت، فشاهد مسح البيانات. على سبيل المثال، قد تحتاج إلى مسح المخزن المؤقت إذا كنت تستخدم SDK في تطبيق يتم إيقاف تشغيله.

تعطيل بيانات تتبع الاستخدام ديناميكيًا

إذا كنت تريد تعطيل بيانات تتبع الاستخدام بشكل مشروط وديناميكي، فيمكنك TelemetryConfigurationحل المثيل باستخدام حاوية حقن التبعية ASP.NET Core في أي مكان في التعليمات البرمجيةDisableTelemetry الخاصة بك وتعيين العلامة عليها.

ASP.NET Core 6 والإصدارات الأحدث
ASP.NET Core 5 والإصدارات السابقة

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddApplicationInsightsTelemetry();

// any custom configuration can be done here:
builder.Services.Configure<TelemetryConfiguration>(x => x.DisableTelemetry = true);

var app = builder.Build();

public void ConfigureServices(IServiceCollection services)
{
    services.AddApplicationInsightsTelemetry();
}

public void Configure(IApplicationBuilder app, IHostingEnvironment env, TelemetryConfiguration configuration)
{
    configuration.DisableTelemetry = true;
    ...
}

إشعار

لم يعد إصدار .NET هذا مدعوما.

يمنع نموذج التعليمات البرمجية السابق إرسال بيانات تتبع الاستخدام إلى Application Insights. لا يمنع أي وحدات جمع تلقائية من جمع بيانات تتبع الاستخدام. إذا كنت ترغب في إزالة وحدة نمطية معينة للتكوين التلقائي، فشاهد إزالة وحدة القياس عن بعد.

الأسئلة الشائعة

يقدم هذا القسم إجابات للأسئلة الشائعة.

هل يدعم Application Insights ASP.NET Core 3.1؟

لم تعد Microsoft تدعم ASP.NET Core 3.1.

يمكن استخدام Application Insights SDK ل ASP.NET Core الإصدار 2.8.0 وVisual Studio 2019 أو أحدث مع تطبيقات ASP.NET Core 3.1.

كيف يمكنني تتبع بيانات تتبع الاستخدام الذي لا يتم جمعه تلقائيًا؟

الحصول على مثيل TelemetryClient باستخدام حقن الدالة الإنشائية واستدعاء الأسلوب المطلوب TrackXXX() عليه. لا نوصي بإنشاء مثيلات جديدةTelemetryClientأو مثيلات TelemetryConfigurationفي تطبيق ASP.NET Core. تم تسجيل مثيل أحادي من TelemetryClient بالفعل في الحاوية DependencyInjection ، والتي تشترك TelemetryConfiguration مع بقية بيانات تتبع الاستخدام. إنشاء مثيل جديد TelemetryClient فقط إذا كان بحاجة إلى تكوين منفصل عن بقية بيانات تتبع الاستخدام.

يوضح المثال التالي كيفية تعقب بيانات تتبع الاستخدام الإضافية من وحدة تحكم.

using Microsoft.ApplicationInsights;

public class HomeController : Controller
{
    private TelemetryClient telemetry;

    // Use constructor injection to get a TelemetryClient instance.
    public HomeController(TelemetryClient telemetry)
    {
        this.telemetry = telemetry;
    }

    public IActionResult Index()
    {
        // Call the required TrackXXX method.
        this.telemetry.TrackEvent("HomePageRequested");
        return View();
    }

لمزيد من المعلومات حول تقارير البيانات المخصصة في Application Insights، راجعمرجع واجهة برمجة التطبيقات للمقاييس المخصصة لتطبيق Application Insights. يمكن استخدام نهج مماثل لإرسال مقاييس مخصصة إلى Application Insights باستخدام واجهة برمجة تطبيقات GetMetric.

كيف أعمل التقاط نص الطلب والاستجابة في بيانات تتبع الاستخدام الخاصة بي؟

يحتوي ASP.NET Core على دعم مضمن لتسجيل معلومات طلب/استجابة HTTP (بما في ذلك النص الأساسي) عبر ILogger. من المستحسن الاستفادة من هذا. قد يعرض هذا معلومات التعريف الشخصية (PII) في بيانات تتبع الاستخدام، ويمكن أن يتسبب في زيادة التكاليف (تكاليف الأداء وفواتير Application Insights) بشكل كبير، لذا قم بتقييم المخاطر بعناية قبل استخدام هذا.

كيف يمكنني تخصيص مجموعة سجلات ILogger؟

الإعداد الافتراضي ل Application Insights هو تسجيل التحذير والسجلات الأكثر خطورة فقط.

التقاط المعلومات والسجلات الأقل خطورة عن طريق تغيير تكوين التسجيل لموفر Application Insights كما يلي.

{
  "Logging": {
    "LogLevel": {
      "Default": "Information"
    },
    "ApplicationInsights": {
      "LogLevel": {
        "Default": "Information"
      }
    }
  },
  "ApplicationInsights": {
    "ConnectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000"
  }
}

من المهم ملاحظة أن المثال التالي لا يتسبب في قيام موفر Application Insights بالتقاط Information السجلات. لا يتم التقاطها لأن SDK تضيف مرشح تسجيل افتراضيًا يرشدك إلىApplicationInsightsالتقاط السجلات فقطWarning وسجلات أكثر خطورة. يتطلب Application Insights تجاوزًا صريحًا.

{
  "Logging": {
    "LogLevel": {
      "Default": "Information"
    }
  }
}

لمزيد من المعلومات، راجع تكوين ILogger.

استخدمت بعض قوالب Visual Studio طريقة الامتداد UseApplicationInsights () على IWebHostBuilder لتمكين Application Insights. هل هذا الاستخدام لا يزال صالحًا؟

لا تزال طريقةUseApplicationInsights() الامتداد مدعومة ، ولكن تم تمييزها على أنها قديمة في Application Insights SDK الإصدار 2.8.0 والإصدارات الأحدث. تتم إزالته في الإصدار الرئيسي التالي من SDK. لتمكين القياس عن بعد ل Application Insights، استخدم AddApplicationInsightsTelemetry() لأنه يوفر تحميلا زائدا للتحكم في بعض التكوينات. أيضًا، في تطبيقات ASP.NET Core 3.X، services.AddApplicationInsightsTelemetry()هي الطريقة الوحيدة لتمكين Application Insights.

أنا أقوم بنشر تطبيق ASP.NET Core الخاص بي على تطبيقات الويب. هل يجب علي الاستمرار في تمكين ملحق Application Insights من تطبيقات الويب؟

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

يستمر القياس عن بعد ل Application Insights في العمل في:
- جميع أنظمة التشغيل، بما في ذلك Windows، Linux، وMac.
- جميع أوضاع النشر، بما في ذلك القائمة بذاتها أو التي تعتمد على إطار العمل.
- جميع الأطر المستهدفة، بما في ذلك .NET Framework الكامل.
- جميع خيارات الاستضافة، بما في ذلك تطبيقات الويب والأجهزة الظاهرية وLinux والحاويات وAKS والاستضافة غير Azure.
- جميع إصدارات .NET Core، بما في ذلك إصدارات المعاينة.
يمكنك رؤية القياس عن بُعد محليًا عند تصحيح الأخطاء من Visual Studio.
يمكنك تتبع التتبع عن بُعد المخصص الإضافي باستخدامTrackXXX()واجهة برمجة التطبيقات.
لديك سيطرة كاملة على التكوين.

هل يمكنني تمكين مراقبة Application Insights باستخدام أدوات مثل Azure Monitor Application Insights Agent (سابقًا Status Monitor v2)؟

نعم. في Application Insights Agent 2.0.0-beta1 والإصدارات الأحدث، يتم دعم تطبيقات ASP.NET Core المستضافة في IIS.

هل يتم دعم جميع الميزات إذا قمت بتشغيل تطبيقي في Linux؟

نعم. دعم الميزات لـSDK هو نفسه في جميع الأنظمة الأساسية، مع الاستثناءات التالية:

تجمع SDK عدادات الأحداث على Linux لأن عدادات الأداء مدعومة فقط في Windows. معظم المقاييس هي نفسها.

هل SDK هذا مدعوم لخدمات العامل؟

‏‏لا. يرجى استخدام Application Insights لتطبيقات خدمة العامل (تطبيقات غير HTTP) لخدمات العامل.

كيف يمكنني إلغاء تثبيت SDK؟

لإزالة Application Insights، تحتاج إلى إزالة حزم NuGet والمراجع من واجهة برمجة التطبيقات في التطبيق الخاص بك. يمكنك إلغاء تثبيت حزم NuGet باستخدام مدير الحِزَم NuGet في Visual Studio.

إشعار

هذه الإرشادات هي لإلغاء تثبيت ASP.NET Core SDK. إذا كنت بحاجة إلى إلغاء تثبيت ASP.NET SDK، فشاهد كيف يمكنني إلغاء تثبيت ASP.NET SDK؟.

قم بإلغاء تثبيت حزمة Microsoft.ApplicationInsights.AspNetCore باستخدام مدير الحِزَم NuGet.
لإزالة Application Insights بالكامل، تحقق من التعليمات البرمجية أو الملفات المضافة وحذفها يدويا مع أي استدعاءات واجهة برمجة التطبيقات التي أضفتها في مشروعك. لمزيد من المعلومات، راجع ما الذي يتم إنشاؤه عند إضافة Application Insights SDK؟.

ما الذي يتم إنشاؤه عند إضافة Application Insights SDK؟

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

عند إضافة بيانات تتبع الاستخدام الخاصة بـ Application Insights إلى مشروع قالب Visual Studio ASP.NET Core، فإنه يضيف التعليمة البرمجية التالية:

[اسم المشروع الخاص بك].csproj

  <PropertyGroup>
    <TargetFramework>netcoreapp3.1</TargetFramework>
    <ApplicationInsightsResourceId>/subscriptions/00000000-0000-0000-0000-000000000000/resourcegroups/Default-ApplicationInsights-EastUS/providers/microsoft.insights/components/WebApplication4core</ApplicationInsightsResourceId>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.ApplicationInsights.AspNetCore" Version="2.12.0" />
  </ItemGroup>

  <ItemGroup>
    <WCFMetadata Include="Connected Services" />
  </ItemGroup>

Appsettings.json:

"ApplicationInsights": {
    "InstrumentationKey": "00000000-0000-0000-0000-000000000000"

ConnectedService.json

{
  "ProviderId": "Microsoft.ApplicationInsights.ConnectedService.ConnectedServiceProvider",
  "Version": "16.0.0.0",
  "GettingStartedDocument": {
    "Uri": "https://go.microsoft.com/fwlink/?LinkID=798432"
  }
}

Startup.cs

   public void ConfigureServices(IServiceCollection services)
        {
            services.AddRazorPages();
            services.AddApplicationInsightsTelemetry(); // This is added
        }

استكشاف الأخطاء وإصلاحها

اختبار الاتصال بين مضيف التطبيق وخدمة الاستيعاب

ترسل Application Insights SDKs والوكلاء بيانات تتبع الاستخدام للحصول على استيعابها كمكالمات REST إلى نقاط نهاية الاستيعاب الخاصة بنا. يمكنك اختبار الاتصال من خادم الويب أو الجهاز المضيف للتطبيق إلى نقاط نهاية خدمة الاستيعاب باستخدام عملاء REST الخام من أوامر PowerShell أو curl. راجع استكشاف أخطاء بيانات تتبع استخدام التطبيق المفقودة وإصلاحها في Azure Monitor Application Insights.

عدة تطوير البرامج SDK مفتوحة المصدر

قراءة الرمز والمساهمة فيه.

للحصول على آخر التحديثات وإصلاحات الأخطاء، راجع ملاحظات الإصدار.

ملاحظات الإصدار

للحصول على الإصدار 2.12 وأحدث: .NET SDKs (بما في ذلك ASP.NET ASP.NET الذاكرة الأساسية ومحولات التسجيل)

التحديثات خدمتنا أيضا تلخيص تحسينات Application Insights الرئيسية.

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

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

Share via

Application Insights لتطبيقات ASP.NET Core

السيناريوهات المدعومة

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

تمكين القياس عن بعد من جانب الخادم Application Insights (Visual Studio)

تمكين القياس عن بعد من جانب الخادم Application Insights (بدون Visual Studio)

أسرار المستخدم وموفري التكوين الآخرين

تشغيل التطبيق الخاص بك

القياسات المباشرة

سجلات ILogger

التبعيات

عدادات الأداء

EventCounter

إثراء البيانات من خلال HTTP

تفعيل التتبع عن بعد من جانب العميل لتطبيقات الويب

قم بتكوين Application Insights SDK

استخدام ApplicationInsightsServiceOptions

توصية التكوين لـMicrosoft.ApplicationInsights.AspNetCore SDK 2.15.0 والأحدث

أخذ عينات

إضافة TelemetryInitializers

إزالة TelemetryInitializers

إضافة معالجات بيانات تتبع الاستخدام

تكوين أو إزالة الوحدات الافتراضية لبيانات تتبع الاستخدام

كوّن قناة بيانات تتبع الاستخدام

تعطيل بيانات تتبع الاستخدام ديناميكيًا

الأسئلة الشائعة

هل يدعم Application Insights ASP.NET Core 3.1؟

كيف يمكنني تتبع بيانات تتبع الاستخدام الذي لا يتم جمعه تلقائيًا؟

كيف أعمل التقاط نص الطلب والاستجابة في بيانات تتبع الاستخدام الخاصة بي؟

كيف يمكنني تخصيص مجموعة سجلات ILogger؟

استخدمت بعض قوالب Visual Studio طريقة الامتداد UseApplicationInsights () على IWebHostBuilder لتمكين Application Insights. هل هذا الاستخدام لا يزال صالحًا؟

أنا أقوم بنشر تطبيق ASP.NET Core الخاص بي على تطبيقات الويب. هل يجب علي الاستمرار في تمكين ملحق Application Insights من تطبيقات الويب؟

هل يمكنني تمكين مراقبة Application Insights باستخدام أدوات مثل Azure Monitor Application Insights Agent (سابقًا Status Monitor v2)؟

هل يتم دعم جميع الميزات إذا قمت بتشغيل تطبيقي في Linux؟

هل SDK هذا مدعوم لخدمات العامل؟

كيف يمكنني إلغاء تثبيت SDK؟

ما الذي يتم إنشاؤه عند إضافة Application Insights SDK؟

استكشاف الأخطاء وإصلاحها

اختبار الاتصال بين مضيف التطبيق وخدمة الاستيعاب

عدة تطوير البرامج SDK مفتوحة المصدر

ملاحظات الإصدار

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

الموارد الإضافية