RestSharp.net REST/HTTP 工具庫

說明

RestSharp的主要目的是經過HTTP對遠程資源進行同步和異步調用。顧名思義，RestSharp的主要受衆是使用REST API的開發人員。可是，只要您擁有要發送的資源URI和請求參數符合W3C HTTP標準，RestSharp能夠經過HTTP調用任何API（但不能調用HTTP / 2）。

爲.NET開發人員使用HTTP API的主要挑戰之一是處理不一樣種類的請求和響應，並將它們轉換爲複雜的C＃類型。RestSharp能夠負責將請求正文序列化爲JSON或XML並反序列化響應。它還能夠根據不一樣的參數類型（路徑，查詢，表單或正文）造成有效的請求URI。

入門

您必須先添加NuGet軟件包，而後才能在應用程序中使用RestSharp。您可使用IDE或命令行執行此操做：

dotnet add package RestSharp

基本用法

若是您只對API提出了一些一次性請求，則能夠這樣使用RestSharp：

using RestSharp;
using RestSharp.Authenticators;

var client = new RestClient("https://api.twitter.com/1.1");
client.Authenticator = new HttpBasicAuthenticator("username", "password");

var request = new RestRequest("statuses/home_timeline.json", DataFormat.Json);

var response = client.Get(request);

IRestResponse包含從遠程服務器返回的全部信息。您能夠訪問標題，內容，HTTP狀態等。

咱們建議使用通用重載，例如Get<T>將響應自動反序列化爲.NET類。

異步呼叫

全部同步方法都有其異步同級，後綴爲Async。

所以，您可使用和來代替Get<T>返回T或Execute<T>返回。參數集一般是相同的。您能夠選擇提供取消令牌，該令牌默認設置爲。IRestResponse<T>GetAsync<T>ExecuteAsync<T>CancellationToken.None

例如：

using RestSharp;
using RestSharp.Authenticators;

var client = new RestClient("https://api.twitter.com/1.1");
client.Authenticator = new HttpBasicAuthenticator("username", "password");

var request = new RestRequest("statuses/home_timeline.json", DataFormat.Json);

var timeline = await client.GetAsync<HomeTimeline>(request, cancellationToken);

不過，最重要的區別是，以HTTP方法命名的異步方法返回Task<T>而不是Task<IRestResponse<T>>。由於這意味着若是請求失敗，您將不會收到錯誤響應，所以這些方法將引起異常。

ExecuteAsync可是，全部重載的行爲都與相同，Execute並返回IRestResponse或IRestResponse<T>。

內容類型

RestSharp支持將XML或JSON正文做爲請求的一部分發送。要將主體添加到請求中，只需調用實例的AddJsonBody或AddXmlBody方法IRestRequest。

使用這些方法時，無需設置Content-Type或DataFormat在請求中添加參數，RestSharp會爲您完成此操做。

RestSharp還將處理XML和JSON響應，並根據服務器響應類型執行全部必要的反序列化任務。所以，僅在Accept要手動反序列化響應時才須要添加標頭。

例如，只須要這些行便可使用JSON正文進行請求：

var request = new RestRequest("address/update")
    .AddJsonBody(updatedAddress);
var response = await client.PostAsync<AddressUpdateResponse>(request);

響應

當使用Execute或時ExecuteAsync，您將得到IRestResponse具備Content屬性的back實例，該實例以字符串形式包含響應。您能夠在那裏找到其餘有用的屬性，例如StatusCode，ContentType等等。若是請求未成功，您將得到響應，並將IsSuccessful屬性設置爲，false而且在ErrorException和ErrorMessage屬性中說明了錯誤。

使用typeExecute<T>或時ExecuteAsync<T>，您將得到IRestResponse<T>back的實例，該實例與back實例相同，IRestResponse但也包含T Data具備反序列化響應的屬性。

擴展喜歡Get<T>而且GetAsync<T>不會返回所有，IRestResponse<T>而只是反序列化的響應。null若是出現問題，您可能會回來，而且很難理解該問題。所以，在使用類型化擴展方法時，建議將IRestClient.ThrowOnAnyError屬性設置爲true。這樣，您告訴RestSharp在出現問題時引起異常。而後，您能夠將調用包裝在try/catch塊中，並相應地處理異常。