ARTICLE DETAIL

资讯详情

深耕网站视觉设计与运营推广的一线实战洞察。

mRemoteNG 外部工具变量参考:连接属性动态注入与转义规则完全指南

mRemoteNG 外部工具变量参考:连接属性动态注入与转义规则完全指南 桌面应用网络【免费下载链接】mRemoteNGmRemoteNG is the next generation of mRemote, open source, tabbed, multi-protocol, remote connections manager.项目地址https://gitcode.com/gh_mirrors/mr/mRemoteNG点击查看免费下载mRemoteNG 的变量Variables也称参数是打通当前连接信息与外部程序的桥梁在 External Tools外部工具的 Filename 与 Arguments 字段中写入%HOSTNAME%、%USERNAME%等占位符运行时会自动替换为当前选中连接的实际属性值从而让tracert、WinSCP、filezilla、PuTTY等程序按连接上下文动态工作。读完本文你将掌握 mRemoteNG 全部内置变量的语义、环境变量展开与屏蔽技巧、^防止展开、以及-/!前缀控制的参数分割与 Shell 元字符双层转义机制并能结合源码理解其底层实现与测试验证。变量功能在 External Tools 界面中使用相关入口与完整界面说明见 外部工具使用指南本文是其中的变量参考专题页。一、变量是什么把连接属性注入外部命令变量Variables也叫 Parameters可以在 External Tools 中动态地把连接属性插入命令与参数中。例如你可以在连接树上选中某台主机然后通过外部工具一键对它执行tracert而不必手动敲入主机名Filename%COMSPEC%Arguments/c set /P | tracert %HostName%其运行原理在源码中非常清晰ExternalTool.Start()启动进程前会为当前连接构造一个 ExternalToolArgumentParser构造参数为ConnectionInfo然后对FileName、Arguments、WorkingDir三个字段统一调用ParseArguments完成替换见 ExternalTool.SetProcessProperties。因此变量不只用于 Arguments也适用于 Filename例如%COMSPEC%和工作目录字段。二、可用变量完整列表mRemoteNG 支持以下内置变量均引用当前选中连接的属性变量含义对应 ConnectionInfo 属性源码%NAME%连接的显示名称Name%HOSTNAME%连接的主机名或 IP 地址Hostname%PORT%连接的端口号PortConvert.ToString转为字符串%USERNAME%连接配置的用户名Username%PASSWORD%连接配置的密码Password%DOMAIN%连接配置的域Domain%DESCRIPTION%连接的描述文本Description%MACADDRESS%连接配置的 MAC 地址MacAddress%USERFIELD%连接的自定义用户字段UserField上面的源码映射可直接在 ExternalToolArgumentParser.GetVariableReplacement 中找到解析器对变量名做ToLowerInvariant()后按name / hostname / port / username / password / domain / description / macaddress / userfield逐一匹配。2.1 用户名、密码、域的空值回退行为从源码可以看出%USERNAME%、%PASSWORD%、%DOMAIN%三个变量在连接属性为空时并非简单地替换为空字符串而是受Options → Credentials 页的EmptyCredentials设置影响见 OptionsCredentialsPage%USERNAME%为空时若EmptyCredentials windows替换为Environment.UserName当前 Windows 登录用户名若EmptyCredentials custom替换为设置的默认用户名DefaultUsername。%PASSWORD%为空时仅当EmptyCredentials custom会使用LegacyRijndaelCryptographyProvider解密DefaultPassword后替换。%DOMAIN%为空时windows模式替换为Environment.UserDomainNamecustom模式替换为DefaultDomain。这意味着即使连接的凭据字段留空外部工具也可能拿到来自操作系统或默认凭据设置的值——在配置敏感命令时需留意这一点。三、环境变量展开%PATH%、%USERPROFILE%与\%转义除了内置变量mRemoteNG 也会展开操作系统环境变量如%PATH%、%USERPROFILE%。展开流程见 ExternalToolArgumentParser.BuildReplacementList当变量名既不是内置变量、又不是特殊形式时会调用Environment.GetEnvironmentVariable(variableName)尝试读取系统环境变量读取成功则替换读取失败则保留原文。3.1 冲突场景\%USERNAME\%强制走环境变量当环境变量与 mRemoteNG 内置变量同名时最典型的是USERNAME内置变量优先%USERNAME%→ 展开为当前选中连接里配置的用户名\%USERNAME\%用\%代替%→ 展开为USERNAME环境变量的值。其实现位于源码第 45-60 行当 token 前后两个字符都是\时解析器标记isEnvironmentVariable true跳过内置变量查找、直接走环境变量分支。3.2 相关测试佐证在 ExternalToolsArgumentParserTests 中可以看到对应测试用例%COMSPEC%→ 解析为Environment.GetEnvironmentVariable(comspec)环境变量被解析\%COMSPEC\%→ 同样解析为comspec环境变量的值反斜杠转义的环境变量被解析^%COMSPEC^%→ 原样返回%COMSPEC%见下文防止展开。四、防止变量展开^%前缀如果想把变量名原样传给目标程序、不让 mRemoteNG 展开请用^%代替%。mRemoteNG 会移除插入符^并保留其余内容不变。例如输入^%USERNAME^%→ 传给程序的是字面量%USERNAME%不会被展开。实现上解析器在 第 61-75 行 检测 token 前后字符为^时直接把 token 还原为%变量名%加入替换列表不进行任何值替换与转义。测试ChevronEscapedEnvironmentVariablesNotParsed验证了该行为。五、变量的使用规则使用变量时须遵守以下规则变量始终引用当前选中的连接在连接树中高亮的那个连接变量名不区分大小写%HOSTNAME%与%HostName%等价源码用ToLowerInvariant统一处理变量可用于 External Tools 的Filename与Arguments两个字段实际上 Working directory 字段同样经过解析器处理变量总是被%包裹未定义的变量名不会被替换例如%UNSUPPORTEDPARAMETER%原样保留测试UnsupportedParametersNotParsed已覆盖空的变量标签%%不会被当作变量解析测试EmptyVariableTagsNotParsed已覆盖。六、特殊字符转义双层转义机制展开后的变量值会被自动转义转义分两个层次参数分割转义针对 C/C argv、CommandLineToArgvW等标准参数拆分规则Shell 元字符转义针对ShellExecute场景下的 shell 特殊字符。注意只有被展开的变量值才会转义命令中其余部分需要你自己负责转义。6.1 参数分割转义规则按标准 Windows 命令行参数拆分规则源自 CommandLineArguments.cs注释标明 Adapted from http://qntm.org/cmd每个引号之前加一个反斜杠转义一个或多个反斜杠后跟引号\每个反斜杠再补一个反斜杠翻倍引号前再加一个反斜杠。官方文档给出的示例%USERFIELD%若连接的用户字段内容为Thisis a\test\则%USERFIELD%替换为\This\is a\\\test\\\若用户字段内容为c:\Example\结尾带反斜杠则%USERFIELD%替换为c:\Example\\。第二个示例对应源码中的EscapeBackslashesForTrailingQuote当变量后面紧跟一个引号且值以反斜杠结尾时末尾反斜杠必须翻倍否则会吃掉闭合引号见 ExternalToolArgumentParser 第 125-126 行。6.2 禁用参数分割转义-前缀在变量名前加减号-可关闭参数分割转义只保留 Shell 元字符转义。例如%-USERFIELD%→ 不进行引号/反斜杠的参数分割转义但仍做 Shell 元字符转义。源码 DetermineEscapeType 中前缀-对应EscapeType.ShellMetacharacters。6.3 Shell 元字符转义规则Shell 元字符集合为( ) % ! ^ |。每个元字符前会加一个插入符^进行转义对应 CommandLineArguments.EscapeShellMetacharacters 中的正则([()%!^|])→^$1。测试用例中给出了非常直观的对照测试常量见 ExternalToolsArgumentParserTests原始值()%!^abc123*|\结尾仅 Shell 元字符转义后%-前缀^()^%^!^^abc123*^^^^|^\双层全量转义后默认^()^%^!^^abc123*^^^^|\^\6.4 完全禁用转义!前缀不推荐在变量名前加感叹号!可同时关闭参数分割转义与 Shell 元字符转义。例如%!USERFIELD%→ 原样替换不做任何转义。文档明确警示这可能导致意外结果不建议使用例如包含空格或引号的值会破坏命令参数结构。源码中!前缀对应EscapeType.None。6.5 三层转义行为速查写法参数分割转义Shell 元字符转义适用场景%USERFIELD%✅✅默认行为最安全%-USERFIELD%❌✅值内部已含需要保留的引号结构%!USERFIELD%❌❌特殊场景风险高官方不建议测试 ParserTestsDataSource 对全部 9 个内置变量逐一验证了%x%、%-x%、%!x%三种形态的展开结果与上述规则完全一致。七、解析器实现细节token 扫描流程理解底层实现有助于排查变量不生效的问题。BuildReplacementList的核心流程是用IndexOf(%)在输入串中从左到右扫描%...%token第 29-39 行检查 token 前导字符\\前后成对 → 环境变量强制展开^前后成对 → 原样保留不展开检查 token 第二个字符-/!→ 决定转义级别先在ConnectionInfo中查内置变量查不到再查Environment.GetEnvironmentVariable有替换值才加入替换列表并应用对应转义无替换值时保留原文最后在PerformReplacements中从右向左执行替换避免下标错位。另外解析器对ConnectionInfo null时返回空字符串测试NullConnectionInfoResultsInEmptyVariables验证test %USERNAME% test解析为test test这对应外部工具在无连接上下文时启动的场景。八、实战示例把变量用起来结合 外部工具常用配置速查表以下示例展示了变量的典型组合用法Ping使用环境变量%COMSPEC%作为 FilenameFilename%COMSPEC%Arguments/c ping -t %HostName%FileZilla 连接用户名/密码/主机/端口组合FilenameC:\Program Files\FileZilla FTP Client\filezilla.exe示例路径ArgumentsFTPftp://%Username%:%Password%%Hostname%ArgumentsSFTPsftp://%Username%:%Password%%Hostname%WinSCP SCP 会话FilenameC:\Program Files\WinSCP\WinSCP.exe示例路径Argumentsscp://%Username%:%Password%%Hostname%/可选参数-rawsetting Compression1 -hostkey*开启压缩并忽略主机密钥错误COM 串口变量放在 Filename 里也能展开Filenameputty.exe示例路径Arguments-serial com%Port%PowerShell 远程会话引号与^配合Filename%WINDIR%\system32\WindowsPowerShell\v1.0\PowerShell.exeArguments-noexit $pw \%password%\ -replace \^, ; ... Enter-PSSession -ComputerName %hostname% -credential $Cred最后一个示例特别体现了转义的价值\是让参数分割转义产生的输出与 PowerShell 语法兼容的典型写法而-replace \^, 中的^用于在 mRemoteNG 展开后对 PowerShell 特殊字符做二次处理。九、最佳实践小结优先使用默认转义%HOSTNAME%、%USERNAME%等默认形式足够应对绝大多数场景只有确认值中的引号/反斜杠会被参数拆分破坏时才用%-前缀。密码变量注意隐私%PASSWORD%会把明文密码拼进命令行参数进程列表如任务管理器中可能可见且当连接密码为空、EmptyCredentials设为custom时会回退到全局默认密码。环境变量冲突时显式声明要取操作系统级%USERNAME%、%DOMAIN%时用\%USERNAME\%形式避免被连接属性覆盖。字面量用^%需要把%xxx%原样传给下游程序如脚本模板时使用^%xxx^%。不要滥用%!前缀完全关闭转义会让包含空格、引号、、|等字符的值直接进入命令行可能导致参数错位甚至意外执行仅在明确风险可控时使用。十、相关文档导航外部工具使用指南变量在 External Tools 界面中的配置入口Tools → External Tools快捷键Shift-F4新建外部工具常用配置速查表Ping、traceroute、WinSCP、FileZilla、PowerShell 等完整可复制示例变量解析器源码内置变量映射、环境变量回退、^/-/!前缀与转义级别判定命令行转义工具源码EscapeBackslashes、EscapeBackslashesForTrailingQuote、EscapeShellMetacharacters的具体正则实现外部工具启动流程Start→SetProcessProperties→ 解析 Filename/Arguments/WorkingDir 的调用链解析器单元测试覆盖全部变量的三种转义形态、环境变量展开、防止展开、未定义变量保留等边界场景。赞分享桌面应用网络【免费下载链接】mRemoteNGmRemoteNG is the next generation of mRemote, open source, tabbed, multi-protocol, remote connections manager.项目地址https://gitcode.com/gh_mirrors/mr/mRemoteNG点击查看免费下载相关推荐mRemoteNG External Tools 完全指南用连接变量驱动任意外部命令mRemoteNG External Tools 完全指南用连接变量驱动任意外部命令 mRemoteNG 的 External Tools外部工具机制允许桌面应用网络mRemoteNG 用户界面完全指南主窗口、面板、连接管理、快速连接与外部工具实战mRemoteNG 用户界面完全指南主窗口、面板、连接管理、快速连接与外部工具实战 mRemoteNG 是一款开源的标签式多协议远程连接管理器其界面围绕「主桌面应用网络mRemoteNG 外部工具External Tools实战指南变量注入、命令行集成与典型配置示例mRemoteNG 外部工具External Tools实战指南变量注入、命令行集成与典型配置示例 mRemoteNG 的 External Tools桌面应用网络创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表