Вызов веб-API из клиента .NET (C#) Call a Web API From a .NET Client (C#)

Это содержимое предназначено для предыдущей версии .NET. This content is for a previous version of .NET. Новая разработка должна использовать ASP.NET Core. New development should use ASP.NET Core. Дополнительные сведения об использовании ASP.NET Core веб-API см. в следующих статьях: For more information on using ASP.NET Core Web API, see:

В этом руководстве показано, как вызвать веб-API из приложения .NET с помощью System .NET. http. HttpClient. This tutorial shows how to call a web API from a .NET application, using System.Net.Http.HttpClient.

В этом руководстве написано клиентское приложение, использующее следующий веб-API: In this tutorial, a client app is written that consumes the following web API:

Действие Action	Метод HTTP HTTP method	Относительный URI Relative URI
Получение сведений о продукте по идентификатору Get a product by ID	GET GET	идентификатор /АПИ/Продуктс/ /api/products/id
Создать продукт Create a new product	POST POST	/апи/продуктс /api/products
Обновить продукт Update a product	PUT PUT	идентификатор /АПИ/Продуктс/ /api/products/id
Удалить продукт Delete a product	DELETE DELETE	идентификатор /АПИ/Продуктс/ /api/products/id

Сведения о том, как реализовать этот API с веб-API ASP.NET, см. в разделе Создание веб-API, поддерживающего операции CRUD. To learn how to implement this API with ASP.NET Web API, see Creating a Web API that Supports CRUD Operations.

Для простоты клиентское приложение в этом учебнике является консольным приложением Windows. For simplicity, the client application in this tutorial is a Windows console application. HttpClient также поддерживается для приложений Windows Phone и магазина Windows. HttpClient is also supported for Windows Phone and Windows Store apps. Дополнительные сведения см. в статье написание кода клиента веб-API для нескольких платформ с помощью переносимых библиотек . For more information, see Writing Web API Client Code for Multiple Platforms Using Portable Libraries

Примечание. При передаче базовых URL-адресов и относительных URI в виде жестко заданных значений следует учитывать правила использования HttpClient API. NOTE: If you pass base URLs and relative URIs as hard-coded values, be mindful of the rules for utilizing the HttpClient API. HttpClient.BaseAddress Для свойства необходимо задать адрес с завершающей косой чертой ( / ). The HttpClient.BaseAddress property should be set to an address with a trailing forward slash ( / ). Например, при передаче в метод жестко запрограммированных URI ресурсов HttpClient.GetAsync не включайте в начале косую черту вперед. For example, when passing hard-coded resource URIs to the HttpClient.GetAsync method, don’t include a leading forward slash. Чтобы получить объект Product по идентификатору: To get a Product by ID:

1. Параметр client.BaseAddress = new Uri(«https://localhost:5001/»); Set client.BaseAddress = new Uri(«https://localhost:5001/»);
2. Запрос а Product . Request a Product . Например, client.GetAsync

(«api/products/4»); . For example, client.GetAsync

Создание консольного приложения Create the Console Application

В Visual Studio создайте новое консольное приложение Windows с именем хттпклиентсампле и вставьте следующий код: In Visual Studio, create a new Windows console app named HttpClientSample and paste in the following code:

Приведенный выше код является полноценным клиентским приложением. The preceding code is the complete client app.

RunAsync выполняется и блокируется до завершения. RunAsync runs and blocks until it completes. Большинство методов HttpClient являются асинхронными, так как они выполняют сетевые операции ввода-вывода. Most HttpClient methods are async, because they perform network I/O. Все асинхронные задачи выполняются внутри RunAsync . All of the async tasks are done inside RunAsync . Обычно приложение не блокирует основной поток, но это приложение не позволяет никакого взаимодействия. Normally an app doesn’t block the main thread, but this app doesn’t allow any interaction.

Установка клиентских библиотек веб-API Install the Web API Client Libraries

Используйте диспетчер пакетов NuGet для установки пакета клиентских библиотек веб-API. Use NuGet Package Manager to install the Web API Client Libraries package.

В меню Инструменты выберите Диспетчер пакетов NuGet > Консоль диспетчера пакетов. From the Tools menu, select NuGet Package Manager > Package Manager Console. В консоли диспетчера пакетов (PMC) введите следующую команду: In the Package Manager Console (PMC), type the following command:

Предыдущая команда добавляет в проект следующие пакеты NuGet: The preceding command adds the following NuGet packages to the project:

• Microsoft. AspNet. WebApi. Client Microsoft.AspNet.WebApi.Client
• Newtonsoft.Json. Newtonsoft.Json

Netwonsoft.Json (также известный как Json.NET) — это популярная высокопроизводительная платформа JSON для .NET. Netwonsoft.Json (also known as Json.NET) is a popular high-performance JSON framework for .NET.

Добавление класса модели Add a Model Class

Проверьте класс Product : Examine the Product class:

Этот класс соответствует модели данных, используемой веб-API. This class matches the data model used by the web API. Приложение может использовать HttpClient для чтения Product экземпляра из HTTP-ответа. An app can use HttpClient to read a Product instance from an HTTP response. Приложению не нужно писать код десериализации. The app doesn’t have to write any deserialization code.

Создание и инициализация HttpClient Create and Initialize HttpClient

Изучите статическое свойство HttpClient : Examine the static HttpClient property:

HttpClient предназначен для однократного создания и повторного использования в течение всего жизненного цикла приложения. HttpClient is intended to be instantiated once and reused throughout the life of an application. Следующие условия могут привести к ошибкам SocketException : The following conditions can result in SocketException errors:

• Создание нового экземпляра HttpClient для каждого запроса. Creating a new HttpClient instance per request.
• Сервер при интенсивной нагрузке. Server under heavy load.

Создание нового экземпляра HttpClient для каждого запроса может исчерпать доступные сокеты. Creating a new HttpClient instance per request can exhaust the available sockets.

Следующий код инициализирует экземпляр HttpClient : The following code initializes the HttpClient instance:

Предыдущий код: The preceding code:

• Задает базовый URI для HTTP-запросов. Sets the base URI for HTTP requests. Измените номер порта на порт, используемый в серверном приложении. Change the port number to the port used in the server app. Приложение не будет работать, если не используется порт для серверного приложения. The app won’t work unless port for the server app is used.
• Устанавливает заголовок Accept в значение Application/JSON. Sets the Accept header to «application/json». Установка этого заголовка сообщает серверу о необходимости отправки данных в формате JSON. Setting this header tells the server to send data in JSON format.

Отправка запроса GET для получения ресурса Send a GET request to retrieve a resource

Следующий код отправляет запрос GET для продукта: The following code sends a GET request for a product:

Метод Async ОТПРАВЛЯЕТ запрос HTTP GET. The GetAsync method sends the HTTP GET request. Когда метод завершает работу, он возвращает HttpResponseMessage , СОДЕРЖАЩИЙ ответ HTTP. When the method completes, it returns an HttpResponseMessage that contains the HTTP response. Если код состояния в ответе является кодом успешного выполнения, текст ответа содержит представление JSON продукта. If the status code in the response is a success code, the response body contains the JSON representation of a product. Вызовите реадасасинк , чтобы десериализовать полезные данные JSON в Product экземпляре. Call ReadAsAsync to deserialize the JSON payload to a Product instance. Метод реадасасинк является асинхронным, так как текст ответа может быть произвольным большим. The ReadAsAsync method is asynchronous because the response body can be arbitrarily large.

HttpClient не создает исключение, если HTTP-ответ содержит код ошибки. HttpClient does not throw an exception when the HTTP response contains an error code. Вместо этого свойство IsSuccessStatusCode имеет значение false , если состояние — код ошибки. Instead, the IsSuccessStatusCode property is false if the status is an error code. Если вы предпочитаете обрабатывать коды ошибок HTTP как исключения, вызовите метод HttpResponseMessage. енсуресукцессстатускоде для объекта Response. If you prefer to treat HTTP error codes as exceptions, call HttpResponseMessage.EnsureSuccessStatusCode on the response object. EnsureSuccessStatusCode создает исключение, если код состояния находится за пределами диапазона 200 – 299. EnsureSuccessStatusCode throws an exception if the status code falls outside the range 200–299. Обратите внимание, что HttpClient может создавать исключения по другим причинам, например при истечении — времени ожидания запроса. Note that HttpClient can throw exceptions for other reasons — for example, if the request times out.

Media-Type модулей форматирования для десериализации Media-Type Formatters to Deserialize

Когда реадасасинк вызывается без параметров, он использует набор модулей форматирования мультимедиа по умолчанию для чтения текста ответа. When ReadAsAsync is called with no parameters, it uses a default set of media formatters to read the response body. Модули форматирования по умолчанию поддерживают данные JSON, XML и кодируются в формате URL. The default formatters support JSON, XML, and Form-url-encoded data.

Вместо использования модулей форматирования по умолчанию можно предоставить список модулей форматирования для метода реадасасинк . Instead of using the default formatters, you can provide a list of formatters to the ReadAsAsync method. Использование списка модулей форматирования полезно при наличии пользовательского модуля форматирования типа мультимедиа: Using a list of formatters is useful if you have a custom media-type formatter:

Отправка запроса POST для создания ресурса Sending a POST Request to Create a Resource

Следующий код отправляет запрос POST, содержащий Product экземпляр в формате JSON: The following code sends a POST request that contains a Product instance in JSON format:

Метод постасжсонасинк : The PostAsJsonAsync method:

• Сериализует объект в JSON. Serializes an object to JSON.
• Отправляет полезные данные JSON в запрос POST. Sends the JSON payload in a POST request.

Если запрос будет выполнен, выполните следующие действия: If the request succeeds:

• Он должен возвращать ответ 201 (создан). It should return a 201 (Created) response.
• Ответ должен содержать URL-адрес созданных ресурсов в заголовке Location. The response should include the URL of the created resources in the Location header.

Отправка запроса на размещение для обновления ресурса Sending a PUT Request to Update a Resource

Следующий код отправляет запрос на размещение для обновления продукта: The following code sends a PUT request to update a product:

Метод путасжсонасинк работает так же, как постасжсонасинк, за исключением того, что он отправляет запрос на размещение вместо POST. The PutAsJsonAsync method works like PostAsJsonAsync, except that it sends a PUT request instead of POST.

Отправка запроса на удаление для удаления ресурса Sending a DELETE Request to Delete a Resource

Следующий код отправляет запрос на удаление для удаления продукта: The following code sends a DELETE request to delete a product:

Как и в случае GET, запрос на удаление не содержит текст запроса. Like GET, a DELETE request does not have a request body. Не нужно указывать формат JSON или XML с помощью DELETE. You don’t need to specify JSON or XML format with DELETE.

Тестирование примера Test the sample

Чтобы протестировать клиентское приложение, выполните следующие действия. To test the client app:

Скачайте и запустите серверное приложение. Download and run the server app. Указания по скачиванию. Download instructions. Убедитесь, что серверное приложение работает. Verify the server app is working. Например, http://localhost:64195/api/products должен возвращать список продуктов. For example, http://localhost:64195/api/products should return a list of products.

Задайте базовый URI для HTTP-запросов. Set the base URI for HTTP requests. Измените номер порта на порт, используемый в серверном приложении. Change the port number to the port used in the server app.

Запустите клиентское приложение. Run the client app. Выводятся следующие результаты: The following output is produced:

Quickstart: Acquire a token and call Microsoft Graph API from a Windows desktop app

In this quickstart, you download and run a code sample that demonstrates how a Windows desktop .NET (WPF) application can sign in users and get an access token to call the Microsoft Graph API.

See How the sample works for an illustration.

Prerequisites

Register and download your quickstart app

You have two options to start your quickstart application:

Option 1: Register and auto configure your app and then download your code sample

1. Go to the Azure portal — App registrations quickstart experience.
2. Enter a name for your application and select Register.
3. Follow the instructions to download and automatically configure your new application with just one click.

Option 2: Register and manually configure your application and code sample

Step 1: Register your application

To register your application and add the app’s registration information to your solution manually, follow these steps:

1. Sign in to the Azure portal.
2. If you have access to multiple tenants, use the Directory + subscription filter in the top menu to select the tenant in which you want to register an application.
3. Search for and select Azure Active Directory.
4. Under Manage, select App registrations >New registration.
5. Enter a Name for your application, for example Win-App-calling-MsGraph . Users of your app might see this name, and you can change it later.
6. In the Supported account types section, select Accounts in any organizational directory and personal Microsoft accounts (for example, Skype, Xbox, Outlook.com).
7. Select Register to create the application.
8. Under Manage, select Authentication.
9. Select Add a platform >Mobile and desktop applications.
10. In the Redirect URIs section, select https://login.microsoftonline.com/common/oauth2/nativeclient and in Custom redirect URIs add ms-appx-web://microsoft.aad.brokerplugin/ where is the application (client) ID of your application (the same GUID that appears in the msal://auth checkbox).
11. Select Configure.

Step 1: Configure your application in Azure portal

For the code sample in this quickstart to work, add a Redirect URI of https://login.microsoftonline.com/common/oauth2/nativeclient and ms-appx-web://microsoft.aad.brokerplugin/ .

Your application is configured with these attributes.