使用 TShell 进行连接

项目
05/30/2023

TShell 是 Windows 系统工具包中包含的一个 PowerShell 模块，可用于连接、调试测试设备和 VM，以及在其上运行测试。

若要使用 TShell 进行连接，需要：

一台装有 Windows 系统工具包并已连接到网络的技术人员电脑
一台工厂 OS 设备，该设备：
- 可以在技术人员电脑上通过网络访问。有关如何获取设备 IP 地址的信息，请参阅查找设备的 IP 地址。
- 包含 TShell。 TShell 包含在 WCOS_TEST_COMPONENTS 功能中，该功能是 WindowsCoreNonProduction.xml 功能清单的一部分。此功能默认已包含在开发映像中。

WDP topology showing you can connect via tshell from a remote pc

连接

在技术人员电脑上，装载 WSK ISO 并以管理员身份启动 WSK 生成环境（例如 E:\SetImagGenEnv.cmd）。
打开 TShell：
```
E:\tshell.cmd
```
连接到设备
```
open-device 192.168.1.2
```
其中 192.168.1.2 是要连接到的设备的 IP 地址。

TShell cmdlet

本部分所述的命令用于与远程设备交互。这些命令仅在已连接到 TShell 的情况下才能正常运行。

结合 -? 运行每个命令可获取基本用法，运行 help <command> -detailed 可获取详细用法。

所有 *-Device cmdlet 的别名为其谓词部分（“-”前面的单词）加上字母“d”。示例：

cmdlet 名称	Cmdlet 别名
Put-Device	putd
Exec-Device	execd
Dir-Device	dird

可用的 cmdlet

设备连接 cmdlet

cmdlet	说明
open-device	将 tshell 连接到目标设备
close-device	从已连接的目标设备断开连接

设备执行 cmdlet

cmdlet	说明
cmd-device(cmdd)	运行 cmd.exe 命令
exec-device(execd)	运行可执行文件

设备交互 cmdlet

cmdlet	说明
deploy-device(deployd)	将测试包部署到已连接的设备
dir-device(dird)	列出目录
cd-device(cdd)	切换设备目录
rmdir-device(rdd, rmdird)	移除目录
copy-device(cpd, copyd)	复制文件
del-device(deld)	删除文件
mkdir-device(mdd, mkdird)	创建新目录
move-device(mvd, moved)	移动文件
put-device(putd)	将文件从本地设备复制到远程设备
get-device(getd)	将文件从远程设备复制到本地设备
tlist-device(tlistd)	显示每个正在运行的任务的信息
type-device(typed)	在终端中输出设备上文件的内容
kill-device(killd)
reg-device(regd)	用于处理与注册表项相关的任何内容

获取有关设备和 TShell 环境的信息

cmdlet	说明
get-variable device	显示设备地址、名称和工作目录。
get-variable TShell	显示设备上安装的 TShell 版本

用于调试的 Cmdlet

cmdlet	说明
debug-device(debugd)	调试进程

设备连接 cmdlet

open-device：将 tshell 连接到目标设备

若要打开连接，请指定 localhost IP（默认值：127.0.0.1）；如果启用了 kdnet，请使用 MAC 地址。

PS> open-device 127.0.0.1

close-device：从已连接的目标设备断开连接

在设备上完成工作后，关闭连接：

PS> close-device

设备执行 cmdlet

cmd-device(cmdd)：运行 cmd.exe 命令

TShell 通过设备上的 cmd.exe 公开正在运行的命令，并通过 cmd-device (cmdd) 命令将标准输出、标准错误和退出代码传回到 PowerShell 管道。

PS C:\> cmd-device dir %DataDrive%\test
PS C:\> cmd-device copy %DataDrive%\test\foo %DataDrive%\test\bar
PS C:\> cmd-device del %DataDrive%\test\foo

它还通过专用 cmdlet 公开一些常见的 cmd.exe 命令，对于这些命令，它会禁止提示（例如：/y用于“复制”），并以字符串形式返回命令的输出（注意：这些命令是为了方便在提示符下工作。编写 PowerShell 脚本时，应改用 cmd-device cmdlet）。

exec-device(execd)：运行可执行文件

