为 ASP.NET 网站配置 Application InsightsConfigure Application Insights for your ASP.NET website

此过程将 ASP.NET Web 应用配置为将遥测发送到 Azure Application Insights 服务。This procedure configures your ASP.NET web app to send telemetry to the Azure Application Insights service. 它适用于托管在你自己的本地或云中 IIS 服务器上的 ASP.NET 应用。It works for ASP.NET apps that are hosted either in your own IIS servers on-premises or in the Cloud.

先决条件Prerequisites

若要要将 Application Insights 添加到 ASP.NET 网站,需要:To add Application Insights to your ASP.NET website, you need to:

如果没有 Azure 订阅,请在开始前创建一个试用帐户If you don't have an Azure subscription, create a trial account before you begin.

  • 创建基于工作区的 Application Insights 资源。Create an Application Insights workspace-based resource.

创建基本的 ASP.NET Web 应用Create a basic ASP.NET web app

  1. 启动 Visual Studio 2019。Launch Visual Studio 2019.
  2. 选择“文件” > “新建” > “项目” 。Select File > New > Project.
  3. 选择“ASP.NET Web 应用程序(.NET Framework) C#”。Select ASP.NET Web Application(.NET Framework) C#.
  4. 输入项目名称 > 选择“创建”。Enter a project name > Select Create.
  5. 选择“MVC” > “创建” 。Select MVC > Create.

自动添加 Application InsightsAdd Application Insights automatically

本部分将指导你将 Application Insights 自动添加到基于模板的 ASP.NET Web 应用。This section will guide you through automatically adding Application Insights to a template-based ASP.NET web app. 在 Visual Studio 中的 ASP.NET Web 应用项目中,请执行以下操作:From within your ASP.NET web app project in Visual Studio:

  1. 选择“添加 Application Insights 遥测” > “Application Insights Sdk (本地)” > “下一步” > “完成” > “关闭” 。Select Add Application Insights Telemetry > Application Insights Sdk (local) > Next > Finish > Close.

  2. 打开 ApplicationInsights.config 文件。Open the ApplicationInsights.config file.

  3. 在结束标记 </ApplicationInsights> 之前,添加一行,其中包含 Application Insights 资源的检测密钥。Before the closing </ApplicationInsights> tag add a line containing the instrumentation key for your Application Insights resource. 可以在新建的 Application Insights 资源(作为本文先决条件之一而创建)的“概述”窗格中找到检测密钥。Your instrumentation key can be found on the overview pane of your newly created Application Insights resource that you created as part of the prerequisites for this article.

    <InstrumentationKey>your-instrumentation-key-goes-here</InstrumentationKey>
    
  4. 选择“项目” > “管理 NuGet 包” > “更新”>“将每个 Microsoft.ApplicationInsights NuGet 包更新到最新的稳定版本” 。Select Project > Manage NuGet Packages > Updates > Update each Microsoft.ApplicationInsights NuGet package to the latest stable release.

  5. 通过选择“IIS Express”来运行应用程序。Run your application by selecting IIS Express. 将启动基本 ASP.NET 应用。A basic ASP.NET app will launch. 浏览站点上的页面时,遥测将发送到 Application Insights。As you navigate the pages on the site telemetry will be sent to Application Insights.

手动添加 Application InsightsAdd Application Insights manually

