---
title: Configure options
summary: Replace the retry, header-persistence, and serializer behavior used for subsequent requests.
status: draft
owner: Framework
last_reviewed: 2026-10-02
library: SAIF.NetCore.HttpClients
reference_type: package
operation_id: OP-03
trigger: A consumer calls SetOptions(HttpClientOptions) on an HttpJsonClient instance
---

# Configure options

`SetOptions` replaces the full `HttpClientOptions` on an `HttpJsonClient` instance, controlling header persistence across requests, the retry delay and retryable status codes, and the RestSharp client/handler serializer selection used when the request is built. This serializer selection governs RestSharp's own internal handling of the outgoing request only; it does not affect how [Consume result](consume-result.md) converts the returned content.

| Field | Value |
| --- | --- |
| **Operation ID** | OP-03 |
| **Trigger** | A consumer calls `SetOptions(HttpClientOptions)` |
| **Inputs** | An `HttpClientOptions` instance: `PersistHeadersAfterRequest`, `RetryDelayInMs`, `RetryOnStatusCodes`, `Serializer` |
| **Outputs** | An `HttpJsonClient` instance whose subsequent request-building and retry behavior reflects the new options |
| **Primary components** | `HttpJsonClient.SetOptions`, `HttpClientOptions` (SAIF.NetCore.ServiceContracts) |
| **Entry point** | `src/SAIF.NetCore.HttpClients/SAIF.NetCore.HttpClients/SAIF.NetCore.HttpClients/HttpJsonClient/HttpJsonClient.cs` |

## Steps

1. The consumer constructs an `HttpClientOptions` instance, setting any subset of `PersistHeadersAfterRequest`, `RetryDelayInMs`, `RetryOnStatusCodes`, and `Serializer`; unset fields retain the `HttpClientOptions` defaults.
2. The consumer calls `SetOptions(options)`. The instance replaces its entire internal options object with the one supplied; `SetOptions` performs no null guard on the argument.
   - On failure: passing `null` is accepted at the call site but produces a `NullReferenceException` the next time the options are read during request execution.
3. From this point, every subsequent request on the instance uses the new options:
   - Header persistence controls whether custom headers (including a Basic `Authorization` header) survive past the first request ([BR-HTTP-07](../business-rules.md#br-http-07-custom-headers-cleared-after-each-request-unless-persisted)).
   - `RetryOnStatusCodes` and `RetryDelayInMs` control which response statuses trigger a retry and how long each retry waits ([BR-HTTP-04](../business-rules.md#br-http-04-retry-on-configured-response-status-codes)).
   - `Serializer` selects between RestSharp's built-in JSON handling and the Newtonsoft-backed serializer used by the RestSharp client itself ([BR-HTTP-11](../business-rules.md#br-http-11-serializer-selection)). This selection does not change how typed results are produced: `GetResult<T>`/`GetContent<T>` always follow `ToReturnType<T>` ([Consume result](consume-result.md)), independently of this option.
4. These effects are realized the next time [Execute request](execute-request.md) runs, since `CreateClient` and `CreateRequest` read the current options at call time rather than caching them.

## Process flow

The following diagram visualizes how a `SetOptions` call changes the behavior of subsequent requests.

```mermaid
flowchart TD
    Start([Consumer builds HttpClientOptions]) --> Call["SetOptions(options)"]
    Call --> Replace["Replace instance options field<br>(no null guard)"]
    Replace --> Next["Next Execute request call"]
    Next --> Persist{"PersistHeadersAfterRequest?"}
    Persist -->|true| Keep["Custom headers survive<br>past first request"]
    Persist -->|false| Clear["Custom headers cleared<br>after first request"]
    Next --> RetryCfg["Apply RetryOnStatusCodes<br>and RetryDelayInMs"]
    Next --> SerCfg["RestSharp client uses Serializer<br>selection (does not affect<br>GetResult/GetContent conversion)"]
```

## Failure and edge-case behavior

- `SetOptions(null)` is accepted without error at the call site, but the next request that reads options throws a `NullReferenceException`.
- Replacing options mid-lifecycle (for example between a persisted-header setup and a later call) can silently change retry or persistence behavior for in-flight consumer code that assumed the prior options.

## Related documentation
- [Operations and processes](../operations-processes.md)
- [Business rules](../business-rules.md)

## Sources
- `src/SAIF.NetCore.HttpClients/SAIF.NetCore.HttpClients/SAIF.NetCore.HttpClients/HttpJsonClient/HttpJsonClient.cs`