Como usar o SDK do ASP.NET Framework para Aplicativos Móveis do Azure

Este tópico mostra como usar o SDK do servidor back-end .NET nos principais cenários de Aplicativos Móveis do Serviço de Aplicativo do Azure. O SDK de Aplicativos Móveis do Azure ajuda você a trabalhar com clientes móveis de seu aplicativo ASP.NET.

Criar um back-end do Azure Mobile Apps ASP.NET Framework

Você pode criar um aplicativo ASP.NET Framework usando o Visual Studio 2019.

• Escolha o modelo de Aplicativo Web ASP.NET (.NET Framework). Se você estiver tendo problemas para localizar esse modelo, selecione C# , Todas as plataformase Web.
• Depois de selecionar um nome e um local para o aplicativo, selecione a API Web modelo de projeto. A coleção correta de serviços básicos para seu aplicativo será instalada.

Baixe e inicialize o SDK

O SDK está disponível no NuGet.orge fornece a funcionalidade básica necessária para começar a usar os Aplicativos Móveis do Azure. Para instalar o pacote:

1. Clique com o botão direito do mouse no projeto e selecione Gerenciar pacotes NuGet....
2. No separador Procurar, introduza Microsoft.Azure.Mobile.Server na caixa de pesquisa e, em seguida, prima Enter.
3. Selecione o Microsoft.Azure.Mobile.Server.Quickstart pacote.
4. Clique Instalar.
5. Siga as instruções para concluir a instalação.

Repita o processo para instalar Microsoft.Owin.Host.SystemWeb também.

Inicializar o projeto do servidor

Um projeto de servidor de Aplicativos Móveis do Azure é inicializado de forma semelhante a outros projetos do ASP.NET Framework; incluindo uma classe OWIN Startup. Para adicionar uma classe OWIN Startup:

1. Clique com o botão direito do mouse no projeto e selecione Adicionar>Novo Item

2. Selecione Web>Generale, em seguida, selecione o modelo classe OWIN Startup.

3. Digite o nome Startup.cs como o nome da inicialização.

4. O conteúdo do arquivo Startup.cs deve ser semelhante ao seguinte código:

   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);
           }
       }
   }
   

   O OwinStartup, namespace e nome da classe serão diferentes, dependendo do seu projeto. Especificamente, você deve substituir o conteúdo do método Configuration() e ajustar as diretivas using de acordo.

Para habilitar recursos individuais, você deve chamar métodos de extensão no objeto MobileAppConfiguration antes de chamar ApplyTo. Por exemplo, o código a seguir adiciona as rotas padrão a todos os controladores de API que têm o atributo [MobileAppController] durante a inicialização:

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

A configuração a seguir é considerada um uso "normal" que permite que controladores de tabela e API usando o Entity Framework acessem um serviço SQL.

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

Os métodos de extensão utilizados são:

• AddMobileAppHomeController() fornece a home page padrão dos Aplicativos Móveis do Azure.
• MapApiControllers() fornece recursos de API personalizados para controladores WebAPI decorados com o atributo [MobileAppController].
• AddTables() fornece um mapeamento dos pontos de extremidade /tables para controladores de tabela.
• AddTablesWithEntityFramework() é uma abreviação para mapear os pontos de extremidade /tables usando controladores baseados no Entity Framework.
• MapLegacyCrossDomainController() fornece cabeçalhos CORS padrão para o desenvolvimento local.

Extensões SDK

Os seguintes pacotes de extensão baseados em NuGet fornecem vários recursos móveis que podem ser usados pelo seu aplicativo. Você habilita extensões durante a inicialização usando o MobileAppConfiguration objeto.

