# Build Error Resolution Guide

## Overview

This guide addresses the two main types of build issues in the Jellyfin solution:
1. **CS0006 Metadata Errors** - Missing reference assemblies
2. **IDE#### Analyzer Warnings** - Code style suggestions

---

## 1. CS0006 Metadata Errors (ACTUAL BUILD FAILURES)

### Error Description
```
CS0006: Metadata file '...\obj\Debug\net11.0\ref\ProjectName.dll' could not be found
```

### Cause
These errors occur when:
- Project build artifacts are corrupted or missing
- Projects are built out of order
- Incremental build state is invalid
- Clean operation didn't complete properly

### Solution Options

#### Option A: Quick Rebuild (Recommended)
Run the provided PowerShell script:
```powershell
.\rebuild-solution.ps1
```

#### Option B: Manual Steps in Visual Studio
1. **Build → Clean Solution**
2. **Build → Rebuild Solution**

If that doesn't work:
3. Close Visual Studio
4. Delete all `bin` and `obj` folders:
   ```powershell
   Get-ChildItem -Path . -Include bin,obj -Recurse -Directory | Remove-Item -Recurse -Force
   ```
5. Reopen Visual Studio
6. **Build → Rebuild Solution**

#### Option C: Build Projects in Order
If full rebuild fails, build these projects manually in order:

```powershell
dotnet build "src\Jellyfin.Database\Jellyfin.Database.Implementations\Jellyfin.Database.Implementations.csproj"
dotnet build "src\Jellyfin.Database\Jellyfin.Database.Providers.Postgres\Jellyfin.Database.Providers.Postgres.csproj"
dotnet build "Jellyfin.Server.Implementations\Jellyfin.Server.Implementations.csproj"
dotnet build "Emby.Server.Implementations\Emby.Server.Implementations.csproj"
dotnet build "Jellyfin.Server\Jellyfin.Server.csproj"
dotnet build "Jellyfin.sln"
```

---

## 2. IDE#### Analyzer Warnings (CODE STYLE - NOT BUILD FAILURES)

### Common IDE Warnings and What They Mean

| Code | Description | Severity | Action Taken |
|------|-------------|----------|--------------|
| **IDE0005** | Using directive is unnecessary | Silent | Suppressed |
| **IDE0010** | Populate switch (add missing cases) | Silent | Suppressed |
| **IDE0031** | Null check can be simplified | Silent | Suppressed |
| **IDE0037** | Member name can be simplified | Silent | Suppressed |
| **IDE0047** | Parentheses can be removed | Silent | Suppressed |
| **IDE0055** | Fix formatting | Silent | Suppressed |
| **IDE0060** | Remove unused parameter | Silent | Suppressed |
| **IDE0100** | Remove redundant equality | Silent | Suppressed |
| **IDE0370** | Suppression is unnecessary | Silent | Suppressed |
| **IDE0004** | Cast is redundant | Silent | Suppressed |

### StyleCop Warnings

| Code | Description | Severity | Action Taken |
|------|-------------|----------|--------------|
| **SA1118** | Parameter spans multiple lines | Silent | Suppressed |

### Configuration

All IDE warnings have been suppressed in `.editorconfig`:

```ini
# IDE Rules - Suppress non-critical suggestions
dotnet_diagnostic.IDE0004.severity = silent
dotnet_diagnostic.IDE0005.severity = silent
dotnet_diagnostic.IDE0010.severity = silent
# ... etc
```

### When Suppressions Take Effect

1. **Visual Studio**: 
   - Restart Visual Studio after modifying `.editorconfig`
   - Or reload all projects: Right-click solution → **Reload Projects**

2. **Command Line**:
   - Changes apply immediately on next build
   - May need to clean and rebuild for full effect

### To See Warnings Again

If you want to see these warnings during development, change their severity:

```ini
# In .editorconfig
dotnet_diagnostic.IDE0055.severity = suggestion  # Shows as suggestion
dotnet_diagnostic.IDE0055.severity = warning     # Shows as warning
dotnet_diagnostic.IDE0055.severity = error       # Causes build failure
```

---

## 3. Troubleshooting

### Problem: .editorconfig Changes Not Taking Effect

**Solution:**
1. Close Visual Studio
2. Delete `.vs` folder in solution directory
3. Reopen Visual Studio
4. **Build → Rebuild Solution**

### Problem: Still Getting CS0006 Errors After Clean Build

**Solution:**
1. Check if any projects failed to build:
   ```powershell
   dotnet build Jellyfin.sln --no-incremental
   ```
2. Look for actual compilation errors (not IDE warnings)
3. Build failed projects individually
4. Check for circular dependencies

### Problem: Too Many Warnings Hiding Real Issues

**Solution:**
Adjust severity levels to your preference:
- `none` - Don't show at all
- `silent` - Don't show in Error List, but still in editor
- `suggestion` - Show as suggestion (···)
- `warning` - Show as warning (yellow)
- `error` - Show as error (red)

---

## 4. Build Script Usage

### rebuild-solution.ps1

This script automates the clean and rebuild process:

```powershell
# Run from solution root directory
.\rebuild-solution.ps1
```

**What it does:**
1. Cleans the solution
2. Removes all bin/obj directories
3. Restores NuGet packages
4. Rebuilds the entire solution

**When to use:**
- After switching branches
- After pulling changes that modify project files
- When getting CS0006 errors
- After modifying .csproj files

---

## 5. Git Considerations

### Files to Commit
- ✅ `.editorconfig` - Code style settings
- ✅ `rebuild-solution.ps1` - Build helper script
- ✅ `docs/build-error-resolution.md` - This guide

### Files to Ignore
- ❌ `bin/` directories (already in .gitignore)
- ❌ `obj/` directories (already in .gitignore)
- ❌ `.vs/` directory (already in .gitignore)

---

## 6. Summary

### Quick Reference

**CS0006 Errors (Build Failures):**
```powershell
# Quick fix
.\rebuild-solution.ps1
```

**IDE Warnings (Code Style):**
- Already suppressed in `.editorconfig`
- Restart Visual Studio if needed
- No action required for build

### Build Status Check

After fixing errors, verify clean build:
```powershell
dotnet build Jellyfin.sln --no-incremental
```

Expected output:
```
Build succeeded.
    0 Warning(s)
    0 Error(s)
```

---

## Support

If you continue to experience issues:
1. Check that you're using .NET 11 SDK
2. Verify all NuGet packages restored successfully
3. Check for antivirus interference with build process
4. Try building in a fresh clone of the repository