Uso del SDK de ASP.NET Framework para Azure Mobile Apps

En este tema se muestra cómo usar el SDK del servidor back-end de .NET en escenarios clave de Azure App Service Mobile Apps. El SDK de Azure Mobile Apps le ayuda a trabajar con clientes móviles desde la aplicación ASP.NET.

Creación de un back-end de Azure Mobile Apps ASP.NET Framework

Puede crear una aplicación de ASP.NET Framework mediante Visual Studio 2019.

• Elija la plantilla aplicación web de ASP.NET (.NET Framework). Si tiene problemas para localizar esta plantilla, seleccione de C#, Todas las plataformasy Web.
• Después de seleccionar un nombre y una ubicación para la aplicación, seleccione la plantilla de proyecto WEB API. Se instalará la colección correcta de servicios base para la aplicación.

Descarga e inicialización del SDK

El SDK está disponible en NuGet.orgy proporciona la funcionalidad base necesaria para empezar a usar Azure Mobile Apps. Para instalar el paquete:

1. Haga clic con el botón derecho en el proyecto y seleccione Administrar paquetes NuGet....
2. En la pestaña Examinar , escriba Microsoft.Azure.Mobile.Server en el cuadro de búsqueda y presione Entrar.
3. Seleccione el paquete Microsoft.Azure.Mobile.Server.Quickstart.
4. Haga clic en Instalar.
5. Siga las indicaciones para completar la instalación.

Repita el proceso para instalar también Microsoft.Owin.Host.SystemWeb.

Inicialización del proyecto de servidor

Un proyecto de servidor de Azure Mobile Apps se inicializa de forma similar a otros proyectos de ASP.NET Framework; mediante la inclusión de una clase de inicio de OWIN. Para agregar una clase de inicio de OWIN:

1. Haga clic con el botón derecho en el proyecto y seleccione Agregar>nuevo elemento

2. Seleccione Web>Generaly, a continuación, seleccione la plantilla clase de inicio de OWIN.

3. Escriba el nombre Startup.cs como nombre de inicio.

4. El contenido del archivo Startup.cs debe ser similar al código siguiente:

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

   El OwinStartup, el espacio de nombres y el nombre de clase serán diferentes, en función del proyecto. En concreto, debe reemplazar el contenido del método Configuration() y ajustar las directivas using en consecuencia.

Para habilitar características individuales, debe llamar a métodos de extensión en el objeto mobileAppConfiguration de antes de llamar a ApplyTo. Por ejemplo, el código siguiente agrega las rutas predeterminadas a todos los controladores de API que tienen el atributo [MobileAppController] durante la inicialización:

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

La siguiente configuración se considera un uso "normal" que permite que los controladores de tabla y API que usan Entity Framework accedan a un servicio SQL.

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

Los métodos de extensión usados son:

• AddMobileAppHomeController() proporciona la página principal predeterminada de Azure Mobile Apps.
• MapApiControllers() proporciona funcionalidades de API personalizadas para controladores webAPI decorados con el atributo [MobileAppController].
• AddTables() proporciona una asignación de los puntos de conexión de /tables a los controladores de tabla.
• AddTablesWithEntityFramework() es una mano corta para asignar los puntos de conexión de /tables mediante controladores basados en Entity Framework.
• MapLegacyCrossDomainController() proporciona encabezados CORS estándar para el desarrollo local.

Extensiones del SDK

Los siguientes paquetes de extensión basados en NuGet proporcionan varias características móviles que la aplicación puede usar. Las extensiones se habilitan durante la inicialización mediante el objeto MobileAppConfiguration.