• Microsoft.Azure.Mobile.Server.Quickstart Suporta a configuração básica de Aplicações Móveis. Adicionado à configuração chamando o UseDefaultConfiguration método de extensão durante a inicialização. Esta extensão inclui as seguintes extensões: Notificações, Autenticação, Entidade, Tabelas, Domínios cruzados e pacotes Home.
• Microsoft.Azure.Mobile.Server.Home Implementa o padrão este aplicativo móvel está ativo e em execução de página para a raiz do site. Adicione à configuração chamando o AddMobileAppHomeController método de extensão.
• Microsoft.Azure.Mobile.Server.Tables inclui classes para trabalhar com dados e configura o pipeline de dados. Adicione à configuração chamando o AddTables método de extensão.
• Microsoft.Azure.Mobile.Server.Entity Permite que o Entity Framework acesse dados no Banco de Dados SQL. Adicione à configuração chamando o AddTablesWithEntityFramework método de extensão.
• Microsoft.Azure.Mobile.Server.Authentication Habilita a autenticação e configura o middleware OWIN usado para validar tokens. Adicione à configuração chamando o AddAppServiceAuthentication e IAppBuilder.UseAppServiceAuthentication métodos de extensão.
• Microsoft.Azure.Mobile.Server.Notifications Habilita notificações por push e define um ponto de extremidade de registro por push. Adicione à configuração chamando o AddPushNotifications método de extensão.
• Microsoft.Azure.Mobile.Server.CrossDomain Cria um controlador que fornece dados para navegadores da Web herdados a partir de seu aplicativo móvel. Adicione à configuração chamando o MapLegacyCrossDomainController método de extensão.
• Microsoft.Azure.Mobile.Server.Login Fornece o método AppServiceLoginHandler.CreateToken(), que é um método estático usado durante cenários de autenticação personalizados.

Publicar o projeto do servidor

Esta seção mostra como publicar seu projeto de back-end .NET do Visual Studio. Existem outros métodos pelos quais você pode publicar seu aplicativo. Para obter mais informações, consulte a documentação do Serviço de Aplicativo do Azure.

1. No Visual Studio, recrie o projeto para restaurar pacotes NuGet.
2. No Gerenciador de Soluções, clique com o botão direito do mouse no projeto, clique em Publicar.
3. Se você não publicou este projeto antes, você configurará a publicação.
   • Selecione do Azure para o destino.
   • Selecione Serviço de Aplicativo do Azure (Windows) para o destino específico.
   • Selecione a instância do serviço de aplicativo na qual você deseja implantar. Se você não tiver um, use o + para criar um.
   • Clique Concluir.
4. Se você não tiver vinculado um banco de dados SQL antes, clique em Configurar ao lado do Banco de dados SQL.
   • Selecione Banco de Dados SQL do Azure
   • Selecione a sua base de dados. Se você não tiver um ou quiser usar um diferente, clique no + para criar um novo banco de dados e servidor.
   • Digite MS_TableConnectionString como o nome da cadeia de conexão do banco de dados. Preencha o nome de utilizador e a palavra-passe nas caixas fornecidas.
   • Clique em Concluir
5. Clique Publicar

Leva algum tempo para publicar no Azure. Para obter mais informações, consulte a documentação do Visual Studio.

Definir um controlador de tabela

Defina um controlador de tabela para expor uma tabela SQL a clientes móveis. A configuração de um controlador de tabela requer três etapas:

1. Crie uma classe DTO (Data Transfer Object).
2. Configure uma referência de tabela na classe Mobile DbContext.
3. Crie um controlador de tabela.

Um objeto de transferência de dados (DTO) é um objeto C# simples que herda de EntityData. Por exemplo:

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

O DTO é usado para definir a tabela dentro do banco de dados SQL. Para criar a entrada do banco de dados, adicione uma propriedade DbSet<> ao DbContext que você está usando:

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()));
    }
}

Finalmente, crie um novo controlador:

1. Clique com o botão direito do rato na pasta Controllers.

2. Selecione Web API>Web API 2 Controller - Esvaziar

3. Insira um nome para o controlador.

4. Substitua o conteúdo do novo controlador pelo seguinte código:

   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);
       }
   }
   

Ajustar o tamanho da paginação da tabela

Por padrão, os Aplicativos Móveis do Azure retornam 50 registros por solicitação. A paginação garante que o cliente não amarre seu thread de interface do usuário nem o servidor por muito tempo, garantindo uma boa experiência do usuário. Para alterar o tamanho da paginação da tabela, aumente o "tamanho da consulta permitido" do lado do servidor e o tamanho da página do lado do cliente O "tamanho da consulta permitido" do lado do servidor é ajustado usando o atributo EnableQuery:

[EnableQuery(PageSize = 500)]

Verifique se o PageSize é igual ou maior do que o tamanho solicitado pelo cliente. Consulte a documentação específica do cliente HOWTO para obter detalhes sobre como alterar o tamanho da página do cliente.

