RestSharp使用说明

最新推荐文章于 2024-09-26 18:20:55 发布
最新推荐文章于 2024-09-26 18:20:55 发布
阅读量1.5w 收藏 6
点赞数 2

翻译自：https://github.com/restsharp/RestSharp/wiki，转载请注明。

一、新手入门

如果只有少量一次性请求需要封装为API，则可以如下使用RestSharp ：

using RestSharp;
using RestSharp.Authenticators;

var client = new RestClient();
client.BaseUrl = new Uri("http://twitter.com");
client.Authenticator = new HttpBasicAuthenticator("username", "password");

var request = new RestRequest();
request.Resource = "statuses/friends_timeline.xml";

IRestResponse response = client.Execute(request);

IRestResponse 接口中包含了所有远程服务返回的信息，可以访问头信息（header）数据内容（content）、HTTP状态等。建议使用泛型将返回结果自动反序列化为.NET实体类。

关于错误处理：

如果发生了网络传输错误（网络瘫痪，DNS查找失败等），RestResponse.ResponseStatus 将会置为Error ，否则RestResponse.ResponseStatus的值为Completed 。如果API返回404，ResponseStatus 仍然是Completed 。如果需要访问返回的HTTP状态码，则需要查看RestResponse.StatusCode 的值，Status  属性是请求完成的标识，独立于API错误处理。

二、推荐用法

RestSharp适合作为API代理类实现的基础，下面是 Twilio类库中的一些使用示例：

创建一个包含API代理实现的类，声明一个执行方法当作所有请求的入口。这个执行方法允许设置常用参数和其它跨请求共享设置（例如认证），因为每一个请求都需要帐户ID和密钥，所以在建立新的代理实例时都需要传递这两个值。需要注意的是执行过程中不会抛出异常，但是可以在ErrorException 中访问到异常信息。

// TwilioApi.cs
public class TwilioApi {
    const string BaseUrl = "https://api.twilio.com/2008-08-01";

    readonly string _accountSid;
    readonly string _secretKey;

    public TwilioApi(string accountSid, string secretKey) {
        _accountSid = accountSid;
        _secretKey = secretKey;
    }

    public T Execute<T>(RestRequest request) where T : new()
    {
        var client = new RestClient();
        client.BaseUrl = new System.Uri(BaseUrl);
        client.Authenticator = new HttpBasicAuthenticator(_accountSid, _secretKey);
        request.AddParameter("AccountSid", _accountSid, ParameterType.UrlSegment); // used on every request
        var response = client.Execute<T>(request);

        if (response.ErrorException != null)
        {
            const string message = "Error retrieving response.  Check inner details for more info.";
            var twilioException = new ApplicationException(message, response.ErrorException);
            throw twilioException;
        }
        return response.Data;
    }

}

接下来，定义一个实体类来映射API返回的数据，再定义一个方法用来访问API同时获取返回的Call资源的具体信息：

// Call.cs
public class Call
{
    public string Sid { get; set; }
    public DateTime DateCreated { get; set; }
    public DateTime DateUpdated { get; set; }
    public string CallSegmentSid { get; set; }
    public string AccountSid { get; set; }
    public string Called { get; set; }
    public string Caller { get; set; }
    public string PhoneNumberSid { get; set; }
    public int Status { get; set; }
    public DateTime StartTime { get; set; }
    public DateTime EndTime { get; set; }
    public int Duration { get; set; }
    public decimal Price { get; set; }
    public int Flags { get; set; }
}

// TwilioApi.cs, method of TwilioApi class
public Call GetCall(string callSid) 
{
    var request = new RestRequest();
    request.Resource = "Accounts/{AccountSid}/Calls/{CallSid}";
    request.RootElement = "Call";

    request.AddParameter("CallSid", callSid, ParameterType.UrlSegment);

    return Execute<Call>(request);
}

有一些神奇之处是RestSharp 需要关心而我们不必关注：

1、API返回的XML数据被默认XmlDeserializer 检测到，同时反序列化为Call对象。

