BrighterCommand / BrighterCommand/Brighter
Align Microsoft.Extensions Package Versions with Target Framework in v11
- Dominant language
- C#
- Stars
- 2.5k
- Forks
- 296
- Avg merge
- 1d 11h
- Merged PRs (30d)
- 21
Description
### Problem Statement
Brighter currently uses a **single version** of `Microsoft.Extensions.*` packages across all target frameworks. In v10, `Microsoft.Extensions.DependencyInjection.Abstractions`, `Microsoft.Extensions.Options`, `Microsoft.Extensions.Logging`, etc. are all pinned to `10.0.3` regardless of whether the consumer targets `net8.0`, `net9.0`, or `net10.0`.
This causes issues:
- **Diamond dependency conflicts**: A .NET 8 application that references other packages depending on `Microsoft.Extensions.* 8.x` gets forced to resolve to `10.0.3` because Brighter pulls it in transitively.
- **Version mismatch warnings**: MSBuild emits NU1608/NU1701 warnings when the app references an older Microsoft.Extensions package and Brighter overrides it.
- **Unnecessary upgrades**: Consumers on .NET 8 or .NET 9 are forced to upgrade their Microsoft.Extensions stack even if they don't need v10 features.
### Current State
From `Directory.Packages.props` (Central Package Management), Brighter v10 pins:
```xml
```
These versions are applied to **all** TFMs: `net8.0`, `net9.0`, `net10.0`, and `netstandard2.0`.
### Proposed Change for v11
Use **conditional package references** in `Directory.Packages.props` (or per-project `.csproj` files) so that each target framework gets the matching `Microsoft.Extensions` major version:
| Target Framework | Microsoft.Extensions Version |
|------------------|------------------------------|
| `net8.0` | `8.0.x` (latest patch) |
| `net9.0` | `9.0.x` (latest patch) |
| `net10.0` | `10.0.x` (latest patch) |
| `net11.0` | `11.0.x` (latest patch) |
#### Example Implementation
In `Directory.Packages.props` or individual `.csproj` files:
```xml
```
Alternatively, using MSBuild properties in `Directory.Build.props`:
```xml
8.0.2
9.0.3
10.0.3
11.0.0
```
Then in `Directory.Packages.props`:
```xml
```
### Packages Affected
All packages that reference `Microsoft.Extensions.*` should be updated, including:
- `Paramore.Brighter`
- `Paramore.Brighter.Extensions.DependencyInjection`
- `Paramore.Brighter.Extensions.Hosting`
- `Paramore.Brighter.ServiceActivator.Extensions.DependencyInjection`
- `Paramore.Brighter.ServiceActivator.Extensions.Hosting`
- `Paramore.Brighter.Outbox.*` (if applicable)
- `Paramore.Brighter.Inbox.*` (if applicable)
- Any other package referencing `Microsoft.Extensions.Logging`, `Microsoft.Extensions.DependencyInjection`, `Microsoft.Extensions.Options`, `System.Text.Json`, etc.
### Benefits
1. **No more diamond dependency conflicts** — a .NET 8 app gets `Microsoft.Extensions.* 8.x`, a .NET 9 app gets `9.x`, etc.
2. **Cleaner build output** — eliminates NU1608/NU1701 warnings caused by version mismatches.
3. **Follows .NET ecosystem conventions** — major Microsoft.Extensions versions map to major .NET versions (8→8, 9→9, 10→10, 11→11).
4. **Smaller upgrade friction** — consumers can upgrade Brighter without being forced to upgrade their entire Microsoft.Extensions stack.
### Migration Path for v11
Since this is a **major version breaking change**:
1. **v11.0.0**:
- Update `Directory.Packages.props` (or `Directory.Build.props`) with conditional versions per TFM.
- Update all `.csproj` files that reference `Microsoft.Extensions.*` packages.
- Ensure CI builds and tests pass for all target frameworks.
2. **Migration guide**:
- No action required for most consumers — NuGet will automatically resolve the correct Microsoft.Extensions version based on their app's TFM.
- For consumers who were relying on Brighter to pull in `Microsoft.Extensions.* 10.x` transitively, they may need to add an explicit reference if they need a newer version.
### Considerations
- **Breaking change**: This is intentional. v11 is the correct vehicle for changing dependency resolution behavior.
- **Central Package Management**: Since Brighter uses `Directory.Packages.props`, the change should be centralized there rather than scattered across individual `.csproj` files.
- **LTS support**: If Brighter v11 drops `net8.0` support, this becomes simpler. If `net8.0` is still supported, the conditional logic is required.
Contributor guide
Research direction
Start with Directory.Packages.props and inspect the affected .csproj files for Microsoft.Extensions.* references, then review Directory.Build.props if conditional properties are used. Determine the complete package set and supported target frameworks before choosing the central conditional approach. Done means all affected packages use matching framework versions and CI builds and tests pass for every target framework.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- csharp
- Domain
- build-system
- Issue type
- Refactor
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100