Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 9 additions & 3 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -46,12 +46,18 @@ jobs:
- '**/*.props'
- '**/*.targets'
ui:
- 'global.json'
- 'src/InputBox/InputBox.csproj'
- 'src/InputBox/Program.cs'
- 'tests/InputBox.Tests/InputBox.Tests.csproj'
- 'src/InputBox/MainForm*.cs'
- 'src/InputBox/MainForm.resx'
- 'src/InputBox/Core/Controls/**'
- 'src/InputBox/Resources/**'
- 'tests/InputBox.Tests/MainFormUiSmokeTests.cs'
- 'tests/InputBox.Tests/UiSmokeTestRequirements.cs'
- 'tests/InputBox.Tests/UiVisualSnapshot.cs'
- 'tests/InputBox.Tests/UiWindowDiscovery.cs'

build-check:
if: needs.changes.outputs.code == 'true'
Expand All @@ -64,7 +70,7 @@ jobs:

# 定義環境變數,方便統一管理。
env:
DOTNET_MAJOR_VERSION: '10'
DOTNET_MAJOR_VERSION: '11'
DOTNET_CLI_TELEMETRY_OPTOUT: '1'
DOTNET_SKIP_FIRST_TIME_EXPERIENCE: '1'
# xUnit v3 MTP 的 coverage 輸出在 bin 輸出目錄的 TestResults 子目錄下。
Expand Down Expand Up @@ -140,7 +146,7 @@ jobs:
- name: 建置應用程式與測試專案(Build App + Tests)
working-directory: ./tests/InputBox.Tests
# 測試專案會連同主專案相依一起建置,避免重複編譯浪費資源。
run: dotnet build InputBox.Tests.csproj -c Release --no-incremental
run: dotnet build InputBox.Tests.csproj -c Release --no-incremental -warnaserror

- name: 上傳建置產出(供 ui-smoke 重用)
if: needs.changes.outputs.ui == 'true'
Expand Down Expand Up @@ -215,7 +221,7 @@ jobs:
contents: read

env:
DOTNET_MAJOR_VERSION: '10'
DOTNET_MAJOR_VERSION: '11'
DOTNET_CLI_TELEMETRY_OPTOUT: '1'
DOTNET_SKIP_FIRST_TIME_EXPERIENCE: '1'
INPUTBOX_RUN_UI_TESTS: '1'
Expand Down
4 changes: 2 additions & 2 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ jobs:

# 定義環境變數,方便統一管理。
env:
DOTNET_MAJOR_VERSION: '10'
DOTNET_MAJOR_VERSION: '11'
DOTNET_CLI_TELEMETRY_OPTOUT: '1'
DOTNET_SKIP_FIRST_TIME_EXPERIENCE: '1'
DOTNET_NOLOGO: '1'
Expand Down Expand Up @@ -582,7 +582,7 @@ jobs:
## 📦 輸入框發佈摘要
- **版本號碼**:`${{ github.ref_name }}`
- **目標平台**:Windows x64
- **執行環境**:.NET 10(已隨附 Runtime,無需額外安裝)
- **執行環境**:.NET 11(已隨附 Runtime,無需額外安裝)
- **執行檔案的雜湊值(SHA256)**:`${{ env.SHA256_HASH }}`
- **GameInput Redist(選用手動安裝)SHA256**:`${{ env.GAMEINPUT_REDIST_SHA256 }}`

Expand Down
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# 輸入框(InputBox)⌨️

