Conectar-se usando o TShell

  • Artigo

O TShell é um módulo do PowerShell incluído no Kit do Sistema windows ao qual você pode usar para se conectar, executar testes e depurar seus dispositivos de teste e VMs.

Para se conectar usando o TShell, você precisará de:

  • Um computador técnico com o Windows System Kit conectado a uma rede
  • Um dispositivo do sistema operacional de fábrica que:
    • Está disponível pela rede do computador técnico. Consulte Localizar o endereço IP do dispositivo para obter informações sobre como obter o endereço IP do dispositivo.
    • Inclui o TShell. O TShell está incluído no WCOS_TEST_COMPONENTS recurso , que faz parte do manifesto do recursoWindowsCoreNonProduction.xml. Esse recurso é incluído em imagens de desenvolvimento por padrão.

Topologia do WDP mostrando que você pode se conectar por meio do tshell de um computador remoto

Para se conectar

  1. No computador técnico, monte o ISO do WSK e inicie o Ambiente de Build do WSK (exemplo, E:\SetImagGenEnv.cmd) como administrador.

  2. Abra o TShell:

    E:\tshell.cmd

  3. Conectar-se ao dispositivo

    open-device 192.168.1.2

    Onde 192.168.1.2 é o endereço IP do dispositivo ao qual você está se conectando.

Cmdlets do TShell

Os comandos nesta seção são usados para interagir com o dispositivo remoto. Eles só funcionarão enquanto você estiver conectado ao TShell.

Execute cada comando com -? para obter o uso básico e execute help <command> -detailed para obter o uso detalhado.

Todos os *-Device cmdlets são aliased em seu verbo (a palavra antes de '-') e a letra 'd'. Exemplos:

Nome do Cmdlet Cmdlet Alias
Put-Device putd
Exec-Device execd
Dir-Device dird

Cmdlets disponíveis

Cmdlets de conexão do dispositivo

cmdlet Descrição
open-device Conecta o tshell ao dispositivo de destino
close-device Desconectar-se do dispositivo de destino conectado

Cmdlets de execução do dispositivo

cmdlet Descrição
cmd-device(cmdd) Executar comandos cmd.exe
exec-device(execd) Executar executáveis

Cmdlets de interação do dispositivo

cmdlet Descrição
deploy-device(deployd) Implantar pacotes de teste no dispositivo conectado
dir-device(dird) Listar diretório
cd-device(cdd) Alterar o diretório do dispositivo
rmdir-device(rdd, rmdird) Remover diretório
copy-device(cpd, copyd) Copiar arquivos
del-device(deld) Excluir arquivo
mkdir-device(mdd, mkdird) Criar um diretório
move-device(mvd, moved) Mover arquivos
put-device(putd) Copiar arquivos de um dispositivo local para um dispositivo remoto
get-device(getd) copiar arquivos de um dispositivo remoto para um dispositivo local
tlist-device(tlistd) Mostra informações para cada tarefa em execução
type-device(typed) Imprime o conteúdo de um arquivo no dispositivo no terminal
kill-device(killd)
reg-device(regd) Usado para qualquer coisa relacionada a chaves do Registro

Obter informações sobre o dispositivo e o ambiente do TShell

cmdlet Descrição
dispositivo get-variable Mostrar o endereço do dispositivo, o nome e o diretório de trabalho.
get-variable TShell Mostrar a versão do TShell instalada no dispositivo

Cmdlets para depuração

cmdlet Descrição
debug-device(debugd) Processo de depuração

Cmdlets de conexão do dispositivo

open-device: conectando o tshell ao dispositivo de destino

Para abrir uma conexão, especifique o IP localhost (padrão: 127.0.0.1) ou, se kdnet estiver habilitado, use o endereço MAC.

PS> open-device 127.0.0.1

close-device: desconectar do dispositivo de destino conectado

Quando terminar de trabalhar em um dispositivo, feche a conexão:

PS> close-device

Cmdlets de execução do dispositivo

cmd-device(cmdd): executar comandos cmd.exe

O TShell expõe comandos em execução por meio de cmd.exe no dispositivo e redireciona o padrão para fora, o erro padrão e o código de saída de volta para o pipeline do PowerShell por meio do comando cmd-device (cmdd).

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

Ele também expõe alguns comandos comuns cmd.exe por meio de cmdlets dedicados, para os quais suprime prompts (por exemplo: /y para 'copy') e retorna a saída do comando como uma cadeia de caracteres (Observação: esses comandos servem para conveniência ao trabalhar no prompt. Ao escrever scripts do PowerShell, o cmdlet cmd-device deve ser usado em vez disso).

exec-device(execd):executar executáveis

Para executar um comando no dispositivo, use o comando exec-device (execd). Toda a linha de comando após qualquer comutador será executada no modo em que se encontra no dispositivo. Todos os argumentos para o processo que começam com '-' devem ser passados entre aspas (simples ou duplas) para que o PowerShell não tente analisá-los. O TShell aguardará a saída do processo e a saída do código de saída para o console.

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

