Поделиться через

Начало работы с веб-API ASP.NET 2 (C#)

  • Статья

Майк Уассон

Скачать завершенный проект

В этом руководстве вы будете использовать веб-API ASP.NET для создания веб-API, который возвращает список продуктов.

HTTP предназначен не только для обслуживания веб-страниц. HTTP также является мощной платформой для создания API, которые предоставляют службы и данные. HTTP — это простой, гибкий и вездесущий протокол. Почти любая платформа, которую можно представить, имеет библиотеку HTTP, поэтому службы HTTP могут обращаться к широкому кругу клиентов, включая браузеры, мобильные устройства и традиционные классические приложения.

веб-API ASP.NET — это платформа для создания веб-API на основе платформа .NET Framework.

Версии программного обеспечения, используемые в этом руководстве

Дополнительные сведения см. в статье Создание веб-API с помощью ASP.NET Core и Visual Studio для Windows.

Создание проекта веб-API

В этом руководстве вы будете использовать веб-API ASP.NET для создания веб-API, который возвращает список продуктов. Интерфейсная веб-страница использует jQuery для отображения результатов.

Снимок экрана: окно браузера локального узла с примером проекта со списком продуктов, их ценами, полем и кнопкой поиска по идентификатору.

Запустите Visual Studio и выберите Создать проект на начальной странице. Или в меню Файл выберите Создать , а затем — Проект.

В области Шаблоны выберите Установленные шаблоны и разверните узел Visual C# . В разделе Visual C# выберите Интернет. В списке шаблонов проектов выберите ASP.NET веб-приложение. Назовите проект ProductsApp и нажмите кнопку ОК.

Снимок экрана: параметры шаблона

В диалоговом окне Создать проект ASP.NET выберите пустой шаблон. В разделе "Добавление папок и основных ссылок для" проверка веб-API. Нажмите кнопку ОК.

Снимок экрана: диалоговое окно нового проекта с разными параметрами шаблона и тремя вариантами выбора папок и основной ссылки.

Примечание

Вы также можете создать проект веб-API с помощью шаблона "Веб-API". Шаблон веб-API использует ASP.NET MVC для предоставления страниц справки по API. Я использую пустой шаблон для этого руководства, так как я хочу показать веб-API без MVC. Как правило, вам не нужно знать, ASP.NET MVC для использования веб-API.

Добавление модели

Модель — это объект, который представляет данные в приложении. веб-API ASP.NET может автоматически сериализовать модель в ФОРМАТЕ JSON, XML или в другом формате, а затем записать сериализованные данные в текст ответа HTTP. Пока клиент может считывать формат сериализации, он может десериализовать объект . Большинство клиентов могут анализировать XML или JSON. Кроме того, клиент может указать нужный формат, задав заголовок Accept в сообщении HTTP-запроса.

Начнем с создания простой модели, представляющей продукт.

Если обозреватель решений не отображается, щелкните меню Просмотр и выберите Обозреватель решений. В обозревателе решений щелкните правой кнопкой мыши папку Models. В контекстном меню выберите Добавить, а затем выберите Класс.

Снимок экрана: меню обозревателя решений с параметрами, расположенными в папке models, где показано, как добавить класс.

Назовите класс "Product". Добавьте следующие свойства в Product класс .

namespace ProductsApp.Models
{
    public class Product
    {
        public int Id { get; set; }
        public string Name { get; set; }
        public string Category { get; set; }
        public decimal Price { get; set; }
    }
}

Добавление контроллера

В веб-API контроллер — это объект, который обрабатывает HTTP-запросы. Мы добавим контроллер, который может возвращать список продуктов или один продукт, указанный идентификатором.

Примечание

Если вы использовали ASP.NET MVC, вы уже знакомы с контроллерами. Контроллеры веб-API похожи на контроллеры MVC, но наследуют класс ApiController , а не класс Controller .

В обозревателе решений щелкните правой кнопкой мыши папку Controllers. Щелкните Добавить, а затем выберите Контроллер.

Снимок экрана: меню обозревателя решений с визуальным руководством по добавлению класса контроллера в проект.

В диалоговом окне Добавление шаблона выберите Контроллер веб-API — пустой. Нажмите кнопку Добавить.

Снимок экрана: параметры меню диалогового окна

В диалоговом окне Добавление контроллера назовите контроллер "ProductsController". Нажмите кнопку Добавить.

Снимок экрана: диалоговое окно

Формирование шаблонов создает файл с именем ProductsController.cs в папке Controllers.

Снимок экрана: параметры меню обозревателя решений, обращающиеся к только что созданному параметру с именем

Примечание

Вам не нужно помещать контроллеры в папку с именем Контроллеры. Имя папки — это просто удобный способ упорядочить исходные файлы.

Если этот файл еще не открыт, дважды щелкните его. Замените код в этом файле следующим кодом:

using ProductsApp.Models;
using System;
using System.Collections.Generic;
using System.Linq;
using System.Net;
using System.Web.Http;

namespace ProductsApp.Controllers
{
    public class ProductsController : ApiController
    {
        Product[] products = new Product[] 
        { 
            new Product { Id = 1, Name = "Tomato Soup", Category = "Groceries", Price = 1 }, 
            new Product { Id = 2, Name = "Yo-yo", Category = "Toys", Price = 3.75M }, 
            new Product { Id = 3, Name = "Hammer", Category = "Hardware", Price = 16.99M } 
        };

        public IEnumerable<Product> GetAllProducts()
        {
            return products;
        }

        public IHttpActionResult GetProduct(int id)
        {
            var product = products.FirstOrDefault((p) => p.Id == id);
            if (product == null)
            {
                return NotFound();
            }
            return Ok(product);
        }
    }
}

Чтобы упростить пример, продукты хранятся в фиксированном массиве внутри класса контроллера. Конечно, в реальном приложении вы будете запрашивать базу данных или использовать другой внешний источник данных.

Контроллер определяет два метода, возвращающих продукты:

  • Метод GetAllProducts возвращает весь список продуктов как тип продукта> IEnumerable<.
  • Метод GetProduct ищет один продукт по его идентификатору.

Вот и все! У вас есть рабочий веб-API. Каждый метод на контроллере соответствует одному или нескольким URI:

Метод контроллера URI
GetAllProducts /api/products
GetProduct /api/products/id

GetProduct Для метода идентификатор в URI является заполнителем. Например, чтобы получить продукт с идентификатором 5, универсальный код ресурса (URI) имеет значение api/products/5.

Дополнительные сведения о том, как веб-API направляет HTTP-запросы к методам контроллера, см. в статье Маршрутизация в веб-API ASP.NET.

Вызов веб-API с помощью JavaScript и jQuery

В этом разделе мы добавим HTML-страницу, которая использует AJAX для вызова веб-API. Мы будем использовать jQuery для выполнения вызовов AJAX, а также для обновления страницы с результатами.

В Обозреватель решений щелкните правой кнопкой мыши проект и выберите Добавить, а затем — Новый элемент.

Снимок экрана: меню обозревателя решений с выделенным параметром приложения products для отображения выбранных в меню элементов для добавления нового элемента.

В диалоговом окне Добавление нового элемента выберите веб-узел в разделе Visual C#, а затем выберите элемент HTML-страница . Назовите страницу "index.html".

Снимок экрана: параметры меню

Замените все содержимое этого файла следующим:

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
  <title>Product App</title>
</head>
<body>

  <div>
    <h2>All Products</h2>
    <ul id="products" />
  </div>
  <div>
    <h2>Search by ID</h2>
    <input type="text" id="prodId" size="5" />
    <input type="button" value="Search" onclick="find();" />
    <p id="product" />
  </div>

  <script src="https://ajax.aspnetcdn.com/ajax/jQuery/jquery-2.0.3.min.js"></script>
  <script>
    var uri = 'api/products';

    $(document).ready(function () {
      // Send an AJAX request
      $.getJSON(uri)
          .done(function (data) {
            // On success, 'data' contains a list of products.
            $.each(data, function (key, item) {
              // Add a list item for the product.
              $('<li>', { text: formatItem(item) }).appendTo($('#products'));
            });
          });
    });

    function formatItem(item) {
      return item.Name + ': $' + item.Price;
    }

    function find() {
      var id = $('#prodId').val();
      $.getJSON(uri + '/' + id)
          .done(function (data) {
            $('#product').text(formatItem(data));
          })
          .fail(function (jqXHR, textStatus, err) {
            $('#product').text('Error: ' + err);
          });
    }
  </script>
</body>
</html>

Для получения jQuery можно использовать следующие способы. В этом примере я использовал cdn Microsoft Ajax. Вы также можете скачать его по адресу http://jquery.com/, и шаблон проекта ASP.NET "Веб-API" также включает jQuery.

Получение списка продуктов

Чтобы получить список продуктов, отправьте HTTP-запрос GET по адресу /api/products.

Функция jQuery getJSON отправляет запрос AJAX. Ответ содержит массив объектов JSON. Функция done задает обратный вызов, который вызывается при успешном выполнении запроса. В обратном вызове мы обновляем модель DOM, указав сведения о продукте.

$(document).ready(function () {
    // Send an AJAX request
    $.getJSON(apiUrl)
        .done(function (data) {
            // On success, 'data' contains a list of products.
            $.each(data, function (key, item) {
                // Add a list item for the product.
                $('<li>', { text: formatItem(item) }).appendTo($('#products'));
            });
        });
});

Получение продукта по идентификатору

Чтобы получить продукт по идентификатору, отправьте HTTP-запрос GET по адресу /api/products/id, где id — это идентификатор продукта.

function find() {
    var id = $('#prodId').val();
    $.getJSON(apiUrl + '/' + id)
        .done(function (data) {
            $('#product').text(formatItem(data));
        })
        .fail(function (jqXHR, textStatus, err) {
            $('#product').text('Error: ' + err);
        });
}

Мы по-прежнему вызываем getJSON для отправки запроса AJAX, но на этот раз мы помещаем идентификатор в URI запроса. Ответ от этого запроса представляет собой представление одного продукта в формате JSON.

Запуск приложения

Нажмите клавишу F5 для запуска отладки приложения. Веб-страница должна выглядеть следующим образом:

Снимок экрана: веб-браузер с маркированной формой

Чтобы получить продукт по идентификатору, введите идентификатор и нажмите кнопку Поиск:

Снимок экрана: браузер со всеми продуктами и ценами в маркированном виде и числом 2 в поле

Если ввести недопустимый идентификатор, сервер возвращает ошибку HTTP:

Снимок экрана: браузер со списком всех продуктов и их ценами, а также сообщением об ошибке

Использование F12 для просмотра HTTP-запроса и ответа

При работе со службой HTTP может быть очень полезно просматривать http-запросы и ответные сообщения. Это можно сделать с помощью средств разработчика F12 в Интернете Обозреватель 9. В Интернете Обозреватель 9 нажмите клавишу F12, чтобы открыть инструменты. Перейдите на вкладку Сеть и нажмите кнопку Начать запись. Теперь вернитесь на веб-страницу и нажмите клавишу F5 , чтобы перезагрузить веб-страницу. Интернет-Обозреватель фиксирует HTTP-трафик между браузером и веб-сервером. В представлении сводки отображается весь сетевой трафик для страницы:

Снимок экрана: окно запросов и ответов H T T P, в котором отображается список url-адресов ИП и все ответы сетевого трафика.

Найдите запись относительного URI "api/products/". Выберите эту запись и щелкните Перейти к подробному представлению. В представлении сведений есть вкладки для просмотра заголовков и текста запроса и ответа. Например, если щелкнуть вкладку Заголовки запроса , вы увидите, что клиент запросил "application/json" в заголовке Accept.

Снимок экрана: диалоговое окно запроса и ответа H T T P, на котором показан пример ответа на отдельный запрос P I.

Если щелкнуть вкладку Текст ответа, вы увидите, как список продуктов был сериализован в ФОРМАТЕ JSON. Другие браузеры имеют аналогичные функции. Другим полезным инструментом является Fiddler, прокси-сервер веб-отладки. Fiddler можно использовать для просмотра трафика HTTP, а также для создания HTTP-запросов, что обеспечивает полный контроль над заголовками HTTP в запросе.

См. это приложение, работающее в Azure

Хотите, чтобы готовый сайт работал как динамическое веб-приложение? Вы можете развернуть полную версию приложения в своей учетной записи Azure.

Для развертывания этого решения в Azure требуется учетная запись Azure. Если у вас еще нет учетной записи, доступны следующие варианты:

Next Steps