• Microsoft.Azure.Mobile.Server.Quickstart Admite la configuración básica de Mobile Apps. Se agregó a la configuración llamando al método de extensión UseDefaultConfiguration durante la inicialización. Esta extensión incluye las siguientes extensiones: notificaciones, autenticación, entidad, tablas, dominios cruzados y paquetes home.
• Microsoft.Azure.Mobile.Server.Home Implementa el valor predeterminado esta aplicación móvil está en funcionamiento para la raíz del sitio web. Agregue a la configuración llamando al método de extensión AddMobileAppHomeController.
• Microsoft.Azure.Mobile.Server.Tables incluye clases para trabajar con datos y configurar la canalización de datos. Agregue a la configuración llamando al método de extensión addTables .
• Microsoft.Azure.Mobile.Server.Entity Permite que Entity Framework acceda a los datos de SQL Database. Agregue a la configuración llamando al método de extensión AddTablesWithEntityFramework.
• Microsoft.Azure.Mobile.Server.Authentication Habilita la autenticación y configura el middleware de OWIN usado para validar tokens. Agregue a la configuración llamando al addAppServiceAuthentication y IAppBuilder.métodos de extensión UseAppServiceAuthentication.
• Microsoft.Azure.Mobile.Server.Notifications Habilita las notificaciones push y define un punto de conexión de registro de inserción. Agregue a la configuración llamando al método de extensión addPushNotifications .
• Microsoft.Azure.Mobile.Server.CrossDomain Crea un controlador que sirve datos a exploradores web heredados de la aplicación móvil. Agregue a la configuración llamando al método de extensión MapLegacyCrossDomainController .
• Microsoft.Azure.Mobile.Server.Login Proporciona el método AppServiceLoginHandler.CreateToken(), que es un método estático que se usa durante escenarios de autenticación personalizados.

Publicación del proyecto de servidor

En esta sección se muestra cómo publicar el proyecto de back-end de .NET desde Visual Studio. Hay otros métodos por los que puede publicar la aplicación. Para más información, consulte la documentación de Azure App Service.

1. En Visual Studio, recompile el proyecto para restaurar paquetes NuGet.
2. En el Explorador de soluciones, haga clic con el botón derecho en el proyecto, haga clic en Publicar.
3. Si no ha publicado este proyecto antes, configurará la publicación.
   • Seleccione Azure para el destino.
   • Seleccione Azure App Service (Windows) para el destino específico.
   • Seleccione la instancia de App Service en la que desea realizar la implementación. Si no tiene una, use el + para crear una.
   • Haga clic en Finalizar
4. Si no ha vinculado una base de datos SQL antes, haga clic en Configurar junto a SQL Database.
   • Seleccione de Azure SQL Database.
   • Seleccione la base de datos. Si no tiene uno o desea usar uno diferente, haga clic en el + para crear una nueva base de datos y un servidor.
   • Escriba MS_TableConnectionString como nombre de la cadena de conexión de base de datos. Rellene el nombre de usuario y la contraseña en los cuadros proporcionados.
   • Haga clic en Finish (Finalizar).
5. Haga clic en Publicar

Se tarda algún tiempo en publicarse en Azure. Para obtener más información, consulte la documentación de Visual Studio.

Definición de un controlador de tabla

Defina un controlador de tabla para exponer una tabla SQL a los clientes móviles. La configuración de un controlador de tabla requiere tres pasos:

1. Cree una clase de objeto de transferencia de datos (DTO).
2. Configure una referencia de tabla en la clase Mobile DbContext.
3. Cree un controlador de tabla.

Un objeto de transferencia de datos (DTO) es un objeto de C# sin formato que hereda de EntityData. Por ejemplo:

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

El DTO se usa para definir la tabla dentro de la base de datos SQL. Para crear la entrada de base de datos, agregue una propiedad DbSet<> al DbContext que use:

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 último, cree un nuevo controlador:

1. Haga clic con el botón derecho en la carpeta Controllers.

2. Seleccione Web API>Controlador de WEB API 2: vacío

3. Escriba un nombre para el controlador.

4. Reemplace el contenido del nuevo controlador por el código siguiente:

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

Ajuste del tamaño de paginación de la tabla

De forma predeterminada, Azure Mobile Apps devuelve 50 registros por solicitud. La paginación garantiza que el cliente no ata su subproceso de interfaz de usuario ni el servidor durante demasiado tiempo, lo que garantiza una buena experiencia de usuario. Para cambiar el tamaño de paginación de la tabla, aumente el "tamaño de consulta permitido" del lado servidor y el tamaño de página del lado cliente El "tamaño de consulta permitido" del lado servidor se ajusta mediante el atributo EnableQuery:

[EnableQuery(PageSize = 500)]

