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

Artigo
12/19/2022

Nota

Este produto está desativado. Para obter uma substituição para projetos que usam o .NET 8 ou posterior, consulte a biblioteca datasync do Kit de Ferramentas da Comunidade .

Este tópico mostra como usar o SDK do servidor de back-end do .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.

Aviso

Este artigo aborda informações sobre a versão da biblioteca v4.2.0, que é substituída pela biblioteca v5.0.0. Para obter as informações mais atualizadas, consulte o artigo para a versão mais recente do

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 do 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 base para seu aplicativo será instalada.

Baixar e inicializar o SDK

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

Clique com o botão direito do mouse no projeto e selecione Gerenciar Pacotes NuGet....
Na guia Procurar , insira na caixa de pesquisa e pressione Enter.
Selecione o pacote de Microsoft.Azure.Mobile.Server.Quickstart.
Clique em Instalar.
Siga os prompts para concluir a instalação.

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

Nota

Não atualize os pacotes usados como dependências, como Newtonsoft.JSON ou System.IdentityModel.Jwt. As APIs desses pacotes foram, em muitos casos, alteradas e agora são incompatíveis com os Aplicativos Móveis do Azure para ASP.NET Framework.

Inicializar o projeto do servidor

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

Clique com o botão direito do mouse no projeto e selecione Adicionar>Novo Item
Selecione Geral doWeb e, em seguida, selecione o modelo de da classe de inicialização OWIN .
Insira o nome Startup.cs como o nome de inicialização.

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, o namespace e o 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 de using adequadamente.

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 usados 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 desenvolvimento local.

Extensões do SDK

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

Microsoft.Azure.Mobile.Server.Quickstart dá suporte à configuração básica de Aplicativos Móveis. Adicionado à configuração chamando o método de extensão UseDefaultConfiguration durante a inicialização. Essa extensão inclui as seguintes extensões: Notificações, Autenticação, Entidade, Tabelas, domínio cruzado e pacotes Home.
Microsoft.Azure.Mobile.Server.Home Implementa o padrão este aplicativo móvel está em execução de página para a raiz do site. Adicione à configuração chamando o método de extensão AddMobileAppHomeController.
Microsoft.Azure.Mobile.Server.Tables inclui classes para trabalhar com dados e configurar o pipeline de dados. Adicione à configuração chamando o método de extensão AddTables.
Microsoft.Azure.Mobile.Server.Entity permite que o Entity Framework acesse dados no Banco de Dados SQL. Adicione à configuração chamando o método de extensão AddTablesWithEntityFramework.
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.métodos de extensão useAppServiceAuthentication.
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 método de extensão AddPushNotifications.
Microsoft.Azure.Mobile.Server.CrossDomain Cria um controlador que fornece dados para navegadores da Web herdados do seu Aplicativo Móvel. Adicione à configuração chamando o método de extensão MapLegacyCrossDomainController.
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 do .NET no Visual Studio. Há outros métodos pelos quais você pode publicar seu aplicativo. Para obter mais informações, consulte a documentação serviço de aplicativo do Azure.

No Visual Studio, recompile o projeto para restaurar pacotes NuGet.
No Gerenciador de Soluções, clique com o botão direito do mouse no projeto, clique em Publicar.
Se você não tiver publicado este projeto antes, 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 em Concluir.
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 seu banco de dados. Se você não tiver um ou quiser usar outro, clique no + para criar um novo banco de dados e um servidor.
- Insira MS_TableConnectionString como o nome da cadeia de conexão do banco de dados. Preencha o nome de usuário e a senha nas caixas fornecidas.
- Clique em Concluir
Clique em 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:

Crie uma classe DTO (Objeto de Transferência de Dados).
Configure uma referência de tabela na classe DbContext Móvel.
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 no 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()));
    }
}

Por fim, crie um novo controlador:

Clique com o botão direito do mouse na pasta Controllers.
Selecione controlador da API Web>Web API 2 – vazio
Insira um nome para o controlador.

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 vincule 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 lado do servidor "tamanho de consulta permitido" e o tamanho da página do lado do cliente O "tamanho de consulta permitido" do lado do servidor é ajustado usando o atributo EnableQuery:

[EnableQuery(PageSize = 500)]

Verifique se o PageSize é o mesmo ou maior que o tamanho solicitado pelo cliente. Consulte a documentação de HOWTO do cliente específica 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 Aplicativo Móvel expondo um ponto de extremidade. Você pode registrar um controlador de API específico do dispositivo móvel usando o atributo [MobileAppController]. O atributo MobileAppController registra a rota, configura o serializador JSON dos Aplicativos Móveis e ativa a verificação de versão do cliente.

O conteúdo do controlador de API Personalizado é:

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

Depois de configurado com o atributo MobileAppController, você pode definir a API personalizada da mesma forma que qualquer outra API 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 de back-end do .NET:

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

Adicionar autenticação a um projeto de servidor

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

