Verbinden über TShell

TShell ist ein PowerShell-Modul im Windows System Kit, mit dem Sie eine Verbindung mit Testgeräten und VMs herstellen, Tests auf ihnen ausführen und sie debuggen können.

Zum Herstellen einer Verbindung mit TShell benötigen Sie Folgendes:

• Einen Techniker-PC mit dem Windows System Kit, der mit einem Netzwerk verbunden ist
• Ein Factory-Betriebssystemgerät, für das gilt:
  • Es ist über das Netzwerk vom Techniker-PC aus verfügbar. Informationen zum Abrufen der IP-Adresse Ihres Geräts finden Sie unter Abrufen der IP-Adresse Ihres Geräts.
  • Enthält TShell. TShell ist im Feature WCOS_TEST_COMPONENTS enthalten, das Teil des Featuremanifests WindowsCoreNonProduction.xml ist. Dieses Feature ist standardmäßig in Entwicklungsimages enthalten.

So stellen Sie eine Verbindung her

1. Binden Sie auf dem Techniker-PC die WSK-ISO-Datei ein, und starten Sie die WSK-Erstellungsumgebung (Beispiel: E:\SetImagGenEnv.cmd) als Administrator*in.

2. Öffnen Sie TShell:

   E:\tshell.cmd
   

3. Stellen Sie eine Verbindung mit dem Gerät her.

   open-device 192.168.1.2
   

   Dabei ist 192.168.1.2 die IP-Adresse des Geräts, mit dem Sie eine Verbindung herstellen.

TShell-Cmdlets

Über die Befehle in diesem Abschnitt interagieren Sie mit dem Remotegerät. Sie funktionieren nur, während Sie mit TShell verbunden sind.

Führen Sie jeden Befehl mit -? aus, um die grundlegende Verwendung abzurufen, und führen Sie help <command> -detailed aus, um die detaillierte Verwendung abzurufen.

Alle Cmdlets des Typs *-Device weisen einen Alias aus ihrem Verb (dem Wort vor dem „-“) und dem Buchstaben „d“ auf. Beispiele:

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

Verfügbare Cmdlets

Geräteverbindungs-Cmdlets

Cmdlet	BESCHREIBUNG
open-device	Herstellen einer Verbindung zwischen TShell und dem Zielgerät
close-device	Abtrennen des verbundenem Zielgeräts

Cmdlets für die Geräteausführung

Cmdlet	BESCHREIBUNG
cmd-device (cmdd)	Ausführen von Befehlen mit „cmd.exe“
exec-device (execd)	Ausführen von ausführbaren Dateien

Cmdlets für Geräteinteraktion

Cmdlet	BESCHREIBUNG
deploy-device (deployd)	Bereitstellen von Testpaketen auf dem verbundenen Gerät
dir-device (dird)	Auflisten eines Verzeichnisses
cd-device (cdd)	Ändern des Geräteverzeichnisses
rmdir-device (rdd, rmdird)	Verzeichnis entfernen
copy-device (cpd, kopiert)	Kopieren von Dateien
del-device (deld)	Datei löschen
mkdir-device (mdd, mkdird)	Neues Verzeichnis erstellen
move-device (mvd, verschoben)	Verschieben von Dateien
put-device (putd)	Kopieren von Dateien von einem lokalen Gerät auf ein Remotegerät
get-device (getd)	Kopieren von Dateien von einem Remotegerät auf ein lokales Gerät
tlist-device (tlistd)	Anzeigen von Informationen für jeden ausgeführten Task
type-device (typed)	Drucken des Inhalts einer Datei auf dem Gerät im Terminal
kill-device (killd)
reg-device (regd)	Verwendet im Zusammenhang mit Registrierungsschlüsseln

Abrufen von Informationen zur Geräte- und TShell-Umgebung

Cmdlet	BESCHREIBUNG
get-variable	Anzeigen der Geräteadresse, des Namens und des Arbeitsverzeichnisses
get-variable TShell	Anzeigen der auf dem Gerät installierten TShell-Version

Cmdlets zum Debuggen

Cmdlet	BESCHREIBUNG
debug-device (debugd)	Debuggen eines Prozesses

Geräteverbindungs-Cmdlets

open-device: Verbinden von TShell mit dem Zielgerät