本部分将指导你将 Application Insights 手动添加到基于模板的 ASP.NET Web 应用。This section will guide you through manually adding Application Insights to a template-based ASP.NET web app. 本部分假定你使用的是基于标准 ASP.NET Framework MVC Web 应用模板的 Web 应用。This section assumes you are using a web app based on the standard ASP.NET Framework MVC web app template.

  1. 将以下 NuGet 包及其依赖项添加到项目中:Add the following NuGet packages and their dependencies to your project:

  2. 在某些情况下,将自动为你创建 ApplicationInsights.config 文件。In some cases, the ApplicationInsights.config file will be created for you automatically. 如果该文件已存在,请跳到步骤 #4。If the file is already present, skip to step #4. 如果没有自动创建,则需要自行创建。If it is not created automatically, then you will need to create it yourself. 在项目中与 Global.asax 文件相同的级别上,创建一个名为 ApplicationInsights.config 的新文件At the same level in your project as the Global.asax file, create a new file called ApplicationInsights.config

  3. 将以下 XML 配置复制到新创建的文件中:Copy the following XML configuration into your newly created file:

    <?xml version="1.0" encoding="utf-8"?>
    <ApplicationInsights xmlns="http://schemas.microsoft.com/ApplicationInsights/2013/Settings">
     <TelemetryInitializers>
       <Add Type="Microsoft.ApplicationInsights.DependencyCollector.HttpDependenciesParsingTelemetryInitializer, Microsoft.AI.DependencyCollector" />
       <Add Type="Microsoft.ApplicationInsights.WindowsServer.AzureRoleEnvironmentTelemetryInitializer, Microsoft.AI.WindowsServer" />
       <Add Type="Microsoft.ApplicationInsights.WindowsServer.BuildInfoConfigComponentVersionTelemetryInitializer, Microsoft.AI.WindowsServer" />
       <Add Type="Microsoft.ApplicationInsights.Web.WebTestTelemetryInitializer, Microsoft.AI.Web" />
       <Add Type="Microsoft.ApplicationInsights.Web.SyntheticUserAgentTelemetryInitializer, Microsoft.AI.Web">
         <!-- Extended list of bots:
               search|spider|crawl|Bot|Monitor|BrowserMob|BingPreview|PagePeeker|WebThumb|URL2PNG|ZooShot|GomezA|Google SketchUp|Read Later|KTXN|KHTE|Keynote|Pingdom|AlwaysOn|zao|borg|oegp|silk|Xenu|zeal|NING|htdig|lycos|slurp|teoma|voila|yahoo|Sogou|CiBra|Nutch|Java|JNLP|Daumoa|Genieo|ichiro|larbin|pompos|Scrapy|snappy|speedy|vortex|favicon|indexer|Riddler|scooter|scraper|scrubby|WhatWeb|WinHTTP|voyager|archiver|Icarus6j|mogimogi|Netvibes|altavista|charlotte|findlinks|Retreiver|TLSProber|WordPress|wsr-agent|http client|Python-urllib|AppEngine-Google|semanticdiscovery|facebookexternalhit|web/snippet|Google-HTTP-Java-Client-->
         <Filters>search|spider|crawl|Bot|Monitor|AlwaysOn</Filters>
       </Add>
       <Add Type="Microsoft.ApplicationInsights.Web.ClientIpHeaderTelemetryInitializer, Microsoft.AI.Web" />
       <Add Type="Microsoft.ApplicationInsights.Web.AzureAppServiceRoleNameFromHostNameHeaderInitializer, Microsoft.AI.Web" />
       <Add Type="Microsoft.ApplicationInsights.Web.OperationNameTelemetryInitializer, Microsoft.AI.Web" />
       <Add Type="Microsoft.ApplicationInsights.Web.OperationCorrelationTelemetryInitializer, Microsoft.AI.Web" />
       <Add Type="Microsoft.ApplicationInsights.Web.UserTelemetryInitializer, Microsoft.AI.Web" />
       <Add Type="Microsoft.ApplicationInsights.Web.AuthenticatedUserIdTelemetryInitializer, Microsoft.AI.Web" />
       <Add Type="Microsoft.ApplicationInsights.Web.AccountIdTelemetryInitializer, Microsoft.AI.Web" />
       <Add Type="Microsoft.ApplicationInsights.Web.SessionTelemetryInitializer, Microsoft.AI.Web" />
     </TelemetryInitializers>
     <TelemetryModules>
       <Add Type="Microsoft.ApplicationInsights.DependencyCollector.DependencyTrackingTelemetryModule, Microsoft.AI.DependencyCollector">
         <ExcludeComponentCorrelationHttpHeadersOnDomains>
           <!-- 
           Requests to the following hostnames will not be modified by adding correlation headers.         
           Add entries here to exclude additional hostnames.
           NOTE: this configuration will be lost upon NuGet upgrade.
           -->
           <Add>core.chinacloudapi.cn</Add>
           <Add>core.chinacloudapi.cn</Add>
           <Add>core.cloudapi.de</Add>
           <Add>core.usgovcloudapi.net</Add>
         </ExcludeComponentCorrelationHttpHeadersOnDomains>
         <IncludeDiagnosticSourceActivities>
           <Add>Microsoft.Azure.EventHubs</Add>
           <Add>Microsoft.Azure.ServiceBus</Add>
         </IncludeDiagnosticSourceActivities>
       </Add>
       <Add Type="Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector.PerformanceCollectorModule, Microsoft.AI.PerfCounterCollector">
         <!--
         Use the following syntax here to collect additional performance counters:
    
         <Counters>
           <Add PerformanceCounter="\Process(??APP_WIN32_PROC??)\Handle Count" ReportAs="Process handle count" />
           ...
         </Counters>
    
         PerformanceCounter must be either \CategoryName(InstanceName)\CounterName or \CategoryName\CounterName
    
         NOTE: performance counters configuration will be lost upon NuGet upgrade.
    
         The following placeholders are supported as InstanceName:
           ??APP_WIN32_PROC?? - instance name of the application process  for Win32 counters.
           ??APP_W3SVC_PROC?? - instance name of the application IIS worker process for IIS/ASP.NET counters.
           ??APP_CLR_PROC?? - instance name of the application CLR process for .NET counters.
         -->
       </Add>
       <Add Type="Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector.QuickPulse.QuickPulseTelemetryModule, Microsoft.AI.PerfCounterCollector" />
       <Add Type="Microsoft.ApplicationInsights.WindowsServer.AppServicesHeartbeatTelemetryModule, Microsoft.AI.WindowsServer" />
       <Add Type="Microsoft.ApplicationInsights.WindowsServer.AzureInstanceMetadataTelemetryModule, Microsoft.AI.WindowsServer">
         <!--
         Remove individual fields collected here by adding them to the ApplicationInsighs.HeartbeatProvider 
         with the following syntax:
    
         <Add Type="Microsoft.ApplicationInsights.Extensibility.Implementation.Tracing.DiagnosticsTelemetryModule, Microsoft.ApplicationInsights">
           <ExcludedHeartbeatProperties>
             <Add>osType</Add>
             <Add>location</Add>
             <Add>name</Add>
             <Add>offer</Add>
             <Add>platformFaultDomain</Add>
             <Add>platformUpdateDomain</Add>
             <Add>publisher</Add>
             <Add>sku</Add>
             <Add>version</Add>
             <Add>vmId</Add>
             <Add>vmSize</Add>
             <Add>subscriptionId</Add>
             <Add>resourceGroupName</Add>
             <Add>placementGroupId</Add>
             <Add>tags</Add>
             <Add>vmScaleSetName</Add>
           </ExcludedHeartbeatProperties>
         </Add>
    
         NOTE: exclusions will be lost upon upgrade.
         -->
       </Add>
       <Add Type="Microsoft.ApplicationInsights.WindowsServer.DeveloperModeWithDebuggerAttachedTelemetryModule, Microsoft.AI.WindowsServer" />
       <Add Type="Microsoft.ApplicationInsights.WindowsServer.UnhandledExceptionTelemetryModule, Microsoft.AI.WindowsServer" />
       <Add Type="Microsoft.ApplicationInsights.WindowsServer.UnobservedExceptionTelemetryModule, Microsoft.AI.WindowsServer">
         <!--</Add>
       <Add Type="Microsoft.ApplicationInsights.WindowsServer.FirstChanceExceptionStatisticsTelemetryModule, Microsoft.AI.WindowsServer">-->
       </Add>
       <Add Type="Microsoft.ApplicationInsights.Web.RequestTrackingTelemetryModule, Microsoft.AI.Web">
         <Handlers>
           <!-- 
           Add entries here to filter out additional handlers: 
    
           NOTE: handler configuration will be lost upon NuGet upgrade.
           -->
           <Add>Microsoft.VisualStudio.Web.PageInspector.Runtime.Tracing.RequestDataHttpHandler</Add>
           <Add>System.Web.StaticFileHandler</Add>
           <Add>System.Web.Handlers.AssemblyResourceLoader</Add>
           <Add>System.Web.Optimization.BundleHandler</Add>
           <Add>System.Web.Script.Services.ScriptHandlerFactory</Add>
           <Add>System.Web.Handlers.TraceHandler</Add>
           <Add>System.Web.Services.Discovery.DiscoveryRequestHandler</Add>
           <Add>System.Web.HttpDebugHandler</Add>
         </Handlers>
       </Add>
       <Add Type="Microsoft.ApplicationInsights.Web.ExceptionTrackingTelemetryModule, Microsoft.AI.Web" />
       <Add Type="Microsoft.ApplicationInsights.Web.AspNetDiagnosticTelemetryModule, Microsoft.AI.Web" />
     </TelemetryModules>
     <ApplicationIdProvider Type="Microsoft.ApplicationInsights.Extensibility.Implementation.ApplicationId.ApplicationInsightsApplicationIdProvider, Microsoft.ApplicationInsights" />
     <TelemetrySinks>
       <Add Name="default">
         <TelemetryProcessors>
           <Add Type="Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector.QuickPulse.QuickPulseTelemetryProcessor, Microsoft.AI.PerfCounterCollector" />
           <Add Type="Microsoft.ApplicationInsights.Extensibility.AutocollectedMetricsExtractor, Microsoft.ApplicationInsights" />
           <Add Type="Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel.AdaptiveSamplingTelemetryProcessor, Microsoft.AI.ServerTelemetryChannel">
             <MaxTelemetryItemsPerSecond>5</MaxTelemetryItemsPerSecond>
             <ExcludedTypes>Event</ExcludedTypes>
           </Add>
           <Add Type="Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel.AdaptiveSamplingTelemetryProcessor, Microsoft.AI.ServerTelemetryChannel">
             <MaxTelemetryItemsPerSecond>5</MaxTelemetryItemsPerSecond>
             <IncludedTypes>Event</IncludedTypes>
           </Add>
         </TelemetryProcessors>
         <TelemetryChannel Type="Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel.ServerTelemetryChannel, Microsoft.AI.ServerTelemetryChannel" />
       </Add>
     </TelemetrySinks>
     <!-- 
       Learn more about Application Insights configuration with ApplicationInsights.config here: 
       http://go.microsoft.com/fwlink/?LinkID=513840
     -->
     <InstrumentationKey>your-instrumentation-key-here</InstrumentationKey>
    </ApplicationInsights>
    
  4. 在结束标记 </ApplicationInsights> 之前,添加 Application Insights 资源的检测密钥。Before the closing </ApplicationInsights> tag, add your instrumentation key for your Application Insights resource. 可以在新建的 Application Insights 资源(作为本文先决条件之一而创建)的“概述”窗格中找到检测密钥。Your instrumentation key can be found on the overview pane of your newly created Application Insights resource that you created as part of the prerequisites for this article.

    <InstrumentationKey>your-instrumentation-key-goes-here</InstrumentationKey>
    
  5. 在项目中与 ApplicationInsights.config 文件相同的级别上,创建名为 ErrorHandler 的文件夹,其中包含名为 AiHandleErrorAttribute.cs 的新 C# 文件。At the same level of your project as the ApplicationInsights.config file, create a folder called ErrorHandler with a new C# file called AiHandleErrorAttribute.cs. 文件的内容将如下所示:The contents of the file will look as follows:

    using System;
    using System.Web.Mvc;
    using Microsoft.ApplicationInsights;
    
    namespace WebApplication10.ErrorHandler //namespace will vary based on your project name
    {
        [AttributeUsage(AttributeTargets.Class | AttributeTargets.Method, Inherited = true, AllowMultiple = true)] 
        public class AiHandleErrorAttribute : HandleErrorAttribute
        {
            public override void OnException(ExceptionContext filterContext)
            {
                if (filterContext != null && filterContext.HttpContext != null && filterContext.Exception != null)
                {
                    //If customError is Off, then AI HTTPModule will report the exception
                    if (filterContext.HttpContext.IsCustomErrorEnabled)
                    {   
                        var ai = new TelemetryClient();
                        ai.TrackException(filterContext.Exception);
                    } 
                }
                base.OnException(filterContext);
            }
        }
    }
    
    
  6. App_Start 文件夹中,打开 FilterConfig.cs 文件并进行更改,使其与示例相匹配:In the App_Start folder, open the FilterConfig.cs file and change it to match the sample:

    using System.Web;
    using System.Web.Mvc;
    
    namespace WebApplication10 //Namespace will vary based on project name
    {
        public class FilterConfig
        {
            public static void RegisterGlobalFilters(GlobalFilterCollection filters)
            {
                filters.Add(new ErrorHandler.AiHandleErrorAttribute());
            }
        }
    }
    
  7. 按如下所示更新 Web.config 文件:Update the Web.config file as follows:

    <?xml version="1.0" encoding="utf-8"?>
    <!--
      For more information on how to configure your ASP.NET application, please visit
      https://go.microsoft.com/fwlink/?LinkId=301880
      -->
    <configuration>
      <appSettings>
        <add key="webpages:Version" value="3.0.0.0" />
        <add key="webpages:Enabled" value="false" />
        <add key="ClientValidationEnabled" value="true" />
        <add key="UnobtrusiveJavaScriptEnabled" value="true" />
      </appSettings>
      <system.web>
        <compilation debug="true" targetFramework="4.7.2" />
        <httpRuntime targetFramework="4.7.2" />
        <httpModules>
          <add name="TelemetryCorrelationHttpModule" type="Microsoft.AspNet.TelemetryCorrelation.TelemetryCorrelationHttpModule, Microsoft.AspNet.TelemetryCorrelation" />
          <add name="ApplicationInsightsWebTracking" type="Microsoft.ApplicationInsights.Web.ApplicationInsightsHttpModule, Microsoft.AI.Web" />
        </httpModules>
      </system.web>
      <runtime>
        <assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1">
          <dependentAssembly>
            <assemblyIdentity name="Antlr3.Runtime" publicKeyToken="eb42632606e9261f" />
            <bindingRedirect oldVersion="0.0.0.0-3.5.0.2" newVersion="3.5.0.2" />
          </dependentAssembly>
          <dependentAssembly>
            <assemblyIdentity name="Newtonsoft.Json" publicKeyToken="30ad4fe6b2a6aeed" />
            <bindingRedirect oldVersion="0.0.0.0-12.0.0.0" newVersion="12.0.0.0" />
          </dependentAssembly>
          <dependentAssembly>
            <assemblyIdentity name="System.Web.Optimization" publicKeyToken="31bf3856ad364e35" />
            <bindingRedirect oldVersion="1.0.0.0-1.1.0.0" newVersion="1.1.0.0" />
          </dependentAssembly>
          <dependentAssembly>
            <assemblyIdentity name="WebGrease" publicKeyToken="31bf3856ad364e35" />
            <bindingRedirect oldVersion="0.0.0.0-1.6.5135.21930" newVersion="1.6.5135.21930" />
          </dependentAssembly>
          <dependentAssembly>
            <assemblyIdentity name="System.Web.Helpers" publicKeyToken="31bf3856ad364e35" />
            <bindingRedirect oldVersion="1.0.0.0-3.0.0.0" newVersion="3.0.0.0" />
          </dependentAssembly>
          <dependentAssembly>
            <assemblyIdentity name="System.Web.WebPages" publicKeyToken="31bf3856ad364e35" />
            <bindingRedirect oldVersion="1.0.0.0-3.0.0.0" newVersion="3.0.0.0" />
          </dependentAssembly>
          <dependentAssembly>
            <assemblyIdentity name="System.Web.Mvc" publicKeyToken="31bf3856ad364e35" />
            <bindingRedirect oldVersion="1.0.0.0-5.2.7.0" newVersion="5.2.7.0" />
          </dependentAssembly>
          <dependentAssembly>
            <assemblyIdentity name="System.Memory" publicKeyToken="cc7b13ffcd2ddd51" culture="neutral" />
            <bindingRedirect oldVersion="0.0.0.0-4.0.1.1" newVersion="4.0.1.1" />
          </dependentAssembly>
        </assemblyBinding>
      </runtime>
      <system.codedom>
        <compilers>
          <compiler language="c#;cs;csharp" extension=".cs" type="Microsoft.CodeDom.Providers.DotNetCompilerPlatform.CSharpCodeProvider, Microsoft.CodeDom.Providers.DotNetCompilerPlatform, Version=2.0.1.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" warningLevel="4" compilerOptions="/langversion:default /nowarn:1659;1699;1701" />
          <compiler language="vb;vbs;visualbasic;vbscript" extension=".vb" type="Microsoft.CodeDom.Providers.DotNetCompilerPlatform.VBCodeProvider, Microsoft.CodeDom.Providers.DotNetCompilerPlatform, Version=2.0.1.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" warningLevel="4" compilerOptions="/langversion:default /nowarn:41008 /define:_MYTYPE=\&quot;Web\&quot; /optionInfer+" />
        </compilers>
      </system.codedom>
      <system.webServer>
        <validation validateIntegratedModeConfiguration="false" />
        <modules>
          <remove name="TelemetryCorrelationHttpModule" />
          <add name="TelemetryCorrelationHttpModule" type="Microsoft.AspNet.TelemetryCorrelation.TelemetryCorrelationHttpModule, Microsoft.AspNet.TelemetryCorrelation" preCondition="managedHandler" />
          <remove name="ApplicationInsightsWebTracking" />
          <add name="ApplicationInsightsWebTracking" type="Microsoft.ApplicationInsights.Web.ApplicationInsightsHttpModule, Microsoft.AI.Web" preCondition="managedHandler" />
        </modules>
      </system.webServer>
    </configuration>
    
    

