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

Использование пакета SDK ASP.NET Framework для мобильных приложений Azure

  • Статья

Заметка

Этот продукт отставлен. Сведения о замене проектов с помощью .NET 8 или более поздней версии см. вбиблиотеке Community Toolkit Datasync.

В этом разделе показано, как использовать пакет SDK серверного сервера .NET в ключевых сценариях мобильных приложений Службы приложений Azure. Пакет SDK для мобильных приложений Azure помогает работать с мобильными клиентами из приложения ASP.NET.

Предупреждение

В этой статье рассматриваются сведения о версии библиотеки версии 4.2.0, которая заменена библиотекой версии 5.0.0. Актуальные сведения см. в статье последней версии

Создание серверной части ASP.NET Платформы мобильных приложений Azure

Вы можете создать приложение ASP.NET Framework с помощью Visual Studio 2019.

  • Выберите шаблон веб-приложения ASP.NET (.NET Framework). Если у вас возникли проблемы с поиском этого шаблона, выберите C#, Все платформыи Веб-.
  • Выбрав имя и расположение приложения, выберите шаблон проекта веб-API. Будет установлена правильная коллекция базовых служб для приложения.

Скачивание и инициализация пакета SDK

Пакет SDK доступен в NuGet.orgи предоставляет базовые функциональные возможности, необходимые для начала работы с мобильными приложениями Azure. Чтобы установить пакет, выполните следующие действия.

  1. Щелкните проект правой кнопкой мыши, а затем выберите Управление пакетами NuGet....
  2. На вкладке Обзор введите Microsoft.Azure.Mobile.Server в поле поиска, а затем нажмите клавишу ВВОД.
  3. Выберите пакет Microsoft.Azure.Mobile.Server.Quickstart.
  4. Щелкните Установить.
  5. Следуйте инструкциям, чтобы завершить установку.

Повторите процесс, чтобы установить Microsoft.Owin.Host.SystemWeb, а также.

Заметка

Не обновляйте пакеты, используемые в качестве зависимостей, например Newtonsoft.JSON или System.IdentityModel.Jwt. API этих пакетов во многих случаях изменились и теперь несовместимы с мобильными приложениями Azure для ASP.NET Framework.

Инициализация проекта сервера

Проект сервера мобильных приложений Azure инициализирован, как и другие проекты ASP.NET Framework; включая класс запуска OWIN. Чтобы добавить класс запуска OWIN, выполните приведенные действия.

  1. Щелкните проект правой кнопкой мыши, а затем выберите Добавить>новый элемент

  2. Выберите веб->Общие, а затем выберите шаблон класса запуска OWIN.

  3. Введите имя Startup.cs в качестве имени запуска.

  4. Содержимое файла Startup.cs должно совпадать со следующим кодом:

    using Microsoft.Azure.Mobile.Server.Config;
using Microsoft.Owin;
using Owin;
using System.Web.Http;

[assembly: OwinStartup(typeof(WebApplication1.Startup))]
namespace WebApplication1
{
    public class Startup
    {
        public void Configuration(IAppBuilder app)
        {
            HttpConfiguration config = new HttpConfiguration();
            new MobileAppConfiguration()
                // no added features
                .ApplyTo(config);
            app.UseWebApi(config);
        }
    }
}

    OwinStartup, пространство имен и имя класса будут отличаться в зависимости от проекта. В частности, следует заменить содержимое метода Configuration() и соответствующим образом настроить директивы using.

Чтобы включить отдельные функции, необходимо вызвать методы расширения в объекте MobileAppConfiguration перед вызовом ApplyTo. Например, следующий код добавляет маршруты по умолчанию ко всем контроллерам API, имеющим атрибут [MobileAppController] во время инициализации:

new MobileAppConfiguration()
    .MapApiControllers()
    .ApplyTo(config);

Следующая настройка считается обычным использованием, которое позволяет контроллерам таблиц и API использовать Entity Framework для доступа к службе SQL.

new MobileAppConfiguration()
    .AddMobileAppHomeController()
    .MapApiControllers()
    .AddTables(
        new MobileAppTableConfiguration()
            .MapTableControllers()
            .AddEntityFramework()
    )
    .MapLegacyCrossDomainController()
    .ApplyTo(config);

Используются методы расширения:

  • AddMobileAppHomeController() предоставляет домашнюю страницу мобильных приложений Azure по умолчанию.
  • MapApiControllers() предоставляет пользовательские возможности API для контроллеров WebAPI, украшенных атрибутом [MobileAppController].
  • AddTables() предоставляет сопоставление конечных точек /tables с контроллерами таблиц.
  • AddTablesWithEntityFramework() — это короткое слово для сопоставления конечных точек /tables с помощью контроллеров на основе Entity Framework.
  • MapLegacyCrossDomainController() предоставляет стандартные заголовки CORS для локальной разработки.

