Экспорт (0) Печать
Развернуть все
EN
Данное содержимое не доступно на вашем языке, используйте версию на английском языке.

Automating Tracing Functions

At times, it may be advantageous for you to automate certain Message Analyzer functions that enable you to do the following:

  • Utilize enhancements to the manner in which you start and stop traces, for example, with various types of triggers such as a time trigger or process trigger.

  • Gain control over the type of trace that you run, for example, a linear or circular trace.

  • Run traces while you are focusing on other high-priority issues.

To enable these scenarios, Message Analyzer provides you with the capability to automate the capture of network messages through PowerShell scripting. Message Analyzer makes this feature available by providing PowerShell commandlets (cmdlets) that programmatically expose PEF message tracing functionality in the PowerShell scripting environment. Other supporting configuration capabilities are also provided in the PowerShell environment to facilitate some basic Trace Session configuration, including automation triggers that define how and when Trace Sessions are started and stopped.

The following topics in this section describe the PowerShell automation features that are available in Message Analyzer:

   Encapsulated Functionality

   PowerShell Cmdlets

   PowerShell Script Example

   Accessing PowerShell Cmdlets and Help

Important  Before you run any PowerShell cmdlets, ensure that you update the PowerShell cmdlet help for Message Analyzer. For further information, see Accessing PowerShell Cmdlets and Help.

Encapsulated Funtionality
The preconfigured PowerShell commandlets (cmdlets) that are provided with every Message Analyzer installation enable you to do the following:

  • Run circular capture Trace Sessions.

  • Configure new Trace Sessions.

  • Add a message provider to your Trace Session configuration.

  • Apply a Trace Filter to your Trace Session configuration by specifying a predefined or custom filter expression.

  • Specify the following types of triggers that can start and stop a Message Analyzer Trace Session or perform other functions:

    • DateTime

    • KeyDown

    • Message

    • Process

    • Event Log

    • Win32 Events

    • TimeSpan

  • Receive notification when a particular condition is met, for example, when an event triggers Message Analyzer to start a Trace Session or when a Trace Session stops.

  • Save a message data collection in the file system.

