Improve build reliability, query perf, and documentation
- 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
This commit is contained in:
@@ -0,0 +1,227 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user