[![Windows 11 22H2 (Build 22621+)](https://img.shields.io/badge/作業系統-Windows%2011%2022H2%20(22621%2B)-003A6D?style=for-the-badge)](https://www.microsoft.com/zh-tw/windows)
[![.NET Runtime](https://img.shields.io/badge/Runtime-.NET%2010-512BD4?logo=dotnet&logoColor=white&style=for-the-badge)](https://dotnet.microsoft.com/zh-tw/download/dotnet/10.0)
[![.NET Runtime](https://img.shields.io/badge/Runtime-.NET%2011-512BD4?logo=dotnet&logoColor=white&style=for-the-badge)](https://dotnet.microsoft.com/zh-tw/download/dotnet/11.0)
[![程式語言](https://img.shields.io/badge/程式語言-C%23-1B5E20?style=for-the-badge)](https://learn.microsoft.com/zh-tw/dotnet/csharp/)
[![XInput](https://img.shields.io/badge/遊戲控制器輸入%20API-XInput-107C10?style=for-the-badge)](https://learn.microsoft.com/zh-tw/windows/win32/xinput/getting-started-with-xinput)
[![GameInput](https://img.shields.io/badge/遊戲控制器輸入%20API-GameInput-A84300?style=for-the-badge)](https://learn.microsoft.com/zh-tw/gaming/gdk/docs/features/common/input/overviews/input-overview)
Expand Down Expand Up @@ -521,7 +521,7 @@ dotnet publish -c Release -r win-x64 --self-contained true -p:PublishSingleFile=

發佈完成後,編譯好的單一執行檔會生成在以下路徑:
```
bin\Release\net10.0-windows\publish\win-x64\InputBox.exe
bin\Release\net11.0-windows\publish\win-x64\InputBox.exe
```

### 2. 使用 Visual Studio 發佈 🚀
Expand Down
31 changes: 28 additions & 3 deletions docs/engineering/core-engineering.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# 核心工程與架構標準 (Core Engineering)

- **目標框架**:`.NET 10 (net10.0-windows)`。
- **C# 13 特性**:
- **目標框架**:`.NET 11 (net11.0-windows)`。
- **C# 15 語言版本(LangVersion=15.0)與既有鎖定規範**:
- **執行緒鎖定**:必須使用宣告為 `private readonly Lock _lock = new();` 的專用物件。
- **非同步與 UI 安全 (Threading)**:
- **同步與非同步調度**:
Expand All @@ -22,7 +22,7 @@
- **計算標記**:計算縮放時除數/被除數必須包含 `96.0f` 或 `(float)` 強制轉型,杜絕整數截斷誤差。
- **智慧重定位 (Smart Positioning)**:視窗初始顯示或版面配置擴張時,須執行 `ApplySmartPosition` 螢幕邊界檢查。
- **系統偏好同步**:
- **主題還原**:還原預設配色時應將屬性設為 `Color.Empty`,由 .NET 10 主題引擎自動判斷 (禁:硬式編碼 `SystemColors.Control`)。
- **主題還原**:還原預設配色時應將屬性設為 `Color.Empty`,由 .NET 11 主題引擎自動判斷 (禁:硬式編碼 `SystemColors.Control`)。
- **程式內重啟與前景恢復**:
- **單次啟用標記**:若為本程式主動要求重新啟動,舊執行個體必須先寫入具短時效的一次性啟用標記,供新執行個體在首次顯示時消費;標記必須於讀取後立即清除,避免重複生效。
- **前景授權交接**:由 `RestartProcessLauncher` 自行啟動新執行個體(取代 `Application.Restart()`),並在舊視窗關閉前以 `AllowSetForegroundWindow(新程序 PID)` 只授權該程序搶回前景;不得使用 `ASFW_ANY` 開放給所有程序,僅在無法啟動新程序而退回 `Application.Restart()` 時例外。授權必須在舊視窗仍位於前景時完成,因為控制器操作不會產生 Windows 輸入事件。
Expand All @@ -36,3 +36,28 @@
- **`var` 使用原則**:依 [Microsoft C# 編碼慣例](https://learn.microsoft.com/dotnet/csharp/fundamentals/coding-style/coding-conventions#implicitly-typed-local-variables) 與 [.NET Runtime 程式碼風格](https://github.com/dotnet/runtime/blob/main/docs/coding-guidelines/coding-style.md),僅在型別可由右側直接看出(`new`、明確轉型)時使用 `var`,此時亦可使用 target-typed `new()`;內建型別、方法回傳值與 `foreach` 迴圈變數一律使用明確型別,不以方法或變數名稱推測型別;LINQ 匿名型別等必須使用 `var` 的情況除外。對應設定見 `.editorconfig`(IDE0007/IDE0008)。
- **Release 日誌門檻**:正式版預設只寫入 `Warning` 以上;`Info` 僅供 Debug、測試主機或 `INPUTBOX_LOG_LEVEL=Info` 臨時診斷使用。
- **可行動診斷原則**:正常 lifecycle、成功 probe、成功或略過震動、一般輪詢健康資料應維持 `Info`;會影響使用者操作、裝置可用性、API 呼叫失敗或資料修復失敗的訊號才可升級為 `Warning` 或 `Error`。

## .NET 11 遷移與主題

- SDK 基線由根目錄 global.json 固定為 11.0.100,僅允許同 feature band 的修補更新;主程式、測試與 CI/release 均使用 .NET 11。
- C# 15 使用正式語言版本;集合需要預設容量時可使用 `[with(capacity: count)]`,保留原有容量與元素語意,不為採用新語法改變輸入/輸出行為。
- 保留 `Application.SetColorMode(SystemColorMode.System)`、既有高對比與 Color.Empty 配色還原,並在建立視窗前呼叫 `Application.SetDefaultFormRevealMode(FormRevealMode.Deferred)`,避免初次套用深色主題時閃白。
- 依維護者偏好啟用 `Application.SetDefaultVisualStylesMode(VisualStylesMode.Latest)`,子控制項沿用繼承值。Latest 隨 runtime 解析為最新渲染器,因此 runtime 升級時必須重跑深/淺色、高對比及原生多 DPI UI 矩陣。
- 發行狀態以 [Microsoft 正式下載頁](https://dotnet.microsoft.com/en-us/download/dotnet/11.0) 與 [支援政策](https://dotnet.microsoft.com/en-us/platform/support/policy) 為準:.NET 11.0.0 已於 2026-11-10 正式發布(GA),正式 SDK 為 11.0.100。[WinForms 功能文件](https://learn.microsoft.com/en-us/dotnet/desktop/winforms/whats-new/net110) 的 RC 1 標題描述該階段的功能資訊,不代表 .NET 11 目前仍為 RC。[C# 15 官方文件](https://learn.microsoft.com/en-us/dotnet/csharp/whats-new/csharp-15) 確認 net11.0 預設採用 C# 15,集合建構參數與 union 等正式功能不需 preview。

## C# 15 適用性審查(2026-11-14)

依上述官方版本說明及語言參考,採用能改善現有語意的功能,保留適合的值型別與控制流程。

| 新功能 | 目前實作與判斷 |
|---|---|
| 集合建構參數 | SingleInstanceHandoff 容量配置改用 `[with(capacity: commandLineArgs.Count)]`,保留容量及元素行為。其餘集合多已使用 `[]` 或展開語法,沒有需要批次改寫的等價比較器/容量建構式。 |
| union | PhraseService.ImportOutcome/ExportOutcome 的成功旗標、錯誤碼及計數是可重新建模的候選。語言升級本身不要求改變公開回傳型別、預設值、相等性及解構契約;目前保留既有 record 與測試。未來調整 API 時可拆成成功/失敗 case,避免矛盾狀態。 |
| union 的成本與安全 | 生成的 union 使用 object? 儲存,值型別 case 會裝箱,default 內容為 null。採用時應明確處理 null,避免以 `_` 掩蓋未來新增 case。控制器輪詢、NavigationResult、VibrationProfile 及設定快照維持 record struct/enum,不引入額外配置。 |
| closed 階層 | 沒有僅用於 case 分組且需要窮盡比對的 abstract class/record 階層。WinForms 類別及控制器介面具實際共用行為,維持現有契約。 |
| 具標籤 break/continue | 未發現 goto 或布林旗標跨多層迴圈退出的待簡化模式;既有提前 return/continue 已清楚。 |
| 擴充索引子 | 現有 API 使用 List、IReadOnlyList 或陣列,不為一般 IEnumerable 加入隱藏列舉成本的索引子。 |
| 舊 runtime 的非虛擬 static 介面成員 | 只以 net11.0-windows 為目標,沒有此相容性需求。 |
| 記憶體安全 preview | 不啟用 preview 或 updated-memory-safety-rules,保留原生互通既有 unsafe 審查範圍。 |

取捨依據:[官方 union 參考](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/builtin-types/union)、[官方跳躍語句參考](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/statements/jump-statements)。以上是對目前程式碼的工程評估,並非官方要求所有專案採用新語法。
2 changes: 1 addition & 1 deletion docs/engineering/gamepad-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@
- **GameInput 同步**:InputBox 仍必須在背景 MTA polling thread 建立、存取與釋放 InputWeave `GameInputClient` / `GameInputDevice` / callback registration;callback 只能設定喚醒或重新整理訊號,不得直接觸發 managed UI 命令。
- **GameInput 診斷 metadata 邊界**:runtime probe、timestamp stale counters、missing reading counters、device unavailable refresh counters 只能進入 log、測試或未來診斷快照,不可直接改變 edge detection、Pause/Resume neutral gate 或任何 UI 命令。
- **GameInput subset 範圍**:目前只實作 InputBox 需要的 Gamepad subset:裝置資訊、VID/PID、timestamp、gamepad button state、rumble、device/reading callbacks,以及 gamepad capabilities / extra control metadata。不得在未重新評估安全與產品需求前擴張到 keyboard、mouse、sensors、raw report、force feedback、aggregate device 或 1:1 GameInput wrapper。
- **InputWeave callback 互通性**:repo-local `InputWeave.GameInput` 套件的 `IGameInput.Register*Callback` callback 參數必須使用原生 function pointer 路徑;`net10.0-windows` 可透過 `IntPtr`/unmanaged function pointer vtable wrapper 傳遞 callback,`net48` 則必須以 `MarshalAs(UnmanagedType.FunctionPtr)` 宣告。不得以 InputBox 端 aggregate polling fallback 遮蔽 callback marshaling 錯誤;若列舉或 callback 仍失敗,應走既有 GameInput 初始化失敗與 XInput 退避路徑。
- **InputWeave callback 互通性**:repo-local `InputWeave.GameInput` 套件的 `IGameInput.Register*Callback` callback 參數必須使用原生 function pointer 路徑;`net11.0-windows` 可透過 `IntPtr`/unmanaged function pointer vtable wrapper 傳遞 callback,`net48` 則必須以 `MarshalAs(UnmanagedType.FunctionPtr)` 宣告。不得以 InputBox 端 aggregate polling fallback 遮蔽 callback marshaling 錯誤;若列舉或 callback 仍失敗,應走既有 GameInput 初始化失敗與 XInput 退避路徑。
- **Callback 使用邊界**:GameInput 的 `RegisterDeviceCallback` / `RegisterReadingCallback` 僅可用於要求背景 MTA polling thread 重新整理或喚醒診斷路徑;正式輸入命令仍必須由 60 FPS polling 消費,callback 不得直接觸發 UI、剪貼簿、返回前景或任何輸入動作。
- **GameInput runtime/redist 政策**:`Microsoft.GameInput` NuGet 僅作為官方 SDK、header 與 redist 來源。發佈 ZIP 可隨附 `redist/GameInputRedist.msi` 供使用者手動安裝,但應用程式不得自動執行安裝程式,也不得要求一般啟動流程取得系統管理員權限。
- **Auto 模式解析優先序**:當使用者選擇 Face 鍵 `Auto` 模式且目前提供者為 **GameInput** 時,必須先使用較穩定的硬體識別資訊(例如 VID/PID、產品家族名稱)判斷裝置類型,再退回裝置名稱關鍵字比對;像 `Wireless`、`Bluetooth`、`Adapter`、`Receiver` 等連線詞應視為雜訊而忽略。
Expand Down
2 changes: 2 additions & 0 deletions docs/engineering/localization.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,3 +14,5 @@
- 允許在 Designer 中硬式編碼正體中文以供預覽。
- 執行階段必須透過 `ApplyLocalization` 再次賦值以確保多語系正確性。
- 嚴禁手動修改 `MainForm.Designer.cs` 中自動生成的版面配置結構。

- **Xbox 模式術語**:Windows 的 Xbox 使用模式統一為「Xbox 模式」(zh-Hant/zh-Hans)、Xbox mode(en)、Xbox-Modus(de)、mode Xbox(fr)、Xbox モード(ja)、Xbox 모드(ko)。此術語適用於應用程式、文件與網站;控制器主按鍵配置中的 Xbox 名稱維持不變。
2 changes: 1 addition & 1 deletion docs/engineering/testing.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@

- **框架**:[xUnit v3](https://xunit.net/)(選用理由:每個 `[Fact]` 獨立實例化、`IDisposable` 自動呼叫、語法精簡)。
- **測試專案路徑**:`tests/InputBox.Tests/InputBox.Tests.csproj`
- **目標框架**:`net10.0-windows`(與主專案一致,僅支援 Windows)。
- **目標框架**:`net11.0-windows`(與主專案一致,僅支援 Windows)。
- **InternalsVisibleTo**:主專案透過 `<AssemblyAttribute>` 授予測試專案存取 `internal` 類別的權限,無需建立手動的 `AssemblyInfo.cs`。

## 2. 執行測試
Expand Down
5 changes: 5 additions & 0 deletions global.json
Original file line number Diff line number Diff line change
@@ -1,4 +1,9 @@
{
"sdk": {
"version": "11.0.100",
"rollForward": "latestPatch",
Comment on lines +3 to +4
"allowPrerelease": false
},
"test": {
"runner": "Microsoft.Testing.Platform"
}
Expand Down
4 changes: 2 additions & 2 deletions src/InputBox/Core/Input/GameInputGamepadController.cs
Original file line number Diff line number Diff line change
Expand Up @@ -2097,8 +2097,8 @@ private void StartDeviceDiscovery(int pollingGeneration = 0)
/// <param name="pollingGeneration">目前輪詢迴圈的世代編號。</param>
private void CheckAndApplyDiscoveryResults(int pollingGeneration = 0)
{
Task<IReadOnlyList<GameInputDevice>>? task = null;
long capturedVersion = 0;
Task<IReadOnlyList<GameInputDevice>>? task;
long capturedVersion;

lock (_discoveryLock)
{
Expand Down
8 changes: 4 additions & 4 deletions src/InputBox/Core/Interop/DllResolver.cs
Original file line number Diff line number Diff line change
Expand Up @@ -22,13 +22,13 @@ internal class DllResolver
/// 自訂的 native 載入解析器,用於覆寫 XInput 的載入邏輯。
/// </summary>
/// <param name="libraryName">開啟端要求載入的 DLL 名稱</param>
/// <param name="assembly">觸發載入的組件。</param>
/// <param name="searchPath">DllImportSearchPath 設定。</param>
/// <param name="_1">觸發載入的組件。</param>
/// <param name="_2">DllImportSearchPath 設定。</param>
/// <returns>成功載入時回傳 DLL handle;若無法載入或名稱不符則回傳 IntPtr.Zero。</returns>
public static nint ResolveNativeLibrary(
string libraryName,
Assembly assembly,
DllImportSearchPath? searchPath)
Assembly _1,
DllImportSearchPath? _2)
{
// 僅攔截 xinput1_4.dll,其餘 DLL 交由系統處理。
if (!libraryName.Equals("xinput1_4.dll", StringComparison.OrdinalIgnoreCase))
Expand Down
2 changes: 1 addition & 1 deletion src/InputBox/Core/Services/SingleInstanceHandoff.cs
Original file line number Diff line number Diff line change
Expand Up @@ -116,7 +116,7 @@ public static IReadOnlyList<string> RemoveHandoffArguments(IReadOnlyList<string>
{
ArgumentNullException.ThrowIfNull(commandLineArgs);

List<string> result = new(commandLineArgs.Count);
List<string> result = [with(capacity: commandLineArgs.Count)];

for (int i = 0; i < commandLineArgs.Count; i++)
{
Expand Down
3 changes: 2 additions & 1 deletion src/InputBox/InputBox.csproj
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,8 @@

<PropertyGroup>
<OutputType>WinExe</OutputType>
<TargetFramework>net10.0-windows</TargetFramework>
<TargetFramework>net11.0-windows</TargetFramework>
<LangVersion>15.0</LangVersion>
<EnableWindowsTargeting>true</EnableWindowsTargeting>
<Nullable>enable</Nullable>
<UseWindowsForms>true</UseWindowsForms>
Expand Down
4 changes: 2 additions & 2 deletions src/InputBox/MainForm.Gamepad.cs
Original file line number Diff line number Diff line change
Expand Up @@ -2141,7 +2141,7 @@ private void PushUndoSnapshot()

// 與上一份快照相同,不重複儲存。
if (_undoStack.Count > 0 &&
_undoStack[_undoStack.Count - 1] == current)
_undoStack[^1] == current)
{
return;
}
Expand All @@ -2166,7 +2166,7 @@ private void HandleUndoAction()
// 優先使用快照堆疊(覆蓋 B 清空、歷程導覽等程式賦值後的還原)。
if (_undoStack.Count > 0)
{
string previous = _undoStack[_undoStack.Count - 1];
string previous = _undoStack[^1];

_undoStack.RemoveAt(_undoStack.Count - 1);

Expand Down
3 changes: 3 additions & 0 deletions src/InputBox/Program.cs
Original file line number Diff line number Diff line change
Expand Up @@ -200,7 +200,10 @@ static void Main()
// To customize application configuration such as set high DPI settings or default font,
// see https://aka.ms/applicationconfiguration.
ApplicationConfiguration.Initialize();
Application.SetDefaultVisualStylesMode(VisualStylesMode.Latest);
Application.SetColorMode(SystemColorMode.System);
// 等待初次版面與主題套用完成,避免深色模式啟動時閃白。
Application.SetDefaultFormRevealMode(FormRevealMode.Deferred);

// 載入設定檔(若無檔案會自動建立)。
AppSettings.Load();
Expand Down
2 changes: 1 addition & 1 deletion tests/InputBox.Tests/AnnouncementServiceTests.cs
Original file line number Diff line number Diff line change
Expand Up @@ -102,7 +102,7 @@ public void Dispose_CalledMultipleTimes_DoesNotThrow()
{
_svc = new AnnouncementService(async (_, _, _) => await Task.CompletedTask);

var capturedException = Record.Exception(() =>
Exception? capturedException = Record.Exception(() =>
{
_svc.Dispose();
_svc.Dispose();
Expand Down
Loading
Loading