[Breaking change] chore: method ToControllerWith() instead of null check in ToController()

moomiji · moomiji · commit f31de206a46d · 2025-11-09T00:25:37.000+08:00
diff --git a/src/MaaFramework.Binding.Native/Extensions/AdbDeviceInfoExtensions.cs b/src/MaaFramework.Binding.Native/Extensions/AdbDeviceInfoExtensions.cs
@@ -19,39 +19,36 @@ public static class AdbDeviceInfoExtensions
     /// <param name="check">Checks LinkStart().Wait() status if <see cref="CheckStatusOption.ThrowIfNotSucceeded"/>; otherwise, not check.</param>
     /// <returns>A MaaAdbController.</returns>
     /// <exception cref="ArgumentNullException"/>
-    public static MaaAdbController ToAdbController(this AdbDeviceInfo info,
+    public static MaaAdbController ToAdbControllerWith(this AdbDeviceInfo info,
         string? adbPath = null,
         string? adbSerial = null,
         AdbScreencapMethods? screencapMethods = null,
         AdbInputMethods? inputMethods = null,
         string? config = null,
-        string agentPath = "./MaaAgentBinary",
+        string? agentPath = null,
         LinkOption link = LinkOption.Start,
         CheckStatusOption check = CheckStatusOption.ThrowIfNotSucceeded)
     {
         ArgumentNullException.ThrowIfNull(info);
 
-        if (adbPath is null
-            && adbSerial is null
-            && screencapMethods is null
-            && inputMethods is null
-            && config is null)
-        {
-            return new MaaAdbController(info, agentPath, link, check);
-        }
-
         return new MaaAdbController(
             new AdbDeviceInfo(
                 info.Name,
                 adbPath ?? info.AdbPath,
                 adbSerial ?? info.AdbSerial,
                 screencapMethods ?? info.ScreencapMethods,
                 inputMethods ?? info.InputMethods,
-                config ?? info.Config
+                config ?? info.Config,
+                agentPath ?? info.AgentPath
             ),
-            agentPath,
             link,
             check
         );
     }
+
+    /// <inheritdoc cref="ToAdbControllerWith(AdbDeviceInfo, string?, string?, AdbScreencapMethods?, AdbInputMethods?, string?, string?, LinkOption, CheckStatusOption)"/>
+    public static MaaAdbController ToAdbController(this AdbDeviceInfo info,
+            LinkOption link = LinkOption.Start,
+            CheckStatusOption check = CheckStatusOption.ThrowIfNotSucceeded)
+        => new(info, link, check);
 }
diff --git a/src/MaaFramework.Binding.Native/Extensions/DesktopWindowInfoExtensions.cs b/src/MaaFramework.Binding.Native/Extensions/DesktopWindowInfoExtensions.cs
@@ -17,18 +17,38 @@ public static class DesktopWindowInfoExtensions
     /// <param name="check">Checks LinkStart().Wait() status if <see cref="CheckStatusOption.ThrowIfNotSucceeded"/>; otherwise, not check.</param>
     /// <returns>A MaaWin32Controller.</returns>
     /// <exception cref="ArgumentNullException"/>
-    public static MaaWin32Controller ToWin32Controller(this DesktopWindowInfo info,
-        Win32ScreencapMethod screencapMethod,
-        Win32InputMethod mouseMethod,
-        Win32InputMethod keyboardMethod,
+    public static MaaWin32Controller ToWin32ControllerWith(this DesktopWindowInfo info,
+        Win32ScreencapMethod? screencapMethod = null,
+        Win32InputMethod? mouseMethod = null,
+        Win32InputMethod? keyboardMethod = null,
         nint? hWnd = null,
         LinkOption link = LinkOption.Start,
         CheckStatusOption check = CheckStatusOption.ThrowIfNotSucceeded)
     {
         ArgumentNullException.ThrowIfNull(info);
 
-        return hWnd.HasValue
-            ? new MaaWin32Controller(hWnd.Value, screencapMethod, mouseMethod, keyboardMethod, link, check)
-            : new MaaWin32Controller(info, screencapMethod, mouseMethod, keyboardMethod, link, check);
+        var handle = hWnd ?? info.Handle;
+        return new MaaWin32Controller(
+            new DesktopWindowInfo(
+                handle,
+                handle == info.Handle ? info.Name : string.Empty,
+                handle == info.Handle ? info.ClassName : string.Empty,
+                screencapMethod ?? info.ScreencapMethod,
+                mouseMethod ?? info.MouseMethod,
+                keyboardMethod ?? info.KeyboardMethod
+            ),
+            link,
+            check
+        );
+    }
+
+    /// <inheritdoc cref="ToWin32ControllerWith(DesktopWindowInfo, Win32ScreencapMethod?, Win32InputMethod?, Win32InputMethod?, nint?, LinkOption, CheckStatusOption)"/>
+    public static MaaWin32Controller ToWin32Controller(this DesktopWindowInfo info,
+        LinkOption link = LinkOption.Start,
+        CheckStatusOption check = CheckStatusOption.ThrowIfNotSucceeded)
+    {
+        ArgumentNullException.ThrowIfNull(info);
+
+        return new MaaWin32Controller(info, link, check);
     }
 }
diff --git a/src/MaaFramework.Binding.Native/MaaController/MaaAdbController.cs b/src/MaaFramework.Binding.Native/MaaController/MaaAdbController.cs
@@ -11,44 +11,39 @@ namespace MaaFramework.Binding;
 public class MaaAdbController : MaaController
 {
     private readonly AdbDeviceInfo _debugInfo;
-    private readonly string _debugAgentPath;
 
     [ExcludeFromCodeCoverage(Justification = "Debugger display.")]
     [DebuggerBrowsable(DebuggerBrowsableState.Never)]
     private string DebuggerDisplay => IsInvalid
         ? $"Invalid {GetType().Name}"
-        : $"{GetType().Name} {{ {nameof(_debugInfo.Name)} = {_debugInfo.Name}, {nameof(_debugInfo.AdbSerial)} = {_debugInfo.AdbSerial}, {nameof(_debugInfo.ScreencapMethods)} = {_debugInfo.ScreencapMethods}, {nameof(_debugInfo.InputMethods)} = {_debugInfo.InputMethods}, AgentPath = {_debugAgentPath} }}";
+        : $"{GetType().Name} {{ {nameof(_debugInfo.Name)} = {_debugInfo.Name}, {nameof(_debugInfo.AdbSerial)} = {_debugInfo.AdbSerial}, {nameof(_debugInfo.ScreencapMethods)} = {_debugInfo.ScreencapMethods}, {nameof(_debugInfo.InputMethods)} = {_debugInfo.InputMethods}, AgentPath = {_debugInfo.AgentPath} }}";
 
     /// <summary>
     ///     Creates a <see cref="MaaAdbController"/> instance.
     /// </summary>
-    /// <param name="adbDevice">The adb device info.</param>
-    /// <param name="agentPath">The path of agent directory. Default is "./MaaAgentBinary" if package "Maa.Framework" or "Maa.AgentBinary" is used.</param>
+    /// <param name="info">The adb device info.</param>
     /// <param name="link">Executes <see cref="IMaaController.LinkStart"/> if <see cref="LinkOption.Start"/>; otherwise, not link.</param>
     /// <param name="check">Checks LinkStart().Wait() status if <see cref="CheckStatusOption.ThrowIfNotSucceeded"/>; otherwise, not check.</param>
     /// <remarks>
     ///     Wrapper of <see cref="MaaAdbControllerCreate"/>.
     /// </remarks>
     /// <exception cref="ArgumentException"/>
     /// <exception cref="MaaJobStatusException"/>
-    public MaaAdbController(AdbDeviceInfo adbDevice, string agentPath = "./MaaAgentBinary", LinkOption link = LinkOption.Start, CheckStatusOption check = CheckStatusOption.ThrowIfNotSucceeded)
+    public MaaAdbController(AdbDeviceInfo info, LinkOption link = LinkOption.Start, CheckStatusOption check = CheckStatusOption.ThrowIfNotSucceeded)
     {
-        ArgumentException.ThrowIfNullOrEmpty(adbDevice.AdbPath);
-        ArgumentException.ThrowIfNullOrEmpty(adbDevice.AdbSerial);
-        if (adbDevice.ScreencapMethods == AdbScreencapMethods.None) throw new ArgumentException($"Value cannot be {AdbScreencapMethods.None}.", "adbDevice.ScreencapMethods");
-        if (adbDevice.InputMethods == AdbInputMethods.None) throw new ArgumentException($"Value cannot be {AdbInputMethods.None}.", "adbDevice.InputMethods");
-        ArgumentException.ThrowIfNullOrEmpty(adbDevice.Config);
-        ArgumentException.ThrowIfNullOrEmpty(agentPath);
+        ArgumentException.ThrowIfNullOrEmpty(info.AdbPath);
+        ArgumentException.ThrowIfNullOrEmpty(info.AdbSerial);
+        ArgumentException.ThrowIfNullOrEmpty(info.Config);
+        ArgumentException.ThrowIfNullOrEmpty(info.AgentPath);
 
-        var handle = MaaAdbControllerCreate(adbDevice.AdbPath, adbDevice.AdbSerial, (MaaAdbScreencapMethod)adbDevice.ScreencapMethods, (MaaAdbInputMethod)adbDevice.InputMethods, adbDevice.Config, agentPath);
+        var handle = MaaAdbControllerCreate(info.AdbPath, info.AdbSerial, (MaaAdbScreencapMethod)info.ScreencapMethods, (MaaAdbInputMethod)info.InputMethods, info.Config, info.AgentPath);
         _ = MaaControllerAddSink(Handle, MaaEventCallback, nint.Zero);
         SetHandle(handle, needReleased: true);
 
-        _debugInfo = adbDevice;
-        _debugAgentPath = agentPath;
+        _debugInfo = info;
 
         if (link == LinkOption.Start)
-            LinkStartOnConstructed(check, adbDevice, _debugAgentPath);
+            LinkStartOnConstructed(check, info);
     }
 
     /// <param name="adbPath">The path of adb executable file.</param>
@@ -59,10 +54,9 @@ public MaaAdbController(AdbDeviceInfo adbDevice, string agentPath = "./MaaAgentB
     /// <param name="agentPath">The path of agent directory. Default is "./MaaAgentBinary" if package "Maa.Framework" or "Maa.AgentBinary" is used.</param>
     /// <param name="link">Executes <see cref="IMaaController.LinkStart"/> if <see cref="LinkOption.Start"/>; otherwise, not link.</param>
     /// <param name="check">Checks LinkStart().Wait() status if <see cref="CheckStatusOption.ThrowIfNotSucceeded"/>; otherwise, not check.</param>
-    /// <inheritdoc cref="Binding.MaaAdbController(AdbDeviceInfo, string, LinkOption, CheckStatusOption)"/>
+    /// <inheritdoc cref="Binding.MaaAdbController(AdbDeviceInfo, LinkOption, CheckStatusOption)"/>
     public MaaAdbController(string adbPath, string adbSerial, AdbScreencapMethods screencapMethods, AdbInputMethods inputMethods, [StringSyntax("Json")] string config = "{}", string agentPath = "./MaaAgentBinary", LinkOption link = LinkOption.Start, CheckStatusOption check = CheckStatusOption.ThrowIfNotSucceeded)
-        : this(new AdbDeviceInfo(string.Empty, adbPath, adbSerial, screencapMethods, inputMethods, config),
-            agentPath, link, check)
+        : this(new AdbDeviceInfo(string.Empty, adbPath, adbSerial, screencapMethods, inputMethods, config, agentPath), link, check)
     {
     }
 }
diff --git a/src/MaaFramework.Binding.Native/MaaController/MaaWin32Controller.cs b/src/MaaFramework.Binding.Native/MaaController/MaaWin32Controller.cs
@@ -11,47 +11,36 @@ namespace MaaFramework.Binding;
 public class MaaWin32Controller : MaaController
 {
     private readonly DesktopWindowInfo _debugInfo;
-    private readonly Win32ScreencapMethod _debugScreencapMethod;
-    private readonly Win32InputMethod _debugMouseMethod;
-    private readonly Win32InputMethod _debugKeyboardMethod;
 
     [ExcludeFromCodeCoverage(Justification = "Debugger display.")]
     [DebuggerBrowsable(DebuggerBrowsableState.Never)]
     private string DebuggerDisplay => IsInvalid
         ? $"Invalid {GetType().Name}"
-        : $"{GetType().Name} {{ {nameof(_debugInfo.Name)} = {_debugInfo.Name}, {nameof(_debugInfo.ClassName)} = {_debugInfo.ClassName}, ScreencapMethod = {_debugScreencapMethod}, MouseMethod = {_debugMouseMethod}, KeyboardMethod = {_debugKeyboardMethod} }}";
+        : $"{GetType().Name} {{ {nameof(_debugInfo.Name)} = {_debugInfo.Name}, {nameof(_debugInfo.ClassName)} = {_debugInfo.ClassName}, ScreencapMethod = {_debugInfo.ScreencapMethod}, MouseMethod = {_debugInfo.MouseMethod}, KeyboardMethod = {_debugInfo.KeyboardMethod} }}";
 
     /// <summary>
     ///     Creates a <see cref="MaaWin32Controller"/> instance.
     /// </summary>
-    /// <param name="desktopWindow">The desktop window info.</param>
-    /// <param name="screencapMethod">The screencap method.</param>
-    /// <param name="mouseMethod">The mouse method.</param>
-    /// <param name="keyboardMethod">The keyboard method.</param>
+    /// <param name="info">The desktop window info.</param>
     /// <param name="link">Executes <see cref="IMaaController.LinkStart"/> if <see cref="LinkOption.Start"/>; otherwise, not link.</param>
     /// <param name="check">Checks LinkStart().Wait() status if <see cref="CheckStatusOption.ThrowIfNotSucceeded"/>; otherwise, not check.</param>
     /// <remarks>
     ///     Wrapper of <see cref="MaaWin32ControllerCreate"/>.
     /// </remarks>
     /// <exception cref="ArgumentException"/>
     /// <exception cref="MaaJobStatusException"/>
-    public MaaWin32Controller(DesktopWindowInfo desktopWindow, Win32ScreencapMethod screencapMethod, Win32InputMethod mouseMethod, Win32InputMethod keyboardMethod, LinkOption link = LinkOption.Start, CheckStatusOption check = CheckStatusOption.ThrowIfNotSucceeded)
+    public MaaWin32Controller(DesktopWindowInfo info, LinkOption link = LinkOption.Start, CheckStatusOption check = CheckStatusOption.ThrowIfNotSucceeded)
     {
-        if (screencapMethod == Win32ScreencapMethod.None) throw new ArgumentException($"Value cannot be {Win32ScreencapMethod.None}.", nameof(screencapMethod));
-        if (mouseMethod == Win32InputMethod.None) throw new ArgumentException($"Value cannot be {Win32InputMethod.None}.", nameof(mouseMethod));
-        if (keyboardMethod == Win32InputMethod.None) throw new ArgumentException($"Value cannot be {Win32InputMethod.None}.", nameof(keyboardMethod));
+        if (info.Handle == nint.Zero) throw new ArgumentException("Value cannot be zero.", "info.Handle");
 
-        var handle = MaaWin32ControllerCreate(desktopWindow.Handle, (MaaWin32ScreencapMethod)screencapMethod, (MaaWin32InputMethod)mouseMethod, (MaaWin32InputMethod)keyboardMethod);
+        var handle = MaaWin32ControllerCreate(info.Handle, (MaaWin32ScreencapMethod)info.ScreencapMethod, (MaaWin32InputMethod)info.MouseMethod, (MaaWin32InputMethod)info.KeyboardMethod);
         _ = MaaControllerAddSink(Handle, MaaEventCallback, nint.Zero);
         SetHandle(handle, needReleased: true);
 
-        _debugInfo = desktopWindow;
-        _debugScreencapMethod = screencapMethod;
-        _debugMouseMethod = mouseMethod;
-        _debugKeyboardMethod = keyboardMethod;
+        _debugInfo = info;
 
         if (link == LinkOption.Start)
-            LinkStartOnConstructed(check, desktopWindow, screencapMethod, mouseMethod, keyboardMethod);
+            LinkStartOnConstructed(check, info);
     }
 
     /// <param name="hWnd">The handle to a win32 window.</param>
@@ -60,10 +49,9 @@ public MaaWin32Controller(DesktopWindowInfo desktopWindow, Win32ScreencapMethod
     /// <param name="keyboardMethod">The keyboard method.</param>
     /// <param name="link">Executes <see cref="IMaaController.LinkStart"/> if <see cref="LinkOption.Start"/>; otherwise, not link.</param>
     /// <param name="check">Checks LinkStart().Wait() status if <see cref="CheckStatusOption.ThrowIfNotSucceeded"/>; otherwise, not check.</param>
-    /// <inheritdoc cref="Binding.MaaWin32Controller(DesktopWindowInfo, Win32ScreencapMethod, Win32InputMethod, Win32InputMethod, LinkOption, CheckStatusOption)"/>
+    /// <inheritdoc cref="Binding.MaaWin32Controller(DesktopWindowInfo, LinkOption, CheckStatusOption)"/>
     public MaaWin32Controller(nint hWnd, Win32ScreencapMethod screencapMethod, Win32InputMethod mouseMethod, Win32InputMethod keyboardMethod, LinkOption link = LinkOption.Start, CheckStatusOption check = CheckStatusOption.ThrowIfNotSucceeded)
-        : this(new DesktopWindowInfo(hWnd, string.Empty, string.Empty),
-            screencapMethod, mouseMethod, keyboardMethod, link, check)
+        : this(new DesktopWindowInfo(hWnd, string.Empty, string.Empty, screencapMethod, mouseMethod, keyboardMethod), link, check)
     {
     }
 }
diff --git a/src/MaaFramework.Binding.UnitTests/Test_IMaaToolkit.cs b/src/MaaFramework.Binding.UnitTests/Test_IMaaToolkit.cs
@@ -60,7 +60,7 @@ public void Interface_AdbDevice(MaaTypes type, IMaaToolkit maaToolkit, string ar
 
         using var maaController = type switch
         {
-            MaaTypes.Native => devices[0].ToAdbController(
+            MaaTypes.Native => devices[0].ToAdbControllerWith(
                 adbPath: Common.AdbPath,
                 screencapMethods: AdbScreencapMethods.Encode,
                 inputMethods: AdbInputMethods.AdbShell,
@@ -102,7 +102,7 @@ private static void Test_Win32_WindowInfos(MaaTypes type, IList<DesktopWindowInf
 
         using var maaController = type switch
         {
-            MaaTypes.Native => windows[0].ToWin32Controller(
+            MaaTypes.Native => windows[0].ToWin32ControllerWith(
                 screencapMethod: Win32ScreencapMethod.GDI,
                 mouseMethod: Win32InputMethod.SendMessage,
                 keyboardMethod: Win32InputMethod.SendMessage,
@@ -117,7 +117,7 @@ private static void Test_Win32_WindowInfos(MaaTypes type, IList<DesktopWindowInf
 #if MAA_WIN32
         using var optionalArgumentDefaultValuesTest = type switch
         {
-            MaaTypes.Native => windows[0].ToWin32Controller(
+            MaaTypes.Native => windows[0].ToWin32ControllerWith(
                 screencapMethod: Win32ScreencapMethod.GDI,
                 mouseMethod: Win32InputMethod.SendMessage,
                 keyboardMethod: Win32InputMethod.SendMessage),
diff --git a/src/MaaFramework.Binding/Infos/AdbDeviceInfo.cs b/src/MaaFramework.Binding/Infos/AdbDeviceInfo.cs
@@ -11,11 +11,13 @@ namespace MaaFramework.Binding;
 /// <param name="ScreencapMethods">Gets the <see cref="AdbScreencapMethods"/> of a device.</param>
 /// <param name="InputMethods">Gets the <see cref="AdbInputMethods"/> of a device.</param>
 /// <param name="Config">Gets the config of a device.</param>
+/// <param name="AgentPath">The path of agent directory. Default is "./MaaAgentBinary" if package "Maa.Framework" or "Maa.AgentBinary" is used.</param>
 public record AdbDeviceInfo(
     string Name,
     string AdbPath,
     string AdbSerial,
     AdbScreencapMethods ScreencapMethods,
     AdbInputMethods InputMethods,
-    [StringSyntax("Json")] string Config
+    [StringSyntax("Json")] string Config,
+    string AgentPath = "./MaaAgentBinary"
 );
diff --git a/src/MaaFramework.Binding/Infos/DesktopWindowInfo.cs b/src/MaaFramework.Binding/Infos/DesktopWindowInfo.cs
@@ -6,8 +6,14 @@
 /// <param name="Handle">Gets the handle to a window.</param>
 /// <param name="Name">Gets the window name.</param>
 /// <param name="ClassName">Gets the window class name.</param>
+/// <param name="ScreencapMethod">The screencap method.</param>
+/// <param name="MouseMethod">The mouse method.</param>
+/// <param name="KeyboardMethod">The keyboard method.</param>
 public record DesktopWindowInfo(
     nint Handle,
     string Name,
-    string ClassName
+    string ClassName,
+    Win32ScreencapMethod ScreencapMethod = Win32ScreencapMethod.DXGIDesktopDup,
+    Win32InputMethod MouseMethod = Win32InputMethod.Seize,
+    Win32InputMethod KeyboardMethod = Win32InputMethod.Seize
 );
