skills.rest
dotnet
dotnetOFFICIAL
Explore all skills by this author →
Website𝕏@dotnetfdnGitHub

authoring-errors-and-warnings

Guides authoring of MSBuild error, warning, and diagnostic messages with MSBxxxx codes.

1.2k|337|Updated Oct 13, 2022
Search Tags:#Diagnostics#build tooling#msbuild#resx#Localization#Error handling#warning severity
One-click install
npx skills add https://github.com/dotnet/dotnet --skill authoring-errors-and-warnings
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: authoring-errors-and-warnings
Source: https://github.com/dotnet/dotnet/tree/main/src/msbuild/.github/skills/authoring-errors-and-warnings
Command: npx skills add https://github.com/dotnet/dotnet --skill authoring-errors-and-warnings

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Writing clear, correctly-coded MSBuild diagnostics is hard: messages must be actionable, assigned the right MSBxxxx code from the correct Strings.resx range, localized properly, and chosen at a severity that does not silently break WarnAsError builds.

Core Features & Use Cases

  • Message Quality Rules: Enforces the what/why/what-to-do structure so every diagnostic helps developers fix problems without reading source code.
  • Severity Decision Framework: Provides a decision tree for error vs warning vs message, including the WarnAsError breaking-change constraint and ChangeWave gating.
  • Code Assignment & Localization: Documents MSBxxxx code ranges per assembly, Strings.resx conventions with {StrBegin} comments, and the .xlf generation workflow.
  • Use Case: When adding a new MSB4xxx engine error for an invalid project file, follow the checklist to pick the code, write the resource string with placeholder documentation, consume it via LogErrorWithCodeFromResources, and verify with a test.

Quick Start

Ask the assistant to help author a new MSBuild warning for a specific condition, including the MSB code, resource string, and severity recommendation.

Frequently Asked Questions about authoring-errors-and-warnings

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I add a new MSBuild error code MSBxxxx?▼

Open the Strings.resx file for the appropriate assembly, find the "Next message code" comment at the bottom, confirm the code is unused by searching the repo, then use it and update the comment. Code ranges map to assemblies, such as MSB4xxx for the engine.

How to choose between error, warning, and message in MSBuild?▼

Use an error when the condition is always wrong, a warning when it could cause build correctness issues, and a message for informational output. Consider that new warnings break WarnAsError builds, so gate them behind a ChangeWave when needed.

Why do new MSBuild warnings break existing builds?▼

New warnings become errors in builds using -WarnAsError, TreatWarningsAsErrors, or WarningsAsErrors settings. Evaluate whether the warning justifies this breakage, whether a message suffices, or whether ChangeWave gating is required.

What is the correct format for MSBuild resource strings in Strings.resx?▼

Use a FeatureArea.DescriptiveName key, start the value with the MSBxxxx code followed by a colon and space, and add a comment with the {StrBegin} marker plus documentation for each {N} placeholder to guide translators.

How do I log errors with codes from MSBuild task code?▼

Call Log.LogErrorWithCodeFromResources or Log.LogWarningWithCodeFromResources with the resource name and placeholder arguments. Never concatenate error strings manually, since resource strings are required for localization support.

Related Skills

Explore More Software Engineering Skills→
wshaddixwshaddix
71

dotnet-build-analysis

Analyze MSBuild output and diagnose CS, MSB, NU, IDE, and CA errors.

Community
Intermediate
StrocsStrocs

sdd-verify

Run tests and builds to generate structured verification reports.

Community
Advanced
hashintelhashintel
1.6k

writing-hashql-diagnostics

Generate structured HashQL diagnostics with labels, severity, and patches.

Official
Advanced
zdanovichnickzdanovichnick
4

logging

Standardize Serilog structured logging in ASP.NET Core applications.

Community
Intermediate