PowerShell Cmdlets
The following PowerShell cmdlets automate several Message Analyzer functions so that you can streamline your network problem solving tasks, gain more control over tracing functions, and achieve better time management. The cmdlets enable you to configure, start, stop, and save data for Trace Sessions and to specify trigger events that invoke or respond to these actions, as described below.

  • Action scripts:

    • Invoke-PefCustomAction — enables you to run a PowerShell script block that invokes PEF actions. You must specify the script block you want to run and a trigger for the actions it invokes. When the trigger occurs, such as a specified date-time to start or stop a Trace Session, the specified script block is invoked. The script block can contain any custom script necessary to perform custom PEF actions, for example, a script that stops a Trace Session and sends an email at that time. To learn more about script blocks, you can invoke Get-Help about_script_blocks at the PowerShell command line.

    • Save-PefDataCollection — enables you to save a collection of messages from a Trace Session. You must specify the session you want to save and the file path for the data. You can also specify a trigger that activates the save action when a Trace Session completes, so that you can save all messages currently contained in the session. You can also save a specified number of bytes so that you can analyze the data without stopping the Trace Session.

    • Set-PefTraceFilter — enables you to override the Trace Filter that you specified in a Trace Session object that you originally created with the New-PefTraceSession cmdlet. You can specify a string value for the Trace Filter and the target Trace Session as parameters of the Set-PefTraceFilter cmdlet. If you use the Set-PefTraceFilter to specify a Trace Filter, it will override any filtering value that you specified with the Filter parameter of the New-PefTraceSession cmdlet. If you do not specify a trigger for the override action, the Trace Filter that you specify will take effect immediately. However, if you do specify a trigger, you can control the point in time at which the Trace Filter is applied in the Trace Session. For example, you can set the Filter parameter of the New-PefTraceSession cmdlet to a specific value and then use the New-PefTimeSpanTrigger cmdlet to specify a time span after which a Trace Filter configured by the Set-PefTraceFilter cmdlet is inserted into the PEF Runtime component parsing and filtering processes.

      When you start a Trace Session with the Start-PefTraceSession cmdlet, the Trace Filter that you specify with the Set-PefTraceFilter cmdlet functions the same way as any other Trace Filter configured in the Message Analyzer UI. The Set-PefTraceFilter cmdlet also returns the target session to enable pipelining.

      Note  If you specify a file-based data source (such as a log file) as the message provider when creating a Trace Session with the New-PefTraceSession cmdlet, any filter that you specify with the Set-PefTraceFilter cmdlet will act as a Selection Filter.


      More Information
      To learn more about Selection Filters, see Applying a Selection Filter.
      To learn more about Trace Filters, see Creating and Applying Trace Filters.


    • Start-PefTraceSession — enables you to start a Message Analyzer Trace Session and to specify a trigger for the startup action. Start-PefTraceSession acts as an entry point for message processing. If you do not specify a trigger, Start-PefTraceSession initiates a processing loop where no other PowerShell cmdlets or functions are executed until the loop ends. If the Start-PefTraceSession cmdlet has a trigger, it will start a message processing loop only when that trigger is fired. When a message processing loop terminates, all active Trace Sessions are stopped. You can stop a Trace Session by invoking the Stop-PefTraceSession cmdlet, which causes Start-PefTraceSession to exit the processing loop. This cmdlet also returns the target session to enable pipelining.

    • Stop-PefTraceSession — provides the means to define how you will stop a specified Trace Session. When the session is stopped, it is terminated and the PEF Runtime state is cleaned up. You can also use this cmdlet to define the trigger action that stops a specified Trace Session, which you configure prior to starting the Trace Session. To store the data retrieved in the Trace Session, you can specify values for the SaveOnStop parameter when creating a Trace Session with the New-PefTraceSession cmdlet, or you can use the Save-PefDataCollection cmdlet to specify where to store retrieved data.

      Note  When you write a PowerShell script, you typically specify the Stop_PefTraceSession cmdlet before the Start-PefTraceSession cmdlet, because the Trace Session will start as soon as you hit return at the PowerShell command line after specifying the Start-PefTraceSession cmdlet.

  • Trigger scripts:

    • New-PefDateTimeTrigger — enables you to create a date-time trigger that you can use to start a Trace Session, stop a Trace Session, or inject a Trace Filter into the Trace Session at a specific time. When you associate a date-time trigger with a PEF action, the computer where the Trace Session will run sets a timer that triggers the specified PEF action when the trigger is activated.

    • New-PefKeyDownTrigger — enables you to create a trigger action based on keyboard input, by pressing Ctrl+C. You can use this keystroke trigger to start or stop a Trace session. When you associate this trigger with a PEF action, the PEF action occurs when the trigger fires on the computer where the Trace Session is running.

    • New-PefMessageTrigger — provides the means to create a message trigger that you can use to start, stop, save, or filter a PEF Trace Session, for example, based on a captured message type. When you associate this trigger with a PEF action, the PEF action occurs when the trigger fires on the computer where the Trace Session is running.

    • New-PefProcessTrigger — enables you to create a process trigger that starts a Trace Session when a process exits. For example, you might start a Trace Session after a started executable process has finished running. When you associate this trigger with a PEF action, the PEF action occurs when the trigger fires on the computer where the Trace Session is running.

    • New-PefTimeSpanTrigger — enables you to create a timer trigger that fires after a specified time span. You can use this timer trigger to start, stop, or add a Trace Filter to a Trace Session when a specified interval of time elapses.

    • New-PefEventLogTrigger — enables you to create a trigger that fires when an entry is created in the Windows Event Log.

    • New-PefWin32EventTrigger — enables you to create a trigger that fires when a Win32 Event object is set.

  • Miscellaneous scripts:

    • Add-PefMessageProvider — enables you to add one or more message providers to a specified Trace Session object that you create with the New-PefTraceSession cmdlet. A message provider can be a PEF message provider such as the Microsoft-Pef-WFP-MessageProvider, a system ETW provider, or even a file-based message source such as a log file.

    • New-PefTraceSession — enables you to create a Trace Session object that captures live data or retrieves stored messages, for example, from a log file. You can specify whether to capture data in circular or linear mode to control how much data is held in the Trace Session. You can also configure a Trace Filter to focus the data retrieval action on messages that meet specific filtering criteria. If you want to save the data to a file after the Trace Session is stopped, you can do so by specifying the SaveOnStop parameter. For each Trace Session that you configure, you must add the message provider you want to use, such as the Microsoft-Pef-NDIS-PacketCapture or Microsoft-Pef-WFP-MessageProvider, by specifying it with the Add-PefMessageProvider cmdlet. To start and stop the Trace Session, you can use the Start-PefTraceSession and Stop-PefTraceSession, respectively, along with configuring any triggers that facilitate such actions.

