Set-TraceSource
Configura, inicia e interrompe um rastreamento dos componentes do Windows PowerShell.
Sintaxe
Set-TraceSource [[-Option] {<None> | <Constructor> | <Dispose> | <Finalizer> | <Method> | <Property> | <Delegates> | <Events> | <Exception> | <Lock> | <Error> | <Errors> | <Warning> | <Verbose> | <WriteLine> | <Data> | <Scope> | <ExecutionFlow> | <Assert> | <All>}] [-Debugger] [-FilePath <string>] [-Force] [-ListenerOption {<None> | <LogicalOperationStack> | <DateTime> | <Timestamp> | <ProcessId> | <ThreadId> | <Callstack>}] [-PassThru] [-PSHost] [-Name] <string[]> [<CommonParameters>]
Set-TraceSource [-RemoveListener <string[]>] [-Name] <string[]> [<CommonParameters>]
Set-TraceSource [-RemoveFileListener <string[]>] [-Name] <string[]> [<CommonParameters>]
Descrição
O cmdlet Set-TraceSource configura, inicia e interrompe um rastreamento de um componente do Windows PowerShell. Você pode usá-lo para especificar quais componentes serão rastreados e para que saída o rastreamento será enviado.
Parâmetros
-Debugger
Envia a saída do rastreamento para o depurador. Você pode exibir a saída em qualquer depurador no modo de usuário ou kernel ou no Microsoft Visual Studio. Esse parâmetro também seleciona a escuta do rastreamento padrão.
Necessário? |
false |
Posição? |
named |
Valor padrão |
|
Aceitar entrada do pipeline? |
false |
Aceitar caracteres curinga? |
false |
-FilePath <string>
Envia a saída do rastreamento para o arquivo especificado. Esse parâmetro também seleciona a escuta do rastreamento de arquivo. Se você usar esse parâmetro para iniciar o rastreamento, use o parâmetro RemoveFileListener para interromper o rastreamento.
Necessário? |
false |
Posição? |
named |
Valor padrão |
|
Aceitar entrada do pipeline? |
false |
Aceitar caracteres curinga? |
false |
-Force
Permite que o cmdlet substitua um arquivo somente leitura. Use com o parâmetro FilePath.
Necessário? |
false |
Posição? |
named |
Valor padrão |
|
Aceitar entrada do pipeline? |
false |
Aceitar caracteres curinga? |
false |
-ListenerOption <TraceOptions>
Adiciona dados opcionais ao prefixo de cada mensagem de rastreamento na saída. Os valores válidos são "None", "LogicalOperationStack", "DateTime", "Timestamp", "ProcessId", "ThreadId" e "Callstack". "None" é o padrão.
Para especificar várias opções, separe-as com vírgulas, mas sem espaços, e coloque-as entre aspas, como "ProcessID,ThreadID".
Necessário? |
false |
Posição? |
named |
Valor padrão |
|
Aceitar entrada do pipeline? |
false |
Aceitar caracteres curinga? |
false |
-Name <string[]>
Determina quais componentes serão rastreados. Digite o nome da fonte de rastreamento de cada componente. Os caracteres curinga são permitidos.
Necessário? |
true |
Posição? |
1 |
Valor padrão |
|
Aceitar entrada do pipeline? |
true (ByValue, ByPropertyName) |
Aceitar caracteres curinga? |
false |
-Option <PSTraceSourceOptions>
Determina os tipos de eventos que são rastreados.
Os valores válidos são: "None", "Constructor", "Dispose", "Finalizer", "Method", "Property", "Delegates", "Events", "Exception", "Lock", "Error", "Errors", "Warning", "Verbose", "WriteLine", "Data", "Scope", "ExecutionFlow", "Assert" e "All". "All" é o padrão.
Os seguintes valores são combinações de outros valores:
-- ExecutionFlow: (Constructor, Dispose, Finalizer, Method, Delegates, Events e Scope)
-- Data: (Constructor, Dispose, Finalizer, Property, Verbose e WriteLine)
-- Errors: (Error e Exception).
Para especificar várias opções, separe-as com vírgulas, mas sem espaços, e coloque-as entre aspas, como "Constructor,Dispose".
Necessário? |
false |
Posição? |
2 |
Valor padrão |
|
Aceitar entrada do pipeline? |
true (ByPropertyName) |
Aceitar caracteres curinga? |
false |
-PassThru
Retorna um objeto que representa a sessão de rastreamento. Por padrão, este cmdlet não gera nenhuma saída.
Necessário? |
false |
Posição? |
named |
Valor padrão |
|
Aceitar entrada do pipeline? |
false |
Aceitar caracteres curinga? |
false |
-PSHost
Envia a saída do rastreamento para o host do Windows PowerShell. Esse parâmetro também seleciona a escuta do rastreamento PSHost.
Necessário? |
false |
Posição? |
named |
Valor padrão |
|
Aceitar entrada do pipeline? |
false |
Aceitar caracteres curinga? |
false |
-RemoveFileListener <string[]>
Interrompe o rastreamento ao remover a escuta de rastreamento de arquivo associada ao arquivo especificado. Digite o caminho e o nome do arquivo de saída do rastreamento.
Necessário? |
false |
Posição? |
named |
Valor padrão |
|
Aceitar entrada do pipeline? |
false |
Aceitar caracteres curinga? |
false |
-RemoveListener <string[]>
Interrompe o rastreamento ao remover a escuta do rastreamento.
Use os seguintes valores com o RemoveListener:
--Para remover o PSHost (console), digite "Host".
--Para remover o Depurador, digite "Debug".
--Para remover todas as escutas de rastreamento, digite "*".
Para remover a escuta do rastreamento de arquivo, use o parâmetro RemoveFileListener.
Necessário? |
false |
Posição? |
named |
Valor padrão |
|
Aceitar entrada do pipeline? |
false |
Aceitar caracteres curinga? |
false |
<CommonParameters>
Esse cmdlet oferece suporte aos parâmetros comuns: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer e -OutVariable. Para obter mais informações, consulte about_Commonparameters.
Entradas e saídas
O tipo de entrada é o tipo dos objetos que você pode canalizar para o cmdlet. O tipo de retorno é o tipo dos objetos que o cmdlet retorna.
Entradas |
System.String Você pode canalizar uma cadeia de caracteres que contém um nome para Set-TraceSource. |
Saídas |
Nenhum ou System.Management.Automation.PSTraceSource Quando você usa o parâmetro PassThru, Set-TraceSource gera um objeto System.Management.Automation.PSTraceSource que representa a sessão de rastreamento. Caso contrário, esse cmdlet não gera nenhuma saída. |
Observações
O rastreamento é um método que os desenvolvedores utilizam para depurar e refinar programas. Ao rastrear, o programa gera mensagens detalhadas sobre cada etapa em seu processamento interno.
Os cmdlets de rastreamento do Windows PowerShell foram projetados para auxiliar os desenvolvedores do Windows PowerShell, mas também estão disponíveis para todos os usuários. Eles permitem que você monitore praticamente todos os aspectos da funcionalidade do Windows PowerShell.
Uma "fonte de rastreamento" é a parte de cada componente do Windows PowerShell que gerencia o rastreamento e gera as mensagens de rastreamento do componente. Para rastrear um componente, você identifica sua fonte de rastreamento.
Uma "escuta do rastreador" recebe a saída do rastreamento e a exibe ao usuário. Você pode decidir enviar os dados de rastreamento para um depurador do modo de usuário ou kernel para o console, para um arquivo ou para uma escuta personalizada derivada da classe System.Diagnostics.TraceListener.
Para iniciar um rastreamento, use o parâmetro Name para especificar uma fonte de rastreamento (o componente a ser rastreado) e os parâmetros FilePath, Debugger ou PSHost, a fim de especificar uma escuta (um destino para a saída). Use o parâmetro Options para determinar os tipos de eventos que são rastreados e o parâmetro ListenerOptions para configurar a saída do rastreamento.
Para alterar a configuração de um rastreamento, insira um comando Set-TraceSource da mesma forma que faria para iniciar um rastreamento. O Windows PowerShell reconhece que a fonte de rastreamento já está sendo rastreada. Ele interrompe o rastreamento, adiciona a nova configuração e inicia ou reinicia o rastreamento.
Para interromper um rastreamento, use o parâmetro RemoveListener. Para interromper um rastreamento que use uma escuta de arquivo (um rastreamento iniciado usando o parâmetro -FilePath), use o parâmetro RemoveFileListener. Ao remover a escuta, o rastreamento é interrompido.
Para determinar quais componentes podem ser rastreados, use Get-TraceSource. As fontes de rastreamento para cada módulo serão carregadas automaticamente quando o componente estiver em uso e aparecerão na saída do Get-TraceSource.
Exemplo 1
C:\PS>Set-TraceSource -Name Parameterbinding -Option ExecutionFlow -PSHost '
-ListenerOption "ProcessID,TimeStamp"
Descrição
-----------
Este comando inicia o rastreamento do componente ParameterBinding do Windows PowerShell. Ele usa o parâmetro Name para especificar a fonte de rastreamento, o parâmetro Option para selecionar os eventos de rastreamento ExecutionFlow e o parâmetro PSHost para selecionar a escuta host do Windows PowerShell, a qual envia a saída para o console. O parâmetro ListenerOption adiciona os valores "ProcessID" e "TimeStamp" ao prefixo da mensagem de rastreamento.
Exemplo 2
C:\PS>set-tracesource -name ParameterBinding -RemoveListener Host
Descrição
-----------
Este comando interrompe o rastreamento do componente ParameterBinding do Windows PowerShell. Ele usa o parâmetro Name para identificar o componente sendo rastreado e o parâmetro RemoveListener para identificar a escuta do rastreamento.