若要在设备上执行命令，请使用 exec-device (execd) 命令。任何开关后面的整个命令行将在设备上按原样执行。以“-”开头的进程的任何参数必须包含在引号（单引号或双引号）中进行传递，使 PowerShell 不会尝试分析这些参数。 TShell 将等待进程退出，并将退出代码输出到控制台。

PS C:\> execd windows\system32\cmd.exe
PS C:\> execd tux.exe '-d tuxdemo.dll'

若要将双引号中的单个参数传递给设备端进程，必须在将所有进程参数传递给 TShell 时，将其包含在单引号（PowerShell 中的文本字符串）中。

PS C:\> execd tux.exe '-d tuxdemo.dll -c "arg1 arg2" -f results.log'

默认情况下，进程的输出不会发送到 shell。可以使用 -output 开关将标准输出和标准错误传送到主机，两者将作为命令返回值的属性返回。

PS C:\> execd -output tux.exe '-d tuxdemo.dll'

默认情况下，命令将同步运行，这意味着，TShell 将在返回到提示符之前等待进程退出。可以使用 -async 开关以异步方式运行进程，在这种情况下，TShell 只会启动进程并立即返回。

PS C:\> execd -async tux '-d tuxdemo.dll -f results.log'

设备交互 cmdlet

deploy-device(deployd)：将测试包部署到已连接的设备

若要将包部署到设备，请使用 deploy-device (deployd) 命令。

Deploy-Device 语法

 Deploy-Device -Packages <string[]> [-PackageRootPaths <string>] [-AlternatePackageRoots <string[]>]
    [-TestToolsPath <string>] [-DeployPackageMacroOverride <string>] [-PackageCache <string>] [-Timeout <int>]
    [-OnDevice] [-TestArchitecture <string>] [<CommonParameters>]

示例：

PS C:\> Deploy-Device -Packages Microsoft.OneCore.ATest.spkg
  -packageRootPath \\server\folder
  -alternatePackageRoots c:\packages\sd.binaries.x86fre\prebuilt

若要了解详细信息，请运行 get-help Deploy-Device -detailed。

若要部署 WOW 测试包，请添加 -testarch 选项。示例：

PS c:> Deploy-Device -Packages Microsoft-Windows-Test-TAEF -testarch wow64

支持的 TestArch 输入为：amd64、x86、arm、arm64、wow64、arm64.arm、arm64.x86。如果未指定 TestArch，则只会部署本机包。

dir-device(dird)：列出目录

可以列出远程设备上的目录：

dird

cd-device(cdd)：切换设备目录

TShell 将检查设备上是否存在新目录，如果不存在，则会返回错误。不支持使用双点表示法切换到父目录，每次都会更新 $DeviceWD 变量。

DEVICE C:\
PS C:\> cdd test
DEVICE C:\test
PS C:\> cdd ..\windows
DEVICE C:\windows
PS C:\> cdd \
DEVICE C:\
PS C:\>

rmdir-device(rdd, rmdird)：删除目录

可以从远程设备中删除文件夹：

rmdird c:\foldertoremove

copy-device(cpd, copyd)：复制文件

在远程系统上的目录之间复制文件。（这不会在主机和远程系统之间复制文件。请参阅 getd 和 putd。）

del-device(deld)：删除文件

可以从远程设备中删除文件：

deld file.bat

mkdir-device(mdd, mkdird)：创建新目录

可以在远程设备上创建目录：

mkdird c:\newfolder

move-device(mvd, moved)：移动文件

可将文件夹从远程设备上的一个位置移到另一个位置：

moved c:\source\file.txt c:\destination\file.txt

put-device(putd)：将文件复制到目标

若要将文件复制到远程设备，请使用 put-device (putd)。

将文件复制到设备时，可以指定新设备文件的路径，或要将文件复制到的目录的路径。

PS C:\> putd C:\hostdir\hostfile.txt C:\devicedir\devicefile.txt
PS C:\> putd C:\hostdir\hostfile.txt C:\devicedir

仅支持对源主机路径使用通配符，主机和设备路径都相对于当前工作目录。

PS C:\> putd C:\hostdir\* C:\devicedir
PS C:\> putd C:\hostdir\hostfile.txt .

支持以递归方式复制目录。

PS C:\> putd -r C:\hostdir\* C:\devicedir

get-device(getd)：从源复制文件

若要从设备复制文件，请使用 get-device (getd) 命令。

向/从设备复制文件时，可以指定新设备文件的路径，或要将文件复制到的目录的路径。

PS C:\> getd C:\devicedir\devicefile.txt C:\hostdir\hostfile.txt
PS C:\> getd C:\devicedir\devicefile.txt C:\hostdir

仅支持对源主机路径使用通配符，主机和设备路径都相对于当前工作目录。

PS C:\> getd C:\devicedir\devicefile.txt .

支持以递归方式复制目录。

PS C:\> getd -r C:\devicedir\ .

kill-device(killd)

reg-device(regd)

用于处理与注册表项相关的任何内容。 regd query "insert setting here" 用于查询设备上的注册表项，regd add "insert setting here" 用于添加/更改注册表设置。

tlist-device(tlistd)

显示每个正在运行的任务的命令、命令行、工作目录、内存使用率和 DLL。

type-device(typed)

将设备上的文件内容输出到终端（类似于桌面版 PowerShell 别名“cat”）

获取有关设备和 TShell 环境的信息

get-variable device*

显示设备地址、名称和工作目录。

PS C:\> Get-Variable device*
  
Name                           Value
----                           -----
DeviceAddress                  10.225.96.216
DeviceName                     10.225.96.216
Dget-variable devices*

get-variable TShell*

显示设备上安装的 TShell 版本。

PS C:\> Get-Variable TShell*
  
Name                           Value
----                           -----
TShellInstallPath              C:\WINDOWS\system32\WindowsPowerShell\v1.0\Modules\TShell\TShell
TShellVersion                  8.1.1801.9001

用于调试的 Cmdlet

debug-device(debugd)：调试进程

若要正常运行此命令，需要安装最新版本的调试器。

若要将调试器客户端（默认为 windbg）附加到用户模式进程，请使用 debug-device (debugd) 命令。可以通过指定 exe 的路径（可以相对于设备当前工作目录），使用附加的调试器启动新进程。

PS C:\> debugd M:\windows\system32\cmd.exe

或者，通过指定 PID（可以使用 tlist-device 命令来获取）附加到现有进程。

PS C:\> tlistd
...
1234 myproc.exe

PS C:\> debugd -pid 1234

如果既未指定路径，也未指定 PID，则会通过与设备的连接启动调试器客户端，但不会附加任何进程。

PS C:\> debugd

还可以指定要与 -dbg 开关结合使用的调试器客户端路径

PS C:\> debugd -dbg C:\debuggers\ntsd.exe -pid 1234

调试新式应用进程

若要在启动时调试新式应用进程，请附加到 DcomLaunch 服务并启用子进程调试：

在 TShell 中运行以下命令：

PS C:\> debugd -servicename dcomlaunch

然后在调试器中运行以下命令：

.childdbg 1

通过

使用 TShell 进行连接

连接

TShell cmdlet

可用的 cmdlet

设备连接 cmdlet

设备执行 cmdlet

设备交互 cmdlet

获取有关设备和 TShell 环境的信息

用于调试的 Cmdlet

设备连接 cmdlet

open-device：将 tshell 连接到目标设备

close-device：从已连接的目标设备断开连接

设备执行 cmdlet

cmd-device(cmdd)：运行 cmd.exe 命令

exec-device(execd)：运行可执行文件

设备交互 cmdlet

deploy-device(deployd)：将测试包部署到已连接的设备

Deploy-Device 语法

dir-device(dird)：列出目录

cd-device(cdd)：切换设备目录

rmdir-device(rdd, rmdird)：删除目录

copy-device(cpd, copyd)：复制文件

del-device(deld)：删除文件

mkdir-device(mdd, mkdird)：创建新目录

move-device(mvd, moved)：移动文件

put-device(putd)：将文件复制到目标

get-device(getd)：从源复制文件

kill-device(killd)

reg-device(regd)

tlist-device(tlistd)

type-device(typed)

获取有关设备和 TShell 环境的信息

get-variable device*

get-variable TShell*

用于调试的 Cmdlet

debug-device(debugd)：调试进程

调试新式应用进程

其他资源