配置 RestClient

本页面描述如何创建和配置 RestClient。

基本配置

RestClient 的主要构造函数接受一个 RestClientOptions 实例。大多数情况下，无需更改默认选项值。但在某些情况下，您可能希望以不同方式配置客户端，因此需要在代码中更改一些选项。构造函数还包含几个可选参数，用于配置未涵盖在客户端选项之外的其他内容。以下是构造函数签名：

public RestClient(
    RestClientOptions       options,
    ConfigureHeaders?       configureDefaultHeaders = null,
    ConfigureSerialization? configureSerialization  = null,
    bool                    useClientFactory        = false
)

构造函数参数如下：

以下是使用客户端选项创建客户端的示例：

var options = new RestClientOptions("https://localhost:5000/api") {
    DisableCharset = true
};
var client = new RestClient(options);

当您只需要设置基本 URL 时，可以使用简化构造函数：

var client = new RestClient("https://localhost:5000/api");

简化构造函数将创建一个客户端选项实例，并使用作为构造函数参数提供的基本 URL。

最后，您可以使用配置函数覆盖默认选项的属性。以下是支持此方法的构造函数签名：

public RestClient(
    ConfigureRestClient?    configureRestClient     = null,
    ConfigureHeaders?       configureDefaultHeaders = null,
    ConfigureSerialization? configureSerialization  = null,
    bool                    useClientFactory        = false
)

例如：

var client = new RestClient(options => {
    options.BaseUrl = new Url("https://localhost:5000/api"),
    options.DisableCharset = true
});

您也可以将基 URL 作为构造函数参数提供：

var client = new RestClient("https://localhost:5000/api", options => {
    options.DisableCharset = true
});

使用自定义 HttpClient

默认情况下，RestSharp 会使用客户端选项创建一个 HttpClient 实例，并在整个客户端生命周期内保持它。当 RestClient 实例被释放时，它也会释放 HttpClient 实例。

有时，您可能需要提供自己的 HttpClient。例如，您想要使用 HTTP 客户端工厂创建的 HttpClient。RestSharp 允许您这样做，通过使用附加构造函数。这些构造函数如下：

// 使用现有 HttpClient 和 RestClientOptions 创建客户端（可选）
public RestClient(
    HttpClient              httpClient,
    RestClientOptions?      options,
    bool                    disposeHttpClient      = false,
    ConfigureSerialization? configureSerialization = null
)

// 使用现有 HttpClient 和可选 RestClient 配置函数创建客户端
public RestClient(
    HttpClient              httpClient,
    bool                    disposeHttpClient      = false,
    ConfigureRestClient?    configureRestClient    = null,
    ConfigureSerialization? configureSerialization = null
)

disposeHttpClient 参数告诉客户端在 RestClient 实例被释放时也释放 HttpClient 实例。默认值为 false，因为当从外部提供 HttpClient 时，通常也应该在外部释放它。

使用自定义消息处理器

除非您使用外部 HttpClient，否则 RestSharp 在构造时会创建一个，使用客户端选项来配置消息处理器。通常，您会得到一个 SocketHttpHandler（现代 .NET）或 WinHttpHandler（.NET Framework）。

可能会有情况需要配置消息处理器。例如，您想要添加一个委托消息处理器。RestSharp 允许您这样做，通过使用附加构造函数。有一个构造函数允许您传递自定义 HttpMessageHandler：

public RestClient(
    HttpMessageHandler      handler,
    bool                    disposeHandler         = true,
    ConfigureRestClient?    configureRestClient    = null,
    ConfigureSerialization? configureSerialization = null
)

此构造函数将使用提供的消息处理器创建新的 HttpClient 实例。由于 RestSharp 将在 RestClient 实例被释放时释放 HttpClient 实例，因此消息处理器也将被释放。如果您想改变这一点并保留处理器，请将 disposeHandler 参数设置为 false。

使用自定义消息处理器时，RestSharp 将 不 使用客户端选项来配置它，通常这些选项用于配置由 RestSharp 创建的消息处理器。

