diff --git a/src/Http/Http.Features/src/ISession.cs b/src/Http/Http.Features/src/ISession.cs index 6bd780684d..b196b5140c 100644 --- a/src/Http/Http.Features/src/ISession.cs +++ b/src/Http/Http.Features/src/ISession.cs @@ -7,6 +7,10 @@ using System.Threading.Tasks; namespace Microsoft.AspNetCore.Http { + /// + /// Stores user data while the user browses a web application. Session state uses a store maintained by the application + /// to persist data across requests from a client. The session data is backed by a cache and considered ephemeral data. + /// public interface ISession { /// diff --git a/src/Http/Http.Features/src/ISessionFeature.cs b/src/Http/Http.Features/src/ISessionFeature.cs index 2365299415..05f1eb7dd0 100644 --- a/src/Http/Http.Features/src/ISessionFeature.cs +++ b/src/Http/Http.Features/src/ISessionFeature.cs @@ -3,8 +3,14 @@ namespace Microsoft.AspNetCore.Http.Features { + /// + /// Provides access to the for the current request. + /// public interface ISessionFeature { + /// + /// The for the current request. + /// ISession Session { get; set; } } } \ No newline at end of file diff --git a/src/Middleware/Diagnostics.EntityFrameworkCore/src/DatabaseDeveloperPageExceptionFilter.cs b/src/Middleware/Diagnostics.EntityFrameworkCore/src/DatabaseDeveloperPageExceptionFilter.cs index 447124077e..dbf8328ee5 100644 --- a/src/Middleware/Diagnostics.EntityFrameworkCore/src/DatabaseDeveloperPageExceptionFilter.cs +++ b/src/Middleware/Diagnostics.EntityFrameworkCore/src/DatabaseDeveloperPageExceptionFilter.cs @@ -16,17 +16,33 @@ using Microsoft.Extensions.Options; #nullable enable namespace Microsoft.AspNetCore.Diagnostics.EntityFrameworkCore { + /// + /// An that captures database-related exceptions that can be resolved by using Entity Framework migrations. + /// When these exceptions occur, an HTML response with details about possible actions to resolve the issue is generated. + /// + /// + /// This should only be enabled in the Development environment. + /// public sealed class DatabaseDeveloperPageExceptionFilter : IDeveloperPageExceptionFilter { private readonly ILogger _logger; private readonly DatabaseErrorPageOptions _options; + /// + /// Initializes a new instance of . + /// + /// The . + /// The . public DatabaseDeveloperPageExceptionFilter(ILogger logger, IOptions options) { _logger = logger ?? throw new ArgumentNullException(nameof(logger)); _options = options?.Value ?? throw new ArgumentNullException(nameof(options)); } + /// + /// Handle errors and output an HTML response with additional details. + /// + /// public async Task HandleExceptionAsync(ErrorContext errorContext, Func next) { if (!(errorContext.Exception is DbException)) diff --git a/src/Middleware/Diagnostics.EntityFrameworkCore/src/DatabaseDeveloperPageExceptionFilterServiceExtensions.cs b/src/Middleware/Diagnostics.EntityFrameworkCore/src/DatabaseDeveloperPageExceptionFilterServiceExtensions.cs index 51041852b5..72c0b17012 100644 --- a/src/Middleware/Diagnostics.EntityFrameworkCore/src/DatabaseDeveloperPageExceptionFilterServiceExtensions.cs +++ b/src/Middleware/Diagnostics.EntityFrameworkCore/src/DatabaseDeveloperPageExceptionFilterServiceExtensions.cs @@ -15,10 +15,14 @@ namespace Microsoft.Extensions.DependencyInjection public static class DatabaseDeveloperPageExceptionFilterServiceExtensions { /// - /// Add response caching services. + /// In combination with UseDeveloperExceptionPage, this captures database-related exceptions that can be resolved by using Entity Framework migrations. + /// When these exceptions occur, an HTML response with details about possible actions to resolve the issue is generated. /// /// The for adding services. /// + /// + /// This should only be enabled in the Development environment. + /// public static IServiceCollection AddDatabaseDeveloperPageExceptionFilter(this IServiceCollection services) { if (services == null) diff --git a/src/Middleware/Diagnostics.EntityFrameworkCore/src/Microsoft.AspNetCore.Diagnostics.EntityFrameworkCore.csproj b/src/Middleware/Diagnostics.EntityFrameworkCore/src/Microsoft.AspNetCore.Diagnostics.EntityFrameworkCore.csproj index 36e5b56079..0a608c511f 100644 --- a/src/Middleware/Diagnostics.EntityFrameworkCore/src/Microsoft.AspNetCore.Diagnostics.EntityFrameworkCore.csproj +++ b/src/Middleware/Diagnostics.EntityFrameworkCore/src/Microsoft.AspNetCore.Diagnostics.EntityFrameworkCore.csproj @@ -3,7 +3,7 @@ ASP.NET Core middleware for Entity Framework Core error pages. Use this middleware to detect and diagnose errors with Entity Framework Core migrations. $(DefaultNetCoreTargetFramework) - $(NoWarn);CS1591 + $(NoWarn.Replace('1591', '')) true aspnetcore;diagnostics;entityframeworkcore diff --git a/src/Middleware/Diagnostics/src/DeveloperExceptionPage/DeveloperExceptionPageExtensions.cs b/src/Middleware/Diagnostics/src/DeveloperExceptionPage/DeveloperExceptionPageExtensions.cs index 6ef0f6dfe1..2752263847 100644 --- a/src/Middleware/Diagnostics/src/DeveloperExceptionPage/DeveloperExceptionPageExtensions.cs +++ b/src/Middleware/Diagnostics/src/DeveloperExceptionPage/DeveloperExceptionPageExtensions.cs @@ -17,6 +17,9 @@ namespace Microsoft.AspNetCore.Builder /// /// The . /// A reference to the after the operation has completed. + /// + /// This should only be enabled in the Development environment. + /// public static IApplicationBuilder UseDeveloperExceptionPage(this IApplicationBuilder app) { if (app == null) @@ -33,6 +36,9 @@ namespace Microsoft.AspNetCore.Builder /// The . /// A that specifies options for the middleware. /// A reference to the after the operation has completed. + /// + /// This should only be enabled in the Development environment. + /// public static IApplicationBuilder UseDeveloperExceptionPage( this IApplicationBuilder app, DeveloperExceptionPageOptions options) diff --git a/src/Middleware/HeaderPropagation/src/DependencyInjection/HeaderPropagationApplicationBuilderExtensions.cs b/src/Middleware/HeaderPropagation/src/DependencyInjection/HeaderPropagationApplicationBuilderExtensions.cs index 7297b1de7e..b0a23c6d6d 100644 --- a/src/Middleware/HeaderPropagation/src/DependencyInjection/HeaderPropagationApplicationBuilderExtensions.cs +++ b/src/Middleware/HeaderPropagation/src/DependencyInjection/HeaderPropagationApplicationBuilderExtensions.cs @@ -8,6 +8,9 @@ using Microsoft.Extensions.DependencyInjection; namespace Microsoft.AspNetCore.Builder { + /// + /// extension methods for which propagates request headers to an . + /// public static class HeaderPropagationApplicationBuilderExtensions { private static readonly string _unableToFindServices = string.Format( diff --git a/src/Middleware/HeaderPropagation/src/DependencyInjection/HeaderPropagationHttpClientBuilderExtensions.cs b/src/Middleware/HeaderPropagation/src/DependencyInjection/HeaderPropagationHttpClientBuilderExtensions.cs index cf28277a62..8a01fc74e6 100644 --- a/src/Middleware/HeaderPropagation/src/DependencyInjection/HeaderPropagationHttpClientBuilderExtensions.cs +++ b/src/Middleware/HeaderPropagation/src/DependencyInjection/HeaderPropagationHttpClientBuilderExtensions.cs @@ -7,6 +7,9 @@ using Microsoft.Extensions.Options; namespace Microsoft.Extensions.DependencyInjection { + /// + /// extension methods for which propagates request headers to an . + /// public static class HeaderPropagationHttpClientBuilderExtensions { /// diff --git a/src/Middleware/HeaderPropagation/src/DependencyInjection/HeaderPropagationServiceCollectionExtensions.cs b/src/Middleware/HeaderPropagation/src/DependencyInjection/HeaderPropagationServiceCollectionExtensions.cs index ab3d60cc0d..e7f99064d4 100644 --- a/src/Middleware/HeaderPropagation/src/DependencyInjection/HeaderPropagationServiceCollectionExtensions.cs +++ b/src/Middleware/HeaderPropagation/src/DependencyInjection/HeaderPropagationServiceCollectionExtensions.cs @@ -8,6 +8,9 @@ using Microsoft.Extensions.DependencyInjection.Extensions; namespace Microsoft.Extensions.DependencyInjection { + /// + /// extension methods for which propagates request headers to an . + /// public static class HeaderPropagationServiceCollectionExtensions { /// diff --git a/src/Middleware/HeaderPropagation/src/HeaderPropagationMiddleware.cs b/src/Middleware/HeaderPropagation/src/HeaderPropagationMiddleware.cs index f62c9e4a72..afc31374c9 100644 --- a/src/Middleware/HeaderPropagation/src/HeaderPropagationMiddleware.cs +++ b/src/Middleware/HeaderPropagation/src/HeaderPropagationMiddleware.cs @@ -12,7 +12,7 @@ using Microsoft.Extensions.Primitives; namespace Microsoft.AspNetCore.HeaderPropagation { /// - /// A Middleware for propagating headers to a . + /// A Middleware for propagating headers to an . /// public class HeaderPropagationMiddleware { @@ -20,6 +20,14 @@ namespace Microsoft.AspNetCore.HeaderPropagation private readonly HeaderPropagationOptions _options; private readonly HeaderPropagationValues _values; + /// + /// Initializes a new instance of . + /// + /// The next middleware in the pipeline. + /// The . + /// + /// The that stores the request headers to be propagated in an + /// public HeaderPropagationMiddleware(RequestDelegate next, IOptions options, HeaderPropagationValues values) { _next = next ?? throw new ArgumentNullException(nameof(next)); @@ -33,6 +41,10 @@ namespace Microsoft.AspNetCore.HeaderPropagation _values = values ?? throw new ArgumentNullException(nameof(values)); } + /// + /// Executes the middleware that stores the request headers to be propagated in using . + /// + /// The for the current request. public Task Invoke(HttpContext context) { // We need to intialize the headers because the message handler will use this to detect misconfiguration. diff --git a/src/Middleware/HeaderPropagation/src/Microsoft.AspNetCore.HeaderPropagation.csproj b/src/Middleware/HeaderPropagation/src/Microsoft.AspNetCore.HeaderPropagation.csproj index 717e48d779..999ece225c 100644 --- a/src/Middleware/HeaderPropagation/src/Microsoft.AspNetCore.HeaderPropagation.csproj +++ b/src/Middleware/HeaderPropagation/src/Microsoft.AspNetCore.HeaderPropagation.csproj @@ -1,9 +1,9 @@ - + ASP.NET Core middleware to propagate HTTP headers from the incoming request to the outgoing HTTP Client requests $(DefaultNetCoreTargetFramework) - $(NoWarn);CS1591 + $(NoWarn.Replace('1591', '')) true aspnetcore;httpclient diff --git a/src/Middleware/MiddlewareAnalysis/src/AnalysisBuilder.cs b/src/Middleware/MiddlewareAnalysis/src/AnalysisBuilder.cs index f26ca9926a..62717afc90 100644 --- a/src/Middleware/MiddlewareAnalysis/src/AnalysisBuilder.cs +++ b/src/Middleware/MiddlewareAnalysis/src/AnalysisBuilder.cs @@ -9,10 +9,18 @@ using Microsoft.AspNetCore.Http.Features; namespace Microsoft.AspNetCore.MiddlewareAnalysis { + /// + /// An decorator used by + /// to add before and after each other middleware in the pipeline. + /// public class AnalysisBuilder : IApplicationBuilder { private const string NextMiddlewareName = "analysis.NextMiddlewareName"; + /// + /// Initializes a new instance of . + /// + /// The to decorate. public AnalysisBuilder(IApplicationBuilder inner) { InnerBuilder = inner; @@ -20,22 +28,26 @@ namespace Microsoft.AspNetCore.MiddlewareAnalysis private IApplicationBuilder InnerBuilder { get; } + /// public IServiceProvider ApplicationServices { get { return InnerBuilder.ApplicationServices; } set { InnerBuilder.ApplicationServices = value; } } + /// public IDictionary Properties { get { return InnerBuilder.Properties; } } + /// public IFeatureCollection ServerFeatures { get { return InnerBuilder.ServerFeatures;} } + /// public RequestDelegate Build() { // Add one maker at the end before the default 404 middleware (or any fancy Join middleware). @@ -43,11 +55,13 @@ namespace Microsoft.AspNetCore.MiddlewareAnalysis .Build(); } + /// public IApplicationBuilder New() { return new AnalysisBuilder(InnerBuilder.New()); } + /// public IApplicationBuilder Use(Func middleware) { string middlewareName = string.Empty; // UseMiddleware doesn't work with null params. diff --git a/src/Middleware/MiddlewareAnalysis/src/AnalysisMiddleware.cs b/src/Middleware/MiddlewareAnalysis/src/AnalysisMiddleware.cs index 081f64f0ce..eaa4985c86 100644 --- a/src/Middleware/MiddlewareAnalysis/src/AnalysisMiddleware.cs +++ b/src/Middleware/MiddlewareAnalysis/src/AnalysisMiddleware.cs @@ -8,6 +8,10 @@ using Microsoft.AspNetCore.Http; namespace Microsoft.AspNetCore.MiddlewareAnalysis { + /// + /// Middleware that is inserted before and after each other middleware in the pipeline by + /// to log to a when other middleware starts, finishes and throws. + /// public class AnalysisMiddleware { private readonly Guid _instanceId = Guid.NewGuid(); @@ -15,6 +19,15 @@ namespace Microsoft.AspNetCore.MiddlewareAnalysis private readonly DiagnosticSource _diagnostics; private readonly string _middlewareName; + /// + /// Initializes a new instance of . + /// + /// The next middleware in the pipeline. + /// The to log when other middleware starts, finishes and throws. + /// + /// The name of the next middleware in the pipeline. This name is typically retrieved from + /// using the "analysis.NextMiddlewareName" key. + /// public AnalysisMiddleware(RequestDelegate next, DiagnosticSource diagnosticSource, string middlewareName) { _next = next; @@ -26,6 +39,10 @@ namespace Microsoft.AspNetCore.MiddlewareAnalysis _middlewareName = middlewareName; } + /// + /// Executes the middleware that logs to a when the next middleware starts, finishes and throws. + /// + /// The for the current request. public async Task Invoke(HttpContext httpContext) { var startTimestamp = Stopwatch.GetTimestamp(); diff --git a/src/Middleware/MiddlewareAnalysis/src/AnalysisServiceCollectionExtensions.cs b/src/Middleware/MiddlewareAnalysis/src/AnalysisServiceCollectionExtensions.cs index c86020bc7d..a10a05d462 100644 --- a/src/Middleware/MiddlewareAnalysis/src/AnalysisServiceCollectionExtensions.cs +++ b/src/Middleware/MiddlewareAnalysis/src/AnalysisServiceCollectionExtensions.cs @@ -14,7 +14,8 @@ namespace Microsoft.Extensions.DependencyInjection public static class AnalysisServiceCollectionExtensions { /// - /// Adds diagnostic services to the specified . + /// Adds diagnostic services to the specified by logging to + /// a when middleware starts, finishes and throws. /// /// The to add services to. /// The so that additional calls can be chained. diff --git a/src/Middleware/MiddlewareAnalysis/src/AnalysisStartupFilter.cs b/src/Middleware/MiddlewareAnalysis/src/AnalysisStartupFilter.cs index ffce35a667..90baa6ee29 100644 --- a/src/Middleware/MiddlewareAnalysis/src/AnalysisStartupFilter.cs +++ b/src/Middleware/MiddlewareAnalysis/src/AnalysisStartupFilter.cs @@ -7,8 +7,17 @@ using Microsoft.AspNetCore.Hosting; namespace Microsoft.AspNetCore.MiddlewareAnalysis { + /// + /// An that configures the middleware pipeline to log to a + /// when middleware starts, finishes and throws. + /// public class AnalysisStartupFilter : IStartupFilter { + /// + /// Wraps the with and directly adds + /// to the end of the middleware pipeline. + /// + /// public Action Configure(Action next) { return builder => diff --git a/src/Middleware/MiddlewareAnalysis/src/Microsoft.AspNetCore.MiddlewareAnalysis.csproj b/src/Middleware/MiddlewareAnalysis/src/Microsoft.AspNetCore.MiddlewareAnalysis.csproj index 517a69dea4..ba76902d34 100644 --- a/src/Middleware/MiddlewareAnalysis/src/Microsoft.AspNetCore.MiddlewareAnalysis.csproj +++ b/src/Middleware/MiddlewareAnalysis/src/Microsoft.AspNetCore.MiddlewareAnalysis.csproj @@ -1,9 +1,9 @@ - + ASP.NET Core middleware for analyzing middleware in the request pipeline with System.Diagnostics.DiagnosticSource. $(DefaultNetCoreTargetFramework) - $(NoWarn);CS1591 + $(NoWarn.Replace('1591', '')) true aspnetcore;diagnostics diff --git a/src/Middleware/Session/src/DistributedSession.cs b/src/Middleware/Session/src/DistributedSession.cs index 8c8632fc6d..cce1a83e4f 100644 --- a/src/Middleware/Session/src/DistributedSession.cs +++ b/src/Middleware/Session/src/DistributedSession.cs @@ -14,6 +14,9 @@ using Microsoft.Extensions.Logging; namespace Microsoft.AspNetCore.Session { + /// + /// An backed by an . + /// public class DistributedSession : ISession { private const int IdByteCount = 16; @@ -35,6 +38,23 @@ namespace Microsoft.AspNetCore.Session private string _sessionId; private byte[] _sessionIdBytes; + /// + /// Initializes a new instance of . + /// + /// The used to store the session data. + /// A unique key used to lookup the session. + /// How long the session can be inactive (e.g. not accessed) before it will expire. + /// + /// The maximum amount of time and are allowed take. + /// + /// + /// A callback invoked during to verify that modifying the session is currently valid. + /// If the callback returns , throws an . + /// provides a callback that returns if the session was not established + /// prior to sending the response. + /// + /// The . + /// if establishing a new session; if resuming a session. public DistributedSession( IDistributedCache cache, string sessionKey, @@ -74,6 +94,7 @@ namespace Microsoft.AspNetCore.Session _isNewSessionKey = isNewSessionKey; } + /// public bool IsAvailable { get @@ -83,6 +104,7 @@ namespace Microsoft.AspNetCore.Session } } + /// public string Id { get @@ -109,6 +131,7 @@ namespace Microsoft.AspNetCore.Session } } + /// public IEnumerable Keys { get @@ -118,12 +141,14 @@ namespace Microsoft.AspNetCore.Session } } + /// public bool TryGetValue(string key, out byte[] value) { Load(); return _store.TryGetValue(new EncodedKey(key), out value); } + /// public void Set(string key, byte[] value) { if (value == null) @@ -151,12 +176,14 @@ namespace Microsoft.AspNetCore.Session } } + /// public void Remove(string key) { Load(); _isModified |= _store.Remove(new EncodedKey(key)); } + /// public void Clear() { Load(); @@ -196,9 +223,10 @@ namespace Microsoft.AspNetCore.Session } } - // This will throw if called directly and a failure occurs. The user is expected to handle the failures. + /// public async Task LoadAsync(CancellationToken cancellationToken = default) { + // This will throw if called directly and a failure occurs. The user is expected to handle the failures. if (!_loaded) { using (var timeout = new CancellationTokenSource(_ioTimeout)) @@ -232,6 +260,7 @@ namespace Microsoft.AspNetCore.Session } } + /// public async Task CommitAsync(CancellationToken cancellationToken = default) { using (var timeout = new CancellationTokenSource(_ioTimeout)) @@ -419,6 +448,5 @@ namespace Microsoft.AspNetCore.Session } return output; } - } -} \ No newline at end of file +} diff --git a/src/Middleware/Session/src/DistributedSessionStore.cs b/src/Middleware/Session/src/DistributedSessionStore.cs index 49050af588..14a0c40a1c 100644 --- a/src/Middleware/Session/src/DistributedSessionStore.cs +++ b/src/Middleware/Session/src/DistributedSessionStore.cs @@ -8,11 +8,19 @@ using Microsoft.Extensions.Logging; namespace Microsoft.AspNetCore.Session { + /// + /// An backed by an . + /// public class DistributedSessionStore : ISessionStore { private readonly IDistributedCache _cache; private readonly ILoggerFactory _loggerFactory; + /// + /// Initializes a new instance of . + /// + /// The used to store the session data. + /// The . public DistributedSessionStore(IDistributedCache cache, ILoggerFactory loggerFactory) { if (cache == null) @@ -29,6 +37,7 @@ namespace Microsoft.AspNetCore.Session _loggerFactory = loggerFactory; } + /// public ISession Create(string sessionKey, TimeSpan idleTimeout, TimeSpan ioTimeout, Func tryEstablishSession, bool isNewSessionKey) { if (string.IsNullOrEmpty(sessionKey)) diff --git a/src/Middleware/Session/src/ISessionStore.cs b/src/Middleware/Session/src/ISessionStore.cs index 247ba2307f..ef5c3db36e 100644 --- a/src/Middleware/Session/src/ISessionStore.cs +++ b/src/Middleware/Session/src/ISessionStore.cs @@ -6,8 +6,28 @@ using Microsoft.AspNetCore.Http; namespace Microsoft.AspNetCore.Session { + /// + /// Storage for sessions that maintain user data while the user browses a web application. + /// public interface ISessionStore { + /// + /// Create a new or resume an . + /// + /// A unique key used to lookup the session. + /// How long the session can be inactive (e.g. not accessed) before it will expire. + /// + /// The maximum amount of time and + /// are allowed take. + /// + /// + /// A callback invoked during to verify that modifying the session is currently valid. + /// If the callback returns , should throw an . + /// provides a callback that returns if the session was not established + /// prior to sending the response. + /// + /// if establishing a new session; if resuming a session. + /// The that was created or resumed. ISession Create(string sessionKey, TimeSpan idleTimeout, TimeSpan ioTimeout, Func tryEstablishSession, bool isNewSessionKey); } -} \ No newline at end of file +} diff --git a/src/Middleware/Session/src/Microsoft.AspNetCore.Session.csproj b/src/Middleware/Session/src/Microsoft.AspNetCore.Session.csproj index 4763fe2b20..cbad383b5c 100644 --- a/src/Middleware/Session/src/Microsoft.AspNetCore.Session.csproj +++ b/src/Middleware/Session/src/Microsoft.AspNetCore.Session.csproj @@ -4,7 +4,7 @@ ASP.NET Core session state middleware. $(DefaultNetCoreTargetFramework) true - $(NoWarn);CS1591 + $(NoWarn.Replace('1591', '')) true true aspnetcore;session;sessionstate diff --git a/src/Middleware/Session/src/SessionFeature.cs b/src/Middleware/Session/src/SessionFeature.cs index 44a378e614..042c8c416b 100644 --- a/src/Middleware/Session/src/SessionFeature.cs +++ b/src/Middleware/Session/src/SessionFeature.cs @@ -6,8 +6,10 @@ using Microsoft.AspNetCore.Http.Features; namespace Microsoft.AspNetCore.Session { + /// public class SessionFeature : ISessionFeature { + /// public ISession Session { get; set; } } } \ No newline at end of file diff --git a/src/Middleware/SpaServices.Extensions/src/Microsoft.AspNetCore.SpaServices.Extensions.csproj b/src/Middleware/SpaServices.Extensions/src/Microsoft.AspNetCore.SpaServices.Extensions.csproj index f05b05d9ea..4feb9c83c1 100644 --- a/src/Middleware/SpaServices.Extensions/src/Microsoft.AspNetCore.SpaServices.Extensions.csproj +++ b/src/Middleware/SpaServices.Extensions/src/Microsoft.AspNetCore.SpaServices.Extensions.csproj @@ -3,6 +3,7 @@ Helpers for building single-page applications on ASP.NET MVC Core. $(DefaultNetCoreTargetFramework) + $(NoWarn.Replace('1591', ''))