Modernize to .NET 8 LTS, add fluent API, DI package, and samples

[DeeJayTC]

Why

A bundled modernization of the library that fixes a pile of latent issues and pays the "eventually we should do this" tax in one coordinated change.

Runtime and dependency support has rotted

• net5.0 reached end of support on 2022-05-10. netcoreapp3.1 ended on 2022-12-13. Both have been unsupported for multiple years. The library's test project still targeted both.
• The 5.x-line dependencies we were pinning (Microsoft.Extensions.Http.Polly 5.0.1, System.Text.Json 5.0.2) have known security advisories that only ship fixes on 6.x+ / 8.x lines. We were shipping consumers onto a patched-CVE surface by default.
• Polly v7 (the version referenced by Microsoft.Extensions.Http.Polly 5.x) is effectively frozen — active development moved to Polly v8's ResiliencePipeline API and Microsoft's replacement package Microsoft.Extensions.Http.Resilience. Sitting on the 5.x-of-the-wrapper permanently blocks us from that ecosystem.
• Test harness: xunit 2.4.1 / NSubstitute 4.3.0 / Microsoft.NET.Test.Sdk 16.9.4 are all 2021-era and miss several analyzer fixes, async-safety guards, and bug fixes that ship in 2.9 / 5.3 / 17.11.
• The custom workaround code we'd carried around (LargeFormUrlEncodedContent for a size-limit bug, LowerSnakeCaseNamingPolicy for missing BCL API) was no longer necessary: the first was fixed in .NET 5 (Remove unnecessary length restriction on Uri.Escape{Data/Uri}String dotnet/corefx#41686, as our own source comment noted), the second is built into .NET 8 as JsonNamingPolicy.SnakeCaseLower.

Consumer ergonomics gaps

• No fluent builder API — every option had to be set by constructing a TextTranslateOptions / DocumentTranslateOptions etc. and passing it through positional arguments. Verbose for the common case of "translate this with formality=more".
• No DI integration — every ASP.NET Core / Worker service consumer that wanted DeepL had to hand-roll a singleton registration, wire up IHttpClientFactory themselves, handle options validation themselves. Every major .NET client library ships a companion *.Extensions.DependencyInjection package; we didn't.
• No runnable samples.

What this PR delivers

Logically separated commits. Each can be reviewed independently.

1. feat: Add fluent API layer (220a5d8)

LINQ-style extensions on top of ITranslator / IWriter / IGlossaryManager / IStyleRuleManager. Builders are directly awaitable (GetAwaiter) and have implicit Task<T> conversion so they drop into Task.WhenAll etc. Non-breaking: every fluent method is an extension over an existing interface, so the new API works with any ITranslator/IWriter implementation (including mocks) and doesn't alter existing call sites.

await translator.Translate("Hello").From("en").To("de")
      .WithFormality(Formality.More)
      .WithGlossary(glossary)
      .WithCustomInstructions("Keep it concise");

await client.CreateGlossary("My glossary")
      .WithDictionary("en", "de", enDeEntries)
      .WithDictionary("de", "en", deEnEntries);

await translator.TranslateDocument(input)
      .From("en").To("de")
      .WithFormality(Formality.More)
      .SaveTo(output);

Includes 73 unit tests (NSubstitute-based, no network) covering argument forwarding, every option helper, validation, single + batch shapes, cancellation propagation, and the implicit Task<T> conversion.

2. build: Modernize target frameworks to net8.0 + netstandard2.0 (53b10b1)

Project	Before	After
Library TFMs	net5.0;netstandard2.0	netstandard2.0;net8.0
Library LangVersion	8	12
Test TFMs	net5.0;netcoreapp3.1;net462	net8.0;net462

Dependency bumps:

Package	Before	After
Microsoft.Extensions.Http.Polly	5.0.1	8.0.26
System.Text.Json	5.0.2	8.0.6
System.Net.Http.Json	(new)	8.0.1
Microsoft.NET.Test.Sdk	16.9.4	17.11.1
xunit	2.4.1	2.9.2
xunit.runner.visualstudio	2.4.3	2.8.2
NSubstitute	4.3.0	5.3.0
coverlet.collector	3.0.2	6.0.2
JunitXml.TestLogger	3.0.98	5.0.0

netstandard2.0 retained as the floor — the package stays usable from .NET Framework 4.7.2+, Mono, Unity, etc. net462 retained in the test project to validate that consumer story.

3. refactor: Adopt .NET 8 BCL APIs in HTTP/JSON internals (4a0465f)

Modern BCL on net8.0, existing code preserved as netstandard2.0 fallback behind #if NET8_0_OR_GREATER / NET5_0_OR_GREATER:

• JsonNamingPolicy.SnakeCaseLower + HttpContent.ReadFromJsonAsync replace the custom snake-case policy and stream reader.
• HttpMethod.Patch replaces the new HttpMethod("PATCH") allocation (factored to a static field in both cases).
• JsonContent.Create replaces new StringContent(JsonSerializer.Serialize(...)) — streams instead of an intermediate string allocation.
• SocketsHttpHandler with PooledConnectionLifetime = 5min and PooledConnectionIdleTimeout = 2min replaces HttpClientHandler. Long-lived HttpClient instances now pick up DNS changes correctly.
• HttpVersion.Version20 + RequestVersionOrHigher policy: DeepL's API supports HTTP/2, enabling proper multiplexing for batch translation.
• FormUrlEncodedContent (built-in) replaces LargeFormUrlEncodedContent on net5+. The underlying size-limit bug was fixed in .NET 5 — our custom workaround is now compiled out of the modern asset and only survives for ns2.0.

No public API change; ns2.0 consumers see identical behavior, net8 consumers get the modern paths.

4. feat: Add DeepL.Extensions.DependencyInjection companion package (d9bba3a)

New NuGet package (TFMs: netstandard2.0 + net8.0) providing Microsoft.Extensions.DependencyInjection integration:

services.AddDeepLClient(o => o.AuthKey = "...");
services.AddDeepLClient(builder.Configuration);                           // binds "DeepL" section
services.AddDeepLClient(builder.Configuration.GetSection("Translation"));

• Registers DeepLClient as a singleton (documented thread-safe) and forwards every surface interface (ITranslator, IWriter, IGlossaryManager, IStyleRuleManager) to the same instance.
• Routes the underlying HttpClient through IHttpClientFactory with the named client "DeepL", so consumers can layer their own handlers / resilience policies on top:

services.AddDeepLClient(o => o.AuthKey = key);
services.AddHttpClient(DeepLOptions.HttpClientName).AddStandardResilienceHandler();

• Validates AuthKey via IValidateOptions<> — missing key surfaces on first resolve, not on first API call.
• Idempotent (TryAdd semantics).

Why a separate package rather than adding DI to DeepL.net itself:

1. DeepL.net stays dependency-free for consumers using Autofac / DryIoc / SimpleInjector or constructing DeepLClient manually.
2. Matches the established .NET ecosystem pattern (MediatR.Extensions.Microsoft.DependencyInjection, Polly.Extensions.Http, Serilog.Extensions.Hosting, OpenTelemetry.Extensions.Hosting).
3. DI-integration shape can evolve independently without forcing main-library version bumps.

Versioning: lockstep with DeepL.net for simplicity. Strong-named with the shared sgKey.snk. Includes 15 DI-container tests covering registration, singleton lifetime, interface forwarding, auth-key validation, HttpClientFactory integration, ServerUrl propagation (verified end-to-end via a capturing HttpMessageHandler), idempotency, and both the configure-delegate + IConfiguration overloads.

5. docs: Add /samples with FluentApi and DependencyInjection examples (4b88dc8)

Two runnable sample console apps:

• samples/FluentApi — exhaustive demo of every fluent entry point (text translation, rephrase, document translation one-shot + split, glossary CRUD, style rule CRUD).
• samples/DependencyInjection — generic host + AddDeepLClient + an IHostedService consumer pulling ITranslator / IWriter / IGlossaryManager from DI.

Samples live in their own solution (samples/DeepL.Samples.slnx) deliberately — out of the main CI scope so they don't affect the library's build or NuGet pack. They use ProjectReference against the sibling library so local changes are picked up on each build.

6. chore: Drop in-progress Voice API draft from this branch (d772750)

The branch had picked up an unrelated WIP commit for the Voice API. That work is separately tracked on tc/add-voice and will land in its own PR; it was stripped from this branch to keep scope clean. When Voice lands, the DI package just needs one line re-added to forward IVoiceManager to the same singleton.

Verification

All projects build clean on all TFMs. Tests pass:

Main solution (DeepL.net.sln):
  DeepL                                        net8.0 + netstandard2.0   0 warn / 0 err
  DeepLTests                                   net8.0 + net462           0 warn / 0 err
  DeepL.Extensions.DependencyInjection         net8.0 + netstandard2.0   0 warn / 0 err
  DeepL.Extensions.DependencyInjection.Tests   net8.0                    0 warn / 0 err

Samples (DeepL.Samples.slnx):
  FluentApi                                    net8.0                    0 warn / 0 err
  DependencyInjection                          net8.0                    0 warn / 0 err

Tests (net8.0, no network required):
  Fluent API                     73/73 pass
  DI integration                 15/15 pass