另一种自定义消息处理器的方法是让 RestSharp 创建处理器，然后对其进行配置，或者在其上使用委托处理器。这可以通过使用 RestClientOptions.ConfigureMessageHandler 属性来完成。它可以设置为一个函数，该函数接收 RestSharp 创建的处理器，然后返回具有不同设置的相同处理器或新处理器。

例如，如果您想在测试中使用 MockHttp 和其处理器，可以这样做：

var mockHttp = new MockHttpMessageHandler();
// 配置 MockHttp 处理器进行检查
...

var options = new RestClientOptions(Url) {
    ConfigureMessageHandler = _ => mockHttp
};
using var client = new RestClient(options);

在这个例子中，我们重赋值了处理器给 MockHttp，所以 RestSharp 创建的处理器没有被使用。在其他情况下，您可能想要使用委托处理器作为中间件，因此您会将 RestSharp 创建的处理器传递给委托处理器：

var options = new RestClientOptions(Url) {
    ConfigureMessageHandler = handler => new MyDelegatingHandler(handler)
};
using var client = new RestClient(options);

客户端选项

RestSharp 允许使用客户端选项配置 RestClient，如页面开头所述。以下详细介绍了可用的选项。

| BaseHost | 与每个请求一起发送到 Host 头的值。 | | CookieContainer | 自定义 cookie 容器，所有由客户端发出的请求都将共享。通常不需要，因为 RestSharp 会处理 cookies，而无需使用客户端级别的 cookie 容器。 | | MaxTimeout | 客户端级别的超时（以毫秒为单位）。如果还设置了请求超时，则此值将不被使用。 | | Encoding | 默认请求编码。只有在不使用 UTF-8 时才覆盖它。 | | ThrowOnDeserializationError | 如果解析响应时失败，强制客户端抛出异常。请记住，并非所有解析问题都会导致序列化器抛出异常。默认为 false，因此客户端将返回一个包含解析异常详情的RestResponse。仅对Execute...函数有效。 | | FailOnDeserializationError | 当设置为 true 时，如果客户端无法解析响应，响应对象将状态设为 Failed，尽管 HTTP 调用可能成功。默认为 true。 | | ThrowOnAnyError | 当设置为 true 时，客户端将重新抛出 HttpClient 抛出的任何异常。默认为 false。仅适用于 Execute... 函数。 | | AllowMultipleDefaultParametersWithSameName | 默认情况下，不允许添加具有相同名称的参数。您可以通过设置此属性为 true 来覆盖此行为。 | | Encode | 一个用于编码 URL 的函数，默认使用基于 Uri.EscapeDataString() 的 RestSharp 自定义函数。如果您需要使用不同的方式进行编码，请设置此属性。 | | EncodeQuery | 一个用于编码 URL 查询参数的函数，默认与 Encode 属性使用相同的函数。 |

其中一些选项由 RestSharp 代码使用，但有些仅用于配置 HttpMessageHandler。这些选项包括：

• Credentials
• UseDefaultCredentials
• AutomaticDecompression
• PreAuthenticate
• MaxRedirects
• RemoteCertificateValidationCallback
• ClientCertificates
• FollowRedirects
• Proxy

注意： 如果将这些选项设置为非默认值未产生期望的效果，请检查您的框架和平台是否支持它们。RestSharp 不会根据这些选项的值改变行为。

IRestClient 接口提供了Options属性，因此可以在运行时检查任何选项。然而，RestSharp 将传递给客户端构造函数的选项对象转换为不可变对象。因此，实例化客户端后，不能更改任何客户端选项。这是因为，在并发环境中更改客户端选项可能会导致问题，从而使客户端失去线程安全性。此外，更改用于创建消息处理器的选项需要重新创建处理器以及 HttpClient，这不应在运行时进行。

配置请求

客户端选项应用于客户端发出的所有请求。有时，您可能希望精细调整特定请求，使其使用定制配置执行。这可以通过以下 RestRequest 属性实现：

上面是 RestRequest 的所有配置属性。有关如何添加请求参数的更多信息，请参阅 使用页面 中关于使用参数创建请求的部分。