RestSharp C# (.NET): методы, примеры, установка

Что такое RestSharp и зачем он нужен?

RestSharp — это популярная open-source библиотека для языка C# (.NET), предназначенная для упрощения работы с RESTful API. Она предоставляет удобный и интуитивно понятный интерфейс для выполнения HTTP-запросов (GET, POST, PUT, DELETE, PATCH и других) и обработки ответов от веб-сервисов.

RestSharp решает несколько ключевых задач:

Упрощение кода: Вместо написания громоздкого кода с использованием HttpClient, RestSharp предлагает лаконичный fluent-интерфейс.
Автоматическая сериализация/десериализация: Библиотека автоматически преобразует ваши C#-объекты в JSON/XML и обратно, избавляя от ручной работы.
Удобная обработка ошибок: RestSharp предоставляет понятные классы для обработки HTTP-статусов и исключений.
Поддержка аутентификации: Встроенная поддержка OAuth, Basic Auth, JWT и других схем.
Работа с файлами: Простая загрузка и скачивание файлов.

Библиотека активно используется в .NET-приложениях (ASP.NET Core, консольные приложения, Xamarin, Unity) для интеграции с внешними сервисами: социальными сетями, платежными системами, облачными платформами и т.д.

Установка RestSharp

RestSharp устанавливается через менеджер пакетов NuGet. Выберите один из способов:

Через Package Manager Console (Visual Studio):

Install-Package RestSharp

Через .NET CLI (командная строка):

dotnet add package RestSharp

Через интерфейс NuGet (Visual Studio/Rider):

Откройте Manage NuGet Packages → найдите RestSharp → установите последнюю стабильную версию.

После установки добавьте using-директиву в ваш код:

using RestSharp;

Быстрый старт: первый запрос

Давайте сделаем простой GET-запрос к публичному API (JSONPlaceholder) и получим список пользователей.

using RestSharp;

var client = new RestClient("https://jsonplaceholder.typicode.com");
var request = new RestRequest("/users", Method.Get);

var response = client.Execute(request);

if (response.IsSuccessful)
{
    Console.WriteLine(response.Content); // Выведет JSON-строку
}
else
{
    Console.WriteLine($"Ошибка: {response.StatusCode} - {response.ErrorMessage}");
}

Этот код создает клиент, формирует GET-запрос к эндпоинту /users и выводит ответ в консоль. Обратите внимание: response.IsSuccessful проверяет, что статус ответа находится в диапазоне 200-299.

Основные методы и функции RestSharp

Ниже представлены ключевые методы библиотеки с описанием, параметрами и примерами.

1. `RestClient(string baseUrl)` — Конструктор клиента

Описание: Создает экземпляр HTTP-клиента с базовым URL. Все последующие запросы будут использовать этот URL как основу.

Параметры:

baseUrl (string) — базовый адрес API (например, "https://api.example.com").

Пример:

var client = new RestClient("https://api.github.com");

2. `RestRequest(string resource, Method method)` — Создание запроса

Описание: Формирует HTTP-запрос к указанному ресурсу с заданным методом (GET, POST, PUT, DELETE и т.д.).

Параметры:

resource (string) — относительный путь к ресурсу (например, "/users").
method (Method) — HTTP-метод из перечисления Method (Get, Post, Put, Delete, Patch, Head, Options).

Пример:

var request = new RestRequest("/users/1", Method.Get);

3. `client.Execute(IRestRequest request)` — Выполнение запроса (синхронно)

Описание: Выполняет запрос синхронно и возвращает объект RestResponse, содержащий статус, заголовки, тело ответа и возможные ошибки.

Параметры:

request (IRestRequest) — объект запроса.

Пример:

var response = client.Execute(request);
if (response.IsSuccessful)
{
    Console.WriteLine(response.Content);
}

4. `client.ExecuteAsync(IRestRequest request, CancellationToken cancellationToken)` — Асинхронное выполнение

Описание: Выполняет запрос асинхронно. Рекомендуется для UI-приложений и ASP.NET Core, чтобы не блокировать поток.

Параметры:

request (IRestRequest) — объект запроса.
cancellationToken (CancellationToken) — токен отмены (опционально).

Пример:

var response = await client.ExecuteAsync(request);
Console.WriteLine(response.Content);

5. `client.GetAsync<T>(IRestRequest request)` — Десериализация ответа в объект

Описание: Выполняет запрос и автоматически десериализует JSON/XML ответ в указанный тип T. Удобно для работы с типизированными данными.

Параметры:

request (IRestRequest) — объект запроса.

Пример:

