Xshell 脚本常用函数及参数规范

本文档介绍 Xshell 脚本中常用的函数及其参数，旨在提供一个清晰、规范的参考，帮助开发者编写更可靠、易维护的脚本。

1. xsh.Screen 对象

xsh.Screen 对象代表 Xshell 的终端屏幕，用于与屏幕进行交互，是脚本操作的核心。

1.1 xsh.Screen.Send(string)

• 功能: 向终端发送文本，模拟键盘输入。

• 参数:

  • string (必需): 要发送的字符串。

• 返回值: 无

• 注意: Send 方法本身不执行命令，需要配合发送回车符（如 VbCr）。

• 示例:

  xsh.Screen.Send "ls -l"      ' 发送命令文本
  xsh.Screen.Send VbCr        ' 发送回车符，执行命令
  xsh.Screen.Send "MyPassword" & VbCr ' 发送密码并回车（强烈不推荐明文密码！）
  

1.2 xsh.Screen.WaitForString(string, [timeout])

• 功能: 等待终端屏幕出现指定的字符串。

• 参数:

  • string (必需): 要等待的字符串。
  • timeout (可选): 超时时间（秒）。默认无限期等待。

• 返回值:

  • True: 如果找到字符串。
  • False: 如果超时或发生错误。

• 示例:

  If xsh.Screen.WaitForString("password:", 10) Then
      xsh.Screen.Send "MyPassword" & VbCr
  Else
      MsgBox "等待密码提示超时！"
  End If
  

1.3 xsh.Screen.Get(row, col, length)

• 功能: 获取终端屏幕上指定位置的文本。

• 参数:

  • row (必需): 行号（从 1 开始）。
  • col (必需): 列号（从 1 开始）。
  • length (必需): 要获取的字符数。

• 返回值: 获取到的字符串。

• 示例:

  Dim screenText
  screenText = xsh.Screen.Get(1, 1, 80)  ' 获取第一行前 80 个字符
  MsgBox "第一行文本: " & screenText
  

1.4 xsh.Screen.Match(pattern, [row], [col])

• 功能: 使用正则表达式在屏幕上查找匹配项。

• 参数:

  • pattern (必需): 正则表达式字符串。
  • row (可选): 开始搜索的行号，默认为 1。
  • col (可选): 开始搜索的列号，默认为 1。

• 返回值:

  • 找到匹配项: 返回一个匹配对象 (Match Object)。
  • 未找到匹配项: 返回 Null。

• Match Object属性

  • Value:匹配到的完整字符串.
  • FirstIndex:匹配字符串在屏幕文本中的起始位置.
  • Length:匹配字符串的长度.
  • SubMatches:一个集合,包含了正则表达式中捕获组的内容.

• 示例:

  Dim match
  Set match = xsh.Screen.Match("([0-9]+)\s+files", 1, 1)
  If Not IsNull(match) Then
    MsgBox "找到 " & match.SubMatches(0) & " 个文件" ' 获取第一个捕获组的内容
     MsgBox "匹配的完整文本是: "& match.Value
  End If
  
  

1.5 xsh.Screen.Clear()

• 功能: 清除终端屏幕内容。

• 参数: 无

• 返回值: 无

• 示例:

  xsh.Screen.Clear()
  

1.6. xsh.Screen.Rows 和 xsh.Screen.Columns

• 功能:

  • xsh.Screen.Rows: 获取终端屏幕的行数。
  • xsh.Screen.Columns: 获取终端屏幕的列数。

• 参数: 无

• 返回值: 整数 (行数或列数)

• 示例:

  Dim rows, cols
  rows = xsh.Screen.Rows
  cols = xsh.Screen.Columns
  MsgBox "终端尺寸：" & rows & " 行 x " & cols & " 列"
  

2. xsh.Dialog 对象

xsh.Dialog 对象用于创建和显示对话框。

2.1 xsh.Dialog.MsgBox(prompt, [buttons], [title], [context], [helpfile])

• 功能: 显示一个消息框。

• 参数:

  • prompt (必需): 要显示的消息文本。
  • buttons (可选): 按钮组合，VBScript 常量 (如 vbOKOnly, vbYesNo, vbOKCancel 等)。 默认是vbOKOnly。
  • title (可选): 消息框的标题。
  • context (可选): 帮助文件上下文 ID。
  • helpfile (可选): 帮助文件路径。

• 返回值: 用户点击的按钮对应的 VBScript 常量 (如 vbOK, vbCancel, vbYes, vbNo 等)。

• 示例

  Dim result
    result = xsh.Dialog.MsgBox("是否继续？", vbYesNo + vbQuestion, "确认")
    If result = vbYes Then
        ' 继续执行
    Else
         ' 取消操作
    End if
  

3. xsh.Session 对象

xsh.Session 对象代表当前的 Xshell 会话，用于控制会话连接、日志等。

3.1 xsh.Session.Sleep(milliseconds)

• 功能: 暂停脚本执行指定的毫秒数。

• 参数:

  • milliseconds (必需): 要暂停的毫秒数。

• 返回值: 无

• 示例:

  xsh.Session.Sleep(1000)  ' 暂停 1 秒 (1000 毫秒)
  

3.2. xsh.Session.LogFilePath

• 功能: 获取或设置会话日志文件的路径。

• 参数:

  • 设置时:传入文件路径字符串。

• 返回值:

  • 获取时:返回文件路径字符串。

• 示例:

  ' 设置日志文件路径
  xsh.Session.LogFilePath = "C:\MyLogs\session.log"
  ' 获取日志文件路径
  Dim logPath
  logPath = xsh.Session.LogFilePath
  

3.3. xsh.Session.LogStart 和 xsh.Session.LogStop

• 功能:
  • xsh.Session.LogStart: 开始记录会话日志。
  • xsh.Session.LogStop: 停止记录会话日志。
• 参数:无
• 返回值: 无
• 示例:

   xsh.Session.LogStart  ' 开始记录日志
   ' ... 执行一些操作 ...
   xsh.Session.LogStop   ' 停止记录日志

3.4. xsh.Session.Connect(connectString)

• 功能: 连接到指定的会话。

• 参数:

  • connectString (必需): 连接字符串，指定连接协议、主机、端口、用户名、密码等信息。

• 返回值: 无 (连接失败会引发异常)

• 示例:

  ' SSH 连接 (强烈不推荐明文密码！)
  xsh.Session.Connect "ssh://user:password@host:port"
   ' 使用 SSH 密钥连接（推荐）
  xsh.Session.Connect "ssh://user@host:port /keyfile=C:\MyKeys\id_rsa"
  ' 串口连接
  xsh.Session.Connect "/COM=COM1 /BAUD=115200"
  

  安全提示： 尽可能避免在连接字符串中使用明文密码。

3.5 xsh.Session.Disconnect()

• 功能:断开当前的会话连接。

• 参数:无

• 返回值: 无

• 示例:

  xsh.Session.Disconnect
  

4. VBScript 内置函数和对象 (补充)

Xshell 脚本基于 VBScript，可以使用大多数 VBScript 内置函数和对象。

• 常用字符串函数: Left, Right, Mid, InStr, Len, Trim, LCase, UCase, Replace, Split, Join

• 常用日期/时间函数: Now, Date, Time, Year, Month, Day, Hour, Minute, Second, DateDiff, DateAdd

• CreateObject: 创建 COM 对象（例如，Scripting.FileSystemObject 用于文件操作）。

  Dim fso, file
  Set fso = CreateObject("Scripting.FileSystemObject")
  Set file = fso.CreateTextFile("C:\test.txt", True)
  file.WriteLine "Hello, Xshell!"
  file.Close
  Set file = Nothing
  Set fso = Nothing
  

• InputBox:创建用户输入对话框.

  Dim userInput
  userInput = InputBox("请输入您的名字：", "输入", "默认值")
  If userInput <> "" Then
     MsgBox "您好，" & userInput & "！"
  End If
  

5. 编码规范建议

• 使用有意义的变量名。
• 添加注释，解释代码的功能和逻辑。
• 适当缩进，提高代码可读性。
• 将重复的代码块提取为函数或子程序。
• 错误处理: 使用 On Error Resume Next 和 Err 对象来处理可能出现的错误，避免脚本意外终止。
• 安全: 避免在脚本中存储敏感信息（如密码），使用更安全的方式（如 SSH 密钥）。
• 模块化: 如果脚本较长，考虑将其拆分为多个模块或文件。
• 测试: 在不同的环境下充分测试你的脚本。

' 示例：良好的错误处理
On Error Resume Next  ' 开启错误处理

xsh.Session.Connect "ssh://user@example.com" ' 假设这里可能出错

If Err.Number <> 0 Then  ' 检查是否有错误发生
    MsgBox "连接错误：" & Err.Description, vbCritical, "错误"
    Err.Clear          ' 清除错误
    On Error GoTo 0    ' 恢复默认错误处理（停止脚本）
    Exit Sub           ' 退出当前子程序
End If

On Error GoTo 0 ' 恢复默认的错误处理