Connect using TShell

TShell is a PowerShell module included with the Windows System Kit which you can use to connect to, run tests on, and debug your test devices and VMs.

To connect using TShell, you'll need:

• A technician PC with the Windows System Kit that's connected to a network
• A Factory OS device that:
  • Is available over the network from the technician PC. See Find the IP address of your device for information on how to get the IP address of your device.
  • Includes TShell. TShell is included in the WCOS_TEST_COMPONENTS feature, which is part of the WindowsCoreNonProduction.xml feature manifest. This feature is included in development images by default.

To connect

1. On the technician PC, Mount the WSK ISO and start the WSK Build Environment (example, E:\SetImagGenEnv.cmd) as an administrator.

2. Open TShell:

   E:\tshell.cmd
   

3. Connect to the device

   open-device 192.168.1.2
   

   Where 192.168.1.2 is the IP address of the device you're connecting to.

TShell cmdlets

The commands in this section are used to interact with the remote device. They will only work while you're connected to TShell.

Run each command with -? to get the basic usage, and run help <command> -detailed to get the detailed usage.

All *-Device cmdlets are aliased to their verb (the word before the '-') and the letter 'd'. Examples:

Cmdlet Name	Cmdlet Alias
Put-Device	putd
Exec-Device	execd
Dir-Device	dird

Available cmdlets

Device connection cmdlets

cmdlet	Description
open-device	Connects tshell to target device
close-device	Disconnect from connected target device

Device execution cmdlets

cmdlet	Description
cmd-device(cmdd)	Run cmd.exe commands
exec-device(execd)	Run executables

Device interaction cmdlets

cmdlet	Description
deploy-device(deployd)	Deploy test packages onto the connected device
dir-device(dird)	List directory
cd-device(cdd)	Change device directory
rmdir-device(rdd, rmdird)	Remove directory
copy-device(cpd, copyd)	Copy files
del-device(deld)	Delete file
mkdir-device(mdd, mkdird)	Create new directory
move-device(mvd, moved)	Move files
put-device(putd)	Copy files from a local device to a remote device
get-device(getd)	copy files from a remote device to a local device
tlist-device(tlistd)	Shows information for each running task
type-device(typed)	Prints the contents of a file on the device to the terminal
kill-device(killd)
reg-device(regd)	Used for anything related to registry keys

Get info about the device and TShell Environment

cmdlet	Description
get-variable device	Show device address, name and working directory.
get-variable TShell	Show the TShell version installed on the device

Cmdlets for debugging

cmdlet	Description
debug-device(debugd)	Debug process

Device connection cmdlets

open-device: connecting tshell to target device

To open a connection, specify the localhost IP (default: 127.0.0.1) or if kdnet is enabled, use the MAC address.

PS> open-device 127.0.0.1

close-device: disconnect from connected target device

When you're finished working on a device, close the connection:

PS> close-device

Device execution cmdlets

cmd-device(cmdd): Run cmd.exe commands

TShell exposes running commands via cmd.exe on the device, and pipes the standard out, standard error, and exit code back to the PowerShell pipeline via the cmd-device (cmdd) command.

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

It also exposes some common cmd.exe commands via dedicated cmdlets, for which it suppresses prompts (example: /y for 'copy') and returns the output of the command as a string (Note: these commands are meant for convenience when working from the prompt. When writing PowerShell scripts, the cmd-device cmdlet should be used instead).

exec-device(execd):run executables

To execute a command on the device, use the exec-device (execd) command. The entire command line after any switches will be executed as-is on the device. Any arguments to the process that start with '-' must be passed in quotes (single or double) so PowerShell doesn't try to parse them. TShell will wait for the process to exit and output the exit code to the console.

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

To pass single arguments inside double quotes to the device side process, you must put all the process arguments inside single quotes (which is a literal string in PowerShell) when passing them to TShell.

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

By default the output from the process will not be sent to the shell. You can use the -output switch to pipe both standard out and standard error to the host, both will be returned as properties of the command return value.

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

By default the command will be run synchronous, which means TShell waits for the process to exit before returning to the prompt. You can use the -async switch to run the process asynchronously, in which case TShell just starts the process and returns immediately.

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

Device interaction cmdlets

deploy-device(deployd): deploy test packages onto the connected device

To deploy a package to the device, use the deploy-device (deployd) command.

Deploy-Device Syntax

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

Example:

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

To learn more, run get-help Deploy-Device -detailed.

To deploy WOW test packages, add the -testarch option. Example:

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

Supported TestArch inputs are: amd64, x86, arm, arm64, wow64, arm64.arm, arm64.x86. Only Native packages will be deployed if no TestArch is specified.

dir-device(dird):list directory

You can list the directories on a remote device:

dird

cd-device(cdd): change device directory

TShell will check if the new directory exists on the device and error if it does not. Dot-dot notation is supported for moving to the parent directory, and the $DeviceWD variable is updated each time.

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):remove directory

You can remove a folder from a remote device:

rmdird c:\foldertoremove

copy-device(cpd, copyd):copy files

Copy files between directories on the remote system. (This does not copy files between the host and remote system. See getd and putd for that.)

del-device(deld):delete file

You can delete files from a remote device:

deld file.bat

mkdir-device(mdd, mkdird):create new directory

You can create a directory on a remote device:

mkdird c:\newfolder

move-device(mvd, moved):move files

You can move folders from one place on a remote device to another:

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

put-device(putd):copy files to

To copy files to the remote device, use the put-device (putd).

When copying a file to the device, you can either specifiy the path of the new device file or the directory into which it should be copied.

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

Wildcards are supported for the source host path only, and both the host and device paths are relative to the current working directories.

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

Recursively copying directories is supported.

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

get-device(getd): copy files from

To copy files from the device, use the get-device (getd) commands.

When copying a file to or from the device, you can either specify the path of the new device file or the directory into which it should be copied.

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

Wildcards are supported for the source host path only, and both the host and device paths are relative to the current working directories.

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

Recursively copying directories is supported.

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

kill-device(killd)

reg-device(regd)

Used for anything related to registry keys. regd query "insert setting here" is used to query registry keys on the device and regd add "insert setting here" is used to add/change registry settings.

tlist-device(tlistd)

Show the command, command line, working directory, memory usage and DLLs for each running task.

type-device(typed)

Prints the contents of a file on the device to the terminal (similar to the desktop powershell alias "cat")

Get info about the device and TShell Environment

get-variable device*

Show device address, name and working directory.

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

get-variable TShell*

Show the TShell version installed on the device.

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

Cmdlets for debugging

debug-device(debugd):debug process

For this command to work you need to install the latest version of the Debugger.

To attach a debugger client (windbg is the default) to a user mode process, use the debug-device (debugd) command. A new process can be started with the debugger attached by specifying the path of the exe (can be relative to the device current working directory).

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

Or attach to an existing process by specifying the PID, which can be obtained using the tlist-device command.

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

PS C:\> debugd -pid 1234

If neither is specified, the debugger client is started with a connection to the device but no process attached.

PS C:\> debugd

You can also specify the path of the debugger client to use with the -dbg switch

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

Debugging a Modern App process

To debug a modern app process on launch, attach to the DcomLaunch service and enable child process debugging:

In TShell:

PS C:\> debugd -servicename dcomlaunch

Then in the debugger:

.childdbg 1