# .NET 11.0 (PREVIEW) Upgrade Plan
## Table of Contents
1. [Executive Summary](#executive-summary)
2. [Migration Strategy](#migration-strategy)
3. [Detailed Dependency Analysis](#detailed-dependency-analysis)
4. [Project-by-Project Plans](#project-by-project-plans)
5. [Risk Management](#risk-management)
6. [Testing & Validation Strategy](#testing--validation-strategy)
7. [Complexity & Effort Assessment](#complexity--effort-assessment)
8. [Source Control Strategy](#source-control-strategy)
9. [Success Criteria](#success-criteria)
---
## Executive Summary
### Scenario Overview
This plan details the upgrade of the Jellyfin media server solution from .NET 9.0 to **.NET 11.0 (PREVIEW)**, encompassing 41 projects (40 application projects plus 1 analyzer project targeting netstandard2.0).
### Scope
- **Projects to Upgrade**: 40 projects (main codebase)
- **Projects Unchanged**: 1 project (Jellyfin.CodeAnalysis - netstandard2.0 analyzer)
- **Total Lines of Code**: Estimated 200,000+ LOC across solution
- **Project Types**: ASP.NET Core web applications, class libraries, test projects
- **Current Framework**: .NET 9.0
- **Target Framework**: .NET 11.0 (PREVIEW)
### Discovered Metrics
- **Total Projects**: 41
- **Dependency Depth**: 12 levels (from leaf to top-level test projects)
- **Circular Dependencies**: None detected
- **Critical Path Length**: 12 project levels
- **NuGet Packages**: 80 total packages
- **Package Compatibility**: ✅ **100% compatible** - All packages already support .NET 11.0
- **Security Vulnerabilities**: None detected in current packages
- **Breaking Changes**: No mandatory breaking changes identified by assessment
- **Risk Indicators**:
- Large, complex solution with deep dependency chains
- Preview framework (not production-ready)
- Heavy use of Entity Framework Core and ASP.NET Core
- Database providers (PostgreSQL, SQLite) require careful testing
### Complexity Classification: **Complex**
**Justification:**
- **42 projects** exceeds medium threshold (>15 projects)
- **12-level dependency depth** exceeds complexity threshold (>4 levels)
- **No high-risk issues** detected (0 mandatory issues)
- **No security vulnerabilities** in current packages
- **Complex technology stack**: EF Core, ASP.NET Core, multiple database providers, media processing
- **Preview framework target**: .NET 11.0 is not yet released (preview stability concerns)
Despite the absence of breaking changes or compatibility issues, the solution's **size, depth, and preview framework target** classify this as a **Complex** upgrade requiring careful, phased execution.
### Selected Strategy: Bottom-Up (Dependency-First) Approach
**Rationale:**
- **Large solution** (41 projects) benefits from incremental validation
- **Deep dependency tree** (12 levels) requires stable foundation before building upward
- **Preview framework** introduces unknown risks best addressed incrementally
- **Database providers** in mid-levels need thorough testing before application tier
- **Test projects** at multiple levels enable validation after each tier
- **Zero breaking changes** identified, but preview framework may introduce runtime issues
- **Risk-averse approach** appropriate for production media server moving to preview framework
### Critical Considerations
1. **Preview Framework**: .NET 11.0 is not production-ready; expect potential instability
2. **Package Ecosystem**: While packages report compatibility, preview framework behavior may differ
3. **Database Providers**: PostgreSQL and SQLite providers need extensive testing with .NET 11.0
4. **Media Processing**: SkiaSharp and media encoding libraries require validation
5. **Performance**: Monitor for performance regressions in preview builds
6. **Breaking Changes**: May emerge during testing despite clean analysis
### Expected Remaining Iterations
Based on complexity classification and solution structure:
- **Phase 1**: Complete (Discovery & Classification)
- **Phase 2**: 3 iterations (Foundation planning)
- **Phase 3**: 8-10 iterations (Tier-by-tier detailed planning)
- **Total**: ~11-13 iterations to complete plan
## Migration Strategy
### Approach Selection: Bottom-Up (Dependency-First)
**Decision: Incremental tier-by-tier migration** starting from leaf nodes (Tier 2) progressing to top-level application (Tier 11) and tests (Tiers 12-13).
### Rationale for Bottom-Up Strategy
#### Why Bottom-Up is Optimal for This Solution
1. **Large Solution Scale**
- 41 projects exceed threshold for coordinated migration (>15 projects)
- Incremental approach reduces risk of simultaneous failures
- Enables validation at each tier before proceeding
2. **Deep Dependency Hierarchy**
- 12 levels of dependencies require stable foundation
- Bottom-up ensures each project builds on already-upgraded, tested tier
- No multi-targeting complexity (all projects move to .NET 11.0)
3. **Preview Framework Target**
- .NET 11.0 is PREVIEW (not production-ready)
- Unknown risks best addressed incrementally
- Early tiers expose framework issues before touching applications
- Allows retreat/adjustment if preview proves unstable
4. **Clear Dependency Structure**
- DAG (no circular dependencies) enables clean bottom-up flow
- Well-defined tiers with explicit between-tier dependencies
- Each tier can be independently validated
5. **Critical Database Layer**
- Database providers (Tier 6) require extensive testing
- Must be stable before business logic (Tier 8+)
- Early validation prevents cascading failures
6. **Test Projects Throughout**
- Test projects in Tiers 3, 5, 7, 9, 12, 13 enable continuous validation
- Each tier completion includes test execution
- Fail-fast at lowest affected tier
### Alternative Approaches Considered
#### ❌ All-At-Once Migration
**Rejected because:**
- 41 projects too large for coordinated update
- Preview framework introduces unknown risks
- Single-shot approach would complicate debugging
- Complex solution requires staged validation
#### ❌ Top-Down (Application-First)
**Rejected because:**
- Would require multi-targeting all dependencies
- Increased complexity managing two framework versions
- Testing top tiers before infrastructure ready is risky
- Database providers must be stable before applications use them
### Bottom-Up Execution Principles
#### Strict Tier Ordering
1. ✅ **Must complete Tier N before starting Tier N+1**
2. ✅ **Tier completion = all projects built, tested, validated**
3. ✅ **No tier skipping** - even if tempting to fast-track
4. ✅ **Rollback at tier level** - if tier fails, revert entire tier
#### Within-Tier Execution
- **Projects within same tier can be upgraded in parallel** (no inter-dependencies)
- **Batch project file updates** for entire tier (single operation)
- **Batch package updates** for entire tier (single operation)
- **Test tier as a whole** before proceeding
- **Tier 8** (12 projects) is largest; can parallelize to speed up
#### Tier Completion Criteria
Each tier must meet criteria before proceeding:
1. **Build Success**
- All projects in tier build without errors
- All projects in tier build without warnings (target: zero warnings)
2. **Package Restoration**
- All NuGet packages restore successfully
- No package dependency conflicts
3. **Test Execution**
- All test projects in tier pass (if tier contains tests)
- Tests for lower tiers still pass (regression check)
4. **Code Quality**
- No new compiler errors introduced
- Code analysis passes (StyleCop, analyzers)
5. **Validation Review**
- Manual review of any unexpected changes
- Verification of preview framework behavior
### Dependency-Based Ordering Details
#### Foundation First (Tiers 2-4)
- **Tier 2**: Core infrastructure (Database.Implementations, Extensions, Keyframes)
- **Tier 3**: Data models (Jellyfin.Data)
- **Tier 4**: Shared models (MediaBrowser.Model)
**Rationale**: These are referenced by all higher tiers. Must be rock-solid.
#### Infrastructure & Providers (Tiers 5-7)
- **Tier 5**: Common utilities (MediaBrowser.Common)
- **Tier 6**: Database providers (PostgreSQL, SQLite), Naming
- **Tier 7**: Controller abstractions
**Rationale**: Database providers are critical infrastructure requiring extensive testing before business logic.
#### Business Logic (Tiers 8-10)
- **Tier 8**: Business logic, media processing, networking (12 projects)
- **Tier 9**: API layer and business tests (8 projects)
- **Tier 10**: Server implementations (2 projects)
**Rationale**: Business logic depends on stable infrastructure; can parallelize within Tier 8.
#### Applications & Tests (Tiers 11-13)
- **Tier 11**: Main application (Jellyfin.Server)
- **Tier 12**: Integration tests
- **Tier 13**: Final implementation tests
**Rationale**: Applications last; integration tests validate entire stack.
### Parallel vs. Sequential Execution
#### Sequential (Between Tiers)
- **All tiers execute sequentially** - Tier N+1 waits for Tier N completion
- **No exceptions** - even for small tiers
- **Validation between tiers** - ensures stability before proceeding
#### Parallel (Within Tier)
Projects within same tier can execute in parallel:
- **Tier 2** (3 projects): Can parallelize
- **Tier 3** (2 projects): Can parallelize
- **Tier 5** (3 projects): Can parallelize
- **Tier 6** (3 projects): Can parallelize
- **Tier 7** (2 projects): Can parallelize
- **Tier 8** (12 projects): **High parallelism potential** - largest tier
- **Tier 9** (8 projects): Can parallelize (all tests)
- **Tier 10** (2 projects): Can parallelize
- **Tier 12** (2 projects): Can parallelize
**Parallelization Guidelines:**
- Update project files for all tier projects simultaneously
- Run builds in parallel (if resources allow)
- Aggregate results before proceeding to tests
- Test tier as a cohesive unit (not per-project)
### Phase Definitions
The migration consists of **13 phases** (one per tier):
#### Phase 1: Core Infrastructure (Tier 2)
- **Projects**: 3
- **Focus**: Database implementations, extensions, keyframe encoding
- **Validation**: Unit tests in Tier 3
#### Phase 2: Data Layer (Tier 3)
- **Projects**: 2
- **Focus**: Data models, first test validation
- **Validation**: Jellyfin.MediaEncoding.Keyframes.Tests
#### Phase 3: Model Layer (Tier 4)
- **Projects**: 1
- **Focus**: Central model definitions
- **Validation**: Model tests in Tier 5
#### Phase 4: Common Utilities (Tier 5)
- **Projects**: 3
- **Focus**: Common utilities, model validation tests
- **Validation**: Jellyfin.Extensions.Tests, Jellyfin.Model.Tests
#### Phase 5: Database Providers (Tier 6)
- **Projects**: 3
- **Focus**: PostgreSQL, SQLite providers; naming
- **Validation**: Extensive database integration tests (manual + automated)
#### Phase 6: Controller Layer (Tier 7)
- **Projects**: 2
- **Focus**: Controller abstractions, naming tests
- **Validation**: Jellyfin.Naming.Tests
#### Phase 7: Business Logic (Tier 8)
- **Projects**: 12 (largest phase)
- **Focus**: Photos, drawing, networking, media encoding, providers, server infrastructure
- **Validation**: Controller tests + business logic validation
#### Phase 8: API & Tests (Tier 9)
- **Projects**: 8
- **Focus**: Jellyfin.Api and comprehensive test suite for Tier 8
- **Validation**: All Tier 9 tests pass
#### Phase 9: Server Implementation (Tier 10)
- **Projects**: 2
- **Focus**: Emby.Server.Implementations, Jellyfin.Api.Tests
- **Validation**: API tests pass
#### Phase 10: Main Application (Tier 11)
- **Projects**: 1
- **Focus**: Jellyfin.Server (main entry point)
- **Validation**: Application starts and responds
#### Phase 11: Integration Tests (Tier 12)
- **Projects**: 2
- **Focus**: End-to-end integration tests
- **Validation**: All integration tests pass
#### Phase 12: Final Validation (Tier 13)
- **Projects**: 1
- **Focus**: Jellyfin.Server.Implementations.Tests
- **Validation**: Complete solution test suite passes
#### Phase 13: Solution Validation
- **Projects**: All 40 upgraded projects
- **Focus**: Full solution build, all tests, smoke testing
- **Validation**: Comprehensive validation before completion
### Risk Mitigation for Bottom-Up Strategy
#### Early Failure Detection
- Tier 2-4 failures detected before touching 90% of solution
- Database provider issues (Tier 6) caught before business logic
- Test projects throughout enable continuous validation
#### Preview Framework Risks
- Tier 2 upgrade exposes .NET 11.0 preview issues earliest
- Can assess framework stability before committing all projects
- Option to pause/revert if preview proves problematic
#### Incremental Learning
- Early tiers teach team about .NET 11.0 behavior
- Lessons learned applied to later tiers
- Compilation/runtime patterns identified early
#### Staged Deployment
- Can deploy lower tiers to staging environment incrementally
- Early performance/compatibility testing
- Risk distributed across multiple phases vs. single big-bang
### Rollback Strategy
#### Tier-Level Rollback
- If Tier N fails validation:
1. Revert all Tier N project file changes
2. Restore Tier N packages to .NET 9.0 versions
3. Validate Tiers 1-(N-1) still stable
4. Analyze failure, adjust plan
5. Retry Tier N
#### Solution-Level Rollback
- If preview framework proves unstable:
1. Git revert to upgrade branch start
2. Document .NET 11.0 PREVIEW issues
3. Consider alternative target (.NET 10.0 LTS)
### Success Criteria Per Phase
Each phase must achieve:
1. ✅ All projects build without errors
2. ✅ All projects build without warnings
3. ✅ All test projects pass (100% pass rate)
4. ✅ No package dependency conflicts
5. ✅ Code analysis passes
6. ✅ Manual validation complete (for critical tiers)
7. ✅ Performance acceptable (for application tiers)
Only when all criteria met, proceed to next phase.
## Detailed Dependency Analysis
### Dependency Graph Structure
The Jellyfin solution exhibits a **12-level dependency hierarchy** with clear separation between infrastructure, domain, and application layers. The graph follows a bottom-up structure ideal for tier-based migration.
```
Tier 1 (Level 0): Foundation - Analyzer
└─ Jellyfin.CodeAnalysis (netstandard2.0) - NO UPGRADE
Tier 2 (Level 1): Core Infrastructure
├─ Jellyfin.Database.Implementations
├─ Jellyfin.Extensions
└─ Jellyfin.MediaEncoding.Keyframes
Tier 3 (Level 2): Data & Encoding
├─ Jellyfin.Data
└─ Jellyfin.MediaEncoding.Keyframes.Tests
Tier 4 (Level 3): Model Layer
└─ MediaBrowser.Model
Tier 5 (Level 4): Model Tests & Common Layer
├─ Jellyfin.Extensions.Tests
├─ Jellyfin.Model.Tests
└─ MediaBrowser.Common
Tier 6 (Level 5): Domain & Database Providers
├─ Emby.Naming
├─ Jellyfin.Database.Providers.Postgres
└─ Jellyfin.Database.Providers.Sqlite
Tier 7 (Level 6): Controller & Naming Tests
├─ Jellyfin.Naming.Tests
└─ MediaBrowser.Controller
Tier 8 (Level 7): Business Logic & Drawing
├─ Emby.Photos
├─ Jellyfin.Controller.Tests
├─ Jellyfin.Drawing
├─ Jellyfin.Drawing.Skia
├─ Jellyfin.LiveTv
├─ Jellyfin.MediaEncoding.Hls
├─ Jellyfin.Networking
├─ Jellyfin.Server.Implementations
├─ MediaBrowser.LocalMetadata
├─ MediaBrowser.MediaEncoding
├─ MediaBrowser.Providers
└─ MediaBrowser.XbmcMetadata
Tier 9 (Level 8): API & Business Tests
├─ Jellyfin.Api
├─ Jellyfin.Common.Tests
├─ Jellyfin.LiveTv.Tests
├─ Jellyfin.MediaEncoding.Hls.Tests
├─ Jellyfin.MediaEncoding.Tests
├─ Jellyfin.Networking.Tests
├─ Jellyfin.Providers.Tests
└─ Jellyfin.XbmcMetadata.Tests
Tier 10 (Level 9): Server Implementation
├─ Emby.Server.Implementations
└─ Jellyfin.Api.Tests
Tier 11 (Level 10): Main Application
└─ Jellyfin.Server
Tier 12 (Level 11): Integration Tests
├─ Jellyfin.Server.Integration.Tests
└─ Jellyfin.Server.Tests
Tier 13 (Level 12): Final Test Layer
└─ Jellyfin.Server.Implementations.Tests
```
### Tier Grouping Strategy
Based on the Bottom-Up Strategy and dependency analysis, projects are grouped into **13 tiers** for migration:
#### Tier 1: Foundation Analyzer (NO MIGRATION)
- **Jellyfin.CodeAnalysis** (netstandard2.0)
- **Dependencies**: None
- **Used By**: All projects (build-time analyzer)
- **Rationale**: Remains on netstandard2.0 for broad compatibility
#### Tier 2: Core Infrastructure (3 projects)
- **Jellyfin.Database.Implementations**
- **Jellyfin.Extensions**
- **Jellyfin.MediaEncoding.Keyframes**
- **Dependencies**: Only Jellyfin.CodeAnalysis (unchanged)
- **Rationale**: Leaf nodes with no internal dependencies; database and extension infrastructure
#### Tier 3: Data Layer (2 projects)
- **Jellyfin.Data**
- **Jellyfin.MediaEncoding.Keyframes.Tests**
- **Dependencies**: Tier 2 projects only
- **Rationale**: Data models and first test validation point
#### Tier 4: Model Layer (1 project)
- **MediaBrowser.Model**
- **Dependencies**: Tier 2 (Extensions) + Tier 3 (Data)
- **Rationale**: Central model definitions used throughout solution
#### Tier 5: Common Layer (3 projects)
- **Jellyfin.Extensions.Tests**
- **Jellyfin.Model.Tests**
- **MediaBrowser.Common**
- **Dependencies**: Tiers 2-4
- **Rationale**: Common utilities and model validation tests
#### Tier 6: Naming & Database Providers (3 projects)
- **Emby.Naming**
- **Jellyfin.Database.Providers.Postgres**
- **Jellyfin.Database.Providers.Sqlite**
- **Dependencies**: Tiers 2-5
- **Rationale**: Critical database providers requiring extensive testing
#### Tier 7: Controller Layer (2 projects)
- **Jellyfin.Naming.Tests**
- **MediaBrowser.Controller**
- **Dependencies**: Tiers 2-6
- **Rationale**: Controller abstractions; naming validation
#### Tier 8: Business Logic (12 projects)
- **Emby.Photos**
- **Jellyfin.Controller.Tests**
- **Jellyfin.Drawing**
- **Jellyfin.Drawing.Skia**
- **Jellyfin.LiveTv**
- **Jellyfin.MediaEncoding.Hls**
- **Jellyfin.Networking**
- **Jellyfin.Server.Implementations**
- **MediaBrowser.LocalMetadata**
- **MediaBrowser.MediaEncoding**
- **MediaBrowser.Providers**
- **MediaBrowser.XbmcMetadata**
- **Dependencies**: Tiers 2-7
- **Rationale**: Largest tier; business logic, media processing, networking; can parallelize within tier
#### Tier 9: API & Tests (8 projects)
- **Jellyfin.Api**
- **Jellyfin.Common.Tests**
- **Jellyfin.LiveTv.Tests**
- **Jellyfin.MediaEncoding.Hls.Tests**
- **Jellyfin.MediaEncoding.Tests**
- **Jellyfin.Networking.Tests**
- **Jellyfin.Providers.Tests**
- **Jellyfin.XbmcMetadata.Tests**
- **Dependencies**: Tiers 2-8
- **Rationale**: API layer and comprehensive test coverage for Tier 8
#### Tier 10: Server Implementation (2 projects)
- **Emby.Server.Implementations**
- **Jellyfin.Api.Tests**
- **Dependencies**: Tiers 2-9
- **Rationale**: Main server implementation and API validation
#### Tier 11: Main Application (1 project)
- **Jellyfin.Server**
- **Dependencies**: Tiers 2-10
- **Rationale**: Entry point application; depends on all business logic
#### Tier 12: Integration Tests (2 projects)
- **Jellyfin.Server.Integration.Tests**
- **Jellyfin.Server.Tests**
- **Dependencies**: Tier 11 (Jellyfin.Server)
- **Rationale**: End-to-end application validation
#### Tier 13: Final Test Validation (1 project)
- **Jellyfin.Server.Implementations.Tests**
- **Dependencies**: Tier 12 (Integration.Tests)
- **Rationale**: Final validation of server implementations with integration context
### Critical Path Analysis
**Longest Dependency Chain:**
```
Jellyfin.CodeAnalysis (Level 0)
→ Jellyfin.Database.Implementations (Level 1)
→ Jellyfin.Data (Level 2)
→ MediaBrowser.Model (Level 3)
→ MediaBrowser.Common (Level 4)
→ Emby.Naming (Level 5)
→ MediaBrowser.Controller (Level 6)
→ Jellyfin.Server.Implementations (Level 7)
→ Emby.Server.Implementations (Level 9)
→ Jellyfin.Server (Level 10)
→ Jellyfin.Server.Integration.Tests (Level 11)
→ Jellyfin.Server.Implementations.Tests (Level 12)
```
**Length**: 13 projects (12 upgrade steps, excluding CodeAnalysis)
**Implications:**
- Any failure in early tiers blocks all downstream projects
- Database layer (Tiers 2-6) is critical foundation
- Server implementation consolidates most dependencies (Tier 10)
- Test projects enable validation at each tier
### Circular Dependencies
**Status**: ✅ **None detected**
The dependency graph is a **Directed Acyclic Graph (DAG)**, enabling clean bottom-up migration.
### Key Dependency Relationships
#### High-Fan-Out Projects (Used by Many)
1. **MediaBrowser.Model** (Level 3): Used by 21 projects
- Central model definitions
- Must be stable before progressing
2. **MediaBrowser.Controller** (Level 6): Used by 12 projects
- Core controller abstractions
- Critical stabilization point
3. **MediaBrowser.Common** (Level 4): Used by 10 projects
- Common utilities
- Early tier with wide impact
#### High-Fan-In Projects (Depend on Many)
1. **Jellyfin.Server** (Level 10): Depends on 9 direct projects
- Main application entry point
- Consolidates all functionality
2. **Emby.Server.Implementations** (Level 9): Depends on 14 direct projects
- Server implementation layer
- Complex integration point
3. **Jellyfin.Server.Implementations** (Level 7): Depends on 6 direct projects
- Server infrastructure
- Database and core implementation
### Between-Tier Dependencies
Each tier depends **only** on lower tiers (strict bottom-up):
- **Tier 2** → Tier 1 (CodeAnalysis only)
- **Tier 3** → Tiers 1-2
- **Tier 4** → Tiers 1-3
- **Tier 5** → Tiers 1-4
- **Tier 6** → Tiers 1-5
- **Tier 7** → Tiers 1-6
- **Tier 8** → Tiers 1-7
- **Tier 9** → Tiers 1-8
- **Tier 10** → Tiers 1-9
- **Tier 11** → Tiers 1-10
- **Tier 12** → Tiers 1-11
- **Tier 13** → Tiers 1-12
**No cross-tier or reverse dependencies** ensure clean migration flow.
## Project-by-Project Plans
### Overview
This section provides detailed migration plans for each project, organized by tier. Each project includes:
- Current and target state
- Migration steps
- Package updates
- Expected breaking changes
- Code modifications
- Testing strategy
- Validation checklist
---
### Tier 1: Foundation Analyzer (NO MIGRATION)
#### Jellyfin.CodeAnalysis
**Current State**: netstandard2.0 (Roslyn analyzer)
**Target State**: netstandard2.0 (UNCHANGED)
**Migration**: None required - remains on netstandard2.0 for broad compatibility
---
### Tier 2: Core Infrastructure
#### Overview
**Projects**: 3
**Complexity**: Medium
**Risk**: High (first preview framework exposure)
**Effort**: Medium
This tier establishes the foundation infrastructure: database implementations, extension utilities, and media encoding keyframe support. As the first tier to migrate, it serves as the **early warning system** for .NET 11.0 preview issues.
---
#### Jellyfin.Database.Implementations
**Current State**:
- **Framework**: .NET 9.0
- **Type**: Class Library
- **Dependencies**: Jellyfin.CodeAnalysis (unchanged)
- **Used By**: 6 projects (Data layer, database providers, server implementations)
- **Packages**: Microsoft.EntityFrameworkCore 11.0.0-preview.1 (already upgraded)
- **Risk Level**: High (foundation for all data access)
**Target State**:
- **Framework**: .NET 11.0
- **Type**: Class Library
- **Dependencies**: No changes
- **Package Changes**: None required (already on .NET 11.0-compatible versions)
**Migration Steps**:
1. **Prerequisites**
- ✅ Jellyfin.CodeAnalysis remains unchanged (netstandard2.0)
- ✅ .NET 11.0 SDK installed and verified
- ✅ Backup current solution state
2. **Framework Update**
- Update `Jellyfin.Database.Implementations.csproj`:
```xml
net11.0
```
- No other project file changes needed
3. **Package Updates**
- **All packages already compatible** - no updates required:
- Microsoft.EntityFrameworkCore: 11.0.0-preview.1 ✅
- Microsoft.EntityFrameworkCore.Relational: 11.0.0-preview.1 ✅
- Microsoft.EntityFrameworkCore.Design: 11.0.0-preview.1 ✅
4. **Expected Breaking Changes**
- ✅ **None identified** by assessment
- ⚠️ **Monitor for**: EF Core 11.0 preview query translation changes
- ⚠️ **Monitor for**: Database provider behavior changes
5. **Code Modifications**
- **Expected**: None required
- **Potential**:
- EF Core API changes (preview-specific)
- Query translation adjustments
- Migration compatibility
6. **Testing Strategy**
- **Build Validation**:
- Project builds without errors ✅
- Zero warnings target ✅
- Code analysis passes ✅
- **Dependency Validation**:
- NuGet restore successful ✅
- No package conflicts ✅
- **Functional Testing**:
- Database context initialization ✅
- Basic CRUD operations (deferred to Tier 6 with providers)
- **Performance Baseline**:
- Establish .NET 11.0 build performance metrics
- Compare against .NET 9.0 baseline
7. **Validation Checklist**
- [ ] Project file updated to net11.0
- [ ] Build succeeds without errors
- [ ] Build succeeds without warnings
- [ ] NuGet packages restore successfully
- [ ] No dependency conflicts
- [ ] Code analysis passes (StyleCop, IDisposableAnalyzers, etc.)
- [ ] Database context classes compile
- [ ] No compiler warnings about obsolete APIs
- [ ] EF Core design-time tools work (if applicable)
---
#### Jellyfin.Extensions
**Current State**:
- **Framework**: .NET 9.0
- **Type**: Class Library
- **Dependencies**: Jellyfin.CodeAnalysis (unchanged)
- **Used By**: MediaBrowser.Model, Jellyfin.Extensions.Tests
- **Packages**: Minimal (mostly BCL)
- **Risk Level**: Low (simple utility library)
**Target State**:
- **Framework**: .NET 11.0
- **Type**: Class Library
- **Dependencies**: No changes
- **Package Changes**: None required
**Migration Steps**:
1. **Prerequisites**
- ✅ .NET 11.0 SDK available
- ✅ No external package dependencies to validate
2. **Framework Update**
- Update `Jellyfin.Extensions.csproj`:
```xml
net11.0
```
3. **Package Updates**
- **None required** - uses BCL only
4. **Expected Breaking Changes**
- ✅ **None expected**
- Simple extension methods and utilities
- Minimal BCL surface area
5. **Code Modifications**
- **Expected**: None
- **Potential**: None anticipated
6. **Testing Strategy**
- **Build Validation**:
- Build without errors/warnings ✅
- Code analysis passes ✅
- **Unit Testing**:
- Deferred to Tier 5 (Jellyfin.Extensions.Tests)
- **API Compatibility**:
- Extension methods compile without changes ✅
- No obsolete API usage ✅
7. **Validation Checklist**
- [ ] Project file updated to net11.0
- [ ] Build succeeds without errors
- [ ] Build succeeds without warnings
- [ ] No package dependencies to update
- [ ] Extension methods compile cleanly
- [ ] Code analysis passes
- [ ] No breaking changes in BCL APIs used
---
#### Jellyfin.MediaEncoding.Keyframes
**Current State**:
- **Framework**: .NET 9.0
- **Type**: Class Library
- **Dependencies**: Jellyfin.CodeAnalysis (unchanged)
- **Used By**: MediaBrowser.Controller, Jellyfin.MediaEncoding.Hls, test projects
- **Packages**: Minimal
- **Risk Level**: Low (specialized library)
**Target State**:
- **Framework**: .NET 11.0
- **Type**: Class Library
- **Dependencies**: No changes
- **Package Changes**: None required
**Migration Steps**:
1. **Prerequisites**
- ✅ .NET 11.0 SDK available
- ✅ Understanding of keyframe extraction functionality
2. **Framework Update**
- Update `Jellyfin.MediaEncoding.Keyframes.csproj`:
```xml
net11.0
```
3. **Package Updates**
- **None required** - minimal external dependencies
4. **Expected Breaking Changes**
- ✅ **None expected**
- Specialized media encoding logic
- Limited BCL interaction
5. **Code Modifications**
- **Expected**: None
- **Potential**:
- I/O API changes (if file operations change)
- Stream handling adjustments (unlikely)
6. **Testing Strategy**
- **Build Validation**:
- Build without errors/warnings ✅
- Code analysis passes ✅
- **Unit Testing**:
- Deferred to Tier 3 (Jellyfin.MediaEncoding.Keyframes.Tests)
- **Functional Validation**:
- Keyframe extraction logic compiles ✅
- FFmpeg integration interfaces unchanged ✅
7. **Validation Checklist**
- [ ] Project file updated to net11.0
- [ ] Build succeeds without errors
- [ ] Build succeeds without warnings
- [ ] No external package updates needed
- [ ] Media encoding logic compiles cleanly
- [ ] Code analysis passes
- [ ] FFmpeg integration interfaces compatible
---
### Tier 2: Batch Operations
Since all 3 projects in Tier 2 have similar migration profiles, they can be **upgraded simultaneously**:
#### Batch Update Process
1. **Project File Updates** (Single operation)
- Update all 3 .csproj files to `net11.0`
- Commit: "Upgrade Tier 2 projects to .NET 11.0"
2. **Build Validation** (Parallel)
- Build all 3 projects
- Check for errors/warnings
- Verify code analysis passes
3. **Package Restoration** (Parallel)
- Restore NuGet packages for all projects
- Verify no conflicts
4. **Integration Check**
- Build solution to ensure Tier 2 projects compile together
- Verify dependent projects (still on .NET 9.0) can still reference Tier 2
---
### Tier 2: Completion Criteria
Before proceeding to Tier 3, **all** of the following must be met:
1. ✅ **Build Success**
- All 3 projects build without errors
- All 3 projects build without warnings (zero-warning target)
2. ✅ **Package Health**
- All packages restored successfully
- No package dependency conflicts
- EF Core design-time tools functional (Database.Implementations)
3. ✅ **Code Quality**
- Code analysis passes (StyleCop, analyzers)
- No compiler warnings about obsolete APIs
- No new code analysis violations introduced
4. ✅ **Preview Framework Assessment**
- .NET 11.0 SDK functional
- No blocking preview framework issues discovered
- Build performance acceptable
5. ✅ **Documentation**
- Any issues encountered documented
- Workarounds noted (if applicable)
- Lessons learned recorded for later tiers
**Decision Point**: If Tier 2 shows critical .NET 11.0 preview issues, **PAUSE** migration and assess viability.
---
### Tier 2: Package Update Reference
| Package | Current | Target | Notes |
|---------|---------|--------|-------|
| Microsoft.EntityFrameworkCore | 11.0.0-preview.1 | 11.0.0-preview.1 | Already compatible ✅ |
| Microsoft.EntityFrameworkCore.Relational | 11.0.0-preview.1 | 11.0.0-preview.1 | Already compatible ✅ |
| Microsoft.EntityFrameworkCore.Design | 11.0.0-preview.1 | 11.0.0-preview.1 | Already compatible ✅ |
**All packages already at .NET 11.0-compatible versions - no package updates required for Tier 2.**
---
### Tier 3: Data Layer
#### Overview
**Projects**: 2
**Complexity**: Low
**Risk**: Low
**Effort**: Low
Data models and first test validation point. Straightforward migration with immediate test feedback.
---
#### Jellyfin.Data
**Current State**: .NET 9.0 Class Library
**Target State**: .NET 11.0 Class Library
**Dependencies**: Jellyfin.Database.Implementations (Tier 2), Jellyfin.CodeAnalysis
**Risk**: Low (data models)
**Migration Steps**:
1. Update project file: `net11.0`
2. No package updates required (all compatible)
3. Build and validate data model classes compile cleanly
**Expected Changes**: None
**Validation**:
- [ ] Build succeeds without errors/warnings
- [ ] Data entity classes compile
- [ ] EF Core model configuration unchanged
- [ ] Used successfully by MediaBrowser.Model (Tier 4)
---
#### Jellyfin.MediaEncoding.Keyframes.Tests
**Current State**: .NET 9.0 Test Project (xUnit)
**Target State**: .NET 11.0 Test Project
**Dependencies**: Jellyfin.MediaEncoding.Keyframes (Tier 2), Jellyfin.CodeAnalysis
**Risk**: Low (test project)
**Migration Steps**:
1. Update project file: `net11.0`
2. No package updates required:
- xUnit 2.9.3 ✅
- xunit.runner.visualstudio 2.8.2 ✅
- Microsoft.NET.Test.Sdk 18.0.1 ✅
3. Run tests to validate Tier 2 (MediaEncoding.Keyframes)
**Expected Changes**: None
**Validation**:
- [ ] Build succeeds without errors/warnings
- [ ] All tests run successfully
- [ ] All tests pass (100% pass rate)
- [ ] Test runner compatible with .NET 11.0
- [ ] Tier 2 keyframes functionality validated
**Tier 3 Completion Criteria**:
1. Both projects build without errors/warnings
2. Jellyfin.MediaEncoding.Keyframes.Tests: 100% tests pass
3. No package conflicts
4. Tier 2 functionality validated through tests
---
### Tier 4: Model Layer
#### Overview
**Projects**: 1
**Complexity**: Medium (high fan-out)
**Risk**: Medium
**Effort**: Low
Central model definitions used by 21 projects throughout solution. Critical stability point.
---
#### MediaBrowser.Model
**Current State**: .NET 9.0 Class Library
**Target State**: .NET 11.0 Class Library
**Dependencies**: Jellyfin.Data (Tier 3), Jellyfin.Extensions (Tier 2), Jellyfin.CodeAnalysis
**Used By**: 21 projects (most of solution)
**Risk**: Medium (high fan-out = wide impact)
**Migration Steps**:
1. Update project file: `net11.0`
2. No package updates required (compatible packages)
3. Build and validate model classes compile cleanly
**Expected Changes**: None
**Key Focus Areas**:
- DTO models for API serialization
- Query models for filtering/paging
- Configuration models
- Enum definitions
**Validation**:
- [ ] Build succeeds without errors/warnings
- [ ] All model classes compile cleanly
- [ ] No JSON serialization API changes
- [ ] Enum definitions unchanged
- [ ] Configuration model binding compatible
- [ ] DTOs serialize/deserialize correctly (tested in Tier 5)
**Special Considerations**:
- **High Fan-Out**: 21 projects depend on this
- **API Surface**: Models used in REST API contracts
- **Serialization**: JSON serialization must remain compatible
**Tier 4 Completion Criteria**:
1. Project builds without errors/warnings
2. All model classes compile without changes
3. No breaking changes in public API surface
4. Ready for validation by Tier 5 tests
---
### Tier 5: Common Utilities & Model Tests
#### Overview
**Projects**: 3
**Complexity**: Low
**Risk**: Low
**Effort**: Low
Common utilities and validation tests for Tier 4 models. Provides test coverage for central models.
---
#### MediaBrowser.Common
**Current State**: .NET 9.0 Class Library
**Target State**: .NET 11.0 Class Library
**Dependencies**: MediaBrowser.Model (Tier 4), Jellyfin.CodeAnalysis
**Used By**: 10 projects
**Risk**: Low (utility library)
**Migration Steps**:
1. Update project file: `net11.0`
2. Package updates - All compatible:
- Microsoft.Extensions.DependencyInjection: 11.0.0-preview.1 ✅
- Microsoft.Extensions.Logging: 11.0.0-preview.1 ✅
- Microsoft.Extensions.Http: 11.0.0-preview.1 ✅
3. Build and validate common utilities
**Expected Changes**: None
**Validation**:
- [ ] Build succeeds without errors/warnings
- [ ] Dependency injection helpers compile
- [ ] Logging utilities compatible
- [ ] HTTP client utilities functional
- [ ] Configuration helpers unchanged
---
#### Jellyfin.Extensions.Tests
**Current State**: .NET 9.0 Test Project (xUnit)
**Target State**: .NET 11.0 Test Project
**Dependencies**: MediaBrowser.Model (Tier 4), Jellyfin.Extensions (Tier 2), Jellyfin.CodeAnalysis
**Risk**: Low (test project)
**Migration Steps**:
1. Update project file: `net11.0`
2. No package updates required (test packages compatible)
3. Run tests to validate Tier 2 extensions
**Expected Changes**: None
**Validation**:
- [ ] Build succeeds
- [ ] All tests run
- [ ] All tests pass (100%)
- [ ] Tier 2 extensions validated
---
#### Jellyfin.Model.Tests
**Current State**: .NET 9.0 Test Project (xUnit)
**Target State**: .NET 11.0 Test Project
**Dependencies**: MediaBrowser.Model (Tier 4), Jellyfin.CodeAnalysis
**Risk**: Low (test project)
**Migration Steps**:
1. Update project file: `net11.0`
2. No package updates required (test packages compatible)
3. Run tests to validate Tier 4 models
**Expected Changes**: None
**Validation**:
- [ ] Build succeeds
- [ ] All tests run
- [ ] All tests pass (100%)
- [ ] Tier 4 models validated (DTOs, serialization, configuration)
**Tier 5 Completion Criteria**:
1. All 3 projects build without errors/warnings
2. Both test projects: 100% tests pass
3. Tier 2 extensions validated
4. Tier 4 models validated
5. Common utilities functional
6. No package conflicts
---
### Tier 6: Database Providers & Naming ⚠️ CRITICAL TIER
#### Overview
**Projects**: 3
**Complexity**: High
**Risk**: CRITICAL
**Effort**: High
**This is the most critical tier in the migration.** Database providers are the foundation for all data access throughout Jellyfin. Both PostgreSQL and SQLite EF Core providers are preview versions for .NET 11.0, requiring extensive validation.
**🛑 GO/NO-GO DECISION POINT**: If Tier 6 fails validation, the entire migration may need to pause or revert.
---
#### Emby.Naming
**Current State**: .NET 9.0 Class Library
**Target State**: .NET 11.0 Class Library
**Dependencies**: MediaBrowser.Model (Tier 4), MediaBrowser.Common (Tier 5), Jellyfin.CodeAnalysis
**Used By**: MediaBrowser.Controller (Tier 7), Emby.Server.Implementations, Jellyfin.Naming.Tests (Tier 7)
**Risk**: Low (naming logic)
**Migration Steps**:
1. Update project file: `net11.0`
2. No package updates required
3. Build and validate naming logic
**Expected Changes**: None
**Validation**:
- [ ] Build succeeds without errors/warnings
- [ ] Naming pattern logic compiles
- [ ] File/folder naming utilities unchanged
- [ ] Validated by Jellyfin.Naming.Tests (Tier 7)
---
#### Jellyfin.Database.Providers.Postgres ⚠️ CRITICAL
**Current State**: .NET 9.0 Class Library
**Target State**: .NET 11.0 Class Library
**Dependencies**: MediaBrowser.Common (Tier 5), Jellyfin.Database.Implementations (Tier 2), Jellyfin.CodeAnalysis
**Used By**: Jellyfin.Server (Tier 11), Jellyfin.Server.Implementations (Tier 8)
**Risk**: **CRITICAL** (primary database provider for Jellyfin)
**Package Status**:
- **Npgsql.EntityFrameworkCore.PostgreSQL**: 11.0.0-preview.1 ✅ (already upgraded)
- **Status**: Preview provider for preview framework
**Migration Steps**:
1. **Prerequisites**
- PostgreSQL database server available for testing
- Test database with representative Jellyfin schema
- Baseline performance metrics from .NET 9.0
- Connection string configuration ready
2. **Framework Update**
- Update project file: `net11.0`
- No package updates required (already on preview)
3. **Expected Breaking Changes**
- ✅ **None identified** in assessment
- ⚠️ **Potential**: EF Core 11.0 query translation changes
- ⚠️ **Potential**: Npgsql provider-specific behavior changes
- ⚠️ **Potential**: Connection pooling behavior
- ⚠️ **Potential**: Transaction handling differences
4. **Code Modifications**
- **Expected**: None
- **Potential**:
- DbContext configuration adjustments
- Connection string format changes
- Provider-specific query hints
- Migration compatibility fixes
5. **Testing Strategy** (EXTENSIVE)
**Build Validation**:
- [ ] Project builds without errors
- [ ] Project builds without warnings
- [ ] Code analysis passes
- [ ] DbContext registration compiles
**Database Connection Tests**:
- [ ] Connection string parsing successful
- [ ] Database connection established
- [ ] Connection pooling functional
- [ ] SSL/TLS connections work (if applicable)
- [ ] Connection timeouts handled correctly
**Migration Tests**:
- [ ] Existing migrations still valid
- [ ] Can apply migrations to empty database
- [ ] Can upgrade from previous schema version
- [ ] Migration history table accessible
- [ ] No schema drift detected
**CRUD Operations**:
- [ ] INSERT operations successful
- [ ] SELECT queries return correct data
- [ ] UPDATE operations modify records
- [ ] DELETE operations remove records
- [ ] Bulk operations functional
- [ ] Concurrent operations safe
**Query Translation**:
- [ ] LINQ queries translate to SQL correctly
- [ ] Complex queries (joins, aggregations) work
- [ ] Navigation properties load correctly
- [ ] Explicit loading functional
- [ ] Eager loading (Include) functional
- [ ] Lazy loading compatible (if enabled)
**Transaction Tests**:
- [ ] Explicit transactions work
- [ ] Rollback functional
- [ ] Nested transactions (if used)
- [ ] Distributed transactions (if used)
- [ ] Transaction isolation levels correct
**Performance Tests**:
- [ ] Query performance comparable to .NET 9.0 baseline
- [ ] Insert/update performance acceptable
- [ ] Bulk operation performance
- [ ] Connection pool performance
- [ ] No memory leaks detected
- [ ] No excessive allocations
**Concurrency Tests**:
- [ ] Concurrent reads safe
- [ ] Concurrent writes safe
- [ ] Optimistic concurrency functional
- [ ] Pessimistic locking works (if used)
- [ ] Deadlock handling correct
**Edge Cases**:
- [ ] NULL value handling
- [ ] Large result sets
- [ ] Long-running queries
- [ ] Connection drops handled
- [ ] Database restart recovery
6. **Validation Checklist**
- [ ] All connection tests pass
- [ ] All migration tests pass
- [ ] All CRUD tests pass
- [ ] All query translation tests pass
- [ ] All transaction tests pass
- [ ] Performance within acceptable range (<10% regression)
- [ ] Concurrency tests pass
- [ ] Edge case tests pass
- [ ] No critical issues detected
7. **Performance Baseline Comparison**
- Document query performance vs. .NET 9.0
- Compare connection pool behavior
- Measure memory usage
- Track any regressions
**Contingency Plans**:
- **If connection issues**: Check Npgsql preview release notes; report bug upstream
- **If query translation fails**: Rewrite queries or wait for provider fix
- **If performance degrades >20%**: Profile and optimize or consider blocking issue
- **If critical bugs**: May need to pause migration until Npgsql fix available
---
#### Jellyfin.Database.Providers.Sqlite ⚠️ CRITICAL
**Current State**: .NET 9.0 Class Library
**Target State**: .NET 11.0 Class Library
**Dependencies**: MediaBrowser.Common (Tier 5), Jellyfin.Database.Implementations (Tier 2), Jellyfin.CodeAnalysis
**Used By**: Jellyfin.Server (Tier 11)
**Risk**: **CRITICAL** (alternative database provider for Jellyfin)
**Package Status**:
- **Microsoft.EntityFrameworkCore.Sqlite**: 11.0.0-preview.1 ✅ (already upgraded)
- **Microsoft.Data.Sqlite**: 11.0.0-preview.1 ✅ (already upgraded)
- **Status**: Preview provider for preview framework
**Migration Steps**:
1. **Prerequisites**
- SQLite database file available for testing
- Test database with representative Jellyfin schema
- Baseline performance metrics from .NET 9.0
- Write permissions verified
2. **Framework Update**
- Update project file: `net11.0`
- No package updates required (already on preview)
3. **Expected Breaking Changes**
- ✅ **None identified** in assessment
- ⚠️ **Potential**: EF Core 11.0 query translation changes
- ⚠️ **Potential**: SQLite provider-specific behavior changes
- ⚠️ **Potential**: File locking behavior
- ⚠️ **Potential**: WAL mode changes
4. **Code Modifications**
- **Expected**: None
- **Potential**:
- DbContext configuration adjustments
- Connection string format changes
- Pragmas or SQLite-specific settings
- Migration compatibility fixes
5. **Testing Strategy** (EXTENSIVE)
**Build Validation**:
- [ ] Project builds without errors
- [ ] Project builds without warnings
- [ ] Code analysis passes
- [ ] DbContext registration compiles
**Database File Tests**:
- [ ] Database file created successfully
- [ ] Database file opened correctly
- [ ] File locking works correctly
- [ ] WAL mode functional (if used)
- [ ] File permissions respected
- [ ] Backup/restore operations work
**Migration Tests**:
- [ ] Existing migrations still valid
- [ ] Can apply migrations to empty database
- [ ] Can upgrade from previous schema version
- [ ] Migration history table accessible
- [ ] No schema drift detected
**CRUD Operations**:
- [ ] INSERT operations successful
- [ ] SELECT queries return correct data
- [ ] UPDATE operations modify records
- [ ] DELETE operations remove records
- [ ] Bulk operations functional
- [ ] Concurrent operations safe
**Query Translation**:
- [ ] LINQ queries translate to SQL correctly
- [ ] Complex queries (joins, aggregations) work
- [ ] Navigation properties load correctly
- [ ] Explicit loading functional
- [ ] Eager loading (Include) functional
- [ ] SQLite-specific SQL features work
**Transaction Tests**:
- [ ] Explicit transactions work
- [ ] Rollback functional
- [ ] Nested transactions (if used)
- [ ] Transaction isolation correct
**Performance Tests**:
- [ ] Query performance comparable to .NET 9.0 baseline
- [ ] Insert/update performance acceptable
- [ ] Bulk operation performance
- [ ] File I/O performance
- [ ] No memory leaks detected
- [ ] Database size remains reasonable
**Concurrency Tests**:
- [ ] Concurrent reads safe
- [ ] Concurrent writes safe (within SQLite limits)
- [ ] File locking prevents corruption
- [ ] Busy timeout handling works
**Edge Cases**:
- [ ] NULL value handling
- [ ] Large result sets
- [ ] Long-running queries
- [ ] Database corruption recovery (if applicable)
- [ ] Disk full scenarios handled
6. **Validation Checklist**
- [ ] All file operation tests pass
- [ ] All migration tests pass
- [ ] All CRUD tests pass
- [ ] All query translation tests pass
- [ ] All transaction tests pass
- [ ] Performance within acceptable range (<10% regression)
- [ ] Concurrency tests pass
- [ ] Edge case tests pass
- [ ] No critical issues detected
7. **Performance Baseline Comparison**
- Document query performance vs. .NET 9.0
- Compare file I/O behavior
- Measure database file size
- Track any regressions
**Contingency Plans**:
- **If file locking issues**: Check Microsoft.Data.Sqlite preview release notes
- **If query translation fails**: Rewrite queries or wait for provider fix
- **If performance degrades >20%**: Profile and optimize or consider blocking issue
- **If critical bugs**: May need to pause migration until EF Core Sqlite fix available
---
### Tier 6: Integration Testing
After all 3 projects migrate, perform **cross-provider validation**:
#### Database Provider Integration Tests
1. **Dual-Provider Tests**
- [ ] Can switch between PostgreSQL and SQLite configurations
- [ ] Same queries work on both providers
- [ ] Schema migrations compatible across providers
- [ ] Data integrity maintained across providers
2. **Real-World Scenario Tests**
- [ ] User authentication/authorization queries
- [ ] Media library metadata queries
- [ ] Playback session tracking
- [ ] User preferences and settings
- [ ] Search and filtering operations
3. **Load Testing**
- [ ] Concurrent user simulations
- [ ] Large library operations (10k+ items)
- [ ] Sustained query load
- [ ] Memory usage under load
4. **Failure Recovery**
- [ ] Database connection drop recovery
- [ ] Transaction rollback on errors
- [ ] Database restart handling
- [ ] Corrupted data detection
---
### Tier 6: Completion Criteria (STRICT)
🛑 **This tier has the STRICTEST completion criteria.** Do not proceed to Tier 7 unless ALL criteria met:
1. ✅ **Build Success**
- All 3 projects build without errors
- All 3 projects build without warnings
2. ✅ **Database Connection**
- PostgreSQL provider connects successfully
- SQLite provider connects successfully
- Connection pooling functional for both
3. ✅ **Migration Compatibility**
- All existing migrations apply successfully
- No schema drift detected
- Migration history intact
4. ✅ **CRUD Operations**
- All CRUD tests pass (100%) for both providers
- Concurrency tests pass
- Transaction tests pass
5. ✅ **Query Translation**
- LINQ queries translate correctly
- Complex queries work
- Navigation loading functional
6. ✅ **Performance Acceptable**
- Query performance: <10% regression vs. .NET 9.0
- Connection performance: Comparable to baseline
- Memory usage: No significant increase
- No memory leaks detected
7. ✅ **Integration Tests**
- Dual-provider tests pass
- Real-world scenario tests pass
- Load tests pass (within acceptable limits)
- Failure recovery tests pass
8. ✅ **Manual Validation**
- Senior engineer review of provider behavior
- Database administrator verification (for PostgreSQL)
- Sign-off on performance metrics
9. ✅ **Documentation**
- All issues encountered documented
- Performance baselines recorded
- Known limitations documented
- Contingency plans ready
**🛑 DECISION POINT**: If **any** critical issues detected in Tier 6, **PAUSE** migration:
- **Option A**: Report issues to Npgsql/EF Core teams; wait for fixes
- **Option B**: Implement workarounds (if feasible)
- **Option C**: Revert migration; target .NET 10.0 LTS instead
- **Option D**: Continue with documented risks (ONLY if non-critical)
**Tier 6 is the primary risk gate. Proceed to Tier 7 only with high confidence in database provider stability.**
---
### Tier 7: Controller Layer
#### Overview
**Projects**: 2 (Jellyfin.Naming.Tests, MediaBrowser.Controller)
**Complexity**: Medium
**Risk**: Medium
**Effort**: Medium
Controller abstractions and naming validation. MediaBrowser.Controller has high fan-out (12 projects depend on it).
#### Quick Migration Profile
**Both Projects**:
- Update to `net11.0`
- No package updates required (all compatible)
- Build and run tests
**MediaBrowser.Controller**:
- **Risk**: Medium (high fan-out)
- **Dependencies**: Tiers 2-6
- **Used By**: 12 projects (business logic tier)
- **Focus**: Controller abstractions, interfaces for repositories/services
- **Validation**: Jellyfin.Controller.Tests (Tier 8)
**Jellyfin.Naming.Tests**:
- **Risk**: Low (test project)
- **Validates**: Emby.Naming (Tier 6)
- **Expected**: 100% tests pass
**Tier 7 Completion Criteria**:
1. Both projects build without errors/warnings
2. Jellyfin.Naming.Tests: 100% pass rate
3. MediaBrowser.Controller public API unchanged
4. Ready for Tier 8 business logic
---
### Tier 8: Business Logic ⚡ LARGEST TIER
#### Overview
**Projects**: 12 (largest tier)
**Complexity**: High
**Risk**: High
**Effort**: High
This tier contains most of Jellyfin's business logic: media processing, networking, providers, drawing, and server infrastructure. **High parallelization potential** within tier.
#### Project Grouping for Parallel Execution
**Group A: Media Processing (3 projects)**
- Emby.Photos
- MediaBrowser.MediaEncoding
- Jellyfin.MediaEncoding.Hls
**Group B: Drawing & Graphics (2 projects)**
- Jellyfin.Drawing
- Jellyfin.Drawing.Skia
**Group C: Business Services (4 projects)**
- Jellyfin.LiveTv
- Jellyfin.Networking
- MediaBrowser.Providers
- MediaBrowser.XbmcMetadata
**Group D: Metadata & Server Infrastructure (3 projects)**
- MediaBrowser.LocalMetadata
- Jellyfin.Server.Implementations
- Jellyfin.Controller.Tests
---
#### Group A: Media Processing
##### Emby.Photos
- **Risk**: Medium (image processing)
- **Dependencies**: MediaBrowser.Model, MediaBrowser.Controller
- **Focus**: Photo library management
- **Validation**: Build + integration tests
##### MediaBrowser.MediaEncoding
- **Risk**: High (FFmpeg integration)
- **Packages**: No updates needed
- **Focus**: Video/audio transcoding, FFmpeg process management
- **Key Tests**:
- [ ] FFmpeg process spawning works
- [ ] Stream handling functional
- [ ] Transcoding profiles correct
- [ ] Process cleanup on abort
##### Jellyfin.MediaEncoding.Hls
- **Risk**: Medium (HLS streaming)
- **Dependencies**: MediaBrowser.Controller, Jellyfin.MediaEncoding.Keyframes
- **Focus**: HLS playlist generation, segmentation
- **Key Tests**:
- [ ] Manifest generation correct
- [ ] Segment timing accurate
- [ ] Playlist updates work
---
#### Group B: Drawing & Graphics
##### Jellyfin.Drawing
- **Risk**: Medium (graphics operations)
- **Dependencies**: MediaBrowser.Model, MediaBrowser.Common, MediaBrowser.Controller
- **Focus**: Image operations, thumbnail generation
- **Key Tests**:
- [ ] Image loading/saving works
- [ ] Thumbnail generation functional
- [ ] Image format conversions
##### Jellyfin.Drawing.Skia
- **Risk**: High (native library interop)
- **Packages**:
- SkiaSharp 3.116.1 ✅
- SkiaSharp.HarfBuzz 3.116.1 ✅
- SkiaSharp.NativeAssets.Linux 3.116.1 ✅
- HarfBuzzSharp.NativeAssets.Linux 8.3.1.1 ✅
- **Focus**: SkiaSharp-based image processing
- **Critical Tests**:
- [ ] SkiaSharp native libraries load
- [ ] Image processing operations work
- [ ] Font rendering functional
- [ ] Cross-platform compatibility (Linux primary)
- [ ] No memory leaks in native interop
- **Contingency**: If SkiaSharp issues, check for .NET 11.0-specific native library versions
---
#### Group C: Business Services
##### Jellyfin.LiveTv
- **Risk**: Medium (Live TV functionality)
- **Dependencies**: MediaBrowser.Model, MediaBrowser.Common, MediaBrowser.Controller
- **Focus**: Live TV guide, recording management
- **Tests**: Jellyfin.LiveTv.Tests (Tier 9)
##### Jellyfin.Networking
- **Risk**: Medium (network operations)
- **Dependencies**: MediaBrowser.Common, MediaBrowser.Controller
- **Focus**: Network discovery, DLNA, SSDP
- **Key Tests**:
- [ ] Network interface detection
- [ ] DLNA device discovery
- [ ] Socket operations
- [ ] UDP/TCP communication
- **Tests**: Jellyfin.Networking.Tests (Tier 9)
##### MediaBrowser.Providers
- **Risk**: Medium (metadata providers)
- **Dependencies**: MediaBrowser.Model, MediaBrowser.Controller
- **Focus**: Metadata fetching from external sources (TMDb, MusicBrainz, etc.)
- **Packages**:
- TMDbLib 2.3.0 ✅
- MetaBrainz.MusicBrainz 8.0.1 ✅
- **Tests**: Jellyfin.Providers.Tests (Tier 9)
##### MediaBrowser.XbmcMetadata
- **Risk**: Low (metadata parsing)
- **Dependencies**: MediaBrowser.Model, MediaBrowser.Controller
- **Focus**: NFO file parsing/writing
- **Tests**: Jellyfin.XbmcMetadata.Tests (Tier 9)
---
#### Group D: Metadata & Server Infrastructure
##### MediaBrowser.LocalMetadata
- **Risk**: Low (local metadata)
- **Dependencies**: MediaBrowser.Model, MediaBrowser.Controller
- **Focus**: Local metadata file operations
##### Jellyfin.Server.Implementations
- **Risk**: High (server infrastructure)
- **Dependencies**: 6 direct dependencies (Jellyfin.Database.Providers.Postgres, Jellyfin.Data, MediaBrowser.Model, MediaBrowser.Controller, Jellyfin.Database.Implementations)
- **Focus**: Server core implementations, dependency injection, configuration
- **Key Areas**:
- Database integration (uses Tier 6 providers)
- Configuration management
- Service registration
- Plugin infrastructure
- **Tests**: Jellyfin.Server.Implementations.Tests (Tier 13)
##### Jellyfin.Controller.Tests
- **Risk**: Low (test project)
- **Validates**: MediaBrowser.Controller (Tier 7)
- **Expected**: 100% tests pass
---
### Tier 8: Batch Migration Strategy
Due to 12 projects, **use phased approach within tier**:
#### Phase 8A: Update All Project Files (Single Commit)
- Update all 12 .csproj files to `net11.0`
- Commit: "Upgrade Tier 8 projects to .NET 11.0"
#### Phase 8B: Build Validation (Parallel by Group)
- Build Group A (Media Processing)
- Build Group B (Drawing & Graphics)
- Build Group C (Business Services)
- Build Group D (Metadata & Infrastructure)
- Fix any compilation errors
#### Phase 8C: Integration Testing
- Run Jellyfin.Controller.Tests (validates Tier 7)
- Integration test between groups
- Validate SkiaSharp native libraries (Group B)
- Validate FFmpeg integration (Group A)
- Validate networking operations (Group C)
---
### Tier 8: Completion Criteria
1. ✅ **Build Success**
- All 12 projects build without errors
- All 12 projects build without warnings
2. ✅ **Package Health**
- All packages restored
- No conflicts
- SkiaSharp native libraries load successfully
3. ✅ **Group Validation**
- **Group A**: FFmpeg operations functional; HLS generation works
- **Group B**: SkiaSharp operations successful; image processing works
- **Group C**: Network operations functional; metadata providers work
- **Group D**: Server infrastructure compiles; controller tests pass
4. ✅ **Critical Tests**
- Jellyfin.Controller.Tests: 100% pass
- Native library interop validated (SkiaSharp)
- Process management validated (FFmpeg)
- Network operations validated
5. ✅ **Performance**
- Image processing: Comparable to .NET 9.0
- Transcoding: No significant regression
- Network operations: Acceptable latency
**Tier 8 represents majority of application functionality. Thorough validation required before proceeding.**
---
### Tier 9: API & Tests
#### Overview
**Projects**: 8 (Jellyfin.Api + 7 test projects)
**Complexity**: Medium
**Risk**: Medium
**Effort**: Medium
API layer and comprehensive test coverage for Tier 8 business logic.
#### Projects
**Jellyfin.Api** (ASP.NET Core API):
- **Risk**: High (REST API)
- **Dependencies**: Jellyfin.Networking, Jellyfin.MediaEncoding.Hls, MediaBrowser.MediaEncoding, MediaBrowser.Controller
- **Packages**:
- Microsoft.AspNetCore.Authorization: 11.0.0-preview.1 ✅
- Swashbuckle.AspNetCore: 7.3.2 ✅
- Swashbuckle.AspNetCore.ReDoc: 6.9.0 ✅
- **Key Areas**:
- REST API controllers
- Authentication/authorization
- API versioning
- OpenAPI/Swagger
- **Tests**: Jellyfin.Api.Tests (Tier 10)
**Test Projects** (7 projects):
- Jellyfin.Common.Tests
- Jellyfin.LiveTv.Tests
- Jellyfin.MediaEncoding.Hls.Tests
- Jellyfin.MediaEncoding.Tests
- Jellyfin.Networking.Tests
- Jellyfin.Providers.Tests
- Jellyfin.XbmcMetadata.Tests
**Migration Strategy**:
1. Update all 8 project files to net11.0
2. Build API project; fix any ASP.NET Core compatibility issues
3. Run all 7 test projects (validates Tier 8)
**Tier 9 Completion Criteria**:
1. Jellyfin.Api builds without errors/warnings
2. API controllers compile; routing works
3. Authentication/authorization unchanged
4. Swagger/OpenAPI generation works
5. **All 7 test projects: 100% pass rate**
6. Tier 8 business logic validated through tests
---
### Tier 10: Server Implementation
#### Overview
**Projects**: 2
**Complexity**: High
**Risk**: High
**Effort**: High
Server implementations that integrate all lower tiers.
#### Emby.Server.Implementations
- **Risk**: High (integration complexity)
- **Dependencies**: 14 direct dependencies (most of solution)
- **Focus**: Server implementation layer integrating all features
- **Migration**: Update to net11.0; validate integration
- **Tests**: Jellyfin.Server.Implementations.Tests (Tier 13)
#### Jellyfin.Api.Tests
- **Risk**: Low (test project)
- **Validates**: Jellyfin.Api (Tier 9)
- **Expected**: 100% tests pass
**Tier 10 Completion Criteria**:
1. Both projects build without errors/warnings
2. Jellyfin.Api.Tests: 100% pass
3. Server implementations compile and integrate all dependencies
4. No integration conflicts
---
### Tier 11: Main Application
#### Overview
**Projects**: 1 (Jellyfin.Server)
**Complexity**: High
**Risk**: High
**Effort**: Medium
Main application entry point - consolidates all functionality.
#### Jellyfin.Server
- **Risk**: High (application entry point)
- **Dependencies**: 9 direct dependencies
- **Type**: ASP.NET Core application
- **Packages**:
- Serilog.AspNetCore: 10.0.0 ✅
- prometheus-net.AspNetCore: 8.2.1 ✅
- Microsoft.AspNetCore.Mvc.Testing: 11.0.0-preview.1 ✅
- **Key Areas**:
- Application startup (Program.cs, Startup.cs)
- ASP.NET Core hosting
- Middleware pipeline
- Dependency injection configuration
- Logging configuration (Serilog)
- Metrics (Prometheus)
**Migration Steps**:
1. Update to net11.0
2. Validate startup configuration
3. Test application starts
4. Validate middleware pipeline
5. Check dependency injection registration
6. Verify logging/metrics
**Critical Tests**:
- [ ] Application starts successfully
- [ ] No startup exceptions
- [ ] All services registered correctly
- [ ] Middleware pipeline intact
- [ ] API responds to requests
- [ ] Health checks pass
- [ ] Metrics collected
- [ ] Logging functional
**Tier 11 Completion Criteria**:
1. Project builds without errors/warnings
2. Application starts successfully
3. Basic HTTP requests work (200 OK)
4. Health checks pass
5. No startup errors in logs
6. Ready for integration testing
---
### Tier 12: Integration Tests
#### Overview
**Projects**: 2
**Complexity**: Medium
**Risk**: Medium
**Effort**: Medium
End-to-end integration testing of full application stack.
#### Jellyfin.Server.Integration.Tests
- **Risk**: Medium (integration tests)
- **Dependencies**: Jellyfin.Server (Tier 11)
- **Focus**: End-to-end API testing, authentication flows, feature integration
#### Jellyfin.Server.Tests
- **Risk**: Medium (application tests)
- **Dependencies**: Jellyfin.Server (Tier 11)
- **Focus**: Server startup, configuration, basic functionality
**Migration**: Update both to net11.0; run full test suite
**Tier 12 Completion Criteria**:
1. Both test projects build
2. Jellyfin.Server.Tests: 100% pass
3. Jellyfin.Server.Integration.Tests: 100% pass
4. All integration scenarios validated
5. Authentication/authorization flows work
6. API endpoints functional
---
### Tier 13: Final Test Validation
#### Overview
**Projects**: 1
**Complexity**: Low
**Risk**: Low
**Effort**: Low
Final validation of server implementations with integration context.
#### Jellyfin.Server.Implementations.Tests
- **Risk**: Low (final test validation)
- **Dependencies**: Tier 12 (integration tests), Emby.Server.Implementations, Jellyfin.Server.Implementations
- **Focus**: Server implementation validation
**Migration**: Update to net11.0; run tests
**Tier 13 Completion Criteria**:
1. Project builds
2. 100% tests pass
3. All server implementations validated
4. No regressions detected
---
## Testing & Validation Strategy
### Multi-Level Testing Approach
The migration employs testing at every tier to ensure stability before proceeding.
#### Per-Tier Testing
**Build-Time Validation** (Every Tier):
- Zero compilation errors
- Zero warnings (target)
- Code analysis passes
- Package restoration successful
**Unit Testing** (Tiers with Test Projects):
- 100% test pass rate required
- No skipped tests
- No degraded performance
- Tests validate lower tiers
**Integration Testing** (Critical Tiers):
- Tier 6: Database provider integration tests
- Tier 9: API integration tests
- Tier 12: Full application integration tests
#### Phase-by-Phase Testing Requirements
| Phase | Test Requirements | Success Criteria |
|-------|-------------------|------------------|
| **Phase 1** (Tier 2) | Build validation; no unit tests yet | Builds clean; preview framework functional |
| **Phase 2** (Tier 3) | Jellyfin.MediaEncoding.Keyframes.Tests | 100% pass; Tier 2 validated |
| **Phase 3** (Tier 4) | Build only; tested in Phase 4 | Builds clean |
| **Phase 4** (Tier 5) | Jellyfin.Extensions.Tests + Jellyfin.Model.Tests | 100% pass; Tiers 2 & 4 validated |
| **Phase 5** (Tier 6) | **CRITICAL: Extensive database tests** | All database integration tests pass |
| **Phase 6** (Tier 7) | Jellyfin.Naming.Tests | 100% pass; Tier 6 validated |
| **Phase 7** (Tier 8) | Jellyfin.Controller.Tests | 100% pass; Tier 7 validated |
| **Phase 8** (Tier 9) | 7 test projects | 100% pass all; Tier 8 validated |
| **Phase 9** (Tier 10) | Jellyfin.Api.Tests | 100% pass; API validated |
| **Phase 10** (Tier 11) | Manual smoke tests | Application starts; basic features work |
| **Phase 11** (Tier 12) | Integration + Server tests | 100% pass; full stack validated |
| **Phase 12** (Tier 13) | Jellyfin.Server.Implementations.Tests | 100% pass; server validated |
| **Phase 13** (All) | **Full solution validation** | All tests pass; smoke tests pass; performance acceptable |
### Manual Testing Requirements
#### Tier 11 Smoke Tests (Critical)
After Jellyfin.Server migrates, perform manual validation:
1. **Application Startup**
- [ ] Server starts without errors
- [ ] No exceptions in startup logs
- [ ] Health checks respond
2. **Basic Features**
- [ ] Web UI loads
- [ ] User authentication works
- [ ] Library browsing functional
- [ ] Media playback initiates
3. **API Validation**
- [ ] REST API responds
- [ ] Authentication endpoints work
- [ ] Basic CRUD operations successful
4. **Database Operations**
- [ ] Database queries work (PostgreSQL or SQLite)
- [ ] No connection errors
- [ ] CRUD operations persist
### Performance Testing
**Baseline Comparison Points**:
- Tier 6: Database query performance
- Tier 8: Image processing, transcoding performance
- Tier 11: Application startup time, API response time
**Acceptable Performance**:
- Query performance: <10% regression
- Image/video processing: <15% regression
- Startup time: <20% regression
- Memory usage: <15% increase
**Performance Degradation Response**:
- Document regression
- Profile with dotnet-trace/PerfView
- Report to .NET team if framework-related
- Consider optimization or pause if severe (>30% regression)
### Comprehensive Validation (Phase 13)
After Tier 13 complete, perform full solution validation:
#### Build Validation
- [ ] Full solution builds without errors
- [ ] Full solution builds without warnings
- [ ] All projects target net11.0 (except CodeAnalysis)
- [ ] No package conflicts across solution
#### Test Suite Validation
- [ ] All 15 test projects run successfully
- [ ] 100% test pass rate across solution
- [ ] No flaky tests
- [ ] Test execution time acceptable
#### Smoke Testing
- [ ] Application starts and runs
- [ ] All major features functional:
- User authentication
- Library management
- Media playback
- Transcoding
- Live TV (if applicable)
- Metadata fetching
- Image processing
- Network discovery
- [ ] No critical errors in logs
- [ ] Health checks pass
#### Performance Validation
- [ ] Startup time within acceptable range
- [ ] API response times acceptable
- [ ] Database query performance good
- [ ] Transcoding performance acceptable
- [ ] Memory usage reasonable
- [ ] No memory leaks detected
#### Deployment Testing
- [ ] Application deploys successfully
- [ ] Runs on target platforms (Linux, Windows, Docker)
- [ ] Configuration migration works
- [ ] Database migrations successful
- [ ] Existing data accessible
#### Rollback Validation
- [ ] Can revert to previous .NET version if needed
- [ ] Backup/restore procedures work
- [ ] Database rollback possible (if needed)
## Risk Management
### High-Level Risk Assessment
The migration to .NET 11.0 (PREVIEW) presents **moderate to high risk** despite clean compatibility analysis:
#### Risk Categories
| Risk Level | Description | Count | Projects/Areas |
|------------|-------------|-------|----------------|
| **CRITICAL** | Preview framework; database providers | 2 | .NET 11.0 PREVIEW stability; PostgreSQL/SQLite EF providers |
| **HIGH** | Large complex projects; media processing | 5 | Jellyfin.Server, Emby.Server.Implementations, MediaBrowser.MediaEncoding, SkiaSharp, HLS encoding |
| **MEDIUM** | ASP.NET Core application; multiple dependencies | 8 | Jellyfin.Api, Jellyfin.Server.Implementations, MediaBrowser.Controller, networking, providers |
| **LOW** | Small libraries; test projects | 25 | Extensions, models, most test projects |
### Critical Risks
#### 1. Preview Framework Instability (.NET 11.0 PREVIEW)
**Risk**: CRITICAL
**Impact**: Entire solution
**Probability**: HIGH
**Description**:
.NET 11.0 is in preview - not production-ready. May exhibit:
- Runtime instability
- Unexpected breaking changes in preview builds
- Performance regressions
- Undocumented API changes
- Preview build tooling issues
- Missing or incomplete features
**Mitigation**:
- ✅ Bottom-up approach exposes issues early (Tier 2 discovery)
- ✅ Extensive testing at each tier before proceeding
- ✅ Monitor .NET 11.0 preview release notes for known issues
- ✅ Maintain ability to rollback to .NET 9.0 or switch to .NET 10.0 LTS
- ✅ Test on target deployment environments early
- ✅ Consider pausing if critical preview bugs discovered
**Contingency**:
- If critical preview issues: revert and target .NET 10.0 LTS instead
- If minor issues: document and work around, monitor for preview fixes
- If blocking issues in Tier 2-4: pause migration until preview stabilizes
#### 2. Database Provider Compatibility (Tier 6)
**Risk**: CRITICAL
**Impact**: All database operations (entire application)
**Probability**: MEDIUM
**Description**:
Database providers are critical infrastructure:
- **Npgsql.EntityFrameworkCore.PostgreSQL 11.0.0-preview.1**: Preview provider for preview framework
- **Microsoft.EntityFrameworkCore.Sqlite 11.0.0-preview.1**: Preview EF Core provider
- Jellyfin.Database.Implementations integrates both providers
- Any provider issue breaks data access throughout application
**Mitigation**:
- ✅ Tier 6 dedicated phase for database provider validation
- ✅ Extensive integration testing with real databases (PostgreSQL, SQLite)
- ✅ Test migration scenarios, CRUD operations, query performance
- ✅ Validate connection pooling, transaction behavior
- ✅ Performance benchmarking vs. .NET 9.0 baseline
- ✅ Test under load/concurrent operations
**Contingency**:
- If provider issues: report to Npgsql/EF Core teams, monitor for fixes
- If blocking: consider staying on .NET 9.0 until stable provider releases
- If PostgreSQL issues only: validate SQLite as temporary fallback
- Database provider failures block entire migration at Tier 6
### High Risks
#### 3. Media Processing Libraries (SkiaSharp, Tier 8)
**Risk**: HIGH
**Impact**: Image processing, thumbnail generation, graphics
**Probability**: MEDIUM
**Description**:
- SkiaSharp 3.116.1 used for image processing
- HarfBuzzSharp.NativeAssets.Linux for font rendering
- Native library interop may have .NET 11.0 issues
- Cross-platform compatibility concerns (Linux, Windows, macOS)
**Mitigation**:
- ✅ Test image processing workflows in Tier 8
- ✅ Validate thumbnail generation, image transcoding
- ✅ Test on target platforms (Linux primary for Jellyfin)
- ✅ Verify native library loading and interop
- ✅ Performance testing for image operations
**Contingency**:
- If issues: check for SkiaSharp .NET 11.0 updates
- Report issues to SkiaSharp maintainers
- May need to wait for library updates
#### 4. Main Server Application (Jellyfin.Server, Tier 11)
**Risk**: HIGH
**Impact**: Application entry point, all features
**Probability**: LOW
**Description**:
- Main application consolidates all functionality
- ASP.NET Core 11.0 preview hosting
- Startup configuration, middleware, dependency injection
- All features converge here
**Mitigation**:
- ✅ Tiers 2-10 stable before reaching Tier 11
- ✅ Comprehensive integration testing
- ✅ Manual smoke testing of key user scenarios
- ✅ Performance monitoring vs. baseline
- ✅ Error handling and logging verification
**Contingency**:
- If startup issues: check ASP.NET Core 11.0 preview breaking changes
- Isolate failing features and test independently
- May need ASP.NET Core configuration adjustments
#### 5. Entity Framework Core 11.0 Preview
**Risk**: HIGH
**Impact**: All data access
**Probability**: MEDIUM
**Description**:
- EF Core 11.0.0-preview.1 used throughout solution
- Query translation, migrations, change tracking
- Preview may have query translation issues or performance changes
**Mitigation**:
- ✅ Validate existing database migrations still work
- ✅ Test query patterns used throughout application
- ✅ Monitor query performance
- ✅ Validate LINQ-to-SQL translation
- ✅ Test include/navigation loading
**Contingency**:
- If query translation fails: rewrite queries or wait for EF Core fixes
- Performance issues: profile and optimize or report upstream
- Migration issues: may need manual SQL adjustments
### Medium Risks
#### 6. ASP.NET Core 11.0 API Compatibility (Tier 9)
**Risk**: MEDIUM
**Impact**: REST API, authentication, authorization
**Probability**: MEDIUM
**Description**:
- Jellyfin.Api uses ASP.NET Core 11.0 preview
- Authentication, authorization, middleware pipeline
- API controllers, routing, model binding
**Mitigation**:
- ✅ API tests in Tier 9 validate endpoints
- ✅ Test authentication/authorization flows
- ✅ Validate OpenAPI/Swagger generation
- ✅ Test API versioning
**Contingency**:
- If auth issues: review ASP.NET Core Identity changes
- If routing breaks: adjust route configurations
- API compatibility issues may require code changes
#### 7. Media Encoding & Streaming (Tier 8-9)
**Risk**: MEDIUM
**Impact**: Video transcoding, HLS streaming
**Probability**: LOW
**Description**:
- MediaBrowser.MediaEncoding, Jellyfin.MediaEncoding.Hls
- Video/audio transcoding, HLS playlist generation
- FFmpeg integration (process spawning, stream handling)
**Mitigation**:
- ✅ Test transcoding workflows
- ✅ Validate HLS manifest generation
- ✅ Test FFmpeg process management
- ✅ Performance validation for encoding
**Contingency**:
- If process issues: check .NET 11.0 Process API changes
- If streaming breaks: validate HLS encoding pipeline
- May need FFmpeg command adjustments
#### 8. Networking & Connectivity (Tier 8)
**Risk**: MEDIUM
**Impact**: Network discovery, DLNA, remote access
**Probability**: LOW
**Description**:
- Jellyfin.Networking for network operations
- DLNA, SSDP, network interface detection
- Socket operations, UDP/TCP communication
**Mitigation**:
- ✅ Test network discovery scenarios
- ✅ Validate DLNA device detection
- ✅ Test under various network configurations
- ✅ Socket operation validation
**Contingency**:
- If network issues: check .NET 11.0 networking changes
- May need Socket or HttpClient configuration adjustments
- DLNA issues may require protocol-level debugging
### Low Risks
#### 9. Test Projects
**Risk**: LOW
**Impact**: Testing infrastructure only
**Probability**: LOW
**Description**:
15 test projects throughout tiers; xUnit 2.9.3, Moq 4.18.4
**Mitigation**:
- ✅ Test framework compatibility pre-verified
- ✅ Test projects upgraded incrementally with their targets
- ✅ Validation at each tier
**Contingency**:
- If test framework issues: update xUnit/Moq/AutoFixture
- Test failures indicate actual issues, not test framework problems
#### 10. Small Utility Libraries
**Risk**: LOW
**Impact**: Limited to specific features
**Probability**: VERY LOW
**Description**:
- Extensions, utilities, models (Tiers 2-5)
- Simple, well-tested code
- Minimal external dependencies
**Mitigation**:
- ✅ Unit tests cover functionality
- ✅ Early tiers - failures detected immediately
- ✅ Easy to isolate and fix
**Contingency**:
- Minimal risk; standard debugging if issues arise
### Risk Mitigation Matrix
| Tier | Primary Risks | Mitigation Strategy | Fallback |
|------|---------------|---------------------|----------|
| **Tier 2** | Preview framework first exposure | Extensive testing; early warning system | Revert if critical issues |
| **Tier 3-5** | Model/data layer stability | Unit tests, validation | Isolated fixes |
| **Tier 6** | Database providers (CRITICAL) | Integration tests, performance testing | Block migration if fails |
| **Tier 7** | Controller abstractions | Naming tests, validation | Standard debugging |
| **Tier 8** | Media processing, networking | Functional testing, cross-platform validation | Feature-specific fixes |
| **Tier 9** | API, authentication | API tests, auth flow validation | ASP.NET Core config adjustments |
| **Tier 10-11** | Server implementation, main app | Integration tests, smoke testing | Startup configuration fixes |
| **Tier 12-13** | End-to-end validation | Full test suite, manual validation | Comprehensive debugging |
### Rollback Triggers
Rollback or pause migration if:
1. ✅ **Tier 2-4 failures**: Preview framework shows critical instability
2. ✅ **Tier 6 failure**: Database providers unusable
3. ✅ **>20% test failures** in any tier
4. ✅ **Performance degradation** >30% in benchmarks
5. ✅ **Blocking preview bugs** with no workaround
6. ✅ **Security vulnerabilities** in preview framework
7. ✅ **Critical runtime errors** not present in .NET 9.0
### Risk Acceptance
The following risks are **accepted**:
- ✅ **Preview framework instability**: Required for .NET 11.0 evaluation
- ✅ **Minor breaking changes**: Expected in preview; can be addressed
- ✅ **Performance variations**: Preview builds may have unoptimized code
- ✅ **Incomplete preview features**: Can work around or wait for releases
### Continuous Risk Monitoring
Throughout migration:
- Monitor .NET 11.0 preview announcements and known issues
- Track package update releases for compatibility fixes
- Performance benchmark each tier vs. .NET 9.0 baseline
- Document all issues encountered for future reference
- Maintain communication with .NET/EF Core/package maintainer communities
## Testing & Validation Strategy
[To be filled]
## Complexity & Effort Assessment
### Overall Complexity: **COMPLEX**
Based on solution structure, technology stack, and preview framework target.
### Per-Tier Complexity Assessment
| Tier | Projects | Complexity | Dependencies | Risk | Effort | Rationale |
|------|----------|------------|--------------|------|--------|-----------|
| **Tier 1** | 1 | N/A | None | None | None | No migration (netstandard2.0) |
| **Tier 2** | 3 | **Medium** | CodeAnalysis only | High | Medium | First preview exposure; database/extension infrastructure |
| **Tier 3** | 2 | **Low** | Tier 2 | Low | Low | Data models + 1 test; straightforward |
| **Tier 4** | 1 | **Medium** | Tiers 2-3 | Medium | Low | Central models (high fan-out); single project |
| **Tier 5** | 3 | **Low** | Tiers 2-4 | Low | Low | Common utilities + 2 tests; minimal complexity |
| **Tier 6** | 3 | **High** | Tiers 2-5 | **Critical** | High | Database providers (PostgreSQL, SQLite); extensive testing required |
| **Tier 7** | 2 | **Medium** | Tiers 2-6 | Medium | Medium | Controller abstractions + 1 test; moderate complexity |
| **Tier 8** | 12 | **High** | Tiers 2-7 | High | High | Largest tier; media processing, networking, business logic; parallelizable |
| **Tier 9** | 8 | **Medium** | Tiers 2-8 | Medium | Medium | API + 7 test projects; validation-heavy |
| **Tier 10** | 2 | **High** | Tiers 2-9 | High | High | Server implementations; integration point for all features |
| **Tier 11** | 1 | **High** | Tiers 2-10 | High | Medium | Main application; entry point; consolidates all functionality |
| **Tier 12** | 2 | **Medium** | Tier 11 | Medium | Medium | Integration tests; end-to-end validation |
| **Tier 13** | 1 | **Low** | Tier 12 | Low | Low | Final test project; single project validation |
### Tier-by-Tier Effort Breakdown
#### Low Complexity Tiers (4 tiers, 7 projects)
**Tiers**: 3, 5, 13
**Total Projects**: 7
**Characteristics**:
- Small codebases or test-only projects
- Minimal dependencies or simple utilities
- Straightforward migration
- Low risk of issues
**Estimated Effort**: Low per tier
---
#### Medium Complexity Tiers (5 tiers, 10 projects)
**Tiers**: 2, 4, 7, 9, 12
**Total Projects**: 10
**Characteristics**:
- Infrastructure components (Tier 2)
- Central models with high fan-out (Tier 4)
- Controller abstractions (Tier 7)
- API + multiple tests (Tier 9)
- Integration testing (Tier 12)
**Estimated Effort**: Medium per tier
---
#### High Complexity Tiers (3 tiers, 15 projects)
**Tiers**: 6, 8, 10, 11
**Total Projects**: 15
**Characteristics**:
- **Tier 6**: Database providers (CRITICAL; extensive testing)
- **Tier 8**: Largest tier (12 projects); media processing, networking, business logic
- **Tier 10**: Server implementations (integration complexity)
- **Tier 11**: Main application (consolidation point)
**Estimated Effort**: High per tier
### Resource Requirements
#### Skill Levels Needed
1. **Senior .NET Engineers** (Required)
- Deep .NET framework knowledge
- Experience with preview frameworks
- EF Core expertise (for Tier 6)
- ASP.NET Core experience (for Tiers 9-11)
2. **Database Engineers** (Tier 6)
- PostgreSQL administration
- SQLite expertise
- EF Core migrations and performance tuning
3. **Media Processing Engineers** (Tier 8)
- FFmpeg integration knowledge
- Video encoding/transcoding experience
- HLS streaming protocols
4. **QA/Testing Engineers** (All tiers)
- Test framework expertise (xUnit)
- Integration testing
- Performance testing
#### Parallel Execution Capacity
**Optimal Team Structure**:
- **Tier 2-5, 7**: 1-2 engineers (sequential or small parallel)
- **Tier 6**: 2-3 engineers (database providers need dedicated focus)
- **Tier 8**: 3-5 engineers (12 projects; high parallelism potential)
- **Tier 9-11**: 2-3 engineers (integration complexity)
- **Tier 12-13**: 1-2 engineers (testing focus)
**Minimum Team**: 2 senior .NET engineers + 1 QA engineer
**Optimal Team**: 4-5 engineers (mix of specializations) + 2 QA engineers
### Phase Complexity Summary
| Phase | Tier(s) | Complexity | Effort | Duration Estimate |
|-------|---------|------------|--------|-------------------|
| **Phase 1** | Tier 2 | Medium | Medium | *Relative: Medium* |
| **Phase 2** | Tier 3 | Low | Low | *Relative: Low* |
| **Phase 3** | Tier 4 | Medium | Low | *Relative: Low* |
| **Phase 4** | Tier 5 | Low | Low | *Relative: Low* |
| **Phase 5** | Tier 6 | **High** | **High** | *Relative: High* |
| **Phase 6** | Tier 7 | Medium | Medium | *Relative: Medium* |
| **Phase 7** | Tier 8 | **High** | **High** | *Relative: High* |
| **Phase 8** | Tier 9 | Medium | Medium | *Relative: Medium* |
| **Phase 9** | Tier 10 | **High** | **High** | *Relative: High* |
| **Phase 10** | Tier 11 | High | Medium | *Relative: Medium* |
| **Phase 11** | Tier 12 | Medium | Medium | *Relative: Medium* |
| **Phase 12** | Tier 13 | Low | Low | *Relative: Low* |
| **Phase 13** | All | High | High | *Relative: High* |
**Note**: Duration estimates are relative complexity ratings only. Actual time depends on team size, experience, issue discovery, and preview framework stability.
### Complexity Factors by Tier
#### Tier 2: Core Infrastructure (Medium)
- **Factors**:
- First exposure to .NET 11.0 preview
- Database implementation foundation
- Extension infrastructure
- **Challenges**:
- Unknown preview framework issues
- Critical foundation for all higher tiers
- **Mitigation**: Thorough testing; early warning system
#### Tier 6: Database Providers (High) ⚠️ CRITICAL
- **Factors**:
- PostgreSQL EF Core provider (preview)
- SQLite EF Core provider (preview)
- Database operations throughout solution depend on this
- **Challenges**:
- Provider preview stability
- Query translation, migrations, performance
- Concurrent operations, connection pooling
- **Mitigation**: Extensive integration testing, performance benchmarking
#### Tier 8: Business Logic (High)
- **Factors**:
- 12 projects (largest tier)
- Media processing (SkiaSharp, FFmpeg)
- Networking (DLNA, SSDP)
- Providers, metadata, encoding
- **Challenges**:
- Diverse functionality requiring different expertise
- Native library interop (SkiaSharp)
- Process management (FFmpeg)
- **Mitigation**: Parallelization; specialized testing per area
#### Tier 10: Server Implementation (High)
- **Factors**:
- Emby.Server.Implementations (14 dependencies)
- Integration point for most features
- **Challenges**:
- Complex integration
- Many failure points from dependencies
- **Mitigation**: Tiers 2-9 stable; incremental testing
#### Tier 11: Main Application (High)
- **Factors**:
- Application entry point
- ASP.NET Core 11.0 hosting
- Startup, middleware, DI configuration
- **Challenges**:
- All features converge here
- ASP.NET Core preview stability
- **Mitigation**: Comprehensive smoke testing; staging environment validation
### Incremental Benefit Realization
Benefits realized after each tier completion:
| Tier Complete | Benefits Unlocked |
|---------------|-------------------|
| **Tier 2** | Foundation infrastructure on .NET 11.0; preview framework viability assessed |
| **Tier 3** | Data models available to higher tiers |
| **Tier 4** | Central models on .NET 11.0; broad compatibility established |
| **Tier 5** | Common utilities available; model validation complete |
| **Tier 6** | **Database providers validated** (critical milestone); data access stable |
| **Tier 7** | Controller abstractions ready; naming validated |
| **Tier 8** | **Business logic on .NET 11.0**; media processing, networking validated |
| **Tier 9** | **API layer operational**; comprehensive business logic tests pass |
| **Tier 10** | **Server implementations complete**; integration validated |
| **Tier 11** | **Main application functional**; end-to-end features available |
| **Tier 12** | **Integration testing complete**; confidence in full stack |
| **Tier 13** | **All tests pass**; solution fully validated |
### Critical Milestones
1. **Tier 2 Complete**: Preview framework viability confirmed
2. **Tier 6 Complete**: Database providers stable (go/no-go decision point)
3. **Tier 8 Complete**: Business logic operational
4. **Tier 11 Complete**: Application functional
5. **Tier 13 Complete**: Full solution validation
### Effort Distribution
- **Low Effort Tiers** (3, 5, 13): ~15% of total effort
- **Medium Effort Tiers** (2, 4, 7, 9, 12): ~35% of total effort
- **High Effort Tiers** (6, 8, 10, 11): ~50% of total effort
**Highest effort areas**:
1. Tier 6 (Database providers) - CRITICAL
2. Tier 8 (Business logic) - Largest tier
3. Tier 10-11 (Server & application) - Integration complexity
## Source Control Strategy
### Branching Strategy
**Primary Branch**: `upgrade-to-NET11`
**Source Branch**: `pgsql_testing_branch`
**Merge Target**: `pgsql_testing_branch` (after successful validation)
#### Branch Management
- Upgrade branch created from `pgsql_testing_branch`
- All migration work on `upgrade-to-NET11`
- Tier-by-tier commits
- Protected milestones: Tags after Tier 6, Tier 11, Tier 13
### Commit Strategy
**Format**: `Upgrade Tier [N] ([Name]) to .NET 11.0`
**Per-Tier Commits** (Recommended):
- One commit per tier
- Atomic changes
- Includes test validation
### Review and Merge
**Single PR** after complete validation (recommended for preview framework)
**PR Checklist**:
- [ ] All 13 tiers complete
- [ ] 100% test pass rate
- [ ] Full solution builds clean
- [ ] Performance acceptable
- [ ] Documentation updated
**Review Requirements**: 2+ senior engineers
### Rollback Plan
**Triggers**: Critical preview bugs, database failures, severe performance degradation
**Method**: Git revert to pre-migration state
---
## Success Criteria
### Technical Criteria
**Build & Compilation**:
- ✅ 40 projects upgraded to .NET 11.0
- ✅ Solution builds without errors/warnings
- ✅ No package conflicts
**Testing**:
- ✅ All 15 test projects: 100% pass rate
- ✅ No flaky tests
**Database Providers (CRITICAL)**:
- ✅ PostgreSQL & SQLite functional
- ✅ Migrations successful
- ✅ Performance: <10% regression
**Application**:
- ✅ Jellyfin.Server starts
- ✅ All major features work
- ✅ API functional
**Performance**:
- ✅ Startup: <20% regression
- ✅ Database queries: <10% regression
- ✅ API/processing: <15% regression
- ✅ Memory: <15% increase
**Code Quality**:
- ✅ All analyzers pass
- ✅ No new warnings
**Bottom-Up Strategy**:
- ✅ All 13 tiers completed in order
- ✅ Tier 6 extensively validated
**Deployment**:
- ✅ Deploys to target platforms
- ✅ Rollback tested
### Definition of Done
Migration complete when:
- All technical criteria met
- All stakeholder approvals obtained
- PR merged
- Post-merge validation passed
---
## Final Notes
### .NET 11.0 Preview Warning
Targeting **PREVIEW framework** - expect instability. Monitor closely; consider .NET 10.0 LTS if critical issues arise.
### Post-Migration
1. Monitor .NET 11.0 release progression
2. Update to stable package versions
3. Performance tuning
4. Report issues to .NET team
---
**Plan Version**: 1.0
**Target**: .NET 11.0 (PREVIEW)
**Strategy**: Bottom-Up (Dependency-First)
**Tiers**: 13 (Tier 1 unchanged, Tiers 2-13 migrated)