From a83ecceca8abfd3bc9faf0496012937fe69bab1b Mon Sep 17 00:00:00 2001 From: Chet Husk Date: Tue, 15 Jul 2025 10:33:17 -0500 Subject: [PATCH 1/3] Add -bl placeholder docs and example --- docs/msbuild/msbuild-command-line-reference.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/msbuild/msbuild-command-line-reference.md b/docs/msbuild/msbuild-command-line-reference.md index 951ed0c056e..109ee60f177 100644 --- a/docs/msbuild/msbuild-command-line-reference.md +++ b/docs/msbuild/msbuild-command-line-reference.md @@ -78,7 +78,7 @@ Square brackets `[]` indicate optional parts, and curly braces `{}`indicate user |Switch|Description| |------------|-----------------| -|`-binaryLogger[:[LogFile=]{output.binlog}`
`[;ProjectImports=None`,`Embed`,`ZipFile]]`

`-bl[:[LogFile=]{output.binlog}`
`[;ProjectImports=None`,`Embed`,`ZipFile]]`|Serializes all build events to a compressed binary file. By default the file is in the current directory and named *msbuild.binlog*. The binary log is a detailed description of the build process that can later be used to reconstruct text logs and used by other analysis tools. A binary log is usually 10-20x smaller than the most detailed text diagnostic-level log, but it contains more information.

The binary logger by default collects the source text of project files, including all imported projects and target files encountered during the build. The optional `ProjectImports` parameter controls this behavior:

- **ProjectImports=None**. Don't collect the project imports.
- **ProjectImports=Embed**. Embed project imports in the log file (default).
- **ProjectImports=ZipFile**. Save project files to *{output}.projectimports.zip* where \ is the same name as the binary log file name.

The default setting for ProjectImports is Embed.
**Note**: the logger doesn't collect non-MSBuild source files such as `.cs`, `.cpp`, and so on.
A *.binlog* file can be "played back" by passing it to *msbuild.exe* as an argument instead of a project/solution. Other loggers receive the information contained in the log file as if the original build was happening. You can read more about the binary log and its usages at: https://github.com/dotnet/msbuild/blob/main/documentation/wiki/Binary-Log.md

**Examples**:
- `-bl`
- `-bl:output.binlog`
- `-bl:output.binlog;ProjectImports=None`
- `-bl:output.binlog;ProjectImports=ZipFile`
- `-bl:..\..\custom.binlog`
- `-binaryLogger`| +|`-binaryLogger[:[LogFile=]{output.binlog}`
`[;ProjectImports=None`,`Embed`,`ZipFile]]`

`-bl[:[LogFile=]{output.binlog}`
`[;ProjectImports=None`,`Embed`,`ZipFile]]`|Serializes all build events to a compressed binary file. By default the file is in the current directory and named *msbuild.binlog*. The optional `LogFile` parameter accepts a string of the form `{filename}.binlog`, where `{filename}` contains valid file system characters, but also accepts a placeholder symbol `{}`. If `{}` is provided, MSBuild will fill that position with a 'unique stamp' of the form `yyyyMMdd-HHmmss----<6-character random string>`. The binary log is a detailed description of the build process that can later be used to reconstruct text logs and used by other analysis tools. A binary log is usually 10-20x smaller than the most detailed text diagnostic-level log, but it contains more information.

The binary logger by default collects the source text of project files, including all imported projects and target files encountered during the build. The optional `ProjectImports` parameter controls this behavior:

- **ProjectImports=None**. Don't collect the project imports.
- **ProjectImports=Embed**. Embed project imports in the log file (default).
- **ProjectImports=ZipFile**. Save project files to *{output}.projectimports.zip* where \ is the same name as the binary log file name.

The default setting for ProjectImports is Embed.
**Note**: the logger doesn't collect non-MSBuild source files such as `.cs`, `.cpp`, and so on.
A *.binlog* file can be "played back" by passing it to *msbuild.exe* as an argument instead of a project/solution. Other loggers receive the information contained in the log file as if the original build was happening. You can read more about the binary log and its usages at: https://github.com/dotnet/msbuild/blob/main/documentation/wiki/Binary-Log.md

**Examples**:
- `-bl`
- `-bl:output.binlog`
- `-bl:output.binlog;ProjectImports=None`
- `-bl:output.binlog;ProjectImports=ZipFile`
- `-bl:..\..\custom.binlog`
- `-bl:publish-{}.binlog`
- `-binaryLogger`| |`-consoleLoggerParameters:{parameters}`

