Skip to content

Commit ec31e40

Browse files
committed
docs(AssemblyHelper): 完善类和方法注释的英文翻译
添加完整的英文注释翻译,保持与中文注释内容一致 提高代码的国际化和可读性,方便非中文开发者使用
1 parent 566b912 commit ec31e40

File tree

1 file changed

+114
-37
lines changed

1 file changed

+114
-37
lines changed

GameFrameX.Utility/AssemblyHelper.cs

Lines changed: 114 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
// ==========================================================================================
1+
// ==========================================================================================
22
// GameFrameX 组织及其衍生项目的版权、商标、专利及其他相关权利
33
// GameFrameX organization and its derivative projects' copyrights, trademarks, patents, and related rights
44
// 均受中华人民共和国及相关国际法律法规保护。
@@ -36,6 +36,28 @@
3636
namespace 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>
6082
public 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&lt;T&gt; 保证线程安全的单次初始化
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

Comments
 (0)