Skip to content

Commit 75b5caa

Browse files
dotnet-policy-service[bot]dotnet-policy-service[bot]
authored
Merge pull request #49396 from dotnet/main
Merge main into live
2 parents e7ffd04 + 9e06dd5 commit 75b5caa

16 files changed

+421
-52
lines changed

‎docs/core/enrichment/custom-enricher.md‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
---
2+
title: Custom log enricher
3+
description: Learn how to use the custom log enricher in .NET.
4+
ms.date: 10/13/2025
5+
---
6+
7+
# Custom log enricher
8+
9+
You can easily create a custom enricher by creating a class that implements the <xref:Microsoft.Extensions.Diagnostics.Enrichment.ILogEnricher> interface.
10+
After the class is created, you register it with <xref:Microsoft.Extensions.DependencyInjection.EnrichmentServiceCollectionExtensions.AddLogEnricher(Microsoft.Extensions.DependencyInjection.IServiceCollection,Microsoft.Extensions.Diagnostics.Enrichment.ILogEnricher)>.
11+
Once registered, the logging infrastructure automatically calls the `Enrich()` method exactly once on every registered enricher for each log message produced.
12+
13+
## Install the package
14+
15+
To get started, install the [📦 Microsoft.Extensions.Telemetry.Abstractions](https://www.nuget.org/packages/Microsoft.Extensions.Telemetry.Abstractions) NuGet package:
16+
17+
### [.NET CLI](#tab/dotnet-cli)
18+
19+
```dotnetcli
20+
dotnet add package Microsoft.Extensions.Telemetry.Abstractions
21+
```
22+
23+
Or, if you're using .NET 10+ SDK:
24+
25+
```dotnetcli
26+
dotnet package add Microsoft.Extensions.Telemetry.Abstractions
27+
```
28+
29+
### [PackageReference](#tab/package-reference)
30+
31+
```xml
32+
<PackageReference Include="Microsoft.Extensions.Telemetry.Abstractions"
33+
Version="*" /> <!-- Adjust version -->
34+
```
35+
36+
---
37+
38+
## Implementation
39+
40+
Your custom enricher only needs to implement a single <xref:Microsoft.Extensions.Diagnostics.Enrichment.ILogEnricher.Enrich(Microsoft.Extensions.Diagnostics.Enrichment.IEnrichmentTagCollector)> method.
41+
During enrichment, this method is called and given an <xref:Microsoft.Extensions.Diagnostics.Enrichment.IEnrichmentTagCollector> instance. The enricher then calls one of the overloads of
42+
the <xref:Microsoft.Extensions.Diagnostics.Enrichment.IEnrichmentTagCollector.Add(System.String,System.Object)> method to record any properties it wants.
43+
44+
> [!NOTE]
45+
> If your custom log enricher calls <xref:Microsoft.Extensions.Diagnostics.Enrichment.IEnrichmentTagCollector.Add(System.String,System.Object)>,
46+
> it is acceptable to send any type of argument to the `value` parameter as is, because it is parsed into the actual type and serialized internally
47+
> to be sent further down the logging pipeline.
48+
49+
```csharp
50+
public class CustomEnricher : ILogEnricher
51+
{
52+
public void Enrich(IEnrichmentTagCollector collector)
53+
{
54+
collector.Add("customKey", "customValue");
55+
}
56+
}
57+
58+
```
59+
60+
And you register it as shown in the following code using <xref:Microsoft.Extensions.DependencyInjection.EnrichmentServiceCollectionExtensions.AddLogEnricher``1(Microsoft.Extensions.DependencyInjection.IServiceCollection)>:
61+
62+
```csharp
63+
var builder = Host.CreateApplicationBuilder(args);
64+
builder.Logging.EnableEnrichment();
65+
builder.Services.AddLogEnricher<CustomEnricher>();
66+
```
67+
68+
It's also possible to configure manual instantiation of custom enrichers:
69+
70+
```csharp
71+
public class AnotherEnricher : ILogEnricher
72+
{
73+
private readonly string _key;
74+
private readonly object _value;
75+
public CustomEnricher(string key, object value)
76+
{
77+
_key = key;
78+
_value = value;
79+
}
80+
public void Enrich(IEnrichmentTagCollector collector)
81+
{
82+
collector.Add(_key, _value);
83+
}
84+
}
85+
```
86+
87+
And you register it as shown in the following code <xref:Microsoft.Extensions.DependencyInjection.EnrichmentServiceCollectionExtensions.AddLogEnricher(Microsoft.Extensions.DependencyInjection.IServiceCollection,Microsoft.Extensions.Diagnostics.Enrichment.ILogEnricher)>:
88+
89+
```csharp
90+
var builder = Host.CreateApplicationBuilder();
91+
builder.Logging.EnableEnrichment();
92+
builder.Services.AddLogEnricher(new AnotherEnricher("anotherKey", "anotherValue"));
93+
```

‎docs/core/enrichment/json-output-all-enabled.json‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
{
2+
"EventId": 0,
3+
"LogLevel": "Information",
4+
"Category": "Enrichment.Program",
5+
"Message": "This is a sample log message",
6+
"State": {
7+
"Message": "This is a sample log message",
8+
"process.pid": "12924",
9+
"thread.id": "2",
10+
"{OriginalFormat}": "This is a sample log message"
11+
}
12+
}

‎docs/core/enrichment/json-output.json‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
{
2+
"EventId": 0,
3+
"LogLevel": "Information",
4+
"Category": "Enrichment.Program",
5+
"Message": "This is a sample log message",
6+
"State": {
7+
"Message": "This is a sample log message",
8+
"process.pid": "10696",
9+
"{OriginalFormat}": "This is a sample log message"
10+
}
11+
}

‎docs/core/enrichment/overview.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
---
2+
title: Log enrichment overview
3+
description: Learn about log enrichment in .NET and how to enhance your logs with contextual information.
4+
ms.date: 10/13/2025
5+
---
6+
7+
# Overview
8+
9+
Log enrichment is a powerful feature that automatically attaches contextual information to your application's logs. Instead of manually adding metadata to each log, enrichment provides a systematic way to inject relevant context automatically across your entire application.
10+
11+
## What is enrichment?
12+
13+
Enrichment augments telemetry objects with additional information that provides valuable context about the environment, application state, and execution context when the telemetry was generated. This contextual data helps with debugging, monitoring, performance analysis, and understanding application behavior in production environments.
14+
15+
## Why is enrichment important?
16+
17+
Enrichment plays a critical role in enhancing observability and diagnostics by adding standardized contextual information—such as process details, environment tags, or user identifiers—to telemetry data. This additional metadata transforms raw logs into structured, meaningful insights, making it easier to trace issues, correlate events, and improve application reliability. By enabling enrichment and configuring specific enrichers, teams can streamline troubleshooting, optimize performance monitoring, and ensure compliance with operational standards. Ultimately, enrichment is not just a technical add-on; it’s a foundational practice for building resilient, transparent systems that support informed decision-making and faster incident resolution.
18+
19+
## How enrichment works
20+
21+
The enrichment framework operates through a collection of enrichers that are registered with the dependency injection container. When telemetry is generated, all registered enrichers automatically contribute their contextual information to the telemetry payload. You just register the specific set of enrichers you want into an <xref:Microsoft.Extensions.DependencyInjection.IServiceCollection> instance. The enrichers run automatically without requiring changes to your application code. You simply configure which enrichers you want to use during application startup.
22+
23+
## Dimension names and tags
24+
25+
Enrichers add information to telemetry using standardized dimension names (also called tags or keys).
26+
27+
## Setting up enrichment
28+
29+
To use log enrichment in your application, you need to:
30+
31+
1. **Enable enrichment** for logging.
32+
2. **Register specific enrichers** you want to use.
33+
3. **Configure options** for each enricher (optional).
34+
35+
### Basic setup example
36+
37+
Here's a simple example showing how to set up log enrichment with process information:
38+
39+
:::code language="csharp" source="snippets/enrichment/Program.cs" highlight="8,9":::
40+
41+
This configuration:
42+
43+
- Enables enrichment for logging via `EnableEnrichment()`.
44+
- Registers the process log enricher via `AddProcessLogEnricher()`.
45+
- Configures JSON console output to display the enriched data.
46+
47+
### Output example
48+
49+
With enrichment enabled, your log output will automatically include additional contextual information:
50+
51+
:::code language="json" source="json-output.json" highlight="8":::
52+
53+
## Available enrichers
54+
55+
The .NET enrichment framework provides some built-in enrichers, like:
56+
57+
- **[Process enricher](process-log-enricher.md)**: Process and thread information
58+
59+
## Custom enrichers
60+
61+
If the built-in enrichers don't meet your specific needs, you can create custom enrichers to add application-specific context. For more information, check [custom enrichment](custom-enricher.md).

‎docs/core/enrichment/process-log-enricher.md‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
---
2+
title: Process log enricher
3+
description: Learn how to use the process log enricher in .NET.
4+
ms.date: 10/10/2025
5+
---
6+
7+
# Process log enricher
8+
9+
The process enricher augments telemetry logs with process-specific information.
10+
11+
You can register the enrichers in an IoC container. Then, all registered enrichers are picked up automatically by the respective telemetry instances, such as logs or metrics, where they enrich the telemetry information.
12+
13+
## Install the package
14+
15+
To get started, install the [📦 Microsoft.Extensions.Telemetry](https://www.nuget.org/packages/Microsoft.Extensions.Telemetry) NuGet package:
16+
17+
### [.NET CLI](#tab/dotnet-cli)
18+
19+
```dotnetcli
20+
dotnet add package Microsoft.Extensions.Telemetry
21+
```
22+
23+
Or, if you're using .NET 10+ SDK:
24+
25+
```dotnetcli
26+
dotnet package add Microsoft.Extensions.Telemetry
27+
```
28+
29+
### [PackageReference](#tab/package-reference)
30+
31+
```xml
32+
<PackageReference Include="Microsoft.Extensions.Telemetry"
33+
Version="*" /> <!-- Adjust version -->
34+
```
35+
36+
---
37+
38+
## Usage
39+
40+
To use the process log enricher, first you enable enrichment. Then you can add the <xref:Microsoft.Extensions.DependencyInjection.ProcessEnricherServiceCollectionExtensions.AddProcessLogEnricher*> with default properties, as shown in the following code:
41+
42+
:::code language="csharp" source="snippets/enrichment/Program.cs" highlight="8,9":::
43+
44+
Given this code sample, the output should be similar to the following JSON:
45+
46+
:::code language="json" source="json-output.json" highlight="8":::
47+
48+
## `ProcessLogEnricherOptions`
49+
50+
The <xref:Microsoft.Extensions.Diagnostics.Enrichment.ProcessLogEnricherOptions> class provides fine-grained control over which process-related properties are included in your log enrichment. This options class allows you to selectively enable or disable specific enrichment features such as process ID and thread ID information. Although default properties are supplied by the process enricher, you can customize them by initializing an instance of <xref:Microsoft.Extensions.Diagnostics.Enrichment.ProcessLogEnricherOptions> and providing it when registering the enricher.
51+
52+
You can enable or disable individual options of the enricher using <xref:Microsoft.Extensions.DependencyInjection.ProcessEnricherServiceCollectionExtensions.AddProcessLogEnricher(Microsoft.Extensions.DependencyInjection.IServiceCollection,System.Action{Microsoft.Extensions.Diagnostics.Enrichment.ProcessLogEnricherOptions})>:
53+
54+
```csharp
55+
serviceCollection.AddProcessLogEnricher(options =>
56+
{
57+
options.ThreadId = true;
58+
options.ProcessId = true;
59+
});
60+
```
61+
62+
You may also disable or enable individual options using _appsettings.json_ file configuration, for example:
63+
64+
```json
65+
{
66+
"ProcessLogEnricherOptions": {
67+
"ThreadId": true,
68+
"ProcessId": true
69+
}
70+
}
71+
```
72+
73+
and apply it accordingly using <xref:Microsoft.Extensions.DependencyInjection.ProcessEnricherServiceCollectionExtensions.AddProcessLogEnricher(Microsoft.Extensions.DependencyInjection.IServiceCollection,Microsoft.Extensions.Configuration.IConfigurationSection)>:
74+
75+
```csharp
76+
serviceCollection.AddProcessLogEnricher(
77+
hostBuilder.Configuration.GetSection("ProcessLogEnricherOptions"));
78+
```
79+
80+
The console output after enabling both options should look like this:
81+
82+
:::code language="json" source="json-output-all-enabled.json" highlight="8,9":::
83+
84+
## Default configuration
85+
86+
The default configuration for process log enrichment is:
87+
88+
| Property | Default Value | Description |
89+
|-------------|---------------|---------------------------------------------------------|
90+
| `ProcessId` | `true` | If true, logs are enriched with the current process ID. |
91+
| `ThreadId` | `false` | If true, logs are enriched with the current thread ID |

‎docs/core/enrichment/snippets/enrichment/Enrichment.csproj‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
<Project Sdk="Microsoft.NET.Sdk">
2+
3+
<PropertyGroup>
4+
<OutputType>Exe</OutputType>
5+
<TargetFramework>net9.0</TargetFramework>
6+
<ImplicitUsings>enable</ImplicitUsings>
7+
<Nullable>enable</Nullable>
8+
</PropertyGroup>
9+
10+
<ItemGroup>
11+
<PackageReference Include="Microsoft.Extensions.Hosting" Version="9.0.9" />
12+
<PackageReference Include="Microsoft.Extensions.Logging" Version="9.0.9" />
13+
<PackageReference Include="Microsoft.Extensions.Logging.Console" Version="9.0.9" />
14+
<PackageReference Include="Microsoft.Extensions.Telemetry" Version="9.9.0" />
15+
</ItemGroup>
16+
17+
</Project>

‎docs/core/enrichment/snippets/enrichment/Program.cs‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
using System.Text.Json;
2+
using Microsoft.Extensions.DependencyInjection;
3+
using Microsoft.Extensions.Hosting;
4+
using Microsoft.Extensions.Logging;
5+
6+
var builder = Host.CreateApplicationBuilder(args);
7+
8+
builder.Logging.EnableEnrichment();
9+
builder.Services.AddProcessLogEnricher();
10+
11+
builder.Logging.AddJsonConsole(op =>
12+
{
13+
op.JsonWriterOptions = new JsonWriterOptions
14+
{
15+
Indented = true
16+
};
17+
});
18+
19+
var host = builder.Build();
20+
var logger = host.Services.GetRequiredService<ILogger<Program>>();
21+
22+
logger.LogInformation("This is a sample log message");
23+
await host.RunAsync();

‎docs/core/testing/microsoft-testing-platform-extensions-diagnostics.md‎

Lines changed: 0 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -38,9 +38,6 @@ You can also enable the diagnostics logs using the environment variables:
3838

3939
This extension allows you to create a crash dump file if the process crashes. This extension is shipped as part of [Microsoft.Testing.Extensions.CrashDump](https://nuget.org/packages/Microsoft.Testing.Extensions.CrashDump) NuGet package.
4040

41-
> [!IMPORTANT]
42-
> The package is shipped with Microsoft .NET library closed-source free to use licensing model.
43-
4441
To configure the crash dump file generation, use the following options:
4542

4643
| Option | Description |
@@ -56,9 +53,6 @@ To configure the crash dump file generation, use the following options:
5653

5754
This extension allows you to create a dump file after a given timeout. This extension is shipped as part of [Microsoft.Testing.Extensions.HangDump](https://nuget.org/packages/Microsoft.Testing.Extensions.HangDump) package.
5855

59-
> [!IMPORTANT]
60-
> The package is shipped with Microsoft .NET library closed-source free to use licensing model.
61-
6256
To configure the hang dump file generation, use the following options:
6357

6458
| Option | Description |

‎docs/csharp/language-reference/compiler-messages/array-declaration-errors.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,11 @@ f1_keywords:
3737
- "CS9208"
3838
- "CS9209"
3939
- "CS9210"
40+
- "CS9212"
41+
- "CS9213"
42+
- "CS9214"
43+
- "CS9215"
44+
- "CS9222"
4045
helpviewer_keywords:
4146
- "CS0022"
4247
- "CS0178"
@@ -73,6 +78,11 @@ helpviewer_keywords:
7378
- "CS9208"
7479
- "CS9209"
7580
- "CS9210"
81+
- "CS9212"
82+
- "CS9213"
83+
- "CS9214"
84+
- "CS9215"
85+
- "CS9222"
7686
ms.date: 11/02/2023
7787
---
7888
# Resolve errors and warnings in array and collection declarations and initialization expressions
@@ -110,6 +120,11 @@ That's by design. The text closely matches the text of the compiler error / warn
110120
- [**CS9188**](#invalid-collection-builder): *Type has a CollectionBuilderAttribute but no element type.*
111121
- [**CS9203**](#invalid-collection-initializer): *A collection expression of this type cannot be used in this context because it may be exposed outside of the current scope.*
112122
- [**CS9210**](#invalid-collection-initializer): *This version of <xref:System.Collections.Immutable.ImmutableArray%601?displayProperty=nameWithType>cannot be used with collection expressions.*
123+
- [**CS9212**](#invalid-collection-initializer): *Spread operator '`..`' cannot operate on variables of type 'type' because 'type' does not contain a public instance or extension definition for 'member'.*
124+
- [**CS9213**](#invalid-collection-initializer): *Collection expression target 'type' has no element type.*
125+
- [**CS9214**](#invalid-collection-initializer): *Collection expression type must have an applicable constructor that can be called with no arguments.*
126+
- [**CS9215**](#invalid-collection-initializer): *Collection expression type 'type' must have an instance or extension method 'Add' that can be called with a single argument.*
127+
- [**CS9222**](#invalid-collection-initializer): *Collection initializer results in an infinite chain of instantiations of collection 'type'.*
113128

114129
In addition, the following warnings are covered in this article:
115130

@@ -141,6 +156,11 @@ The following errors indicate that the code generated by the compiler for a coll
141156
- **CS9176**: *There is no target type for the collection literal.*
142157
- **CS9203**: *A collection expression of this type cannot be used in this context because it may be exposed outside of the current scope.*
143158
- **CS9210**: *This version of <xref:System.Collections.Immutable.ImmutableArray%601?displayProperty=nameWithType>cannot be used with collection expressions.*
159+
- **CS9212**: *Spread operator '`..`' cannot operate on variables of type 'type' because 'type' does not contain a public instance or extension definition for 'member'.*
160+
- **CS9213**: *Collection expression target 'type' has no element type.*
161+
- **CS9214**: *Collection expression type must have an applicable constructor that can be called with no arguments.*
162+
- **CS9215**: *Collection expression type 'type' must have an instance or extension method 'Add' that can be called with a single argument.*
163+
- **CS9222**: *Collection initializer results in an infinite chain of instantiations of collection 'type'.*
144164

145165
The compiler might also generate the following warning:
146166

@@ -159,6 +179,11 @@ The errors all indicate that the code generated by the compiler for a collection
159179
- Collection expressions can initialize explicitly typed variables of a collection type. If the variable isn't a collection or array type, or is implicitly typed (using `var`), a collection initializer can't be used.
160180
- A `ref struct` type, like <xref:System.Span%601?displayProperty=nameWithType> can't be initialized with a collection expression that may violate ref safety.
161181
- A collection expression can't correctly initialize an <xref:System.Collections.Immutable.ImmutableArray%601?displayProperty=nameWithType> using the current version. Use a different version of the runtime, or change the initialization expression.
182+
- The spread operator (`..`) in **CS9212** requires the type to implement a suitable method (like `GetEnumerator`) to enumerate its elements. Ensure your type implements the required enumeration pattern or provides an extension method.
183+
- **CS9213** occurs when the compiler can't determine what element type to use for the collection expression. This typically happens with custom collection types. Make sure your collection type properly exposes its element type through its type definition or implements appropriate collection interfaces.
184+
- **CS9214** is generated when a collection expression tries to initialize a type that doesn't have a parameterless constructor. Collection expressions require a constructor that can be called with no arguments to create the instance before adding elements.
185+
- **CS9215** happens when the collection type doesn't provide an `Add` method that accepts a single parameter of the element type. The `Add` method must be accessible (typically public) and accept exactly one argument that matches the collection's element type.
186+
- **CS9222** indicates a circular dependency in collection initialization. This occurs when initializing a collection triggers the creation of another instance of the same collection type, which in turn requires initializing another instance, creating an infinite loop. Review your collection type's constructor and initialization logic to break the circular dependency.
162187

163188
The warnings indicates that the collection expression, including any [spread elements](../operators/collection-expressions.md#spread-element) might allocate memory. Creating different storage and converting might be more efficient.
164189

0 commit comments

Comments
 (0)