From 8118a25e7fcb94d5e98577445fae9b4ff8e83bb5 Mon Sep 17 00:00:00 2001 From: William Godbe Date: Wed, 7 Oct 2020 22:28:49 -0700 Subject: [PATCH] Add API ref docs for HTTPSys (#26649) * Add API ref docs for HTTPSys * Spacing * Feedback --- .../HttpSys/src/AuthenticationSchemes.cs | 26 ++++++++++++- src/Servers/HttpSys/src/DelegationRule.cs | 1 + src/Servers/HttpSys/src/HttpSysDefaults.cs | 3 ++ src/Servers/HttpSys/src/HttpSysException.cs | 4 ++ src/Servers/HttpSys/src/HttpSysOptions.cs | 6 +++ .../src/IHttpSysRequestDelegationFeature.cs | 4 ++ .../HttpSys/src/IServerDelegationFeature.cs | 5 +++ ...Microsoft.AspNetCore.Server.HttpSys.csproj | 1 + src/Servers/HttpSys/src/UrlPrefix.cs | 39 +++++++++++++++++++ .../HttpSys/src/UrlPrefixCollection.cs | 20 ++++++++++ 10 files changed, 108 insertions(+), 1 deletion(-) diff --git a/src/Servers/HttpSys/src/AuthenticationSchemes.cs b/src/Servers/HttpSys/src/AuthenticationSchemes.cs index 3d82bdadc0..6596abb801 100644 --- a/src/Servers/HttpSys/src/AuthenticationSchemes.cs +++ b/src/Servers/HttpSys/src/AuthenticationSchemes.cs @@ -5,15 +5,39 @@ using System; namespace Microsoft.AspNetCore.Server.HttpSys { - // REVIEW: this appears to be very similar to System.Net.AuthenticationSchemes + /// + /// Specifies protocols for authentication. + /// [Flags] public enum AuthenticationSchemes { + /// + /// No authentication is enabled. This should only be used when HttpSysOptions.Authentication.AllowAnonymous is enabled (see ). + /// None = 0x0, + + /// + /// Specifies basic authentication. + /// Basic = 0x1, + + // Digest = 0x2, // TODO: Verify this is no longer supported by Http.Sys + + /// + /// Specifies NTLM authentication. + /// NTLM = 0x4, + + /// + /// Negotiates with the client to determine the authentication scheme. If both client and server support Kerberos, it is used; + /// otherwise, NTLM is used. + /// Negotiate = 0x8, + + /// + /// Specifies Kerberos authentication. + /// Kerberos = 0x10 } } diff --git a/src/Servers/HttpSys/src/DelegationRule.cs b/src/Servers/HttpSys/src/DelegationRule.cs index 593b88456a..e33997338c 100644 --- a/src/Servers/HttpSys/src/DelegationRule.cs +++ b/src/Servers/HttpSys/src/DelegationRule.cs @@ -31,6 +31,7 @@ namespace Microsoft.AspNetCore.Server.HttpSys Queue = new RequestQueue(queueName, UrlPrefix, _logger, receiver: true); } + /// public void Dispose() { Queue.UrlGroup?.Dispose(); diff --git a/src/Servers/HttpSys/src/HttpSysDefaults.cs b/src/Servers/HttpSys/src/HttpSysDefaults.cs index fde04af7ba..401cdeea07 100644 --- a/src/Servers/HttpSys/src/HttpSysDefaults.cs +++ b/src/Servers/HttpSys/src/HttpSysDefaults.cs @@ -3,6 +3,9 @@ namespace Microsoft.AspNetCore.Server.HttpSys { + /// + /// Constants for HttpSys. + /// public static class HttpSysDefaults { /// diff --git a/src/Servers/HttpSys/src/HttpSysException.cs b/src/Servers/HttpSys/src/HttpSysException.cs index 9e65fa3916..d3e1f27482 100644 --- a/src/Servers/HttpSys/src/HttpSysException.cs +++ b/src/Servers/HttpSys/src/HttpSysException.cs @@ -8,6 +8,9 @@ using System.Runtime.InteropServices; namespace Microsoft.AspNetCore.Server.HttpSys { + /// + /// Exception thrown by HttpSys when an error occurs + /// [SuppressMessage("Microsoft.Usage", "CA2237:MarkISerializableTypesWithSerializable")] public class HttpSysException : Win32Exception { @@ -28,6 +31,7 @@ namespace Microsoft.AspNetCore.Server.HttpSys // the base class returns the HResult with this property // we need the Win32 Error Code, hence the override. + /// public override int ErrorCode { get diff --git a/src/Servers/HttpSys/src/HttpSysOptions.cs b/src/Servers/HttpSys/src/HttpSysOptions.cs index db95797980..bd4f24b830 100644 --- a/src/Servers/HttpSys/src/HttpSysOptions.cs +++ b/src/Servers/HttpSys/src/HttpSysOptions.cs @@ -7,6 +7,9 @@ using Microsoft.AspNetCore.Http.Features; namespace Microsoft.AspNetCore.Server.HttpSys { + /// + /// Contains the options used by HttpSys. + /// public class HttpSysOptions { private const uint MaximumRequestQueueNameLength = 260; @@ -26,6 +29,9 @@ namespace Microsoft.AspNetCore.Server.HttpSys private long? _maxRequestBodySize = DefaultMaxRequestBodySize; private string _requestQueueName; + /// + /// Initializes a new . + /// public HttpSysOptions() { } diff --git a/src/Servers/HttpSys/src/IHttpSysRequestDelegationFeature.cs b/src/Servers/HttpSys/src/IHttpSysRequestDelegationFeature.cs index a581cc8683..5aaf1be689 100644 --- a/src/Servers/HttpSys/src/IHttpSysRequestDelegationFeature.cs +++ b/src/Servers/HttpSys/src/IHttpSysRequestDelegationFeature.cs @@ -3,6 +3,9 @@ namespace Microsoft.AspNetCore.Server.HttpSys { + /// + /// Interface for delegating requests to other Http.Sys request queues. + /// public interface IHttpSysRequestDelegationFeature { /// @@ -15,6 +18,7 @@ namespace Microsoft.AspNetCore.Server.HttpSys /// must not be read nor the response started before this is invoked. Check /// before invoking. /// + /// The rule maintaining the handle to the destination queue. void DelegateRequest(DelegationRule destination); } } diff --git a/src/Servers/HttpSys/src/IServerDelegationFeature.cs b/src/Servers/HttpSys/src/IServerDelegationFeature.cs index 7353f9f053..d901a847b1 100644 --- a/src/Servers/HttpSys/src/IServerDelegationFeature.cs +++ b/src/Servers/HttpSys/src/IServerDelegationFeature.cs @@ -3,11 +3,16 @@ namespace Microsoft.AspNetCore.Server.HttpSys { + /// + /// This exposes the creation of delegation rules on request queues owned by the server. + /// public interface IServerDelegationFeature { /// /// Create a delegation rule on request queue owned by the server. /// + /// The name of the Http.Sys request queue. + /// The URL of the Http.Sys Url Prefix. /// /// Creates a that can used to delegate individual requests. /// diff --git a/src/Servers/HttpSys/src/Microsoft.AspNetCore.Server.HttpSys.csproj b/src/Servers/HttpSys/src/Microsoft.AspNetCore.Server.HttpSys.csproj index 0ab19cbe78..7fd71203a9 100644 --- a/src/Servers/HttpSys/src/Microsoft.AspNetCore.Server.HttpSys.csproj +++ b/src/Servers/HttpSys/src/Microsoft.AspNetCore.Server.HttpSys.csproj @@ -12,6 +12,7 @@ $(NoWarn);CA1416 + $(NoWarn.Replace('1591', '')) diff --git a/src/Servers/HttpSys/src/UrlPrefix.cs b/src/Servers/HttpSys/src/UrlPrefix.cs index c013b0e491..9bca1c52a5 100644 --- a/src/Servers/HttpSys/src/UrlPrefix.cs +++ b/src/Servers/HttpSys/src/UrlPrefix.cs @@ -7,6 +7,9 @@ using Microsoft.AspNetCore.HttpSys.Internal; namespace Microsoft.AspNetCore.Server.HttpSys { + /// + /// A set of URL parameters used to listen for incoming requests. + /// public class UrlPrefix { private UrlPrefix(bool isHttps, string scheme, string host, string port, int portValue, string path) @@ -94,6 +97,10 @@ namespace Microsoft.AspNetCore.Server.HttpSys return new UrlPrefix(isHttps, scheme, host, port, portValue.Value, path); } + /// + /// http://msdn.microsoft.com/en-us/library/windows/desktop/aa364698(v=vs.85).aspx + /// + /// The string that the will be created from. public static UrlPrefix Create(string prefix) { string scheme = null; @@ -146,26 +153,58 @@ namespace Microsoft.AspNetCore.Server.HttpSys return Create(scheme, host, port, path); } + /// + /// Gets a value that determines if the prefix's scheme is HTTPS. + /// public bool IsHttps { get; } + + /// + /// Gets the scheme used by the prefix. + /// public string Scheme { get; } + + /// + /// Gets the host domain name used by the prefix. + /// public string Host { get; } + + /// + /// Gets a string representation of the port used by the prefix. + /// public string Port { get; } + internal string HostAndPort { get; } + + /// + /// Gets an integer representation of the port used by the prefix. + /// public int PortValue { get; } + + /// + /// Gets the path component of the prefix. + /// public string Path { get; } + internal string PathWithoutTrailingSlash { get; } + + /// + /// Gets a string representation of the prefix + /// public string FullPrefix { get; } + /// public override bool Equals(object obj) { return string.Equals(FullPrefix, Convert.ToString(obj), StringComparison.OrdinalIgnoreCase); } + /// public override int GetHashCode() { return StringComparer.OrdinalIgnoreCase.GetHashCode(FullPrefix); } + /// public override string ToString() { return FullPrefix; diff --git a/src/Servers/HttpSys/src/UrlPrefixCollection.cs b/src/Servers/HttpSys/src/UrlPrefixCollection.cs index ac92c6591d..e77d2eb32a 100644 --- a/src/Servers/HttpSys/src/UrlPrefixCollection.cs +++ b/src/Servers/HttpSys/src/UrlPrefixCollection.cs @@ -30,6 +30,7 @@ namespace Microsoft.AspNetCore.Server.HttpSys { } + /// public int Count { get @@ -41,16 +42,27 @@ namespace Microsoft.AspNetCore.Server.HttpSys } } + /// + /// Gets a value that determines if this collection is readOnly. + /// public bool IsReadOnly { get { return false; } } + /// + /// Creates a from the given string, and adds it to this collection. + /// + /// The string representing the to add to this collection. public void Add(string prefix) { Add(UrlPrefix.Create(prefix)); } + /// + /// Adds a to this collection. + /// + /// The prefix to add to this collection. public void Add(UrlPrefix item) { lock (_prefixes) @@ -98,6 +110,7 @@ namespace Microsoft.AspNetCore.Server.HttpSys return found; } + /// public void Clear() { lock (_prefixes) @@ -110,6 +123,7 @@ namespace Microsoft.AspNetCore.Server.HttpSys } } + /// public bool Contains(UrlPrefix item) { lock (_prefixes) @@ -118,6 +132,7 @@ namespace Microsoft.AspNetCore.Server.HttpSys } } + /// public void CopyTo(UrlPrefix[] array, int arrayIndex) { lock (_prefixes) @@ -126,11 +141,13 @@ namespace Microsoft.AspNetCore.Server.HttpSys } } + /// public bool Remove(string prefix) { return Remove(UrlPrefix.Create(prefix)); } + /// public bool Remove(UrlPrefix item) { lock (_prefixes) @@ -156,6 +173,9 @@ namespace Microsoft.AspNetCore.Server.HttpSys } } + /// + /// Returns an enumerator that iterates through this collection. + /// public IEnumerator GetEnumerator() { lock (_prefixes)