Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.
Um comando direto ignora o prompt de revisão. Verifique a origem antes de executá-lo.
Help agents interpret and act on MSBuild build output. Covers error code prefixes, NuGet restore failures, analyzer
warning interpretation, multi-targeting build differences, and "works locally, fails in CI" diagnosis patterns. Each
subsection includes example output, diagnosis steps, and a fix pattern.
Writing or modifying .csproj files -- see [skill:dotnet-csproj-reading]
Project structure decisions -- see [skill:dotnet-project-structure]
Common agent code mistakes -- see [skill:dotnet-agent-gotchas]
Prerequisites
.NET 8.0+ SDK. MSBuild (included with .NET SDK). Understanding of SDK-style project format.
Cross-references: [skill:dotnet-agent-gotchas] for common code mistakes that cause build errors,
[skill:dotnet-csproj-reading] for project file structure and modification, [skill:dotnet-project-structure] for project
organization and SDK selection.
Error Code Prefixes
MSBuild output uses standardized prefixes to indicate the error source. Understanding the prefix tells you which system
produced the error and where to look for fixes.
CS -- C# Compiler Errors and Warnings
Produced by the Roslyn C# compiler. These are language-level issues in source code.
Example output:
src/MyApp.Api/Services/OrderService.cs(42,17): error CS0246: The type ornamespacename 'OrderDto' couldnotbefound (areyoumissingausingdirectiveoranassemblyreference?)
src/MyApp.Api/Models/(15,9): : - '' - . '' .
```
**:**
1. -- `///` 42, 17.
2. . : ? ?
?
3. . `` ,
(`?`), .
** :**
- (/ ): . `` , ,
.
- ( ): , , `` . `#`
`!` .
### --
. , ,
.
** :**
```
: ":\ \\\9.0.100\\\\\" . "..." .
: .,=v4 were found. You might need to install the developer pack framework version.
```text
**Diagnosis:**
MSB4019: An MSBuild `.targets` missing. This usually means wrong SDK type, missing workload, corrupt SDK
installation.
MSB3644: Targeting a framework version whose targeting pack installed. Common a project targets .NET
Framework but only .NET (Core) SDK installed.
**Fix pattern:**
- MSB4019: Verify `<Project Sdk=>` = ...` to explicitly discard.
**Fix pattern:**
- IDE analyzers enforce code style. Fix them applying the suggested change. Configure severity `.editorconfig` to
promote warnings to errors CI enforcement.
Produced the .NET code analysis SDK analyzers API design, performance, reliability, security rules.
**Example output:**
```text
src/MyApp.Api/Services/CacheService.cs(,): warning CA1848: Use the LoggerMessage delegates instead of calling . Using LoggerMessage delegates provides better performance.
src/MyApp.Api/Controllers/UserController.cs(,): warning CA2007: Consider calling ConfigureAwait the awaited task
src/MyApp.Api/Crypto/HashService.cs(,): warning CA5351: = = />
< key= = />
</packageSources>
<packageSourceMapping>
<packageSource key=>
<package pattern= />
</packageSource>
<packageSource key=>
<package pattern= />
</packageSource>
</packageSourceMapping>
</configuration>
```text
**Example output:**
```text
error NU1107: Version conflict detected Microsoft.Extensions.DependencyInjection.Abstractions.
MyApp.Api -> Microsoft.EntityFrameworkCore -> Microsoft.Extensions.DependencyInjection.Abstractions (>= )
MyApp.Api -> Microsoft.Extensions.Hosting -> Microsoft.Extensions.DependencyInjection.Abstractions (>= )
```text
**Diagnosis:**
Two dependency chains require different major versions of the same package.
Trace each chain to find which top-level package pinned at an older version.
The fix usually upgrading the older top-level package.
**Fix pattern:**
```xml
<!-- Upgrade the older top-level package to match -->
<PackageReference Include= Version= />
<!-- Or a direct reference to force a specific version -->
<PackageReference Include= Version= />
```text
**Example output:**
```text
Retrying source .
Response status code does indicate success: (Unauthorized).
error NU1301: Unable to load the service index source https:
```json
**Diagnosis:**
Credentials are missing expired the feed.
In CI, check that the credential provider PAT configured.
Locally, run `dotnet nuget update source` credentials use Azure Artifacts Credential Provider.
**Fix pattern:**
```bash
dotnet nuget update source MyCompany --username az --password $PAT --store-password--clear-text
```text
---
Analyzer warnings are produced Roslyn analyzers bundled the SDK added via NuGet. Understanding to fix
vs. to configure severity critical.
```text
src/MyApp.Api/Controllers/OrdersController.cs(,): warning CA2007: Consider calling ConfigureAwait the awaited task [/src/MyApp.Api/MyApp.Api.csproj]
src/MyApp.Api/Services/OrderService.cs(,): warning CA1062: In externally visible method , validate parameter non- before it [/src/MyApp.Api/MyApp.Api.csproj]
src/MyApp.Api/Models/UserDto.cs(,): warning IDE0032: Use auto-implemented property [/src/MyApp.Api/MyApp.Api.csproj]
```csharp
**Diagnosis:**
Identify the prefix: `CA` = = IDE code style analyzers.
Check severity: warnings dont apply project-wide (see below).
- **Suppress inline** ; shown IDE | Fix practical |
| **Hidden** | Not shown; available via code fix | Ignore unless actively refactoring |
Use `.editorconfig` to control analyzer behavior across the project:
```ini
[*.cs]
dotnet_diagnostic.CS8600.severity = error
dotnet_diagnostic.CS8602.severity = error
dotnet_diagnostic.CS8603.severity = error
dotnet_diagnostic.CA2007.severity = none
dotnet_diagnostic.CA5350.severity = error
dotnet_diagnostic.CA5351.severity = error
```text
Suppression acceptable ONLY :
The analyzer cannot understand the codeFrozenDictionary<, >GetAlternateLookup$(TargetFramework)net8System.Collections.ImmutablesdkversionrollForwardlatestPatchResolveAssemblyReferenceSecurityCA5351 ProcessOrderOrderService/ProcessOrdersrc/Services/OrderService.cs
User.cs
warning
CS8618
Non
nullable
property
Name
must
contain
a
non
null
value
when
exiting
constructor
Consider
adding
the
required
modifier
or
declaring
the
property
as
nullable
csharp
Diagnosis
Parse
the
file
path
and
line
number
from
the
error
src
MyApp.Api
Services
OrderService.cs
line
column
CS0246
means
a
type
is
missing
Check
is
the
type
defined
Is
the
namespace
imported
Is
the
project
referencing
the
assembly
that
contains
it
CS8618
is
a
nullable
reference
type
warning
The
property
needs
a
required
modifier
nullable
annotation
string
or
constructor
initialization
Fix
pattern
CS0xxx
syntax
type
errors
Fix
source
code
at
the
indicated
location
Add
using
directives
fix
type
names
add
missing
references
CS8xxx
nullable
warnings
Add
null
annotations
null
checks
or
required
modifiers
Do
NOT
suppress
with
pragma
or
operator
MSB
MSBuild
Engine
Errors
Produced
by
the
MSBuild
build
engine
itself
These
indicate
project
file
problems
target
failures
or
build
system
misconfiguration
Example
output
text
error
MSB4019
The
imported
project
C
Program
Files
dotnet
sdk
Microsoft
VisualStudio
v17.0
WebApplications
Microsoft.WebApplication.targets
was
not
found
Confirm
that
the
expression
in
the
Import
declaration
is
correct
error
MSB3644
The
reference
assemblies
for
NETFramework
Version
.8
not
for
this
1.
file
is
or
2.
is
not
when
is
"..."
iscorrect (e.g., `Microsoft.NET.Sdk.Web` for ASP.NET Core). Run
`dotnet workload list` and install missing workloads.
- MSB3xxx: Check `<TargetFramework>` value. Ensure the required SDK or targeting pack is installed.
### NU -- NuGet Errors and Warnings
Produced by the NuGet package manager during restore or pack operations.
**Example output:**
```text
error NU1101: Unable to find package Newtonsoft.Json.Extensions. No packages exist withthis id insource(s): nuget.org
warning NU1603: Microsoft.EntityFrameworkCore 9.0.0 depends on Microsoft.Extensions.Caching.Memory (>= 9.0.0) but version Microsoft.Extensions.Caching.Memory 8.0.1 was resolved. Approve the package to suppress this warning.
error NU1605: Detected package downgrade: Microsoft.Extensions.Logging from 9.0.0 to 8.0.1. Reference the package directly from the project to select a different version.
```json
**Diagnosis:**
1. NU1101: Package ID does not exist. Check spelling, verify the package source is configured, check if the package was
renamed or deprecated.
2. NU1603: Transitive dependency version conflict. A package wants a newer version than what is resolved.
3. NU1605: Explicit downgrade detected. Two packages require different versions of the same dependency.
**Fix pattern:**
- NU1101: Fix the package name. Search [nuget.org](https://www.nuget.org/) for the correct ID.
- NU1603/NU1605: Add a direct `<PackageReference>` for the conflicting package at a compatible version, or use central
package management to pin versions.
### IDE -- IDE/Roslyn Analyzer Code Style Diagnostics
Produced by Roslyn IDE analyzers for code style enforcement. These are usually warnings, noterrors (unless
`.editorconfig` escalates them).
**Example output:**
```text
src/MyApp.Api/Program.cs(1,1): warning IDE0005: Using directive is unnecessary.
src/MyApp.Api/Models/Order.cs(8,12): warning IDE0044: Make field readonly
src/MyApp.Api/Services/Report.cs(22,5): warning IDE0058: Expression valueis never used
```csharp
**Diagnosis:**
1. IDE0005: Unused `using` directive. Safe to remove.
2. IDE0044: Field can be `readonly` because it is only assigned in the constructor.
3. IDE0058: A method returnvalueis discarded. Either assign it or use `_
by
in
for
### CA -- .NET Code Analysis (FxCop/Microsoft.CodeAnalysis.NetAnalyzers)
Do Not Use Broken Cryptographic Algorithms (MD5)
```csharp
**Diagnosis:**
1. CA1848: High-performance logging. Use `[LoggerMessage]` source generator attributes instead of string interpolation
in log calls.
2. CA2007: `ConfigureAwait(false)` guidance for library code. Not applicable to ASP.NET Core app code (no
`SynchronizationContext`).
3. CA5351: Security-critical. MD5 is broken for cryptographic purposes. Switch to SHA-256 or SHA-512.
**Fix pattern:**
- CA1xxx (design): Apply suggested API changes. These improve API consistency.
- CA2xxx (reliability/performance): Fix per suggestion. CA2007 can be suppressed in ASP.NET Core apps via
`.editorconfig`.
- CA5xxx (security): Always fix. These flag real security vulnerabilities.
---
## NuGet Restore Failures
NuGet restore is the first build step. When it fails, no compilation occurs. These are the most common restore failure
patterns.
### Pattern: Package Not Found
**Example output:**
```text
Determining projects to restore...
Writing assets file to disk. Path: /src/MyApp.Api/obj/project.assets.json
/src/MyApp.Api/MyApp.Api.csproj : error NU1101: Unable to find package MyCompany.Shared.Models. No packages exist withthis id insource(s): nuget.org
Failed to restore /src/MyApp.Api/MyApp.Api.csproj (in2.14 sec).
```csharp
**Diagnosis:**
1. Is the package ID spelled correctly? NuGet IDs are case-insensitive but must be exact.
2. Is the package from a private feed? Check `nuget.config` for feed configuration. NuGet searches feeds hierarchically
upward from the project directory.
3. Is `packageSourceMapping` configured? If so, the package must be mapped to a source that contains it. `MyCompany.*`
patterns take precedence over `*` wildcard.
**Fix pattern:**
```bash
# Check configured sources
dotnet nuget list source
# Check if nuget.config exists (searches upward from project dir)
ls nuget.config ../nuget.config ../../nuget.config 2>/dev/null
```text
```xml
<!-- Add private feed to nuget.config -->
<configuration>
<packageSources>
<add key
# macOS/Linux: sh -c "$(curl -fsSL https://aka.ms/install-artifacts-credprovider.sh)"
# Or add credentials explicitly to a specific source
in
## Analyzer Warning Interpretation
by
with
or
when
when
is
### Example Output
27
5
on
15
16
'OrderService.Process(string)'
'input'
is
null
using
8
12
1.
Code Analysis (.NET analyzers), `IDE`
2.
't break builds unless `<TreatWarningsAsErrors>true</TreatWarningsAsErrors>` is set.
3. Determine if the rule applies to your project type (e.g., CA2007 is irrelevant in ASP.NET Core — no
SynchronizationContext).
4. Decide: fix the code, configure severity in `.editorconfig`, or suppress with documented justification.
**Fix pattern:**
- **Fix the code** when the analyzer identifies a real issue (CA1062 — add null validation or use
`ArgumentNullException.ThrowIfNull`).
- **Configure severity** in `.editorconfig` when the rule doesn'
only with documented justification (see "When Suppression Is Acceptable" below).
### Severity Levels
| Severity | Build Impact | Action |
| -------------- | ----------------------------------------------------------------------------- | ----------------------------------- |
| **Error** | Build fails | Must fix before build succeeds |
| **Warning** | Build succeeds (unless `<TreatWarningsAsErrors>true</TreatWarningsAsErrors>`) | Fix or configure in `.editorconfig` |
| **Suggestion** | Build succeeds
in
when
### Configuring Severity
# .editorconfig (place at solution root)
# Promote nullable warnings to errors (recommended)
# Suppress ConfigureAwait warning in ASP.NET Core apps (no SynchronizationContext)
# Promote security warnings to errors
### When Suppression Is Acceptable
is
when
1.
's safety guarantee (e.g., a custom guard clause that ensures non-null).
2. The rule does not apply to the project type (e.g., CA2007 in ASP.NET Core apps).
3. A documented justification is provided.
```csharp
// ACCEPTABLE: documented justification
[SuppressMessage("Reliability", "CA2007:ConfigureAwait",
Justification = "ASP.NET Core has no SynchronizationContext")]
// TODO: Audit suppression - add justification or remove if not applicable
public async Task<Order> GetOrderAsync(int id, CancellationToken ct)
{
return await _repo.GetByIdAsync(id, ct);
}
// NOT ACCEPTABLE: no justification, hides a real issue
#pragma warning disable CA1062
// TODO: Audit suppression - add justification or remove
public void Process(string input) { } // input could be null
#pragma warning restore CA1062
```text
---
## Multi-Targeting Build Output
When a project targets multiple frameworks, MSBuild builds each TFM separately. Errors may appear for only one target.
### Example Output
```text
MyApp.Shared -> /src/MyApp.Shared/bin/Debug/net8.0/MyApp.Shared.dll
src/MyApp.Shared/Services/FeatureService.cs(18,30): error CS1061: '
string
int
' does not contain a definition for '
' [/src/MyApp.Shared/MyApp.Shared.csproj -> net8.0]
MyApp.Shared -> /src/MyApp.Shared/bin/Debug/net9.0/MyApp.Shared.dll
Build succeeded for net9.0.
Build FAILED for net8.0.
```text
**Diagnosis:**
1. The error tag `[...csproj -> net8.0]` shows which TFM failed. `net9.0` succeeded.
2. `GetAlternateLookup` was added in .NET 9. The code uses an API not available in .NET 8.
3. The fix requires conditional compilation or an alternative API for the older TFM.
**Fix pattern:**
```csharp
// Use preprocessor directives for TFM-specific code
#if NET9_0_OR_GREATER
var lookup = frozenDict.GetAlternateLookup<ReadOnlySpan<char>>();
return lookup.TryGetValue(key, out var value) ? value : default;
#else
return frozenDict.TryGetValue(key.ToString(), out var value) ? value : default;
#endif
```text
```xml
<!-- Or constrain the feature to specific TFMs in the project file -->
<PropertyGroup>
<TargetFrameworks>net8.0;net9.0</TargetFrameworks>
</PropertyGroup>
<!-- TFM-conditional package reference -->
<ItemGroup Condition="'
' == '
.0'
">
<PackageReference Include="
" Version="
8.0
.0
" />
</ItemGroup>
```text
### Reading Multi-Target Output
Key patterns for identifying TFM-specific issues:
- `[ProjectPath -> TFM]` suffix on every diagnostic line identifies the target.
- `Build succeeded for netX.0` / `Build FAILED for netX.0` summary at the end.
- Restore output shows all TFMs: `Restored ... (net8.0, net9.0)`.
- Build output paths include the TFM: `bin/Debug/net8.0/` vs `bin/Debug/net9.0/`.
---
## CI Drift: Works Locally, Fails in CI
The most frustrating build failures are ones that pass locally but fail in CI. These are almost always caused by
environmental differences.
### Pattern: Different SDK Version
**Example scenario:**
```text
Local: dotnet --version -> 9.0.200
CI: dotnet --version -> 9.0.100
Build error in CI:
error CS8652: The feature 'field keyword' is currently in Preview and *unsupported*.
```text
**Diagnosis:**
1. The local SDK (9.0.200) includes a language preview feature that the CI SDK (9.0.100) does not.
2. A `global.json` file is either missing or not pinning the SDK version.
**Fix pattern:**
```json
// global.json -- pin SDK version for consistent builds
{
"
": {
"
": "
9.0
.200
",
"
": "
"
}
}
```text
### Pattern: Missing Workload in CI
**Example scenario:**
```text
CI error:
error NETSDK1147: To build this project, the following workloads must be installed: maui-android
```text
**Diagnosis:**
1. MAUI/Aspire/WASM workloads installed locally but not in the CI image.
2. CI pipeline needs explicit workload install step.
**Fix pattern:**
```yaml
# GitHub Actions example
- name: Install .NET workloads
run: dotnet workload install maui-android maui-ios
```yaml
### Pattern: Implicit NuGet Sources
**Example scenario:**
```text
Local restore succeeds (using cached packages).
CI error:
error NU1101: Unable to find package MyCompany.Internal.Lib.
```text
**Diagnosis:**
1. Local machine has the package in the global NuGet cache from a previous restore.
2. CI starts with a clean cache and cannot find the package because the private feed is not configured.
3. A `nuget.config` file is missing from the repository, or CI lacks feed credentials.
**Fix pattern:**
1. Add `nuget.config` to the repository root with all required package sources.
2. Configure CI to authenticate to private feeds (credential provider, PAT, or managed identity).
3. Do NOT rely on global NuGet cache for CI builds.
### Pattern: OS-Specific Path Differences
**Example scenario:**
```text
Local (Windows): Build succeeds
CI (Linux): error MSB4018: The "
" task failed.
Could not find file '/src/MyApp/../Shared/MyLib.dll'
```text
**Diagnosis:**
1. Windows file system is case-insensitive; Linux is case-sensitive.
2. A file reference uses different casing than the actual file on disk.
3. Or backslash path separators in MSBuild properties that Linux cannot resolve.
**Fix pattern:**
- Ensure file and directory names match the case used in project references exactly.
- Use forward slashes (`/`) in `.csproj` paths -- MSBuild normalizes them on all platforms.
- Test in a Linux container locally with `docker run` before pushing.
### Pattern: TreatWarningsAsErrors in CI Only
**Example scenario:**
```text
Local: Build succeeds with 3 warnings
CI: error CS8602: Dereference of a possibly null reference.
(because CI sets TreatWarningsAsErrors=true)
```text
**Diagnosis:**
1. CI pipeline or `Directory.Build.props` enables `<TreatWarningsAsErrors>true</TreatWarningsAsErrors>` via a CI-only
condition.
2. Developers see warnings locally but never fix them because the build succeeds.
**Fix pattern:**
- Enable `<TreatWarningsAsErrors>true</TreatWarningsAsErrors>` unconditionally in `Directory.Build.props` so local and
CI builds behave identically.
- Fix all warnings. Do NOT add CI-only MSBuild properties that diverge from local behavior.
---
## Slopwatch Anti-Patterns
These patterns indicate an agent is hiding build problems rather than fixing them. Flag these during code review. See
[skill:dotnet-slopwatch] for the automated quality gate that detects these patterns.
### Warning Suppressions
```xml
<!-- RED FLAG: blanket NoWarn in .csproj -->
<PropertyGroup>
<NoWarn>CS8600;CS8602;CS8603;CS8604;IL2026;IL2046</NoWarn>
</PropertyGroup>
```csharp
```csharp
// RED FLAG: pragma disable without justification
#pragma warning disable CS8618
public class UserModel
{
public string Name { get; set; } // non-nullable not initialized
public string Email { get; set; }
}
#pragma warning restore CS8618
```text
**Fix:** Remove `<NoWarn>` entries and fix the underlying issues. If suppression is truly needed, use `.editorconfig`
with per-rule severity and a comment explaining why.
### Silenced Analyzers Without Justification
```csharp
// RED FLAG: suppressing security analyzer with no explanation
[SuppressMessage("
", "
")]
public byte[] HashData(byte[] input)
{
using var md5 = MD5.Create(); // insecure algorithm
return md5.ComputeHash(input);
}
```text
```ini
# RED FLAG: disabling entire analyzer categories in .editorconfig
[*.cs]
dotnet_diagnostic.CA5350.severity = none
dotnet_diagnostic.CA5351.severity = none
dotnet_diagnostic.CA5358.severity = none
```csharp
**Fix:** Replace insecure algorithms (MD5 -> SHA-256). If suppression is unavoidable (e.g., interop with a system
requiring MD5), add a `Justification` string explaining the constraint.
---
## Cross-References
- [skill:dotnet-agent-gotchas] -- common agent coding mistakes that produce build errors
- [skill:dotnet-csproj-reading] -- project file structure, PropertyGroup/ItemGroup conventions
- [skill:dotnet-project-structure] -- SDK selection, project organization, multi-project solutions
## Code Navigation (Serena MCP)
**Primary approach:** Use Serena symbol operations for efficient code navigation:
1. **Find definitions**: `serena_find_symbol` instead of text search
2. **Understand structure**: `serena_get_symbols_overview` for file organization
3. **Track references**: `serena_find_referencing_symbols` for impact analysis
4. **Precise edits**: `serena_replace_symbol_body` for clean modifications
**When to use Serena vs traditional tools:**
- ✅ **Use Serena**: Navigation, refactoring, dependency analysis, precise edits
- ✅ **Use Read/Grep**: Reading full files, pattern matching, simple text operations
- ✅ **Fallback**: If Serena unavailable, traditional tools work fine
**Example workflow:**
```text
# Instead of:
Read: src/Services/OrderService.cs
Grep: "