Um eine Verbindung zu öffnen, geben Sie die IP-Adresse für localhost (Standard: 127.0.0.1) an, oder wenn kdnet aktiviert ist, verwenden Sie die MAC-Adresse.

PS> open-device 127.0.0.1

close-device: Abtrennen des verbundenem Zielgeräts

Wenn Sie mit der Arbeit auf einem Gerät fertig sind, schließen Sie die Verbindung:

PS> close-device

Cmdlets für die Geräteausführung

cmd-device (cmdd): Ausführen von Befehlen mit „cmd.exe“

TShell stellt ausgeführte Befehle über „cmd.exe“ auf dem Gerät zur Verfügung, und leitet den Standardausgabekanal, den Standardfehlerkanal und den Exitcode über den Befehl cmd-device (cmdd) zurück in die PowerShell-Pipeline.

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

Außerdem werden einige gängige Befehle von „cmd.exe“ über spezielle Cmdlets verfügbar gemacht, bei denen die Eingabeaufforderungen (z. B. /y bei „copy“) unterdrückt und die Ausgabe des Befehls als Zeichenfolge zurückgegeben wird. (Hinweis: Diese Befehle sind für die einfache Arbeit mit der Eingabeaufforderung gedacht. Beim Schreiben von PowerShell-Skripts sollte stattdessen das Cmdlet cmd-device verwendet werden.)

exec-device (execd): Ausführen ausführbarer Dateien

Um einen Befehl auf dem Gerät auszuführen, verwenden Sie den Befehl exec-device (execd). Die gesamte Befehlszeile nach eventuellen Schaltern wird unverändert auf dem Gerät ausgeführt. Alle Argumente für den Prozess, die mit „-“ beginnen, müssen in Anführungszeichen (einfach oder doppelt) übergeben werden, damit PowerShell sie nicht analysiert. TShell wartet, bis der Prozesses beendet und der Exitcode in die Konsole ausgegeben wird.

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

Um einzelne Argumente in doppelten Anführungszeichen an den geräteseitigen Prozess zu übergeben, müssen Sie alle Prozessargumente in einzelne Anführungszeichen setzen (eine Literalzeichenfolge in PowerShell), wenn Sie sie an TShell übergeben.

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

Standardmäßig wird die Ausgabe des Prozesses nicht an die Shell gesendet. Sie können den Schalter „-output“ verwenden, um sowohl die Standardausgabe als auch Standardfehler an den Host weiterzureichen. Beide werden als Eigenschaften des Befehlsrückgabewerts zurückgegeben.

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

Standardmäßig wird der Befehl synchron ausgeführt. Das bedeutet, dass TShell auf die Beendigung des Prozesses wartet, bevor zur Eingabeaufforderung zurückgekehrt wird. Sie können den Schalter „-async“ verwenden, um den Prozess asynchron auszuführen. In diesem Fall startet TShell einfach den Prozess und kehrt sofort zurück.

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

Cmdlets für Geräteinteraktion

deploy-device (deployd): Bereitstellen von Testpaketen auf dem verbundenen Gerät

Um ein Paket auf dem Gerät bereitzustellen, verwenden Sie den Befehl deploy-device (deployd).

Syntax von Deploy-Device

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

Beispiel:

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

Weitere Informationen erhalten Sie durch Ausführen von get-help Deploy-Device -detailed.

Fügen Sie zum Bereitstellen von WOW-Testpaketen die Option „-testarch“ hinzu. Beispiel:

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

Unterstützte TestArch-Eingaben sind: amd64, x86, arm, arm64, wow64, arm64.arm, arm64.x86. Wenn TestArch nicht angegeben wird, werden nur native Pakete bereitgestellt.

dir-device (dird): Auflisten eines Verzeichnisses

Sie können die Verzeichnisse auf einem Remotegerät auflisten:

dird

cd-device (cdd): Ändern des Geräteverzeichnisses

TShell überprüft, ob das neue Verzeichnis auf dem Gerät vorhanden ist, und gibt andernfalls einen Fehler aus. Die Punkt-Punkt-Notation wird unterstützt, um zum übergeordneten Verzeichnis zu wechseln, und die Variable $DeviceWD wird jedes Mal aktualisiert.

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): Entfernen eines Verzeichnisses

Sie können einen Ordner von einem Remotegerät entfernen:

rmdird c:\foldertoremove

copy-device (cpd, copyd): Kopieren von Dateien

