Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/core/compatibility/9.0.md
Original file line number Diff line number Diff line change
Expand Up @@ -108,7 +108,7 @@ If you're migrating an app to .NET 9, the breaking changes listed here might aff
| [`installer` repo version no longer documented](sdk/9.0/productcommits-versions.md) | Behavioral change | Preview 5 |
| [MSBuild custom culture resource handling](sdk/10.0/msbuild-custom-culture.md) | Behavioral change | 9.0.200/9.0.300 |
| [New default RID used when targeting .NET Framework](sdk/9.0/default-rid.md) | Source incompatible | GA |
| [Terminal logger is default](sdk/9.0/terminal-logger.md) | Behavioral change | Preview 1 |
| [Terminal Logger is default](sdk/9.0/terminal-logger.md) | Behavioral change | Preview 1 |
| [Version requirements for .NET 9 SDK](sdk/9.0/version-requirements.md) | Source incompatible | GA |
| [Warning emitted for .NET Standard 1.x target](sdk/9.0/netstandard-warning.md) | Source incompatible | Preview 6 |
| [Warning emitted for .NET 7 target](sdk/9.0/net70-warning.md) | Source incompatible | GA |
Expand Down
20 changes: 10 additions & 10 deletions docs/core/compatibility/sdk/9.0/terminal-logger.md
Original file line number Diff line number Diff line change
@@ -1,19 +1,19 @@
---
title: "Breaking change: Terminal logger is default"
description: Learn about a breaking change in the .NET 9 SDK where the terminal logger is used by default for interactive MSBuild invocations.
title: "Breaking change: Terminal Logger is default"
description: Learn about a breaking change in the .NET 9 SDK where Terminal Logger is used by default for interactive MSBuild invocations.
ms.date: 01/10/2024
---
# Terminal logger is default
# Terminal Logger is default