Расширения ПАКЕТА SDK

Следующие пакеты расширений на основе NuGet предоставляют различные мобильные функции, которые могут использоваться приложением. Расширения можно включить во время инициализации с помощью объекта MobileAppConfiguration.

  • Microsoft.Azure.Mobile.Server.Quickstart Поддерживает базовую настройку мобильных приложений. Добавлена в конфигурацию путем вызова метода расширения UseDefaultConfiguration во время инициализации. Это расширение включает следующие расширения: уведомления, проверка подлинности, сущность, таблицы, междоменные и домашние пакеты.
  • Microsoft.Azure.Mobile.Server.Home Реализует по умолчанию это мобильное приложение выполняется для корневого веб-сайта. Добавьте в конфигурацию, вызвав метод расширения AddMobileAppHomeController.
  • Microsoft.Azure.Mobile.Server.Tables включает классы для работы с данными и настройки конвейера данных. Добавьте в конфигурацию, вызвав метод расширения AddTables.
  • Microsoft.Azure.Mobile.Server.Entity позволяет Entity Framework получать доступ к данным в базе данных SQL. Добавьте в конфигурацию путем вызова метода расширения AddTablesWithEntityFramework.
  • Microsoft.Azure.Mobile.Server.Authentication Включает проверку подлинности и настраивает ПО промежуточного слоя OWIN, используемого для проверки маркеров. Добавьте в конфигурацию, вызвав AddAppServiceAuthentication и IAppBuilder.методы расширения UseAppServiceAuthentication.
  • Microsoft.Azure.Mobile.Server.Notifications включает push-уведомления и определяет конечную точку регистрации push-уведомлений. Добавьте в конфигурацию, вызвав метод расширения AddPushNotifications.
  • Microsoft.Azure.Mobile.Server.CrossDomain Создает контроллер, который служит данным для устаревших веб-браузеров из мобильного приложения. Добавьте в конфигурацию, вызвав метод расширения MapLegacyCrossDomainController.
  • Microsoft.Azure.Mobile.Server.Login Предоставляет метод AppServiceLoginHandler.CreateToken(), который является статическим методом, используемым во время пользовательских сценариев проверки подлинности.

Публикация проекта сервера

В этом разделе показано, как опубликовать внутренний проект .NET из Visual Studio. Существуют другие методы, с помощью которых можно опубликовать приложение. Дополнительные сведения см. в документации по службе приложений Azure .

  1. В Visual Studio перестройте проект для восстановления пакетов NuGet.
  2. В обозревателе решений щелкните проект правой кнопкой мыши, щелкните Опубликовать.
  3. Если вы еще не опубликовали этот проект, вы настроите публикацию.
    • Выберите Azure для целевого объекта.
    • Выберите Службу приложений Azure (Windows) для конкретного целевого объекта.
    • Выберите экземпляр службы приложений, на который вы хотите развернуть. Если у вас его нет, используйте + для создания.
    • Нажмите кнопку Готово.
  4. Если вы еще не связали базу данных SQL, щелкните Настроить рядом с базой данных SQL.
    • Выбор базы данных SQL Azure
    • Выберите базу данных. Если у вас нет другого или вы хотите использовать другой, щелкните +, чтобы создать новую базу данных и сервер.
    • Введите MS_TableConnectionString в качестве имени строки подключения к базе данных. Введите имя пользователя и пароль в указанных полях.
    • Нажмите кнопку Готово
  5. Щелкните опубликовать

Для публикации в Azure потребуется некоторое время. Дополнительные сведения см. в документации по Visual Studio.

Определение контроллера таблицы

Определите контроллер таблицы для предоставления таблицы SQL мобильным клиентам. Настройка контроллера таблицы требует трех шагов.

  1. Создайте класс DTO.
  2. Настройте ссылку на таблицу в классе Mobile DbContext.
  3. Создайте контроллер таблицы.

Объект передачи данных (DTO) — это обычный объект C#, наследуемый от EntityData. Например:

public class TodoItem : EntityData
{
    public string Text { get; set; }
    public bool Complete {get; set;}
}

DTO используется для определения таблицы в базе данных SQL. Чтобы создать запись базы данных, добавьте свойство DbSet<> в DbContext, которое вы используете:

