RELEASE: v5.10.0 by moomiji · Pull Request #30 · MaaXYZ/MaaFramework.Binding.CSharp

moomiji · 2026-07-09T12:14:28Z

Summary by Sourcery

发布 v5.10.0，使 C# 绑定与 MaaFramework v5.10.5 保持一致，并更新 CI/CD 工作流与发布流程。

新功能：

添加 AgentServer 日志配置 API，用于设置日志目录和标准输出日志级别。

错误修复：

调整控制器选项测试，以适配 Win32 特定选项，并纠正 shell 输出测试的期望值。
修复 wlroots use_win32_vk_code 方法签名，使其与更新日志中的说明一致。

增强：

将旧版工具包初始化选项扩展标记为弃用，推荐使用新的日志配置 API。
将绑定和文档中的版本引用、示例和元数据更新到 v5.10.x。
引入 Win32 MaaTypes 标志，用于区分平台特定的控制器选项。

构建：

将 CI/CD 工作流中的 GitHub Actions 升级到新的主版本，并调整分支条件语法。
更改 CD 中的 NuGet 发布方式，改为使用 NuGet/login 基于 OIDC 的认证，用于测试和生产源。
更新 GitHub Pages 部署 Action 版本和发布 Action 版本。

CI：

刷新 CI 工作流中的 Actions 和条件表达式，同时保持构建和代码检查行为不变。

文档：

更新 v5.10.0 的更新日志（主日志及所有版本日志），包括破坏性变更、新功能和修复内容。
刷新 README 和文档，使其引用 MaaFramework v5.10.5 和更新后的包版本。

测试：

更新代理服务器和控制器的单元测试，以覆盖新的日志 API 和 Win32 特定选项。

Original summary in English

Summary by Sourcery

Release v5.10.0 aligning the C# bindings with MaaFramework v5.10.5 and updating CI/CD workflows and publishing flows.

New Features:

Add AgentServer logging configuration APIs for setting log directory and stdout logging level.

Bug Fixes:

Adjust controller option tests for Win32-specific options and correct shell output test expectations.
Fix wlroots use_win32_vk_code method signature as noted in changelog.

Enhancements:

Mark legacy toolkit init option extension as obsolete in favor of new logging configuration APIs.
Update binding and documentation version references, samples, and metadata to v5.10.x.
Introduce Win32 MaaTypes flag to distinguish platform-specific controller options.

Build:

Upgrade GitHub Actions in CI/CD workflows to newer major versions and adjust branch condition syntax.
Change NuGet publishing in CD to use NuGet/login OIDC-based authentication for test and production feeds.
Update GitHub Pages deployment action version and release action version.

CI:

Refresh CI workflow actions and conditional expressions while keeping build and lint behavior intact.

Documentation:

Update changelog (main and all-versions) for v5.10.0, including breaking changes, new features, and fixes.
Refresh README and docs to reference MaaFramework v5.10.5 and updated package versions.

Tests:

Update agent server and controller unit tests to exercise new logging APIs and Win32-specific options.

MaaXYZ/MaaFramework#1201

sourcery-ai

Hey - 我发现了两个问题，并给出了一些总体反馈：

在 ci.yml 中，更新后的条件 github.ref == format('refs/heads/{0}', steps.build.outputs.default_branch) 很可能需要包裹在表达式中（${{ format(...) }}）；按当前写法它会被视为字面字符串，而不会被求值。
MaaAgentServer 中的 SetLogDirectory 在文档中声明会抛出 ArgumentNullException，但目前是直接将目录传给 SetOption，没有进行空/空字符串检查；建议对输入进行校验，使其与 XML 文档一致，并避免产生含糊不清的互操作错误。

给 AI Agent 的提示

Please address the comments from this code review:

## Overall Comments
- 在 ci.yml 中，更新后的条件 `github.ref == format('refs/heads/{0}', steps.build.outputs.default_branch)` 很可能需要包裹在表达式中（`${{ format(...) }}`）；按当前写法它会被视为字面字符串，而不会被求值。
- MaaAgentServer 中的 SetLogDirectory 在文档中声明会抛出 ArgumentNullException，但目前是直接将目录传给 SetOption，没有进行空/空字符串检查；建议对输入进行校验，使其与 XML 文档一致，并避免产生含糊不清的互操作错误。

## Individual Comments