2、默认RestRequest 对应HTTP中的GET 请求，可以通过设置RestRequest  的Method属性或者在创建请求实例时通过构造函数指定Method  类型来改变请求类型。

3、UrlSegment  类型参数会根据Resource 属性值中匹配的名称标签将值注入到URL中，AccountSid  在 TwilioApi.Execute  赋值，对于每一个请求它都是相同的。

4、我们指定了从哪里开始反序列化的根元素名称，在本例中，返回的XML形如 ，因为Response元素不包含与我们定义的实体模型相关的任何信息，所以从元素树的下一个节点开始反序列化（Call节点）。

我们还可以定义POST（和 PUT/DELETE/HEAD/OPTIONS ）请求：

// TwilioApi.cs, method of TwilioApi class
public Call InitiateOutboundCall(CallOptions options) 
{
    Require.Argument("Caller", options.Caller);
    Require.Argument("Called", options.Called);
    Require.Argument("Url", options.Url);

    var request = new RestRequest(Method.POST);
    request.Resource = "Accounts/{AccountSid}/Calls";
    request.RootElement = "Calls";

    request.AddParameter("Caller", options.Caller);
    request.AddParameter("Called", options.Called);
    request.AddParameter("Url", options.Url);

    if (options.Method.HasValue) request.AddParameter("Method", options.Method);
    if (options.SendDigits.HasValue()) request.AddParameter("SendDigits", options.SendDigits);
    if (options.IfMachine.HasValue) request.AddParameter("IfMachine", options.IfMachine.Value);
    if (options.Timeout.HasValue) request.AddParameter("Timeout", options.Timeout.Value);

    return Execute<Call>(request);
}

本示例同样证明RestSharp是一个轻量级验证助手，可以在请求前先校验提交的参数值是否有效。

示例中通过AddParameter  方法添加的参数值将通过标准编码格式提交，类似于通过网页提交的表单。如果是GET形式的请求(GET/DELETE/OPTIONS/HEAD) ，参数值将通过查询字符串提交，AddParameter() 方法也可以添加头信息和cookie 参数。将一个对象的所有属性作为参数时，使用AddObject() 方法。上传一个文件时用 AddFile() 方法（请求会以多种编码格式发送），当请求中包含请求体时（例如XML或者JSON），用AddBody()方法。

三、其它应用示例

下面的示例演示了用流（stream）代替内存缓冲请求内容，这在请求大量数据同时需要立刻写入磁盘的场景下非常有用：

string tempFile = Path.GetTempFileName();
using (var writer = File.OpenWrite(tempFile))
{
    var client = new RestClient(baseUrl);
    var request = new RestRequest("Assets/LargeFile.7z");
    request.ResponseWriter = (responseStream) => responseStream.CopyTo(writer);
    var response = client.DownloadData(request);
}

四、反序列化

RestSharp拥有处理XML和JSON的反序列化器，当收到响应时，RestClient通过服务器返回的Content Type 选择适合的反序列化器。默认设置可以通过自定义设置的Content Type覆盖，支持的Content Type如下：

  • application/json - JsonDeserializer
  • application/xml - XmlDeserializer
  • text/json - JsonDeserializer
  • text/xml - XmlDeserializer
  • *+json - JsonDeserializer (content types using a Structured Suffix Syntax specifying JSON)
  • *+xml - XmlDeserializer (content types using a Structured Suffix Syntax specifying XML)
  • @*@ - XmlDeserializer (all other content types not specified)

默认的反序列化器尝试解除必须解析XML或者JSON的痛苦，通过映射CLR实体类来实现。实体类定义了如何反序列化返回的数据。RestSharp不再采用遍历返回的数据，再从实体类中查找匹配的属性的方式反序列化数据，而是把实体类当作起点，循环遍历可访问的可写属性，同时在返回的数据中查找相应的元素。

注意：默认的反序列化器不支持 DataAnnotation/DataMember ，如果要使用，必须实现和注册自己的IDeserializer ，IDeserializer 是包装了与实体类中属性兼容的反序列化库。