public class MobileServiceContext : DbContext
{
    private const string connectionStringName = "Name=MS_TableConnectionString";

    public MobileServiceContext() : base(connectionStringName)
    {

    }

    public DbSet<TodoItem> TodoItems { get; set; }

    protected override void OnModelCreating(DbModelBuilder modelBuilder)
    {
        modelBuilder.Conventions.Add(
            new AttributeToColumnAnnotationConvention<TableColumnAttribute, string>(
                "ServiceColumnTable", (property, attributes) => attributes.Single().ColumnType.ToString()));
    }
}

Наконец, создайте новый контроллер:

  1. Щелкните правой кнопкой мыши папку Controllers.

  2. Выберите контроллер веб-API >веб-API 2 — пустой

  3. Введите имя контроллера.

  4. Замените содержимое нового контроллера следующим кодом:

    public class TodoItemController : TableController<TodoItem>
{
    protected override void Initialize(HttpControllerContext controllerContext)
    {
        base.Initialize(controllerContext);
        ZUMOAPPNAMEContext context = new ZUMOAPPNAMEContext();
        DomainManager = new EntityDomainManager<TodoItem>(context, Request);
    }

    // GET tables/TodoItem
    public IQueryable<TodoItem> GetAllTodoItems()
    {
        return Query();
    }

    // GET tables/TodoItem/48D68C86-6EA6-4C25-AA33-223FC9A27959
    public SingleResult<TodoItem> GetTodoItem(string id)
    {
        return Lookup(id);
    }

    // PATCH tables/TodoItem/48D68C86-6EA6-4C25-AA33-223FC9A27959
    public Task<TodoItem> PatchTodoItem(string id, Delta<TodoItem> patch)
    {
        return UpdateAsync(id, patch);
    }

    // POST tables/TodoItem
    public async Task<IHttpActionResult> PostTodoItem(TodoItem item)
    {
        TodoItem current = await InsertAsync(item);
        return CreatedAtRoute("Tables", new { id = current.Id }, current);
    }

    // DELETE tables/TodoItem/48D68C86-6EA6-4C25-AA33-223FC9A27959
    public Task DeleteTodoItem(string id)
    {
        return DeleteAsync(id);
    }
}

Настройка размера разбиения на страницы таблицы

По умолчанию мобильные приложения Azure возвращают 50 записей на запрос. Разбиение на страницах гарантирует, что клиент не связывает поток пользовательского интерфейса или сервер слишком долго, обеспечивая хороший интерфейс пользователя. Чтобы изменить размер таблицы на страницы, увеличьте размер сервера "разрешенный размер запроса" и размер страницы на стороне клиента, "разрешенный размер запроса" настраивается с помощью атрибута EnableQuery:

[EnableQuery(PageSize = 500)]

Убедитесь, что PageSize совпадает с размером, запрошенным клиентом. Дополнительные сведения об изменении размера клиентской страницы см. в документации по инструкции по использованию ИНСТРУКЦИЙ клиента.

Определение пользовательского контроллера API

Пользовательский контроллер API предоставляет самые основные функциональные возможности серверной части мобильного приложения, предоставляя конечную точку. Вы можете зарегистрировать контроллер API для мобильных устройств с помощью атрибута [MobileAppController]. Атрибут MobileAppController регистрирует маршрут, настраивает сериализатор JSON мобильных приложений и включает проверку версий клиента.

Содержимое пользовательского контроллера API:

[MobileAppController]
public class CustomAPIController : ApiController
{
    // Content here
}

После настройки с помощью атрибута MobileAppController можно определить пользовательский API таким же образом, как и любой другой веб-API.

Работа с проверкой подлинности

Мобильные приложения Azure используют проверку подлинности и авторизацию службы приложений для защиты серверной части мобильных устройств. В этом разделе показано, как выполнять следующие задачи, связанные с проверкой подлинности, в проекте серверного сервера .NET:

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

Вы можете добавить проверку подлинности в проект сервера, расширив объект MobileAppConfiguration и настроив ПО промежуточного слоя OWIN.

  1. В Visual Studio установите пакет Microsoft.Azure.Mobile.Server.Authentication.

  2. В файле проекта добавьте следующую строку кода в начале метода конфигурации :

    app.UseAppServiceAuthentication(config);

    Этот компонент ПО промежуточного слоя OWIN проверяет маркеры, выданные соответствующим шлюзом службы приложений.

  3. Добавьте атрибут [Authorize] к любому контроллеру или методу, требующим проверки подлинности.

Использование пользовательской проверки подлинности для приложения

Важный

