diff --git a/libraries/integration/Microsoft.Bot.Builder.Integration.ApplicationInsights.Core/ApplicationBuilderExtensions.cs b/libraries/integration/Microsoft.Bot.Builder.Integration.ApplicationInsights.Core/ApplicationBuilderExtensions.cs index 56cf826d6a..a21c527df1 100644 --- a/libraries/integration/Microsoft.Bot.Builder.Integration.ApplicationInsights.Core/ApplicationBuilderExtensions.cs +++ b/libraries/integration/Microsoft.Bot.Builder.Integration.ApplicationInsights.Core/ApplicationBuilderExtensions.cs @@ -6,8 +6,14 @@ namespace Microsoft.Bot.Builder.Integration.ApplicationInsights.Core { + /// + /// ApplicationBuilder extension methods for use when registering Application Insights services at startup. + /// public static class ApplicationBuilderExtensions { + /// + /// Constant key used for Application Insights Instrumentation Key. + /// public const string AppInsightsInstrumentationKey = "ApplicationInsights:InstrumentationKey"; /// diff --git a/libraries/integration/Microsoft.Bot.Builder.Integration.ApplicationInsights.Core/Microsoft.Bot.Builder.Integration.ApplicationInsights.Core.csproj b/libraries/integration/Microsoft.Bot.Builder.Integration.ApplicationInsights.Core/Microsoft.Bot.Builder.Integration.ApplicationInsights.Core.csproj index da7a3794de..772317b369 100644 --- a/libraries/integration/Microsoft.Bot.Builder.Integration.ApplicationInsights.Core/Microsoft.Bot.Builder.Integration.ApplicationInsights.Core.csproj +++ b/libraries/integration/Microsoft.Bot.Builder.Integration.ApplicationInsights.Core/Microsoft.Bot.Builder.Integration.ApplicationInsights.Core.csproj @@ -22,11 +22,6 @@ true - - - $(NoWarn);CS1591 - - diff --git a/libraries/integration/Microsoft.Bot.Builder.Integration.ApplicationInsights.Core/ServiceCollectionExtensions.cs b/libraries/integration/Microsoft.Bot.Builder.Integration.ApplicationInsights.Core/ServiceCollectionExtensions.cs index efc8a38cf4..f4ba488bd5 100644 --- a/libraries/integration/Microsoft.Bot.Builder.Integration.ApplicationInsights.Core/ServiceCollectionExtensions.cs +++ b/libraries/integration/Microsoft.Bot.Builder.Integration.ApplicationInsights.Core/ServiceCollectionExtensions.cs @@ -13,6 +13,9 @@ namespace Microsoft.Bot.Builder.Integration.ApplicationInsights.Core { + /// + /// Services collection extension methods for use when configuring Application Insights at startup. + /// public static class ServiceCollectionExtensions { /// diff --git a/libraries/integration/Microsoft.Bot.Builder.Integration.ApplicationInsights.Core/TelemetryBotIdInitializer.cs b/libraries/integration/Microsoft.Bot.Builder.Integration.ApplicationInsights.Core/TelemetryBotIdInitializer.cs index 632ab5ccab..eb87193bb7 100644 --- a/libraries/integration/Microsoft.Bot.Builder.Integration.ApplicationInsights.Core/TelemetryBotIdInitializer.cs +++ b/libraries/integration/Microsoft.Bot.Builder.Integration.ApplicationInsights.Core/TelemetryBotIdInitializer.cs @@ -17,14 +17,23 @@ namespace Microsoft.Bot.Builder.Integration.ApplicationInsights.Core /// public class TelemetryBotIdInitializer : ITelemetryInitializer { + /// + /// Constant key used for storing activity information in turn state. + /// public static readonly string BotActivityKey = "BotBuilderActivity"; + private readonly IHttpContextAccessor _httpContextAccessor; + /// + /// Initializes a new instance of the class. + /// + /// The HttpContextAccessor used to access the current HttpContext. public TelemetryBotIdInitializer(IHttpContextAccessor httpContextAccessor) { _httpContextAccessor = httpContextAccessor ?? throw new ArgumentNullException(nameof(httpContextAccessor)); } + /// public void Initialize(ITelemetry telemetry) { if (telemetry == null) diff --git a/libraries/integration/Microsoft.Bot.Builder.Integration.ApplicationInsights.Core/TelemetrySaveBodyASPMiddleware.cs b/libraries/integration/Microsoft.Bot.Builder.Integration.ApplicationInsights.Core/TelemetrySaveBodyASPMiddleware.cs index 48741166d3..68be5d29da 100644 --- a/libraries/integration/Microsoft.Bot.Builder.Integration.ApplicationInsights.Core/TelemetrySaveBodyASPMiddleware.cs +++ b/libraries/integration/Microsoft.Bot.Builder.Integration.ApplicationInsights.Core/TelemetrySaveBodyASPMiddleware.cs @@ -12,8 +12,11 @@ namespace Microsoft.Bot.Builder.Integration.ApplicationInsights.Core { - // This class has been deprecated in favor of using TelemetryInitializerMiddleware in - // Microsoft.Bot.Integration.ApplicationInsights.Core and Microsoft.Bot.Integration.ApplicationInsights.WebApi + /// + /// Middleware to store the incoming activity request body into the HttpContext items collection. + /// This class has been deprecated in favor of using TelemetryInitializerMiddleware in + /// Microsoft.Bot.Integration.ApplicationInsights.Core and Microsoft.Bot.Integration.ApplicationInsights.WebApi. + /// [Obsolete("This class is deprecated. Please add TelemetryInitializerMiddleware to your adapter's middleware pipeline instead.")] [SuppressMessage("Globalization", "CA1307:Specify StringComparison", Justification = "This class is deprecated, we won't fix FxCop issues")] [SuppressMessage("AsyncUsage.CSharp.Naming", "UseAsyncSuffix:Use Async suffix", Justification = "This class is deprecated, we won't fix FxCop issues")] @@ -21,11 +24,20 @@ public class TelemetrySaveBodyASPMiddleware { private readonly RequestDelegate _next; + /// + /// Initializes a new instance of the class. + /// + /// The delegate to the next piece of middleware in the pipeline. public TelemetrySaveBodyASPMiddleware(RequestDelegate next) { _next = next ?? throw new ArgumentNullException(nameof(next)); } + /// + /// Invokes the TelemetrySaveBodyASPMiddleware middleware. + /// + /// The HttpContext. + /// A task that represents the work queued to execute. public async Task Invoke(HttpContext httpContext) { var request = httpContext.Request; diff --git a/libraries/integration/Microsoft.Bot.Builder.Integration.ApplicationInsights.WebApi/Microsoft.Bot.Builder.Integration.ApplicationInsights.WebApi.csproj b/libraries/integration/Microsoft.Bot.Builder.Integration.ApplicationInsights.WebApi/Microsoft.Bot.Builder.Integration.ApplicationInsights.WebApi.csproj index cf389a513e..fe33093628 100644 --- a/libraries/integration/Microsoft.Bot.Builder.Integration.ApplicationInsights.WebApi/Microsoft.Bot.Builder.Integration.ApplicationInsights.WebApi.csproj +++ b/libraries/integration/Microsoft.Bot.Builder.Integration.ApplicationInsights.WebApi/Microsoft.Bot.Builder.Integration.ApplicationInsights.WebApi.csproj @@ -22,11 +22,6 @@ Full true - - - - $(NoWarn);CS1591 - Microsoft.Bot.Builder.Integration.ApplicationInsights.WebApi diff --git a/libraries/integration/Microsoft.Bot.Builder.Integration.ApplicationInsights.WebApi/TelemetryBotIdInitializer.cs b/libraries/integration/Microsoft.Bot.Builder.Integration.ApplicationInsights.WebApi/TelemetryBotIdInitializer.cs index 2b18f3bd81..105f08391c 100644 --- a/libraries/integration/Microsoft.Bot.Builder.Integration.ApplicationInsights.WebApi/TelemetryBotIdInitializer.cs +++ b/libraries/integration/Microsoft.Bot.Builder.Integration.ApplicationInsights.WebApi/TelemetryBotIdInitializer.cs @@ -18,8 +18,15 @@ namespace Microsoft.Bot.Builder.Integration.ApplicationInsights.WebApi /// public class TelemetryBotIdInitializer : ITelemetryInitializer { + /// + /// Constant key used for storing activity information in turn state. + /// public static readonly string BotActivityKey = "BotBuilderActivity"; + /// + /// Initializes a new instance of the class. + /// + /// The telemetry item to be logged to Application Insights. public void Initialize(ITelemetry telemetry) { var httpContext = HttpContext.Current; diff --git a/libraries/integration/Microsoft.Bot.Builder.Integration.AspNet.Core/BotFrameworkHttpAdapter.cs b/libraries/integration/Microsoft.Bot.Builder.Integration.AspNet.Core/BotFrameworkHttpAdapter.cs index 350cc24e17..e630aa7efb 100644 --- a/libraries/integration/Microsoft.Bot.Builder.Integration.AspNet.Core/BotFrameworkHttpAdapter.cs +++ b/libraries/integration/Microsoft.Bot.Builder.Integration.AspNet.Core/BotFrameworkHttpAdapter.cs @@ -56,16 +56,42 @@ public BotFrameworkHttpAdapter( { } + /// + /// Initializes a new instance of the class, + /// using a credential provider. + /// + /// The credential provider. + /// The channel provider. + /// The ILogger implementation this adapter should use. public BotFrameworkHttpAdapter(ICredentialProvider credentialProvider = null, IChannelProvider channelProvider = null, ILogger logger = null) : this(credentialProvider ?? new SimpleCredentialProvider(), new AuthenticationConfiguration(), channelProvider, null, null, null, logger) { } + /// + /// Initializes a new instance of the class, + /// using a credential provider. + /// + /// The credential provider. + /// The channel provider. + /// The used. + /// The ILogger implementation this adapter should use. public BotFrameworkHttpAdapter(ICredentialProvider credentialProvider, IChannelProvider channelProvider, HttpClient httpClient, ILogger logger) : this(credentialProvider ?? new SimpleCredentialProvider(), new AuthenticationConfiguration(), channelProvider, null, httpClient, null, logger) { } + /// + /// Initializes a new instance of the class. + /// + /// An instance. + /// The credential provider. + /// The authentication configuration. + /// The channel provider. + /// Retry policy for retrying HTTP operations. + /// The HTTP client. + /// The middleware to initially add to the adapter. + /// The ILogger implementation this adapter should use. protected BotFrameworkHttpAdapter( IConfiguration configuration, ICredentialProvider credentialProvider, @@ -87,11 +113,25 @@ protected BotFrameworkHttpAdapter( } } + /// + /// Initializes a new instance of the class. + /// + /// An instance. + /// The ILogger implementation this adapter should use. protected BotFrameworkHttpAdapter(IConfiguration configuration, ILogger logger = null) : this(configuration, new ConfigurationCredentialProvider(configuration), new AuthenticationConfiguration(), new ConfigurationChannelProvider(configuration), logger: logger) { } - + + /// + /// This method can be called from inside a POST method on any Controller implementation. + /// + /// The HTTP request object, typically in a POST handler by a Controller. + /// The HTTP response object. + /// The bot implementation. + /// A cancellation token that can be used by other objects + /// or threads to receive notice of cancellation. + /// A task that represents the work queued to execute. public async Task ProcessAsync(HttpRequest httpRequest, HttpResponse httpResponse, IBot bot, CancellationToken cancellationToken = default) { if (httpRequest == null) diff --git a/libraries/integration/Microsoft.Bot.Builder.Integration.AspNet.Core/BotFrameworkHttpClient.cs b/libraries/integration/Microsoft.Bot.Builder.Integration.AspNet.Core/BotFrameworkHttpClient.cs index 8b570fa555..3a0741dbcf 100644 --- a/libraries/integration/Microsoft.Bot.Builder.Integration.AspNet.Core/BotFrameworkHttpClient.cs +++ b/libraries/integration/Microsoft.Bot.Builder.Integration.AspNet.Core/BotFrameworkHttpClient.cs @@ -29,6 +29,13 @@ namespace Microsoft.Bot.Builder.Integration.AspNet.Core /// public class BotFrameworkHttpClient : BotFrameworkClient { + /// + /// Initializes a new instance of the class. + /// + /// A . + /// An instance of . + /// An instance of . + /// An instance of . public BotFrameworkHttpClient( HttpClient httpClient, ICredentialProvider credentialProvider, @@ -42,16 +49,43 @@ public BotFrameworkHttpClient( ConnectorClient.AddDefaultRequestHeaders(HttpClient); } - // Cache for appCredentials to speed up token acquisition (a token is not requested unless is expired) - // AppCredentials are cached using appId + scope (this last parameter is only used if the app credentials are used to call a skill) + /// + /// Gets the Cache for appCredentials to speed up token acquisition (a token is not requested unless is expired). + /// AppCredentials are cached using appId + scope (this last parameter is only used if the app credentials are used to call a skill). + /// + /// ConcurrentDictionary of . protected static ConcurrentDictionary AppCredentialMapCache { get; } = new ConcurrentDictionary(); + /// + /// Gets the channel provider for this adapter. + /// + /// + /// The channel provider for this adapter. + /// protected IChannelProvider ChannelProvider { get; } + /// + /// Gets the credential provider for this adapter. + /// + /// + /// The credential provider for this adapter. + /// protected ICredentialProvider CredentialProvider { get; } + /// + /// Gets the HttpClient for this adapter. + /// + /// + /// The HttpClient for this adapter. + /// protected HttpClient HttpClient { get; } + /// + /// Gets the logger for this adapter. + /// + /// + /// The logger for this adapter. + /// protected ILogger Logger { get; } /// diff --git a/libraries/integration/Microsoft.Bot.Builder.Integration.AspNet.Core/BotMessageHandler.cs b/libraries/integration/Microsoft.Bot.Builder.Integration.AspNet.Core/BotMessageHandler.cs index 66189c9877..8eed9e6adf 100644 --- a/libraries/integration/Microsoft.Bot.Builder.Integration.AspNet.Core/BotMessageHandler.cs +++ b/libraries/integration/Microsoft.Bot.Builder.Integration.AspNet.Core/BotMessageHandler.cs @@ -11,8 +11,20 @@ namespace Microsoft.Bot.Builder.Integration.AspNet.Core.Handlers { + /// + /// A handler to process incoming http requests via using an adapter. + /// public class BotMessageHandler : BotMessageHandlerBase { + /// + /// Deserializes the incoming request using a BotMessageHandler, processes it with an + /// and returns an . + /// + /// A . + /// An instance of . + /// An instance of . + /// A . + /// An returned from the adapter. protected override async Task ProcessMessageRequestAsync(HttpRequest request, IAdapterIntegration adapter, BotCallbackHandler botCallbackHandler, CancellationToken cancellationToken) { Activity activity; diff --git a/libraries/integration/Microsoft.Bot.Builder.Integration.AspNet.Core/BotMessageHandlerBase.cs b/libraries/integration/Microsoft.Bot.Builder.Integration.AspNet.Core/BotMessageHandlerBase.cs index 5875c31ed8..0b46993782 100644 --- a/libraries/integration/Microsoft.Bot.Builder.Integration.AspNet.Core/BotMessageHandlerBase.cs +++ b/libraries/integration/Microsoft.Bot.Builder.Integration.AspNet.Core/BotMessageHandlerBase.cs @@ -14,14 +14,29 @@ namespace Microsoft.Bot.Builder.Integration.AspNet.Core.Handlers { + /// + /// Abstract base class for a bot message handler. + /// public abstract class BotMessageHandlerBase { + /// + /// A for use when serializing bot messages. + /// public static readonly JsonSerializer BotMessageSerializer = JsonSerializer.Create(MessageSerializerSettings.Create()); + /// + /// Initializes a new instance of the class. + /// public BotMessageHandlerBase() { } + /// + /// Handles common behavior for handling requests, including checking valid request method and content type. + /// Processes the request using the registered adapter and bot and writes the result to the response on the . + /// + /// The . + /// A Task that represents the work to be executed. public async Task HandleAsync(HttpContext httpContext) { var request = httpContext.Request; @@ -95,6 +110,15 @@ public async Task HandleAsync(HttpContext httpContext) } } + /// + /// Abstract method to process the incoming request using the registered adapter and bot and + /// to return an . + /// + /// A . + /// An instance of . + /// An instance of . + /// A . + /// An returned from the adapter. protected abstract Task ProcessMessageRequestAsync(HttpRequest request, IAdapterIntegration adapter, BotCallbackHandler botCallbackHandler, CancellationToken cancellationToken); } } diff --git a/libraries/integration/Microsoft.Bot.Builder.Integration.AspNet.Core/ConfigurationChannelProvider.cs b/libraries/integration/Microsoft.Bot.Builder.Integration.AspNet.Core/ConfigurationChannelProvider.cs index 299091c0ee..7457643b0a 100644 --- a/libraries/integration/Microsoft.Bot.Builder.Integration.AspNet.Core/ConfigurationChannelProvider.cs +++ b/libraries/integration/Microsoft.Bot.Builder.Integration.AspNet.Core/ConfigurationChannelProvider.cs @@ -21,6 +21,10 @@ public sealed class ConfigurationChannelProvider : SimpleChannelProvider /// public const string ChannelServiceKey = "ChannelService"; + /// + /// Initializes a new instance of the class. + /// + /// An instance of . public ConfigurationChannelProvider(IConfiguration configuration) { this.ChannelService = configuration.GetSection(ChannelServiceKey)?.Value; diff --git a/libraries/integration/Microsoft.Bot.Builder.Integration.AspNet.Core/ConfigurationCredentialProvider.cs b/libraries/integration/Microsoft.Bot.Builder.Integration.AspNet.Core/ConfigurationCredentialProvider.cs index 53e68bfe14..9bd0d8be3e 100644 --- a/libraries/integration/Microsoft.Bot.Builder.Integration.AspNet.Core/ConfigurationCredentialProvider.cs +++ b/libraries/integration/Microsoft.Bot.Builder.Integration.AspNet.Core/ConfigurationCredentialProvider.cs @@ -17,6 +17,10 @@ namespace Microsoft.Bot.Builder.BotFramework /// public sealed class ConfigurationCredentialProvider : SimpleCredentialProvider { + /// + /// Initializes a new instance of the class. + /// + /// An instance of . public ConfigurationCredentialProvider(IConfiguration configuration) { this.AppId = configuration.GetSection(MicrosoftAppCredentials.MicrosoftAppIdKey)?.Value; diff --git a/libraries/integration/Microsoft.Bot.Builder.Integration.AspNet.Core/HttpHelper.cs b/libraries/integration/Microsoft.Bot.Builder.Integration.AspNet.Core/HttpHelper.cs index ba3d8261fe..bb9bbf407d 100644 --- a/libraries/integration/Microsoft.Bot.Builder.Integration.AspNet.Core/HttpHelper.cs +++ b/libraries/integration/Microsoft.Bot.Builder.Integration.AspNet.Core/HttpHelper.cs @@ -13,8 +13,14 @@ namespace Microsoft.Bot.Builder.Integration.AspNet.Core { + /// + /// Helper class with methods to help with reading and responding to http requests. + /// public static class HttpHelper { + /// + /// An instance of used by the . + /// public static readonly JsonSerializerSettings BotMessageSerializerSettings = new JsonSerializerSettings { NullValueHandling = NullValueHandling.Ignore, @@ -26,8 +32,17 @@ public static class HttpHelper Converters = new List { new Iso8601TimeSpanConverter() } }; + /// + /// An instance of created using . + /// public static readonly JsonSerializer BotMessageSerializer = JsonSerializer.Create(BotMessageSerializerSettings); + /// + /// Accepts an incoming HttpRequest and deserializes it using the . + /// + /// The type to deserialize the request into. + /// The HttpRequest. + /// The deserialized request. public static async Task ReadRequestAsync(HttpRequest request) { try @@ -53,6 +68,14 @@ public static async Task ReadRequestAsync(HttpRequest request) } } + /// + /// If an is provided the status and body of the + /// are used to set the status and body of the . If no + /// is provided then the status of the is set to 200. + /// + /// A HttpResponse. + /// An instance of . + /// A Task representing the work to be executed. public static async Task WriteResponseAsync(HttpResponse response, InvokeResponse invokeResponse) { if (response == null) diff --git a/libraries/integration/Microsoft.Bot.Builder.Integration.AspNet.Core/Microsoft.Bot.Builder.Integration.AspNet.Core.csproj b/libraries/integration/Microsoft.Bot.Builder.Integration.AspNet.Core/Microsoft.Bot.Builder.Integration.AspNet.Core.csproj index 56fce6df41..dc7065d2db 100644 --- a/libraries/integration/Microsoft.Bot.Builder.Integration.AspNet.Core/Microsoft.Bot.Builder.Integration.AspNet.Core.csproj +++ b/libraries/integration/Microsoft.Bot.Builder.Integration.AspNet.Core/Microsoft.Bot.Builder.Integration.AspNet.Core.csproj @@ -20,11 +20,6 @@ Full true - - - - $(NoWarn);CS1591 - diff --git a/libraries/integration/Microsoft.Bot.Builder.Integration.AspNet.Core/Skills/SkillHttpClient.cs b/libraries/integration/Microsoft.Bot.Builder.Integration.AspNet.Core/Skills/SkillHttpClient.cs index 064521afc7..b0b3b99900 100644 --- a/libraries/integration/Microsoft.Bot.Builder.Integration.AspNet.Core/Skills/SkillHttpClient.cs +++ b/libraries/integration/Microsoft.Bot.Builder.Integration.AspNet.Core/Skills/SkillHttpClient.cs @@ -19,6 +19,14 @@ public class SkillHttpClient : BotFrameworkHttpClient { private readonly SkillConversationIdFactoryBase _conversationIdFactory; + /// + /// Initializes a new instance of the class. + /// + /// A HttpClient. + /// An instance of . + /// An instance of a class derived from . + /// An instance of . + /// An instance of . public SkillHttpClient(HttpClient httpClient, ICredentialProvider credentialProvider, SkillConversationIdFactoryBase conversationIdFactory, IChannelProvider channelProvider = null, ILogger logger = null) : base(httpClient, credentialProvider, channelProvider, logger) { @@ -61,11 +69,30 @@ public async Task> PostActivityAsync(string originatingAudi return await PostActivityAsync(fromBotId, toSkill.AppId, toSkill.SkillEndpoint, callbackUrl, skillConversationId, activity, cancellationToken).ConfigureAwait(false); } + /// + /// Forwards an activity to a skill (bot). + /// + /// The MicrosoftAppId of the bot sending the activity. + /// An instance of . + /// The callback Uri. + /// activity to forward. + /// cancellation Token. + /// Async task with optional invokeResponse. public async Task PostActivityAsync(string fromBotId, BotFrameworkSkill toSkill, Uri callbackUrl, Activity activity, CancellationToken cancellationToken) { return await PostActivityAsync(fromBotId, toSkill, callbackUrl, activity, cancellationToken).ConfigureAwait(false); } + /// + /// Forwards an activity to a skill (bot). + /// + /// The MicrosoftAppId of the bot sending the activity. + /// An instance of . + /// The callback Uri. + /// activity to forward. + /// cancellation Token. + /// type of the result. + /// Async task with optional invokeResponse of type T. public async Task> PostActivityAsync(string fromBotId, BotFrameworkSkill toSkill, Uri callbackUrl, Activity activity, CancellationToken cancellationToken) { var originatingAudience = ChannelProvider != null && ChannelProvider.IsGovernment() ? GovernmentAuthenticationConstants.ToChannelFromBotOAuthScope : AuthenticationConstants.ToChannelFromBotOAuthScope; diff --git a/libraries/integration/Microsoft.Bot.Builder.Integration.AspNet.WebApi/BotFrameworkConfigurationBuilder.cs b/libraries/integration/Microsoft.Bot.Builder.Integration.AspNet.WebApi/BotFrameworkConfigurationBuilder.cs index c2deb1befe..3cf504dda3 100644 --- a/libraries/integration/Microsoft.Bot.Builder.Integration.AspNet.WebApi/BotFrameworkConfigurationBuilder.cs +++ b/libraries/integration/Microsoft.Bot.Builder.Integration.AspNet.WebApi/BotFrameworkConfigurationBuilder.cs @@ -9,13 +9,24 @@ namespace Microsoft.Bot.Builder.Integration.AspNet.WebApi { + /// + /// Used to build the configuration settings for a bot application. + /// public class BotFrameworkConfigurationBuilder { + /// + /// Initializes a new instance of the class. + /// + /// An instance of . public BotFrameworkConfigurationBuilder(BotFrameworkOptions botFrameworkOptions) { BotFrameworkOptions = botFrameworkOptions; } + /// + /// Gets the . + /// + /// An instance of . public BotFrameworkOptions BotFrameworkOptions { get; } /// diff --git a/libraries/integration/Microsoft.Bot.Builder.Integration.AspNet.WebApi/BotFrameworkConfigurationBuilderExtensions.cs b/libraries/integration/Microsoft.Bot.Builder.Integration.AspNet.WebApi/BotFrameworkConfigurationBuilderExtensions.cs index e33644f853..88d7714a1c 100644 --- a/libraries/integration/Microsoft.Bot.Builder.Integration.AspNet.WebApi/BotFrameworkConfigurationBuilderExtensions.cs +++ b/libraries/integration/Microsoft.Bot.Builder.Integration.AspNet.WebApi/BotFrameworkConfigurationBuilderExtensions.cs @@ -5,6 +5,9 @@ namespace Microsoft.Bot.Builder.Integration.AspNet.WebApi { + /// + /// Extension methods for . + /// public static class BotFrameworkConfigurationBuilderExtensions { /// diff --git a/libraries/integration/Microsoft.Bot.Builder.Integration.AspNet.WebApi/BotFrameworkHttpAdapter.cs b/libraries/integration/Microsoft.Bot.Builder.Integration.AspNet.WebApi/BotFrameworkHttpAdapter.cs index 988d208b7a..5023570ce9 100644 --- a/libraries/integration/Microsoft.Bot.Builder.Integration.AspNet.WebApi/BotFrameworkHttpAdapter.cs +++ b/libraries/integration/Microsoft.Bot.Builder.Integration.AspNet.WebApi/BotFrameworkHttpAdapter.cs @@ -23,17 +23,39 @@ public class BotFrameworkHttpAdapter : BotFrameworkHttpAdapterBase, IBotFramewor private const string AuthHeaderName = "authorization"; private const string ChannelIdHeaderName = "channelid"; + /// + /// Initializes a new instance of the class. + /// + /// The credential provider. + /// The channel provider. + /// The ILogger implementation this adapter should use. public BotFrameworkHttpAdapter(ICredentialProvider credentialProvider = null, IChannelProvider channelProvider = null, ILogger logger = null) : base(credentialProvider ?? new SimpleCredentialProvider(), channelProvider, logger) { } + /// + /// Initializes a new instance of the class. + /// + /// The credential provider. + /// The channel provider. + /// The used. + /// The ILogger implementation this adapter should use. public BotFrameworkHttpAdapter(ICredentialProvider credentialProvider, IChannelProvider channelProvider, HttpClient httpClient, ILogger logger) : base(credentialProvider ?? new SimpleCredentialProvider(), channelProvider, httpClient, logger) { } - public async Task ProcessAsync(HttpRequestMessage httpRequest, HttpResponseMessage httpResponse, IBot bot, CancellationToken cancellationToken = default) + /// + /// This method can be called from inside a POST method on any Controller implementation. + /// + /// The HTTP request object, typically in a POST handler by a Controller. + /// The HTTP response object. + /// The bot implementation. + /// A cancellation token that can be used by other objects + /// or threads to receive notice of cancellation. + /// A task that represents the work queued to execute. + public async Task ProcessAsync(HttpRequestMessage httpRequest, HttpResponseMessage httpResponse, IBot bot, CancellationToken cancellationToken = default(CancellationToken)) { if (httpRequest == null) { diff --git a/libraries/integration/Microsoft.Bot.Builder.Integration.AspNet.WebApi/BotMessageHandler.cs b/libraries/integration/Microsoft.Bot.Builder.Integration.AspNet.WebApi/BotMessageHandler.cs index 79294f4056..fa2904a6de 100644 --- a/libraries/integration/Microsoft.Bot.Builder.Integration.AspNet.WebApi/BotMessageHandler.cs +++ b/libraries/integration/Microsoft.Bot.Builder.Integration.AspNet.WebApi/BotMessageHandler.cs @@ -8,15 +8,34 @@ namespace Microsoft.Bot.Builder.Integration.AspNet.WebApi.Handlers { + /// + /// A handler to process incoming http requests via using an adapter. + /// public sealed class BotMessageHandler : BotMessageHandlerBase { + /// + /// The route name for the message handler. + /// public static readonly string RouteName = "BotFramework - Message Handler"; + /// + /// Initializes a new instance of the class. + /// + /// An instance of . public BotMessageHandler(IAdapterIntegration adapter) : base(adapter) { } + /// + /// Deserializes the incoming request using a BotMessageHandler, processes it with an + /// and returns an . + /// + /// A . + /// An instance of . + /// An instance of . + /// A . + /// An returned from the adapter. protected override async Task ProcessMessageRequestAsync(HttpRequestMessage request, IAdapterIntegration adapter, BotCallbackHandler botCallbackHandler, CancellationToken cancellationToken) { var activity = await request.Content.ReadAsAsync(BotMessageHandlerBase.BotMessageMediaTypeFormatters, cancellationToken).ConfigureAwait(false); diff --git a/libraries/integration/Microsoft.Bot.Builder.Integration.AspNet.WebApi/BotMessageHandlerBase.cs b/libraries/integration/Microsoft.Bot.Builder.Integration.AspNet.WebApi/BotMessageHandlerBase.cs index a77f757fbf..972d19d4b4 100644 --- a/libraries/integration/Microsoft.Bot.Builder.Integration.AspNet.WebApi/BotMessageHandlerBase.cs +++ b/libraries/integration/Microsoft.Bot.Builder.Integration.AspNet.WebApi/BotMessageHandlerBase.cs @@ -1,113 +1,138 @@ -// Copyright (c) Microsoft Corporation. All rights reserved. -// Licensed under the MIT License. - -using System; -using System.Net; -using System.Net.Http; -using System.Net.Http.Formatting; -using System.Net.Http.Headers; -using System.Threading; -using System.Threading.Tasks; - -namespace Microsoft.Bot.Builder.Integration.AspNet.WebApi.Handlers -{ - public abstract class BotMessageHandlerBase : HttpMessageHandler - { - public static readonly MediaTypeFormatter[] BotMessageMediaTypeFormatters = - { - new JsonMediaTypeFormatter - { - SerializerSettings = MessageSerializerSettings.Create(), - SupportedMediaTypes = - { - new MediaTypeHeaderValue("application/json") { CharSet = "utf-8" }, - new MediaTypeHeaderValue("text/json") { CharSet = "utf-8" }, - }, - }, - }; - - private readonly IAdapterIntegration _adapter; - - public BotMessageHandlerBase(IAdapterIntegration adapter) - { - _adapter = adapter ?? throw new ArgumentNullException(nameof(adapter)); - } - - protected override async Task SendAsync(HttpRequestMessage request, CancellationToken cancellationToken) - { - if (request.Method != HttpMethod.Post) - { - return request.CreateResponse(HttpStatusCode.MethodNotAllowed); - } - - var requestContentHeaders = request.Content.Headers; - - if (requestContentHeaders.ContentLength == 0) - { - return request.CreateErrorResponse(HttpStatusCode.BadRequest, "Request body should not be empty."); - } - - if (!BotMessageMediaTypeFormatters[0].SupportedMediaTypes.Contains(requestContentHeaders.ContentType)) - { - return request.CreateErrorResponse(HttpStatusCode.NotAcceptable, $"Expecting Content-Type of \"{BotMessageMediaTypeFormatters[0].SupportedMediaTypes[0].MediaType}\"."); - } - - try - { - var invokeResponse = await ProcessMessageRequestAsync( - request, - _adapter, - (context, ct) => - { - cancellationToken.ThrowIfCancellationRequested(); - - IBot bot; - - try - { - bot = (IBot)request.GetDependencyScope()?.GetService(typeof(IBot)); - } - catch (Exception exception) - { - throw new Exception($"An exception occurred attempting to resolve an {nameof(IBot)} service via the dependency resolver. Please check the inner exception for more details.", exception); - } - - if (bot == null) - { - throw new InvalidOperationException($"Did not find an {nameof(IBot)} service via the dependency resolver. Please make sure you have registered your bot with your dependency injection container."); - } - - return bot.OnTurnAsync(context, ct); - }, - cancellationToken).ConfigureAwait(false); - - if (invokeResponse == null) - { - return request.CreateResponse(HttpStatusCode.OK); - } - - var response = request.CreateResponse((HttpStatusCode)invokeResponse.Status); - - if (invokeResponse.Body != null) - { - response.Content = new ObjectContent( - invokeResponse.Body.GetType(), - invokeResponse.Body, - BotMessageMediaTypeFormatters[0]); - } - - return response; - } - catch (UnauthorizedAccessException e) - { - return request.CreateErrorResponse(HttpStatusCode.Unauthorized, e.Message); - } - catch (InvalidOperationException e) - { - return request.CreateErrorResponse(HttpStatusCode.NotFound, e.Message); - } - } - - protected abstract Task ProcessMessageRequestAsync(HttpRequestMessage request, IAdapterIntegration adapter, BotCallbackHandler botCallbackHandler, CancellationToken cancellationToken); - } -} +// Copyright (c) Microsoft Corporation. All rights reserved. +// Licensed under the MIT License. + +using System; +using System.Net; +using System.Net.Http; +using System.Net.Http.Formatting; +using System.Net.Http.Headers; +using System.Threading; +using System.Threading.Tasks; + +namespace Microsoft.Bot.Builder.Integration.AspNet.WebApi.Handlers +{ + /// + /// Abstract base class for a bot message handler. + /// + public abstract class BotMessageHandlerBase : HttpMessageHandler + { + /// + /// A defining the support media types for bot messages. + /// + public static readonly MediaTypeFormatter[] BotMessageMediaTypeFormatters = new[] + { + new JsonMediaTypeFormatter + { + SerializerSettings = MessageSerializerSettings.Create(), + SupportedMediaTypes = + { + new MediaTypeHeaderValue("application/json") { CharSet = "utf-8" }, + new MediaTypeHeaderValue("text/json") { CharSet = "utf-8" }, + }, + }, + }; + + private readonly IAdapterIntegration _adapter; + + /// + /// Initializes a new instance of the class. + /// + /// An instance of . + public BotMessageHandlerBase(IAdapterIntegration adapter) + { + _adapter = adapter ?? throw new ArgumentNullException(nameof(adapter)); + } + + /// + /// Processes the incoming request using the adapter and returns a response. + /// + /// An instance of . + /// An instance of . + /// A . + protected override async Task SendAsync(HttpRequestMessage request, CancellationToken cancellationToken) + { + if (request.Method != HttpMethod.Post) + { + return request.CreateResponse(HttpStatusCode.MethodNotAllowed); + } + + var requestContentHeaders = request.Content.Headers; + + if (requestContentHeaders.ContentLength == 0) + { + return request.CreateErrorResponse(HttpStatusCode.BadRequest, "Request body should not be empty."); + } + + if (!BotMessageMediaTypeFormatters[0].SupportedMediaTypes.Contains(requestContentHeaders.ContentType)) + { + return request.CreateErrorResponse(HttpStatusCode.NotAcceptable, $"Expecting Content-Type of \"{BotMessageMediaTypeFormatters[0].SupportedMediaTypes[0].MediaType}\"."); + } + + try + { + var invokeResponse = await ProcessMessageRequestAsync( + request, + _adapter, + (context, ct) => + { + cancellationToken.ThrowIfCancellationRequested(); + + IBot bot; + + try + { + bot = (IBot)request.GetDependencyScope()?.GetService(typeof(IBot)); + } + catch (Exception exception) + { + throw new Exception($"An exception occurred attempting to resolve an {nameof(IBot)} service via the dependency resolver. Please check the inner exception for more details.", exception); + } + + if (bot == null) + { + throw new InvalidOperationException($"Did not find an {nameof(IBot)} service via the dependency resolver. Please make sure you have registered your bot with your dependency injection container."); + } + + return bot.OnTurnAsync(context, ct); + }, + cancellationToken).ConfigureAwait(false); + + if (invokeResponse == null) + { + return request.CreateResponse(HttpStatusCode.OK); + } + + var response = request.CreateResponse((HttpStatusCode)invokeResponse.Status); + + if (invokeResponse.Body != null) + { + response.Content = new ObjectContent( + invokeResponse.Body.GetType(), + invokeResponse.Body, + BotMessageMediaTypeFormatters[0]); + } + + return response; + } + catch (UnauthorizedAccessException e) + { + return request.CreateErrorResponse(HttpStatusCode.Unauthorized, e.Message); + } + catch (InvalidOperationException e) + { + return request.CreateErrorResponse(HttpStatusCode.NotFound, e.Message); + } + } + + /// + /// Abstract method to process the incoming request using the instance of + /// and to return an . + /// + /// A . + /// An instance of . + /// An instance of . + /// A . + /// An returned from the adapter. + protected abstract Task ProcessMessageRequestAsync(HttpRequestMessage request, IAdapterIntegration adapter, BotCallbackHandler botCallbackHandler, CancellationToken cancellationToken); + } +} diff --git a/libraries/integration/Microsoft.Bot.Builder.Integration.AspNet.WebApi/ConfigurationChannelProvider.cs b/libraries/integration/Microsoft.Bot.Builder.Integration.AspNet.WebApi/ConfigurationChannelProvider.cs index fd5ad585fe..253e418a7c 100644 --- a/libraries/integration/Microsoft.Bot.Builder.Integration.AspNet.WebApi/ConfigurationChannelProvider.cs +++ b/libraries/integration/Microsoft.Bot.Builder.Integration.AspNet.WebApi/ConfigurationChannelProvider.cs @@ -21,6 +21,9 @@ public sealed class ConfigurationChannelProvider : SimpleChannelProvider /// public const string ChannelServiceKey = "ChannelService"; + /// + /// Initializes a new instance of the class. + /// public ConfigurationChannelProvider() { this.ChannelService = ConfigurationManager.AppSettings[ChannelServiceKey]; diff --git a/libraries/integration/Microsoft.Bot.Builder.Integration.AspNet.WebApi/ConfigurationCredentialProvider.cs b/libraries/integration/Microsoft.Bot.Builder.Integration.AspNet.WebApi/ConfigurationCredentialProvider.cs index 2e8b104a36..f0d4221380 100644 --- a/libraries/integration/Microsoft.Bot.Builder.Integration.AspNet.WebApi/ConfigurationCredentialProvider.cs +++ b/libraries/integration/Microsoft.Bot.Builder.Integration.AspNet.WebApi/ConfigurationCredentialProvider.cs @@ -17,6 +17,9 @@ namespace Microsoft.Bot.Builder.BotFramework /// public sealed class ConfigurationCredentialProvider : SimpleCredentialProvider { + /// + /// Initializes a new instance of the class. + /// public ConfigurationCredentialProvider() { this.AppId = ConfigurationManager.AppSettings[MicrosoftAppCredentials.MicrosoftAppIdKey]; diff --git a/libraries/integration/Microsoft.Bot.Builder.Integration.AspNet.WebApi/HttpConfigurationExtensions.cs b/libraries/integration/Microsoft.Bot.Builder.Integration.AspNet.WebApi/HttpConfigurationExtensions.cs index 52621156cd..242c206f9b 100644 --- a/libraries/integration/Microsoft.Bot.Builder.Integration.AspNet.WebApi/HttpConfigurationExtensions.cs +++ b/libraries/integration/Microsoft.Bot.Builder.Integration.AspNet.WebApi/HttpConfigurationExtensions.cs @@ -10,6 +10,9 @@ namespace Microsoft.Bot.Builder.Integration.AspNet.WebApi { + /// + /// Extension methods for . + /// public static class HttpConfigurationExtensions { /// diff --git a/libraries/integration/Microsoft.Bot.Builder.Integration.AspNet.WebApi/Microsoft.Bot.Builder.Integration.AspNet.WebApi.csproj b/libraries/integration/Microsoft.Bot.Builder.Integration.AspNet.WebApi/Microsoft.Bot.Builder.Integration.AspNet.WebApi.csproj index 187dc1477c..e9fc151c2b 100644 --- a/libraries/integration/Microsoft.Bot.Builder.Integration.AspNet.WebApi/Microsoft.Bot.Builder.Integration.AspNet.WebApi.csproj +++ b/libraries/integration/Microsoft.Bot.Builder.Integration.AspNet.WebApi/Microsoft.Bot.Builder.Integration.AspNet.WebApi.csproj @@ -17,11 +17,6 @@ This library integrates the Microsoft Bot Builder SDK with ASP.NET WebAPI. It offers idiomatic configuration APIs in addition to providing all the plumbing to direct incoming bot messages to a configured bot. This library provides integration between the Microsoft Bot Builder SDK and ASP.NET WebAPI. - - - - $(NoWarn);CS1591 - Full