`-clp:{parameters}`|Pass the parameters that you specify to the console logger, which displays build information in the console window. You can specify the following parameters:

- **PerformanceSummary**. Show the time that's spent in tasks, targets, and projects.
- **Summary**. Show the error and warning summary at the end.
- **NoSummary**. Don't show the error and warning summary at the end.
- **ErrorsOnly**. Show only errors.
- **WarningsOnly**. Show only warnings.
- **NoItemAndPropertyList**. Don't show the list of items and properties that would appear at the start of each project build if the verbosity level is set to `diagnostic`.
- **ShowCommandLine**. Show `TaskCommandLineEvent` messages.
- **ShowProjectFile**. Show the path to the project file in diagnostic messages. This setting is on by default.
- **ShowTimestamp**. Show the timestamp as a prefix to any message.
- **ShowEventId**. Show the event ID for each started event, finished event, and message.
- **ForceNoAlign**. Don't align the text to the size of the console buffer.
- **DisableConsoleColor**. Use the default console colors for all logging messages.
- **DisableMPLogging**. Disable the multiprocessor logging style of output when running in non-multiprocessor mode.
- **EnableMPLogging**. Enable the multiprocessor logging style even when running in non-multiprocessor mode. This logging style is on by default.
- **ForceConsoleColor**. Use ANSI console colors even if console doesn't support it.
- **Verbosity**. Override the `-verbosity` setting for this logger.

Use a semicolon to separate multiple parameters, as the following example shows:

`-consoleLoggerParameters:PerformanceSummary;NoSummary -verbosity:minimal`

The default console logger is at normal verbosity and includes a `Summary`.| |`-distributedFileLogger`

`-dfl`|Log the build output of each MSBuild node to its own file. The initial location for these files is the current directory. By default, the files are named *MSBuild\{NodeId}.log*. You can use the `-fileLoggerParameters` switch to specify the location of the files and other parameters for the fileLogger.

If you name a log file by using the `-fileLoggerParameters` switch, the distributed logger uses that name as a template and append the node ID to that name when creating a log file for each node.| |`-distributedLogger:{central logger},{forwarding logger}, ...`

`-dl:{central logger},{forwarding logger, ...}`|Log events from MSBuild, attaching a different logger instance to each node. To specify multiple loggers, specify each logger separately.

You use the logger syntax to specify a logger, except you provide and additional class for the forwarding logger. For the logger syntax, see the `-logger` switch.

The following examples show how to use this switch:

`-dl:XMLLogger,MyLogger,Version=1.0.2,Culture=neutral`

`-dl:MyLogger,C:\My.dll*ForwardingLogger,C:\Logger.dll`| From 4ece478aa46412d6175b585aed791c61d7f50838 Mon Sep 17 00:00:00 2001 From: Gordon Hogenson Date: Wed, 23 Jul 2025 09:07:39 -0700 Subject: [PATCH 2/3] Update docs/msbuild/msbuild-command-line-reference.md --- docs/msbuild/msbuild-command-line-reference.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/msbuild/msbuild-command-line-reference.md b/docs/msbuild/msbuild-command-line-reference.md index 109ee60f177..374c0d0070c 100644 --- a/docs/msbuild/msbuild-command-line-reference.md +++ b/docs/msbuild/msbuild-command-line-reference.md @@ -78,7 +78,7 @@ Square brackets `[]` indicate optional parts, and curly braces `{}`indicate user |Switch|Description| |------------|-----------------| -|`-binaryLogger[:[LogFile=]{output.binlog}`
`[;ProjectImports=None`,`Embed`,`ZipFile]]`

`-bl[:[LogFile=]{output.binlog}`
`[;ProjectImports=None`,`Embed`,`ZipFile]]`|Serializes all build events to a compressed binary file. By default the file is in the current directory and named *msbuild.binlog*. The optional `LogFile` parameter accepts a string of the form `{filename}.binlog`, where `{filename}` contains valid file system characters, but also accepts a placeholder symbol `{}`. If `{}` is provided, MSBuild will fill that position with a 'unique stamp' of the form `yyyyMMdd-HHmmss----<6-character random string>`. The binary log is a detailed description of the build process that can later be used to reconstruct text logs and used by other analysis tools. A binary log is usually 10-20x smaller than the most detailed text diagnostic-level log, but it contains more information.

The binary logger by default collects the source text of project files, including all imported projects and target files encountered during the build. The optional `ProjectImports` parameter controls this behavior:

