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