VSInstr

  • Článek

Applies to: yesVisual Studio noVisual Studio for Mac

Note

This article applies to Visual Studio 2017. If you're looking for the latest Visual Studio documentation, see Visual Studio documentation. We recommend upgrading to the latest version of Visual Studio. Download it here

The VSInstr tool is used to instrument binaries. It is invoked by using the following syntax:

VSInstr [/U] filename [/options]

The following table describes VSInstr tool options:

Options Description
Help or ? Displays help.
U Writes the redirected console output as Unicode. It must be first option specified.
@filename Specifies the name of a response file that contains one command option per line. Do not use quotation marks.
OutputPath :path Specifies a destination directory for the instrumented image. If an output path is not specified, the original binary is renamed by appending "Orig" to the file name in the same directory, and a copy of the binary is instrumented.
Exclude: funcspec Specifies a function specification to exclude from instrumentation by probes. It is useful when profiling probe insertion in a function causes unpredictable or unwanted results.

Do not use Exclude and Include options that refer to functions in the same binary.

You can specify multiple function specification with separate Exclude options.

funcspec is a defined as:

[namespace<separator1>] [class<separator2>]function

<separator1> is :: for native code, and . for managed code.

<separator2> is always ::

Exclude is supported with code coverage.

The wildcard character * is supported. For example, to exclude all functions in a namespace use:

MyNamespace::*

You can use VSInstr /DumpFuncs to list the complete names of functions in the specified binary.
Include: funcspec Specifies a function specification in a binary to instrument with probes. All other functions in the binaries are not instrumented.

You can specify multiple function specifications with separate Include options.

Do not use Include and Exclude options that refer to functions in the same binary.

Include is not supported with code coverage.

funcspec is a defined as:

[namespace<separator1>] [class<separator2>]function

<separator1> is :: for native code, and . for managed code.

<separator2> is always ::

The wildcard character * is supported. For example, to include all functions in a namespace use:

MyNamespace::*

You can use VSInstr /DumpFuncs to list the complete names of functions in the specified binary.
DumpFuncs Lists the functions within the specified image. No instrumentation is performed.
ExcludeSmallFuncs Excludes small functions, which are short functions that do not make any function calls, from instrumentation. The ExcludeSmallFuncs option provides for less instrumentation overhead a thus improved instrumentation speed.

The exclusion of small functions also reduces the .vsp file size and time required for analysis.
Mark:{Before|After|Top|Bottom},funcname,markid Inserts a profile mark (an identifier used to delimit the data in reports) that you can use to identify the start or end of a data range in the .vsp report file.

Before - Immediately before the target function entry.

After - Immediately after the target function exit.

Top - Immediately after the target function entry.

Bottom - Immediately before each return in the target function.

funcname - Name of the target function

Markid - A positive integer (long) to use as the identifier of the profile mark.
Coverage Performs coverage instrumentation. It can be used only with the following options: Verbose, OutputPath, Exclude, and Logfile..
Verbose The Verbose option is used to view detailed information about the instrumentation process.
NoWarn [:[Message Number[;Message Number]]] Suppress all or specific warnings.

Message Number - the warning number. If Message Number is omitted, all warnings are suppressed.

For more information, see VSInstr Warnings.
Control: { Thread | Process | Global } Specifies the profiling level of the following VSInstr data collection control Options:

Start

StartOnly

Suspend

StopOnly

SuspendOnly

ResumeOnly

Thread - specifies thread-level data collection control functions. Profiling is started or stopped only for the current thread. The profiling state of other threads is not affected. The default is thread.

Process - specifies process-level profiling data collection control functions. Profiling starts or stops for all threads in the current process. The profiling state of other processes is not affected.

Global - specifies global-level (cross-process) data collection control functions.

An error occurs if you do not specify the profiling level.
Start: { Inside | Outside },funcname Limits data collection to the target function and child functions called by that function.

Inside - Inserts the StartProfile function immediately after the entry to the target function. Inserts the StopProfile function immediately before each return in the target function.

Outside - Inserts the StartProfile function immediately before each call to the target function. Inserts the StopProfile function immediately after each call to the target function.

funcname - the name of the target function.
Suspend: { Inside | Outside },funcname Excludes data collection for the target function and child functions called by the function.

Inside - Inserts the SuspendProfile function immediately after the entry to the target function. Inserts the ResumeProfile function immediately before each return in the target function.

Outside - Inserts the SuspendProfile function immediately before the entry to the target function. Inserts the ResumeProfile function immediately after the exit from the target function.

funcname - name of the target function.

If the target function contains a StartProfile function, the SuspendProfile function is inserted before it. If the target function contains a StopProfile function, the ResumeProfile function is inserted after it.
StartOnly: { Before | After | Top | Bottom },funcname Begins data collection during a profiling run. It inserts the StartProfile API function at the specified location.

Before - immediately before the target function entry.

After - immediately after the target function exit.

Top - immediately after the target function entry.

Bottom - immediately before each return in the target function.

funcname - name of the target function.
StopOnly:{Before|After|Top|Bottom},funcname Halts data collection during a profiling run. It inserts the StopProfile function at the specified location.

Before - immediately before the target function entry.

After - immediately after the target function exit.

Top - immediately after the target function entry.

Bottom - immediately before each return in the target function.

funcname - name of the target function.
SuspendOnly:{Before|After|Top|Bottom},funcname Halts data collection during a profiling run. It inserts the SuspendProfile API at the specified location.

Before - immediately before the target function entry.

After - immediately after the target function exit.

Top - immediately after the target function entry.

Bottom - immediately before each return in the target function.

funcname - name of the target function.

If the target function contains a StartProfile function, the SuspendProfile function is inserted before it.
ResumeOnly:{Before|After|Top|Bottom},funcname Begins or resumes data collection during a profiling run.

It is usually used to start profiling after a SuspendOnly option has stopped profiling. It inserts a ResumeProfile API at the specified location.

Before - immediately before the target function entry.

After - immediately after the target function exit.

Top - immediately after the target function entry.

Bottom - immediately before each return in the target function.

funcname - name of the target function.

If the target function contains a StopProfile function, the ResumeProfile function is inserted after it.

See also