Para passar argumentos únicos entre aspas duplas para o processo do lado do dispositivo, você deve colocar todos os argumentos do processo entre aspas simples (que é uma cadeia de caracteres literal no PowerShell) ao passá-los para o TShell.

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

Por padrão, a saída do processo não será enviada para o shell. Você pode usar a opção -output para redirecionar o erro padrão para fora e padrão para o host, ambos serão retornados como propriedades do valor retornado do comando.

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

Por padrão, o comando será executado síncrono, o que significa que o TShell aguarda a saída do processo antes de retornar ao prompt. Você pode usar a opção -async para executar o processo de forma assíncrona; nesse caso, o TShell apenas inicia o processo e retorna imediatamente.

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

Cmdlets de interação do dispositivo

deploy-device(deployd): implantar pacotes de teste no dispositivo conectado

Para implantar um pacote no dispositivo, use o comando deploy-device (implantado).

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

Exemplo:

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

Para saber mais, execute get-help Deploy-Device -detailed.

Para implantar pacotes de teste WOW, adicione a opção -testarch. Exemplo:

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

As entradas TestArch com suporte são: amd64, x86, arm, arm64, wow64, arm64.arm, arm64.x86. Somente pacotes nativos serão implantados se nenhum TestArch for especificado.

diretório dir-device(dird):list

Você pode listar os diretórios em um dispositivo remoto:

dird

cd-device(cdd): alterar o diretório do dispositivo

O TShell marcar se o novo diretório existir no dispositivo e ocorrerá um erro se não existir. Há suporte para notação ponto a ponto para mover para o diretório pai e a $DeviceWD variável é atualizada a cada vez.

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

Você pode remover uma pasta de um dispositivo remoto:

rmdird c:\foldertoremove

copy-device(cpd, copyd):copy files

Copie arquivos entre diretórios no sistema remoto. (Isso não copia arquivos entre o host e o sistema remoto. Veja getd e putd para isso.)

del-device(deld):d elete file

Você pode excluir arquivos de um dispositivo remoto:

deld file.bat

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

Você pode criar um diretório em um dispositivo remoto:

mkdird c:\newfolder

move-device(mvd, moved):move files

Você pode mover pastas de um local em um dispositivo remoto para outro:

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

put-device(putd):copy files to

Para copiar arquivos para o dispositivo remoto, use o put-device (putd).

Ao copiar um arquivo para o dispositivo, você pode especificar o caminho do novo arquivo de dispositivo ou o diretório no qual ele deve ser copiado.

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

Os curingas têm suporte apenas para o caminho do host de origem e os caminhos do host e do dispositivo são relativos aos diretórios de trabalho atuais.

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

Há suporte para copiar diretórios recursivamente.

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

get-device(getd): copiar arquivos de

Para copiar arquivos do dispositivo, use os comandos get-device (getd).

Ao copiar um arquivo de ou para o dispositivo, você pode especificar o caminho do novo arquivo de dispositivo ou o diretório no qual ele deve ser copiado.

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

Os curingas têm suporte apenas para o caminho do host de origem e os caminhos do host e do dispositivo são relativos aos diretórios de trabalho atuais.

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

Há suporte para copiar diretórios recursivamente.

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

kill-device(killd)

reg-device(regd)

Usado para qualquer coisa relacionada a chaves do Registro. regd query "insert setting here" é usado para consultar chaves do Registro no dispositivo e regd add "insert setting here" é usado para adicionar/alterar as configurações do Registro.

tlist-device(tlistd)

Mostre o comando, a linha de comando, o diretório de trabalho, o uso de memória e as DLLs para cada tarefa em execução.

type-device(typed)

Imprime o conteúdo de um arquivo no dispositivo para o terminal (semelhante ao alias do PowerShell da área de trabalho "cat")

Obter informações sobre o dispositivo e o ambiente do TShell

get-variable device*

Mostrar endereço do dispositivo, nome e diretório de trabalho.

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

get-variable TShell*

Mostrar a versão do TShell instalada no dispositivo.

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

Cmdlets para depuração

debug-device(debugd):d ebug process

Para que esse comando funcione, você precisa instalar a versão mais recente do Depurador.

Para anexar um cliente de depurador (windbg é o padrão) a um processo de modo de usuário, use o comando debug-device (debugd). Um novo processo pode ser iniciado com o depurador anexado especificando o caminho do exe (pode ser relativo ao diretório de trabalho atual do dispositivo).

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

Ou anexe a um processo existente especificando o PID, que pode ser obtido usando o comando tlist-device.

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

PS C:\> debugd -pid 1234

Se nenhum for especificado, o cliente do depurador será iniciado com uma conexão com o dispositivo, mas nenhum processo anexado.

PS C:\> debugd

Você também pode especificar o caminho do cliente do depurador a ser usado com a opção -dbg

PS C:\> debugd -dbg C:\debuggers\ntsd.exe -pid 1234
Depurando um processo de aplicativo moderno

Para depurar um processo de aplicativo moderno na inicialização, anexe ao serviço DcomLaunch e habilite a depuração de processo filho:

No TShell:

PS C:\> debugd -servicename dcomlaunch

Em seguida, no depurador:

.childdbg 1