例如下面的XML和JSON：

<Person>
    <Name>John</Name>
    <Id>28</Id>
</Person>

{
    "Name": "John",
    "Id": 28
}

映射相同的实体类Person:

public class Person 
{
    public string Name { get; set; }
    public int Id { get; set; }
}

支持的属性类型（数据类型）：

XmlDeserializer：
  • Primitives (int, short, long, etc)
  • Decimal
  • DateTime
  • String
  • Guid
  • List
  • Nested classes
  • Nullable versions of the above listed types
JsonDeserializer
  • Primitives
  • Decimal
  • DateTime
  • String
  • Guid
  • List
  • Dictionary<T1, T2>
  • Nested classes
  • Nullable versions of the above listed types

名称匹配：

XmlDeserializer

当查找匹配元素时，默认的XML反序列化器查找元素和特性遵循以下顺序：

  • 元素和名称绝对匹配
  • 元素和名称的小写匹配
  • 元素和名称的骆驼命名匹配
  • 元素和名称去掉下划线和破折号匹配
  • 特性和名称绝对匹配
  • 特性和名称的小写匹配
  • 特性和名称的骆驼命名匹配
  • 特性和名称去掉下划线和破折号匹配

可以使用@DeserializeAs@ 特性来更改将在属性中查找的名称，如果要将属性的命名与XML中的名称同，这一点将非常有用。

例如：

[DeserializeAs(Name = "forecast_information")]
public ForecastInformation Forecast { get; set; }

有一种返回元素值的特殊情况，示例如下：

如果返回的XML数据如下：

<Response>Hello world</Response>

没有办法用c#的类直接描述

public class Response 
{
}

需要一些东西来保存返回的元素值，在本例中，添加一个Value属性：

public class Response
{
     public string Value { get; set; }
}
JsonDeserializer

当为匹配元素查找数据时，默认的JSON反序列化器在查找元素时将遵循以下顺序：

  • 与名称绝对匹配
  • 与名称骆驼命名匹配
  • 与名称小写匹配
  • 与名称加了下划线匹配 (e.g. ProductId -> Product_Id)
  • 与名称加了下划线小写形式匹配 (e.g. Product_id -> product_id)

XML反序列化器可以通过设置属性的DeserializeAs  特性来改变如何与JSON的键映射。

例如：

[DeserializeAs(Name = "forecast_information")]
public ForecastInformation Forecast { get; set; }

集合处理（List/Dictionary）

XmlDeserializer

处理两种不同形式的集合：内联和嵌套

<?xml version="1.0" encoding="utf-8" ?>
<InlineListSample>
    <image src="1.gif">value1</image>
    <image src="2.gif">value2</image>
    <image src="3.gif">value3</image>
    <image src="4.gif">value4</image>
</InlineListSample>

<?xml version="1.0" encoding="utf-8" ?>
<NestedListSample>
   <images>
      <image src="1.gif">value1</image>
      <image src="2.gif">value2</image>
      <image src="3.gif">value3</image>
      <image src="4.gif">value4</image>
    </images>
</NestedListSample>

对应的c#形式如下：

public class ListSample
{
    public List<Image> Images { get; set; }
}
    
public class Image
{
    public string Src { get; set; }
    public string Value { get; set; }
}

如果在同一份文档中两种元素结构恰巧同时存在，优先级按此顺序：parented/nested/regular 。

JsonDeserializer

在映射JSON数组和字典时，RestSharp支持集合（List）和字典（Dictionary<string, T> ）

日期处理

XmlDeserializer
  • 如果RestRequest.DateFormat已经指定了返回值的格式，则返回值使用指定格式字符串解析。
  • 如果 RestRequest.DateFormat 没有指定, 用DateTime.Parse计算元素值. 如果该方法无法处理当前格式, 则需要改变属性类型为String然后再进行处理 。
JsonDeserializer