Asegúrese de que PageSize es el mismo o mayor que el tamaño solicitado por el cliente. Consulte la documentación de HOWTO de cliente específica para obtener más información sobre cómo cambiar el tamaño de página del cliente.

Definición de un controlador de API personalizado

El controlador de API personalizado proporciona la funcionalidad más básica al back-end de la aplicación móvil exponiendo un punto de conexión. Puede registrar un controlador de API específico para dispositivos móviles mediante el atributo [MobileAppController]. El atributo MobileAppController registra la ruta, configura el serializador JSON de Mobile Apps y activa la comprobación de versiones del cliente.

El contenido del controlador de API personalizada es:

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

Una vez configurado con el atributo MobileAppController, puede definir la API personalizada de la misma manera que cualquier otra API web.

Trabajar con autenticación

Azure Mobile Apps usa la autenticación o autorización de App Service para proteger el back-end móvil. En esta sección se muestra cómo realizar las siguientes tareas relacionadas con la autenticación en el proyecto de servidor back-end de .NET:

• Agregar autenticación a un proyecto de servidor
• Uso de la autenticación personalizada para la aplicación
• Recuperar información de usuario autenticada
• Restringir el acceso a datos para usuarios autorizados

Agregar autenticación a un proyecto de servidor

Puede agregar autenticación al proyecto de servidor mediante la extensión del objeto MobileAppConfiguration y la configuración del middleware de OWIN.

1. En Visual Studio, instale el paquete de Microsoft.Azure.Mobile.Server.Authentication.

2. En el archivo de proyecto Startup.cs, agregue la siguiente línea de código al principio del método Configuration de:

   app.UseAppServiceAuthentication(config);
   

   Este componente de middleware de OWIN valida los tokens emitidos por la puerta de enlace de App Service asociada.

3. Agregue el atributo [Authorize] a cualquier controlador o método que requiera autenticación.

Uso de la autenticación personalizada para la aplicación

La autenticación personalizada se expone mediante la creación de un ApiController y la exposición de register y acciones de login. El cliente debe usar una interfaz de usuario personalizada para recopilar la información del usuario. A continuación, la información se envía a la API con una llamada HTTP POST estándar. Una vez que el servidor valida la aserción, se emite un token mediante el método AppServiceLoginHandler.CreateToken(). El ApiController no debe usar el atributo [MobileAppController].

Ejemplo login acción:

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

En el ejemplo anterior, LoginResult y LoginResultUser son objetos serializables que exponen las propiedades necesarias. El cliente espera que las respuestas de inicio de sesión se devuelvan como objetos JSON del formulario:

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

El método AppServiceLoginHandler.CreateToken() incluye un de audiencia y un parámetro emisor de. Ambos parámetros se establecen en la dirección URL de la raíz de la aplicación mediante el esquema HTTPS. Del mismo modo, debe establecer secretKey para que sea el valor de la clave de firma de la aplicación. No distribuya la clave de firma en un cliente, ya que se puede usar para usar claves de mint y suplantar a los usuarios. Puede obtener la clave de firma mientras se hospeda en App Service haciendo referencia a la variable de entorno WEBSITE_AUTH_SIGNING_KEY. Si es necesario en un contexto de depuración local, siga las instrucciones de la depuración local con autenticación sección para recuperar la clave y almacenarla como una configuración de aplicación.

El token emitido también puede incluir otras notificaciones y una fecha de expiración. Como mínimo, el token emitido debe incluir una notificación subject (sub).

Puede admitir el método loginAsync() de cliente estándar sobrecargando la ruta de autenticación. Si el cliente llama a client.loginAsync('custom'); para iniciar sesión, la ruta debe ser /.auth/login/custom. Puede establecer la ruta del controlador de autenticación personalizado mediante MapHttpRoute():

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

Recuperación de información de usuario autenticada

Cuando app Service autentica a un usuario, puede acceder al identificador de usuario asignado y a otra información en el código back-end de .NET. La información del usuario se puede usar para tomar decisiones de autorización en el back-end. El código siguiente obtiene el identificador de usuario asociado a una solicitud:

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

El SID se deriva del identificador de usuario específico del proveedor y es estático para un usuario y proveedor de inicio de sesión determinado. El SID es null para los tokens de autenticación no válidos.

