Merge branch 'main' into users/tracyboehrer/cards-sample

Author: tracyboehrer

src/libraries/Hosting/AspNetCore/ServiceCollectionExtensions.cs

@@ -6,7 +6,6 @@
 using Microsoft.Agents.Builder.App.UserAuth;
 using Microsoft.Agents.Builder.App;
 using Microsoft.Agents.Hosting.AspNetCore.BackgroundQueue;
-using Microsoft.Agents.Storage;
 using Microsoft.Extensions.DependencyInjection;
 using Microsoft.Extensions.Hosting;
 using System;
@@ -16,35 +15,89 @@ namespace Microsoft.Agents.Hosting.AspNetCore
 {
     public static class ServiceCollectionExtensions
     {
-        public static IHostApplicationBuilder AddAgent(this IHostApplicationBuilder builder, Func<IServiceProvider, IAgent> implementationFactory, IStorage storage = null)
+        /// <summary>
+        /// Adds an Agent which subclasses <c>AgentApplication</c>
+        /// <code>
+        /// builder.Services.AddSingleton&lt;IStorage, MemoryStorage&gt;();
+        /// builder.AddAgentApplicationOptions();
+        /// builder.AddAgent&lt;MyAgent&gt;();
+        /// </code>
+        /// </summary>
+        /// <remarks>
+        /// This will also call <see cref="AddAgentCore(IHostApplicationBuilder)"/> and uses <c>CloudAdapter</c>.
+        /// The Agent is registered as Transient.
+        /// </remarks>
+        /// <typeparam name="TAgent"></typeparam>
+        /// <param name="builder"></param>
+        public static IHostApplicationBuilder AddAgent<TAgent>(this IHostApplicationBuilder builder)
+            where TAgent : class, IAgent
         {
-            return AddAgent<CloudAdapter>(builder, implementationFactory, storage);
+            return AddAgent<TAgent, CloudAdapter>(builder);
         }
 
-        public static IHostApplicationBuilder AddAgent<TAdapter>(this IHostApplicationBuilder builder, Func<IServiceProvider, IAgent> implementationFactory, IStorage storage = null)
+        /// <summary>
+        /// Same as <see cref="AddAgent{TAgent}(IHostApplicationBuilder)"/> but allows for use of
+        /// any <c>CloudAdapter</c> subclass.
+        /// </summary>
+        /// <typeparam name="TAgent"></typeparam>
+        /// <typeparam name="TAdapter"></typeparam>
+        /// <param name="builder"></param>
+        public static IHostApplicationBuilder AddAgent<TAgent, TAdapter>(this IHostApplicationBuilder builder)
+            where TAgent : class, IAgent
             where TAdapter : CloudAdapter
         {
-            AddCore<TAdapter>(builder, storage);
+            AddAgentCore<TAdapter>(builder);
 
-            builder.Services.AddTransient<IAgent>(implementationFactory);
+            // Add the Agent 
+            builder.Services.AddTransient<IAgent, TAgent>();
 
             return builder;
         }
 
-        public static IHostApplicationBuilder AddAgent<TAgent>(this IHostApplicationBuilder builder, IStorage storage = null)
-            where TAgent : class, IAgent
+        /// <summary>
+        /// Adds an Agent via lambda construction.
+        /// <code>
+        /// builder.Services.AddSingleton&lt;IStorage, MemoryStorage&gt;();
+        /// builder.AddAgentApplicationOptions();
+        /// builder.AddAgent(sp =>
+        /// {
+        ///    var options = new AgentApplicationOptions()
+        ///    {
+        ///       TurnStateFactory = () => new TurnState(sp.GetService&lt;IStorage&gt;());
+        ///    };
+        ///        
+        ///    var app = new AgentApplication(options);
+        ///
+        ///    ...
+        ///
+        ///    return app;
+        /// });
+        /// </code>
+        /// </summary>
+        /// <remarks>
+        /// This will also calls <see cref="AddAgentCore(IHostApplicationBuilder)"/> and uses <c>CloudAdapter</c>.
+        /// The Agent is registered as Transient.
+        /// </remarks>
+        /// <param name="builder"></param>
+        /// <param name="implementationFactory"></param>
+        public static IHostApplicationBuilder AddAgent(this IHostApplicationBuilder builder, Func<IServiceProvider, IAgent> implementationFactory)
         {
-            return AddAgent<TAgent, CloudAdapter>(builder, storage);
+            return AddAgent<CloudAdapter>(builder, implementationFactory);
         }
 
-        public static IHostApplicationBuilder AddAgent<TAgent, TAdapter>(this IHostApplicationBuilder builder, IStorage storage = null)
-            where TAgent : class, IAgent
+        /// <summary>
+        /// This is the same as <see cref="AddAgent(IHostApplicationBuilder, Func{IServiceProvider, IAgent})"/>, except allows the
+        /// use of any <c>CloudAdapter</c> subclass.
+        /// </summary>
+        /// <typeparam name="TAdapter"></typeparam>
+        /// <param name="builder"></param>
+        /// <param name="implementationFactory"></param>
+        public static IHostApplicationBuilder AddAgent<TAdapter>(this IHostApplicationBuilder builder, Func<IServiceProvider, IAgent> implementationFactory)
             where TAdapter : CloudAdapter
         {
-            AddCore<TAdapter>(builder, storage);
+            AddAgentCore<TAdapter>(builder);
 
-            // Add the Agent 
-            builder.Services.AddTransient<IAgent, TAgent>();
+            builder.Services.AddTransient<IAgent>(implementationFactory);
 
             return builder;
         }
@@ -53,7 +106,8 @@ public static IHostApplicationBuilder AddAgent<TAgent, TAdapter>(this IHostAppli
         /// Registers AgentApplicationOptions for AgentApplication-based Agents.
         /// </summary>
         /// <remarks>
-        /// This loads options from IConfiguration and DI.
+        /// This loads options from IConfiguration and DI.  The <c>AgentApplicationOptions</c> is
+        /// added as a singleton.
         /// </remarks>
         /// <param name="builder"></param>
         /// <param name="fileDownloaders"></param>
@@ -90,7 +144,7 @@ public static void AddCloudAdapter(this IServiceCollection services)
         }
 
         /// <summary>
-        /// Add the derived CloudAdapter.
+        /// Add a derived CloudAdapter.
         /// </summary>
         /// <param name="services"></param>
         /// <param name="async"></param>
@@ -103,9 +157,21 @@ public static void AddCloudAdapter<T>(this IServiceCollection services) where T
             services.AddSingleton<IChannelAdapter>(sp => sp.GetService<CloudAdapter>());
         }
 
+        /// <summary>
+        /// Adds the core agent services.
+        /// <list type="bullet">
+        /// <item><c>IConnections, which uses IConfiguration for settings.</c></item>
+        /// <item><c>IChannelServiceClientFactory</c> for ConnectorClient and UserTokenClient creations.  Needed for Azure Bot Service and Agent-to-Agent.</item>
+        /// <item><c>CloudAdapter</c>, this is the default adapter that works with Azure Bot Service and Activity Protocol Agents.</item>
+        /// </list>
+        /// </summary>
+        /// <param name="builder"></param>
+        public static IHostApplicationBuilder AddAgentCore(this IHostApplicationBuilder builder)
+        {
+            return builder.AddAgentCore<CloudAdapter>();
+        }
 
-
-        private static void AddCore<TAdapter>(this IHostApplicationBuilder builder, IStorage storage = null)
+        public static IHostApplicationBuilder AddAgentCore<TAdapter>(this IHostApplicationBuilder builder)
             where TAdapter : CloudAdapter
         {
             // Add Connections object to access configured token connections.
@@ -114,14 +180,10 @@ private static void AddCore<TAdapter>(this IHostApplicationBuilder builder, ISto
             // Add factory for ConnectorClient and UserTokenClient creation
             builder.Services.AddSingleton<IChannelServiceClientFactory, RestChannelServiceClientFactory>();
 
-            // Add IStorage for turn state persistence
-            if (storage != null)
-            {
-                builder.Services.AddSingleton(storage);
-            }
-
             // Add the CloudAdapter, this is the default adapter that works with Azure Bot Service and Activity Protocol Agents.
             AddCloudAdapter<TAdapter>(builder.Services);
+
+            return builder;
         }
 
         private static void AddAsyncCloudAdapterSupport(this IServiceCollection services)