- **ProjectImports=None**. Don't collect the project imports.
- **ProjectImports=Embed**. Embed project imports in the log file (default).
- **ProjectImports=ZipFile**. Save project files to *{output}.projectimports.zip* where \ is the same name as the binary log file name.

The default setting for ProjectImports is Embed.
**Note**: the logger doesn't collect non-MSBuild source files such as `.cs`, `.cpp`, and so on.
A *.binlog* file can be "played back" by passing it to *msbuild.exe* as an argument instead of a project/solution. Other loggers receive the information contained in the log file as if the original build was happening. You can read more about the binary log and its usages at: https://github.com/dotnet/msbuild/blob/main/documentation/wiki/Binary-Log.md

**Examples**:
- `-bl`
- `-bl:output.binlog`
- `-bl:output.binlog;ProjectImports=None`
- `-bl:output.binlog;ProjectImports=ZipFile`
- `-bl:..\..\custom.binlog`
- `-bl:publish-{}.binlog`
- `-binaryLogger`| +|`-binaryLogger[:[LogFile=]{output.binlog}`
`[;ProjectImports=None`,`Embed`,`ZipFile]]`

`-bl[:[LogFile=]{output.binlog}`
`[;ProjectImports=None`,`Embed`,`ZipFile]]`|Serializes all build events to a compressed binary file. By default the file is in the current directory and named *msbuild.binlog*. The optional `LogFile` parameter accepts a string of the form `{filename}.binlog`, where `{filename}` contains valid file system characters, but also accepts a placeholder symbol `{}`. If `{}` is provided, MSBuild will fill that position with a 'unique stamp' of the form `yyyyMMdd-HHmmss----<6-character random string>`. The binary log is a detailed description of the build process that can later be used to reconstruct text logs and used by other analysis tools. A binary log is usually 10-20x smaller than the most detailed text diagnostic-level log, but it contains more information.

The binary logger by default collects the source text of project files, including all imported projects and target files encountered during the build. The optional `ProjectImports` parameter controls this behavior:

- **ProjectImports=None**. Don't collect the project imports.
- **ProjectImports=Embed**. Embed project imports in the log file (default).
- **ProjectImports=ZipFile**. Save project files to *{output}.projectimports.zip* where \ is the same name as the binary log file name.

