Skip to content

Commit 2ed45d4

Browse files
alexeyzimarevclaude
alexeyzimarev
and
claude
authored
Add v114 documentation and Docusaurus version snapshot (#2368)
* Add v114 documentation: changelog, RedirectOptions, parameter formatting, error handling - Add v114.0 changelog with breaking changes, new features, behavior changes, and bug fixes - Document RedirectOptions for fine-grained redirect control - Document MultipartFormQuoteParameters default change (false -> true) - Document InvariantCulture default for parameter formatting - Document improved ErrorMessage for timeouts and wrapped exceptions - Update options table entries for FollowRedirects, MaxRedirects, Expect100Continue - Create Docusaurus v114 versioned docs snapshot Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Add .DS_Store and .grok/ to .gitignore Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Fix code snippets in docs: Uri type, semicolons, property names, example constructor - Fix `new Url(...)` to `new Uri(...)` in configuration example - Remove stray semicolon in serialization lambda example - Replace deprecated `MaxTimeout` with `Timeout` in client docs - Replace `BaseAddress` with `BaseUrl` in HttpClient reuse section - Fix example constructor to use `RestClientOptions` instead of `IOptions<>` Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
1 parent 95b155a commit 2ed45d4

24 files changed

+2007
-20
lines changed

‎.gitignore‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -56,4 +56,6 @@ RestSharp.IntegrationTests/config.json
5656
/docs/.vuepress/dist/
5757
.vscode/
5858
.temp/
59-
*.trx
59+
*.trx
60+
.DS_Store
61+
.grok/

‎docs/docs/advanced/configuration.md‎

Lines changed: 48 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -62,8 +62,8 @@ For example:
6262

6363
```csharp
6464
var client = new RestClient(options => {
65-
options.BaseUrl = new Url("https://localhost:5000/api"),
66-
options.DisableCharset = true
65+
options.BaseUrl = new Uri("https://localhost:5000/api");
66+
options.DisableCharset = true;
6767
});
6868
```
6969

@@ -161,12 +161,13 @@ RestSharp allows configuring `RestClient` using client options, as mentioned at
161161
| `UseDefaultCredentials` | Whether to use default OS credentials for NTLM or Kerberos authentication. Not supported in browsers. |
162162
| `DisableCharset` | When set to `true`, the `Content-Type` header won't have the `charset` portion. Some older web servers don't understand the `charset` portion in the header and fail to process the request. |
163163
| `AutomaticDecompression` | Allows customizing supported decompression methods. Default is `All` except for .NET Framework that only support `GZip`. Not supported in browsers. |
164-
| `MaxRedirects` | The number of redirects to follow. Not supported in browsers. |
164+
| `MaxRedirects` | The number of redirects to follow. Delegates to `RedirectOptions.MaxRedirects`. Default is 50. |
165165
| `ClientCertificates` | A collection of X.509 client certificates to be used for authentication. Not supported in browsers. |
166166
| `Proxy` | Can be used if the client needs to use an explicit, non-default proxy. Not supported in browsers, on iOS and tvOS. |
167167
| `CachePolicy` | Shortcut for setting the default value for `Cache-Control` header. |
168-
| `FollowRedirects` | Instructs the client to follow redirects. Default is `true`. |
169-
| `Expect100Continue` | Gets or sets a value that indicates if the `Expect` header for an HTTP request contains `Continue`. |
168+
| `FollowRedirects` | Instructs the client to follow redirects. Default is `true`. Delegates to `RedirectOptions.FollowRedirects`. |
169+
| `RedirectOptions` | Fine-grained control over redirect behavior. See [Redirect Options](#redirect-options) below. |
170+
| `Expect100Continue` | Gets or sets a value that indicates if the `Expect` header for an HTTP request contains `Continue`. Set per-request, not on `HttpClient.DefaultRequestHeaders`. |
170171
| `UserAgent` | Allows overriding the default value for `User-Agent` header, which is `RestSharp/{version}`. |
171172
| `PreAuthenticate` | Gets or sets a value that indicates whether the client sends an `Authorization` header with the request. Not supported in browsers. |
172173
| `RemoteCertificateValidationCallback` | Custom function to validate the server certificate. Normally, it's used when the server uses a certificate that isn't trusted by default. |
@@ -186,10 +187,8 @@ Some of the options are used by RestSharp code, but some are only used to config
186187
- `UseDefaultCredentials`
187188
- `AutomaticDecompression`
188189
- `PreAuthenticate`
189-
- `MaxRedirects`
190190
- `RemoteCertificateValidationCallback`
191191
- `ClientCertificates`
192-
- `FollowRedirects`
193192
- `Proxy`
194193

195194
:::note
@@ -207,6 +206,7 @@ Client options apply to all requests made by the client. Sometimes, you want to
207206
| `AlwaysMultipartFormData` | When set to `true`, the request will be sent as a multipart form, even though it's not required. By default, RestSharp only sends requests with multiple attachments as multipart forms. Default is `false`. |
208207
| `AlwaysSingleFileAsContent` | When set to true, the request with file attachment will not be sent as a multipart form, but as plain content. Default is `false`. It cannot be set to `true` when `AlwaysMultipartFormData` is set to `true`, or when the request has `POST` parameters. |
209208
| `MultipartFormQuoteBoundary` | Default is `true`, which means that the form boundary string will be wrapped in quotes. If the server has an issue with that, setting this to `false` will remove quotes around the boundary. |
209+
| `MultipartFormQuoteParameters` | Whether to quote parameter names in multipart form `Content-Disposition` headers per RFC 7578. Default is `true` (changed from `false` in v114). |
210210
| `FormBoundary` | Allows specifying a custom multipart form boundary instead of using the default random string. |
211211
| `RequestParameters` | Collection of request parameters. Normally, you won't need to use it as parameters are added to the request using `Add...` functions. |
212212
| `CookieContainer` | Custom request-level cookie container. Default is `null`. You can still set request cookies using `AddCookie` and get response cookies from the response object without using cooking container. |
@@ -275,3 +275,44 @@ var longRunningRequest = new RestRequest("long-operation") {
275275
Timeout = Timeout.InfiniteTimeSpan
276276
};
277277
```
278+
279+
## Redirect Options
280+
281+
RestSharp handles redirects internally (rather than delegating to `HttpClient`) so it can capture `Set-Cookie` headers from intermediate redirect responses. The `RedirectOptions` class provides fine-grained control over redirect behavior.
282+
283+
The convenience properties `RestClientOptions.FollowRedirects` and `RestClientOptions.MaxRedirects` delegate to `RedirectOptions` for backward compatibility.
284+
285+
```csharp
286+
var options = new RestClientOptions("https://api.example.com") {
287+
RedirectOptions = new RedirectOptions {
288+
FollowRedirects = true,
289+
MaxRedirects = 10,
290+
ForwardAuthorization = true,
291+
FollowRedirectsToInsecure = false
292+
}
293+
};
294+
```
295+
296+
| Option | Default | Description |
297+
|-----------------------------------|---------|--------------------------------------------------------------------------------------------------------------|
298+
| `FollowRedirects` | `true` | Whether to follow redirects. |
299+
| `MaxRedirects` | `50` | Maximum number of redirects to follow. |
300+
| `FollowRedirectsToInsecure` | `false` | Whether to follow redirects from HTTPS to HTTP. |
301+
| `ForwardHeaders` | `true` | Whether to forward request headers on redirect. |
302+
| `ForwardAuthorization` | `false` | Whether to forward the `Authorization` header on same-host redirects. |
303+
| `ForwardAuthorizationToExternalHost` | `false` | Whether to forward `Authorization` on cross-host redirects. Only applies when `ForwardAuthorization` is true. |
304+
| `ForwardCookies` | `true` | Whether to forward cookies on redirect. `Set-Cookie` headers are always captured regardless. |
305+
| `ForwardBody` | `true` | Whether to forward the request body when the HTTP verb is preserved. Body is always dropped when verb changes to GET. |
306+
| `ForwardQuery` | `true` | Whether to forward the original query string parameters on redirect. |
307+
| `RedirectStatusCodes` | 301, 302, 303, 307, 308 | HTTP status codes considered as redirects. |
308+
309+
## Parameter formatting
310+
311+
By default, all generic parameter methods (`AddParameter<T>`, `AddQueryParameter<T>`, `AddUrlSegment<T>`, `AddHeader<T>`, etc.) format values using `CultureInfo.InvariantCulture`. This ensures consistent behavior regardless of the server's or client's locale.
312+
313+
If you need locale-specific formatting, pass a `CultureInfo` explicitly:
314+
315+
```csharp
316+
request.AddParameter("price", 1234.56, culture: new CultureInfo("da-DK"));
317+
// Sends: price=1234,56
318+
```

‎docs/docs/advanced/error-handling.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,8 @@ If there is a network transport error (network is down, failed DNS lookup, etc.)
55
If an API returns a 404, `ResponseStatus` will still be `Completed`. If you need access to the HTTP status code returned, you will find it at `RestResponse.StatusCode`.
66
The `Status` property is an indicator of completion independent of the API error handling.
77

8+
When a request times out, `ResponseStatus` is set to `TimedOut` and `ErrorMessage` will say `"The request timed out."`. For other transport errors, `ErrorMessage` shows the root cause by using `GetBaseException().Message`, so you see the actual error (e.g., a TLS failure) rather than a generic wrapper message like `"An error occurred while sending the request"`. The full exception chain is always available in `ErrorException`.
9+
810
Normally, RestSharp doesn't throw an exception if the request fails.
911

1012
However, it is possible to configure RestSharp to throw in different situations when it normally doesn't throw

‎docs/docs/advanced/serialization.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ You can tell RestSharp to use a custom serializer by using the `configureSeriali
1616
```csharp
1717
var client = new RestClient(
1818
options,
19-
configureSerialization: s => s.UseSerializer(() => new CustomSerializer());
19+
configureSerialization: s => s.UseSerializer(() => new CustomSerializer())
2020
);
2121
```
2222

‎docs/docs/changelog.md‎

Lines changed: 30 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -10,10 +10,36 @@ For release notes of previous versions, please check the [Releases page](https:/
1010

1111
Changes between major versions are documented in the documentation for each version on this website.
1212

13-
# v112.0
13+
## v114.0
1414

15-
* Security fix for [CVE-2024-45302](https://github.com/restsharp/RestSharp/security/advisories/GHSA-4rr6-2v9v-wcpc). Header values cannot contain `CRLF`.
15+
### Breaking changes
1616

17-
## v112.1
17+
* **`IAuthenticator` interface signature changed** — `Authenticate` now accepts an optional `CancellationToken` parameter. All custom authenticator implementations must be recompiled. ([#2362](https://github.com/restsharp/RestSharp/pull/2362))
18+
* **`FollowRedirects` and `MaxRedirects` removed from `ReadOnlyRestClientOptions`** — these properties are now excluded from the generated immutable wrapper. Use `RedirectOptions` instead. Code accessing these properties on `ReadOnlyRestClientOptions` must be updated. ([#2360](https://github.com/restsharp/RestSharp/pull/2360))
19+
* **Extension method signatures changed** — `AddParameter<T>`, `AddOrUpdateParameter<T>`, `AddHeader<T>`, `AddOrUpdateHeader<T>`, `AddQueryParameter<T>`, and `AddUrlSegment<T>` now have an additional optional `CultureInfo? culture` parameter. Assemblies compiled against v113 must be recompiled. ([#2354](https://github.com/restsharp/RestSharp/pull/2354))
1820

19-
* Follow up on v112.0 security fix: remove `\t` from the list of forbidden characters in headers.
21+
### New features
22+
23+
* **OAuth2 token lifecycle authenticators** — new `OAuth2ClientCredentialsAuthenticator`, `OAuth2RefreshTokenAuthenticator`, and `OAuth2TokenAuthenticator` that handle obtaining, caching, and refreshing tokens automatically. ([#2362](https://github.com/restsharp/RestSharp/pull/2362))
24+
* **Custom redirect handling with `RedirectOptions`** — RestSharp now manages redirects internally instead of delegating to `HttpClient`, fixing lost `Set-Cookie` headers on redirects. New `RedirectOptions` class provides fine-grained control over redirect behavior. ([#2360](https://github.com/restsharp/RestSharp/pull/2360))
25+
* **`MergedParameters` on `RestResponse`** — provides a combined view of request and default parameters at execution time, useful for logging and debugging. ([#2349](https://github.com/restsharp/RestSharp/pull/2349))
26+
* **Restored `AddCookie(name, value)` overload** — the simple two-parameter form defers domain resolution to execution time. ([#2351](https://github.com/restsharp/RestSharp/pull/2351))
27+
28+
### Behavior changes
29+
30+
* **`MultipartFormQuoteParameters` now defaults to `true`** — multipart form parameter names are now quoted per RFC 7578. ([#2357](https://github.com/restsharp/RestSharp/pull/2357))
31+
* **`InvariantCulture` used for parameter formatting** — all generic parameter methods now format values using `CultureInfo.InvariantCulture` by default. Pass a `CultureInfo` explicitly if locale-specific formatting is needed. ([#2354](https://github.com/restsharp/RestSharp/pull/2354))
32+
* **Improved `ErrorMessage` for timeouts** — now shows `"The request timed out."` instead of `"A task was canceled."`. ([#2356](https://github.com/restsharp/RestSharp/pull/2356))
33+
* **`ErrorMessage` surfaces root cause** — uses `GetBaseException().Message` to show the actual error instead of generic wrapper messages. ([#2352](https://github.com/restsharp/RestSharp/pull/2352))
34+
* **`HttpClient.DefaultRequestHeaders` no longer modified** — `Expect100Continue` is now set per-request. Safe to share an `HttpClient` across multiple `RestClient` instances. ([#2363](https://github.com/restsharp/RestSharp/pull/2363))
35+
36+
### Bug fixes
37+
38+
* Fix `ConfigureAwait(false)` missing on several `await` calls, preventing deadlocks in sync-over-async scenarios. ([#2367](https://github.com/restsharp/RestSharp/pull/2367))
39+
* Fix `ResponseUri` returning original URL instead of redirect target when `FollowRedirects=false`. ([#2350](https://github.com/restsharp/RestSharp/pull/2350))
40+
* Fix default parameter merging bugs (multi-value dedup, request mutation, `BuildUriString` without execute). ([#2349](https://github.com/restsharp/RestSharp/pull/2349))
41+
* Fix OAuth1 double-encoding of RFC 3986 special characters in URL paths. ([#2341](https://github.com/restsharp/RestSharp/pull/2341))
42+
* Fix pipe character encoding when `AddQueryParameter` is used with `encode=false`. ([#2345](https://github.com/restsharp/RestSharp/pull/2345))
43+
* Fix `XmlDeserializer` when XML uses same tag name in nested elements. ([#2339](https://github.com/restsharp/RestSharp/pull/2339))
44+
* Fix credential/`UseDefaultCredentials` property order on `HttpClientHandler`. ([#2353](https://github.com/restsharp/RestSharp/pull/2353))
45+
* Fix URL escaping on .NET Framework 4.6.2. ([#2327](https://github.com/restsharp/RestSharp/pull/2327))

‎docs/docs/usage/client.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@ Here's an example of how to create a client using the same base path as in the p
2424
```csharp
2525
// Creates a client using the options object
2626
var options = new RestClientOptions("https://localhost:5000") {
27-
MaxTimeout = 1000
27+
Timeout = TimeSpan.FromSeconds(1)
2828
};
2929
var client = new RestClient(options);
3030
```
@@ -47,7 +47,7 @@ Another way to create the client instance is to use a simple client factory. The
4747
* `RemoteCertificateValidationCallback`
4848
* `ClientCertificates`
4949
* `MaxRedirects`
50-
* `MaxTimeout`
50+
* `Timeout`
5151
* `UserAgent`
5252
* `Expect100Continue`
5353

@@ -66,8 +66,8 @@ RestSharp uses `HttpClient` internally to make HTTP requests. It's possible to r
6666

6767
One way of doing it is to use `RestClient` constructors that accept an instance of `HttpClient` or `HttpMessageHandler` as an argument. Note that in that case not all the options provided via `RestClientOptions` will be used. Here is the list of options that will work:
6868

69-
- `BaseAddress` is be used to set the base address of the `HttpClient` instance if base address is not set there already.
70-
- `MaxTimeout` is used to cancel the call using the cancellation token source, so
69+
- `BaseUrl` will be taken from `httpClient.BaseAddress` if not set explicitly.
70+
- `Timeout` is used to cancel the call using the cancellation token source.
7171
- `UserAgent` will be added to the `RestClient.DefaultParameters` list as a HTTP header. This will be added to each request made by the `RestClient`, and the `HttpClient` instance will not be modified. This is to allow the `HttpClient` instance to be reused for scenarios where different `User-Agent` headers are required.
7272
- `Expect100Continue`
7373

0 commit comments

Comments
 (0)