App Service también le permite solicitar notificaciones específicas del proveedor de inicio de sesión. Cada proveedor de identidades puede proporcionar más información mediante el SDK del proveedor de identidades. Por ejemplo, puede usar Graph API de Facebook para obtener información de amigos. Puede especificar notificaciones que se solicitan en la hoja del proveedor en Azure Portal. Algunas notificaciones requieren más configuración con el proveedor de identidades.

El código siguiente llama al método de extensión GetAppServiceIdentityAsync para obtener las credenciales de inicio de sesión, que incluyen el token de acceso necesario para realizar solicitudes en La API de 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();
}

Agregue una instrucción using para System.Security.Principal para proporcionar el método de extensión GetAppServiceIdentityAsync.

Restricción del acceso a datos para usuarios autorizados

En la sección anterior, se mostró cómo recuperar el identificador de usuario de un usuario autenticado. Puede restringir el acceso a los datos y a otros recursos en función de este valor. Por ejemplo, agregar una columna userId a tablas y filtrar los resultados de la consulta por el identificador de usuario es una manera sencilla de limitar los datos devueltos solo a los usuarios autorizados. El código siguiente devuelve filas de datos solo cuando el SID coincide con el valor de la columna UserId de la tabla 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);

El método Query() devuelve un IQueryable que LINQ puede manipular para controlar el filtrado.

Depuración y solución de problemas del SDK de .NET Server

Azure App Service proporciona varias técnicas de depuración y solución de problemas para ASP.NET aplicaciones:

• Supervisión de Azure App Service
• Habilitación del registro de diagnóstico en Azure App Service
• Solución de problemas de Azure App Service en Visual Studio

Registro

Puede escribir en los registros de diagnóstico de App Service mediante el ASP.NET escritura de seguimiento estándar. Para poder escribir en los registros, debe habilitar los diagnósticos en el back-end de Azure Mobile Apps.

Para habilitar los diagnósticos y escribir en los registros:

1. Siga los pasos descritos en Habilitar el registro de aplicaciones (Windows).

2. Agregue la siguiente instrucción using en el archivo de código:

   using System.Web.Http.Tracing;
   

3. Cree un escritor de seguimiento para escribir desde el back-end de .NET en los registros de diagnóstico, como se indica a continuación:

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

4. Vuelva a publicar el proyecto de servidor y acceda al back-end de Azure Mobile Apps para ejecutar la ruta de acceso del código con el registro.

5. Descargue y evalúe los registros, como se describe en Archivos de registro de Access.

Depuración local con autenticación

Puede ejecutar la aplicación localmente para probar los cambios antes de publicarlos en la nube. Para la mayoría de los back-end de Azure Mobile Apps, presione F5 mientras está en Visual Studio. Sin embargo, hay algunas consideraciones adicionales al usar la autenticación.

Debe tener una aplicación móvil basada en la nube con la autenticación o autorización de App Service configurada y el cliente debe tener el punto de conexión en la nube especificado como host de inicio de sesión alternativo. Consulte la documentación de la plataforma cliente para conocer los pasos específicos necesarios.

Asegúrese de que el back-end móvil tenga instalado Microsoft.Azure.Mobile.Server. Authentication. A continuación, en la clase de inicio OWIN de la aplicación, agregue lo siguiente después de aplicar MobileAppConfiguration a la HttpConfiguration:

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

En el ejemplo anterior, debe configurar la authAudience y authIssuer configuración de la aplicación dentro del archivo de Web.config para cada una de las direcciones URL de la raíz de la aplicación, mediante el esquema HTTPS. Del mismo modo, debe establecer authSigningKey para que sea el valor de la clave de firma de la aplicación.

Para obtener la clave de firma:

1. Vaya a la aplicación en el de Azure Portal
2. Haga clic en Tools>Kudu>Go.
3. En el sitio de administración de Kudu, haga clic en Entorno.
4. Busque el valor de WEBSITE_AUTH_SIGNING_KEY.

Use la clave de firma del parámetro authSigningKey en la configuración de la aplicación local. El back-end móvil ahora está equipado para validar tokens cuando se ejecuta localmente, que el cliente obtiene el token del punto de conexión basado en la nube.