如果没有通过RestRequest.DateFormat指定日期格式，RestSharp尝试用以下格式字符转来反序列化DateTime类型的属性（顺序如下）：

  • "u"
  • "s"
  • "yyyy'-'MM'-'dd'T'HH':'mm':'ss'Z'"
  • "yyyy-MM-ddTHH:mm:ssZ"
  • "yyyy-MM-dd HH:mm:ssZ"
  • "yyyy-MM-ddTHH:mm:ss"
  • "yyyy-MM-ddTHH:mm:sszzzzzz"

JsonSerializer  默认支持以下JSON日期格式，如果指定了具体的RestRequest.DateFormat ，则默认被忽略：

  • ISO - 1910-09-25T09:30:25Z
  • Javascript Date Objects - new Date(-1870352975000)
  • Unix Timestamps - 1435206458

对于JS日期对象，在JS纪元时间基础上加毫秒级的时间间隔，根据指定的时区调整。

自定义

重写默认反序列化器

可以通过如下步骤重写自己的反序列化器处理返回的数据内：

  • 创建一个类同时实现IDeserializer接口。
  • 用RestClient.AddHandler(contentType, IDeserializer)方法注册handler并关联content类型，如果此content类型已经被注册过，则会被指定的刚刚指定的handker重写，可以通过 RestClient.ClearHandlers()方法移除所有注册的handler，或者通过RestClient.RemoveHandler(contentType)移除某一个handler。
重写默认的序列化器

当使用XML或者JSON格式数据作为请求体时，可以使用自己实现的ISerializer  ：

var request = new RestRequest();
request.RequestFormat = DataFormat.Xml;
request.XmlSerializer = new SuperXmlSerializer(); // implements ISerializer
request.AddBody(person); // object serialized to XML using your custom serializer;
重写JsonSerializationStrategy

序列化过程中，尝试支持c#和JSOM间不同投影策略将会陷入麻烦，重写MapClrMemberNameToJsonFieldName 将会有帮助：

class SnakeJsonSerializerStrategy : PocoJsonSerializerStrategy
{
    protected override string MapClrMemberNameToJsonFieldName(string clrPropertyName)
    {
        //PascalCase to snake_case
        return string.Concat(clrPropertyName.Select((x, i) => i > 0 && char.IsUpper(x) ? "_" + char.ToLower(x).ToString() : x.ToString()));
    }
}

然后在代码中使用：

SimpleJson.CurrentJsonSerializerStrategy = new SnakeJsonSerializerStrategy();

五、认证

RestSharp包含HTTP认证，可以通过IAuthenticator  完成自己的实现同时用RestClient注册：

var client = new RestClient();
client.Authenticator = new SuperAuthenticator(); // implements IAuthenticator

在使用RestClient.Execute 或 RestClient.Execute

使用SimpleAuthenticator

SimpleAuthenticator 允许把用户名和密码当作GET 或 POST参数传递，具体取决于所使用的请求方法：

var client = new RestClient("http://example.com");
client.Authenticator = new SimpleAuthenticator("username", "foo", "password", "bar");

var request = new RestRequest("resource", Method.GET);
client.Execute(request);

请求生成的URL应该是如下形式：http://example.com/resource?username=foo&password=bar

上述请求如果使用PUT或者POST请求时，将会以编码表单形式提交值。

六、RestRequest的参数类型

新建了RestRequest 后，可以为它添加参数，下面是5种当前支持的参数类型以及其在使用默认IHttp实现下的特性描述。

添加到cookies  列表的参数将会随着请求被单独发送，Cookie名称是参数的名称，值则是传递的参数的值（.ToString ）。

HttpHeader

添加作为 HTTP header 的参数会随着请求被单独发送，Header名称是参数的名称，Header值则是传递的参数的值。

注意有些受限制的headers表现不同或者会被忽略，可以在Http.cs中的_restrictedHeaderActions  字典中查看它们的特性。

GetOrPost

如果执行GET请求，RestSharp将会追加参数到URL中，形式如下：“url?name1=value1&name2=value2” ；

