API docs for IIS (#26387)

src/Servers/IIS/IIS/src/BadHttpRequestException.cs

@@ -8,6 +8,7 @@ using Microsoft.AspNetCore.Http;
 
 namespace Microsoft.AspNetCore.Server.IIS
 {
+    ///<inheritdoc/>
     [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;
         }
 
+        ///<inheritdoc/>
         public new int StatusCode { get => base.StatusCode; }
 
         internal RequestRejectionReason Reason { get; }

src/Servers/IIS/IIS/src/Core/IISServerAuthenticationHandler.cs

@@ -8,6 +8,9 @@ using Microsoft.AspNetCore.Http;
 
 namespace Microsoft.AspNetCore.Server.IIS.Core
 {
+    /// <summary>
+    /// The default authentication handler with IIS In-Process
+    /// </summary>
     public class IISServerAuthenticationHandler : IAuthenticationHandler
     {
         private HttpContext _context;
@@ -15,6 +18,7 @@ namespace Microsoft.AspNetCore.Server.IIS.Core
 
         internal AuthenticationScheme Scheme { get; private set; }
 
+        ///<inheritdoc/>
         public Task<AuthenticateResult> AuthenticateAsync()
         {
             var user = _iisHttpContext.WindowsUser;
@@ -28,6 +32,7 @@ namespace Microsoft.AspNetCore.Server.IIS.Core
             }
         }
 
+        ///<inheritdoc/>
         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;
         }
 
+        ///<inheritdoc/>
         public Task ForbidAsync(AuthenticationProperties properties)
         {
             _context.Response.StatusCode = 403;
             return Task.CompletedTask;
         }
 
+        ///<inheritdoc/>
         public Task InitializeAsync(AuthenticationScheme scheme, HttpContext context)
         {
             _iisHttpContext = context.Features.Get<IISHttpContext>();

src/Servers/IIS/IIS/src/Core/ThrowingWasUpgradedWriteOnlyStream.cs

@@ -8,20 +8,31 @@ using System.Threading.Tasks;
 
 namespace Microsoft.AspNetCore.Server.IIS.Core
 {
+    /// <summary>
+    /// A <see cref="Stream"/> which throws on calls to write after the stream was upgraded
+    /// </summary>
+    /// <remarks>
+    /// Users should not need to instantiate this class.
+    /// </remarks>
     public class ThrowingWasUpgradedWriteOnlyStream : WriteOnlyStream
     {
+        ///<inheritdoc/>
         public override void Write(byte[] buffer, int offset, int count)
             => throw new InvalidOperationException(CoreStrings.ResponseStreamWasUpgraded);
 
+        ///<inheritdoc/>
         public override Task WriteAsync(byte[] buffer, int offset, int count, CancellationToken cancellationToken)
             => throw new InvalidOperationException(CoreStrings.ResponseStreamWasUpgraded);
 
+        ///<inheritdoc/>
         public override void Flush()
             => throw new InvalidOperationException(CoreStrings.ResponseStreamWasUpgraded);
 
+        ///<inheritdoc/>
         public override long Seek(long offset, SeekOrigin origin)
             => throw new NotSupportedException();
 
+        ///<inheritdoc/>
         public override void SetLength(long value)
             => throw new NotSupportedException();
     }

src/Servers/IIS/IIS/src/Core/WriteOnlyStream.cs

@@ -8,43 +8,56 @@ using System.Threading.Tasks;
 
 namespace Microsoft.AspNetCore.Server.IIS.Core
 {
+    /// <summary>
+    /// A <see cref="Stream"/> which only allows for writes.
+    /// </summary>
     public abstract class WriteOnlyStream : Stream
     {
+        ///<inheritdoc/>
         public override bool CanRead => false;
 
+        ///<inheritdoc/>
         public override bool CanWrite => true;
 
+        ///<inheritdoc/>
         public override int ReadTimeout
         {
             get => throw new NotSupportedException();
             set => throw new NotSupportedException();
         }
 
+        ///<inheritdoc/>
         public override bool CanSeek => false;
 
+        ///<inheritdoc/>
         public override long Length => throw new NotSupportedException();
 
+        ///<inheritdoc/>
         public override long Position
         {
             get => throw new NotSupportedException();
             set => throw new NotSupportedException();
         }
 
+        ///<inheritdoc/>
         public override int Read(byte[] buffer, int offset, int count)
         {
             throw new NotSupportedException();
         }
 
+        ///<inheritdoc/>
         public override Task<int> ReadAsync(byte[] buffer, int offset, int count, CancellationToken cancellationToken)
         {
             throw new NotSupportedException();
         }
 
+        ///<inheritdoc/>
         public override long Seek(long offset, SeekOrigin origin)
         {
             throw new NotSupportedException();
         }
 
+        ///<inheritdoc/>
         public override void SetLength(long value)
         {
             throw new NotSupportedException();

src/Servers/IIS/IIS/src/IISServerDefaults.cs

@@ -3,8 +3,14 @@
 
 namespace Microsoft.AspNetCore.Server.IIS
 {
+    /// <summary>
+    /// String constants used to configure IIS In-Process.
+    /// </summary>
     public class IISServerDefaults
     {
+        /// <summary>
+        /// Default authentication scheme, which is "Windows".
+        /// </summary>
         public const string AuthenticationScheme = "Windows";
     }
 }

src/Servers/IIS/IIS/src/IISServerOptions.cs

@@ -8,6 +8,9 @@ using Microsoft.AspNetCore.Server.IIS;
 
 namespace Microsoft.AspNetCore.Builder
 {
+    /// <summary>
+    /// Provides configuration for IIS In-Process.
+    /// </summary>
     public class IISServerOptions
     {
         /// <summary>

src/Servers/IIS/IIS/src/Microsoft.AspNetCore.Server.IIS.csproj

@@ -5,7 +5,6 @@
     <IsAspNetCoreApp>true</IsAspNetCoreApp>
     <PackageId>Microsoft.AspNetCore.Server.IIS</PackageId>
     <Description>Provides support for hosting ASP.NET Core in IIS using the AspNetCoreModule.</Description>
-    <NoWarn>$(NoWarn);CS1591</NoWarn>
     <GenerateDocumentationFile>true</GenerateDocumentationFile>
     <PackageTags>aspnetcore;iis</PackageTags>
     <AllowUnsafeBlocks>true</AllowUnsafeBlocks>
@@ -13,6 +12,7 @@
     <IsPackable>false</IsPackable>
 
     <!-- Ignore platform compatibility warnings for this project. We know this only works on windows.-->
+    <NoWarn>$(NoWarn.Replace('1591', ''))</NoWarn>
     <NoWarn>$(NoWarn);CA1416</NoWarn>
   </PropertyGroup>
 

src/Servers/IIS/IIS/src/WebHostBuilderIISExtensions.cs

@@ -12,14 +12,17 @@ using Microsoft.AspNetCore.Server.IIS.Core;
 
 namespace Microsoft.AspNetCore.Hosting
 {
+    /// <summary>
+    /// Extension methods for the IIS In-Process.
+    /// </summary>
     public static class WebHostBuilderIISExtensions
     {
         /// <summary>
         /// 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.
         /// </summary>
-        /// <param name="hostBuilder"></param>
+        /// <param name="hostBuilder">The <see cref="IWebHostBuilder"/> to configure.</param>
-        /// <returns></returns>
+        /// <returns>The <see cref="IWebHostBuilder"/>.</returns>
         public static IWebHostBuilder UseIIS(this IWebHostBuilder hostBuilder)
         {
             if (hostBuilder == null)

src/Servers/IIS/IISIntegration/src/IISDefaults.cs

@@ -3,10 +3,22 @@
 
 namespace Microsoft.AspNetCore.Server.IISIntegration
 {
+    /// <summary>
+    /// String constants used to configure IIS Out-Of-Process.
+    /// </summary>
     public class IISDefaults
     {
+        /// <summary>
+        /// Default authentication scheme, which is "Windows".
+        /// </summary>
         public const string AuthenticationScheme = "Windows";
+        /// <summary>
+        /// Default negotiate string, which is "Negotiate".
+        /// </summary>
         public const string Negotiate = "Negotiate";
+        /// <summary>
+        /// Default NTLM string, which is "NTLM".
+        /// </summary>
         public const string Ntlm = "NTLM";
     }
 }

src/Servers/IIS/IISIntegration/src/IISHostingStartup.cs

@@ -7,8 +7,18 @@ using Microsoft.AspNetCore.Hosting;
 
 namespace Microsoft.AspNetCore.Server.IISIntegration
 {
+    /// <summary>
+    /// The <see cref="IHostingStartup"/> to add IISIntegration to apps.
+    /// </summary>
+    /// <remarks>
+    /// This API isn't meant to be used by user code.
+    /// </remarks>
     public class IISHostingStartup : IHostingStartup
     {
+        /// <summary>
+        /// Adds IISIntegration into the middleware pipeline.
+        /// </summary>
+        /// <param name="builder">The <see cref="IWebHostBuilder"/>.</param>
         public void Configure(IWebHostBuilder builder)
         {
             builder.UseIISIntegration();

src/Servers/IIS/IISIntegration/src/IISMiddleware.cs

@@ -17,6 +17,9 @@ using Microsoft.Extensions.Primitives;
 
 namespace Microsoft.AspNetCore.Server.IISIntegration
 {
+    /// <summary>
+    /// The middleware that enables IIS Out-Of-Process to work.
+    /// </summary>
     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;
 
+        /// <summary>
+        /// The middleware that enables IIS Out-Of-Process to work.
+        /// </summary>
+        /// <param name="next">The next middleware in the pipeline.</param>
+        /// <param name="loggerFactory">The <see cref="ILoggerFactory" />.</param>
+        /// <param name="options">The configuration for this middleware.</param>
+        /// <param name="pairingToken">A token used to coordinate with the ASP.NET Core Module.</param>
+        /// <param name="authentication">The <see cref="IAuthenticationSchemeProvider"/>.</param>
+        /// <param name="applicationLifetime">The <see cref="IHostApplicationLifetime"/>.</param>
         // 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
         {
         }
 
+        /// <summary>
+        /// The middleware that enables IIS Out-Of-Process to work.
+        /// </summary>
+        /// <param name="next">The next middleware in the pipeline.</param>
+        /// <param name="loggerFactory">The <see cref="ILoggerFactory" />.</param>
+        /// <param name="options">The configuration for this middleware.</param>
+        /// <param name="pairingToken">A token used to coordinate with the ASP.NET Core Module.</param>
+        /// <param name="isWebsocketsSupported">Whether websockets are supported by IIS.</param>
+        /// <param name="authentication">The <see cref="IAuthenticationSchemeProvider"/>.</param>
+        /// <param name="applicationLifetime">The <see cref="IHostApplicationLifetime"/>.</param>
         public IISMiddleware(RequestDelegate next,
             ILoggerFactory loggerFactory,
             IOptions<IISOptions> options,
@@ -88,6 +110,11 @@ namespace Microsoft.AspNetCore.Server.IISIntegration
             _isWebsocketsSupported = isWebsocketsSupported;
         }
 
+        /// <summary>
+        /// Invoke the middleware.
+        /// </summary>
+        /// <param name="httpContext">The <see cref="HttpContext"/>.</param>
+        /// <returns>A <see cref="Task"/> that represents the asynchronous operation.</returns>
         public async Task Invoke(HttpContext httpContext)
         {
             if (!string.Equals(_pairingToken, httpContext.Request.Headers[MSAspNetCoreToken], StringComparison.Ordinal))

src/Servers/IIS/IISIntegration/src/IISOptions.cs

@@ -3,6 +3,9 @@
 
 namespace Microsoft.AspNetCore.Builder
 {
+    /// <summary>
+    /// Options to configure IIS Out-Of-Process.
+    /// </summary>
     public class IISOptions
     {
         /// <summary>

src/Servers/IIS/IISIntegration/src/Microsoft.AspNetCore.Server.IISIntegration.csproj

@@ -1,16 +1,16 @@
-<Project Sdk="Microsoft.NET.Sdk">
+<Project Sdk="Microsoft.NET.Sdk">
 
   <PropertyGroup>
     <Description>ASP.NET Core components for working with the IIS AspNetCoreModule.</Description>
     <TargetFramework>$(DefaultNetCoreTargetFramework)</TargetFramework>
     <IsAspNetCoreApp>true</IsAspNetCoreApp>
-    <NoWarn>$(NoWarn);CS1591</NoWarn>
     <GenerateDocumentationFile>true</GenerateDocumentationFile>
     <PackageTags>aspnetcore;iis</PackageTags>
     <AllowUnsafeBlocks>true</AllowUnsafeBlocks>
     <IsPackable>false</IsPackable>
 
     <!-- Ignore platform compatibility warnings for this project. We know this only works on windows.-->
+    <NoWarn>$(NoWarn.Replace('1591', ''))</NoWarn>
     <NoWarn>$(NoWarn);CA1416</NoWarn>
   </PropertyGroup>
 

src/Servers/IIS/IISIntegration/src/WebHostBuilderIISExtensions.cs

@@ -11,6 +11,9 @@ using Microsoft.Extensions.DependencyInjection;
 
 namespace Microsoft.AspNetCore.Hosting
 {
+    /// <summary>
+    /// Extension methods for the IIS Out-Of-Process.
+    /// </summary>
     public static class WebHostBuilderIISExtensions
     {
         // These are defined as ASPNETCORE_ environment variables by IIS's AspNetCoreModule.

src/Servers/IIS/IntegrationTesting.IIS/src/Microsoft.AspNetCore.Server.IntegrationTesting.IIS.csproj

@@ -4,7 +4,6 @@
     <TargetFramework>$(DefaultNetCoreTargetFramework)</TargetFramework>
     <PackageId>Microsoft.AspNetCore.Server.IntegrationTesting.IIS</PackageId>
     <Description>Provides support for integration testing using IIS based servers.</Description>
-    <NoWarn>$(NoWarn);CS1591</NoWarn>
     <GenerateDocumentationFile>true</GenerateDocumentationFile>
     <PackageTags>aspnetcore;iis</PackageTags>
     <DisableFastUpToDateCheck>True</DisableFastUpToDateCheck>