Fix up code snippets and descriptions#51524
Conversation
There was a problem hiding this comment.
Pull request overview
This PR addresses Issue #41327 by fixing code snippets and improving descriptions in the custom logging provider documentation. The main issue was that the documentation contained unexplained code fragments (specifically parameter lines from a method signature) that confused readers.
Changes:
- Replaced the meaningless code snippet showing parameter fragments with a proper snippet reference that demonstrates the IsEnabled check pattern
- Improved heading hierarchy by promoting subsections from H3 to H2 for better document structure
- Enhanced clarity in various descriptions and converted text to be more conversational and aligned with Microsoft's documentation style guidelines
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.
| File | Description |
|---|---|
| docs/core/extensions/snippets/configuration/console-custom-logging/ColorConsoleLogger.cs | Added snippet markers around the IsEnabled check for better code reuse in documentation |
| docs/core/extensions/logging/custom-provider.md | Fixed code snippet references, improved heading structure, enhanced descriptive text, added tables for better visual clarity, and updated metadata date |
Comments suppressed due to low confidence (1)
docs/core/extensions/logging/custom-provider.md:58
- The highlight now only emphasizes line 7 (ProviderAlias attribute), but the explanatory text on lines 57-58 describes both the UnsupportedOSPlatform attribute (line 6) and the ProviderAlias attribute (line 7). Consider highlighting both lines 6-7 to match the text, or adjust the text to focus primarily on the ProviderAlias attribute.
:::code language="csharp" source="../snippets/configuration/console-custom-logging/ColorConsoleLoggerProvider.cs" range="6-8" highlight="7":::
The `ColorConsoleLoggerProvider` class defines two class-scoped attributes:
- <xref:System.Runtime.Versioning.UnsupportedOSPlatformAttribute>: The `ColorConsoleLogger` type is _not supported_ in the `"browser"`.
- <xref:Microsoft.Extensions.Logging.ProviderAliasAttribute>: Configuration sections can define options using the `"ColorConsole"` key.
docs/core/extensions/snippets/configuration/console-custom-logging/ColorConsoleLogger.cs
Outdated
Show resolved
Hide resolved
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 3 out of 3 changed files in this pull request and generated 6 comments.
Comments suppressed due to low confidence (1)
docs/core/extensions/logging/custom-provider.md:85
- According to markdown style guidelines, the title should be in sentence case. "app" should be lowercase rather than uppercase "App" to follow the guideline of capitalizing only the first word and proper nouns in headings and text.
- [Dependency injection in .NET](../dependency-injection/overview.md)
| Running this simple application will render color output to the console window similar to the following image: | ||
| The `ILoggingBuilder` creates one or more `ILogger` instances. The `ILogger` instances are used by the framework to log the information. | ||
|
|
||
| The instantiation code overrides the color values from the _appsettings.json_ file for <xref:Microsoft.Extensions.Logging.LogLevel.Warning?displayProperty=nameWithType> and <xref:Microsoft.Extensions.Logging.LogLevel.Error?displayProperty=nameWithType>. |
There was a problem hiding this comment.
The highlight range "8-14" appears to be incorrect. Looking at the Program.cs file, line 8 is the call to AddColorConsoleLogger, which starts the configuration block, but the closing bracket is on line 16, not line 14. The highlight should be "8-16" to include the complete AddColorConsoleLogger call.
| It's a good practice to call <xref:Microsoft.Extensions.Logging.ILogger.IsEnabled*?displayProperty=nameWithType> within <xref:Microsoft.Extensions.Logging.ILogger.Log*?displayProperty=nameWithType> implementations since `Log` can be called by any consumer, and there are no guarantees that it was previously checked. The `IsEnabled` method should be very fast in most implementations. | ||
|
|
||
| It's a good practice to call <xref:Microsoft.Extensions.Logging.ILogger.IsEnabled%2A?displayProperty=nameWithType> within <xref:Microsoft.Extensions.Logging.ILogger.Log%2A?displayProperty=nameWithType> implementations since `Log` can be called by any consumer, and there are no guarantees that it was previously checked. The `IsEnabled` method should be very fast in most implementations. | ||
| :::code language="csharp" source="../snippets/configuration/console-custom-logging/ColorConsoleLogger.cs" range="20-23"::: |
There was a problem hiding this comment.
The code range "19-22" only shows the opening brace of the Log method and the early return check. Based on the context in line 31, which explains that "It's a good practice to call IsEnabled within Log implementations," the range should likely be "20-23" to show the complete IsEnabled check including the closing brace, or the range should be adjusted to show the meaningful part of the implementation.
| :::code language="csharp" source="../snippets/configuration/console-custom-logging/ColorConsoleLogger.cs" range="20-23"::: | |
| :::code language="csharp" source="../snippets/configuration/console-custom-logging/ColorConsoleLogger.cs"::: |
| --- | ||
| title: Implement a custom logging provider | ||
| description: Discover how to implement a custom logging provider with colorized logs, writing custom C# ILogger and ILoggerProvider implementations. | ||
| ms.date: 10/20/2025 | ||
| ms.date: 02/04/2026 | ||
| ms.topic: how-to | ||
| --- |
There was a problem hiding this comment.
According to the .NET Documentation Guidelines (CodingGuidelineID: 1000000), Markdown files that have been generated or significantly modified with AI assistance should include an ai-usage frontmatter key. Since this PR involves substantial edits and improvements, consider adding ai-usage: ai-assisted to the frontmatter if AI was used to assist with these changes.
1 participant
Contributes to #41327 (fragments left in document).
Internal previews