现在已成功配置服务器端应用程序监视。You have now successfully configured server-side application monitoring. 如果运行 Web 应用,将能够看到遥测开始出现在 Application Insights 中。If you run your web app, you will be able to see telemetry begin to appear within Application Insights.

添加客户端监视Add client-side monitoring

前面几个部分提供了有关自动和手动配置服务器端监视的方法的指导。The previous sections provided guidance on methods to automatically and manually configure server-side monitoring. 若要添加客户端监视,将需要使用客户端 JavaScript SDKTo add client-side monitoring, you will need to use our client-side JavaScript SDK. 可以通过在页面 HTML 的结束标记 </head> 之前添加 JavaScript 代码片段来监视任何网页的客户端事务。You can monitor any web page's client-side transactions by adding a JavaScript snippet before the closing </head> tag of the page's HTML.

尽管可以手动将代码片段添加到每个 HTML 页面的标头,但建议改为将代码片段添加到主页,这样可以将代码片段插入网站的所有页面中。While is possible to manually add the snippet to the header of each HTML page, it is recommended to instead add the snippet to a primary page, which will inject the snippet into all pages of a site. 对于本文中基于模板的 ASP.NET MVC 应用,需要编辑位于“视图” > “共享”下名为 _Layout.cshtml 的文件 。For the template-based ASP.NET MVC app from this article, the file you need to edit is called _Layout.cshtml and it is found under Views > Shared.

