From 65237c4858a282d85148efb7a2e545dfefcc8332 Mon Sep 17 00:00:00 2001 From: Gary Pretty Date: Fri, 19 Jun 2020 08:50:21 +0100 Subject: [PATCH 1/2] Added code docs to AppInsights Core lib --- .../ApplicationBuilderExtensions.cs | 6 ++++++ ...r.Integration.ApplicationInsights.Core.csproj | 5 ----- .../ServiceCollectionExtensions.cs | 3 +++ .../TelemetryBotIdInitializer.cs | 9 +++++++++ .../TelemetrySaveBodyASPMiddleware.cs | 16 ++++++++++++++-- 5 files changed, 32 insertions(+), 7 deletions(-) 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 3c99ce50b5..ab163ce408 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..9d3ff8be3a 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 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 37d3dcccda..13db5e80c1 100644 --- a/libraries/integration/Microsoft.Bot.Builder.Integration.ApplicationInsights.Core/TelemetrySaveBodyASPMiddleware.cs +++ b/libraries/integration/Microsoft.Bot.Builder.Integration.ApplicationInsights.Core/TelemetrySaveBodyASPMiddleware.cs @@ -11,18 +11,30 @@ 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.")] 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; From e89fe315d3b091769033e5fa5408bf75066a5afb Mon Sep 17 00:00:00 2001 From: Gary Pretty Date: Fri, 19 Jun 2020 19:29:51 +0100 Subject: [PATCH 2/2] Add missing code docs to integration libraries --- .../TelemetryBotIdInitializer.cs | 2 +- ...egration.ApplicationInsights.WebApi.csproj | 5 -- .../TelemetryBotIdInitializer.cs | 7 +++ .../BotFrameworkHttpAdapter.cs | 40 ++++++++++++++ .../BotFrameworkHttpClient.cs | 52 ++++++++++++++++++- .../BotMessageHandler.cs | 12 +++++ .../BotMessageHandlerBase.cs | 24 +++++++++ .../ConfigurationChannelProvider.cs | 4 ++ .../ConfigurationCredentialProvider.cs | 4 ++ .../HttpHelper.cs | 23 ++++++++ ...Bot.Builder.Integration.AspNet.Core.csproj | 5 -- .../Skills/SkillHttpClient.cs | 27 ++++++++++ .../BotFrameworkConfigurationBuilder.cs | 11 ++++ ...FrameworkConfigurationBuilderExtensions.cs | 3 ++ .../BotFrameworkHttpAdapter.cs | 22 ++++++++ .../BotMessageHandler.cs | 19 +++++++ .../BotMessageHandlerBase.cs | 25 +++++++++ .../ConfigurationChannelProvider.cs | 3 ++ .../ConfigurationCredentialProvider.cs | 3 ++ .../HttpConfigurationExtensions.cs | 3 ++ ...t.Builder.Integration.AspNet.WebApi.csproj | 5 -- 21 files changed, 281 insertions(+), 18 deletions(-) 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 9d3ff8be3a..eb87193bb7 100644 --- a/libraries/integration/Microsoft.Bot.Builder.Integration.ApplicationInsights.Core/TelemetryBotIdInitializer.cs +++ b/libraries/integration/Microsoft.Bot.Builder.Integration.ApplicationInsights.Core/TelemetryBotIdInitializer.cs @@ -18,7 +18,7 @@ namespace Microsoft.Bot.Builder.Integration.ApplicationInsights.Core public class TelemetryBotIdInitializer : ITelemetryInitializer { /// - /// Constant key used for storing information in turn state. + /// Constant key used for storing activity information in turn state. /// public static readonly string BotActivityKey = "BotBuilderActivity"; 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 e8db339f98..b9db651a5c 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 2488877b59..22a1b7bd21 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 60ddc13ad2..16147b10ac 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 758b735c50..d3300dd1ec 100644 --- a/libraries/integration/Microsoft.Bot.Builder.Integration.AspNet.Core/BotFrameworkHttpClient.cs +++ b/libraries/integration/Microsoft.Bot.Builder.Integration.AspNet.Core/BotFrameworkHttpClient.cs @@ -18,8 +18,18 @@ namespace Microsoft.Bot.Builder.Integration.AspNet.Core { + /// + /// A client for posting Bot Framework activities. + /// 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, @@ -33,18 +43,56 @@ 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; } + /// + /// Forwards an activity to a skill (bot). + /// + /// The MicrosoftAppId of the bot sending the activity. + /// The MicrosoftAppId of the bot receiving the activity. + /// The URL of the bot receiving the activity. + /// The callback Url for the skill host. + /// A conversation ID to use for the conversation with the skill. + /// activity to forward. + /// cancellation Token. + /// Async task with optional invokeResponse. public override async Task PostActivityAsync(string fromBotId, string toBotId, Uri toUrl, Uri serviceUrl, string conversationId, Activity activity, CancellationToken cancellationToken = default) { return await PostActivityAsync(fromBotId, toBotId, toUrl, serviceUrl, conversationId, activity, cancellationToken).ConfigureAwait(false); 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 f3e5d7ea52..6e982a5b4e 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) { var activity = default(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 de2948ff75..815ff7d2fd 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; @@ -98,6 +113,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 ee8b690fb7..4c399244c7 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 07b94bc30b..8ca65ff8d7 100644 --- a/libraries/integration/Microsoft.Bot.Builder.Integration.AspNet.WebApi/BotFrameworkHttpAdapter.cs +++ b/libraries/integration/Microsoft.Bot.Builder.Integration.AspNet.WebApi/BotFrameworkHttpAdapter.cs @@ -24,16 +24,38 @@ 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) { } + /// + /// 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 36d0cbc6d8..cbce31c8b1 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 0c33d10341..46b074b336 100644 --- a/libraries/integration/Microsoft.Bot.Builder.Integration.AspNet.WebApi/BotMessageHandlerBase.cs +++ b/libraries/integration/Microsoft.Bot.Builder.Integration.AspNet.WebApi/BotMessageHandlerBase.cs @@ -10,8 +10,14 @@ 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 @@ -27,11 +33,21 @@ public abstract class BotMessageHandlerBase : HttpMessageHandler 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) @@ -111,6 +127,15 @@ protected override async Task SendAsync(HttpRequestMessage } } + /// + /// 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 3059053479..f9a7e9dc6d 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 c44948c1c7..72df650d38 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