managing-apps/.cursor/commands/build-solution.md

build-solution

When to Use

Use this command when you want to:

• Build the entire .NET solution
• Fix compilation errors automatically
• Verify the solution builds successfully
• Check for and resolve build warnings

Prerequisites

• .NET SDK installed (dotnet --version)
• Solution file exists: src/Managing.sln
• All project files are present and valid

Execution Steps

Step 1: Verify Solution File Exists

Check that the solution file exists:

Run: test -f src/Managing.sln

If solution file doesn't exist:

• Error: "❌ Solution file not found at src/Managing.sln"
• STOP: Cannot proceed without solution file

Step 2: Restore NuGet Packages

Restore packages before building:

Run: dotnet restore src/Managing.sln

If restore succeeds:

• Continue to Step 3

If restore fails:

• Show restore errors
• Common issues:
  • Network connectivity issues
  • NuGet feed authentication
  • Package version conflicts
• Try to fix:
  • Check network connectivity
  • Verify NuGet.config exists and is valid
  • Clear NuGet cache: dotnet nuget locals all --clear
  • Retry restore
• If restore still fails:
  • Show detailed error messages
  • STOP: Cannot build without restored packages

Step 3: Build Solution

Build the solution:

Run: dotnet build src/Managing.sln --no-restore

If build succeeds with no errors:

• Show: "✅ Build successful!"
• Show summary of warnings (if any)
• SUCCESS: Build completed

If build fails with errors:

• Continue to Step 4 to fix errors

If build succeeds with warnings only:

• Show warnings summary
• Ask user if they want to fix warnings
• If yes: Continue to Step 5
• If no: SUCCESS: Build completed with warnings

Step 4: Fix Compilation Errors

Analyze build errors and fix them automatically:

Common error types:

1. Project reference errors:

   • Error: "project was not found"
   • Fix: Check project file paths in .csproj files
   • Verify project file names match references
   • Update incorrect project references

2. Missing using statements:

   • Error: "The type or namespace name 'X' could not be found"
   • Fix: Add missing using statements
   • Check namespace matches

3. Type mismatches:

   • Error: "Cannot implicitly convert type 'X' to 'Y'"
   • Fix: Add explicit casts or fix type definitions
   • Check nullable reference types

4. Missing method/property:

   • Error: "'X' does not contain a definition for 'Y'"
   • Fix: Check if method/property exists
   • Verify spelling and accessibility

5. Nullable reference warnings (CS8625, CS8618):

   • Fix: Add ? to nullable types or initialize properties
   • Use null-forgiving operator ! if appropriate
   • Add null checks where needed

6. Package version conflicts:

   • Warning: "Detected package version outside of dependency constraint"
   • Fix: Update package versions in .csproj files
   • Align package versions across projects

For each error:

• Identify the error type and location
• Read the file containing the error
• Fix the error following .NET best practices
• Re-run build to verify fix
• Continue until all errors are resolved

If errors cannot be fixed automatically:

• Show detailed error messages
• Explain what needs to be fixed manually
• STOP: User intervention required

Step 5: Fix Warnings (Optional)

If user wants to fix warnings:

Common warning types:

1. Nullable reference warnings (CS8625, CS8618):

   • Fix: Add nullable annotations or initialize properties
   • Use string? for nullable strings
   • Initialize properties in constructors

2. Package version warnings (NU1608, NU1603, NU1701):

   • Fix: Update package versions to compatible versions
   • Align MediatR versions across projects
   • Update Microsoft.Extensions packages

3. Obsolete API warnings:

   • Fix: Replace with recommended alternatives
   • Update to newer API versions

For each warning:

• Identify warning type and location
• Fix following best practices
• Re-run build to verify fix

If warnings cannot be fixed:

• Show warning summary
• Inform user warnings are acceptable
• SUCCESS: Build completed with acceptable warnings

Step 6: Verify Final Build

Run final build to confirm all errors are fixed:

Run: dotnet build src/Managing.sln --no-restore

If build succeeds:

• Show: "✅ Build successful! All errors fixed."
• Show final warning count (if any)
• SUCCESS: Solution builds successfully

If errors remain:

• Show remaining errors
• Return to Step 4
• STOP if errors cannot be resolved after multiple attempts

Error Handling

If solution file not found:

• Check path: src/Managing.sln
• Verify you're in the correct directory
• STOP: Cannot proceed without solution file

If restore fails:

• Check network connectivity
• Verify NuGet.config exists
• Clear NuGet cache: dotnet nuget locals all --clear
• Check for authentication issues
• Retry restore

If project reference errors:

• Check .csproj files for incorrect references
• Verify project file names match references
• Common issue: Managing.Infrastructure.Database.csproj vs Managing.Infrastructure.Databases.csproj
• Fix project references

If compilation errors persist:

• Read error messages carefully
• Check file paths and line numbers
• Verify all dependencies are restored
• Check for circular references
• STOP if errors require manual intervention

If package version conflicts:

• Update MediatR.Extensions.Microsoft.DependencyInjection to match MediatR version
• Update Microsoft.Extensions.Caching.Memory versions
• Align AspNetCore.HealthChecks.NpgSql versions
• Update packages in all affected projects

Example Execution

User input: /build-solution

AI execution:

1. Verify solution: test -f src/Managing.sln → ✅ Exists
2. Restore packages: dotnet restore src/Managing.sln → ✅ Restored
3. Build solution: dotnet build src/Managing.sln --no-restore
   • Found error: Project reference to Managing.Infrastructure.Database.csproj not found
4. Fix error: Update Managing.Workers.Api.csproj reference to Managing.Infrastructure.Databases.csproj
5. Re-build: dotnet build src/Managing.sln --no-restore → ✅ Build successful
6. Success: "✅ Build successful! All errors fixed."

If nullable warnings:

1-3. Same as above 4. Build succeeds with warnings: CS8625 nullable warnings 5. Fix warnings: Add ? to nullable parameters, initialize properties 6. Re-build: dotnet build src/Managing.sln --no-restore → ✅ Build successful, warnings reduced 7. Success: "✅ Build successful! Warnings reduced."

If package conflicts:

1-3. Same as above 4. Build succeeds with warnings: NU1608 MediatR version conflicts 5. Fix warnings: Update MediatR.Extensions.Microsoft.DependencyInjection to 12.x 6. Re-build: dotnet build src/Managing.sln --no-restore → ✅ Build successful 7. Success: "✅ Build successful! Package conflicts resolved."

Important Notes

• ✅ Always restore first - Ensures packages are available
• ✅ Fix errors before warnings - Errors block builds, warnings don't
• ✅ Check project references - Common source of build errors
• ✅ Verify file names match - Project file names must match references exactly
• ✅ Nullable reference types - Use ? for nullable, initialize non-nullable properties
• ⚠️ Package versions - Keep versions aligned across projects
• ⚠️ Warnings are acceptable - Some warnings (like NU1701) may be acceptable
• 📦 Solution location: src/Managing.sln
• 🔧 Build command: dotnet build src/Managing.sln
• 🗄️ Common fixes: Project references, nullable types, package versions