若要添加客户端监视,请打开 _Layout.cshtml 文件,然后按照客户端 JavaScript SDK 配置文章中基于代码片段的设置说明进行操作。To add client-side monitoring, open the _Layout.cshtml file and follow the snippet-based setup instructions from the client-side JavaScript SDK configuration article.

疑难解答Troubleshooting

当前版本的 Visual Studio 2019 中存在一个已知问题,即对于基于 .NET Framework 的应用而言,将检测密钥存储在用户机密中时,该密钥将被损坏,最终必须将该密钥硬编码到 applicationinsights.config 文件中,才能解决此 bug。There is a known issue in the current version of Visual Studio 2019 that when storing the instrumentation key in a User Secret is broken for .NET Framework-based apps and the key ultimately has to be hardcoded into the applicationinsights.config file to work around this bug. 本文旨在通过不使用用户机密来完全避免此问题。This article is designed to avoid this issue entirely, by not using User Secrets.

开源 SDKOpen-source SDK

有关最新的更新和 bug 修复,请参阅发行说明For the latest updates and bug fixes consult the release notes.

后续步骤Next steps

  • 添加综合事务,以通过可用性监视来测试你的网站是否可从世界各地进行访问。Add synthetic transactions to test that your website is available from all over the world with availability monitoring.
  • 配置采样以帮助降低遥测流量和数据存储费用。Configure sampling to help reduce telemetry traffic, and data storage costs.