Definir um controlador de API personalizado

O controlador de API personalizado fornece a funcionalidade mais básica para o back-end do seu aplicativo móvel, expondo um ponto de extremidade. Você pode registrar um controlador de API específico para dispositivos móveis usando o atributo [MobileAppController]. O atributo MobileAppController registra a rota, configura o serializador JSON de Aplicativos Móveis e ativa a verificação de versão do cliente.

O conteúdo do controlador de API personalizada é:

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

Uma vez configurado com o atributo MobileAppController, você pode definir a API personalizada da mesma forma que qualquer outra API da Web.

Trabalhar com autenticação

Os Aplicativos Móveis do Azure usam a Autenticação/Autorização do Serviço de Aplicativo para proteger seu back-end móvel. Esta seção mostra como executar as seguintes tarefas relacionadas à autenticação em seu projeto de servidor back-end .NET:

• Adicionar autenticação a um projeto de servidor
• Usar autenticação personalizada para seu aplicativo
• Recuperar informações autenticadas do usuário
• Restringir o acesso a dados para usuários autorizados

Adicionar autenticação a um projeto de servidor

Você pode adicionar autenticação ao seu projeto de servidor estendendo o objeto MobileAppConfiguration e configurando o middleware OWIN.

1. No Visual Studio, instale o pacote de Microsoft.Azure.Mobile.Server.Authentication.

2. No arquivo de projeto Startup.cs, adicione a seguinte linha de código no início do método Configuration:

   app.UseAppServiceAuthentication(config);
   

   Esse componente de middleware OWIN valida tokens emitidos pelo gateway do Serviço de Aplicativo associado.

3. Adicione o atributo [Authorize] a qualquer controlador ou método que exija autenticação.

Usar autenticação personalizada para seu aplicativo

A autenticação personalizada é exposta criando um ApiController e expondo register e login ações. O cliente deve usar uma interface do usuário personalizada para coletar as informações do usuário. As informações são então enviadas para a API com uma chamada HTTP POST padrão. Depois que o servidor valida a asserção, um token é emitido usando o método AppServiceLoginHandler.CreateToken(). O ApiController não deve usar o atributo [MobileAppController].

Um exemplo login ação:

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();
    }
}

No exemplo anterior, LoginResult e LoginResultUser são objetos serializáveis que expõem as propriedades necessárias. O cliente espera que as respostas de login sejam retornadas como objetos JSON do formulário:

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

O método AppServiceLoginHandler.CreateToken() inclui um de audiência e um parâmetro de do emissor. Ambos os parâmetros são definidos para a URL da raiz do seu aplicativo, usando o esquema HTTPS. Da mesma forma, você deve definir secretKey como o valor da chave de assinatura do seu aplicativo. Não distribua a chave de assinatura em um cliente, pois ela pode ser usada para cunhar chaves e representar usuários. Você pode obter a chave de assinatura enquanto hospedado no Serviço de Aplicativo fazendo referência à variável de ambiente WEBSITE_AUTH_SIGNING_KEY. Se necessário em um contexto de depuração local, siga as instruções na seção Depuração local com autenticação para recuperar a chave e armazená-la como uma configuração de aplicativo.

O token emitido também pode incluir outras reivindicações e uma data de validade. Minimamente, o token emitido deve incluir uma reivindicação de assunto (sub).

Você pode oferecer suporte ao método de loginAsync() do cliente padrão sobrecarregando a rota de autenticação. Se o cliente ligar para client.loginAsync('custom'); para fazer login, sua rota deverá ser /.auth/login/custom. Você pode definir a rota para o controlador de autenticação personalizado usando MapHttpRoute():

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

Recuperar informações autenticadas do usuário

Quando um usuário é autenticado pelo Serviço de Aplicativo, você pode acessar o ID de usuário atribuído e outras informações em seu código de back-end .NET. As informações do usuário podem ser usadas para tomar decisões de autorização no back-end. O código a seguir obtém o ID de usuário associado a uma solicitação:

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

O SID é derivado do ID de usuário específico do provedor e é estático para um determinado usuário e provedor de login. O SID é nulo para tokens de autenticação inválidos.

