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

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

Майк Уосон

Скачивание завершенного проекта

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

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

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

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

См. статью "Создание веб-API с помощью ASP.NET Core и Visual Studio для Windows" для более новой версии этого руководства.

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

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

Снимок экрана: окно локального браузера узла, показывающее пример проекта со списком продуктов, их ценами и полем поиска по полям I D и кнопке.

Запустите 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.

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

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

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

Если обозреватель решений еще не отображается, щелкните меню "Вид " и выберите обозреватель решений. В обозревателе решений щелкните правой кнопкой мыши папку 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 .

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

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

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

Снимок экрана, показывающий параметры меню диалогового окна

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

Снимок экрана диалогового окна 'Добавить контроллер', показывающего текст 'контроллер продуктов' в поле и кнопку добавления под ним.

Шаблон создает файл с именем ProductsController.cs в папке "Контроллеры".

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

Замечание

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

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

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<Product>.
  • Метод GetProduct ищет один продукт по его идентификатору.

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

Метод контроллера URI
GetAllProducts /api/products
ПолучитьПродукт /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", где идентификатором является идентификатор продукта.

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 в Internet Explorer 9. В Internet Explorer 9 нажмите клавишу F12 , чтобы открыть инструменты. Перейдите на вкладку "Сеть" и нажмите кнопку "Начать запись". Теперь вернитесь на веб-страницу и нажмите клавишу F5 , чтобы перезагрузить веб-страницу. Internet Explorer фиксирует HTTP-трафик между браузером и веб-сервером. В представлении сводки отображается весь сетевой трафик для страницы:

Снимок экрана окна сообщения запроса и ответа HTTP, отображающего список URL и все ответы сетевого трафика.

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

Снимок экрана диалогового окна сообщения запроса и ответа H T T P, в котором передан пример ответа на индивидуальный запрос А П И.

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

Ознакомьтесь с этим приложением, работающим в Azure

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

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

Дальнейшие шаги

  • Last updated on