wjones
23ed81b6b1
- Add build-error-resolution.md guide for CS0006 and IDE analyzer issues - Add rebuild-solution.ps1 script for clean/reliable builds - Suppress noisy IDE/StyleCop warnings in .editorconfig - Optimize BaseItemRepository grouping queries to use Min(Id) instead of FirstOrDefault, avoiding correlated subqueries and greatly improving DB performance - Add database-query-optimization.md explaining query changes and tuning - Enable EF Core SQL query logging, sensitive data, and detailed errors when log level is Debug (ServiceCollectionExtensions, logging.json) - Update readme with SQL logging instructions - Clarify git commit/ignore guidance and improve inline documentation
228 lines
6.0 KiB
Markdown
228 lines
6.0 KiB
Markdown
# 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
|