The terminal logger is now enabled by default for all "interactive" terminal sessions. The terminal logger formats the console output for builds differently to the console logger. For more information about the terminal logger, see ['dotnet build' options](../../../tools/dotnet-build.md#options), specifically the `--tl` option.
Terminal Logger is now enabled by default for all "interactive" terminal sessions. Terminal Logger formats the console output for builds differently to the console logger. For more information about Terminal Logger, see ['dotnet build' options](../../../tools/dotnet-build.md#options), specifically the `--tl` option.

## Previous behavior

`dotnet build` and other build-related CLI commands used the 'minimal' verbosity MSBuild console logger by default for user-driven builds.

## New behavior

If the terminal supports various layout and colorization features, `dotnet build` and other build-related CLI commands use the terminal logger by default for user-triggered builds. If the command is part of a shell script or has had input or output redirected in any way, or if the terminal doesn't support some of the enhanced layout features that terminal logger has, then the terminal logger isn't used.
If the terminal supports various layout and colorization features, `dotnet build` and other build-related CLI commands use Terminal Logger by default for user-triggered builds. If the command is part of a shell script or has had input or output redirected in any way, or if the terminal doesn't support some of the enhanced layout features that Terminal Logger has, then Terminal Logger isn't used.

## Version introduced

Expand All @@ -25,14 +25,14 @@ This change is a [behavioral change](../../categories.md#behavioral-change).

## Reason for change

The terminal logger output about the progress of a build is more information dense and actionable than the console logger output. The MSBuild team wants to encourage the use of terminal logger early in the .NET 9 release cycle so that there's time to gather feedback about the quality and functionality of the feature.
Terminal Logger output about the progress of a build is more information dense and actionable than the console logger output. The MSBuild team wants to encourage the use of Terminal Logger early in the .NET 9 release cycle so that there's time to gather feedback about the quality and functionality of the feature.

## Recommended action

If you need to revert to the console logger, you can disable the terminal logger can be disabled in the following ways:
If you need to revert to the console logger, you can disable Terminal Logger in the following ways:

- To disable terminal logger for a specific command, specify `--tl:off` on the command line or via an MSBuild response file.
- To disable terminal logger for all commands, set the `MSBUILDTERMINALLOGGER` environment variable to `off`.
- To disable Terminal Logger for a specific command, specify `--tl:off` on the command line or via an MSBuild response file.
- To disable Terminal Logger for all commands, set the `MSBUILDTERMINALLOGGER` environment variable to `off`.

## Affected APIs

Expand All @@ -41,4 +41,4 @@ N/A
## See also

- ['dotnet build' options](../../../tools/dotnet-build.md#options)
- [Terminal logger](../../../whats-new/dotnet-9/sdk.md#terminal-logger)
- [Terminal Logger](../../../whats-new/dotnet-9/sdk.md#terminal-logger)
2 changes: 1 addition & 1 deletion docs/core/whats-new/dotnet-8/sdk.md
Original file line number Diff line number Diff line change
Expand Up @@ -66,7 +66,7 @@ bin\Release\net8.0\

### Terminal build output

`dotnet build` has a new option to produce more modernized build output. This *terminal logger* output groups errors with the project they came from, better differentiates the different target frameworks for multi-targeted projects, and provides real-time information about what the build is doing. To opt in to the new output, use the `--tl` option. For more information about this option, see [dotnet build options](../../tools/dotnet-build.md#options).
`dotnet build` has a new option to produce more modernized build output. This *Terminal Logger* output groups errors with the project they came from, better differentiates the different target frameworks for multi-targeted projects, and provides real-time information about what the build is doing. To opt in to the new output, use the `--tl` option. For more information about this option, see [dotnet build options](../../tools/dotnet-build.md#options).

### Simplified output paths

Expand Down
2 changes: 1 addition & 1 deletion docs/core/whats-new/dotnet-9/overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,7 @@ For more information, see [What's new in the .NET 9 libraries](libraries.md).
The .NET 9 SDK introduces _workload sets_, where all of your workloads stay at a single, specific version until explicitly updated. For tools, a new option for [`dotnet tool install`](../../tools/dotnet-tool-install.md) lets users (instead of tool authors) decide whether a tool is allowed to run on a newer .NET runtime version than the version the tool targets. In addition:

- Unit testing has better MSBuild integration that allows you to run tests in parallel.
- The terminal logger is enabled by default and also has improved usability. For example, the total count of failures and warnings is now summarized at the end of a build.
- Terminal Logger is enabled by default and also has improved usability. For example, the total count of failures and warnings is now summarized at the end of a build.
- New MSBuild script analyzers ("build checks") are available.
- The SDK can detect and adjust for version mismatches between the .NET SDK and MSBuild.
- The `dotnet workload history` command shows you the history of workload installations and modifications for the current .NET SDK installation.
Expand Down
24 changes: 12 additions & 12 deletions docs/core/whats-new/dotnet-9/sdk.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: What's new in the SDK and tooling for .NET 9
description: Learn about the new .NET SDK features introduced in .NET 9, including for unit testing, terminal logger, tool roll-forward, and build script analyzers.
description: Learn about the new .NET SDK features introduced in .NET 9, including for unit testing, Terminal Logger, tool roll-forward, and build script analyzers.
titleSuffix: ""
ms.date: 11/11/2024
ms.topic: whats-new
Expand All @@ -12,41 +12,41 @@ This article describes new features in the .NET SDK and tooling for .NET 9.

## Unit testing

This section describes the updates to unit testing in .NET 9: running tests in parallel, and terminal logger test output.
This section describes the updates to unit testing in .NET 9: running tests in parallel, and Terminal Logger test output.

### Run tests in parallel

In .NET 9, `dotnet test` is more fully integrated with MSBuild. Because MSBuild supports [building in parallel](/visualstudio/msbuild/building-multiple-projects-in-parallel-with-msbuild), you can run tests for the same project across different target frameworks in parallel. By default, MSBuild limits the number of parallel processes to the number of processors on the computer. You can also set your own limit using the [-maxcpucount](/visualstudio/msbuild/building-multiple-projects-in-parallel-with-msbuild#-maxcpucount-switch) switch. If you want to opt out of the parallelism, set the `TestTfmsInParallel` MSBuild property to `false`.

### Terminal logger test display
### Terminal Logger test display

Test result reporting for [`dotnet test`](../../tools/dotnet-test.md) is now supported directly in the MSBuild terminal logger. You get more fully featured test reporting both _while_ tests are running (displays the running test name) and _after_ tests are completed (any test errors are rendered in a better way).
Test result reporting for [`dotnet test`](../../tools/dotnet-test.md) is now supported directly in MSBuild Terminal Logger. You get more fully featured test reporting both _while_ tests are running (displays the running test name) and _after_ tests are completed (any test errors are rendered in a better way).

For more information about the terminal logger, see [dotnet build options](../../tools/dotnet-build.md#options).
For more information about Terminal Logger, see [dotnet build options](../../tools/dotnet-build.md#options).

## .NET tool roll-forward

[.NET tools](../../tools/global-tools.md) are framework-dependent apps that you can install globally or locally, then run using the .NET SDK and installed .NET runtimes. These tools, like all .NET apps, target a specific major version of .NET. By default, apps don't run on _newer_ versions of .NET. Tool authors have been able to opt in to running their tools on newer versions of the .NET runtime by setting the `RollForward` MSBuild property. However, not all tools do so.

A new option for [`dotnet tool install`](../../tools/dotnet-tool-install.md) lets _users_ decide how .NET tools should be run. When you install a tool via `dotnet tool install`, or when you run tool via [`dotnet tool run <toolname>`](../../tools/dotnet-tool-run.md), you can specify a new flag called `--allow-roll-forward`. This option configures the tool with roll-forward mode `Major`. This mode allows the tool to run on a newer major version of .NET if the matching .NET version is not available. This feature helps early adopters use .NET tools without tool authors having to change any code.

## Terminal logger
## Terminal Logger

The terminal logger is now [enabled by default](#enabled-by-default) and also has [improved usability](#usability).
Terminal Logger is now [enabled by default](#enabled-by-default) and also has [improved usability](#usability).

### Enabled by default

Starting in .NET 9, the default experience for all .NET CLI commands that use MSBuild is terminal logger, the enhanced logging experience that was released in .NET 8. This new output uses the capabilities of modern terminals to provide functionality like:
Starting in .NET 9, the default experience for all .NET CLI commands that use MSBuild is Terminal Logger, the enhanced logging experience that was released in .NET 8. This new output uses the capabilities of modern terminals to provide functionality like:

- Clickable links
- Duration timers for MSBuild tasks
- Color coding of warning and error messages

The output is more condensed and usable than the existing MSBuild console logger.

The new logger attempts to auto-detect if it can be used, but you can also manually control whether terminal logger is used. Specify the `--tl:off` command-line option to disable terminal logger for a specific command. Or, to disable terminal logger more broadly, set the `MSBUILDTERMINALLOGGER` environment variable to `off`.
The new logger attempts to auto-detect if it can be used, but you can also manually control whether Terminal Logger is used. Specify the `--tl:off` command-line option to disable Terminal Logger for a specific command. Or, to disable Terminal Logger more broadly, set the `MSBUILDTERMINALLOGGER` environment variable to `off`.

The set of commands that uses terminal logger by default is:
The set of commands that uses Terminal Logger by default is:

- `build`
- `clean`
Expand All @@ -58,7 +58,7 @@ The set of commands that uses terminal logger by default is:

### Usability

The terminal logger now summarizes the total count of failures and warnings at the end of a build. It also shows errors that contain newlines. (For more information about the terminal logger, see ['dotnet build' options](../../tools/dotnet-build.md#options), specifically the `--tl` option.)
Terminal Logger now summarizes the total count of failures and warnings at the end of a build. It also shows errors that contain newlines. (For more information about Terminal Logger, see ['dotnet build' options](../../tools/dotnet-build.md#options), specifically the `--tl` option.)

Consider the following project file that emits a warning when the project is built:

Expand Down Expand Up @@ -109,7 +109,7 @@ Build succeeded with 3 warning(s) in 0.8s

The message lines of the warning no longer have the repeated project and location information that clutter the display. In addition, the build summary shows how many warnings (and errors, if there are any) were generated during the build.

If you have feedback about the terminal logger, you can provide it in the [MSBuild repository](https://github.com/dotnet/msbuild/issues).
If you have feedback about Terminal Logger, you can provide it in the [MSBuild repository](https://github.com/dotnet/msbuild/issues).

## Faster NuGet dependency resolution for large repos

Expand Down
4 changes: 2 additions & 2 deletions includes/cli-tl.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +4,9 @@ ms.topic: include
---
- **`--tl:[auto|on|off]`**

Specifies whether the *terminal logger* should be used for the build output. The default is `auto`, which first verifies the environment before enabling terminal logging. The environment check verifies that the terminal is capable of using modern output features and isn't using a redirected standard output before enabling the new logger. `on` skips the environment check and enables terminal logging. `off` skips the environment check and uses the default console logger.
Specifies whether *Terminal Logger* should be used for the build output. The default is `auto`, which first verifies the environment before enabling terminal logging. The environment check verifies that the terminal is capable of using modern output features and isn't using a redirected standard output before enabling the new logger. `on` skips the environment check and enables terminal logging. `off` skips the environment check and uses the default console logger.

The terminal logger shows you the restore phase followed by the build phase. During each phase, the currently building projects appear at the bottom of the terminal. Each project that's building outputs both the MSBuild target currently being built and the amount of time spent on that target. You can search this information to learn more about the build. When a project is finished building, a single "build completed" section is written that captures:
Terminal Logger shows you the restore phase followed by the build phase. During each phase, the currently building projects appear at the bottom of the terminal. Each project that's building outputs both the MSBuild target currently being built and the amount of time spent on that target. You can search this information to learn more about the build. When a project is finished building, a single "build completed" section is written that captures:

- The name of the built project.
- The target framework (if multi-targeted).
Expand Down