Kopieren Sie Dateien zwischen Verzeichnissen auf dem Remotesystem. (Hiermit werden keine Dateien zwischen dem Host und dem Remotesystem kopiert. Dazu können Sie getd und putd verwenden.)

del-device (deld): Löschen einer Datei

Sie können Dateien auf einem Remotegerät löschen:

deld file.bat

mkdir-device (mdd, mkdird): Erstellen eines neuen Verzeichnisses

Sie können ein Verzeichnis auf einem Remotegerät erstellen:

mkdird c:\newfolder

move-device (mvd, moved): Verschieben von Dateien

Sie können Ordner von einem Ort auf einem Remotegerät an einen anderen verschieben:

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

put-device (putd): Kopieren von Dateien auf das Gerät

Um Dateien auf das Remotegerät zu kopieren, verwenden Sie put-device (putd).

Wenn Sie eine Datei auf das Gerät kopieren, können Sie den Pfad der neuen Gerätedatei oder das Verzeichnis festlegen, in das sie kopiert werden soll.

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

Platzhalter werden nur für den Quellhostpfad unterstützt, und sowohl die Host- als auch die Gerätepfade sind relativ zu den aktuellen Arbeitsverzeichnissen.

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

Das rekursive Kopieren von Verzeichnissen wird unterstützt.

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

get-device (getd): Kopieren von Dateien vom Gerät

Um Dateien vom Gerät zu kopieren, verwenden Sie den Befehl get-device (getd).

Wenn Sie eine Datei auf das Gerät oder von diesem kopieren, können Sie den Pfad der neuen Gerätedatei oder das Verzeichnis festlegen, in das sie kopiert werden soll.

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

Platzhalter werden nur für den Quellhostpfad unterstützt, und sowohl die Host- als auch die Gerätepfade sind relativ zu den aktuellen Arbeitsverzeichnissen.

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

Das rekursive Kopieren von Verzeichnissen wird unterstützt.

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

kill-device (killd)

reg-device (regd)

Verwendet im Zusammenhang mit Registrierungsschlüsseln regd query "insert setting here" wird zum Abfragen von Registrierungsschlüsseln auf dem Gerät verwendet, und regd add "insert setting here" wird zum Hinzufügen/Ändern von Registrierungseinstellungen verwendet.

tlist-device (tlistd)

Zeigt den Befehl, die Befehlszeile, das Arbeitsverzeichnis, die Speichernutzung und DLLs für jeden ausgeführten Task an.

type-device (typed)

Gibt den Inhalt einer Datei auf dem Gerät auf dem Terminal aus (ähnlich dem Desktop-PowerShell-Alias „cat“)

Abrufen von Informationen zur Geräte- und TShell-Umgebung

get-variable *

Anzeigen der Geräteadresse, des Namens und des Arbeitsverzeichnisses

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

get-variable TShell*

Anzeigen der auf dem Gerät installierten TShell-Version

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

Cmdlets zum Debuggen

debug-device (debugd): Debuggen eines Prozesses

Damit dieser Befehl funktioniert, müssen Sie die neueste Version des Debuggers installieren.

Verwenden Sie zum Anfügen eines Debuggerclients (der Standard ist windbg) an einen Benutzermodusprozess den Befehl debug-device (debugd). Ein neuer Prozess kann mit dem angefügten Debugger gestartet werden, indem der Pfad der ausführbaren Datei angegeben wird (kann relativ zum aktuellen Arbeitsverzeichnis des Geräts sein).

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

Sie können auch einen vorhandenen Prozess anfügen, indem Sie die PID angeben, die mithilfe des Befehls tlist-device abgerufen werden kann.

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

PS C:\> debugd -pid 1234

Wenn keine der beiden Angaben erfolgt, wird der Debuggerclient mit einer Verbindung mit dem Gerät, aber ohne angefügten Prozess gestartet.

PS C:\> debugd

Sie können auch den Pfad des zu verwendenden Debuggerclients mit dem Schalter „-dbg“ angeben.

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

Debuggen eines modernen App-Prozesses

Um einen modernen App-Prozess beim Start zu debuggen, fügen Sie den DcomLaunch-Dienst an, und aktivieren Sie das Debuggen des untergeordneten Prozesses:

Geben Sie in TShell Folgendes ein:

PS C:\> debugd -servicename dcomlaunch

Geben Sie dann im Debugger Folgendes ein:

.childdbg 1