From d8fdf2c4a74946a70c39038032c674add8dc5717 Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Fri, 17 Oct 2025 11:41:09 -0700 Subject: [PATCH] doc updates --- .../SqlServer/src/SqlServerCacheOptions.cs | 21 +++++++++----- .../PollyHttpClientBuilderExtensions.cs | 22 +++++++------- ...AzureAppServicesLoggerFactoryExtensions.cs | 4 +-- .../src/AzureBlobLoggerContext.cs | 10 +++---- .../src/AzureBlobLoggerOptions.cs | 10 +++++-- .../src/AzureFileLoggerOptions.cs | 29 +++++++++++++------ .../src/BatchingLoggerOptions.cs | 24 ++++++++++----- .../src/BatchingLoggerProvider.cs | 8 ++--- .../src/FileLoggerProvider.cs | 4 +-- .../src/IValidatableInfoResolver.cs | 8 ++--- src/Validation/src/SkipValidationAttribute.cs | 6 ++-- src/Validation/src/ValidateContext.cs | 14 ++++++--- src/Validation/src/ValidationOptions.cs | 20 ++++++++----- 13 files changed, 110 insertions(+), 70 deletions(-) diff --git a/src/Caching/SqlServer/src/SqlServerCacheOptions.cs b/src/Caching/SqlServer/src/SqlServerCacheOptions.cs index 6885696027cf..8ec41a458932 100644 --- a/src/Caching/SqlServer/src/SqlServerCacheOptions.cs +++ b/src/Caching/SqlServer/src/SqlServerCacheOptions.cs @@ -8,39 +8,44 @@ namespace Microsoft.Extensions.Caching.SqlServer; /// -/// Configuration options for . +/// Represents configuration options for . /// public class SqlServerCacheOptions : IOptions { /// - /// An abstraction to represent the clock of a machine in order to enable unit testing. + /// Gets or sets an abstraction to represent the clock of a machine in order to enable unit testing. /// public ISystemClock SystemClock { get; set; } = new SystemClock(); /// - /// The periodic interval to scan and delete expired items in the cache. Default is 30 minutes. + /// Gets or sets the periodic interval to scan and delete expired items in the cache. Default is 30 minutes. /// + /// + /// The periodic interval to scan and delete expired items in the cache. The default is 30 minutes. + /// public TimeSpan? ExpiredItemsDeletionInterval { get; set; } /// - /// The connection string to the database. + /// Gets or sets the connection string to the database. /// public string? ConnectionString { get; set; } /// - /// The schema name of the table. + /// Gets or sets the schema name of the table. /// public string? SchemaName { get; set; } /// - /// Name of the table where the cache items are stored. + /// Gets or sets the name of the table where the cache items are stored. /// public string? TableName { get; set; } /// - /// The default sliding expiration set for a cache entry if neither Absolute or SlidingExpiration has been set explicitly. - /// By default, its 20 minutes. + /// Gets or sets the default sliding expiration set for a cache entry if neither Absolute or SlidingExpiration has been set explicitly. /// + /// + /// The default is 20 minutes. + /// public TimeSpan DefaultSlidingExpiration { get; set; } = TimeSpan.FromMinutes(20); SqlServerCacheOptions IOptions.Value diff --git a/src/HttpClientFactory/Polly/src/DependencyInjection/PollyHttpClientBuilderExtensions.cs b/src/HttpClientFactory/Polly/src/DependencyInjection/PollyHttpClientBuilderExtensions.cs index 777412480336..019813bead09 100644 --- a/src/HttpClientFactory/Polly/src/DependencyInjection/PollyHttpClientBuilderExtensions.cs +++ b/src/HttpClientFactory/Polly/src/DependencyInjection/PollyHttpClientBuilderExtensions.cs @@ -11,13 +11,13 @@ namespace Microsoft.Extensions.DependencyInjection; /// -/// Extensions methods for configuring message handlers as part of +/// Provides extensions methods for configuring message handlers as part of /// and message handler pipeline. /// public static class PollyHttpClientBuilderExtensions { /// - /// Adds a which will surround request execution with the provided + /// Adds a that will surround request execution with the provided /// . /// /// The . @@ -45,7 +45,7 @@ public static IHttpClientBuilder AddPolicyHandler(this IHttpClientBuilder builde } /// - /// Adds a which will surround request execution with a policy returned + /// Adds a that will surround request execution with a policy returned /// by the . /// /// The . @@ -77,7 +77,7 @@ public static IHttpClientBuilder AddPolicyHandler( } /// - /// Adds a which will surround request execution with a policy returned + /// Adds a that will surround request execution with a policy returned /// by the . /// /// The . @@ -112,7 +112,7 @@ public static IHttpClientBuilder AddPolicyHandler( } /// - /// Adds a which will surround request execution with a policy returned + /// Adds a that will surround request execution with a policy returned /// by the . /// /// The . @@ -149,7 +149,7 @@ public static IHttpClientBuilder AddPolicyHandlerFromRegistry(this IHttpClientBu } /// - /// Adds a which will surround request execution with a policy returned + /// Adds a that will surround request execution with a policy returned /// by the . /// /// The . @@ -185,7 +185,7 @@ public static IHttpClientBuilder AddPolicyHandlerFromRegistry( } /// - /// Adds a which will surround request execution with a + /// Adds a that will surround request execution with a /// created by executing the provided configuration delegate. The policy builder will be preconfigured to trigger /// application of the policy for requests that fail with conditions that indicate a transient failure. /// @@ -207,8 +207,8 @@ public static IHttpClientBuilder AddPolicyHandlerFromRegistry( /// /// /// The policy created by will be cached indefinitely per named client. Policies - /// are generally designed to act as singletons, and can be shared when appropriate. To share a policy across multiple - /// named clients, first create the policy and then pass it to multiple calls to + /// are generally designed to act as singletons and can be shared when appropriate. To share a policy across multiple + /// named clients, first create the policy and then pass it to multiple calls to /// as desired. /// /// @@ -236,8 +236,8 @@ public static IHttpClientBuilder AddTransientHttpErrorPolicy( } /// - /// Adds a which will surround request execution with a policy returned - /// by executing provided key selection logic and + /// Adds a that will surround request execution with a policy returned + /// by executing provided key selection logic and . /// /// The . /// Selects an to apply to the current request based on key selection. diff --git a/src/Logging.AzureAppServices/src/AzureAppServicesLoggerFactoryExtensions.cs b/src/Logging.AzureAppServices/src/AzureAppServicesLoggerFactoryExtensions.cs index 360bf0f0d8d8..f91731bf94cd 100644 --- a/src/Logging.AzureAppServices/src/AzureAppServicesLoggerFactoryExtensions.cs +++ b/src/Logging.AzureAppServices/src/AzureAppServicesLoggerFactoryExtensions.cs @@ -13,14 +13,14 @@ namespace Microsoft.Extensions.Logging; /// -/// Extension methods for adding Azure diagnostics logger. +/// Provides extension methods for adding Azure diagnostics logger. /// public static class AzureAppServicesLoggerFactoryExtensions { /// /// Adds an Azure Web Apps diagnostics logger. /// - /// The extension method argument + /// The extension method argument. /// public static ILoggingBuilder AddAzureWebAppDiagnostics(this ILoggingBuilder builder) { diff --git a/src/Logging.AzureAppServices/src/AzureBlobLoggerContext.cs b/src/Logging.AzureAppServices/src/AzureBlobLoggerContext.cs index a59036cdbb4d..3cb8d888ec82 100644 --- a/src/Logging.AzureAppServices/src/AzureBlobLoggerContext.cs +++ b/src/Logging.AzureAppServices/src/AzureBlobLoggerContext.cs @@ -6,12 +6,12 @@ namespace Microsoft.Extensions.Logging.AzureAppServices; /// -/// The context containing details for formatting the file name for the azure blob logger. +/// Represents the context containing details for formatting the file name for the Azure blob logger. /// public readonly struct AzureBlobLoggerContext { /// - /// Create a new . + /// Creates a new . /// /// The app name. /// The file identifier. @@ -24,17 +24,17 @@ public AzureBlobLoggerContext(string appName, string identifier, DateTimeOffset } /// - /// The name of the application. + /// Gets the name of the application. /// public string AppName { get; } /// - /// The identifier for the log. This value is set to "_". + /// Gets the identifier for the log. This value is set to "_". /// public string Identifier { get; } /// - /// The timestamp representing when the log was created. + /// Gets the timestamp representing when the log was created. /// public DateTimeOffset Timestamp { get; } } diff --git a/src/Logging.AzureAppServices/src/AzureBlobLoggerOptions.cs b/src/Logging.AzureAppServices/src/AzureBlobLoggerOptions.cs index c42bb4bfc17f..767cac7f7e59 100644 --- a/src/Logging.AzureAppServices/src/AzureBlobLoggerOptions.cs +++ b/src/Logging.AzureAppServices/src/AzureBlobLoggerOptions.cs @@ -7,7 +7,7 @@ namespace Microsoft.Extensions.Logging.AzureAppServices; /// -/// Options for Azure diagnostics blob logging. +/// Specifies options for Azure diagnostics blob logging. /// public class AzureBlobLoggerOptions : BatchingLoggerOptions { @@ -15,8 +15,10 @@ public class AzureBlobLoggerOptions : BatchingLoggerOptions /// /// Gets or sets the last section of log blob name. - /// Defaults to "applicationLog.txt". /// + /// + /// The last section of the log blob name. The default is "applicationLog.txt". + /// public string BlobName { get { return _blobName; } @@ -29,8 +31,10 @@ public string BlobName /// /// Gets or sets the format of the file name. - /// Defaults to "AppName/Year/Month/Day/Hour/Identifier". /// + /// + /// The format of the file name. The default is "AppName/Year/Month/Day/Hour/Identifier". + /// public Func FileNameFormat { get; set; } = context => { var timestamp = context.Timestamp; diff --git a/src/Logging.AzureAppServices/src/AzureFileLoggerOptions.cs b/src/Logging.AzureAppServices/src/AzureFileLoggerOptions.cs index f8beb284b335..5fcc845ac3b6 100644 --- a/src/Logging.AzureAppServices/src/AzureFileLoggerOptions.cs +++ b/src/Logging.AzureAppServices/src/AzureFileLoggerOptions.cs @@ -7,7 +7,7 @@ namespace Microsoft.Extensions.Logging.AzureAppServices; /// -/// Options for Azure diagnostics file logging. +/// Specifies options for Azure diagnostics file logging. /// public class AzureFileLoggerOptions : BatchingLoggerOptions { @@ -16,10 +16,15 @@ public class AzureFileLoggerOptions : BatchingLoggerOptions private string _fileName = "diagnostics-"; /// - /// Gets or sets a strictly positive value representing the maximum log size in bytes or null for no limit. - /// Once the log is full, no more messages will be appended. - /// Defaults to 10MB. + /// Gets or sets a strictly positive value representing the maximum log size in bytes, or null for no limit. /// + /// + /// The maximum log size in bytes, or for no limit. + /// The default is 10 MB. + /// + /// + /// Once the log is full, no more messages are appended. + /// public int? FileSizeLimit { get { return _fileSizeLimit; } @@ -34,9 +39,12 @@ public int? FileSizeLimit } /// - /// Gets or sets a strictly positive value representing the maximum retained file count or null for no limit. - /// Defaults to 2. + /// Gets or sets a strictly positive value representing the maximum retained file count. /// + /// + /// The maximum retained file count, or for no limit. + /// The default is 2. + /// public int? RetainedFileCountLimit { get { return _retainedFileCountLimit; } @@ -51,10 +59,13 @@ public int? RetainedFileCountLimit } /// - /// Gets or sets a string representing the prefix of the file name used to store the logging information. - /// The current date, in the format YYYYMMDD will be added after the given value. - /// Defaults to diagnostics-. + /// Gets or sets the prefix of the file name used to store the logging information. + /// The current date, in the format YYYYMMDD, is added after this value. /// + /// + /// The prefix of the file name used to store the logging information. + /// The default is diagnostics-. + /// public string FileName { get { return _fileName; } diff --git a/src/Logging.AzureAppServices/src/BatchingLoggerOptions.cs b/src/Logging.AzureAppServices/src/BatchingLoggerOptions.cs index 67d6e60f3b69..d9a3c66930a8 100644 --- a/src/Logging.AzureAppServices/src/BatchingLoggerOptions.cs +++ b/src/Logging.AzureAppServices/src/BatchingLoggerOptions.cs @@ -6,7 +6,7 @@ namespace Microsoft.Extensions.Logging.AzureAppServices; /// -/// Options for a logger which batches up log messages. +/// Specifies options for a logger that batches log messages. /// public class BatchingLoggerOptions { @@ -31,10 +31,14 @@ public TimeSpan FlushPeriod } /// - /// Gets or sets the maximum size of the background log message queue or null for no limit. - /// After maximum queue size is reached log event sink would start blocking. - /// Defaults to 1000. + /// Gets or sets the maximum size of the background log message queue, or null for no limit. /// + /// + /// The maximum size of the background log message queue, or for no limit. The default is 1000. + /// + /// + /// After the maximum queue size is reached, the log event sink starts blocking. + /// public int? BackgroundQueueSize { get { return _backgroundQueueSize; } @@ -49,9 +53,11 @@ public int? BackgroundQueueSize } /// - /// Gets or sets a maximum number of events to include in a single batch or null for no limit. + /// Gets or sets the maximum number of events to include in a single batch. /// - /// Defaults to null. + /// + /// The maximum number of events to include in a single batch, or for no limit. The default is . + /// public int? BatchSize { get { return _batchSize; } @@ -66,13 +72,15 @@ public int? BatchSize } /// - /// Gets or sets value indicating if logger accepts and queues writes. + /// Gets or sets a value indicating whether the logger accepts and queues writes. /// public bool IsEnabled { get; set; } /// /// Gets or sets a value indicating whether scopes should be included in the message. - /// Defaults to false. /// + /// + /// The default is . + /// public bool IncludeScopes { get; set; } } diff --git a/src/Logging.AzureAppServices/src/BatchingLoggerProvider.cs b/src/Logging.AzureAppServices/src/BatchingLoggerProvider.cs index 40fcc93e3904..70cf516013b2 100644 --- a/src/Logging.AzureAppServices/src/BatchingLoggerProvider.cs +++ b/src/Logging.AzureAppServices/src/BatchingLoggerProvider.cs @@ -11,7 +11,7 @@ namespace Microsoft.Extensions.Logging.AzureAppServices; /// -/// A provider of instances. +/// Represents a provider of instances. /// public abstract class BatchingLoggerProvider : ILoggerProvider, ISupportExternalScope { @@ -59,7 +59,7 @@ internal BatchingLoggerProvider(IOptionsMonitor options) } /// - /// Checks if the queue is enabled. + /// Gets a value that indicates whether the queue is enabled. /// public bool IsEnabled { get; private set; } @@ -124,11 +124,11 @@ private async Task ProcessLogQueue() } /// - /// Wait for the given . + /// Waits for the given . /// /// The amount of time to wait. /// A that can be used to cancel the delay. - /// A which completes when the has passed or the has been canceled. + /// A that completes when the has passed or the has been canceled. protected virtual Task IntervalAsync(TimeSpan interval, CancellationToken cancellationToken) { return Task.Delay(interval, cancellationToken); diff --git a/src/Logging.AzureAppServices/src/FileLoggerProvider.cs b/src/Logging.AzureAppServices/src/FileLoggerProvider.cs index 8291b8520c40..25ab016b71df 100644 --- a/src/Logging.AzureAppServices/src/FileLoggerProvider.cs +++ b/src/Logging.AzureAppServices/src/FileLoggerProvider.cs @@ -12,7 +12,7 @@ namespace Microsoft.Extensions.Logging.AzureAppServices; /// -/// A which writes out to a file. +/// Represents a that writes out to a file. /// [ProviderAlias("AzureAppServicesFile")] public class FileLoggerProvider : BatchingLoggerProvider @@ -25,7 +25,7 @@ public class FileLoggerProvider : BatchingLoggerProvider /// /// Creates a new instance of . /// - /// The options to use when creating a provider. + /// The options to use when creating the provider. [SuppressMessage("ApiDesign", "RS0022:Constructor make noninheritable base class inheritable", Justification = "Required for backwards compatibility")] public FileLoggerProvider(IOptionsMonitor options) : base(options) { diff --git a/src/Validation/src/IValidatableInfoResolver.cs b/src/Validation/src/IValidatableInfoResolver.cs index 706204ab6284..96b672647daa 100644 --- a/src/Validation/src/IValidatableInfoResolver.cs +++ b/src/Validation/src/IValidatableInfoResolver.cs @@ -18,16 +18,16 @@ public interface IValidatableInfoResolver /// /// The type to get validation information for. /// - /// The output parameter that will contain the validatable information if found. + /// When this method returns, contains the validatable information if found. /// - /// if the validatable type information was found; otherwise, false. + /// if the validatable type information was found; otherwise, . bool TryGetValidatableTypeInfo(Type type, [NotNullWhen(true)] out IValidatableInfo? validatableInfo); /// /// Gets validation information for the specified parameter. /// /// The parameter to get validation information for. - /// The output parameter that will contain the validatable information if found. - /// if the validatable parameter information was found; otherwise, false. + /// When this method returns, contains the validatable information if found. + /// if the validatable parameter information was found; otherwise, . bool TryGetValidatableParameterInfo(ParameterInfo parameterInfo, [NotNullWhen(true)] out IValidatableInfo? validatableInfo); } diff --git a/src/Validation/src/SkipValidationAttribute.cs b/src/Validation/src/SkipValidationAttribute.cs index ddbb2f56531e..9e2e95572ffb 100644 --- a/src/Validation/src/SkipValidationAttribute.cs +++ b/src/Validation/src/SkipValidationAttribute.cs @@ -6,12 +6,14 @@ namespace Microsoft.Extensions.Validation; /// -/// Indicates that a property, parameter, or a type should not be validated. +/// Indicates that a property, parameter, or type should not be validated. +/// +/// /// When applied to a property, validation is skipped for that property. /// When applied to a parameter, validation is skipped for that parameter. /// When applied to a type, validation is skipped for all properties and parameters of that type. /// This includes skipping validation of nested properties for complex types. -/// +/// [Experimental("ASP0029", UrlFormat = "https://aka.ms/aspnet/analyzer/{0}")] [AttributeUsage(AttributeTargets.Class | AttributeTargets.Property | AttributeTargets.Parameter, AllowMultiple = false, Inherited = true)] public sealed class SkipValidationAttribute : Attribute diff --git a/src/Validation/src/ValidateContext.cs b/src/Validation/src/ValidateContext.cs index 5cce279c4be9..d200e3353a92 100644 --- a/src/Validation/src/ValidateContext.cs +++ b/src/Validation/src/ValidateContext.cs @@ -23,7 +23,7 @@ public sealed class ValidateContext /// the complete set of validation scenarios. /// /// - /// + /// /// var validationContext = new ValidationContext(objectToValidate, serviceProvider, items); /// var validationOptions = serviceProvider.GetService<IOptions<ValidationOptions>>()?.Value; /// var validateContext = new ValidateContext @@ -37,8 +37,10 @@ public sealed class ValidateContext /// /// Gets or sets the prefix used to identify the current object being validated in a complex object graph. - /// This is used to build property paths in validation error messages (e.g., "Customer.Address.Street"). /// + /// + /// This prefix is used to build property paths in validation error messages (for example, "Customer.Address.Street"). + /// public string CurrentValidationPath { get; set; } = string.Empty; /// @@ -49,15 +51,19 @@ public sealed class ValidateContext /// /// Gets or sets the dictionary of validation errors collected during validation. + /// + /// /// Keys are property names or paths, and values are arrays of error messages. /// In the default implementation, this dictionary is initialized when the first error is added. - /// + /// public Dictionary? ValidationErrors { get; set; } /// /// Gets or sets the current depth in the validation hierarchy. - /// This is used to prevent stack overflows from circular references. /// + /// + /// This value is used to prevent stack overflows from circular references. + /// public int CurrentDepth { get; set; } /// diff --git a/src/Validation/src/ValidationOptions.cs b/src/Validation/src/ValidationOptions.cs index 13729b5f124a..0684a1f535cd 100644 --- a/src/Validation/src/ValidationOptions.cs +++ b/src/Validation/src/ValidationOptions.cs @@ -7,13 +7,13 @@ namespace Microsoft.Extensions.Validation; /// -/// Provides configuration options for the validation system. +/// Specifies configuration options for the validation system. /// public class ValidationOptions { /// /// Gets the list of resolvers that provide validation metadata for types and parameters. - /// Resolvers are processed in order, with the first resolver providing a non-null result being used. + /// Resolvers are processed in order, with the first resolver that provides a non-null result being used. /// /// /// Source-generated resolvers are typically inserted at the beginning of this list @@ -24,9 +24,13 @@ public class ValidationOptions /// /// Gets or sets the maximum depth for validation of nested objects. - /// This prevents stack overflows from circular references or extremely deep object graphs. - /// Default value is 32. /// + /// + /// The default is 32. + /// + /// + /// A maximum depth prevents stack overflows from circular references or extremely deep object graphs. + /// public int MaxDepth { get; set; } = 32; /// @@ -34,8 +38,8 @@ public class ValidationOptions /// /// The type to get validation information for. /// When this method returns, contains the validation information for the specified type, - /// if the type was found; otherwise, null. - /// true if validation information was found for the specified type; otherwise, false. + /// if the type was found; otherwise, . + /// if validation information was found for the specified type; otherwise, . [Experimental("ASP0029", UrlFormat = "https://aka.ms/aspnet/analyzer/{0}")] public bool TryGetValidatableTypeInfo(Type type, [NotNullWhen(true)] out IValidatableInfo? validatableTypeInfo) { @@ -56,8 +60,8 @@ public bool TryGetValidatableTypeInfo(Type type, [NotNullWhen(true)] out IValida /// /// The parameter to get validation information for. /// When this method returns, contains the validation information for the specified parameter, - /// if validation information was found; otherwise, null. - /// true if validation information was found for the specified parameter; otherwise, false. + /// if validation information was found; otherwise, . + /// if validation information was found for the specified parameter; otherwise, . [Experimental("ASP0029", UrlFormat = "https://aka.ms/aspnet/analyzer/{0}")] public bool TryGetValidatableParameterInfo(ParameterInfo parameterInfo, [NotNullWhen(true)] out IValidatableInfo? validatableInfo) {