Measure Command - PowerShell

Overview

Measure-Command is a PowerShell command that measures the time it takes for a specified command or script block to complete. It provides performance data, including elapsed time, CPU usage, and memory consumption, helping optimize and troubleshoot scripts.

Syntax

Measure-Command [-ScriptBlock] <script block> [-Expression] <expression> [-AsJob] [-Container <container>] [-Credential <credential>] [-EventSubscriber <event subscriber>] [-Force] [-JobState <job state>] [-MaximumErrorCount <int>] [-MinimumSeconds <int>] [-Name <string>] [-ScriptArgument <object>] [-ScriptArgs <string[]>] [-ScriptFilePath <string>] [-ScriptIsHidden] [-ScriptLine <int>] [-ScriptParameter <script parameter>] [-ScriptUsesCurrentUserCredentials] [-StopwatchEnabled] [-Verbose] [-WhatIf] [-Confirm] [-ThrottleLimit <int>]

Options/Flags

  • -Expression: Specify a PowerShell expression to measure the time taken to evaluate.
  • -ScriptBlock: Script block to measure the time taken to execute.
  • -Container: Name of the container in which to run the command or script block.
  • -Credential: Credential to use for running the command or script block.
  • -EventSubscriber: Subscriber to receive events from the command or script block.
  • -Force: Suppress error messages and continue running the command or script block.
  • -JobState: State of the job to be measured.
  • -MaximumErrorCount: Maximum number of errors to allow before stopping the measurement.
  • -MinimumSeconds: Minimum number of seconds to measure before completing.
  • -Name: Name of the measurement session.
  • -ScriptArgument: Argument to pass to the script block.
  • -ScriptArgs: Array of arguments to pass to the script block.
  • -ScriptFilePath: Path to the script file to execute.
  • -ScriptIsHidden: Hide the script block or script file from the console.
  • -ScriptLine: Line number where the measurement should begin.
  • -ScriptParameter: Parameter to pass to the script block.
  • -ScriptUsesCurrentUserCredentials: Run the script block using the current user’s credentials.
  • -StopwatchEnabled: Enable or disable the stopwatch functionality.
  • -Verbose: Output detailed information about the measurement session.
  • -WhatIf: Simulate the measurement without actually executing it.
  • -Confirm: Prompt for confirmation before running the measurement.
  • -ThrottleLimit: Limit the number of simultaneous measurement sessions.

Examples

Example 1: Measuring execution time of a script block

Measure-Command { Get-Process }

Example 2: Evaluating an expression and measuring the time taken

Measure-Command -Expression { 1 + 2 }

Example 3: Measuring the performance of a complex script

$script = Get-Content "script.ps1"
Measure-Command { Invoke-Expression $script }

Common Issues

  • High CPU usage: Ensure that the script block or command being measured does not perform excessive or inefficient operations.
  • Inaccurate results: Verify that the -MinimumSeconds parameter is set to a reasonable value to ensure sufficient time for measurement.
  • Measurement failing: Check for errors in the script block or command being measured, and ensure that the necessary permissions are granted for execution.

Integration

Measure-Command can be used with other PowerShell commands to create automated performance monitoring and troubleshooting scripts. For example:

$results = Measure-Command { Get-Process }
Export-Csv -Path "results.csv" -InputObject $results