PowerShell Script Example
To automate Message Analyzer network trace functionality with PowerShell, you will need to string together PowerShell cmdlets to achieve a desired result. The base cmdlet upon which all other cmdlet functionality depends is the New-PefTraceSession cmdlet. For example, you must use this cmdlet first to create a trace session object and then use other cmdlets to include additional configurations, such as adding the provider to use in the Trace Session, specifying an override filter, adding data saving functions, and configuring trigger actions.

The following example uses the New-PefTraceSession cmdlet to create a Trace Session object that is stored in the variable $TraceSession01 and is configured for the circular capture mode. The script then uses the Add-PefMessageProvider cmdlet to specify the provider that Message Analyzer should use to capture data and associates the provider specification with $TraceSession01. Next, the Set-PefTraceFilter configures a “TCP” Trace Filter that will be applied to the trace 150 seconds after the Trace Session starts, as specified by the variable $Trigger01, which is configured with the New-PefTimeSpanTrigger cmdlet. The script then specifies two more triggers; $Trigger02, which configures the time at which the Trace Session will start, and $Trigger03, which specifies the PEF action that stops the Trace Session, which in this case is the keyboard shortcut Ctrl+C. These triggers are then associated with the Stop-PefTraceSession and Start-PefTraceSession cmdlets, respectively. Lastly, the Save-PefDataCollection cmdlet specifies the trace file type (.matu) and the file name and full path where the Trace Session data will be stored at the time $Trigger03 occurs. The Force parameter in this cmdlet causes the data of any existing file of the same name to be overwritten. The Start-PefTraceSession cmdlet then begins the session when $Trigger02 fires.

The syntax for this functionality is specified as follows:

$TraceSession01 = New-PefTraceSession -Mode Circular
Add-PefMessageProvider -Session $TraceSession01 –Provider "Microsoft-PEF-WFP-MessageProvider"
$Trigger01 = New-PefTimeSpanTrigger -TimeSpan (New-TimeSpan -Seconds 150)
Set-PefTraceFilter -Session $TraceSession01 –Filter "TCP" -Trigger $Trigger01
$Trigger02 = New-PefDateTimeTrigger -DateTime “9/30/2013 7:00 AM"
$Trigger03 = New-PefKeyDownTrigger -CTRLC
Stop-PefTraceSession -Session $TraceSession01 -Trigger $Trigger03
Save-PefDataCollection -Session $TraceSession01 -Path <”fullTracePath\myTrace.matu”> -Force -Trigger $Trigger03
Start-PefTraceSession -Session $TraceSession01 –Trigger $Trigger02

Accessing PowerShell Cmdlets and Help
To take advantage of the functionality provided in the previously described PowerShell cmdlets for Message Analyzer, you must have PowerShell v3.0 installed. PowerShell v3.0 installs automatically with Windows 8 and later operating systems; however, if you are running Windows 7, you will need to install the Windows Management Framework 3.0 to obtain a PowerShell v3.0 installation. After you have a PowerShell v3.0 installation in place on your Windows 7 machine, you will need to run the following command to import the PEF PowerShell module into your PowerShell session:
Import-Module PEF
Then, to update the help, run the following command to download the latest cmdlet Help content from TechNet:
Update-Help -Module PEF -Force –Verbose

Note  PowerShell cmdlet help documentation is available at the PowerShell command line and also in the TechNet Library on the Message Analyzer Cmdlets site. For complete command-line syntax, parameter specifications, and usage examples, see these locations. If you want to view help at the PowerShell command line for a particular cmdlet, specify the following command string:
get-help <cmdletname>

More Information
To learn more about writing Trace Filters and other Filter Expressions, see Writing Filter Expressions.

Была ли вам полезна эта информация?
(1500 символов осталось)
Спасибо за ваш отзыв
Показ:
© 2014 Microsoft