public class User
{
    public int Id { get; set; }
    public string Name { get; set; }
    public string Email { get; set; }
}

var request = new RestRequest("/users/1", Method.Get);
var user = await client.GetAsync<User>(request);
Console.WriteLine(user.Name);

6. `request.AddJsonBody(object obj)` — Добавление JSON-тела запроса

Описание: Сериализует объект в JSON и добавляет его в тело запроса. Автоматически устанавливает Content-Type: application/json.

Параметры:

obj (object) — любой C#-объект, который будет сериализован.

Пример (POST-запрос):

var newUser = new User { Name = "John", Email = "john@example.com" };
var request = new RestRequest("/users", Method.Post);
request.AddJsonBody(newUser);

var response = await client.ExecuteAsync(request);

7. `request.AddParameter(string name, string value)` — Добавление параметров

Описание: Добавляет параметры запроса: query-параметры, заголовки или параметры формы в зависимости от типа.

Параметры:

name (string) — имя параметра.
value (string) — значение параметра.

Пример (query-параметр):

var request = new RestRequest("/users", Method.Get);
request.AddParameter("page", "2");
request.AddParameter("limit", "10");
// Результат: GET /users?page=2&limit=10

8. `request.AddHeader(string name, string value)` — Добавление заголовков

Описание: Добавляет HTTP-заголовок к запросу. Часто используется для передачи токенов аутентификации (Authorization) или указания формата данных (Accept).

Параметры:

name (string) — имя заголовка.
value (string) — значение заголовка.

Пример:

var request = new RestRequest("/protected/resource", Method.Get);
request.AddHeader("Authorization", "Bearer your_token_here");
request.AddHeader("Accept", "application/json");

9. `client.AddDefaultHeader(string name, string value)` — Глобальные заголовки

Описание: Добавляет заголовок, который будет автоматически включен во все запросы от данного клиента. Удобно для API-ключей или User-Agent.

Параметры:

name (string) — имя заголовка.
value (string) — значение заголовка.

Пример:

var client = new RestClient("https://api.example.com");
client.AddDefaultHeader("X-API-Key", "my-secret-key");
// Теперь все запросы будут содержать этот заголовок

10. `request.AddFile(string name, string path, string contentType)` — Загрузка файла

Описание: Добавляет файл в multipart/form-data запрос. Используется для отправки файлов на сервер.

Параметры:

name (string) — имя поля формы.
path (string) — путь к файлу на диске.
contentType (string) — MIME-тип файла (например, "image/png").

Пример:

var request = new RestRequest("/upload", Method.Post);
request.AddFile("avatar", @"C:\photos\avatar.jpg", "image/jpeg");
var response = await client.ExecuteAsync(request);

11. `response.StatusCode` — Получение HTTP-статуса

Описание: Свойство, возвращающее HTTP-статус код ответа (например, 200, 404, 500).

Пример:

if (response.StatusCode == System.Net.HttpStatusCode.NotFound)
{
    Console.WriteLine("Ресурс не найден");
}

12. `response.Headers` — Доступ к заголовкам ответа

Описание: Коллекция заголовков HTTP-ответа. Позволяет извлечь, например, Content-Type или Set-Cookie.

Пример:

var contentType = response.Headers
    .FirstOrDefault(h => h.Name == "Content-Type")?.Value?.ToString();
Console.WriteLine(contentType);

Реальный практический пример: работа с GitHub API

Давайте создадим консольное приложение, которое получает информацию о репозитории GitHub и выводит её в консоль.

using RestSharp;

public class GitHubRepo
{
    public string Name { get; set; }
    public string Description { get; set; }
    public int StargazersCount { get; set; }
    public string HtmlUrl { get; set; }
}

class Program
{
    static async Task Main(string[] args)
    {
        var client = new RestClient("https://api.github.com");
        client.AddDefaultHeader("User-Agent", "MyApp"); // GitHub требует User-Agent

        var request = new RestRequest("/repos/restsharp/RestSharp", Method.Get);
        request.AddHeader("Accept", "application/vnd.github.v3+json");

        var repo = await client.GetAsync<GitHubRepo>(request);

        if (repo != null)
        {
            Console.WriteLine($"Репозиторий: {repo.Name}");
            Console.WriteLine($"Описание: {repo.Description}");
            Console.WriteLine($"Звезды: {repo.StargazersCount}");
            Console.WriteLine($"URL: {repo.HtmlUrl}");
        }
        else
        {
            Console.WriteLine("Не удалось получить данные репозитория.");
        }
    }
}

Этот пример демонстрирует: