Add structured task logging APIs - #14606
Draft
baronfel wants to merge 4 commits into
Draft
Conversation
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 8c28147a-fe7a-4b4b-91f5-c436d1930d38
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 8c28147a-fe7a-4b4b-91f5-c436d1930d38
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 8c28147a-fe7a-4b4b-91f5-c436d1930d38
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 8c28147a-fe7a-4b4b-91f5-c436d1930d38
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Context
TaskLoggingHelpersupports lazy positional composite formats. However, C# interpolation evaluates and formats values before MSBuild can filter a message.Interpolation also removes the source names that loggers can use for queries and groups.
This change follows the Microsoft.Extensions.Logging
OriginalFormatmodel. It does not add a MEL package dependency or anEventId.After recompilation, existing interpolated calls select the new handler overloads.
Public API
LogMessage,LogWarning, andLogErroradd interpolated string handler overloads.LogStructuredMessage,LogStructuredWarning, andLogStructuredErrorsupport dynamic and non-C# callers.TaskLoggingHelper.Namedsupplies a stable explicit hole name.IStructuredBuildEventArgsexposes an invariant named template and ordered values with unique names.Names and display text
Each event stores the named template as its display format.
The task formats each value one time with its current culture.
This operation makes the displayed message identical before and after transport.
The
Messageproperty creates the display text only when a consumer reads the property.Reading
Messagedoes not remove the named template or its values.Localized callers can supply an invariant template and an already-localized message.
The event stores an original-format override for this case.
The compiler supplies default names through
CallerArgumentExpression.The handler keeps identifiers and dotted paths.
It uses
ValueNfor other expressions.It adds
_2,_3, and subsequent suffixes to duplicate names.Transport
The implementation uses dedicated structured message, warning, and error event types.
It does not add structured state to the existing extended event types.
Node packets serialize the original-format override and ordered name-value pairs directly.
Binary-log format version 28 adds three length-prefixed record kinds.
Each record stores names and values as separate string-table references.
This format preserves order and distinguishes a null value from an empty value.
It does not use JSON, dictionaries, synthetic keys, type tags, or copied value strings.
Central warning policy preserves structured state when it converts a warning to a message or an error.
This behavior covers
NoWarn,MSBuildWarningsAsMessages, and warning-as-error settings.Compatibility
Forward-compatible readers older than version 28 skip the new records.
These readers cannot display the skipped events.
Change Wave 18.11 controls the dedicated event types.
Set
MSBUILDDISABLEFEATURESFROMVERSION=18.11when a consumer requires an older reader.This setting restores ordinary message, warning, and error event types.
Measurements
The measurements use BenchmarkDotNet ShortRun on .NET 11 arm64 with
MemoryDiagnoser.MessageaccessThe original PR implementation allocated 2,160 B for a two-hole capture.
The dedicated implementation allocates 344 B.
The binary-log test writes 500 equivalent repeated events.
The dedicated record is 2.7% larger than existing lazy composite logging.
The extended-metadata design was 22.3% larger.
Structured logging improves queries and filtered-message allocation.
It is not a general binary-log size optimization.
It can reduce size when it replaces a fully formatted message or supports event aggregation.
An inventory found 807 built-in task logging call sites.
Only interpolated or preformatted call sites can benefit from automatic capture or source migration.
The 823.6 MiB reference binary log contains many lazy composite and resource messages.
The size estimate does not apply the microbenchmark ratio to the complete file.
Validation
TaskLoggingHelperTestspass.MSBuild --helpcompletes successfully.git diff --checkreports no errors.