diff --git a/src/DataProtection/DataProtection/src/AuthenticatedEncryption/AuthenticatedEncryptorFactory.cs b/src/DataProtection/DataProtection/src/AuthenticatedEncryption/AuthenticatedEncryptorFactory.cs index 634f48cf66f3..151074ed205e 100644 --- a/src/DataProtection/DataProtection/src/AuthenticatedEncryption/AuthenticatedEncryptorFactory.cs +++ b/src/DataProtection/DataProtection/src/AuthenticatedEncryption/AuthenticatedEncryptorFactory.cs @@ -22,15 +22,19 @@ public sealed class AuthenticatedEncryptorFactory : IAuthenticatedEncryptorFacto { private readonly ILoggerFactory _loggerFactory; + /// + /// Initializes a new instance of . + /// + /// The . public AuthenticatedEncryptorFactory(ILoggerFactory loggerFactory) { _loggerFactory = loggerFactory; } + /// public IAuthenticatedEncryptor? CreateEncryptorInstance(IKey key) { - var descriptor = key.Descriptor as AuthenticatedEncryptorDescriptor; - if (descriptor == null) + if (key.Descriptor is not AuthenticatedEncryptorDescriptor descriptor) { return null; } diff --git a/src/DataProtection/DataProtection/src/AuthenticatedEncryption/CngCbcAuthenticatedEncryptorFactory.cs b/src/DataProtection/DataProtection/src/AuthenticatedEncryption/CngCbcAuthenticatedEncryptorFactory.cs index ed0f3fc75119..58cd9276c08b 100644 --- a/src/DataProtection/DataProtection/src/AuthenticatedEncryption/CngCbcAuthenticatedEncryptorFactory.cs +++ b/src/DataProtection/DataProtection/src/AuthenticatedEncryption/CngCbcAuthenticatedEncryptorFactory.cs @@ -23,15 +23,19 @@ public sealed class CngCbcAuthenticatedEncryptorFactory : IAuthenticatedEncrypto { private readonly ILogger _logger; + /// + /// Initializes a new instance of . + /// + /// The . public CngCbcAuthenticatedEncryptorFactory(ILoggerFactory loggerFactory) { _logger = loggerFactory.CreateLogger(); } + /// public IAuthenticatedEncryptor? CreateEncryptorInstance(IKey key) { - var descriptor = key.Descriptor as CngCbcAuthenticatedEncryptorDescriptor; - if (descriptor == null) + if (key.Descriptor is not CngCbcAuthenticatedEncryptorDescriptor descriptor) { return null; } diff --git a/src/DataProtection/DataProtection/src/AuthenticatedEncryption/CngGcmAuthenticatedEncryptorFactory.cs b/src/DataProtection/DataProtection/src/AuthenticatedEncryption/CngGcmAuthenticatedEncryptorFactory.cs index 93b5e79792da..f666b074c24d 100644 --- a/src/DataProtection/DataProtection/src/AuthenticatedEncryption/CngGcmAuthenticatedEncryptorFactory.cs +++ b/src/DataProtection/DataProtection/src/AuthenticatedEncryption/CngGcmAuthenticatedEncryptorFactory.cs @@ -23,11 +23,16 @@ public sealed class CngGcmAuthenticatedEncryptorFactory : IAuthenticatedEncrypto { private readonly ILogger _logger; + /// + /// Initializes a new instance of . + /// + /// The . public CngGcmAuthenticatedEncryptorFactory(ILoggerFactory loggerFactory) { _logger = loggerFactory.CreateLogger(); } + /// public IAuthenticatedEncryptor? CreateEncryptorInstance(IKey key) { var descriptor = key.Descriptor as CngGcmAuthenticatedEncryptorDescriptor; diff --git a/src/DataProtection/DataProtection/src/AuthenticatedEncryption/ConfigurationModel/AlgorithmConfiguration.cs b/src/DataProtection/DataProtection/src/AuthenticatedEncryption/ConfigurationModel/AlgorithmConfiguration.cs index 4fddb0a706dd..9ce578a62024 100644 --- a/src/DataProtection/DataProtection/src/AuthenticatedEncryption/ConfigurationModel/AlgorithmConfiguration.cs +++ b/src/DataProtection/DataProtection/src/AuthenticatedEncryption/ConfigurationModel/AlgorithmConfiguration.cs @@ -1,10 +1,13 @@ -// Copyright (c) .NET Foundation. All rights reserved. +// Copyright (c) .NET Foundation. All rights reserved. // Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information. using System; namespace Microsoft.AspNetCore.DataProtection.AuthenticatedEncryption.ConfigurationModel { + /// + /// A factory for producing . + /// public abstract class AlgorithmConfiguration { internal const int KDK_SIZE_IN_BYTES = 512 / 8; diff --git a/src/DataProtection/DataProtection/src/AuthenticatedEncryption/ConfigurationModel/AuthenticatedEncryptorConfiguration.cs b/src/DataProtection/DataProtection/src/AuthenticatedEncryption/ConfigurationModel/AuthenticatedEncryptorConfiguration.cs index 606d7484fb05..a421170c5d2a 100644 --- a/src/DataProtection/DataProtection/src/AuthenticatedEncryption/ConfigurationModel/AuthenticatedEncryptorConfiguration.cs +++ b/src/DataProtection/DataProtection/src/AuthenticatedEncryption/ConfigurationModel/AuthenticatedEncryptorConfiguration.cs @@ -30,6 +30,7 @@ public sealed class AuthenticatedEncryptorConfiguration : AlgorithmConfiguration /// public ValidationAlgorithm ValidationAlgorithm { get; set; } = ValidationAlgorithm.HMACSHA256; + /// public override IAuthenticatedEncryptorDescriptor CreateNewDescriptor() { var internalConfiguration = (IInternalAlgorithmConfiguration)this; diff --git a/src/DataProtection/DataProtection/src/AuthenticatedEncryption/ConfigurationModel/AuthenticatedEncryptorDescriptor.cs b/src/DataProtection/DataProtection/src/AuthenticatedEncryption/ConfigurationModel/AuthenticatedEncryptorDescriptor.cs index 9539c9eb7627..f9dd2ca4f44f 100644 --- a/src/DataProtection/DataProtection/src/AuthenticatedEncryption/ConfigurationModel/AuthenticatedEncryptorDescriptor.cs +++ b/src/DataProtection/DataProtection/src/AuthenticatedEncryption/ConfigurationModel/AuthenticatedEncryptorDescriptor.cs @@ -12,6 +12,11 @@ namespace Microsoft.AspNetCore.DataProtection.AuthenticatedEncryption.Configurat /// public sealed class AuthenticatedEncryptorDescriptor : IAuthenticatedEncryptorDescriptor { + /// + /// Initializes a new instance of . + /// + /// The . + /// The master key. public AuthenticatedEncryptorDescriptor(AuthenticatedEncryptorConfiguration configuration, ISecret masterKey) { if (configuration == null) @@ -32,6 +37,7 @@ public AuthenticatedEncryptorDescriptor(AuthenticatedEncryptorConfiguration conf internal AuthenticatedEncryptorConfiguration Configuration { get; } + /// public XmlSerializedDescriptorInfo ExportToXml() { // diff --git a/src/DataProtection/DataProtection/src/AuthenticatedEncryption/ConfigurationModel/CngCbcAuthenticatedEncryptorConfiguration.cs b/src/DataProtection/DataProtection/src/AuthenticatedEncryption/ConfigurationModel/CngCbcAuthenticatedEncryptorConfiguration.cs index c138f02b4aec..d56d7582a12a 100644 --- a/src/DataProtection/DataProtection/src/AuthenticatedEncryption/ConfigurationModel/CngCbcAuthenticatedEncryptorConfiguration.cs +++ b/src/DataProtection/DataProtection/src/AuthenticatedEncryption/ConfigurationModel/CngCbcAuthenticatedEncryptorConfiguration.cs @@ -73,6 +73,7 @@ public sealed class CngCbcAuthenticatedEncryptorConfiguration : AlgorithmConfigu [ApplyPolicy] public string? HashAlgorithmProvider { get; set; } = null; + /// public override IAuthenticatedEncryptorDescriptor CreateNewDescriptor() { var internalConfiguration = (IInternalAlgorithmConfiguration)this; diff --git a/src/DataProtection/DataProtection/src/AuthenticatedEncryption/ConfigurationModel/CngCbcAuthenticatedEncryptorDescriptor.cs b/src/DataProtection/DataProtection/src/AuthenticatedEncryption/ConfigurationModel/CngCbcAuthenticatedEncryptorDescriptor.cs index 21476883662b..b4e3cf87ff48 100644 --- a/src/DataProtection/DataProtection/src/AuthenticatedEncryption/ConfigurationModel/CngCbcAuthenticatedEncryptorDescriptor.cs +++ b/src/DataProtection/DataProtection/src/AuthenticatedEncryption/ConfigurationModel/CngCbcAuthenticatedEncryptorDescriptor.cs @@ -14,6 +14,11 @@ namespace Microsoft.AspNetCore.DataProtection.AuthenticatedEncryption.Configurat [SupportedOSPlatform("windows")] public sealed class CngCbcAuthenticatedEncryptorDescriptor : IAuthenticatedEncryptorDescriptor { + /// + /// Initializes a new instance of . + /// + /// The . + /// The master key. public CngCbcAuthenticatedEncryptorDescriptor(CngCbcAuthenticatedEncryptorConfiguration configuration, ISecret masterKey) { if (configuration == null) @@ -34,6 +39,7 @@ public CngCbcAuthenticatedEncryptorDescriptor(CngCbcAuthenticatedEncryptorConfig internal CngCbcAuthenticatedEncryptorConfiguration Configuration { get; } + /// public XmlSerializedDescriptorInfo ExportToXml() { // diff --git a/src/DataProtection/DataProtection/src/AuthenticatedEncryption/ConfigurationModel/CngGcmAuthenticatedEncryptorConfiguration.cs b/src/DataProtection/DataProtection/src/AuthenticatedEncryption/ConfigurationModel/CngGcmAuthenticatedEncryptorConfiguration.cs index 0ad601af08a7..bfabc9bddbe4 100644 --- a/src/DataProtection/DataProtection/src/AuthenticatedEncryption/ConfigurationModel/CngGcmAuthenticatedEncryptorConfiguration.cs +++ b/src/DataProtection/DataProtection/src/AuthenticatedEncryption/ConfigurationModel/CngGcmAuthenticatedEncryptorConfiguration.cs @@ -49,6 +49,7 @@ public sealed class CngGcmAuthenticatedEncryptorConfiguration : AlgorithmConfigu [ApplyPolicy] public int EncryptionAlgorithmKeySize { get; set; } = 256; + /// public override IAuthenticatedEncryptorDescriptor CreateNewDescriptor() { var internalConfiguration = (IInternalAlgorithmConfiguration)this; diff --git a/src/DataProtection/DataProtection/src/AuthenticatedEncryption/ConfigurationModel/CngGcmAuthenticatedEncryptorDescriptor.cs b/src/DataProtection/DataProtection/src/AuthenticatedEncryption/ConfigurationModel/CngGcmAuthenticatedEncryptorDescriptor.cs index a2184c0e62cb..f80be820214f 100644 --- a/src/DataProtection/DataProtection/src/AuthenticatedEncryption/ConfigurationModel/CngGcmAuthenticatedEncryptorDescriptor.cs +++ b/src/DataProtection/DataProtection/src/AuthenticatedEncryption/ConfigurationModel/CngGcmAuthenticatedEncryptorDescriptor.cs @@ -14,6 +14,11 @@ namespace Microsoft.AspNetCore.DataProtection.AuthenticatedEncryption.Configurat [SupportedOSPlatform("windows")] public sealed class CngGcmAuthenticatedEncryptorDescriptor : IAuthenticatedEncryptorDescriptor { + /// + /// Initializes a new instance of . + /// + /// The . + /// The master key. public CngGcmAuthenticatedEncryptorDescriptor(CngGcmAuthenticatedEncryptorConfiguration configuration, ISecret masterKey) { if (configuration == null) @@ -34,6 +39,7 @@ public CngGcmAuthenticatedEncryptorDescriptor(CngGcmAuthenticatedEncryptorConfig internal CngGcmAuthenticatedEncryptorConfiguration Configuration { get; } + /// public XmlSerializedDescriptorInfo ExportToXml() { // diff --git a/src/DataProtection/DataProtection/src/AuthenticatedEncryption/ConfigurationModel/ManagedAuthenticatedEncryptorConfiguration.cs b/src/DataProtection/DataProtection/src/AuthenticatedEncryption/ConfigurationModel/ManagedAuthenticatedEncryptorConfiguration.cs index 2a23cc0aa86a..38ecbb930e4f 100644 --- a/src/DataProtection/DataProtection/src/AuthenticatedEncryption/ConfigurationModel/ManagedAuthenticatedEncryptorConfiguration.cs +++ b/src/DataProtection/DataProtection/src/AuthenticatedEncryption/ConfigurationModel/ManagedAuthenticatedEncryptorConfiguration.cs @@ -49,6 +49,7 @@ public sealed class ManagedAuthenticatedEncryptorConfiguration : AlgorithmConfig [ApplyPolicy] public Type ValidationAlgorithmType { get; set; } = typeof(HMACSHA256); + /// public override IAuthenticatedEncryptorDescriptor CreateNewDescriptor() { var internalConfiguration = (IInternalAlgorithmConfiguration)this; diff --git a/src/DataProtection/DataProtection/src/AuthenticatedEncryption/ConfigurationModel/ManagedAuthenticatedEncryptorDescriptor.cs b/src/DataProtection/DataProtection/src/AuthenticatedEncryption/ConfigurationModel/ManagedAuthenticatedEncryptorDescriptor.cs index df99f61b9cab..a1bc73b582c6 100644 --- a/src/DataProtection/DataProtection/src/AuthenticatedEncryption/ConfigurationModel/ManagedAuthenticatedEncryptorDescriptor.cs +++ b/src/DataProtection/DataProtection/src/AuthenticatedEncryption/ConfigurationModel/ManagedAuthenticatedEncryptorDescriptor.cs @@ -13,6 +13,11 @@ namespace Microsoft.AspNetCore.DataProtection.AuthenticatedEncryption.Configurat /// public sealed class ManagedAuthenticatedEncryptorDescriptor : IAuthenticatedEncryptorDescriptor { + /// + /// Initializes a new instance of . + /// + /// The . + /// The master key. public ManagedAuthenticatedEncryptorDescriptor(ManagedAuthenticatedEncryptorConfiguration configuration, ISecret masterKey) { if (configuration == null) @@ -33,6 +38,7 @@ public ManagedAuthenticatedEncryptorDescriptor(ManagedAuthenticatedEncryptorConf internal ManagedAuthenticatedEncryptorConfiguration Configuration { get; } + /// public XmlSerializedDescriptorInfo ExportToXml() { // diff --git a/src/DataProtection/DataProtection/src/AuthenticatedEncryption/ConfigurationModel/XmlExtensions.cs b/src/DataProtection/DataProtection/src/AuthenticatedEncryption/ConfigurationModel/XmlExtensions.cs index 572a0cba59ca..ebae69ecb2b0 100644 --- a/src/DataProtection/DataProtection/src/AuthenticatedEncryption/ConfigurationModel/XmlExtensions.cs +++ b/src/DataProtection/DataProtection/src/AuthenticatedEncryption/ConfigurationModel/XmlExtensions.cs @@ -6,6 +6,9 @@ namespace Microsoft.AspNetCore.DataProtection.AuthenticatedEncryption.ConfigurationModel { + /// + /// Data protection extensions for . + /// public static class XmlExtensions { internal static bool IsMarkedAsRequiringEncryption(this XElement element) diff --git a/src/DataProtection/DataProtection/src/AuthenticatedEncryption/IAuthenticatedEncryptorFactory.cs b/src/DataProtection/DataProtection/src/AuthenticatedEncryption/IAuthenticatedEncryptorFactory.cs index a51e77e78d21..92af08466a18 100644 --- a/src/DataProtection/DataProtection/src/AuthenticatedEncryption/IAuthenticatedEncryptorFactory.cs +++ b/src/DataProtection/DataProtection/src/AuthenticatedEncryption/IAuthenticatedEncryptorFactory.cs @@ -6,6 +6,9 @@ namespace Microsoft.AspNetCore.DataProtection.AuthenticatedEncryption { + /// + /// A factory to produce instances. + /// public interface IAuthenticatedEncryptorFactory { /// diff --git a/src/DataProtection/DataProtection/src/AuthenticatedEncryption/ManagedAuthenticatedEncryptorFactory.cs b/src/DataProtection/DataProtection/src/AuthenticatedEncryption/ManagedAuthenticatedEncryptorFactory.cs index 0ac909afbc1d..12382670dbc3 100644 --- a/src/DataProtection/DataProtection/src/AuthenticatedEncryption/ManagedAuthenticatedEncryptorFactory.cs +++ b/src/DataProtection/DataProtection/src/AuthenticatedEncryption/ManagedAuthenticatedEncryptorFactory.cs @@ -19,15 +19,19 @@ public sealed class ManagedAuthenticatedEncryptorFactory : IAuthenticatedEncrypt { private readonly ILogger _logger; + /// + /// Initializes a new instance of . + /// + /// The . public ManagedAuthenticatedEncryptorFactory(ILoggerFactory loggerFactory) { _logger = loggerFactory.CreateLogger(); } + /// public IAuthenticatedEncryptor? CreateEncryptorInstance(IKey key) { - var descriptor = key.Descriptor as ManagedAuthenticatedEncryptorDescriptor; - if (descriptor == null) + if (key.Descriptor is not ManagedAuthenticatedEncryptorDescriptor descriptor) { return null; } diff --git a/src/DataProtection/DataProtection/src/DataProtectionUtilityExtensions.cs b/src/DataProtection/DataProtection/src/DataProtectionUtilityExtensions.cs index a2a71e7e124a..45af825a6cef 100644 --- a/src/DataProtection/DataProtection/src/DataProtectionUtilityExtensions.cs +++ b/src/DataProtection/DataProtection/src/DataProtectionUtilityExtensions.cs @@ -8,6 +8,9 @@ namespace Microsoft.AspNetCore.DataProtection { + /// + /// Data protection extensions for . + /// public static class DataProtectionUtilityExtensions { /// diff --git a/src/DataProtection/DataProtection/src/EphemeralDataProtectionProvider.cs b/src/DataProtection/DataProtection/src/EphemeralDataProtectionProvider.cs index 353fa896b72a..8faae175fedc 100644 --- a/src/DataProtection/DataProtection/src/EphemeralDataProtectionProvider.cs +++ b/src/DataProtection/DataProtection/src/EphemeralDataProtectionProvider.cs @@ -62,6 +62,7 @@ public EphemeralDataProtectionProvider(ILoggerFactory loggerFactory) _dataProtectionProvider = new KeyRingBasedDataProtectionProvider(keyringProvider, loggerFactory); } + /// public IDataProtector CreateProtector(string purpose) { if (purpose == null) diff --git a/src/DataProtection/DataProtection/src/KeyManagement/Internal/ICacheableKeyRingProvider.cs b/src/DataProtection/DataProtection/src/KeyManagement/Internal/ICacheableKeyRingProvider.cs index 7c41388532ef..2e677b3fa702 100644 --- a/src/DataProtection/DataProtection/src/KeyManagement/Internal/ICacheableKeyRingProvider.cs +++ b/src/DataProtection/DataProtection/src/KeyManagement/Internal/ICacheableKeyRingProvider.cs @@ -11,6 +11,10 @@ namespace Microsoft.AspNetCore.DataProtection.KeyManagement.Internal /// public interface ICacheableKeyRingProvider { + /// + /// This API supports infrastructure and is not intended to be used + /// directly from your code. This API may change or be removed in future releases. + /// CacheableKeyRing GetCacheableKeyRing(DateTimeOffset now); } } diff --git a/src/DataProtection/DataProtection/src/KeyManagement/Internal/IInternalXmlKeyManager.cs b/src/DataProtection/DataProtection/src/KeyManagement/Internal/IInternalXmlKeyManager.cs index 2a35ae4a5ab8..1433df932701 100644 --- a/src/DataProtection/DataProtection/src/KeyManagement/Internal/IInternalXmlKeyManager.cs +++ b/src/DataProtection/DataProtection/src/KeyManagement/Internal/IInternalXmlKeyManager.cs @@ -13,10 +13,22 @@ namespace Microsoft.AspNetCore.DataProtection.KeyManagement.Internal /// public interface IInternalXmlKeyManager { + /// + /// This API supports infrastructure and is not intended to be used + /// directly from your code. This API may change or be removed in future releases. + /// IKey CreateNewKey(Guid keyId, DateTimeOffset creationDate, DateTimeOffset activationDate, DateTimeOffset expirationDate); + /// + /// This API supports infrastructure and is not intended to be used + /// directly from your code. This API may change or be removed in future releases. + /// IAuthenticatedEncryptorDescriptor DeserializeDescriptorFromKeyElement(XElement keyElement); + /// + /// This API supports infrastructure and is not intended to be used + /// directly from your code. This API may change or be removed in future releases. + /// void RevokeSingleKey(Guid keyId, DateTimeOffset revocationDate, string? reason); } } diff --git a/src/DataProtection/DataProtection/src/KeyManagement/Internal/IKeyRingProvider.cs b/src/DataProtection/DataProtection/src/KeyManagement/Internal/IKeyRingProvider.cs index 67bc44776e72..e16ccd80ebfa 100644 --- a/src/DataProtection/DataProtection/src/KeyManagement/Internal/IKeyRingProvider.cs +++ b/src/DataProtection/DataProtection/src/KeyManagement/Internal/IKeyRingProvider.cs @@ -9,6 +9,10 @@ namespace Microsoft.AspNetCore.DataProtection.KeyManagement.Internal /// public interface IKeyRingProvider { + /// + /// This API supports infrastructure and is not intended to be used + /// directly from your code. This API may change or be removed in future releases. + /// IKeyRing GetCurrentKeyRing(); } } diff --git a/src/DataProtection/DataProtection/src/KeyManagement/KeyManagementOptions.cs b/src/DataProtection/DataProtection/src/KeyManagement/KeyManagementOptions.cs index f6421717d6c7..592aeea7b770 100644 --- a/src/DataProtection/DataProtection/src/KeyManagement/KeyManagementOptions.cs +++ b/src/DataProtection/DataProtection/src/KeyManagement/KeyManagementOptions.cs @@ -20,6 +20,9 @@ public class KeyManagementOptions private static readonly TimeSpan _maxServerClockSkew = TimeSpan.FromMinutes(5); private TimeSpan _newKeyLifetime = TimeSpan.FromDays(90); + /// + /// Initializes a new instance of . + /// public KeyManagementOptions() { } diff --git a/src/DataProtection/DataProtection/src/KeyManagement/XmlKeyManager.cs b/src/DataProtection/DataProtection/src/KeyManagement/XmlKeyManager.cs index 23eb087ee980..a72735e13762 100644 --- a/src/DataProtection/DataProtection/src/KeyManagement/XmlKeyManager.cs +++ b/src/DataProtection/DataProtection/src/KeyManagement/XmlKeyManager.cs @@ -136,6 +136,7 @@ internal XmlKeyManager( internal IXmlRepository KeyRepository { get; } + /// public IKey CreateNewKey(DateTimeOffset activationDate, DateTimeOffset expirationDate) { return _internalKeyManager.CreateNewKey( @@ -151,6 +152,7 @@ private static string DateTimeOffsetToFilenameSafeString(DateTimeOffset dateTime return dateTime.UtcDateTime.ToString("yyyyMMddTHHmmssFFFFFFFZ", CultureInfo.InvariantCulture); } + /// public IReadOnlyCollection GetAllKeys() { var allElements = KeyRepository.GetAllElements(); @@ -245,6 +247,7 @@ public IReadOnlyCollection GetAllKeys() return keyIdToKeyMap.Values.ToList().AsReadOnly(); } + /// public CancellationToken GetCacheExpirationToken() { Debug.Assert(_cacheExpirationTokenSource != null, $"{nameof(TriggerAndResetCacheExpirationToken)} must have been called first."); @@ -316,6 +319,7 @@ private object ProcessRevocationElement(XElement revocationElement) } } + /// public void RevokeAllKeys(DateTimeOffset revocationDate, string? reason = null) { // @@ -341,6 +345,7 @@ public void RevokeAllKeys(DateTimeOffset revocationDate, string? reason = null) TriggerAndResetCacheExpirationToken(); } + /// public void RevokeKey(Guid keyId, string? reason = null) { _internalKeyManager.RevokeSingleKey( diff --git a/src/DataProtection/DataProtection/src/Microsoft.AspNetCore.DataProtection.csproj b/src/DataProtection/DataProtection/src/Microsoft.AspNetCore.DataProtection.csproj index 88a34ef8c0ac..c2ebd423a1f3 100644 --- a/src/DataProtection/DataProtection/src/Microsoft.AspNetCore.DataProtection.csproj +++ b/src/DataProtection/DataProtection/src/Microsoft.AspNetCore.DataProtection.csproj @@ -1,11 +1,10 @@ - + ASP.NET Core logic to protect and unprotect data, similar to DPAPI. $(DefaultNetFxTargetFramework);netstandard2.0;$(DefaultNetCoreTargetFramework) $(DefaultNetCoreTargetFramework) true - $(NoWarn);CS1591 true true aspnetcore;dataprotection diff --git a/src/DataProtection/DataProtection/src/Repositories/FileSystemXmlRepository.cs b/src/DataProtection/DataProtection/src/Repositories/FileSystemXmlRepository.cs index b5893910e82d..5f40498717c5 100644 --- a/src/DataProtection/DataProtection/src/Repositories/FileSystemXmlRepository.cs +++ b/src/DataProtection/DataProtection/src/Repositories/FileSystemXmlRepository.cs @@ -62,6 +62,7 @@ public FileSystemXmlRepository(DirectoryInfo directory, ILoggerFactory loggerFac /// public DirectoryInfo Directory { get; } + /// public virtual IReadOnlyCollection GetAllElements() { // forces complete enumeration @@ -105,6 +106,7 @@ private XElement ReadElementFromFile(string fullPath) } } + /// public virtual void StoreElement(XElement element, string friendlyName) { if (element == null) diff --git a/src/DataProtection/DataProtection/src/Repositories/RegistryXmlRepository.cs b/src/DataProtection/DataProtection/src/Repositories/RegistryXmlRepository.cs index be48aa3c8be7..98ba16480696 100644 --- a/src/DataProtection/DataProtection/src/Repositories/RegistryXmlRepository.cs +++ b/src/DataProtection/DataProtection/src/Repositories/RegistryXmlRepository.cs @@ -54,6 +54,7 @@ public RegistryXmlRepository(RegistryKey registryKey, ILoggerFactory loggerFacto /// public RegistryKey RegistryKey { get; } + /// public virtual IReadOnlyCollection GetAllElements() { // forces complete enumeration @@ -133,6 +134,7 @@ private static bool IsSafeRegistryValueName(string filename) return (!string.IsNullOrEmpty(data)) ? XElement.Parse(data) : null; } + /// public virtual void StoreElement(XElement element, string friendlyName) { if (element == null) diff --git a/src/Http/WebUtilities/src/Base64UrlTextEncoder.cs b/src/Http/WebUtilities/src/Base64UrlTextEncoder.cs index 304ee6522f81..3a4294e08660 100644 --- a/src/Http/WebUtilities/src/Base64UrlTextEncoder.cs +++ b/src/Http/WebUtilities/src/Base64UrlTextEncoder.cs @@ -1,8 +1,11 @@ -// Copyright (c) .NET Foundation. All rights reserved. +// Copyright (c) .NET Foundation. All rights reserved. // Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information. namespace Microsoft.AspNetCore.WebUtilities { + /// + /// Encodes and decodes using base64 url encoding. + /// public static class Base64UrlTextEncoder { /// diff --git a/src/Http/WebUtilities/src/FileBufferingReadStream.cs b/src/Http/WebUtilities/src/FileBufferingReadStream.cs index 5f889933f18b..91c17e1808bc 100644 --- a/src/Http/WebUtilities/src/FileBufferingReadStream.cs +++ b/src/Http/WebUtilities/src/FileBufferingReadStream.cs @@ -45,6 +45,13 @@ public FileBufferingReadStream(Stream inner, int memoryThreshold) { } + /// + /// Initializes a new instance of . + /// + /// The wrapping . + /// The maximum size to buffer in memory. + /// The maximum size that will be buffered before this throws. + /// Provides the temporary directory to which files are buffered to. public FileBufferingReadStream( Stream inner, int memoryThreshold, @@ -54,6 +61,14 @@ public FileBufferingReadStream( { } + /// + /// Initializes a new instance of . + /// + /// The wrapping . + /// The maximum size to buffer in memory. + /// The maximum size that will be buffered before this throws. + /// Provides the temporary directory to which files are buffered to. + /// The to use. public FileBufferingReadStream( Stream inner, int memoryThreshold, @@ -89,6 +104,13 @@ public FileBufferingReadStream( _tempFileDirectoryAccessor = tempFileDirectoryAccessor; } + /// + /// Initializes a new instance of . + /// + /// The wrapping . + /// The maximum size to buffer in memory. + /// The maximum size that will be buffered before this throws. + /// The temporary directory to which files are buffered to. public FileBufferingReadStream( Stream inner, int memoryThreshold, @@ -98,6 +120,14 @@ public FileBufferingReadStream( { } + /// + /// Initializes a new instance of . + /// + /// The wrapping . + /// The maximum size to buffer in memory. + /// The maximum size that will be buffered before this throws. + /// The temporary directory to which files are buffered to. + /// The to use. public FileBufferingReadStream( Stream inner, int memoryThreshold, @@ -133,36 +163,47 @@ public FileBufferingReadStream( _tempFileDirectory = tempFileDirectory; } + /// + /// Gets a value that determines if the contents are buffered entirely in memory. + /// public bool InMemory { get { return _inMemory; } } + /// + /// Gets a value that determines where the contents are buffered on disk. + /// public string? TempFileName { get { return _tempFileName; } } + /// public override bool CanRead { get { return true; } } + /// public override bool CanSeek { get { return true; } } + /// public override bool CanWrite { get { return false; } } + /// public override long Length { get { return _buffer.Length; } } + /// public override long Position { get { return _buffer.Position; } @@ -174,6 +215,7 @@ public override long Position } } + /// public override long Seek(long offset, SeekOrigin origin) { ThrowIfDisposed(); @@ -209,6 +251,7 @@ private Stream CreateTempFile() FileOptions.Asynchronous | FileOptions.DeleteOnClose | FileOptions.SequentialScan); } + /// public override int Read(Span buffer) { ThrowIfDisposed(); @@ -271,16 +314,19 @@ public override int Read(Span buffer) return read; } + /// public override int Read(byte[] buffer, int offset, int count) { return Read(buffer.AsSpan(offset, count)); } + /// public override Task ReadAsync(byte[] buffer, int offset, int count, CancellationToken cancellationToken) { return ReadAsync(buffer.AsMemory(offset, count), cancellationToken).AsTask(); } + /// [SuppressMessage("ApiDesign", "RS0027:Public API with optional parameter(s) should have the most parameters amongst its public overloads.", Justification = "Required to maintain compatibility")] public override async ValueTask ReadAsync(Memory buffer, CancellationToken cancellationToken = default) { @@ -343,26 +389,31 @@ public override async ValueTask ReadAsync(Memory buffer, Cancellation return read; } + /// public override void Write(byte[] buffer, int offset, int count) { throw new NotSupportedException(); } + /// public override Task WriteAsync(byte[] buffer, int offset, int count, CancellationToken cancellationToken) { throw new NotSupportedException(); } + /// public override void SetLength(long value) { throw new NotSupportedException(); } + /// public override void Flush() { throw new NotSupportedException(); } + /// public override Task CopyToAsync(Stream destination, int bufferSize, CancellationToken cancellationToken) { // Set a minimum buffer size of 4K since the base Stream implementation has weird behavior when the stream is @@ -401,6 +452,7 @@ async Task CopyToAsyncImpl() return CopyToAsyncImpl(); } + /// protected override void Dispose(bool disposing) { if (!_disposed) @@ -418,6 +470,7 @@ protected override void Dispose(bool disposing) } } + /// public async override ValueTask DisposeAsync() { if (!_disposed) diff --git a/src/Http/WebUtilities/src/FileBufferingWriteStream.cs b/src/Http/WebUtilities/src/FileBufferingWriteStream.cs index 0d77cbfbc345..9cf551d817ad 100644 --- a/src/Http/WebUtilities/src/FileBufferingWriteStream.cs +++ b/src/Http/WebUtilities/src/FileBufferingWriteStream.cs @@ -200,6 +200,12 @@ public async Task DrainBufferAsync(Stream destination, CancellationToken cancell await PagedByteBuffer.MoveToAsync(destination, cancellationToken); } + /// + /// Drains buffered content to . + /// + /// The to drain buffered contents to. + /// The . + /// A that represents the asynchronous drain operation. [SuppressMessage("ApiDesign", "RS0026:Do not add multiple public overloads with optional parameters", Justification = "Required to maintain compatibility")] public async Task DrainBufferAsync(PipeWriter destination, CancellationToken cancellationToken = default) { diff --git a/src/Http/WebUtilities/src/FormPipeReader.cs b/src/Http/WebUtilities/src/FormPipeReader.cs index 4a8a3d216c8d..d2008a427f47 100644 --- a/src/Http/WebUtilities/src/FormPipeReader.cs +++ b/src/Http/WebUtilities/src/FormPipeReader.cs @@ -40,11 +40,20 @@ public class FormPipeReader private readonly PipeReader _pipeReader; private readonly Encoding _encoding; + /// + /// Initializes a new instance of . + /// + /// The to read from. public FormPipeReader(PipeReader pipeReader) : this(pipeReader, Encoding.UTF8) { } + /// + /// Initializes a new instance of . + /// + /// The to read from. + /// The . public FormPipeReader(PipeReader pipeReader, Encoding encoding) { #pragma warning disable CS0618, SYSLIB0001 // Type or member is obsolete diff --git a/src/Http/WebUtilities/src/FormReader.cs b/src/Http/WebUtilities/src/FormReader.cs index 4cadb6c88e74..95aa9e6c0845 100644 --- a/src/Http/WebUtilities/src/FormReader.cs +++ b/src/Http/WebUtilities/src/FormReader.cs @@ -18,8 +18,19 @@ namespace Microsoft.AspNetCore.WebUtilities /// public class FormReader : IDisposable { + /// + /// Gets the default value for . + /// public const int DefaultValueCountLimit = 1024; + + /// + /// Gets the default value for . + /// public const int DefaultKeyLengthLimit = 1024 * 2; + + /// + /// Gets the default value for . + /// public const int DefaultValueLengthLimit = 1024 * 1024 * 4; private const int _rentedCharPoolLength = 8192; @@ -34,11 +45,20 @@ public class FormReader : IDisposable private bool _endOfStream; private bool _disposed; + /// + /// Initializes a new instance of . + /// + /// The data to read. public FormReader(string data) : this(data, ArrayPool.Shared) { } + /// + /// Initializes a new instance of . + /// + /// The data to read. + /// The to use. public FormReader(string data, ArrayPool charPool) { if (data == null) @@ -51,16 +71,31 @@ public FormReader(string data, ArrayPool charPool) _reader = new StringReader(data); } + /// + /// Initializes a new instance of . + /// + /// The to read. Assumes a utf-8 encoded stream. public FormReader(Stream stream) : this(stream, Encoding.UTF8, ArrayPool.Shared) { } + /// + /// Initializes a new instance of . + /// + /// The to read. + /// The character encoding to use. public FormReader(Stream stream, Encoding encoding) : this(stream, encoding, ArrayPool.Shared) { } + /// + /// Initializes a new instance of . + /// + /// The to read. + /// The character encoding to use. + /// The to use. public FormReader(Stream stream, Encoding encoding, ArrayPool charPool) { if (stream == null) @@ -302,6 +337,7 @@ private void Append(ref KeyValueAccumulator accumulator) } } + /// public void Dispose() { if (!_disposed) diff --git a/src/Http/WebUtilities/src/HttpRequestStreamReader.cs b/src/Http/WebUtilities/src/HttpRequestStreamReader.cs index 7b99271e87e6..3136b5768166 100644 --- a/src/Http/WebUtilities/src/HttpRequestStreamReader.cs +++ b/src/Http/WebUtilities/src/HttpRequestStreamReader.cs @@ -12,6 +12,9 @@ namespace Microsoft.AspNetCore.WebUtilities { + /// + /// A to read the HTTP request stream. + /// public class HttpRequestStreamReader : TextReader { private const int DefaultBufferSize = 1024; @@ -36,16 +39,35 @@ public class HttpRequestStreamReader : TextReader private bool _isBlocked; private bool _disposed; + /// + /// Initializes a new instance of . + /// + /// The HTTP request . + /// The character encoding to use. public HttpRequestStreamReader(Stream stream, Encoding encoding) : this(stream, encoding, DefaultBufferSize, ArrayPool.Shared, ArrayPool.Shared) { } + /// + /// Initializes a new instance of . + /// + /// The HTTP request . + /// The character encoding to use. + /// The minimum buffer size. public HttpRequestStreamReader(Stream stream, Encoding encoding, int bufferSize) : this(stream, encoding, bufferSize, ArrayPool.Shared, ArrayPool.Shared) { } + /// + /// Initializes a new instance of . + /// + /// The HTTP request . + /// The character encoding to use. + /// The minimum buffer size. + /// The byte array pool to use. + /// The char array pool to use. public HttpRequestStreamReader( Stream stream, Encoding encoding, @@ -90,6 +112,7 @@ public HttpRequestStreamReader( } } + /// protected override void Dispose(bool disposing) { if (disposing && !_disposed) @@ -103,6 +126,7 @@ protected override void Dispose(bool disposing) base.Dispose(disposing); } + /// public override int Peek() { if (_disposed) @@ -121,6 +145,7 @@ public override int Peek() return _charBuffer[_charBufferIndex]; } + /// public override int Read() { if (_disposed) @@ -139,6 +164,7 @@ public override int Read() return _charBuffer[_charBufferIndex++]; } + /// public override int Read(char[] buffer, int index, int count) { if (buffer == null) @@ -160,6 +186,7 @@ public override int Read(char[] buffer, int index, int count) return Read(span); } + /// public override int Read(Span buffer) { if (buffer == null) @@ -213,6 +240,7 @@ public override int Read(Span buffer) return charsRead; } + /// public override Task ReadAsync(char[] buffer, int index, int count) { if (buffer == null) @@ -234,6 +262,7 @@ public override Task ReadAsync(char[] buffer, int index, int count) return ReadAsync(memory).AsTask(); } + /// [SuppressMessage("ApiDesign", "RS0027:Public API with optional parameter(s) should have the most parameters amongst its public overloads.", Justification = "Required to maintain compatibility")] public override async ValueTask ReadAsync(Memory buffer, CancellationToken cancellationToken = default) { @@ -330,6 +359,7 @@ public override async ValueTask ReadAsync(Memory buffer, Cancellation return charsRead; } + /// public override async Task ReadLineAsync() { if (_disposed) @@ -367,6 +397,7 @@ public override async ValueTask ReadAsync(Memory buffer, Cancellation // immediately followed by a line feed. The resulting string does not // contain the terminating carriage return and/or line feed. The returned // value is null if the end of the input stream has been reached. + /// public override string? ReadLine() { if (_disposed) @@ -530,6 +561,7 @@ private async Task ReadIntoBufferAsync() return _charsRead; } + /// public async override Task ReadToEndAsync() { StringBuilder sb = new StringBuilder(_charsRead - _charBufferIndex); diff --git a/src/Http/WebUtilities/src/HttpResponseStreamWriter.cs b/src/Http/WebUtilities/src/HttpResponseStreamWriter.cs index 46ec2e79410f..55cc5d3933d3 100644 --- a/src/Http/WebUtilities/src/HttpResponseStreamWriter.cs +++ b/src/Http/WebUtilities/src/HttpResponseStreamWriter.cs @@ -14,7 +14,7 @@ namespace Microsoft.AspNetCore.WebUtilities { /// - /// Writes to the using the supplied . + /// Writes to the HTTP response using the supplied . /// It does not write the BOM and also does not close the stream. /// public class HttpResponseStreamWriter : TextWriter @@ -34,16 +34,35 @@ public class HttpResponseStreamWriter : TextWriter private int _charBufferCount; private bool _disposed; + /// + /// Initializes a new instance of . + /// + /// The HTTP response . + /// The character encoding to use. public HttpResponseStreamWriter(Stream stream, Encoding encoding) : this(stream, encoding, DefaultBufferSize, ArrayPool.Shared, ArrayPool.Shared) { } + /// + /// Initializes a new instance of . + /// + /// The HTTP response . + /// The character encoding to use. + /// The minimum buffer size. public HttpResponseStreamWriter(Stream stream, Encoding encoding, int bufferSize) : this(stream, encoding, bufferSize, ArrayPool.Shared, ArrayPool.Shared) { } + /// + /// Initializes a new instance of . + /// + /// The HTTP response . + /// The character encoding to use. + /// The minimum buffer size. + /// The byte array pool. + /// The char array pool. public HttpResponseStreamWriter( Stream stream, Encoding encoding, @@ -88,8 +107,10 @@ public HttpResponseStreamWriter( } } + /// public override Encoding Encoding { get; } + /// public override void Write(char value) { if (_disposed) @@ -106,6 +127,7 @@ public override void Write(char value) _charBufferCount++; } + /// public override void Write(char[] values, int index, int count) { if (_disposed) @@ -129,6 +151,7 @@ public override void Write(char[] values, int index, int count) } } + /// public override void Write(ReadOnlySpan value) { if (_disposed) @@ -151,6 +174,7 @@ public override void Write(ReadOnlySpan value) }; } + /// public override void Write(string? value) { if (_disposed) @@ -176,6 +200,7 @@ public override void Write(string? value) } } + /// public override void WriteLine(ReadOnlySpan value) { if (_disposed) @@ -187,6 +212,7 @@ public override void WriteLine(ReadOnlySpan value) Write(NewLine); } + /// public override Task WriteAsync(char value) { if (_disposed) @@ -217,6 +243,7 @@ private async Task WriteAsyncAwaited(char value) _charBufferCount++; } + /// public override Task WriteAsync(char[] values, int index, int count) { if (_disposed) @@ -258,6 +285,7 @@ private async Task WriteAsyncAwaited(char[] values, int index, int count) } } + /// public override Task WriteAsync(string? value) { if (_disposed) @@ -302,6 +330,7 @@ private async Task WriteAsyncAwaited(string value) } } + /// [SuppressMessage("ApiDesign", "RS0027:Public API with optional parameter(s) should have the most parameters amongst its public overloads.", Justification = "Required to maintain compatibility")] public override Task WriteAsync(ReadOnlyMemory value, CancellationToken cancellationToken = default) { @@ -353,6 +382,7 @@ private async Task WriteAsyncAwaited(ReadOnlyMemory value) }; } + /// public override Task WriteLineAsync(ReadOnlyMemory value, CancellationToken cancellationToken = default) { if (_disposed) @@ -393,6 +423,7 @@ private async Task WriteLineAsyncAwaited(ReadOnlyMemory value) // We want to flush the stream when Flush/FlushAsync is explicitly // called by the user (example: from a Razor view). + /// public override void Flush() { if (_disposed) @@ -403,6 +434,7 @@ public override void Flush() FlushInternal(flushEncoder: true); } + /// public override Task FlushAsync() { if (_disposed) @@ -413,6 +445,7 @@ public override Task FlushAsync() return FlushInternalAsync(flushEncoder: true); } + /// protected override void Dispose(bool disposing) { if (disposing && !_disposed) @@ -432,6 +465,7 @@ protected override void Dispose(bool disposing) base.Dispose(disposing); } + /// public override async ValueTask DisposeAsync() { if (!_disposed) diff --git a/src/Http/WebUtilities/src/KeyValueAccumulator.cs b/src/Http/WebUtilities/src/KeyValueAccumulator.cs index 5ae402e5236c..0b308de5ffae 100644 --- a/src/Http/WebUtilities/src/KeyValueAccumulator.cs +++ b/src/Http/WebUtilities/src/KeyValueAccumulator.cs @@ -7,11 +7,19 @@ namespace Microsoft.AspNetCore.WebUtilities { + /// + /// This API supports infrastructure and is not intended to be used + /// directly from your code. This API may change or be removed in future releases. + /// public struct KeyValueAccumulator { private Dictionary _accumulator; private Dictionary> _expandingAccumulator; + /// + /// This API supports infrastructure and is not intended to be used + /// directly from your code. This API may change or be removed in future releases. + /// public void Append(string key, string value) { if (_accumulator == null) @@ -63,12 +71,28 @@ public void Append(string key, string value) ValueCount++; } + /// + /// This API supports infrastructure and is not intended to be used + /// directly from your code. This API may change or be removed in future releases. + /// public bool HasValues => ValueCount > 0; + /// + /// This API supports infrastructure and is not intended to be used + /// directly from your code. This API may change or be removed in future releases. + /// public int KeyCount => _accumulator?.Count ?? 0; + /// + /// This API supports infrastructure and is not intended to be used + /// directly from your code. This API may change or be removed in future releases. + /// public int ValueCount { get; private set; } + /// + /// This API supports infrastructure and is not intended to be used + /// directly from your code. This API may change or be removed in future releases. + /// public Dictionary GetResults() { if (_expandingAccumulator != null) diff --git a/src/Http/WebUtilities/src/Microsoft.AspNetCore.WebUtilities.csproj b/src/Http/WebUtilities/src/Microsoft.AspNetCore.WebUtilities.csproj index d165fe972721..95b496204d4e 100644 --- a/src/Http/WebUtilities/src/Microsoft.AspNetCore.WebUtilities.csproj +++ b/src/Http/WebUtilities/src/Microsoft.AspNetCore.WebUtilities.csproj @@ -5,7 +5,6 @@ $(DefaultNetCoreTargetFramework) true $(DefineConstants);WebEncoders_In_WebUtilities - $(NoWarn);CS1591 true aspnetcore false diff --git a/src/Http/WebUtilities/src/MultipartReader.cs b/src/Http/WebUtilities/src/MultipartReader.cs index b9692e1d9436..c714b013c48f 100644 --- a/src/Http/WebUtilities/src/MultipartReader.cs +++ b/src/Http/WebUtilities/src/MultipartReader.cs @@ -12,9 +12,19 @@ namespace Microsoft.AspNetCore.WebUtilities { // https://www.ietf.org/rfc/rfc2046.txt + /// + /// Reads multipart form content from the specified . + /// public class MultipartReader { + /// + /// Gets the default value for . + /// public const int DefaultHeadersCountLimit = 16; + + /// + /// Gets the default value for . + /// public const int DefaultHeadersLengthLimit = 1024 * 16; private const int DefaultBufferSize = 1024 * 4; @@ -22,11 +32,22 @@ public class MultipartReader private readonly MultipartBoundary _boundary; private MultipartReaderStream _currentStream; + /// + /// Initializes a new instance of . + /// + /// The multipart boundary. + /// The containing multipart data. public MultipartReader(string boundary, Stream stream) : this(boundary, stream, DefaultBufferSize) { } + /// + /// Initializes a new instance of . + /// + /// The multipart boundary. + /// The containing multipart data. + /// The minimum buffer size to use. public MultipartReader(string boundary, Stream stream, int bufferSize) { if (boundary == null) @@ -65,6 +86,12 @@ public MultipartReader(string boundary, Stream stream, int bufferSize) /// public long? BodyLengthLimit { get; set; } + /// + /// Reads the next . + /// + /// The token to monitor for cancellation requests. + /// The default value is . + /// public async Task ReadNextSectionAsync(CancellationToken cancellationToken = new CancellationToken()) { // Drain the prior section. diff --git a/src/Http/WebUtilities/src/MultipartSection.cs b/src/Http/WebUtilities/src/MultipartSection.cs index 793bb04253ae..2b5b5073f24a 100644 --- a/src/Http/WebUtilities/src/MultipartSection.cs +++ b/src/Http/WebUtilities/src/MultipartSection.cs @@ -8,8 +8,14 @@ namespace Microsoft.AspNetCore.WebUtilities { + /// + /// A multipart section read by . + /// public class MultipartSection { + /// + /// Gets the value of the Content-Type header. + /// public string? ContentType { get @@ -22,6 +28,9 @@ public string? ContentType } } + /// + /// Gets the value of the Content-Disposition header. + /// public string? ContentDisposition { get @@ -34,6 +43,9 @@ public string? ContentDisposition } } + /// + /// Gets or sets the multipart header collection. + /// public Dictionary? Headers { get; set; } /// diff --git a/src/Http/WebUtilities/src/ReasonPhrases.cs b/src/Http/WebUtilities/src/ReasonPhrases.cs index 1659bdbcea3f..63f1d6451467 100644 --- a/src/Http/WebUtilities/src/ReasonPhrases.cs +++ b/src/Http/WebUtilities/src/ReasonPhrases.cs @@ -5,10 +5,14 @@ namespace Microsoft.AspNetCore.WebUtilities { + /// + /// Provides access to HTTP status code reason phrases as listed in + /// http://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml. + /// public static class ReasonPhrases { // Status Codes listed at http://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml - private static IDictionary Phrases = new Dictionary() + private static readonly Dictionary Phrases = new() { { 100, "Continue" }, { 101, "Switching Protocols" }, @@ -78,6 +82,11 @@ public static class ReasonPhrases { 511, "Network Authentication Required" }, }; + /// + /// Gets the reason phrase for the specified status code. + /// + /// The status code. + /// The reason phrase, or if the status code is unknown. public static string GetReasonPhrase(int statusCode) { return Phrases.TryGetValue(statusCode, out var phrase) ? phrase : string.Empty; diff --git a/src/Http/WebUtilities/src/StreamHelperExtensions.cs b/src/Http/WebUtilities/src/StreamHelperExtensions.cs index f4ec558aaa6e..cc12b951e549 100644 --- a/src/Http/WebUtilities/src/StreamHelperExtensions.cs +++ b/src/Http/WebUtilities/src/StreamHelperExtensions.cs @@ -8,20 +8,53 @@ namespace Microsoft.AspNetCore.WebUtilities { + /// + /// HTTP extension methods for . + /// public static class StreamHelperExtensions { private const int _maxReadBufferSize = 1024 * 4; + /// + /// Reads the specified to the end. + /// + /// This API is effective when used in conjunction with buffering. It allows + /// a buffered request stream to be synchronously read after it has been completely drained. + /// + /// + /// The to completely read. + /// The token to monitor for cancellation requests. public static Task DrainAsync(this Stream stream, CancellationToken cancellationToken) { return stream.DrainAsync(ArrayPool.Shared, null, cancellationToken); } + /// + /// Reads the specified to the end. + /// + /// This API is effective when used in conjunction with buffering. It allows + /// a buffered request stream to be synchronously read after it has been completely drained. + /// + /// + /// The to completely read. + /// The maximum number of bytes to read. Throws if the is larger than this limit. + /// The token to monitor for cancellation requests. public static Task DrainAsync(this Stream stream, long? limit, CancellationToken cancellationToken) { return stream.DrainAsync(ArrayPool.Shared, limit, cancellationToken); } + /// + /// Reads the specified to the end. + /// + /// This API is effective when used in conjunction with buffering. It allows + /// a buffered request stream to be synchronously read after it has been completely drained. + /// + /// + /// The to completely read. + /// The byte array pool to use. + /// The maximum number of bytes to read. Throws if the is larger than this limit. + /// The token to monitor for cancellation requests. public static async Task DrainAsync(this Stream stream, ArrayPool bytePool, long? limit, CancellationToken cancellationToken) { cancellationToken.ThrowIfCancellationRequested(); @@ -48,4 +81,4 @@ public static async Task DrainAsync(this Stream stream, ArrayPool bytePool } } } -} \ No newline at end of file +} diff --git a/src/JSInterop/Microsoft.JSInterop/src/JSInProcessObjectReferenceExtensions.cs b/src/JSInterop/Microsoft.JSInterop/src/JSInProcessObjectReferenceExtensions.cs index 57b9cc66fe46..ad4294095770 100644 --- a/src/JSInterop/Microsoft.JSInterop/src/JSInProcessObjectReferenceExtensions.cs +++ b/src/JSInterop/Microsoft.JSInterop/src/JSInProcessObjectReferenceExtensions.cs @@ -5,6 +5,9 @@ namespace Microsoft.JSInterop { + /// + /// Extension methods for . + /// public static class JSInProcessObjectReferenceExtensions { /// diff --git a/src/JSInterop/Microsoft.JSInterop/src/Microsoft.JSInterop.csproj b/src/JSInterop/Microsoft.JSInterop/src/Microsoft.JSInterop.csproj index 732502e4fff0..15af621cda2d 100644 --- a/src/JSInterop/Microsoft.JSInterop/src/Microsoft.JSInterop.csproj +++ b/src/JSInterop/Microsoft.JSInterop/src/Microsoft.JSInterop.csproj @@ -6,7 +6,6 @@ javascript;interop true true - $(NoWarn);CS1591 enable diff --git a/src/ObjectPool/src/DefaultObjectPool.cs b/src/ObjectPool/src/DefaultObjectPool.cs index be514c0e633f..8fb9a40de180 100644 --- a/src/ObjectPool/src/DefaultObjectPool.cs +++ b/src/ObjectPool/src/DefaultObjectPool.cs @@ -55,6 +55,7 @@ bool IsDefaultPolicy() } } + /// public override T Get() { var item = _firstItem; @@ -80,6 +81,7 @@ public override T Get() [MethodImpl(MethodImplOptions.NoInlining)] private T Create() => _fastPolicy?.Create() ?? _policy.Create(); + /// public override void Return(T obj) { if (_isDefaultPolicy || (_fastPolicy?.Return(obj) ?? _policy.Return(obj))) diff --git a/src/ObjectPool/src/DefaultPooledObjectPolicy.cs b/src/ObjectPool/src/DefaultPooledObjectPolicy.cs index a7c386ae2a88..892f7adab16e 100644 --- a/src/ObjectPool/src/DefaultPooledObjectPolicy.cs +++ b/src/ObjectPool/src/DefaultPooledObjectPolicy.cs @@ -1,19 +1,25 @@ -// Copyright (c) .NET Foundation. All rights reserved. +// Copyright (c) .NET Foundation. All rights reserved. // Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information. namespace Microsoft.Extensions.ObjectPool { + /// + /// Default implementation for . + /// + /// The type of object which is being pooled. public class DefaultPooledObjectPolicy : PooledObjectPolicy where T : class, new() { + /// public override T Create() { return new T(); } - // DefaultObjectPool doesn't call 'Return' for the default policy. - // So take care adding any logic to this method, as it might require changes elsewhere. + /// public override bool Return(T obj) { + // DefaultObjectPool doesn't call 'Return' for the default policy. + // So take care adding any logic to this method, as it might require changes elsewhere. return true; } } diff --git a/src/ObjectPool/src/LeakTrackingObjectPool.cs b/src/ObjectPool/src/LeakTrackingObjectPool.cs index 4bae02babc93..2740fa1d6f78 100644 --- a/src/ObjectPool/src/LeakTrackingObjectPool.cs +++ b/src/ObjectPool/src/LeakTrackingObjectPool.cs @@ -7,11 +7,24 @@ namespace Microsoft.Extensions.ObjectPool { + /// + /// An implementation that detects leaks in the use of the object pool. + /// + /// A leak is produced if an object is leased from the pool but not returned before it is finalized. + /// An error is only produced in Debug builds. + /// This type is only recommended to be used for diagnostc builds. + /// + /// + /// The type of object which is being pooled. public class LeakTrackingObjectPool : ObjectPool where T : class { private readonly ConditionalWeakTable _trackers = new ConditionalWeakTable(); private readonly ObjectPool _inner; + /// + /// Initializes a new instance of . + /// + /// The instance to track leaks in. public LeakTrackingObjectPool(ObjectPool inner) { if (inner == null) @@ -22,6 +35,7 @@ public LeakTrackingObjectPool(ObjectPool inner) _inner = inner; } + /// public override T Get() { var value = _inner.Get(); @@ -29,6 +43,7 @@ public override T Get() return value; } + /// public override void Return(T obj) { if (_trackers.TryGetValue(obj, out var tracker)) diff --git a/src/ObjectPool/src/LeakTrackingObjectPoolProvider.cs b/src/ObjectPool/src/LeakTrackingObjectPoolProvider.cs index 134eaf161c31..cf9d79682d43 100644 --- a/src/ObjectPool/src/LeakTrackingObjectPoolProvider.cs +++ b/src/ObjectPool/src/LeakTrackingObjectPoolProvider.cs @@ -1,14 +1,22 @@ -// Copyright (c) .NET Foundation. All rights reserved. +// Copyright (c) .NET Foundation. All rights reserved. // Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information. using System; namespace Microsoft.Extensions.ObjectPool { + /// + /// An that produces instances of + /// . + /// public class LeakTrackingObjectPoolProvider : ObjectPoolProvider { private readonly ObjectPoolProvider _inner; + /// + /// Initializes a new instance of . + /// + /// The to wrap. public LeakTrackingObjectPoolProvider(ObjectPoolProvider inner) { if (inner == null) @@ -19,6 +27,7 @@ public LeakTrackingObjectPoolProvider(ObjectPoolProvider inner) _inner = inner; } + /// public override ObjectPool Create(IPooledObjectPolicy policy) { var inner = _inner.Create(policy); diff --git a/src/ObjectPool/src/Microsoft.Extensions.ObjectPool.csproj b/src/ObjectPool/src/Microsoft.Extensions.ObjectPool.csproj index b2f3e690e35b..ab96bc0facee 100644 --- a/src/ObjectPool/src/Microsoft.Extensions.ObjectPool.csproj +++ b/src/ObjectPool/src/Microsoft.Extensions.ObjectPool.csproj @@ -3,7 +3,6 @@ A simple object pool implementation. $(DefaultNetFxTargetFramework);netstandard2.0;$(DefaultNetCoreTargetFramework) - $(NoWarn);CS1591 true pooling true diff --git a/src/ObjectPool/src/ObjectPoolProviderExtensions.cs b/src/ObjectPool/src/ObjectPoolProviderExtensions.cs index b9e93598894f..f2ef3224bdee 100644 --- a/src/ObjectPool/src/ObjectPoolProviderExtensions.cs +++ b/src/ObjectPool/src/ObjectPoolProviderExtensions.cs @@ -1,17 +1,33 @@ -// Copyright (c) .NET Foundation. All rights reserved. +// Copyright (c) .NET Foundation. All rights reserved. // Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information. using System.Text; namespace Microsoft.Extensions.ObjectPool { + /// + /// Extension methods for . + /// public static class ObjectPoolProviderExtensions { + /// + /// Creates an that pools instances. + /// + /// The . + /// The . public static ObjectPool CreateStringBuilderPool(this ObjectPoolProvider provider) { return provider.Create(new StringBuilderPooledObjectPolicy()); } + /// + /// Creates an that pools instances. + /// + /// The . + /// The initial capacity to initiaize instances with. + /// The maximum value for that is allowed to be + /// retained, when an instance is returned. + /// The . public static ObjectPool CreateStringBuilderPool( this ObjectPoolProvider provider, int initialCapacity, diff --git a/src/ObjectPool/src/PooledObjectPolicy.cs b/src/ObjectPool/src/PooledObjectPolicy.cs index c1dbd72d0c1d..538b1c124ce9 100644 --- a/src/ObjectPool/src/PooledObjectPolicy.cs +++ b/src/ObjectPool/src/PooledObjectPolicy.cs @@ -1,12 +1,18 @@ -// Copyright (c) .NET Foundation. All rights reserved. +// Copyright (c) .NET Foundation. All rights reserved. // Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information. namespace Microsoft.Extensions.ObjectPool { + /// + /// A base type for . + /// + /// The type of object which is being pooled. public abstract class PooledObjectPolicy : IPooledObjectPolicy where T : notnull { + /// public abstract T Create(); + /// public abstract bool Return(T obj); } } diff --git a/src/ObjectPool/src/StringBuilderPooledObjectPolicy.cs b/src/ObjectPool/src/StringBuilderPooledObjectPolicy.cs index 94f318729a74..a051c0496c5b 100644 --- a/src/ObjectPool/src/StringBuilderPooledObjectPolicy.cs +++ b/src/ObjectPool/src/StringBuilderPooledObjectPolicy.cs @@ -1,21 +1,35 @@ -// Copyright (c) .NET Foundation. All rights reserved. +// Copyright (c) .NET Foundation. All rights reserved. // Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information. using System.Text; namespace Microsoft.Extensions.ObjectPool { + /// + /// A policy for pooling instances. + /// public class StringBuilderPooledObjectPolicy : PooledObjectPolicy { + /// + /// Gets or sets the initial capacity of pooled instances. + /// + /// Defaults to 100. public int InitialCapacity { get; set; } = 100; + /// + /// Gets or sets the maximum value for that is allowed to be + /// retained, when is invoked. + /// + /// Defaults to 4096. public int MaximumRetainedCapacity { get; set; } = 4 * 1024; + /// public override StringBuilder Create() { return new StringBuilder(InitialCapacity); } + /// public override bool Return(StringBuilder obj) { if (obj.Capacity > MaximumRetainedCapacity)