New-PefCaptureSession
New-PefCaptureSession
Creates a PEF trace session.
Syntax
Parameter Set: Default
New-PefCaptureSession [[-Mode] <SessionMode> ] [[-Filter] <String> ] [[-Force]] [[-Path] <String> ] [[-TotalSize] <Uint> ] [[-UnitSize] <Uint> ] [-Name <String> ] [-SaveOnStop] [ <CommonParameters>]
Detailed Description
The New-PefCaptureSession cmdlet creates a Protocol Engineering Framework (PEF) Trace Session to capture live data or to load message data from saved trace files or logs. This cmdlet enables you to specify a mode, either Circular or Linear, to control how much data the Trace Session holds. You can also specify a filter that selects specific types of messages during data retrieval, either from a Trace Session or from saved files and logs. Use the SaveOnStop parameter to save a data collection to a file when the Trace Session stops.
You can use the Add-PefMessageProvider to specify a message provider for a capture session.
After you create a Trace Session object, use the Start-PefCaptureSession and Stop-PefCaptureSession cmdlets to define how the session will start and stop collecting message data.
You need to be a member of the Message Capture Users Group and the Performance Log Users Group.
Parameters
-Filter<String>
Specifies a string that configures a Trace Filter, which defines the types of messages a Trace Session retrieves.
Aliases |
none |
Required? |
false |
Position? |
2 |
Default Value |
none |
Accept Pipeline Input? |
false |
Accept Wildcard Characters? |
false |
-Mode<SessionMode>
Specifies a mode for the Trace Session. The acceptable values for this parameter are:
— Circular. The Trace Session records data until the data size reaches a limit defined by the TotalSize dynamic parameter, and then the session records new data while discarding the oldest recorded data.
— Linear. The session does not discard data.
The default value for this parameter is Linear.
Aliases |
none |
Required? |
false |
Position? |
1 |
Default Value |
none |
Accept Pipeline Input? |
false |
Accept Wildcard Characters? |
false |
-Name<String>
Specifies an input file path. If you use the SaveOnStop parameter, you can specify this parameter to cause the trace session to retrieve input data from the specified file
Aliases |
none |
Required? |
false |
Position? |
named |
Default Value |
none |
Accept Pipeline Input? |
false |
Accept Wildcard Characters? |
false |
-SaveOnStop
Indicates that the Trace Session saves data when it stops. You can use the Name dynamic parameter to specify a file path for saving the data.
Aliases |
none |
Required? |
false |
Position? |
named |
Default Value |
none |
Accept Pipeline Input? |
false |
Accept Wildcard Characters? |
false |
-Force
Indicates that the cmdlet overwrites the data of an existing saved Trace Session file that is specified by the Path parameter. You can specify this dynamic parameter if the command also includes the SaveOnStop parameter.
Aliases |
none |
Required? |
false |
Position? |
2 |
Default Value |
none |
Accept Pipeline Input? |
false |
Accept Wildcard Characters? |
false |
-Path<String>
Specifies a file path to save a Trace Session. You can specify this dynamic parameter if the New-PefCaptureSession cmdlet also includes the SaveOnStop parameter. The current folder is the default location for saving session data when you use the Path parameter.
Aliases |
none |
Required? |
false |
Position? |
2 |
Default Value |
none |
Accept Pipeline Input? |
false |
Accept Wildcard Characters? |
false |
-TotalSize<Uint>
Specifies the total size, in megabytes, of a circular message store. You can specify this dynamic parameter if the Mode parameter has a value of Circular. The default value for this parameter is 100 MB.
Aliases |
none |
Required? |
false |
Position? |
2 |
Default Value |
none |
Accept Pipeline Input? |
false |
Accept Wildcard Characters? |
false |
-UnitSize<Uint>
Specifies the size, in bytes, of a circular store unit. You can specify this dynamic parameter if the Mode parameter has a value of Circular. The default value for this parameter is 20 MB.
Aliases |
none |
Required? |
false |
Position? |
2 |
Default Value |
none |
Accept Pipeline Input? |
false |
Accept Wildcard Characters? |
false |
<CommonParameters>
This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see about_CommonParameters.
Inputs
The input type is the type of the objects that you can pipe to the cmdlet.
Outputs
The output type is the type of the objects that the cmdlet emits.
Examples
Example 1: Create and run a PEF Trace Session
This example creates and starts a PEF Trace Session.
The first command creates a Trace Session object and stores it in the $TraceSession01 variable. This command specifies the Circular capture mode, with a total size of 50 MB. The command also uses the SaveOnStop parameter and specifies a name for the trace file Trace01.matu, by using the Path parameter, which saves the Trace Session results in the current directory. The command uses the Force parameter, which causes any existing file of the same name to be overwritten when your Trace Session results are saved.
The second command uses the Add-PefMessageProvider cmdlet to specify a provider for the Trace Session stored in the $TraceSession01 variable.
The third command uses the Stop-PefCaptureSession cmdlet to create a stop action that activates on a the Ctrl+C keystroke trigger, which this cmdlet associates with the Trace Session object stored in the $TraceSession01 variable.
The fourth command uses the Start-PefCaptureSession cmdlet to start the Trace Session stored in the $TraceSession01 variable.
PS C:\> $TraceSession01 = New-PefCaptureSession -Mode Circular -Force -Path ".\Trace01.matu" -TotalSize 50 -SaveOnStop
PS C:\> Add-PefMessageProvider -Session $TraceSession01 –Provider "Microsoft-PEF-NDIS-PacketCapture"
PS C:\> Stop-PefCaptureSession -Session $TraceSession01 -Trigger (New-PefKeyDownTrigger -CTRLC)
PS C:\> Start-PefCaptureSession -Session $TraceSession01