Skip to content

Commit 3831d52

Browse files
Copilotalexeyzimarev
Copilot
and
alexeyzimarev
authored
Document Timeout property behavior for RestClientOptions and RestRequest (#2331)
* Initial plan * Document Timeout behavior for RestClientOptions and RestRequest Co-authored-by: alexeyzimarev <2821205+alexeyzimarev@users.noreply.github.com> * Improve timeout documentation with dedicated section Co-authored-by: alexeyzimarev <2821205+alexeyzimarev@users.noreply.github.com> * Add migration note about MaxTimeout to Timeout property Co-authored-by: alexeyzimarev <2821205+alexeyzimarev@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: alexeyzimarev <2821205+alexeyzimarev@users.noreply.github.com> Co-authored-by: Alexey Zimarev <alex@zimarev.com>
1 parent eb9e3d1 commit 3831d52

3 files changed

Lines changed: 68 additions & 5 deletions

File tree

‎docs/docs/advanced/configuration.md‎

Lines changed: 49 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -172,7 +172,7 @@ RestSharp allows configuring `RestClient` using client options, as mentioned at
172172
| `RemoteCertificateValidationCallback` | Custom function to validate the server certificate. Normally, it's used when the server uses a certificate that isn't trusted by default. |
173173
| `BaseHost` | Value for the `Host` header sent with each request. |
174174
| `CookieContainer` | Custom cookie container that will be shared among all calls made by the client. Normally not required as RestSharp handles cookies without using a client-level cookie container. |
175-
| `MaxTimeout` | Client-level timeout in milliseconds. If the request timeout is also set, this value isn't used. |
175+
| `Timeout` | Client-level timeout as `TimeSpan`. Default is 100 seconds. See [Configuring Timeouts](#configuring-timeouts) for details on timeout behavior. |
176176
| `Encoding` | Default request encoding. Override it only if you don't use UTF-8. |
177177
| `ThrowOnDeserializationError` | Forces the client to throw if it fails to deserialize the response. Remember that not all deserialization issues forces the serializer to throw. Default is `false`, so the client will return a `RestResponse` with deserialization exception details. Only relevant for `Execute...` functions. |
178178
| `FailOnDeserializationError` | When set to `true`, if the client fails to deserialize the response, the response object will have status `Failed`, although the HTTP calls might have been successful. Default is `true`. |
@@ -213,7 +213,7 @@ Client options apply to all requests made by the client. Sometimes, you want to
213213
| `Authenticator` | Overrides the client-level authenticator. |
214214
| `Files` | Collection of file parameters, read-only. Use `AddFile` for adding files to the request. |
215215
| `Method` | Request HTTP method, default is `GET`. Only needed when using `Execute` or `ExecuteAsync` as other functions like `ExecutePostAsync` will override the request method. |
216-
| `TImeout` | Overrides the client-level timeout. |
216+
| `Timeout` | Request-level timeout override. See [Configuring Timeouts](#configuring-timeouts) for details on timeout behavior. |
217217
| `Resource` | Resource part of the remote endpoint URL. For example, when using the client-level base URL `https://localhost:5000/api` and `Resource` set to `weather`, the request will be sent to `https://localhost:5000/api/weather`. It can container resource placeholders to be used in combination with `AddUrlSegment` |
218218
| `RequestFormat` | Identifies the request as JSON, XML, binary, or none. Rarely used because the client will set the request format based on the body type if functions like `AddJsonBody` or `AddXmlBody` are used. |
219219
| `RootElement` | Used by the default deserializers to determine where to start deserializing from. Only supported for XML responses. Does not apply to requests. |
@@ -228,3 +228,50 @@ Client options apply to all requests made by the client. Sometimes, you want to
228228
| `Interceptors` | Allows adding interceptors to the request. Both client-level and request-level interceptors will be called. |
229229

230230
The table below contains all configuration properties of `RestRequest`. To learn more about adding request parameters, check the [usage page](../usage/request.md) page about creating requests with parameters.
231+
232+
## Configuring Timeouts
233+
234+
RestSharp provides flexible timeout configuration at both the client and request levels. The timeout determines how long RestSharp will wait for a response before canceling the request.
235+
236+
:::note Migration from MaxTimeout
237+
In older versions of RestSharp, the `MaxTimeout` property (measured in milliseconds) was used. This has been replaced by the `Timeout` property, which uses `TimeSpan` for more intuitive and type-safe timeout configuration.
238+
:::
239+
240+
### Timeout Resolution
241+
242+
When making a request, RestSharp uses the following priority order to determine the timeout:
243+
1. `RestRequest.Timeout` (if set)
244+
2. `RestClientOptions.Timeout` (if set)
245+
3. Default timeout of 100 seconds
246+
247+
### Timeout Values
248+
249+
The `Timeout` property accepts a `TimeSpan?` value and supports the following behaviors:
250+
251+
| Value | Behavior |
252+
|-------|----------|
253+
| `null` (not set) | Uses the next level timeout (client timeout, then default 100 seconds) |
254+
| Positive `TimeSpan` | Request times out after the specified duration (e.g., `TimeSpan.FromSeconds(30)`) |
255+
| `Timeout.InfiniteTimeSpan` or `TimeSpan.FromMilliseconds(-1)` | No timeout - request will wait indefinitely for a response |
256+
| `TimeSpan.Zero` | Request is canceled immediately (effectively no time allowed for the request) |
257+
| Other negative values | Throws `ArgumentOutOfRangeException` when the request is executed |
258+
259+
### Examples
260+
261+
```csharp
262+
// Client-level timeout of 30 seconds
263+
var options = new RestClientOptions("https://api.example.com") {
264+
Timeout = TimeSpan.FromSeconds(30)
265+
};
266+
var client = new RestClient(options);
267+
268+
// Request-level timeout override
269+
var request = new RestRequest("resource") {
270+
Timeout = TimeSpan.FromSeconds(60) // This request gets 60 seconds
271+
};
272+
273+
// Infinite timeout (no timeout)
274+
var longRunningRequest = new RestRequest("long-operation") {
275+
Timeout = Timeout.InfiniteTimeSpan
276+
};
277+
```

‎src/RestSharp/Options/RestClientOptions.cs‎

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -183,8 +183,16 @@ public RestClientOptions(string baseUrl) : this(new Uri(Ensure.NotEmptyString(ba
183183
public CookieContainer? CookieContainer { get; set; }
184184

185185
/// <summary>
186-
/// Request duration. Used when the request timeout is not specified using <seealso cref="RestRequest.Timeout"/>,
187-
/// </summary>
186+
/// Request timeout duration. Used when the request timeout is not specified using <seealso cref="RestRequest.Timeout"/>.
187+
/// If not set, the default timeout is 100 seconds.
188+
/// </summary>
189+
/// <remarks>
190+
/// <list type="bullet">
191+
/// <item><description>Set to <see cref="System.Threading.Timeout.InfiniteTimeSpan"/> (or <c>TimeSpan.FromMilliseconds(-1)</c>) for no timeout</description></item>
192+
/// <item><description>Set to <see cref="TimeSpan.Zero"/> to cancel the request immediately</description></item>
193+
/// <item><description>Negative values (other than -1 millisecond) will throw <see cref="ArgumentOutOfRangeException"/></description></item>
194+
/// </list>
195+
/// </remarks>
188196
public TimeSpan? Timeout { get; set; }
189197

190198
/// <summary>

‎src/RestSharp/Request/RestRequest.cs‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -131,8 +131,16 @@ public RestRequest(Uri resource, Method method = Method.Get)
131131
public Method Method { get; set; }
132132

133133
/// <summary>
134-
/// Custom request timeout
134+
/// Custom request timeout. Overrides <see cref="RestClientOptions.Timeout"/> if set.
135+
/// If not set, uses the client-level timeout or the default of 100 seconds.
135136
/// </summary>
137+
/// <remarks>
138+
/// <list type="bullet">
139+
/// <item><description>Set to <see cref="System.Threading.Timeout.InfiniteTimeSpan"/> (or <c>TimeSpan.FromMilliseconds(-1)</c>) for no timeout</description></item>
140+
/// <item><description>Set to <see cref="TimeSpan.Zero"/> to cancel the request immediately</description></item>
141+
/// <item><description>Negative values (other than -1 millisecond) will throw <see cref="ArgumentOutOfRangeException"/></description></item>
142+
/// </list>
143+
/// </remarks>
136144
public TimeSpan? Timeout { get; set; }
137145

138146
/// <summary>

0 commit comments

Comments
 (0)