如果是POST或者是PUT请求，则取决于请求中是否有文件，如果没有，则参数以请求体发送，形如“name1=value1&name2=value2” ，将会以application/x-www-form-urlencoded格式发送，基于不同的请求方法会有不同的表现。

两种情形下，参数名称和值都会自动被url编码。

如果请求中有文件，RestSharp将会发送multipart/form-data 形式的请求，发送的参数将会形如以下格式：

Content-Disposition: form-data; name="parameterName"

ParameterValue

UrlSegment

不同于GetOrPost ，这种参数类型在RequestUrl 中用占位符代替值。

var request = new RestRequest("health/{entity}/status");
request.AddParameter("entity", "s2", ParameterType.UrlSegment);

当执行请求时，RestSharp将尝试用参数名称匹配占位符，匹配成功后则用参数值代替占位符，上面的代码结果是：“health/s2/status”  。

RequestBody

如果设置了这个参数，参数值会以请求的body方式传递。请求只能接收一个RequestBody  参数（第一个）。

参数名称将被用作请求的Content-Type header 。

RequestBody  参数对于GET或者HEAD  是无效的，它们不需要发送请求体。

如果同时还有GetOrPost  参数，则该参数将重写RequestBody  ——RestSharp  不会合并这些参数，但会抛弃RequestBody  参数。

QueryString

类似于GetOrPost ，除此之外，它总是用如下形式追加参数到URL：“url?name1=value1&name2=value2” ，不管是什么类型的请求方法。

七、缓存

自动缓存管理

RestSharp 102.4 +版本支持所有IRestClient 实例的请求共享同一个System.Net.CookieContainer 管理，通过这种方式，responses 设置或没设置缓存在后续的请求中都会使用，为了共享CookieContainer ，在创建RestClient 时设置属性即可：

var client = new RestClient("http://server/");
client.CookieContainer = new System.Net.CookieContainer();

八、跨平台支持

RestSharp包含2个版本的lib：

  • .NET Framework 4.5.2
  • .NET Standard 2.0

意味着可以在以下平台应用RestSharp：

  • Windows using .NET Framework
  • Windows using .NET Core
  • Linux or Mac using Mono
  • Linux or Mac using .NET Core
  • Any other platform that supports Mono 5 or .NET Core 2