### Comment 1
<location path="src/MaaFramework.Binding/IMaaAgentServer.cs" line_range="24-26" />
<code_context>
+    /// <summary>
+    ///     Sets the log directory.
+    /// </summary>
+    /// <param name="directory">The log directory.</param>
+    /// <exception cref="ArgumentNullException"/>
+    /// <exception cref="MaaInteroperationException"/>
+    IMaaAgentServer SetLogDirectory(string directory);
+
</code_context>
<issue_to_address>
**issue:** `SetLogDirectory`/`SetStdoutLevel` 文档中声明的 `ArgumentNullException` 与当前实现不匹配。

该接口在 `SetLogDirectory` 和 `SetStdoutLevel` 上记录了 `ArgumentNullException`，但 `MaaAgentServer` 是委托给 `MaaGlobal.Shared.SetOption`，并未显式强制这一异常。如果 `SetOption` 在接收到 null 时不会抛出 `ArgumentNullException`，那么 XML 文档就是不准确的。请考虑要么添加显式的 null 检查以匹配文档中声明的异常，要么更新 XML 注释以反映实际行为。
</issue_to_address>

### Comment 2
<location path="docs/articles/overview-of-wrapper-and-api.md" line_range="1" />
<code_context>
-# Overview of Wrapper (v5.8.0) and Api ([v5.8.1](https://github.com/MaaXYZ/MaaFramework/tree/v5.8.1))
+# Overview of Wrapper (v5.10.0) and Api ([v5.10.5](https://github.com/MaaXYZ/MaaFramework/tree/v5.10.5))

 ## Enums
</code_context>
<issue_to_address>
**suggestion (typo):** 建议将标题中的 "Api" 改为更常见的大写形式 "API"。

在这里使用标准缩写大写形式 "API" 可以让文档在风格上更统一，也更清晰易读。

```suggestion
# Overview of Wrapper (v5.10.0) and API ([v5.10.5](https://github.com/MaaXYZ/MaaFramework/tree/v5.10.5))
```
</issue_to_address>

Sourcery 对开源项目是免费的——如果你觉得我们的评审有帮助，欢迎分享 ✨

_{帮我变得更有用！请在每条评论上点 👍 或 👎，我会根据你的反馈改进后续评审。}

Original comment in English

Hey - I've found 2 issues, and left some high level feedback:

In ci.yml, the updated condition github.ref == format('refs/heads/{0}', steps.build.outputs.default_branch) should likely be wrapped in an expression (${{ format(...) }}); as written it will be treated as a literal string rather than evaluated.
SetLogDirectory in MaaAgentServer is documented as throwing ArgumentNullException but currently passes the directory directly to SetOption without a null/empty check; consider validating the input to match the XML documentation and avoid ambiguous interop errors.

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- In ci.yml, the updated condition `github.ref == format('refs/heads/{0}', steps.build.outputs.default_branch)` should likely be wrapped in an expression (`${{ format(...) }}`); as written it will be treated as a literal string rather than evaluated.
- SetLogDirectory in MaaAgentServer is documented as throwing ArgumentNullException but currently passes the directory directly to SetOption without a null/empty check; consider validating the input to match the XML documentation and avoid ambiguous interop errors.

## Individual Comments

### Comment 1
<location path="src/MaaFramework.Binding/IMaaAgentServer.cs" line_range="24-26" />
<code_context>
+    /// <summary>
+    ///     Sets the log directory.
+    /// </summary>
+    /// <param name="directory">The log directory.</param>
+    /// <exception cref="ArgumentNullException"/>
+    /// <exception cref="MaaInteroperationException"/>
+    IMaaAgentServer SetLogDirectory(string directory);
+
</code_context>
<issue_to_address>
**issue:** The documented `ArgumentNullException` for `SetLogDirectory`/`SetStdoutLevel` does not match the current implementation.

The interface documents `ArgumentNullException` for `SetLogDirectory` and `SetStdoutLevel`, but `MaaAgentServer` delegates to `MaaGlobal.Shared.SetOption` and does not explicitly enforce this. If `SetOption` doesn’t throw `ArgumentNullException` for null values, the XML docs are inaccurate. Please either add explicit null checks to match the documented exceptions or update the XML comments to reflect the actual behavior.
</issue_to_address>

### Comment 2
<location path="docs/articles/overview-of-wrapper-and-api.md" line_range="1" />
<code_context>
-# Overview of Wrapper (v5.8.0) and Api ([v5.8.1](https://github.com/MaaXYZ/MaaFramework/tree/v5.8.1))
+# Overview of Wrapper (v5.10.0) and Api ([v5.10.5](https://github.com/MaaXYZ/MaaFramework/tree/v5.10.5))

 ## Enums
</code_context>
<issue_to_address>
**suggestion (typo):** Consider capitalizing "Api" to the more standard "API" in this heading.

Using the standard acronym capitalization "API" here will keep the documentation consistent and clearer for readers.

