From cee7ed3adc359769821ab7752b3b9762f32b8f99 Mon Sep 17 00:00:00 2001 From: Rikitav Date: Fri, 8 Aug 2025 17:15:57 +0400 Subject: [PATCH] Added missing XML summaries --- .../Components/UpdateHandlerAttributeBase.cs | 21 +- .../Components/AnonymousCompiledFilter.cs | 9 +- .../Filters/Components/AnonymousTypeFilter.cs | 9 +- .../Filters/Components/CompiledFilter.cs | 7 +- Telegrator/Filters/Components/IFilter.cs | 6 + .../Handlers/Building/AwaiterHandler.cs | 11 +- .../Components/FiltersFallbackReport.cs | 56 +++ .../Descriptors/HandlerDescriptor.cs | 371 ++++++++++-------- 8 files changed, 302 insertions(+), 188 deletions(-) diff --git a/Telegrator/Attributes/Components/UpdateHandlerAttributeBase.cs b/Telegrator/Attributes/Components/UpdateHandlerAttributeBase.cs index c765d8b..bdfd8e6 100644 --- a/Telegrator/Attributes/Components/UpdateHandlerAttributeBase.cs +++ b/Telegrator/Attributes/Components/UpdateHandlerAttributeBase.cs @@ -35,17 +35,20 @@ namespace Telegrator.Attributes.Components /// public int Priority { get; set; } + /// + /// Gets or sets a value indicating whether to form a fallback report for debugging purposes. + /// public bool FormReport { get; set; } /// /// Creates a new instance of /// - /// - /// - /// - /// - /// - /// + /// The types of handlers that this attribute can be applied to. + /// The type of update that this handler processes. + /// The importance level of this handler (default: 0). + /// Thrown when is null. + /// Thrown when one of the handler types is not a valid handler type. + /// Thrown when is . protected internal UpdateHandlerAttributeBase(Type[] expectingHandlerType, UpdateType updateType, int importance = 0) { if (expectingHandlerType == null) @@ -65,15 +68,15 @@ namespace Telegrator.Attributes.Components /// /// Gets an of this from and /// - /// + /// A descriptor indexer for this handler attribute. public DescriptorIndexer GetIndexer() => new DescriptorIndexer(0, this); /// /// Validator () of the that will process /// - /// - /// + /// The filter execution context containing the update to validate. + /// True if the update passes validation; otherwise, false. public abstract bool CanPass(FilterExecutionContext context); } } diff --git a/Telegrator/Filters/Components/AnonymousCompiledFilter.cs b/Telegrator/Filters/Components/AnonymousCompiledFilter.cs index 2de7496..7f4727a 100644 --- a/Telegrator/Filters/Components/AnonymousCompiledFilter.cs +++ b/Telegrator/Filters/Components/AnonymousCompiledFilter.cs @@ -12,12 +12,15 @@ namespace Telegrator.Filters.Components private readonly Func GetFilterringTarget; private readonly string _name; + /// + /// Gets the name of this compiled filter. + /// public virtual string Name => _name; /// /// Initializes a new instance of the class. /// - /// + /// The name of the compiled filter. /// The filter action delegate. /// The function to get the filtering target from an update. private AnonymousCompiledFilter(string name, Func getFilterringTarget, Func, object, bool> filterAction) @@ -43,10 +46,10 @@ namespace Telegrator.Filters.Components } /// - /// Compiles a set of filters into an for a specific target type. + /// Compiles a set of filters into an for a specific target type with a custom name. /// /// The type of the filtering target. - /// + /// The custom name for the compiled filter. /// The list of filters to compile. /// The function to get the filtering target from an update. /// The compiled filter. diff --git a/Telegrator/Filters/Components/AnonymousTypeFilter.cs b/Telegrator/Filters/Components/AnonymousTypeFilter.cs index ad13a45..61ca05b 100644 --- a/Telegrator/Filters/Components/AnonymousTypeFilter.cs +++ b/Telegrator/Filters/Components/AnonymousTypeFilter.cs @@ -12,12 +12,15 @@ namespace Telegrator.Filters.Components private readonly Func GetFilterringTarget; private readonly string _name; + /// + /// Gets the name of this filter. + /// public virtual string Name => _name; /// /// Initializes a new instance of the class. /// - /// + /// The name of the filter. /// The filter action delegate. /// The function to get the filtering target from an update. public AnonymousTypeFilter(string name, Func getFilterringTarget, Func, object, bool> filterAction) @@ -43,10 +46,10 @@ namespace Telegrator.Filters.Components } /// - /// Compiles a filter for a specific target type. + /// Compiles a filter for a specific target type with a custom name. /// /// The type of the filtering target. - /// + /// The custom name for the compiled filter. /// The filter to apply. /// The function to get the filtering target from an update. /// The compiled filter. diff --git a/Telegrator/Filters/Components/CompiledFilter.cs b/Telegrator/Filters/Components/CompiledFilter.cs index 51a5dfc..a407db8 100644 --- a/Telegrator/Filters/Components/CompiledFilter.cs +++ b/Telegrator/Filters/Components/CompiledFilter.cs @@ -11,6 +11,9 @@ namespace Telegrator.Filters.Components private readonly IFilter[] Filters; private readonly string _name; + /// + /// Gets the name of this compiled filter. + /// public virtual string Name => _name; /// @@ -24,9 +27,9 @@ namespace Telegrator.Filters.Components } /// - /// Initializes a new instance of the class. + /// Initializes a new instance of the class with a custom name. /// - /// + /// The custom name for the compiled filter. /// The filters to compose. public CompiledFilter(string name, params IFilter[] filters) { diff --git a/Telegrator/Filters/Components/IFilter.cs b/Telegrator/Filters/Components/IFilter.cs index 4b39096..4f6f430 100644 --- a/Telegrator/Filters/Components/IFilter.cs +++ b/Telegrator/Filters/Components/IFilter.cs @@ -1,7 +1,13 @@ namespace Telegrator.Filters.Components { + /// + /// Interface for filters that have a name for identification and debugging purposes. + /// public interface INamedFilter { + /// + /// Gets the name of the filter. + /// public string Name { get; } } diff --git a/Telegrator/Handlers/Building/AwaiterHandler.cs b/Telegrator/Handlers/Building/AwaiterHandler.cs index 24123d6..f9b3acd 100644 --- a/Telegrator/Handlers/Building/AwaiterHandler.cs +++ b/Telegrator/Handlers/Building/AwaiterHandler.cs @@ -1,7 +1,6 @@ using Telegram.Bot.Types; using Telegram.Bot.Types.Enums; using Telegrator.Handlers.Components; -using Telegrator.MadiatorCore; using Telegrator.MadiatorCore.Descriptors; namespace Telegrator.Handlers.Building @@ -56,13 +55,15 @@ namespace Telegrator.Handlers.Building return Task.FromResult(Result.Ok()); } - /// - /// Disposes of the reset event. - /// - public void Dispose() + /// + protected override bool Dispose(bool disposing) { + if (!disposing) + return true; + ResetEvent.Dispose(); ResetEvent = null!; + return true; } } } diff --git a/Telegrator/Handlers/Components/FiltersFallbackReport.cs b/Telegrator/Handlers/Components/FiltersFallbackReport.cs index f5d8bcf..a44cd6e 100644 --- a/Telegrator/Handlers/Components/FiltersFallbackReport.cs +++ b/Telegrator/Handlers/Components/FiltersFallbackReport.cs @@ -6,16 +6,37 @@ using Telegrator.MadiatorCore.Descriptors; namespace Telegrator.Handlers.Components { + /// + /// Represents a report of filter fallback information for debugging and error handling. + /// Contains detailed information about which filters failed and why during handler execution. + /// + /// The handler descriptor that generated this report. + /// The filter execution context. public class FiltersFallbackReport(HandlerDescriptor descriptor, FilterExecutionContext context) { + /// + /// Gets the handler descriptor associated with this fallback report. + /// public HandlerDescriptor Descriptor { get; } = descriptor; + /// + /// Gets the filter execution context that generated this report. + /// public FilterExecutionContext Context { get; } = context; + /// + /// Gets or sets the fallback information for the update validator filter. + /// public FilterFallbackInfo? UpdateValidator { get; set; } + /// + /// Gets or sets the fallback information for the state keeper validator filter. + /// public FilterFallbackInfo? StateKeeperValidator { get; set; } + /// + /// Gets the list of fallback information for update filters that failed. + /// public List UpdateFilters { get; } = []; /* @@ -35,6 +56,12 @@ namespace Telegrator.Handlers.Components } */ + /// + /// Checks if the failure is due to a specific attribute type, excluding other failures. + /// + /// The attribute type to check for. + /// The index of the filter to check (default: 0). + /// True if the failure is exclusively due to the specified attribute type; otherwise, false. public bool ExceptAttribute(int index = 0) where T : UpdateFilterAttributeBase { string name = typeof(T).Name; @@ -46,21 +73,50 @@ namespace Telegrator.Handlers.Components } } + /// + /// Contains information about a filter that failed during execution. + /// Provides details about the filter, its failure status, and any associated exception. + /// + /// The name of the filter. + /// The filter instance that failed. + /// Whether the filter failed. + /// The exception that occurred during filter execution, if any. public class FilterFallbackInfo(string name, IFilter filter, bool failed, Exception? exception) { + /// + /// Gets the name of the filter. + /// public string Name { get; } = name; + /// + /// Gets the filter instance that failed. + /// public IFilter Filter { get; } = filter; + /// + /// Gets a value indicating whether the filter failed. + /// public bool Failed { get; } = failed; + /// + /// Gets the exception that occurred during filter execution, if any. + /// public Exception? Exception { get; } = exception; } + /// + /// Specifies the reason for a filter fallback. + /// public enum FallbackReason { + /// + /// The filter target was null. + /// NullTarget, + /// + /// The filter failed to pass. + /// FailedFilter } } diff --git a/Telegrator/MadiatorCore/Descriptors/HandlerDescriptor.cs b/Telegrator/MadiatorCore/Descriptors/HandlerDescriptor.cs index b66dfb1..63b1321 100644 --- a/Telegrator/MadiatorCore/Descriptors/HandlerDescriptor.cs +++ b/Telegrator/MadiatorCore/Descriptors/HandlerDescriptor.cs @@ -73,6 +73,9 @@ namespace Telegrator.MadiatorCore.Descriptors set; } + /// + /// Gets or sets a value indicating whether to form a fallback report for debugging purposes. + /// public bool FormReport { get; @@ -126,7 +129,8 @@ namespace Telegrator.MadiatorCore.Descriptors } /// - /// Display string for the handler (for debugging or logging). + /// Gets or sets the display string for this handler descriptor. + /// Used for debugging and logging purposes. /// public string? DisplayString { @@ -135,7 +139,8 @@ namespace Telegrator.MadiatorCore.Descriptors } /// - /// Gets or sets a function for 'lazy' handlers initialization + /// Gets or sets the lazy initialization action for this handler. + /// Called when the handler instance needs to be initialized. /// public Action? LazyInitialization { @@ -144,56 +149,60 @@ namespace Telegrator.MadiatorCore.Descriptors } /// - /// Initializes a new instance of the class with the specified descriptor type and handler type. - /// Automatically inspects the handler type to extract attributes, filters, and configuration. + /// Initializes a new instance of the class. /// - /// The type of the descriptor - /// The type of the handler to describe - /// - /// Thrown when the handler type is not compatible with the expected handler type + /// The type of the descriptor. + /// The type of the handler. + /// Whether to skip inspection of the handler type. public HandlerDescriptor(DescriptorType descriptorType, Type handlerType, bool dontInspect = false) { Type = descriptorType; HandlerType = handlerType; - Filters = new DescriptorFiltersSet(null, null, null); + Indexer = new DescriptorIndexer(0, 0, 0); - if (dontInspect) - return; + if (!dontInspect) + { + UpdateHandlerAttributeBase? pollingHandlerAttribute = HandlerInspector.GetPollingHandlerAttribute(handlerType); + if (pollingHandlerAttribute != null) + { + UpdateType = pollingHandlerAttribute.Type; + Indexer = pollingHandlerAttribute.GetIndexer(); + } - UpdateHandlerAttributeBase handlerAttribute = HandlerInspector.GetHandlerAttribute(handlerType); - if (handlerAttribute.ExpectingHandlerType != null && !handlerAttribute.ExpectingHandlerType.Contains(handlerType.BaseType)) - throw new ArgumentException(string.Format("This handler attribute cannot be attached to this class. Attribute can be attached on next handlers : {0}", string.Join(", ", handlerAttribute.ExpectingHandlerType.AsEnumerable()))); + IFilter[]? filters = HandlerInspector.GetFilterAttributes(handlerType, UpdateType).ToArray(); + IFilter? stateKeepFilter = HandlerInspector.GetStateKeeperAttribute(handlerType); + DescriptorAspectsSet? aspects = HandlerInspector.GetAspects(handlerType); - StateKeeperAttributeBase? stateKeeperAttribute = HandlerInspector.GetStateKeeperAttribute(handlerType); - IFilter[] filters = HandlerInspector.GetFilterAttributes(handlerType, handlerAttribute.Type).ToArray(); + if (filters.Length > 0 || stateKeepFilter != null) + { + Filters = new DescriptorFiltersSet(filters ?? [], stateKeepFilter); + } - UpdateType = handlerAttribute.Type; - Indexer = handlerAttribute.GetIndexer(); - FormReport = handlerAttribute.FormReport; - Filters = new DescriptorFiltersSet(handlerAttribute, stateKeeperAttribute, filters); - Aspects = HandlerInspector.GetAspects(handlerType); - DisplayString = HandlerInspector.GetDisplayName(handlerType); + if (aspects != null) + { + Aspects = aspects; + } + } } /// - /// Initializes a new instance of the class as a keyed handler with the specified service key. + /// Initializes a new instance of the class for keyed handlers. /// - /// The type of the handler to describe - /// The service key for dependency injection - /// Thrown when is null + /// The type of the handler. + /// The service key for the handler. public HandlerDescriptor(Type handlerType, object serviceKey) : this(DescriptorType.Keyed, handlerType) { - ServiceKey = serviceKey ?? throw new ArgumentNullException(nameof(serviceKey)); + ServiceKey = serviceKey; } /// - /// Initializes a new instance of the class with all basic properties. + /// Initializes a new instance of the class with complete configuration. /// - /// The type of the descriptor - /// The type of the handler - /// The type of update this handler processes - /// The indexer for handler concurrency and priority - /// The set of filters associated with this handler + /// The type of the descriptor. + /// The type of the handler. + /// The update type handled by this handler. + /// The indexer for handler concurrency and priority. + /// The set of filters associated with this handler. public HandlerDescriptor(DescriptorType type, Type handlerType, UpdateType updateType, DescriptorIndexer indexer, DescriptorFiltersSet filters) { Type = type; @@ -204,16 +213,15 @@ namespace Telegrator.MadiatorCore.Descriptors } /// - /// Initializes a new instance of the class with singleton instance support. + /// Initializes a new instance of the class for singleton handlers. /// - /// The type of the descriptor - /// The type of the handler - /// The type of update this handler processes - /// The indexer for handler concurrency and priority - /// The set of filters associated with this handler - /// The service key for dependency injection - /// The singleton instance of the handler - /// Thrown when or is null + /// The type of the descriptor. + /// The type of the handler. + /// The update type handled by this handler. + /// The indexer for handler concurrency and priority. + /// The set of filters associated with this handler. + /// The service key for the handler. + /// The singleton instance of the handler. public HandlerDescriptor(DescriptorType type, Type handlerType, UpdateType updateType, DescriptorIndexer indexer, DescriptorFiltersSet filters, object serviceKey, UpdateHandlerBase singletonInstance) { Type = type; @@ -221,20 +229,19 @@ namespace Telegrator.MadiatorCore.Descriptors UpdateType = updateType; Indexer = indexer; Filters = filters; - ServiceKey = serviceKey ?? throw new ArgumentNullException(nameof(serviceKey)); - SingletonInstance = singletonInstance ?? throw new ArgumentNullException(nameof(singletonInstance)); + ServiceKey = serviceKey; + SingletonInstance = singletonInstance; } /// - /// Initializes a new instance of the class with instance factory support. + /// Initializes a new instance of the class with instance factory. /// - /// The type of the descriptor - /// The type of the handler - /// The type of update this handler processes - /// The indexer for handler concurrency and priority - /// The set of filters associated with this handler - /// Factory for creating handler instances - /// Thrown when is null + /// The type of the descriptor. + /// The type of the handler. + /// The update type handled by this handler. + /// The indexer for handler concurrency and priority. + /// The set of filters associated with this handler. + /// The factory for creating handler instances. public HandlerDescriptor(DescriptorType type, Type handlerType, UpdateType updateType, DescriptorIndexer indexer, DescriptorFiltersSet filters, Func instanceFactory) { Type = type; @@ -242,20 +249,19 @@ namespace Telegrator.MadiatorCore.Descriptors UpdateType = updateType; Indexer = indexer; Filters = filters; - InstanceFactory = instanceFactory ?? throw new ArgumentNullException(nameof(instanceFactory)); + InstanceFactory = instanceFactory; } /// - /// Initializes a new instance of the class with service key and instance factory support. + /// Initializes a new instance of the class with service key and instance factory. /// - /// The type of the descriptor - /// The type of the handler - /// The type of update this handler processes - /// The indexer for handler concurrency and priority - /// The set of filters associated with this handler - /// The service key for dependency injection - /// Factory for creating handler instances - /// Thrown when or is null + /// The type of the descriptor. + /// The type of the handler. + /// The update type handled by this handler. + /// The indexer for handler concurrency and priority. + /// The set of filters associated with this handler. + /// The service key for the handler. + /// The factory for creating handler instances. public HandlerDescriptor(DescriptorType type, Type handlerType, UpdateType updateType, DescriptorIndexer indexer, DescriptorFiltersSet filters, object serviceKey, Func instanceFactory) { Type = type; @@ -263,210 +269,243 @@ namespace Telegrator.MadiatorCore.Descriptors UpdateType = updateType; Indexer = indexer; Filters = filters; - ServiceKey = serviceKey ?? throw new ArgumentNullException(nameof(serviceKey)); - InstanceFactory = instanceFactory ?? throw new ArgumentNullException(nameof(instanceFactory)); + ServiceKey = serviceKey; + InstanceFactory = instanceFactory; } /// - /// Initializes a new instance of the class with polling handler attribute and filters. + /// Initializes a new instance of the class with polling handler attribute. /// - /// The type of the descriptor - /// The type of the handler - /// The polling handler attribute containing configuration - /// Optional array of filters to apply - /// Optional state keeping filter + /// The type of the descriptor. + /// The type of the handler. + /// The polling handler attribute. + /// The array of filters associated with this handler. + /// The state keeper filter. public HandlerDescriptor(DescriptorType type, Type handlerType, UpdateHandlerAttributeBase pollingHandlerAttribute, IFilter[]? filters, IFilter? stateKeepFilter) { Type = type; HandlerType = handlerType; UpdateType = pollingHandlerAttribute.Type; Indexer = pollingHandlerAttribute.GetIndexer(); - Filters = new DescriptorFiltersSet(pollingHandlerAttribute, stateKeepFilter, filters); + FormReport = pollingHandlerAttribute.FormReport; + + if (filters != null || stateKeepFilter != null) + { + Filters = new DescriptorFiltersSet(filters ?? [], stateKeepFilter); + } } /// - /// Initializes a new instance of the class with polling handler attribute, filters, and singleton instance. + /// Initializes a new instance of the class for singleton handlers with polling handler attribute. /// - /// The type of the descriptor - /// The type of the handler - /// The polling handler attribute containing configuration - /// Optional array of filters to apply - /// Optional state keeping filter - /// The service key for dependency injection - /// The singleton instance of the handler - /// Thrown when or is null + /// The type of the descriptor. + /// The type of the handler. + /// The polling handler attribute. + /// The array of filters associated with this handler. + /// The state keeper filter. + /// The service key for the handler. + /// The singleton instance of the handler. public HandlerDescriptor(DescriptorType type, Type handlerType, UpdateHandlerAttributeBase pollingHandlerAttribute, IFilter[]? filters, IFilter? stateKeepFilter, object serviceKey, UpdateHandlerBase singletonInstance) { Type = type; HandlerType = handlerType; UpdateType = pollingHandlerAttribute.Type; Indexer = pollingHandlerAttribute.GetIndexer(); - Filters = new DescriptorFiltersSet(pollingHandlerAttribute, stateKeepFilter, filters); - ServiceKey = serviceKey ?? throw new ArgumentNullException(nameof(serviceKey)); - SingletonInstance = singletonInstance ?? throw new ArgumentNullException(nameof(singletonInstance)); + FormReport = pollingHandlerAttribute.FormReport; + ServiceKey = serviceKey; + SingletonInstance = singletonInstance; + + if (filters != null || stateKeepFilter != null) + { + Filters = new DescriptorFiltersSet(filters ?? [], stateKeepFilter); + } } /// - /// Initializes a new instance of the class with polling handler attribute, filters, and instance factory. + /// Initializes a new instance of the class with instance factory and polling handler attribute. /// - /// The type of the descriptor - /// The type of the handler - /// The polling handler attribute containing configuration - /// Optional array of filters to apply - /// Optional state keeping filter - /// Factory for creating handler instances - /// Thrown when is null + /// The type of the descriptor. + /// The type of the handler. + /// The polling handler attribute. + /// The array of filters associated with this handler. + /// The state keeper filter. + /// The factory for creating handler instances. public HandlerDescriptor(DescriptorType type, Type handlerType, UpdateHandlerAttributeBase pollingHandlerAttribute, IFilter[]? filters, IFilter? stateKeepFilter, Func instanceFactory) { Type = type; HandlerType = handlerType; UpdateType = pollingHandlerAttribute.Type; Indexer = pollingHandlerAttribute.GetIndexer(); - Filters = new DescriptorFiltersSet(pollingHandlerAttribute, stateKeepFilter, filters); - InstanceFactory = instanceFactory ?? throw new ArgumentNullException(nameof(instanceFactory)); + FormReport = pollingHandlerAttribute.FormReport; + InstanceFactory = instanceFactory; + + if (filters != null || stateKeepFilter != null) + { + Filters = new DescriptorFiltersSet(filters ?? [], stateKeepFilter); + } } /// - /// Initializes a new instance of the class with polling handler attribute, filters, service key, and instance factory. + /// Initializes a new instance of the class with service key, instance factory and polling handler attribute. /// - /// The type of the descriptor - /// The type of the handler - /// The polling handler attribute containing configuration - /// Optional array of filters to apply - /// Optional state keeping filter - /// The service key for dependency injection - /// Factory for creating handler instances - /// Thrown when or is null + /// The type of the descriptor. + /// The type of the handler. + /// The polling handler attribute. + /// The array of filters associated with this handler. + /// The state keeper filter. + /// The service key for the handler. + /// The factory for creating handler instances. public HandlerDescriptor(DescriptorType type, Type handlerType, UpdateHandlerAttributeBase pollingHandlerAttribute, IFilter[]? filters, IFilter? stateKeepFilter, object serviceKey, Func instanceFactory) { Type = type; HandlerType = handlerType; UpdateType = pollingHandlerAttribute.Type; Indexer = pollingHandlerAttribute.GetIndexer(); - Filters = new DescriptorFiltersSet(pollingHandlerAttribute, stateKeepFilter, filters); - ServiceKey = serviceKey ?? throw new ArgumentNullException(nameof(serviceKey)); - InstanceFactory = instanceFactory ?? throw new ArgumentNullException(nameof(instanceFactory)); + FormReport = pollingHandlerAttribute.FormReport; + ServiceKey = serviceKey; + InstanceFactory = instanceFactory; + + if (filters != null || stateKeepFilter != null) + { + Filters = new DescriptorFiltersSet(filters ?? [], stateKeepFilter); + } } /// - /// Initializes a new instance of the class with validation filter support. + /// Initializes a new instance of the class with complete configuration. /// - /// The type of the descriptor - /// The type of the handler - /// The type of update this handler processes - /// The indexer for handler concurrency and priority - /// Optional validation filter - /// Optional array of filters to apply - /// Optional state keeping filter + /// The type of the descriptor. + /// The type of the handler. + /// The update type handled by this handler. + /// The indexer for handler concurrency and priority. + /// The validation filter. + /// The array of filters associated with this handler. + /// The state keeper filter. public HandlerDescriptor(DescriptorType type, Type handlerType, UpdateType updateType, DescriptorIndexer indexer, IFilter? validateFilter, IFilter[]? filters, IFilter? stateKeepFilter) { Type = type; HandlerType = handlerType; UpdateType = updateType; Indexer = indexer; - Filters = new DescriptorFiltersSet(validateFilter, stateKeepFilter, filters); + + if (validateFilter != null || filters != null || stateKeepFilter != null) + { + Filters = new DescriptorFiltersSet(filters ?? [], stateKeepFilter, validateFilter); + } } /// - /// Initializes a new instance of the class with validation filter and singleton instance support. + /// Initializes a new instance of the class for singleton handlers with complete configuration. /// - /// The type of the descriptor - /// The type of the handler - /// The type of update this handler processes - /// The indexer for handler concurrency and priority - /// Optional validation filter - /// Optional array of filters to apply - /// Optional state keeping filter - /// The service key for dependency injection - /// The singleton instance of the handler - /// Thrown when or is null + /// The type of the descriptor. + /// The type of the handler. + /// The update type handled by this handler. + /// The indexer for handler concurrency and priority. + /// The validation filter. + /// The array of filters associated with this handler. + /// The state keeper filter. + /// The service key for the handler. + /// The singleton instance of the handler. public HandlerDescriptor(DescriptorType type, Type handlerType, UpdateType updateType, DescriptorIndexer indexer, IFilter? validateFilter, IFilter[]? filters, IFilter? stateKeepFilter, object serviceKey, UpdateHandlerBase singletonInstance) { Type = type; HandlerType = handlerType; UpdateType = updateType; Indexer = indexer; - Filters = new DescriptorFiltersSet(validateFilter, stateKeepFilter, filters); - ServiceKey = serviceKey ?? throw new ArgumentNullException(nameof(serviceKey)); - SingletonInstance = singletonInstance ?? throw new ArgumentNullException(nameof(singletonInstance)); + ServiceKey = serviceKey; + SingletonInstance = singletonInstance; + + if (validateFilter != null || filters != null || stateKeepFilter != null) + { + Filters = new DescriptorFiltersSet(filters ?? [], stateKeepFilter, validateFilter); + } } /// - /// Initializes a new instance of the class with validation filter and instance factory support. + /// Initializes a new instance of the class with instance factory and complete configuration. /// - /// The type of the descriptor - /// The type of the handler - /// The type of update this handler processes - /// The indexer for handler concurrency and priority - /// Optional validation filter - /// Optional array of filters to apply - /// Optional state keeping filter - /// Factory for creating handler instances - /// Thrown when is null + /// The type of the descriptor. + /// The type of the handler. + /// The update type handled by this handler. + /// The indexer for handler concurrency and priority. + /// The validation filter. + /// The array of filters associated with this handler. + /// The state keeper filter. + /// The factory for creating handler instances. public HandlerDescriptor(DescriptorType type, Type handlerType, UpdateType updateType, DescriptorIndexer indexer, IFilter? validateFilter, IFilter[]? filters, IFilter? stateKeepFilter, Func instanceFactory) { Type = type; HandlerType = handlerType; UpdateType = updateType; Indexer = indexer; - Filters = new DescriptorFiltersSet(validateFilter, stateKeepFilter, filters); - InstanceFactory = instanceFactory ?? throw new ArgumentNullException(nameof(instanceFactory)); + InstanceFactory = instanceFactory; + + if (validateFilter != null || filters != null || stateKeepFilter != null) + { + Filters = new DescriptorFiltersSet(filters ?? [], stateKeepFilter, validateFilter); + } } /// - /// Initializes a new instance of the class with validation filter, service key, and instance factory support. + /// Initializes a new instance of the class with service key, instance factory and complete configuration. /// - /// The type of the descriptor - /// The type of the handler - /// The type of update this handler processes - /// The indexer for handler concurrency and priority - /// Optional validation filter - /// Optional array of filters to apply - /// Optional state keeping filter - /// The service key for dependency injection - /// Factory for creating handler instances - /// Thrown when or is null + /// The type of the descriptor. + /// The type of the handler. + /// The update type handled by this handler. + /// The indexer for handler concurrency and priority. + /// The validation filter. + /// The array of filters associated with this handler. + /// The state keeper filter. + /// The service key for the handler. + /// The factory for creating handler instances. public HandlerDescriptor(DescriptorType type, Type handlerType, UpdateType updateType, DescriptorIndexer indexer, IFilter? validateFilter, IFilter[]? filters, IFilter? stateKeepFilter, object serviceKey, Func instanceFactory) { Type = type; HandlerType = handlerType; UpdateType = updateType; Indexer = indexer; - Filters = new DescriptorFiltersSet(validateFilter, stateKeepFilter, filters); - ServiceKey = serviceKey ?? throw new ArgumentNullException(nameof(serviceKey)); - InstanceFactory = instanceFactory ?? throw new ArgumentNullException(nameof(instanceFactory)); + ServiceKey = serviceKey; + InstanceFactory = instanceFactory; + + if (validateFilter != null || filters != null || stateKeepFilter != null) + { + Filters = new DescriptorFiltersSet(filters ?? [], stateKeepFilter, validateFilter); + } } /// - /// Sets singleton instance of this descriptor - /// Throws exception if instance already set + /// Sets the singleton instance for this handler descriptor. /// - /// - /// + /// The singleton instance to set. public void SetInstance(UpdateHandlerBase instance) { - if (SingletonInstance != null) - throw new Exception(); + if (Type != DescriptorType.Singleton) + throw new InvalidOperationException("Cannot set instance for non-singleton descriptor"); SingletonInstance = instance; } /// - /// Tries to set singleton instance of this descriptor + /// Attempts to set the singleton instance for this handler descriptor. /// - /// - /// + /// The singleton instance to set. + /// True if the instance was set successfully; otherwise, false. public bool TrySetInstance(UpdateHandlerBase instance) { - if (SingletonInstance != null) + if (Type != DescriptorType.Singleton) return false; SingletonInstance = instance; return true; } - /// + /// + /// Returns a string representation of this handler descriptor. + /// + /// A string representation of the handler descriptor. public override string ToString() - => DisplayString ?? HandlerType.Name; + { + return DisplayString ?? $"{Type} {HandlerType.Name}"; + } } }