Чтобы включить пользовательскую проверку подлинности, необходимо сначала включить проверку подлинности службы приложений без выбора поставщика для службы приложений на портале Azure. Это позволит включить переменную среды WEBSITE_AUTH_SIGNING_KEY при размещении.

Если вы не хотите использовать один из поставщиков проверки подлинности и авторизации службы приложений, вы можете реализовать собственную систему входа. Установите пакет Microsoft.Azure.Mobile.Server.Login, чтобы помочь в создании маркера проверки подлинности. Укажите собственный код для проверки учетных данных пользователя. Например, можно проверить наличие соленых и хэшированных паролей в базе данных. В приведенном ниже примере метод isValidAssertion() (определенный в другом месте) отвечает за эти проверки.

Пользовательская проверка подлинности предоставляется путем создания ApiController и предоставления register и login действий. Клиент должен использовать пользовательский интерфейс для сбора сведений от пользователя. Затем сведения передаются в API с помощью стандартного вызова HTTP POST. После проверки утверждения маркер будет выдан с помощью метода AppServiceLoginHandler.CreateToken(). ApiController не должен использовать атрибут [MobileAppController].

Пример действия login:

public IHttpActionResult Post([FromBody] JObject assertion)
{
    if (isValidAssertion(assertion)) // user-defined function, checks against a database
    {
        JwtSecurityToken token = AppServiceLoginHandler.CreateToken(new Claim[] { new Claim(JwtRegisteredClaimNames.Sub, assertion["username"]) },
            mySigningKey,
            myAppURL,
            myAppURL,
            TimeSpan.FromHours(24) );
        return Ok(new LoginResult()
        {
            AuthenticationToken = token.RawData,
            User = new LoginResultUser() { UserId = userName.ToString() }
        });
    }
    else // user assertion was not valid
    {
        return this.Request.CreateUnauthorizedResponse();
    }
}

В предыдущем примере LoginResult и LoginResultUser являются сериализуемыми объектами, предоставляющими необходимые свойства. Клиент ожидает, что ответы входа будут возвращены в виде объектов JSON формы:

{
    "authenticationToken": "<token>",
    "user": {
        "userId": "<userId>"
    }
}

Метод включает аудитории и параметр издателя. Оба этих параметра имеют URL-адрес корневого каталога приложения, используя схему HTTPS. Аналогичным образом необходимо задать secretKey значение ключа подписи приложения. Не распределяйте ключ подписи в клиенте, так как его можно использовать для олицетворения ключей и олицетворения пользователей. Ключ подписи можно получить во время размещения в Службе приложений, ссылаясь на переменную среды WEBSITE_AUTH_SIGNING_KEY. При необходимости в локальном контексте отладки следуйте инструкциям в разделе Локальная отладка с проверкой подлинности, чтобы получить ключ и сохранить его в качестве параметра приложения.

Выданный маркер также может включать другие утверждения и дату окончания срока действия. Как минимум, выданный маркер должен содержать утверждение субъекта (вложенных) .

Вы можете поддерживать стандартный метод loginAsync() клиента, перегрузив маршрут проверки подлинности. Если клиент вызывает client.loginAsync('custom'); для входа, маршрут должен быть /.auth/login/custom. Можно задать маршрут для пользовательского контроллера проверки подлинности с помощью MapHttpRoute():

config.Routes.MapHttpRoute("custom", ".auth/login/custom", new { controller = "CustomAuth" });

Кончик

Использование подхода loginAsync() гарантирует, что маркер проверки подлинности подключен к каждому последующему вызову службы.

Получение сведений о пользователе, прошедших проверку подлинности

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

// Get the SID of the current user.
var claimsPrincipal = this.User as ClaimsPrincipal;
string sid = claimsPrincipal.FindFirst(ClaimTypes.NameIdentifier).Value;

Идентификатор безопасности является производным от идентификатора пользователя для конкретного поставщика и является статическим для данного пользователя и поставщика входа. Идентификатор безопасности имеет значение NULL для недопустимых маркеров проверки подлинности.

Служба приложений также позволяет запрашивать определенные утверждения от поставщика входа. Каждый поставщик удостоверений может предоставить дополнительные сведения с помощью пакета SDK поставщика удостоверений. Например, вы можете использовать API Graph Facebook для сведений о друзьях. Вы можете указать утверждения, запрашиваемые в колонке поставщика на портале Azure. Для некоторых утверждений требуется дополнительная конфигурация с поставщиком удостоверений.

Следующий код вызывает метод расширения GetAppServiceIdentityAsync для получения учетных данных для входа, которые включают маркер доступа, необходимый для выполнения запросов к API Graph Facebook:

