添加注释内容

.github/workflows/dotnet-build.yml

@@ -8,7 +8,16 @@ jobs:
     runs-on: windows-latest
 
     steps:
-    - uses: actions/checkout@v1
+    - uses: actions/checkout@v6
+    - name: Setup .NET
+      uses: actions/setup-dotnet@v5
+      with:
+        dotnet-version: |
+          3.1.x
+          6.0.x
+          8.0.x
+          9.0.x
+          10.0.x
 
     - name: Build with dotnet
       run: dotnet build --configuration Release

.github/workflows/nuget-tag-publish.yml

@@ -11,7 +11,19 @@ jobs:
     runs-on: windows-latest
 
     steps:
-    - uses: actions/checkout@v1
+    - uses: actions/checkout@v6
+    - name: Setup .NET
+      uses: actions/setup-dotnet@v5
+      with:
+        dotnet-version: |
+          3.1.x
+          6.0.x
+          8.0.x
+          9.0.x
+          10.0.x
+
+    - name: Add .NET global tools to PATH
+      run: echo "$HOME/.dotnet/tools" >> $GITHUB_PATH
 
     - name: Install dotnet tool
       run: dotnet tool install -g dotnetCampus.TagToVersion
@@ -24,16 +36,10 @@ jobs:
         dotnet build --configuration Release
         dotnet pack --configuration Release --no-build
 
-    - name: Install Nuget
-      uses: nuget/setup-nuget@v1
-      with:
-        nuget-version: '5.x'
-
-    - name: Add private GitHub registry to NuGet
-      run: |
-        nuget sources add -name github -Source https://nuget.pkg.github.com/dotnet-campus/index.json -Username dotnet-campus -Password ${{ secrets.GITHUB_TOKEN }}
-
-    - name: Push generated package to GitHub registry
+    - name: Publish
       run: |
-        nuget push .\bin\Release\*.nupkg -Source github -SkipDuplicate
-        nuget push .\bin\Release\*.nupkg -Source https://api.nuget.org/v3/index.json -SkipDuplicate -ApiKey ${{ secrets.NugetKey }} 
+        dotnet nuget push ".\bin\Release\*.nupkg" --api-key ${{ secrets.NugetKey }} --source https://api.nuget.org/v3/index.json --skip-duplicate
+        dotnet nuget push ".\bin\Release\*.nupkg" \
+          --api-key ${{ secrets.GITHUB_TOKEN }} \
+          --source https://nuget.pkg.github.com/${{ github.repository_owner }} \
+          --skip-duplicate

src/LightWorkFlowManager.Tests/MessageWorkerManagerTest.cs

@@ -12,11 +12,17 @@
 
 namespace LightWorkFlowManager.Tests;
 
+/// <summary>
+/// `MessageWorkerManager` 相关测试。
+/// </summary>
 [TestClass]
 public class MessageWorkerManagerTest
 {
     private const int UnknownError = 7000;
 
+    /// <summary>
+    /// 验证工作器管理器在失败、重试与异常场景下的行为。
+    /// </summary>
     [ContractTestCase]
     public void RunFail()
     {
@@ -120,6 +126,14 @@ await Assert.ThrowsExceptionAsync<MessageWorkerInputNotFoundException>(async ()
         });
     }
 