The existing integration test suite (DeepLTests/*Test.cs, requires DEEPL_AUTH_KEY or a mock server) is unchanged and untouched by this PR — needs a run against staging / mock server before merge to confirm no behavioral regression from the HTTP/JSON refactor.

Notes for reviewers

• The modernization sequence (commits 2–3) was structured to be behavior-preserving on netstandard2.0. Consumer apps on .NET Framework 4.7.2+ see identical behavior; only the net8.0 asset swaps to the new BCL paths.
• What's not in this PR (deferred):
  • Language-cleanup sweep (file-scoped namespaces, ArgumentNullException.ThrowIfNull conversion). ~40-file mechanical diff; belongs in its own PR.
  • STJ source generators for AOT / trim readiness. High value but reshapes every DTO.
  • Polly v8 / Microsoft.Extensions.Http.Resilience migration. Rewrites the retry stack; separate PR.

Test plan

• dotnet build DeepL.net.sln — clean on all TFMs
• dotnet test DeepLTests/DeepLTests.csproj -f net8.0 --filter FullyQualifiedName~Fluent — 73/73
• dotnet test DeepL.Extensions.DependencyInjection.Tests — 15/15
• dotnet test DeepLTests/DeepLTests.csproj -f net8.0 with DEEPL_AUTH_KEY or mock-server — existing suite passes (verifies HTTP/JSON refactor is behavior-preserving)
• dotnet test DeepLTests/DeepLTests.csproj -f net462 with auth key — verifies ns2.0 consumer story still works
• dotnet build samples/DeepL.Samples.slnx — samples build clean
• (optional) dotnet run --project samples/FluentApi with a real DEEPL_AUTH_KEY — end-to-end smoke
• (optional) dotnet run --project samples/DependencyInjection — DI end-to-end smoke

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Modernizes the DeepL .NET SDK to current TFMs/dependencies while adding a fluent API layer, a companion Microsoft DI integration package, and runnable sample apps to demonstrate both.

Changes:

• Add fluent, awaitable builder extensions for translation/rephrase/document/glossary/style-rule flows plus unit tests.
• Upgrade library/tests to net8.0 (keeping netstandard2.0 for the library) and adopt newer BCL HTTP/JSON APIs with conditional fallbacks.
• Introduce DeepL.Extensions.DependencyInjection + tests and add /samples solution demonstrating fluent + DI usage.

Reviewed changes

Copilot reviewed 28 out of 28 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
samples/README.md	Documents how to build/run the sample apps.
samples/FluentApi/Program.cs	End-to-end console sample showcasing the fluent API surface.
samples/FluentApi/FluentApi.csproj	Sample project referencing the library via ProjectReference.
samples/Directory.Build.props	Shared build settings for sample projects (net8, nullable, no pack/sign).
samples/DependencyInjection/TranslationService.cs	Hosted service sample consuming DeepL interfaces from DI.
samples/DependencyInjection/Program.cs	Generic-host sample wiring up AddDeepLClient.
samples/DependencyInjection/DependencyInjection.csproj	Sample project referencing DI package + Hosting.
samples/DeepL.Samples.slnx	Standalone samples solution file.
DeepLTests/FluentTranslationTest.cs	Unit tests for fluent text translation + rephrase builders.
DeepLTests/FluentStyleRuleTest.cs	Unit tests for fluent style-rule management builders/refs.
DeepLTests/FluentGlossaryTest.cs	Unit tests for fluent glossary builders/refs.
DeepLTests/FluentDocumentTranslationTest.cs	Unit tests for fluent document translation builders/refs including progress + cancellation.
DeepLTests/DeepLTests.csproj	Update test TFMs/packages to net8/net462 and newer test deps.
DeepL/Internal/LargeFormUrlEncodedContent.cs	Compile out workaround on modern TFMs (keep for pre-.NET5).
DeepL/Internal/JsonUtils.cs	Use JsonNamingPolicy.SnakeCaseLower + ReadFromJsonAsync on net8 with fallback.
DeepL/Internal/DeepLHttpClient.cs	Modernize HTTP internals (PATCH static, JSON/form helpers, SocketsHttpHandler, HTTP/2 defaults).
DeepL/FluentTranslation.cs	New fluent translation/rephrase API with awaitable builders and option helpers.
DeepL/FluentStyleRule.cs	New fluent API for style-rule management (refs + create builder).
DeepL/FluentGlossary.cs	New fluent API for multilingual glossary management (refs + create builder).
DeepL/FluentDocumentTranslation.cs	New fluent API for document translation (one-shot, split flow, progress + cancelable job).
DeepL/DeepL.csproj	Update TFMs/lang version and bump core dependencies.
DeepL.net.sln	Add DI projects to the main solution and expand configs.
DeepL.Extensions.DependencyInjection/README.md	Usage docs for the DI companion package.
DeepL.Extensions.DependencyInjection/DeepLServiceCollectionExtensions.cs	Implements AddDeepLClient registration and interface forwarding.
DeepL.Extensions.DependencyInjection/DeepLOptions.cs	Options contract for DI registration (AuthKey, ServerUrl, client name).
DeepL.Extensions.DependencyInjection/DeepL.Extensions.DependencyInjection.csproj	New package project targeting netstandard2.0/net8.0 with signing/pack settings.
DeepL.Extensions.DependencyInjection.Tests/DeepLServiceCollectionExtensionsTest.cs	Container-level tests for registration/validation/httpclient usage.
DeepL.Extensions.DependencyInjection.Tests/DeepL.Extensions.DependencyInjection.Tests.csproj	New test project for DI package (net8, updated test deps).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.