// Get the credentials for the logged-in user.
var credentials = await this.User.GetAppServiceIdentityAsync<FacebookCredentials>(this.Request);

if (credentials.Provider == "Facebook")
{
    // Create a query string with the Facebook access token.
    var fbRequestUrl = "https://graph.facebook.com/me/feed?access_token="
        + credentials.AccessToken;

    // Create an HttpClient request.
    var client = new System.Net.Http.HttpClient();

    // Request the current user info from Facebook.
    var resp = await client.GetAsync(fbRequestUrl);
    resp.EnsureSuccessStatusCode();

    // Do something here with the Facebook user information.
    var fbInfo = await resp.Content.ReadAsStringAsync();
}

Добавьте инструкцию using для System.Security.Principal, чтобы предоставить метод расширения GetAppServiceIdentityA sync.

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

В предыдущем разделе мы показали, как получить идентификатор пользователя прошедшего проверку подлинности. Вы можете ограничить доступ к данным и другим ресурсам на основе этого значения. Например, добавление столбца userId в таблицы и фильтрация результатов запроса по идентификатору пользователя — это простой способ ограничить возвращаемые данные только авторизованным пользователям. Следующий код возвращает строки данных, только если идентификатор безопасности соответствует значению в столбце UserId в таблице TodoItem:

// Get the SID of the current user.
var claimsPrincipal = this.User as ClaimsPrincipal;
string sid = claimsPrincipal.FindFirst(ClaimTypes.NameIdentifier).Value;

// Only return data rows that belong to the current user.
return Query().Where(t => t.UserId == sid);

Метод Query() возвращает IQueryable, которые можно управлять с помощью LINQ для обработки фильтрации.

Отладка и устранение неполадок пакета SDK для .NET Server

Служба приложений Azure предоставляет несколько методов отладки и устранения неполадок для ASP.NET приложений:

Лесозаготовка

Журналы диагностики службы приложений можно записать с помощью стандартной записи трассировки ASP.NET. Перед записью в журналы необходимо включить диагностику в серверной части мобильных приложений Azure.

Чтобы включить диагностику и запись в журналы, выполните следующие действия.

  1. Выполните действия, описанные в разделе Включение ведения журнала приложений (Windows).

  2. Добавьте следующую инструкцию using в файл кода:

    using System.Web.Http.Tracing;

  3. Создайте модуль записи трассировки для записи из серверной части .NET в журналы диагностики следующим образом:

    ITraceWriter traceWriter = this.Configuration.Services.GetTraceWriter();
traceWriter.Info("Hello, World");

  4. Повторно опубликуйте проект сервера и получите доступ к серверной части мобильных приложений Azure, чтобы выполнить путь кода с помощью ведения журнала.

  5. Скачайте и оцените журналы, как описано в файлах журналов Access.

Локальная отладка с проверкой подлинности

Вы можете запустить приложение локально, чтобы протестировать изменения перед их публикацией в облаке. Для большинства серверных компонентов мобильных приложений Azure нажмите клавишу F5 в Visual Studio. Однако при использовании проверки подлинности существуют некоторые дополнительные аспекты.

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

Убедитесь, что серверная часть мобильного устройства установлена Microsoft.Azure.Mobile.Server.Authentication. Затем в классе запуска OWIN приложения добавьте следующее после применения MobileAppConfiguration к HttpConfiguration:

app.UseAppServiceAuthentication(new AppServiceAuthenticationOptions()
{
    SigningKey = ConfigurationManager.AppSettings["authSigningKey"],
    ValidAudiences = new[] { ConfigurationManager.AppSettings["authAudience"] },
    ValidIssuers = new[] { ConfigurationManager.AppSettings["authIssuer"] },
    TokenHandler = config.GetAppServiceTokenHandler()
});

В предыдущем примере необходимо настроить authAudience и authIssuer параметры приложения в файле Web.config в каждом URL-адресе корневого приложения, используя схему HTTPS. Аналогичным образом необходимо задать authSigningKey значение ключа подписи приложения.

Чтобы получить ключ подписи, выполните следующие действия.

  1. Перейдите к приложению на портале Azure
  2. Щелкните Сервис>Kudu>Перейти.
  3. На сайте управления Kudu щелкните среды.
  4. Найдите значение для WEBSITE_AUTH_SIGNING_KEY.

Используйте ключ подписи для параметра authSigningKey в конфигурации локального приложения. Теперь серверная часть мобильного устройства оснащена для проверки маркеров при локальном запуске, который клиент получает маркер из облачной конечной точки.