ahilll
关注
WPF实战项目十五（客户端）：RestSharp的使用
yigu4011的博客
11-22 2055
10、修改ToDoViewModel的代码，添加ToDoService服务，修改CreateToDoList 代码。12、F5启动项目，点击【待办事项】，显示了待办事项的列表这和webapi中返回的待办事项Json数据一样。8、新增ToDoService类，继承BaseService类和接口IToDoService。9、在客户端App.xaml中注册httprestclient、注册默认服务的地址、注册服务。7、新增IToDoService接口，继承IBaseService接口。
C# RestSharp应用
dengzitui的博客
03-21 4969
C# RestSharp应用 开通博客是想将自己所学的东西记录下来，以便自己查缺补漏，希望自己能坚持下去 正题关于RestSharp的使用 下载 NuGet直接搜索即可，最新版本RestSharp需要.net framework 4.5.2及以上支持 Json序列化工具：Newtonsoft.Json,直接由NuGet下载 官网说明： var client = new RestClient("...
简单的REST的框架实现
weixin_34192732的博客
07-21 223
源码下载地址：http://download.csdn.net/source/1662193      一. 认识REST          REST软件架构是由Roy Thomas Fielding博士在2000年首次提出的。他为我们描绘了开发基于互联网的网络软件的蓝图。REST软件架构是一个抽象的概念，是一种为了实现这一互联网的超媒体分布式系统的行动指南。利用任何的技术都可以实现这种理念...
RestSharp简介
最新发布
arvinzd的博客
09-26 452
RestSharp是一个轻量级HTTP客户端库，主要功能是通过HTTP对远程资源进行同步异步调用，可将请求主体序列化为JSON或XML并反序列化相应。参数类型：查询、URL段、标头、cookie、正文。请求主体的方式：JSON、XML和表单数据。
RestSharp的使用说明
芝麻麻雀-Asp.Net学习之路
03-20 2015
RestSharp介绍 不得不说，RestSharp是一款非常有用的REST API客户端库。RestSharp可能是.NET中最受欢迎的HTTP客户端库，具有自动序列化和反序列化，请求和响应类型检测，各种身份验证以及其他有用的功能，正在被成千上万的项目使用。 RestSharp在NuGet上的下载量超过3200万，评价每日下载量为10000。许多受欢迎的OSS项目（包括Roslyn和Swagge...
C# 使用RestSharp实现Postman中的各种形式的请求
Admans的专栏
07-19 2782
原文：https://blog.csdn.net/qq_31025841/article/details/120448324。版权声明：本文为作者原创文章，转载请附上博文链接！作者：软件小哥哥QAQ。
RestSharp简单使用
kusse的博客
02-21 2319
RestSharp简单使用
HTTP辅助类组件RestSharp.dll文件
03-29
- 文档：详细说明了库的使用方法和API。 - 测试项目：包含了一些测试用例，验证了库的功能和性能。 通过深入学习和使用这个压缩包中的资源，开发者不仅可以掌握RestSharp的用法，还能了解HTTP请求的最佳实践，提高...
C# 使用RestSharp实现图片上传服务端与客户端源码解析
我们还将详细说明如何利用RestSharp提供的接口来监控上传过程，包括上传进度和错误处理机制。最后，我们将展示如何发送带有必要HTTP头信息的请求，并确保文件数据被正确上传到服务端。 通过本文档，读者将能够了解...
RestSharp 104.1
11-07
- `readme.txt`：可能包含关于库的说明、使用指南或版本更新信息。 - `lib`：库文件夹，包含了RestSharp的DLL或NuGet包的依赖库。 - `_rels`：可能与包的内部关系链接有关。 总结来说，RestSharp是一个强大的工具，...
restsharp中文文档
11-28
新鲜的restsharp中文文档，纯手工翻译，有需要请自行下载。
RestSharp-106.13.0_dll.rar
11-21
最新版RestSharp-106.13.0.dll。RestSharp是一款非常有用的REST API客户端库。RestSharp可能是.NET中最受欢迎的HTTP客户端库，具有自动序列化和反序列化，请求和响应类型检测，各种身份验证以及其他有用的功能，正在被成千上万的项目使用。
c# restsharp 帮助类,c# restsharp 帮助类
03-31
c# restsharp 帮助类,c# restsharp 帮助类
RestSharp使用
xiuyuandashen的博客
09-26 1021
应该是.Net目前最流行的Restful Api 客户端库。
C#通过restsharp模拟Get、Post请求
你要明白，任何问题都不是孤立存在的，一定有人曾经遇到过，并且已经有更好的解决办法了，只是我还不知道。我不应该在黑暗中独自前行，去重新发明轮子，也许我的顿悟，只是别人的基本功！我应该要站在巨人的肩膀上，学习更成熟的经验和方法，然后再来解决这个问题
10-10 6056
我们在开发CS架构时通常采用直接链接数据库方式获取数据，这里写下通过RestClient 向第三方接口推送数据、获取数据 准备 1.cs客户端 2.后台api接口(这里采用abp框架) 包控制台安装restsharp 一。登录 登录代码 引用 using RestSharp; public int? UserId = null; public string AccessToken = null;//登录后获取token验证信息 private voi
WMS中RestSharp的使用
forrange的博客
03-11 582
RestSharp 可能是.NET 最流行的 HTTP 客户端库。它具有自动序列化和反序列化、请求和响应类型检测、多种身份验证和其他有用功能，正被数十万个项目使用。RestSharp 的主要目的是通过 HTTP 对远程资源进行同步和异步调用。顾名思义，RestSharp 的主要受众是使用 REST API 的开发人员。只要您具有要发送的资源 URI 和请求参数符合 W3C HTTP 标准，RestSharp 就 可以通过 HTTP 调用任何 API。
评论 4
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值