+    /// <summary>
+    /// 创建用于测试的工作器管理器。
+    /// </summary>
+    /// <param name="serviceProvider">可选的服务提供器。</param>
+    /// <param name="taskId">可选的任务标识。</param>
+    /// <param name="taskName">可选的任务名称。</param>
+    /// <param name="retryCount">重试次数。</param>
+    /// <returns>测试用工作器管理器实例。</returns>
     public static MessageWorkerManager GetTestMessageWorkerManager(IServiceProvider? serviceProvider = null,
         string? taskId = null, string? taskName = null, int retryCount = 3)
     {
@@ -128,6 +142,10 @@ public static MessageWorkerManager GetTestMessageWorkerManager(IServiceProvider?
         return messageWorkerManager;
     }
 
+    /// <summary>
+    /// 构建测试用服务提供器。
+    /// </summary>
+    /// <returns>测试用服务提供器实例。</returns>
     public static IServiceProvider BuildServiceProvider()
     {
         var serviceCollection = new ServiceCollection();

src/LightWorkFlowManager.Tests/MessageWorkerTest.cs

@@ -11,9 +11,15 @@
 
 namespace LightWorkFlowManager.Tests;
 
+/// <summary>
+/// `MessageWorker` 相关测试。
+/// </summary>
 [TestClass]
 public class MessageWorkerTest
 {
+    /// <summary>
+    /// 验证工作器内部可以继续运行其他工作器。
+    /// </summary>
     [ContractTestCase]
     public void RunWorkerOnWorker()
     {

src/LightWorkFlowManager.Tests/ProgressCompositorTest.cs

@@ -6,9 +6,15 @@
 
 namespace LightWorkFlowManager.Tests;
 
+/// <summary>
+/// `ProgressCompositor` 相关测试。
+/// </summary>
 [TestClass]
 public class ProgressCompositorTest
 {
+    /// <summary>
+    /// 验证子进度合成后的进度计算结果。
+    /// </summary>
     [ContractTestCase]
     public void TestSubProgressReport()
     {

src/LightWorkFlowManager/Contexts/IWorkerContext.cs

@@ -11,15 +11,15 @@ public interface IWorkerContext
     /// <summary>
     /// 获取上下文信息
     /// </summary>
-    /// <typeparam name="T"></typeparam>
-    /// <returns>如果获取不到，返回空</returns>
+    /// <typeparam name="T">上下文类型。</typeparam>
+    /// <returns>如果获取不到则返回空。</returns>
     T? GetContext<T>();
 
     /// <summary>
     /// 设置上下文信息
     /// </summary>
-    /// <typeparam name="T"></typeparam>
-    /// <param name="context"></param>
+    /// <typeparam name="T">上下文类型。</typeparam>
+    /// <param name="context">要保存的上下文对象。</param>
     void SetContext<T>(T context);
 }
 
@@ -31,9 +31,9 @@ public static class MessageContextExtension
     /// <summary>
     /// 获取一定存在的上下文信息
     /// </summary>
-    /// <typeparam name="T"></typeparam>
-    /// <param name="workerContext"></param>
-    /// <returns></returns>
+    /// <typeparam name="T">上下文类型。</typeparam>
+    /// <param name="workerContext">工作器上下文。</param>
+    /// <returns>已存在的上下文对象。</returns>
     /// <exception cref="WorkerContextNotFoundException">如果上下文信息不存在，就抛出异常</exception>
     public static T GetEnsureContext<T>(this IWorkerContext workerContext)
     {

src/LightWorkFlowManager/Contexts/WorkFlowErrorCode.cs

@@ -12,6 +12,8 @@ namespace DC.LightWorkFlowManager.Contexts;
     /// <summary>
     /// 创建错误码
     /// </summary>
+    /// <param name="code">错误码数值。</param>
+    /// <param name="message">错误码对应的可读信息。</param>
     public WorkFlowErrorCode(int code, string message)
     {
         Code = code;
@@ -38,8 +40,8 @@ public WorkFlowErrorCode(int code, string message)
     /// <summary>
     /// 追加信息
     /// </summary>
-    /// <param name="appendMessage"></param>
-    /// <returns></returns>
+    /// <param name="appendMessage">要追加的描述信息。</param>
+    /// <returns>追加描述后的错误码。</returns>
     public WorkFlowErrorCode AppendMessage(string? appendMessage)
     {
         if (appendMessage == null)
@@ -55,7 +57,8 @@ public WorkFlowErrorCode AppendMessage(string? appendMessage)
     /// <summary>
     /// 隐式转换为 int 类型
     /// </summary>
-    /// <param name="code"></param>
+    /// <param name="code">工作流错误码。</param>
+    /// <returns>错误码数值。</returns>
     public static implicit operator int(WorkFlowErrorCode code)
     {
         return code.Code;
@@ -64,7 +67,8 @@ public static implicit operator int(WorkFlowErrorCode code)
     /// <summary>
     /// 从 int 类型隐式转换为错误信息
     /// </summary>
-    /// <param name="code"></param>
+    /// <param name="code">错误码数值。</param>
+    /// <returns>对应的工作流错误码。</returns>
     public static implicit operator WorkFlowErrorCode(int code)
     {
         if (ErrorCodeDictionary.TryGetValue(code, out var value))
@@ -107,9 +111,9 @@ public override int GetHashCode()
     /// <summary>
     /// 判断相等
     /// </summary>
-    /// <param name="left"></param>
-    /// <param name="right"></param>
-    /// <returns></returns>
+    /// <param name="left">左侧错误码。</param>
+    /// <param name="right">右侧错误码。</param>
+    /// <returns>两个错误码是否相等。</returns>
     public static bool operator ==(WorkFlowErrorCode left, WorkFlowErrorCode right)
     {
         return left.Equals(right);
@@ -118,9 +122,9 @@ public override int GetHashCode()
     /// <summary>
     /// 判断不相等
     /// </summary>
-    /// <param name="left"></param>
-    /// <param name="right"></param>
-    /// <returns></returns>
+    /// <param name="left">左侧错误码。</param>
+    /// <param name="right">右侧错误码。</param>
+    /// <returns>两个错误码是否不相等。</returns>
     public static bool operator !=(WorkFlowErrorCode left, WorkFlowErrorCode right)
     {
         return !left.Equals(right);

src/LightWorkFlowManager/Contexts/WorkerContext.cs

@@ -3,8 +3,12 @@
 
 namespace DC.LightWorkFlowManager.Contexts;
 
+/// <summary>
+/// 提供基于类型索引的工作器上下文实现。
+/// </summary>
 public class WorkerContext : IWorkerContext
 {
+    /// <inheritdoc />
     [System.Diagnostics.DebuggerStepThrough]
     public T? GetContext<T>()
     {
@@ -16,6 +20,7 @@ public class WorkerContext : IWorkerContext
         return default;
     }
 
+    /// <inheritdoc />
     public void SetContext<T>(T context)
     {
         _contextDictionary[typeof(T)] = context;

src/LightWorkFlowManager/Exceptions/MessageWorkerException.cs

@@ -11,7 +11,7 @@ public class MessageWorkerException : WorkFlowException
     /// <summary>
     /// 工作过程的异常
     /// </summary>
-    /// <param name="errorCode"></param>
+    /// <param name="errorCode">工作流错误码。</param>
     /// <param name="canRetryWorker">默认 false 表示不能重试</param>
     public MessageWorkerException(WorkFlowErrorCode errorCode, bool canRetryWorker = false)
     {
@@ -22,6 +22,8 @@ public MessageWorkerException(WorkFlowErrorCode errorCode, bool canRetryWorker =
     /// <summary>
     /// 工作过程的异常
     /// </summary>
+    /// <param name="errorCode">工作流错误码。</param>
+    /// <param name="innerException">导致当前异常的内部异常。</param>
     public MessageWorkerException(WorkFlowErrorCode errorCode, Exception innerException) : base(errorCode.Message, innerException)
     {
         ErrorCode = errorCode;
@@ -32,7 +34,12 @@ public MessageWorkerException(WorkFlowErrorCode errorCode, Exception innerExcept
     /// 是否可以重试
     /// </summary>
     public bool CanRetryWorker { get; }
+
+    /// <summary>
+    /// 获取当前异常对应的工作流错误码。
+    /// </summary>
     public WorkFlowErrorCode ErrorCode { get; }
 
+    /// <inheritdoc />
     public override string Message => ErrorCode.Message;
 }

src/LightWorkFlowManager/Exceptions/MessageWorkerInputArgumentException.cs

@@ -7,6 +7,10 @@ namespace DC.LightWorkFlowManager.Exceptions;
 /// </summary>
 public class MessageWorkerInputArgumentException : MessageWorkerException
 {
+    /// <summary>
+    /// 使用指定错误码初始化输入参数异常。
+    /// </summary>
+    /// <param name="errorCode">输入参数错误对应的工作流错误码。</param>
     public MessageWorkerInputArgumentException(WorkFlowErrorCode errorCode) : base(errorCode,canRetryWorker: false)
     {
     }

src/LightWorkFlowManager/Exceptions/MessageWorkerInputNotFoundException.cs

@@ -7,6 +7,10 @@ namespace DC.LightWorkFlowManager.Exceptions;
 /// </summary>
 public class MessageWorkerInputNotFoundException : InvalidOperationException, IWorkFlowException
 {
+    /// <summary>
+    /// 使用指定错误消息初始化异常。
+    /// </summary>
+    /// <param name="message">异常消息。</param>
     public MessageWorkerInputNotFoundException(string? message) : base(message)
     {
     }

src/LightWorkFlowManager/Exceptions/WorkFlowException.cs

@@ -8,18 +8,35 @@ namespace DC.LightWorkFlowManager.Exceptions;
 /// </summary>
 public abstract class WorkFlowException : Exception, IWorkFlowException
 {
+    /// <summary>
+    /// 初始化工作流异常。
+    /// </summary>
     protected WorkFlowException()
     {
     }
 
+    /// <summary>
+    /// 使用序列化信息初始化工作流异常。
+    /// </summary>
+    /// <param name="info">保存序列化对象数据的对象。</param>
+    /// <param name="context">有关源或目标的上下文信息。</param>
     protected WorkFlowException(SerializationInfo info, StreamingContext context) : base(info, context)
     {
     }
 
+    /// <summary>
+    /// 使用指定错误消息初始化工作流异常。
+    /// </summary>
+    /// <param name="message">异常消息。</param>
     protected WorkFlowException(string? message) : base(message)
     {
     }
 
+    /// <summary>
+    /// 使用指定错误消息和内部异常初始化工作流异常。
+    /// </summary>
+    /// <param name="message">异常消息。</param>
+    /// <param name="innerException">导致当前异常的内部异常。</param>
     protected WorkFlowException(string? message, Exception? innerException) : base(message, innerException)
     {
     }

src/LightWorkFlowManager/Exceptions/WorkerContextNotFoundException.cs

@@ -1,13 +1,24 @@
 namespace DC.LightWorkFlowManager.Exceptions;
 
+/// <summary>
+/// 表示无法从工作器上下文中找到指定类型数据的异常。
+/// </summary>
 public class WorkerContextNotFoundException : WorkFlowException
 {
+    /// <summary>
+    /// 使用缺失的上下文键初始化异常。
+    /// </summary>
+    /// <param name="key">缺失的上下文键。</param>
     public WorkerContextNotFoundException(string key)
     {
         Key = key;
     }
 
+    /// <summary>
+    /// 获取缺失的上下文键。
+    /// </summary>
     public string Key { get; }
 
+    /// <inheritdoc />
     public override string Message => $"Can not find {Key}";
 }