Refit 14.0.0

Refit 14 is a major bug-fix and request-generation release. It fixes a broad set of correctness issues while completing the move to source-generated request building. Most clients can now build requests without runtime reflection, improving trimming, Native AOT support, startup time, and allocations.

What end users need to know

• Check RF006 warnings before upgrading. The reflection request builder has moved out of the main package. If any API method reports RF006, add the Refit.Reflection package. Fully generated clients should not add it.
• Some async APIs now return ValueTask. This affects the success-guard methods, DefaultApiExceptionFactory.CreateAsync, and several RefitSettings delegates. Most callers can continue to await them; code that stores a Task may need .AsTask().
• A few request-building behaviours are intentionally different. Query objects are flattened from their declared type, serializer property names are honoured in query keys, and nested URL-encoded objects are flattened instead of using ToString().
• Caller-owned streams remain open. Refit no longer disposes streams supplied as request bodies or multipart parts; callers are responsible for disposing them.
• Validation timing can change. Fully generated interfaces validate route templates when the first request is built rather than when the client is created. Generated method frames also no longer appear in ApiException stack traces.
• Empty authorization tokens now omit the header. Returning null, empty, or whitespace from AuthorizationHeaderValueGetter no longer sends a blank Authorization header.

Major fixes

• Request generation now handles multiple generic overloads, escaped C# keyword identifiers, nullable value-type query objects, nested URL-encoded bodies, and indexed query collections correctly.
• Caller-supplied request streams can be reused, generated helper types no longer collide across InternalsVisibleTo assemblies, and null parameter values round-trip correctly.

Highlights

• New request controls include [PathPrefix], per-method [Timeout], absolute URLs with [Url], optional route segments, indexed query collections, header validation, and returning a built HttpRequestMessage without sending it.
• Query objects, dictionaries, generic methods, multipart form objects, and custom return-type adapters gain broader reflection-free generation.
• Server-Sent Events can be consumed as IAsyncEnumerable<T>, and transport exceptions can be customized with TransportExceptionFactory.
• Runtime, reflection, and source-generator allocation reductions improve throughput; source generation is roughly twice as fast in the measured workload.

See the V14 migration details and complete feature documentation.

🗞️ What's Changed

💥 Breaking Changes

