From 75e707bc38beae984dc021c1e1e225e953fdce04 Mon Sep 17 00:00:00 2001 From: Justin Kotalik Date: Tue, 29 Sep 2020 14:12:28 -0700 Subject: [PATCH] API docs for IIS (#26387) --- .../IIS/IIS/src/BadHttpRequestException.cs | 2 ++ .../Core/IISServerAuthenticationHandler.cs | 7 +++++ .../ThrowingWasUpgradedWriteOnlyStream.cs | 11 ++++++++ .../IIS/IIS/src/Core/WriteOnlyStream.cs | 13 +++++++++ src/Servers/IIS/IIS/src/IISServerDefaults.cs | 6 +++++ src/Servers/IIS/IIS/src/IISServerOptions.cs | 3 +++ .../Microsoft.AspNetCore.Server.IIS.csproj | 2 +- .../IIS/src/WebHostBuilderIISExtensions.cs | 7 +++-- .../IIS/IISIntegration/src/IISDefaults.cs | 12 +++++++++ .../IISIntegration/src/IISHostingStartup.cs | 10 +++++++ .../IIS/IISIntegration/src/IISMiddleware.cs | 27 +++++++++++++++++++ .../IIS/IISIntegration/src/IISOptions.cs | 3 +++ ...ft.AspNetCore.Server.IISIntegration.csproj | 4 +-- .../src/WebHostBuilderIISExtensions.cs | 3 +++ ...tCore.Server.IntegrationTesting.IIS.csproj | 1 - 15 files changed, 105 insertions(+), 6 deletions(-) diff --git a/src/Servers/IIS/IIS/src/BadHttpRequestException.cs b/src/Servers/IIS/IIS/src/BadHttpRequestException.cs index 2abefae9e9..68b227a8cb 100644 --- a/src/Servers/IIS/IIS/src/BadHttpRequestException.cs +++ b/src/Servers/IIS/IIS/src/BadHttpRequestException.cs @@ -8,6 +8,7 @@ using Microsoft.AspNetCore.Http; namespace Microsoft.AspNetCore.Server.IIS { + /// [Obsolete("Moved to Microsoft.AspNetCore.Http.BadHttpRequestException")] public sealed class BadHttpRequestException : Microsoft.AspNetCore.Http.BadHttpRequestException { @@ -17,6 +18,7 @@ namespace Microsoft.AspNetCore.Server.IIS Reason = reason; } + /// public new int StatusCode { get => base.StatusCode; } internal RequestRejectionReason Reason { get; } diff --git a/src/Servers/IIS/IIS/src/Core/IISServerAuthenticationHandler.cs b/src/Servers/IIS/IIS/src/Core/IISServerAuthenticationHandler.cs index 7031df34ea..a2de9e1d95 100644 --- a/src/Servers/IIS/IIS/src/Core/IISServerAuthenticationHandler.cs +++ b/src/Servers/IIS/IIS/src/Core/IISServerAuthenticationHandler.cs @@ -8,6 +8,9 @@ using Microsoft.AspNetCore.Http; namespace Microsoft.AspNetCore.Server.IIS.Core { + /// + /// The default authentication handler with IIS In-Process + /// public class IISServerAuthenticationHandler : IAuthenticationHandler { private HttpContext _context; @@ -15,6 +18,7 @@ namespace Microsoft.AspNetCore.Server.IIS.Core internal AuthenticationScheme Scheme { get; private set; } + /// public Task AuthenticateAsync() { var user = _iisHttpContext.WindowsUser; @@ -28,6 +32,7 @@ namespace Microsoft.AspNetCore.Server.IIS.Core } } + /// public Task ChallengeAsync(AuthenticationProperties properties) { // We would normally set the www-authenticate header here, but IIS does that for us. @@ -35,12 +40,14 @@ namespace Microsoft.AspNetCore.Server.IIS.Core return Task.CompletedTask; } + /// public Task ForbidAsync(AuthenticationProperties properties) { _context.Response.StatusCode = 403; return Task.CompletedTask; } + /// public Task InitializeAsync(AuthenticationScheme scheme, HttpContext context) { _iisHttpContext = context.Features.Get(); diff --git a/src/Servers/IIS/IIS/src/Core/ThrowingWasUpgradedWriteOnlyStream.cs b/src/Servers/IIS/IIS/src/Core/ThrowingWasUpgradedWriteOnlyStream.cs index 3990cd9865..23855ff435 100644 --- a/src/Servers/IIS/IIS/src/Core/ThrowingWasUpgradedWriteOnlyStream.cs +++ b/src/Servers/IIS/IIS/src/Core/ThrowingWasUpgradedWriteOnlyStream.cs @@ -8,20 +8,31 @@ using System.Threading.Tasks; namespace Microsoft.AspNetCore.Server.IIS.Core { + /// + /// A which throws on calls to write after the stream was upgraded + /// + /// + /// Users should not need to instantiate this class. + /// public class ThrowingWasUpgradedWriteOnlyStream : WriteOnlyStream { + /// public override void Write(byte[] buffer, int offset, int count) => throw new InvalidOperationException(CoreStrings.ResponseStreamWasUpgraded); + /// public override Task WriteAsync(byte[] buffer, int offset, int count, CancellationToken cancellationToken) => throw new InvalidOperationException(CoreStrings.ResponseStreamWasUpgraded); + /// public override void Flush() => throw new InvalidOperationException(CoreStrings.ResponseStreamWasUpgraded); + /// public override long Seek(long offset, SeekOrigin origin) => throw new NotSupportedException(); + /// public override void SetLength(long value) => throw new NotSupportedException(); } diff --git a/src/Servers/IIS/IIS/src/Core/WriteOnlyStream.cs b/src/Servers/IIS/IIS/src/Core/WriteOnlyStream.cs index 9ccf9c9cd1..db659f6a0f 100644 --- a/src/Servers/IIS/IIS/src/Core/WriteOnlyStream.cs +++ b/src/Servers/IIS/IIS/src/Core/WriteOnlyStream.cs @@ -8,43 +8,56 @@ using System.Threading.Tasks; namespace Microsoft.AspNetCore.Server.IIS.Core { + /// + /// A which only allows for writes. + /// public abstract class WriteOnlyStream : Stream { + /// public override bool CanRead => false; + /// public override bool CanWrite => true; + /// public override int ReadTimeout { get => throw new NotSupportedException(); set => throw new NotSupportedException(); } + /// public override bool CanSeek => false; + /// public override long Length => throw new NotSupportedException(); + /// public override long Position { get => throw new NotSupportedException(); set => throw new NotSupportedException(); } + /// public override int Read(byte[] buffer, int offset, int count) { throw new NotSupportedException(); } + /// public override Task ReadAsync(byte[] buffer, int offset, int count, CancellationToken cancellationToken) { throw new NotSupportedException(); } + /// public override long Seek(long offset, SeekOrigin origin) { throw new NotSupportedException(); } + /// public override void SetLength(long value) { throw new NotSupportedException(); diff --git a/src/Servers/IIS/IIS/src/IISServerDefaults.cs b/src/Servers/IIS/IIS/src/IISServerDefaults.cs index 5ac1296597..7b47134953 100644 --- a/src/Servers/IIS/IIS/src/IISServerDefaults.cs +++ b/src/Servers/IIS/IIS/src/IISServerDefaults.cs @@ -3,8 +3,14 @@ namespace Microsoft.AspNetCore.Server.IIS { + /// + /// String constants used to configure IIS In-Process. + /// public class IISServerDefaults { + /// + /// Default authentication scheme, which is "Windows". + /// public const string AuthenticationScheme = "Windows"; } } diff --git a/src/Servers/IIS/IIS/src/IISServerOptions.cs b/src/Servers/IIS/IIS/src/IISServerOptions.cs index 430f1b3b77..5f20167758 100644 --- a/src/Servers/IIS/IIS/src/IISServerOptions.cs +++ b/src/Servers/IIS/IIS/src/IISServerOptions.cs @@ -8,6 +8,9 @@ using Microsoft.AspNetCore.Server.IIS; namespace Microsoft.AspNetCore.Builder { + /// + /// Provides configuration for IIS In-Process. + /// public class IISServerOptions { /// diff --git a/src/Servers/IIS/IIS/src/Microsoft.AspNetCore.Server.IIS.csproj b/src/Servers/IIS/IIS/src/Microsoft.AspNetCore.Server.IIS.csproj index 5727a00650..d01355b74c 100644 --- a/src/Servers/IIS/IIS/src/Microsoft.AspNetCore.Server.IIS.csproj +++ b/src/Servers/IIS/IIS/src/Microsoft.AspNetCore.Server.IIS.csproj @@ -5,7 +5,6 @@ true Microsoft.AspNetCore.Server.IIS Provides support for hosting ASP.NET Core in IIS using the AspNetCoreModule. - $(NoWarn);CS1591 true aspnetcore;iis true @@ -13,6 +12,7 @@ false + $(NoWarn.Replace('1591', '')) $(NoWarn);CA1416 diff --git a/src/Servers/IIS/IIS/src/WebHostBuilderIISExtensions.cs b/src/Servers/IIS/IIS/src/WebHostBuilderIISExtensions.cs index 0a4dd7e4d7..d4d6fa9c40 100644 --- a/src/Servers/IIS/IIS/src/WebHostBuilderIISExtensions.cs +++ b/src/Servers/IIS/IIS/src/WebHostBuilderIISExtensions.cs @@ -12,14 +12,17 @@ using Microsoft.AspNetCore.Server.IIS.Core; namespace Microsoft.AspNetCore.Hosting { + /// + /// Extension methods for the IIS In-Process. + /// public static class WebHostBuilderIISExtensions { /// /// Configures the port and base path the server should listen on when running behind AspNetCoreModule. /// The app will also be configured to capture startup errors. /// - /// - /// + /// The to configure. + /// The . public static IWebHostBuilder UseIIS(this IWebHostBuilder hostBuilder) { if (hostBuilder == null) diff --git a/src/Servers/IIS/IISIntegration/src/IISDefaults.cs b/src/Servers/IIS/IISIntegration/src/IISDefaults.cs index f34da18d1e..ba1a1a1f85 100644 --- a/src/Servers/IIS/IISIntegration/src/IISDefaults.cs +++ b/src/Servers/IIS/IISIntegration/src/IISDefaults.cs @@ -3,10 +3,22 @@ namespace Microsoft.AspNetCore.Server.IISIntegration { + /// + /// String constants used to configure IIS Out-Of-Process. + /// public class IISDefaults { + /// + /// Default authentication scheme, which is "Windows". + /// public const string AuthenticationScheme = "Windows"; + /// + /// Default negotiate string, which is "Negotiate". + /// public const string Negotiate = "Negotiate"; + /// + /// Default NTLM string, which is "NTLM". + /// public const string Ntlm = "NTLM"; } } diff --git a/src/Servers/IIS/IISIntegration/src/IISHostingStartup.cs b/src/Servers/IIS/IISIntegration/src/IISHostingStartup.cs index d701dc3181..af120f50cb 100644 --- a/src/Servers/IIS/IISIntegration/src/IISHostingStartup.cs +++ b/src/Servers/IIS/IISIntegration/src/IISHostingStartup.cs @@ -7,8 +7,18 @@ using Microsoft.AspNetCore.Hosting; namespace Microsoft.AspNetCore.Server.IISIntegration { + /// + /// The to add IISIntegration to apps. + /// + /// + /// This API isn't meant to be used by user code. + /// public class IISHostingStartup : IHostingStartup { + /// + /// Adds IISIntegration into the middleware pipeline. + /// + /// The . public void Configure(IWebHostBuilder builder) { builder.UseIISIntegration(); diff --git a/src/Servers/IIS/IISIntegration/src/IISMiddleware.cs b/src/Servers/IIS/IISIntegration/src/IISMiddleware.cs index f0596d40cc..513e4920fc 100644 --- a/src/Servers/IIS/IISIntegration/src/IISMiddleware.cs +++ b/src/Servers/IIS/IISIntegration/src/IISMiddleware.cs @@ -17,6 +17,9 @@ using Microsoft.Extensions.Primitives; namespace Microsoft.AspNetCore.Server.IISIntegration { + /// + /// The middleware that enables IIS Out-Of-Process to work. + /// public class IISMiddleware { private const string MSAspNetCoreClientCert = "MS-ASPNETCORE-CLIENTCERT"; @@ -34,6 +37,15 @@ namespace Microsoft.AspNetCore.Server.IISIntegration private readonly IHostApplicationLifetime _applicationLifetime; private readonly bool _isWebsocketsSupported; + /// + /// The middleware that enables IIS Out-Of-Process to work. + /// + /// The next middleware in the pipeline. + /// The . + /// The configuration for this middleware. + /// A token used to coordinate with the ASP.NET Core Module. + /// The . + /// The . // Can't break public API, so creating a second constructor to propagate the isWebsocketsSupported flag. public IISMiddleware(RequestDelegate next, ILoggerFactory loggerFactory, @@ -45,6 +57,16 @@ namespace Microsoft.AspNetCore.Server.IISIntegration { } + /// + /// The middleware that enables IIS Out-Of-Process to work. + /// + /// The next middleware in the pipeline. + /// The . + /// The configuration for this middleware. + /// A token used to coordinate with the ASP.NET Core Module. + /// Whether websockets are supported by IIS. + /// The . + /// The . public IISMiddleware(RequestDelegate next, ILoggerFactory loggerFactory, IOptions options, @@ -88,6 +110,11 @@ namespace Microsoft.AspNetCore.Server.IISIntegration _isWebsocketsSupported = isWebsocketsSupported; } + /// + /// Invoke the middleware. + /// + /// The . + /// A that represents the asynchronous operation. public async Task Invoke(HttpContext httpContext) { if (!string.Equals(_pairingToken, httpContext.Request.Headers[MSAspNetCoreToken], StringComparison.Ordinal)) diff --git a/src/Servers/IIS/IISIntegration/src/IISOptions.cs b/src/Servers/IIS/IISIntegration/src/IISOptions.cs index efd9eec1f3..8a7d83fb48 100644 --- a/src/Servers/IIS/IISIntegration/src/IISOptions.cs +++ b/src/Servers/IIS/IISIntegration/src/IISOptions.cs @@ -3,6 +3,9 @@ namespace Microsoft.AspNetCore.Builder { + /// + /// Options to configure IIS Out-Of-Process. + /// public class IISOptions { /// diff --git a/src/Servers/IIS/IISIntegration/src/Microsoft.AspNetCore.Server.IISIntegration.csproj b/src/Servers/IIS/IISIntegration/src/Microsoft.AspNetCore.Server.IISIntegration.csproj index 0c1e8fb171..842d4ac19d 100644 --- a/src/Servers/IIS/IISIntegration/src/Microsoft.AspNetCore.Server.IISIntegration.csproj +++ b/src/Servers/IIS/IISIntegration/src/Microsoft.AspNetCore.Server.IISIntegration.csproj @@ -1,16 +1,16 @@ - + ASP.NET Core components for working with the IIS AspNetCoreModule. $(DefaultNetCoreTargetFramework) true - $(NoWarn);CS1591 true aspnetcore;iis true false + $(NoWarn.Replace('1591', '')) $(NoWarn);CA1416 diff --git a/src/Servers/IIS/IISIntegration/src/WebHostBuilderIISExtensions.cs b/src/Servers/IIS/IISIntegration/src/WebHostBuilderIISExtensions.cs index a9234ee4b8..acb9ea3536 100644 --- a/src/Servers/IIS/IISIntegration/src/WebHostBuilderIISExtensions.cs +++ b/src/Servers/IIS/IISIntegration/src/WebHostBuilderIISExtensions.cs @@ -11,6 +11,9 @@ using Microsoft.Extensions.DependencyInjection; namespace Microsoft.AspNetCore.Hosting { + /// + /// Extension methods for the IIS Out-Of-Process. + /// public static class WebHostBuilderIISExtensions { // These are defined as ASPNETCORE_ environment variables by IIS's AspNetCoreModule. diff --git a/src/Servers/IIS/IntegrationTesting.IIS/src/Microsoft.AspNetCore.Server.IntegrationTesting.IIS.csproj b/src/Servers/IIS/IntegrationTesting.IIS/src/Microsoft.AspNetCore.Server.IntegrationTesting.IIS.csproj index 148e9db98e..d178fce4d6 100644 --- a/src/Servers/IIS/IntegrationTesting.IIS/src/Microsoft.AspNetCore.Server.IntegrationTesting.IIS.csproj +++ b/src/Servers/IIS/IntegrationTesting.IIS/src/Microsoft.AspNetCore.Server.IntegrationTesting.IIS.csproj @@ -4,7 +4,6 @@ $(DefaultNetCoreTargetFramework) Microsoft.AspNetCore.Server.IntegrationTesting.IIS Provides support for integration testing using IIS based servers. - $(NoWarn);CS1591 true aspnetcore;iis True