You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Another way to create the client instance is to use a simple client factory. The factory will use the `BaseUrl` property of the client options to cache `HttpClient` instances. Every distinct base URL will get its own `HttpClient` instance. Other options don't affect the caching. Therefore, if you use different options for the same base URL, you'll get the same `HttpClient` instance, which will not be configured with the new options. Options that aren't applied _after_ the first client instance is created are:
156
+
157
+
*`Credentials`
158
+
*`UseDefaultCredentials`
159
+
*`AutomaticDecompression`
160
+
*`PreAuthenticate`
161
+
*`FollowRedirects`
162
+
*`RemoteCertificateValidationCallback`
163
+
*`ClientCertificates`
164
+
*`MaxRedirects`
165
+
*`MaxTimeout`
166
+
*`UserAgent`
167
+
*`Expect100Continue`
168
+
169
+
Constructor parameters to configure the `HttpMessageHandler` and default `HttpClient` headers configuration are also ignored for the cached instance as the factory only configures the handler once.
170
+
171
+
You need to set the `useClientFactory` parameter to `true` in the `RestClient` constructor to enable the factory.
Before making a request using `RestClient`, you need to create a request instance:
@@ -166,9 +190,23 @@ var request = new RestRequest(resource, Method.Post);
166
190
167
191
After you've created a `RestRequest`, you can add parameters to it. Below, you can find all the parameter types supported by RestSharp.
168
192
169
-
### Http Header
193
+
### Headers
194
+
195
+
Adds the header parameter as an HTTP header that is sent along with the request. The header name is the parameter's name and the header value is the value.
196
+
197
+
You can use one of the following request methods to add a header parameter:
198
+
199
+
```csharp
200
+
AddHeader(stringname, stringvalue);
201
+
AddHeader<T>(stringname, Tvalue); // value will be converted to string
202
+
AddOrUpdateHeader(stringname, stringvalue); // replaces the header if it already exists
203
+
```
204
+
205
+
You can also add header parameters to the client, and they will be added to every request made by the client. This is useful for adding authentication headers, for example.
170
206
171
-
Adds the parameter as an HTTP header that is sent along with the request. The header name is the parameter's name and the header value is the value.
207
+
```csharp
208
+
client.AddDefaultHeader(stringname, stringvalue);
209
+
```
172
210
173
211
::: warning Content-Type
174
212
RestSharp will use the correct content type by default. Avoid adding the `Content-Type` header manually to your requests unless you are absolutely sure it is required. You can add a custom content type to the [body parameter](#request-body) itself.
You can also add `GetOrPost` parameter as a default parameter to the client. This will add the parameter to every request made by the client.
233
+
234
+
```csharp
235
+
client.AddDefaultParameter("foo", "bar");
236
+
```
237
+
238
+
It will work the same way as request parameters, except that it will be added to every request.
239
+
194
240
#### AddObject
195
241
196
242
You can avoid calling `AddParameter` multiple times if you collect all the parameters in an object, and then use `AddObject`.
@@ -241,6 +287,26 @@ var request = new RestRequest("health/{entity}/status")
241
287
242
288
When the request executes, RestSharp will try to match any `{placeholder}` with a parameter of that name (without the `{}`) and replace it with the value. So the above code results in `health/s2/status` being the url.
243
289
290
+
You can also add `UrlSegment` parameter as a default parameter to the client. This will add the parameter to every request made by the client.
291
+
292
+
```csharp
293
+
client.AddDefaultUrlSegment("foo", "bar");
294
+
```
295
+
296
+
### Cookies
297
+
298
+
You can add cookies to a request using the `AddCookie` method:
299
+
300
+
```csharp
301
+
request.AddCookie("foo", "bar");
302
+
```
303
+
304
+
RestSharp will add cookies from the request as cookie headers and then extract the matching cookies from the response. You can observe and extract response cookies using the `RestResponse.Cookies` properties, which has the `CookieCollection` type.
305
+
306
+
However, the usage of a default URL segment parameter is questionable as you can just include the parameter value to the base URL of the client. There is, however, a `CookieContainer` instance on the request level. You can either assign the pre-populated container to `request.CookieContainer`, or let the container be created by the request when you call `AddCookie`. Still, the container is only used to extract all the cookies from it and create cookie headers for the request instead of using the container directly. It's because the cookie container is normally configured on the `HttpClientHandler` level and cookies are shared between requests made by the same client. In most of the cases this behaviour can be harmful.
307
+
308
+
If your use case requires sharing cookies between requests made by the client instance, you can use the client-level `CookieContainer`, which you must provide as the options' property. You can add cookies to the container using the container API. No response cookies, however, would be auto-added to the container, but you can do it in code by getting cookies from the `Cookes` property of the response and adding them to the client-level container available via `IRestClient.Options.CookieContainer` property.
309
+
244
310
### Request Body
245
311
246
312
RestSharp supports multiple ways to add a request body:
@@ -252,6 +318,8 @@ We recommend using `AddJsonBody` or `AddXmlBody` methods instead of `AddParamete
252
318
253
319
When you make a `POST`, `PUT` or `PATCH` request and added `GetOrPost`[parameters](#get-or-post), RestSharp will send them as a URL-encoded form request body by default. When a request also has files, it will send a `multipart/form-data` request. You can also instruct RestSharp to send the body as `multipart/form-data` by setting the `AlwaysMultipartFormData` property to `true`.
254
320
321
+
It is not possible to add client-level default body parameters.
322
+
255
323
#### AddStringBody
256
324
257
325
If you have a pre-serialized payload like a JSON string, you can use `AddStringBody` to add it as a body parameter. You need to specify the content type, so the remote endpoint knows what to do with the request body. For example:
@@ -322,6 +390,14 @@ To do so, set the `encode` argument to `false` when adding the parameter:
You can also add a query string parameter as a default parameter to the client. This will add the parameter to every request made by the client.
394
+
395
+
```csharp
396
+
client.AddDefaultQueryParameter("foo", "bar");
397
+
```
398
+
399
+
The line above will result in all the requests made by that client instance to have `foo=bar` in the query string for all the requests made by that client.
400
+
325
401
## Making a call
326
402
327
403
Once you've added all the parameters to your `RestRequest`, you are ready to make a request.
All the overloads that return `RestResponse` or `RestResponse<T>` don't throw an exception if the server returns an error. Read more about it [here](error-handling.md).
433
+
All the overloads with names starting with `Execute` don't throw an exception if the server returns an error. Read more about it [here](error-handling.md).
358
434
359
435
If you just need a deserialized response, you can use one of the extensions:
Those extensions will throw an exception if the server returns an error, as there's no other way to float the error back to the caller.
371
447
448
+
The `IRestClient` interface also has extensions for making requests without deserialization, which throw an exception if the server returns an error even if the client is configured to not throw exceptions.
To make a simple `GET` call and get a deserialized JSON response with a pre-formed resource string, use this:
@@ -474,15 +561,7 @@ One way of doing it is to use `RestClient` constructors that accept an instance
474
561
-`UserAgent` will be set if the `User-Agent` header is not set on the `HttpClient` instance already.
475
562
-`Expect100Continue`
476
563
477
-
Another option is to use a simple HTTP client factory. It is a static factory, which holds previously instantiated `HttpClient` instances. It can be used to create `RestClient` instances that share the same `HttpClient` instance. The cache key is the `BaseUrl` provided in the options. When you opt-in to use the factory and don't set `BaseUrl`, the `RestClient` constructor will crash.
Note that the `RestClient` constructor will not reconfigure the `HttpClient` instance if it's already in the cache. Therefore, you should not try using the factory when providing different options for the same base URL.
485
-
:::
564
+
Another option is to use a simple HTTP client factory as described [above](#simple-factory).
0 commit comments