• [e511df] feat!: reflection-free source-generated request building (#2210) @glennawatson @TimothyMakkison

✨ Features

• [88e1c2] feat: add generic tests to ReflectionTests (#2195) @TimothyMakkison
• [463f5c] feat: add [Timeout] attribute for per-method request timeouts (#2238) @glennawatson
• [294e63] feat: add success guards to the non-generic IApiResponse (#2242) @glennawatson
• [f75468] feat: add interface-level [PathPrefix] attribute for a shared route prefix (#2240) @glennawatson
• [65f864] feat: only generate AttributeProvider field when not empty (#2271) @TimothyMakkison
• [99c055] feat: support optional url segments with {name?} syntax (#2237) @glennawatson
• [759a3c] feat: support returning the built HttpRequestMessage without sending (#2235) @glennawatson
• [88d5e6] feat: add CollectionFormat.Indexed for indexed query collection expansion (#2262) @Copilot @glennawatson @jgarciadelanoceda
• [d9b3d5] feat: support Server-Sent Events as a streaming content format (#2232) @glennawatson
• [1e35cc] feat: add [Url] attribute for absolute request URLs (#2236) @glennawatson
• [7c3387] feat: add opt-in RefitSettings.ValidateHeaders (#2225) @glennawatson
• [b583a3] feat: add null handling for round trip parameter and add verifying test (#2201) @TimothyMakkison
• [485c63] feat: opt-in [FormObject] flattens a model into multipart form fields (#2245) @glennawatson
• [7ac3e1] feat: fix failiure when multiple generic overloads (#2199) @TimothyMakkison
• [852cb2] feat: move version configuration into AddConfiguredRequestOptions (#2214) @glennawatson @TimothyMakkison
• [a2b158] feat: add analyzer diagnostics for invalid Refit interfaces (#2220) @glennawatson
• [4068d9] feature: Create a TransportExceptionFactory to let the user decide the exception to be thrown (#2205) @glennawatson @jgarciadelanoceda
• [ed6352] feat: optional auth header and scoped authorization token provider (#2221) @glennawatson
• [7bf7b4] feat: inline constrained-generic path-bound objects in the source generator (#2222) @glennawatson
• [14895a] feat: expose call argument values to DelegatingHandlers (#2223) @glennawatson
• [37efb4] feat: add per-type URL parameter formatter registry (#2226) @glennawatson
• [aa1c19] feat: publish method name and route template in request options (#2239) @glennawatson

♻️ Refactoring

• [aa2229] refactor: resolve analyzer diagnostics across solution (#2268) @ChrisPulman

🐛 Fixes

• [8e4237] fix:Analyzer false positive on Indexed CollectionFormat (#2274) @jgarciadelanoceda
• [809de1] fix: do not dispose caller-supplied request streams (#2234) @glennawatson
• [71634f] fix: escape keyword identifiers in generated interface member names (#2248) @glennawatson
• [17c24d] fix: name generated helper types per assembly to avoid InternalsVisibleTo conflicts (#2257) @glennawatson
• [78271e] fix: generate inline query building for nullable value-type query objects (#2265) @rmja
• [02a037] fix: flatten nested objects in url-encoded request bodies (#2224) @glennawatson

⚡ Performance

• [147282] perf: replace StringBuilder with ValueStringBuilder in RoundTripEscapePath (#2253) @TimothyMakkison
• [b19349] perf: replace StringBuilder with ValueStringBuilder (#2270) @TimothyMakkison
• [eb9291] perf: call PooledStringBuilder directly and remove ConcatParts and JoinParts (#2275) @TimothyMakkison
• [b575c9] perf: AllAttributesCache replace Lazy with laziliy initialised code (#2211) @TimothyMakkison
• [8382be] perf: reduce Refit.Reflection memory allocations (#2267) @glennawatson
• [fc06c5] perf: check for allowUnmatchedParameter before calling IndexOf (#2252) @TimothyMakkison
• [f24d17] perf: wrap helper methods in MethodImplOptions.AggressiveInlining (#2260) @TimothyMakkison
• [8cea3f] perf: reduce runtime Refit memory allocations (#2263) @glennawatson
• [5dcfcc] perf: cut source generator allocations and roughly halve generation time (#2259) @glennawatson

🧹 General Changes

• [44f81d] ci: gate native AOT smoke test via shared reusable workflow (#2244) @glennawatson
• [a9932f] chore: enable 1000 lines for real @glennawatson
• [393b24] ci: add alpha/beta/rc pre-release channel to release workflow @glennawatson
• [8cc1c3] chore: Relax number of file lines to 1000 lines instead of 500 @glennawatson

✅ Tests

• [e5da8b] test: reach 100% product code coverage (#2243) @glennawatson
• [865d0f] test(refit.testing): cover retry and timeout scenarios (#2208) @glennawatson
• [e67c5c] test: cover TransportExceptionFactory cancellation and timeout behavior (#2203) @arpitjain099 @glennawatson

📝 Documentation

• [544db0] docs: make v12 Error.Content migration discoverable and add interface composition example (#2217) @glennawatson
• [69eb3e] docs: document IQueryConverter and httpClientName client-name override (#2233) @glennawatson

📦 Dependencies

• Combined package, analyzer, and workflow dependency updates: NuGet dependencies and analyzers ([3d0546], [ddc42c], [5cd9a9]); Verify.DiffPlex 3.3.1 ([841ff0]); Verify.TUnit 31.24.2, 31.24.3, 31.25.0, and 31.27.0 ([136d00], [e1512d], [fb87be], [cf77d8]); actions/setup-dotnet v6 ([b920e2]); and the lock-threads workflow action ([d688b1]).

🔗 Full Changelog: https://github.com/reactiveui/refit/compare/v13.1.0...v14.0.0

🙌 Contributions

🌱 New contributors since the last release: @arpitjain099, @jgarciadelanoceda, @rmja 💖 Thanks to all the contributors: @arpitjain099, @ChrisPulman, @Copilot, @glennawatson, @jgarciadelanoceda, @rmja, @TimothyMakkison

🤖 Automated services that contributed: @renovate[bot]