fxcop: update xml comments (#886)

src/Microsoft.ApplicationInsights.AspNetCore/ExceptionTrackingMiddleware.cs

@@ -16,6 +16,11 @@
         private readonly TelemetryClient telemetryClient;
         private readonly string sdkVersion;
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="ExceptionTrackingMiddleware" /> class.
+        /// </summary>
+        /// <param name="next">A function that can process an HTTP request.</param>
+        /// <param name="client">Send events, metrics and other telemetry to the Application Insights service.</param>
         public ExceptionTrackingMiddleware(RequestDelegate next, TelemetryClient client)
         {
             this.next = next;
@@ -23,6 +28,11 @@
             this.sdkVersion = SdkVersionUtils.GetVersion();
         }
 
+        /// <summary>
+        /// Invoke the RequestDelegate with the HttpContext provided.
+        /// </summary>
+        /// <param name="httpContext">The HttpContext for the request.</param>
+        /// <returns>A task that represents the completion of request processing.</returns>
         public async Task Invoke(HttpContext httpContext)
         {
             try

src/Microsoft.ApplicationInsights.AspNetCore/Extensions/ApplicationInsightsExtensions.cs

@@ -2,9 +2,10 @@
 {
     using System;
     using System.Collections.Generic;
-    using System.Globalization;
+    using System.Diagnostics.CodeAnalysis;
     using System.Linq;
     using System.Reflection;
+
     using Microsoft.ApplicationInsights;
     using Microsoft.ApplicationInsights.AspNetCore;
     using Microsoft.ApplicationInsights.AspNetCore.Extensibility.Implementation.Tracing;
@@ -23,7 +24,6 @@
     using Microsoft.AspNetCore.Http;
     using Microsoft.Extensions.Configuration;
     using Microsoft.Extensions.Configuration.Memory;
-    using Microsoft.Extensions.DependencyInjection;
     using Microsoft.Extensions.DependencyInjection.Extensions;
     using Microsoft.Extensions.Logging;
     using Microsoft.Extensions.Options;
@@ -42,12 +42,14 @@
         private const string DeveloperModeForWebSites = "APPINSIGHTS_DEVELOPER_MODE";
         private const string EndpointAddressForWebSites = "APPINSIGHTS_ENDPOINTADDRESS";
 
+        [SuppressMessage(category: "", checkId: "CS1591:MissingXmlComment", Justification = "Obsolete method.")]
         [Obsolete("This middleware is no longer needed. Enable Request monitoring using services.AddApplicationInsights")]
         public static IApplicationBuilder UseApplicationInsightsRequestTelemetry(this IApplicationBuilder app)
         {
             return app;
         }
 
+        [SuppressMessage(category: "", checkId: "CS1591:MissingXmlComment", Justification = "Obsolete method.")]
         [Obsolete("This middleware is no longer needed to track exceptions as they are automatically tracked by RequestTrackingTelemetryModule")]
         public static IApplicationBuilder UseApplicationInsightsExceptionTelemetry(this IApplicationBuilder app)
         {
@@ -358,7 +360,7 @@
             {
                 telemetryConfigValues.Add(new KeyValuePair<string, string>(DeveloperModeForWebSites,
 #if !NETSTANDARD1_6
-                    developerMode.Value.ToString(CultureInfo.InvariantCulture)));
+                    developerMode.Value.ToString(System.Globalization.CultureInfo.InvariantCulture)));
 #else
                     developerMode.Value.ToString()));
 #endif

src/Microsoft.ApplicationInsights.AspNetCore/RequestTrackingTelemetryModule.cs

@@ -134,6 +134,10 @@ namespace Microsoft.ApplicationInsights.AspNetCore
             this.Dispose(true);
         }
 
