1- // ==========================================================================================
1+ // ==========================================================================================
22// GameFrameX 组织及其衍生项目的版权、商标、专利及其他相关权利
33// GameFrameX organization and its derivative projects' copyrights, trademarks, patents, and related rights
44// 均受中华人民共和国及相关国际法律法规保护。
3636namespace GameFrameX . Utility ;
3737
3838/// <summary>
39+ /// Assembly helper utility class
40+ /// Provides assembly and type loading, caching, and querying functionality with thread-safe operations
41+ /// Main Features:
42+ /// 1. Assembly Management: Get all loaded assemblies in the current application domain
43+ /// 2. Type Discovery: Find and cache type information from assemblies
44+ /// 3. Inheritance Analysis: Find implementations, derived classes, and subclasses of specified types
45+ /// 4. Instance Creation: Automatically instantiate types that meet specified conditions
46+ /// 5. Attribute Filtering: Filter types based on custom attribute markers
47+ ///
48+ /// Performance Features:
49+ /// - Uses ConcurrentDictionary for thread-safe type caching
50+ /// - Implements lazy loading with Lazy{T} to avoid repeated type scanning
51+ /// - Built-in exception handling ensures partial assembly loading failures don't affect overall functionality
52+ ///
53+ /// Use Cases:
54+ /// - Type discovery and loading for plugin systems
55+ /// - Type registration and resolution for IoC containers
56+ /// - Module scanning for component-based architectures
57+ /// - Performance optimization for reflection operations
58+ ///
59+ /// </summary>
60+ /// <remarks>
3961/// 程序集辅助工具类
4062/// 提供程序集和类型的加载、缓存和查询功能,支持线程安全操作
4163///
@@ -56,31 +78,46 @@ namespace GameFrameX.Utility;
5678/// - IoC 容器的类型注册和解析
5779/// - 组件化架构的模块扫描
5880/// - 反射操作的性能优化
59- /// </summary >
81+ /// </remarks >
6082public static class AssemblyHelper
6183{
6284 /// <summary>
85+ /// Type cache dictionary using type full name as key, thread-safe
86+ /// Uses StringComparer.Ordinal for optimal string comparison performance
87+ /// </summary>
88+ /// <remarks>
6389 /// 类型缓存字典,使用类型全名作为键,线程安全
6490 /// 使用 StringComparer.Ordinal 提供最佳性能的字符串比较
65- /// </summary >
91+ /// </remarks >
6692 private static readonly ConcurrentDictionary < string , Type > CachedTypes = new ( StringComparer . Ordinal ) ;
6793
6894 /// <summary>
95+ /// Lazy-loaded type array ensuring types are loaded only once
96+ /// Uses Lazy{T} to guarantee thread-safe single initialization
97+ /// </summary>
98+ /// <remarks>
6999 /// 延迟加载的类型数组,确保类型只被加载一次
70100 /// 使用 Lazy<T> 保证线程安全的单次初始化
71- /// </summary >
101+ /// </remarks >
72102 private static readonly Lazy < Type [ ] > LazyTypes = new ( ( ) => LoadAllTypes ( ) ) ;
73103
74104 /// <summary>
75- /// 程序集访问锁,用于同步程序集获取操作
105+ /// Assembly access lock for synchronizing assembly retrieval operations
76106 /// </summary>
107+ /// <remarks>
108+ /// 程序集访问锁,用于同步程序集获取操作
109+ /// </remarks>
77110 private static readonly object AssemblyLock = new ( ) ;
78111
79112 /// <summary>
113+ /// Load all types with exception handling
114+ /// Iterates through all loaded assemblies and extracts type information
115+ /// </summary>
116+ /// <remarks>
80117 /// 加载所有类型,包含异常处理
81118 /// 遍历所有已加载的程序集,提取其中的类型信息
82- /// </summary >
83- /// <returns>所有已加载的类型数组</returns>
119+ /// </remarks >
120+ /// <returns>Array of all loaded types / 所有已加载的类型数组</returns>
84121 private static Type [ ] LoadAllTypes ( )
85122 {
86123 var results = new List < Type > ( ) ;
@@ -113,10 +150,14 @@ private static Type[] LoadAllTypes()
113150 }
114151
115152 /// <summary>
153+ /// Get currently loaded assemblies
154+ /// Uses lock to ensure safe access to assembly list in multi-threaded environment
155+ /// </summary>
156+ /// <remarks>
116157 /// 获取当前已加载的程序集
117158 /// 使用锁确保在多线程环境下安全访问程序集列表
118- /// </summary >
119- /// <returns>当前已加载的程序集数组</returns>
159+ /// </remarks >
160+ /// <returns>Array of currently loaded assemblies / 当前已加载的程序集数组</returns>
120161 private static Assembly [ ] GetCurrentAssemblies ( )
121162 {
122163 // 使用锁保护程序集访问,防止在程序集动态加载时出现竞态条件
@@ -127,31 +168,43 @@ private static Assembly[] GetCurrentAssemblies()
127168 }
128169
129170 /// <summary>
171+ /// Get loaded assemblies
172+ /// Returns all loaded assemblies in the current application domain, including dynamically loaded assemblies
173+ /// </summary>
174+ /// <remarks>
130175 /// 获取已加载的程序集
131176 /// 返回当前应用程序域中所有已加载的程序集,包括动态加载的程序集
132- /// </summary >
133- /// <returns>已加载的程序集数组,包含系统程序集和用户程序集</returns>
177+ /// </remarks >
178+ /// <returns>Array of loaded assemblies, including system and user assemblies / 已加载的程序集数组,包含系统程序集和用户程序集</returns>
134179 public static Assembly [ ] GetAssemblies ( )
135180 {
136181 return GetCurrentAssemblies ( ) ;
137182 }
138183
139184 /// <summary>
185+ /// Get all types from loaded assemblies
186+ /// Uses lazy loading and caching mechanism to ensure type information is loaded only once, improving performance
187+ /// </summary>
188+ /// <remarks>
140189 /// 获取已加载的程序集中的所有类型
141190 /// 使用延迟加载和缓存机制,确保类型信息只被加载一次,提高性能
142- /// </summary >
143- /// <returns>已加载的程序集中的所有类型数组,包括类、接口、枚举、委托等</returns>
191+ /// </remarks >
192+ /// <returns>Array of all types from loaded assemblies, including classes, interfaces, enums, delegates, etc. / 已加载的程序集中的所有类型数组,包括类、接口、枚举、委托等</returns>
144193 public static Type [ ] GetTypes ( )
145194 {
146195 return LazyTypes . Value ;
147196 }
148197
149198 /// <summary>
199+ /// Get all types from loaded assemblies and add results to the specified list
200+ /// This method clears the target list and then adds all type information
201+ /// </summary>
202+ /// <remarks>
150203 /// 获取已加载的程序集中的所有类型,并将结果添加到指定的列表中
151204 /// 此方法会清空目标列表,然后添加所有类型信息
152- /// </summary >
153- /// <param name="results">用于存储结果的列表,不能为 null</param>
154- /// <exception cref="ArgumentNullException">当 results 参数为 null 时抛出</exception>
205+ /// </remarks >
206+ /// <param name="results">List for storing results, cannot be null / 用于存储结果的列表,不能为 null</param>
207+ /// <exception cref="ArgumentNullException">Thrown when results parameter is null / 当 results 参数为 null 时抛出</exception>
155208 public static void GetTypes ( List < Type > results )
156209 {
157210 ArgumentNullException . ThrowIfNull ( results , nameof ( results ) ) ;
@@ -161,12 +214,16 @@ public static void GetTypes(List<Type> results)
161214 }
162215
163216 /// <summary>
217+ /// Get specified type from loaded assemblies
218+ /// Supports fully qualified names and simple type names, uses caching mechanism to improve lookup performance
219+ /// </summary>
220+ /// <remarks>
164221 /// 获取已加载的程序集中的指定类型
165222 /// 支持完全限定名和简单类型名,使用缓存机制提高查找性能
166- /// </summary >
167- /// <param name="typeName">要获取的类型名,支持完全限定名(如 "System.String")</param>
168- /// <returns>已加载的程序集中的指定类型,如果未找到则返回 null</returns>
169- /// <exception cref="ArgumentException">当 typeName 参数为 null 或空字符串时抛出</exception>
223+ /// </remarks >
224+ /// <param name="typeName">Type name to get, supports fully qualified names (e.g., "System.String") / 要获取的类型名,支持完全限定名(如 "System.String")</param>
225+ /// <returns>Specified type from loaded assemblies, returns null if not found / 已加载的程序集中的指定类型,如果未找到则返回 null</returns>
226+ /// <exception cref="ArgumentException">Thrown when typeName parameter is null or empty string / 当 typeName 参数为 null 或空字符串时抛出</exception>
170227 public static Type GetType ( string typeName )
171228 {
172229 ArgumentException . ThrowIfNullOrEmpty ( typeName , nameof ( typeName ) ) ;
@@ -205,11 +262,15 @@ public static Type GetType(string typeName)
205262 }
206263
207264 /// <summary>
265+ /// Get instantiated list of subclasses of specified type from loaded assemblies
266+ /// Automatically creates instances of all implementing types, only instantiates types with parameterless constructors
267+ /// </summary>
268+ /// <remarks>
208269 /// 获取已加载的程序集中的指定类型的子类实例化列表
209270 /// 自动创建所有实现类型的实例,只实例化具有无参构造函数的类型
210- /// </summary >
211- /// <typeparam name="T">指定的基类型或接口类型</typeparam>
212- /// <returns>指定类型的子类实例化列表,已排除无法实例化的类型</returns>
271+ /// </remarks >
272+ /// <typeparam name="T">Specified base type or interface type / 指定的基类型或接口类型</typeparam>
273+ /// <returns>Instantiated list of subclasses of specified type, excluding types that cannot be instantiated / 指定类型的子类实例化列表,已排除无法实例化的类型</returns>
213274 public static List < T > GetRuntimeImplementTypeNamesInstance < T > ( )
214275 {
215276 var types = GetRuntimeImplementTypeNames ( typeof ( T ) ) ;
@@ -240,23 +301,31 @@ public static List<T> GetRuntimeImplementTypeNamesInstance<T>()
240301 }
241302
242303 /// <summary>
304+ /// Get subclass list of specified type from loaded assemblies
305+ /// Generic version providing type-safe calling method
306+ /// </summary>
307+ /// <remarks>
243308 /// 获取已加载的程序集中的指定类型的子类列表
244309 /// 泛型版本,提供类型安全的调用方式
245- /// </summary >
246- /// <typeparam name="T">指定的基类型或接口类型</typeparam>
247- /// <returns>指定类型的子类列表,包括所有实现类和派生类</returns>
310+ /// </remarks >
311+ /// <typeparam name="T">Specified base type or interface type / 指定的基类型或接口类型</typeparam>
312+ /// <returns>Subclass list of specified type, including all implementing classes and derived classes / 指定类型的子类列表,包括所有实现类和派生类</returns>
248313 public static List < Type > GetRuntimeImplementTypeNames < T > ( )
249314 {
250315 return GetRuntimeImplementTypeNames ( typeof ( T ) ) ;
251316 }
252317
253318 /// <summary>
319+ /// Get subclass list of specified type from loaded assemblies and filter types with specified attributes
320+ /// Combines type inheritance and attribute marking for dual filtering, commonly used in plugin systems and component discovery
321+ /// </summary>
322+ /// <remarks>
254323 /// 获取已加载的程序集中的指定类型的子类列表,并过滤出具有指定特性的类型
255324 /// 结合类型继承和特性标记进行双重过滤,常用于插件系统和组件发现
256- /// </summary >
257- /// <typeparam name="T">指定的基类型或接口类型</typeparam>
258- /// <typeparam name="TAttribute">指定的自定义特性标记类型</typeparam>
259- /// <returns>指定类型的子类列表,且这些类型具有指定的特性标记</returns>
325+ /// </remarks >
326+ /// <typeparam name="T">Specified base type or interface type / 指定的基类型或接口类型</typeparam>
327+ /// <typeparam name="TAttribute">Specified custom attribute marker type / 指定的自定义特性标记类型</typeparam>
328+ /// <returns>Subclass list of specified type with specified attribute markers / 指定类型的子类列表,且这些类型具有指定的特性标记</returns>
260329 public static List < Type > GetRuntimeImplementTypeNames < T , TAttribute > ( ) where TAttribute : Attribute
261330 {
262331 var types = GetRuntimeImplementTypeNames ( typeof ( T ) ) ;
@@ -266,11 +335,15 @@ public static List<Type> GetRuntimeImplementTypeNames<T, TAttribute>() where TAt
266335 }
267336
268337 /// <summary>
338+ /// Get subclass list of specified type from loaded assemblies and return their full names
339+ /// Returns fully qualified names of types, convenient for serialization, configuration, and logging
340+ /// </summary>
341+ /// <remarks>
269342 /// 获取已加载的程序集中的指定类型的子类列表,并返回它们的全名
270343 /// 返回类型的完全限定名称,便于序列化、配置和日志记录
271- /// </summary >
272- /// <param name="type">指定的基类型或接口类型</param>
273- /// <returns>指定类型的子类列表的全名字符串集合</returns>
344+ /// </remarks >
345+ /// <param name="type">Specified base type or interface type / 指定的基类型或接口类型</param>
346+ /// <returns>Collection of full name strings of subclass list of specified type / 指定类型的子类列表的全名字符串集合</returns>
274347 public static List < string > GetRuntimeTypeNames ( Type type )
275348 {
276349 var results = new List < string > ( ) ;
@@ -287,12 +360,16 @@ public static List<string> GetRuntimeTypeNames(Type type)
287360 }
288361
289362 /// <summary>
363+ /// Get subclass list of specified type from loaded assemblies
364+ /// Core implementation method supporting multiple matching modes including interface implementation, class inheritance, and type assignment
365+ /// </summary>
366+ /// <remarks>
290367 /// 获取已加载的程序集中的指定类型的子类列表
291368 /// 核心实现方法,支持接口实现、类继承和类型分配的多种匹配模式
292- /// </summary >
293- /// <param name="type">指定的基类型或接口类型,不能为 null</param>
294- /// <returns>指定类型的子类列表,包括实现类、派生类和可分配类型</returns>
295- /// <exception cref="ArgumentNullException">当 type 参数为 null 时抛出</exception>
369+ /// </remarks >
370+ /// <param name="type">Specified base type or interface type, cannot be null / 指定的基类型或接口类型,不能为 null</param>
371+ /// <returns>Subclass list of specified type, including implementing classes, derived classes, and assignable types / 指定类型的子类列表,包括实现类、派生类和可分配类型</returns>
372+ /// <exception cref="ArgumentNullException">Thrown when type parameter is null / 当 type 参数为 null 时抛出</exception>
296373 public static List < Type > GetRuntimeImplementTypeNames ( Type type )
297374 {
298375 ArgumentNullException . ThrowIfNull ( type , nameof ( type ) ) ;
0 commit comments