```suggestion
# Overview of Wrapper (v5.10.0) and API ([v5.10.5](https://github.com/MaaXYZ/MaaFramework/tree/v5.10.5))
```
</issue_to_address>

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

Copilot

Pull request overview

Release PR for v5.10.0, updating the C# bindings to align with MaaFramework v5.10.5, introducing AgentServer logging configuration APIs, and refreshing docs/tests/CI-CD for the new release line.

Changes:

Updated dependency versions to MaaFramework runtimes 5.10.5 and refreshed version references across samples/docs/changelogs.
Added IMaaAgentServer logging configuration APIs (SetLogDirectory, SetStdoutLevel) and marked the legacy toolkit init-option extension as obsolete.
Updated unit tests and GitHub Actions workflows for the new release/publishing flow.

Reviewed changes

Copilot reviewed 21 out of 21 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
src/MaaFramework/packages.lock.json	Updates locked MaaFramework runtime dependencies to `5.10.5`.
src/MaaFramework.Binding/MaaMsg.cs	Updates embedded API document version reference.
src/MaaFramework.Binding/IMaaAgentServer.cs	Adds AgentServer logging configuration methods to the public interface.
src/MaaFramework.Binding.UnitTests/Test_IMaaController.cs	Adjusts controller option test scoping and shell output expectations.
src/MaaFramework.Binding.UnitTests/Test_IMaaAgentServer.cs	Updates AgentServer test to use new logging APIs.
src/MaaFramework.Binding.UnitTests/packages.lock.json	Updates unit test project lockfile to MaaFramework runtimes `5.10.5`.
src/MaaFramework.Binding.UnitTests/MaaTypes.cs	Introduces a `Win32` MaaTypes flag for platform-specific test selection.
src/MaaFramework.Binding.Native/NativeBindingContext.cs	Bumps binding version constant to `v5.10.0`.
src/MaaFramework.Binding.Native/MaaAgentServer.cs	Implements new logging APIs and marks legacy init-option extension obsolete.
src/Directory.Packages.props	Updates central package version for MaaFramework runtimes to `5.10.5`.
sample/csharp/3.CSBinding README Example.cs	Updates sample package reference to `5.10.0`.
sample/csharp/2.AgentMain.cs	Updates sample package reference to `5.10.0`.
sample/csharp/2.AgentChild.cs	Updates sample package reference to `5.10.0`.
sample/csharp/1.main.cs	Updates sample package reference to `5.10.0`.
README.zh_cn.md	Updates MaaFramework doc links to `v5.10.5`.
README.md	Updates MaaFramework doc links to `v5.10.5`.
docs/articles/overview-of-wrapper-and-api.md	Updates wrapper/API version header references to `v5.10.x`.
docs/articles/changelog-all-version.md	Adds `5.10.0` entry to the aggregated changelog.
CHANGELOG.md	Updates top-level changelog for `v5.10.0` release notes and links.
.github/workflows/ci.yml	Updates CI workflow action versions and branch condition syntax.
.github/workflows/cd.yml	Updates CD action versions and switches NuGet publishing to NuGet/login (OIDC).

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

moomiji added 5 commits July 8, 2026 19:34

chore: update interop to framework v5.10.5

c5b19bd

fix: unit tests

761159f

feat: configure AgentServer logging

68492cf

MaaXYZ/MaaFramework#1201

ci: update actions version

6ccc0dd

RELEASE: v5.10.0

5106b0b

moomiji requested a review from Copilot July 9, 2026 12:14

sourcery-ai Bot reviewed Jul 9, 2026

View reviewed changes

Comment thread src/MaaFramework.Binding/IMaaAgentServer.cs

Comment thread docs/articles/overview-of-wrapper-and-api.md

Copilot started reviewing on behalf of moomiji July 9, 2026 12:19 View session

Copilot AI reviewed Jul 9, 2026

View reviewed changes

Comment thread src/MaaFramework.Binding.UnitTests/MaaTypes.cs

Comment thread src/MaaFramework.Binding/IMaaAgentServer.cs

moomiji merged commit 27c69a5 into main Jul 9, 2026
6 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

RELEASE: v5.10.0#30

RELEASE: v5.10.0#30
moomiji merged 5 commits into
mainfrom
dev

moomiji commented Jul 9, 2026 •

edited by sourcery-ai Bot

Loading

Uh oh!

sourcery-ai Bot left a comment

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

moomiji commented Jul 9, 2026 • edited by sourcery-ai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary by Sourcery

Summary by Sourcery

Uh oh!

sourcery-ai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

moomiji commented Jul 9, 2026 •

edited by sourcery-ai Bot

Loading