O Serviço de Aplicativo também permite que você solicite declarações específicas do seu provedor de login. Cada provedor de identidade pode fornecer mais informações usando o SDK do provedor de identidade. Por exemplo, você pode usar a API do Facebook Graph para obter informações de amigos. Você pode especificar declarações que são solicitadas na folha do provedor no portal do Azure. Algumas declarações exigem mais configuração com o provedor de identidade.

O código a seguir chama o GetAppServiceIdentityAsync método de extensão para obter as credenciais de login, que incluem o token de acesso necessário para fazer solicitações na API do Facebook Graph:

// 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();
}

Adicione uma instrução using para System.Security.Principal para fornecer o GetAppServiceIdentityAsync método de extensão.

Restringir o acesso a dados para usuários autorizados

Na seção anterior, mostramos como recuperar o ID de usuário de um usuário autenticado. Você pode restringir o acesso a dados e outros recursos com base nesse valor. Por exemplo, adicionar uma coluna userId a tabelas e filtrar os resultados da consulta pelo ID do usuário é uma maneira simples de limitar os dados retornados apenas a usuários autorizados. O código a seguir retorna linhas de dados somente quando o SID corresponde ao valor na coluna UserId na tabela 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);

O método Query() retorna um IQueryable que pode ser manipulado pelo LINQ para manipular a filtragem.

Depurar e solucionar problemas do SDK do .NET Server

O Serviço de Aplicativo do Azure fornece várias técnicas de depuração e solução de problemas para aplicativos ASP.NET:

• Monitorando o Serviço de Aplicativo do Azure
• Habilitar o log de diagnóstico no Serviço de Aplicativo do Azure
• Solucionar problemas de um Serviço de Aplicativo do Azure no Visual Studio

Registo

Você pode gravar nos logs de diagnóstico do Serviço de Aplicativo usando a gravação de rastreamento de ASP.NET padrão. Antes de gravar nos logs, você deve habilitar o diagnóstico em seu back-end de Aplicativos Móveis do Azure.

Para habilitar o diagnóstico e gravar nos logs:

1. Siga as etapas em Habilitar log de aplicativos (Windows).

2. Adicione a seguinte instrução using em seu arquivo de código:

   using System.Web.Http.Tracing;
   

3. Crie um gravador de rastreamento para gravar do back-end .NET para os logs de diagnóstico, da seguinte maneira:

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

4. Republique seu projeto de servidor e acesse o back-end dos Aplicativos Móveis do Azure para executar o caminho de código com o log.

5. Transfira e avalie os registos, conforme descrito em ficheiros de registo do Access.

Depuração local com autenticação

Você pode executar seu aplicativo localmente para testar as alterações antes de publicá-las na nuvem. Para a maioria dos back-ends dos Aplicativos Móveis do Azure, pressione F5 enquanto estiver no Visual Studio. No entanto, há algumas considerações extras ao usar a autenticação.

Você deve ter um aplicativo móvel baseado em nuvem com Autenticação/Autorização do Serviço de Aplicativo configurado, e seu cliente deve ter o ponto de extremidade na nuvem especificado como o host de logon alternativo. Consulte a documentação da plataforma do seu cliente para obter as etapas específicas necessárias.

Verifique se o back-end móvel Microsoft.Azure.Mobile.Server.Authentication instalado. Em seguida, na classe de inicialização OWIN do seu aplicativo, adicione o seguinte, depois que MobileAppConfiguration tiver sido aplicado ao seu HttpConfiguration:

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

No exemplo anterior, você deve configurar o authAudience e authIssuer configurações do aplicativo dentro do arquivo Web.config para que cada um seja a URL da raiz do aplicativo, usando o esquema HTTPS. Da mesma forma, você deve definir authSigningKey como o valor da chave de assinatura do seu aplicativo.

Para obter a chave de assinatura:

1. Navegue até seu aplicativo no portal do Azure
2. Clique em Ferramentas >Kudu>Go.
3. No site Kudu Management, clique em Environment.
4. Encontre o valor para WEBSITE_AUTH_SIGNING_KEY.

Use a chave de assinatura para o parâmetro authSigningKey na configuração do aplicativo local. Seu back-end móvel agora está equipado para validar tokens ao executar localmente, que o cliente obtém o token do ponto de extremidade baseado em nuvem.