No Visual Studio, instale o pacote Microsoft.Azure.Mobile.Server.Authentication.
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 os tokens emitidos pelo gateway do Serviço de Aplicativo associado.
Adicione o atributo [Authorize] a qualquer controlador ou método que exija autenticação.

Usar a autenticação personalizada para seu aplicativo

Importante

Para habilitar a autenticação personalizada, primeiro você deve habilitar a Autenticação do Serviço de Aplicativo sem selecionar um provedor para o Serviço de Aplicativo no portal do Azure. Isso habilitará a variável de ambiente WEBSITE_AUTH_SIGNING_KEY quando hospedada.

Se você não quiser usar um dos provedores de Autenticação/Autorização do Serviço de Aplicativo, poderá implementar seu próprio sistema de logon. Instale o pacote Microsoft.Azure.Mobile.Server.Login para ajudar na geração de token de autenticação. Forneça seu próprio código para validar as credenciais do usuário. Por exemplo, você pode verificar as senhas saltadas e hash em um banco de dados. No exemplo a seguir, o método isValidAssertion() (definido em outro lugar) é responsável por essas verificações.

A autenticação personalizada é exposta criando um ApiController e expondo ações de register e login. O cliente deve usar uma interface do usuário personalizada para coletar as informações do usuário. Em seguida, as informações são enviadas à API com uma chamada HTTP POST padrão. Depois que o servidor valida a declaraçã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 expondo as propriedades necessárias. O cliente espera que as respostas de logon sejam retornadas como objetos JSON do formulário:

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

O método inclui um de audiência e um parâmetro de do emissor . Ambos os parâmetros são definidos como a URL da raiz do aplicativo, usando o esquema HTTPS. Da mesma forma, você deve definir secretKey como o valor da chave de assinatura do aplicativo. Não distribua a chave de assinatura em um cliente, pois ela pode ser usada para criar chaves e representar usuários. Você pode obter a chave de assinatura enquanto está hospedada 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 Local depuração com autenticação seção para recuperar a chave e armazená-la como uma configuração de aplicativo.

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

Você pode dar suporte ao método de loginAsync() do cliente padrão sobrecarregando a rota de autenticação. Se o cliente chamar client.loginAsync('custom'); fazer logon, 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" });

Ponta

O uso da abordagem loginAsync() garante que o token de autenticação seja anexado a cada chamada subsequente ao serviço.

Recuperar informações do usuário autenticado

Quando um usuário é autenticado pelo Serviço de Aplicativo, você pode acessar a ID de usuário atribuída e outras informações no código de back-end do .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 a ID de usuário associada 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 da ID de usuário específica do provedor e estático para um determinado usuário e provedor de logon. 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 logon. Cada provedor de identidade pode fornecer mais informações usando o SDK do provedor de identidade. Por exemplo, você pode usar a API do Graph do Facebook para obter informações de amigos. Você pode especificar declarações 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 método de extensão GetAppServiceIdentityAsync para obter as credenciais de logon, 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 para fornecer o método de extensão GetAppServiceIdentityAsync.

Restringir o acesso a dados para usuários autorizados

Na seção anterior, mostramos como recuperar a 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 pela ID do usuário é uma maneira simples de limitar os dados retornados apenas aos 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 uma IQueryable que pode ser manipulada pelo LINQ para lidar com 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 do Serviço de Aplicativo do Azure
habilitar o registro em log de diagnóstico no Serviço de Aplicativo do Azure
solucionar problemas de um Serviço de Aplicativo do Azure no Visual Studio

Log

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 no back-end dos Aplicativos Móveis do Azure.

Para habilitar o diagnóstico e gravar nos logs:

Siga as etapas em Habilitar registro em log de aplicativos (Windows).
Adicione a seguinte instrução de uso no arquivo de código:
```
using System.Web.Http.Tracing;
```
Crie um gravador de rastreamento para gravar do back-end do .NET nos logs de diagnóstico, da seguinte maneira:
```
ITraceWriter traceWriter = this.Configuration.Services.GetTraceWriter();
traceWriter.Info("Hello, World");
```
Republice seu projeto de servidor e acesse o back-end dos Aplicativos Móveis do Azure para executar o caminho do código com o log.
Baixe e avalie os logs, conforme descrito nos arquivos de log 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 a Autenticação/Autorização do Serviço de Aplicativo configurada e seu cliente deve ter o ponto de extremidade de nuvem especificado como o host de logon alternativo. Consulte a documentação da plataforma 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 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 definir as configurações do aplicativo authAudience e authIssuer no arquivo Web.config para cada uma ser 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 aplicativo.

Para obter a chave de assinatura:

Navegue até seu aplicativo no portal do do Azure
Clique Ferramentas>Kudu>Go.
No site de Gerenciamento do Kudu, clique em Ambiente.
Localize o valor para WEBSITE_AUTH_SIGNING_KEY.

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

Compartilhar via