|
| 1 | +--- |
| 2 | +title: Interceptors |
| 3 | +--- |
| 4 | + |
| 5 | +## Intercepting requests and responses |
| 6 | + |
| 7 | +Interceptors are a powerful feature of RestSharp that allows you to modify requests and responses before they are sent or received. You can use interceptors to add headers, modify the request body, or even cancel the request. You can also use interceptors to modify the response before it is returned to the caller. |
| 8 | + |
| 9 | +### Implementing an interceptor |
| 10 | + |
| 11 | +To implement an interceptor, you need to create a class that inherits the `Interceptor` base class. The base class implements all interceptor methods as virtual, so you can override them in your derived class. |
| 12 | + |
| 13 | +Methods that you can override are: |
| 14 | +- `BeforeRequest(RestRequest request, CancellationToken cancellationToken)` |
| 15 | +- `AfterRequest(RestResponse response, CancellationToken cancellationToken)` |
| 16 | +- `BeforeHttpRequest(HttpRequestMessage requestMessage, CancellationToken cancellationToken)` |
| 17 | +- `AfterHttpResponse(HttpResponseMessage responseMessage, CancellationToken cancellationToken)` |
| 18 | +- `BeforeDeserialization(RestResponse response, CancellationToken cancellationToken)` |
| 19 | + |
| 20 | +All those functions must return a `ValueTask` instance. |
| 21 | + |
| 22 | +Here's an example of an interceptor that adds a header to a request: |
| 23 | + |
| 24 | +```csharp |
| 25 | +// This interceptor adds a header to the request |
| 26 | +// You'd not normally use this interceptor, as RestSharp already has a method |
| 27 | +// to add headers to the request |
| 28 | +class HeaderInterceptor(string headerName, string headerValue) : Interceptors.Interceptor { |
| 29 | + public override ValueTask BeforeHttpRequest(HttpRequestMessage requestMessage, CancellationToken cancellationToken) { |
| 30 | + requestMessage.Headers.Add(headerName, headerValue); |
| 31 | + return ValueTask.CompletedTask; |
| 32 | + } |
| 33 | +} |
| 34 | +``` |
| 35 | + |
| 36 | +Because interceptor functions return `ValueTask`, you can use `async` and `await` inside them. |
| 37 | + |
| 38 | +### Using an interceptor |
| 39 | + |
| 40 | +It's possible to add as many interceptors as you want, both to the client and to the request. The interceptors are executed in the order they were added. |
| 41 | + |
| 42 | +Adding interceptors to the client is done via the client options: |
| 43 | + |
| 44 | +```csharp |
| 45 | +var options = new RestClientOptions("https://api.example.com") { |
| 46 | + Interceptors = [new HeaderInterceptor("Authorization", token)] |
| 47 | +}; |
| 48 | +var client = new RestClient(options); |
| 49 | +``` |
| 50 | + |
| 51 | +When you add an interceptor to the client, it will be executed for every request made by that client. |
| 52 | + |
| 53 | +You can also add an interceptor to a specific request: |
| 54 | + |
| 55 | +```csharp |
| 56 | +var request = new RestRequest("resource") { |
| 57 | + Interceptors = [new HeaderInterceptor("Authorization", token)] |
| 58 | +}; |
| 59 | +``` |
| 60 | + |
| 61 | +In this case, the interceptor will only be executed for that specific request. |
| 62 | + |
| 63 | +### Deprecation notice |
| 64 | + |
| 65 | +Interceptors aim to replace the existing request hooks available in RestSharp prior to version 111.0. Those hooks are marked with `Obsolete` attribute and will be removed in the future. If you are using those hooks, we recommend migrating to interceptors as soon as possible. |
| 66 | + |
| 67 | +To make the migration easier, RestSharp provides a class called `CompatibilityInterceptor`. It has properties for the hooks available in RestSharp 110.0 and earlier. You can use it to migrate your code to interceptors without changing the existing logic. |
| 68 | + |
| 69 | +For example, a code that uses `OnBeforeRequest` hook: |
| 70 | + |
| 71 | +```csharp |
| 72 | +var request = new RestRequest("success"); |
| 73 | +request.OnBeforeDeserialization += _ => throw new Exception(exceptionMessage); |
| 74 | +``` |
| 75 | + |
| 76 | +Can be migrated to interceptors like this: |
| 77 | + |
| 78 | +```csharp |
| 79 | +var request = new RestRequest("success") { |
| 80 | + Interceptors = [new CompatibilityInterceptor { |
| 81 | + OnBeforeDeserialization = _ => throw new Exception(exceptionMessage) |
| 82 | + }] |
| 83 | +}; |
| 84 | +``` |
0 commit comments