+        /// <summary>
+        /// Dispose the class.
+        /// </summary>
+        /// <param name="disposing">Indicates if this class is currently being disposed.</param>
         protected virtual void Dispose(bool disposing)
         {
             if (!disposing)

src/Microsoft.ApplicationInsights.AspNetCore/TelemetryInitializers/AspNetCoreEnvironmentTelemetryInitializer.cs

@@ -17,6 +17,7 @@
         /// <summary>
         /// Initializes a new instance of the <see cref="AspNetCoreEnvironmentTelemetryInitializer"/> class.
         /// </summary>
+        /// <param name="environment">HostingEnvironment to provide EnvironmentName to be added to telemetry properties.</param>
         public AspNetCoreEnvironmentTelemetryInitializer(IHostingEnvironment environment)
         {
             this.environment = environment;

src/Microsoft.ApplicationInsights.AspNetCore/TelemetryInitializers/ClientIpHeaderTelemetryInitializer.cs

@@ -20,6 +20,10 @@
 
         private char[] headerValueSeparators;
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="ClientIpHeaderTelemetryInitializer" /> class.
+        /// </summary>
+        /// <param name="httpContextAccessor">Accessor to provide HttpContext corresponding to telemetry items.</param>
         public ClientIpHeaderTelemetryInitializer(IHttpContextAccessor httpContextAccessor)
              : base(httpContextAccessor)
         {
@@ -58,6 +62,7 @@
         /// </summary>
         public bool UseFirstIp { get; set; }
 
+        /// <inheritdoc />
         protected override void OnInitializeTelemetry(HttpContext platformContext, RequestTelemetry requestTelemetry, ITelemetry telemetry)
         {
             if (!string.IsNullOrEmpty(telemetry.Context.Location.Ip))

src/Microsoft.ApplicationInsights.AspNetCore/TelemetryInitializers/ComponentVersionTelemetryInitializer.cs

@@ -6,17 +6,22 @@
     using Microsoft.Extensions.Options;
 
     /// <summary>
-    /// A telemetry initializer that populates telemetry.Context.Component.Version to the value read from configuration
+    /// A telemetry initializer that populates telemetry.Context.Component.Version to the value read from configuration.
     /// </summary>
     public class ComponentVersionTelemetryInitializer : ITelemetryInitializer
     {
         private readonly string version;
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="ComponentVersionTelemetryInitializer" /> class.
+        /// </summary>
+        /// <param name="options">Provides the Application Version to be added to the telemetry.</param>
         public ComponentVersionTelemetryInitializer(IOptions<ApplicationInsightsServiceOptions> options)
         {
              this.version = options.Value.ApplicationVersion;
         }
 
+        /// <inheritdoc />
         public void Initialize(ITelemetry telemetry)
         {
             if (string.IsNullOrEmpty(telemetry.Context.Component.Version))

src/Microsoft.ApplicationInsights.AspNetCore/TelemetryInitializers/OperationNameTelemetryInitializer.cs

@@ -1,17 +1,23 @@
 namespace Microsoft.ApplicationInsights.AspNetCore.TelemetryInitializers
 {
-    using System;
-    using System.Diagnostics;
     using Microsoft.ApplicationInsights.Channel;
     using Microsoft.ApplicationInsights.DataContracts;
     using Microsoft.AspNetCore.Http;
 
+    /// <summary>
+    /// This telemetry initializer sets the Operation Name on telemetry items.
+    /// </summary>
     public class OperationNameTelemetryInitializer : TelemetryInitializerBase
     {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="OperationNameTelemetryInitializer" /> class.
+        /// </summary>
+        /// <param name="httpContextAccessor">Accessor to provide HttpContext corresponding to telemetry items.</param>
         public OperationNameTelemetryInitializer(IHttpContextAccessor httpContextAccessor) : base(httpContextAccessor)
         {
         }
 
+        /// <inheritdoc />
         protected override void OnInitializeTelemetry(HttpContext platformContext, RequestTelemetry requestTelemetry, ITelemetry telemetry)
         {
             if (string.IsNullOrEmpty(telemetry.Context.Operation.Name))

src/Microsoft.ApplicationInsights.AspNetCore/TelemetryInitializers/SyntheticTelemetryInitializer.cs

@@ -1,14 +1,8 @@
 namespace Microsoft.ApplicationInsights.AspNetCore.TelemetryInitializers
 {
-    using System;
-    using System.Collections.Generic;
-    using System.Net;
-    using System.Net.Sockets;
-    using Extensibility.Implementation.Tracing;
     using Microsoft.ApplicationInsights.Channel;
     using Microsoft.ApplicationInsights.DataContracts;
     using Microsoft.AspNetCore.Http;
-    using Microsoft.AspNetCore.Http.Features;
 
     /// <summary>
     /// This will allow to mark synthetic traffic from availability tests
@@ -20,11 +14,16 @@
 
         private const string SyntheticSourceHeaderValue = "Application Insights Availability Monitoring";
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="SyntheticTelemetryInitializer" /> class.
+        /// </summary>
+        /// <param name="httpContextAccessor">Accessor to provide HttpContext corresponding to telemetry items.</param>
         public SyntheticTelemetryInitializer(IHttpContextAccessor httpContextAccessor)
              : base(httpContextAccessor)
         {
         }
 
+        /// <inheritdoc />
         protected override void OnInitializeTelemetry(HttpContext platformContext, RequestTelemetry requestTelemetry, ITelemetry telemetry)
         {
             if (string.IsNullOrEmpty(telemetry.Context.Operation.SyntheticSource))

src/Microsoft.ApplicationInsights.AspNetCore/TelemetryInitializers/TelemetryInitializerBase.cs

@@ -1,25 +1,33 @@
 namespace Microsoft.ApplicationInsights.AspNetCore.TelemetryInitializers
 {
     using System;
-    using System.Diagnostics;
+
     using Microsoft.ApplicationInsights.AspNetCore.Extensibility.Implementation.Tracing;
     using Microsoft.ApplicationInsights.Channel;
     using Microsoft.ApplicationInsights.DataContracts;
     using Microsoft.ApplicationInsights.Extensibility;
     using Microsoft.AspNetCore.Http;
-    using Microsoft.Extensions.DependencyInjection;
 
+    /// <summary>
+    /// Base class for Telemetry Initializers. Provides access to HttpContext and RequestTelemetry
+    /// </summary>
     public abstract class TelemetryInitializerBase : ITelemetryInitializer
     {
         private readonly IHttpContextAccessor httpContextAccessor;
 
-        /// <inheritdoc />
+        /// <summary>
+        /// Initializes a new instance of the <see cref="TelemetryInitializerBase" /> class.
+        /// </summary>
+        /// <param name="httpContextAccessor">Accessor to provide HttpContext corresponding to telemetry items.</param>
         public TelemetryInitializerBase(IHttpContextAccessor httpContextAccessor)
         {
             this.httpContextAccessor = httpContextAccessor ?? throw new ArgumentNullException(nameof(httpContextAccessor));
         }
 
-        /// <inheritdoc />
+        /// <summary>
+        /// TelemetryInitializerBase will retrieve the HttpContext and RequestTelemetry for the current ITelemetry and then invoke <see cref="OnInitializeTelemetry"/>.
+        /// </summary>
+        /// <param name="telemetry"></param>
         public void Initialize(ITelemetry telemetry)
         {
             var context = this.httpContextAccessor.HttpContext;
@@ -44,6 +52,12 @@
             }
         }
 
+        /// <summary>
+        /// Abstract method provides HttpContext, RequestTelemetry for the given ITelemetry.
+        /// </summary>
+        /// <param name="platformContext"></param>
+        /// <param name="requestTelemetry"></param>
+        /// <param name="telemetry"></param>
         protected abstract void OnInitializeTelemetry(
             HttpContext platformContext,
             RequestTelemetry requestTelemetry,

src/Microsoft.ApplicationInsights.AspNetCore/TelemetryInitializers/WebSessionTelemetryInitializer.cs

@@ -5,11 +5,17 @@
     using Microsoft.ApplicationInsights.DataContracts;
     using Microsoft.AspNetCore.Http;
 
-    /// <inheritdoc />
+    /// <summary>
+    /// This telemetry initializer sets the Context.Session properties on an ITelemetry item.
+    /// </summary>
     public class WebSessionTelemetryInitializer : TelemetryInitializerBase
     {
         private const string WebSessionCookieName = "ai_session";
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="WebSessionTelemetryInitializer" /> class.
+        /// </summary>
+        /// <param name="httpContextAccessor">Accessor to provide HttpContext corresponding to telemetry items.</param>
         public WebSessionTelemetryInitializer(IHttpContextAccessor httpContextAccessor)
              : base(httpContextAccessor)
         {

src/Microsoft.ApplicationInsights.AspNetCore/TelemetryInitializers/WebUserTelemetryInitializer.cs

@@ -5,11 +5,17 @@
     using Microsoft.ApplicationInsights.DataContracts;
     using Microsoft.AspNetCore.Http;
 
-    /// <inheritdoc />
+    /// <summary>
+    /// This initializer sets the User Id on telemetry.
+    /// </summary>
     public class WebUserTelemetryInitializer : TelemetryInitializerBase
     {
         private const string WebUserCookieName = "ai_user";
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="WebUserTelemetryInitializer" /> class.
+        /// </summary>
+        /// <param name="httpContextAccessor">Accessor to provide HttpContext corresponding to telemetry items.</param>
         public WebUserTelemetryInitializer(IHttpContextAccessor httpContextAccessor)
              : base(httpContextAccessor)
         {