The default setting for ProjectImports is Embed.
**Note**: the logger doesn't collect non-MSBuild source files such as `.cs`, `.cpp`, and so on.
A *.binlog* file can be "played back" by passing it to *msbuild.exe* as an argument instead of a project/solution. Other loggers receive the information contained in the log file as if the original build was happening. You can read more about the binary log and its usages at: [MSBuild Binary Log overview](https://github.com/dotnet/msbuild/blob/main/documentation/wiki/Binary-Log.md)

**Examples**:
- `-bl`
- `-bl:output.binlog`
- `-bl:output.binlog;ProjectImports=None`
- `-bl:output.binlog;ProjectImports=ZipFile`
- `-bl:..\..\custom.binlog`
- `-bl:publish-{}.binlog`
- `-binaryLogger`| |`-consoleLoggerParameters:{parameters}`

`-clp:{parameters}`|Pass the parameters that you specify to the console logger, which displays build information in the console window. You can specify the following parameters:

- **PerformanceSummary**. Show the time that's spent in tasks, targets, and projects.
- **Summary**. Show the error and warning summary at the end.
- **NoSummary**. Don't show the error and warning summary at the end.
- **ErrorsOnly**. Show only errors.
- **WarningsOnly**. Show only warnings.
- **NoItemAndPropertyList**. Don't show the list of items and properties that would appear at the start of each project build if the verbosity level is set to `diagnostic`.
- **ShowCommandLine**. Show `TaskCommandLineEvent` messages.
- **ShowProjectFile**. Show the path to the project file in diagnostic messages. This setting is on by default.
- **ShowTimestamp**. Show the timestamp as a prefix to any message.
- **ShowEventId**. Show the event ID for each started event, finished event, and message.
- **ForceNoAlign**. Don't align the text to the size of the console buffer.
- **DisableConsoleColor**. Use the default console colors for all logging messages.
- **DisableMPLogging**. Disable the multiprocessor logging style of output when running in non-multiprocessor mode.
- **EnableMPLogging**. Enable the multiprocessor logging style even when running in non-multiprocessor mode. This logging style is on by default.
- **ForceConsoleColor**. Use ANSI console colors even if console doesn't support it.
- **Verbosity**. Override the `-verbosity` setting for this logger.

Use a semicolon to separate multiple parameters, as the following example shows:

`-consoleLoggerParameters:PerformanceSummary;NoSummary -verbosity:minimal`

The default console logger is at normal verbosity and includes a `Summary`.| |`-distributedFileLogger`

`-dfl`|Log the build output of each MSBuild node to its own file. The initial location for these files is the current directory. By default, the files are named *MSBuild\{NodeId}.log*. You can use the `-fileLoggerParameters` switch to specify the location of the files and other parameters for the fileLogger.

If you name a log file by using the `-fileLoggerParameters` switch, the distributed logger uses that name as a template and append the node ID to that name when creating a log file for each node.| |`-distributedLogger:{central logger},{forwarding logger}, ...`

`-dl:{central logger},{forwarding logger, ...}`|Log events from MSBuild, attaching a different logger instance to each node. To specify multiple loggers, specify each logger separately.

You use the logger syntax to specify a logger, except you provide and additional class for the forwarding logger. For the logger syntax, see the `-logger` switch.

The following examples show how to use this switch:

`-dl:XMLLogger,MyLogger,Version=1.0.2,Culture=neutral`

`-dl:MyLogger,C:\My.dll*ForwardingLogger,C:\Logger.dll`| From 31681509295dc6c5d9b1f208c21da112dbf2b280 Mon Sep 17 00:00:00 2001 From: Gordon Hogenson Date: Wed, 23 Jul 2025 09:08:52 -0700 Subject: [PATCH 3/3] Update docs/msbuild/msbuild-command-line-reference.md --- docs/msbuild/msbuild-command-line-reference.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/msbuild/msbuild-command-line-reference.md b/docs/msbuild/msbuild-command-line-reference.md index 374c0d0070c..2dd9e8a0bb0 100644 --- a/docs/msbuild/msbuild-command-line-reference.md +++ b/docs/msbuild/msbuild-command-line-reference.md @@ -78,7 +78,7 @@ Square brackets `[]` indicate optional parts, and curly braces `{}`indicate user |Switch|Description| |------------|-----------------| -|`-binaryLogger[:[LogFile=]{output.binlog}`
`[;ProjectImports=None`,`Embed`,`ZipFile]]`

`-bl[:[LogFile=]{output.binlog}`
`[;ProjectImports=None`,`Embed`,`ZipFile]]`|Serializes all build events to a compressed binary file. By default the file is in the current directory and named *msbuild.binlog*. The optional `LogFile` parameter accepts a string of the form `{filename}.binlog`, where `{filename}` contains valid file system characters, but also accepts a placeholder symbol `{}`. If `{}` is provided, MSBuild will fill that position with a 'unique stamp' of the form `yyyyMMdd-HHmmss----<6-character random string>`. The binary log is a detailed description of the build process that can later be used to reconstruct text logs and used by other analysis tools. A binary log is usually 10-20x smaller than the most detailed text diagnostic-level log, but it contains more information.

The binary logger by default collects the source text of project files, including all imported projects and target files encountered during the build. The optional `ProjectImports` parameter controls this behavior:

- **ProjectImports=None**. Don't collect the project imports.
- **ProjectImports=Embed**. Embed project imports in the log file (default).
- **ProjectImports=ZipFile**. Save project files to *{output}.projectimports.zip* where \ is the same name as the binary log file name.

The default setting for ProjectImports is Embed.
**Note**: the logger doesn't collect non-MSBuild source files such as `.cs`, `.cpp`, and so on.
A *.binlog* file can be "played back" by passing it to *msbuild.exe* as an argument instead of a project/solution. Other loggers receive the information contained in the log file as if the original build was happening. You can read more about the binary log and its usages at: [MSBuild Binary Log overview](https://github.com/dotnet/msbuild/blob/main/documentation/wiki/Binary-Log.md)

**Examples**:
- `-bl`
- `-bl:output.binlog`
- `-bl:output.binlog;ProjectImports=None`
- `-bl:output.binlog;ProjectImports=ZipFile`
- `-bl:..\..\custom.binlog`
- `-bl:publish-{}.binlog`
- `-binaryLogger`| +|`-binaryLogger[:[LogFile=]{output.binlog}`
`[;ProjectImports=None`,`Embed`,`ZipFile]]`

`-bl[:[LogFile=]{output.binlog}`
`[;ProjectImports=None`,`Embed`,`ZipFile]]`|Serializes all build events to a compressed binary file. By default the file is in the current directory and named *msbuild.binlog*. The optional `LogFile` parameter accepts a string of the form `{filename}.binlog`, where `{filename}` contains valid file system characters, but also accepts a placeholder symbol `{}`. If `{}` is provided, MSBuild will fill that position with a 'unique stamp' of the form `yyyyMMdd-HHmmss----<6-character random string>`. The binary log is a detailed description of the build process that can later be used to reconstruct text logs and used by other analysis tools. A binary log is usually 10-20x smaller than the most detailed text diagnostic-level log, but it contains more information.

The binary logger by default collects the source text of project files, including all imported projects and target files encountered during the build. The optional `ProjectImports` parameter controls this behavior:

- **ProjectImports=None**. Don't collect the project imports.
- **ProjectImports=Embed**. Embed project imports in the log file (default).
- **ProjectImports=ZipFile**. Save project files to *{output}.projectimports.zip* where \ is the same name as the binary log file name.

The default setting for ProjectImports is Embed.
**Note**: the logger doesn't collect non-MSBuild source files such as `.cs`, `.cpp`, and so on.
A *.binlog* file can be "played back" by passing it to *msbuild.exe* as an argument instead of a project/solution. Other loggers receive the information contained in the log file as if the original build was happening. You can read more about the binary log and its usages at [MSBuild Binary Log overview](https://github.com/dotnet/msbuild/blob/main/documentation/wiki/Binary-Log.md).

**Examples**:
- `-bl`
- `-bl:output.binlog`
- `-bl:output.binlog;ProjectImports=None`
- `-bl:output.binlog;ProjectImports=ZipFile`
- `-bl:..\..\custom.binlog`
- `-bl:publish-{}.binlog`
- `-binaryLogger`| |`-consoleLoggerParameters:{parameters}`

`-clp:{parameters}`|Pass the parameters that you specify to the console logger, which displays build information in the console window. You can specify the following parameters:

- **PerformanceSummary**. Show the time that's spent in tasks, targets, and projects.
- **Summary**. Show the error and warning summary at the end.
- **NoSummary**. Don't show the error and warning summary at the end.
- **ErrorsOnly**. Show only errors.
- **WarningsOnly**. Show only warnings.
- **NoItemAndPropertyList**. Don't show the list of items and properties that would appear at the start of each project build if the verbosity level is set to `diagnostic`.
- **ShowCommandLine**. Show `TaskCommandLineEvent` messages.
- **ShowProjectFile**. Show the path to the project file in diagnostic messages. This setting is on by default.
- **ShowTimestamp**. Show the timestamp as a prefix to any message.
- **ShowEventId**. Show the event ID for each started event, finished event, and message.
- **ForceNoAlign**. Don't align the text to the size of the console buffer.
- **DisableConsoleColor**. Use the default console colors for all logging messages.
- **DisableMPLogging**. Disable the multiprocessor logging style of output when running in non-multiprocessor mode.
- **EnableMPLogging**. Enable the multiprocessor logging style even when running in non-multiprocessor mode. This logging style is on by default.
- **ForceConsoleColor**. Use ANSI console colors even if console doesn't support it.
- **Verbosity**. Override the `-verbosity` setting for this logger.

Use a semicolon to separate multiple parameters, as the following example shows:

`-consoleLoggerParameters:PerformanceSummary;NoSummary -verbosity:minimal`

The default console logger is at normal verbosity and includes a `Summary`.| |`-distributedFileLogger`

`-dfl`|Log the build output of each MSBuild node to its own file. The initial location for these files is the current directory. By default, the files are named *MSBuild\{NodeId}.log*. You can use the `-fileLoggerParameters` switch to specify the location of the files and other parameters for the fileLogger.

If you name a log file by using the `-fileLoggerParameters` switch, the distributed logger uses that name as a template and append the node ID to that name when creating a log file for each node.| |`-distributedLogger:{central logger},{forwarding logger}, ...`

`-dl:{central logger},{forwarding logger, ...}`|Log events from MSBuild, attaching a different logger instance to each node. To specify multiple loggers, specify each logger separately.

You use the logger syntax to specify a logger, except you provide and additional class for the forwarding logger. For the logger syntax, see the `-logger` switch.

The following examples show how to use this switch:

`-dl:XMLLogger,MyLogger,Version=1.0.2,Culture=neutral`

`-dl:MyLogger,C:\My.dll*ForwardingLogger,C:\Logger.dll`|