Trabajar con el SDK del servidor back-end de .NET para Azure Mobile AppsWork with the .NET backend server SDK for 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.This topic shows you how to use the .NET backend server SDK in key Azure App Service Mobile Apps scenarios. El SDK de Azure Mobile Apps le permite trabajar con clientes móviles de su aplicación ASP.NET.The Azure Mobile Apps SDK helps you work with mobile clients from your ASP.NET application.

Sugerencia

El SDK de servidor de .NET para Azure Mobile Apps es de código abierto en GitHub.The .NET server SDK for Azure Mobile Apps is open source on GitHub. El repositorio contiene todo el código fuente incluido en el conjunto de pruebas de unidad SDK del servidor completo, así como algunos proyectos de ejemplo.The repository contains all source code including the entire server SDK unit test suite and some sample projects.

Documentación de referenciaReference documentation

La documentación de referencia para el SDK de servidor se encuentra aquí: Referencia de .NET para Azure Mobile Apps.The reference documentation for the server SDK is located here: Azure Mobile Apps .NET Reference.

Instrucciones: Creación de un back-end de aplicación móvil .NETHow to: Create a .NET Mobile App backend

Si va a iniciar un nuevo proyecto, puede crear una aplicación de App Service mediante el Azure Portal o Visual Studio.If you are starting a new project, you can create an App Service application using either the Azure portal or Visual Studio. Puede ejecutar la aplicación de App Service localmente o publicarla en la aplicación móvil de App Service basada en la nube.You can run the App Service application locally or publish the project to your cloud-based App Service mobile app.

Si va a agregar funcionalidades móviles a un proyecto existente, consulte la sección Descarga e inicialización del SDK .If you are adding mobile capabilities to an existing project, see the Download and initialize the SDK section.

Creación de un back-end .NET mediante el Portal de AzureCreate a .NET backend using the Azure portal

Para crear una instancia de App Service de back-end móvil, siga el tutorial rápido o estos pasos:To create an App Service mobile backend, either follow the Quickstart tutorial or follow these steps:

  1. Inicie sesión en Azure Portal.Sign in at the Azure portal.

  2. Seleccione +NUEVO > Web y móvil > Aplicación móvil y, después, proporcione un nombre para el back-end de Mobile Apps.Select +NEW > Web + Mobile > Mobile App, and then provide a name for your Mobile Apps back end.

  3. En Grupo de recursos, seleccione un grupo de recursos existente o cree uno nuevo (con el mismo nombre que su aplicación).For Resource Group, select an existing resource group, or create a new one (by using the same name as your app).

  4. Para Plan de App Service, se selecciona el plan predeterminado (en el plan Estándar).For App Service plan, the default plan (in the Standard tier) is selected. También puede seleccionar otro plan o crear uno.You can also select a different plan, or create a new one.

    La configuración del plan de App Service determina la ubicación, las características, el costo y los recursos de proceso asociados con la aplicación.The App Service plan's settings determine the location, features, cost, and compute resources associated with your app. Para más información acerca de los planes de App Service y cómo crear un nuevo plan en un plan de tarifa diferente en la ubicación deseada, consulte Introducción detallada a los planes de Azure App Service.For more about App Service plans and how to create a new plan in a different pricing tier and in your desired location, see Azure App Service plans in-depth overview.

  5. Seleccione Crear.Select Create. Este paso crea el back-end de Mobile Apps.This step creates the Mobile Apps back end.

  6. En el panel Configuración del nuevo back-end de Mobile Apps, seleccione Inicio rápido > la plataforma de aplicaciones cliente > Conectar a una base de datos.In the Settings pane for the new Mobile Apps back end, select Quick start > your client app platform > Connect a database.

    Selecciones para conectarse a una base de datos

  7. En el panel Agregar la conexión de datos, haga clic en SQL Database > Crear una base de datos nueva.In the Add data connection pane, select SQL Database > Create a new database. Escriba el nombre de la base de datos, elija un plan de tarifa y, después, seleccione Servidor.Enter the database name, choose a pricing tier, and then select Server. Puede reutilizar esta nueva base de datos.You can reuse this new database. Si ya tiene una base de datos en la misma ubicación, puede elegir Usar base de datos existente.If you already have a database in the same location, you can instead choose Use an existing database. No se recomienda el uso de una base de datos en una ubicación diferente debido a los costos de ancho de banda y a una mayor latencia.We don't recommend the use of a database in a different location, due to bandwidth costs and higher latency.

    Selección de una base de datos

  8. En el panel Nuevo servidor, escriba un nombre de servidor único en el cuadro Nombre del servidor, proporcione un inicio de sesión y una contraseña, active Permitir que los servicios de Azure accedan al servidor y seleccione Aceptar.In the New server pane, enter a unique server name in the Server name box, provide a login and password, select Allow Azure services to access server, and select OK. Este paso creará la nueva base de datos.This step creates the new database.

  9. De nuevo en el panel Agregar conexión de datos, seleccione Cadena de conexión, escriba los valores de inicio de sesión y contraseña para la base de datos y seleccione Aceptar.Back in the Add data connection pane, select Connection string, enter the login and password values for your database, and select OK.

    Espere unos minutos para que se implemente la base de datos correctamente antes de continuar.Wait a few minutes for the database to be deployed successfully before you proceed.

De nuevo en la hoja Comenzar, en Create a table API (Crear una API de tabla), elija C# como el valor de Backend language (Lenguaje de back-end).Back in the Get started blade, under Create a table API, choose C# as your Backend language. Haga clic en Descargar, extraiga los archivos de proyecto comprimidos en el equipo local y abra la solución en Visual Studio.Click Download, extract the compressed project files to your local computer, and open the solution in Visual Studio.

Creación de un back-end de .NET con Visual Studio 2017Create a .NET backend using Visual Studio 2017

Instale la carga de trabajo de Azure mediante el instalador de Visual Studio para publicar en el proyecto de Azure Mobile Apps desde Visual Studio.Install the Azure workload via the Visual Studio Installer to publish to Azure Mobile Apps project from Visual Studio. Una vez haya instalado el SDK, cree una aplicación de ASP.NET mediante los siguientes pasos:Once you have installed the SDK, create an ASP.NET application using the following steps:

  1. Abra el cuadro de diálogo Nuevo proyecto (desde Archivo > Nuevo > Proyecto... ).Open the New Project dialog (from File > New > Project...).
  2. Expanda Visual C# y seleccione Web.Expand Visual C# and select Web.
  3. Seleccione Aplicación web ASP.NET (.NET Framework) .Select ASP.NET Web Application (.NET Framework).
  4. Rellene el nombre del proyecto.Fill in the project name. A continuación, haga clic en Aceptar.Then click OK.
  5. Seleccione Azure Mobile App en la lista de plantillas.Select Azure Mobile App from the list of templates.
  6. Haga clic en Aceptar para crear la solución.Click OK to create the solution.
  7. Haga clic con el botón derecho en el proyecto en el Explorador de soluciones y elija Publicar... y luego App Service como destino de publicación.Right-click on the project in the Solution Explorer and choose Publish..., then choose App Service as the publishing target.
  8. Siga las indicaciones para autenticar y elija un servicio de aplicaciones de Azure nuevo o existente para publicar.Follow the prompts to authenticate and choose a new or existing Azure App Service to publish.

Creación de un back-end de .NET con Visual Studio 2015Create a .NET backend using Visual Studio 2015

Para crear un proyecto de Azure Mobile Apps en Visual Studio, instale la versión 2.9.0 o posterior de Azure SDK para .NET.Install the Azure SDK for .NET (version 2.9.0 or later) to create an Azure Mobile Apps project in Visual Studio. Una vez haya instalado el SDK, cree una aplicación de ASP.NET mediante los siguientes pasos:Once you have installed the SDK, create an ASP.NET application using the following steps:

  1. Abra el cuadro de diálogo Nuevo proyecto (desde Archivo > Nuevo > Proyecto... ).Open the New Project dialog (from File > New > Project...).
  2. Expanda Plantillas > Visual C# y seleccione Web.Expand Templates > Visual C#, and select Web.
  3. Seleccione Aplicación web ASP.NET.Select ASP.NET Web Application.
  4. Rellene el nombre del proyecto.Fill in the project name. A continuación, haga clic en Aceptar.Then click OK.
  5. En Plantillas de ASP.NET 4.5.2, seleccione Aplicación móvil de Azure.Under ASP.NET 4.5.2 Templates, select Azure Mobile App. Seleccione Host en la nube para crear un back-end móvil en la nube, en el que puede publicar este proyecto.Check Host in the cloud to create a mobile backend in the cloud to which you can publish this project.
  6. Haga clic en OK.Click OK.

Instrucciones: Descarga e inicialización del SDKHow to: Download and initialize the SDK

El SDK está disponible en NuGet.org. Este paquete incluye la funcionalidad básica necesaria para comenzar a usar el SDK.The SDK is available on NuGet.org. This package includes the base functionality required to get started using the SDK. Para inicializar el SDK, tendrá que realizar acciones en el objeto HttpConfiguration .To initialize the SDK, you need to perform actions on the HttpConfiguration object.

Instalación del SDKInstall the SDK

Para instalar el SDK, haga clic con el botón derecho en el proyecto de servidor en Visual Studio, seleccione Administrar paquetes de NuGet, busque el paquete Microsoft.Azure.Mobile.Server y haga clic en Instalar.To install the SDK, right-click on the server project in Visual Studio, select Manage NuGet Packages, search for the Microsoft.Azure.Mobile.Server package, then click Install.

Inicializar el proyecto de servidorInitialize the server project

Un proyecto de servidor backend de .NET se inicializa de manera similar a otros proyectos ASP.NET mediante la inclusión de una clase de inicio OWIN.A .NET backend server project is initialized similar to other ASP.NET projects, by including an OWIN startup class. Asegúrese de que ha hecho referencia al paquete de NuGet Microsoft.Owin.Host.SystemWeb.Ensure that you have referenced the NuGet package Microsoft.Owin.Host.SystemWeb. Para agregar esta clase en Visual Studio, haga clic con el botón derecho en el proyecto de servidor y seleccione Agregar > Nuevo elemento, luego Web > General > Clase de inicio OWIN.To add this class in Visual Studio, right-click on your server project and select Add > New Item, then Web > General > OWIN Startup class. Se genera una clase con el atributo siguiente:A class is generated with the following attribute:

[assembly: OwinStartup(typeof(YourServiceName.YourStartupClassName))]

En el método Configuration() de la clase de inicio OWIN, use un objeto HttpConfiguration para configurar el entorno de Azure Mobile Apps.In the Configuration() method of your OWIN startup class, use an HttpConfiguration object to configure the Azure Mobile Apps environment. En el ejemplo siguiente se inicializa el proyecto de servidor sin características agregadas:The following example initializes the server project with no added features:

// in OWIN startup class
public void Configuration(IAppBuilder app)
{
    HttpConfiguration config = new HttpConfiguration();

    new MobileAppConfiguration()
        // no added features
        .ApplyTo(config);

    app.UseWebApi(config);
}

Para habilitar características individuales, debe llamar a los métodos de extensión del objeto MobileAppConfiguration antes de llamar a ApplyTo.To enable individual features, you must call extension methods on the MobileAppConfiguration object before calling ApplyTo. Por ejemplo, el siguiente código agrega las rutas predeterminadas a todos los controladores de API que tengan el atributo [MobileAppController] durante la inicialización:For example, the following code adds the default routes to all API controllers that have the attribute [MobileAppController] during initialization:

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

El inicio rápido de servidor desde el Portal de Azure llama a UseDefaultConfiguration() .The server quickstart from the Azure portal calls UseDefaultConfiguration(). Es equivalente a la siguiente configuración:This equivalent to the following setup:

    new MobileAppConfiguration()
        .AddMobileAppHomeController()             // from the Home package
        .MapApiControllers()
        .AddTables(                               // from the Tables package
            new MobileAppTableConfiguration()
                .MapTableControllers()
                .AddEntityFramework()             // from the Entity package
            )
        .AddPushNotifications()                   // from the Notifications package
        .MapLegacyCrossDomainController()         // from the CrossDomain package
        .ApplyTo(config);

Los métodos de extensión utilizados son:The extension methods used are:

  • AddMobileAppHomeController() proporciona la página principal predeterminada de Azure Mobile Apps.AddMobileAppHomeController() provides the default Azure Mobile Apps home page.
  • MapApiControllers() proporciona funcionalidades de API personalizadas para controladores de WebAPI que contienen el atributo [MobileAppController].MapApiControllers() provides custom API capabilities for WebAPI controllers decorated with the [MobileAppController] attribute.
  • AddTables() proporciona una asignación de los puntos de conexión /tables a los controladores de la tabla.AddTables() provides a mapping of the /tables endpoints to table controllers.
  • AddTablesWithEntityFramework() es un elemento abreviado para la asignación de los puntos de conexión /tables mediante controladores basados en Entity Framework.AddTablesWithEntityFramework() is a short-hand for mapping the /tables endpoints using Entity Framework based controllers.
  • AddPushNotifications() proporciona un método sencillo de registrar los dispositivos para Notification Hubs.AddPushNotifications() provides a simple method of registering devices for Notification Hubs.
  • MapLegacyCrossDomainController() proporciona los encabezados de CORS estándar para el desarrollo local.MapLegacyCrossDomainController() provides standard CORS headers for local development.

Extensiones de SDKSDK extensions

Los siguientes paquetes de extensión basados en NuGet proporcionan diversas características móviles que puede usar la aplicación.The following NuGet-based extension packages provide various mobile features that can be used by your application. Las extensiones se habilitan durante la inicialización mediante el objeto MobileAppConfiguration .You enable extensions during initialization by using the MobileAppConfiguration object.

  • Microsoft.Azure.Mobile.Server.Quickstart admite la configuración básica de Mobile Apps.Microsoft.Azure.Mobile.Server.Quickstart Supports the basic Mobile Apps setup. Se agrega a la configuración mediante una llamada al método de extensión UseDefaultConfiguration durante la inicialización.Added to the configuration by calling the UseDefaultConfiguration extension method during initialization. Esta extensión incluye las siguientes extensiones: paquetes de notificaciones, autenticación, entidad, tablas, entre dominios y principal.This extension includes following extensions: Notifications, Authentication, Entity, Tables, Cross-domain, and Home packages. Inicio rápido de Mobile Apps, disponible en Azure Portal, usa este paquete.This package is used by the Mobile Apps Quickstart available on the Azure portal.
  • Microsoft.Azure.Mobile.Server.Home Implementa el valor predeterminado de esta página de aplicación móvil está funcionando para la raíz del sitio web.Microsoft.Azure.Mobile.Server.Home Implements the default this mobile app is up and running page for the web site root. Se agrega a la configuración mediante una llamada al método de extensión AddMobileAppHomeController .Add to the configuration by calling the AddMobileAppHomeController extension method.
  • Microsoft.Azure.Mobile.Server.Tables incluye clases para trabajar con datos y configura la canalización de datos.Microsoft.Azure.Mobile.Server.Tables includes classes for working with data and sets-up the data pipeline. Se agrega a la configuración mediante una llamada al método de extensión AddTables .Add to the configuration by calling the AddTables extension method.
  • Microsoft.Azure.Mobile.Server.Entity permite a Entity Framework obtener acceso a los datos de SQL Database.Microsoft.Azure.Mobile.Server.Entity Enables the Entity Framework to access data in the SQL Database. Se agrega a la configuración mediante una llamada al método de extensión AddTablesWithEntityFramework .Add to the configuration by calling the AddTablesWithEntityFramework extension method.
  • Microsoft.Azure.Mobile.Server.Authentication habilita la autenticación y configura el middleware OWIN que se usa para validar los tokens.Microsoft.Azure.Mobile.Server.Authentication Enables authentication and sets-up the OWIN middleware used to validate tokens. Se agrega a la configuración mediante una llamada a los métodos de extensión AddAppServiceAuthentication e IAppBuilder.UseAppServiceAuthentication.Add to the configuration by calling the AddAppServiceAuthentication and IAppBuilder.UseAppServiceAuthentication extension methods.
  • Microsoft.Azure.Mobile.Server.Notifications habilita las notificaciones push y define un punto de conexión de registro de inserción.Microsoft.Azure.Mobile.Server.Notifications Enables push notifications and defines a push registration endpoint. Se agrega a la configuración mediante una llamada al método de extensión AddPushNotifications .Add to the configuration by calling the AddPushNotifications extension method.
  • Microsoft.Azure.Mobile.Server.CrossDomain crea un controlador que sirve datos de la aplicación móvil a los exploradores web heredados.Microsoft.Azure.Mobile.Server.CrossDomain Creates a controller that serves data to legacy web browsers from your Mobile App. Se agrega a la configuración mediante una llamada al método de extensión MapLegacyCrossDomainController .Add to the configuration by calling the MapLegacyCrossDomainController extension method.
  • Microsoft.Azure.Mobile.Server.Login proporciona el método AppServiceLoginHandler.CreateToken(), que es un método estático usado en escenarios de autenticación personalizada.Microsoft.Azure.Mobile.Server.Login Provides the AppServiceLoginHandler.CreateToken() method, which is a static method used during custom authentication scenarios.

Instrucciones: Publicación del proyecto de servidorHow to: Publish the server project

En esta sección se muestra cómo publicar el proyecto de back-end de .NET desde Visual Studio.This section shows you how to publish your .NET backend project from Visual Studio. También puede implementar el proyecto de back-end con Git o con cualquiera de los demás métodos que están disponibles allí.You can also deploy your backend project using Git or any of the other methods available there.

  1. En Visual Studio, vuelva a generar el proyecto para restaurar los paquetes de NuGet.In Visual Studio, rebuild the project to restore NuGet packages.

  2. En el Explorador de soluciones, haga clic con el botón derecho en el proyecto y luego haga clic en Publicar.In Solution Explorer, right-click the project, click Publish. La primera vez que publique, debe definir un perfil de publicación.The first time you publish, you need to define a publishing profile. Si ya tiene un perfil definido, puede seleccionarlo y hacer clic en Publicar.When you already have a profile defined, you can select it and click Publish.

  3. Si se le pide que seleccione un destino de publicación, haga clic en Microsoft Azure App Service > Siguiente y, luego, (si es necesario), inicie sesión con sus credenciales de Azure.If asked to select a publish target, click Microsoft Azure App Service > Next, then (if needed) sign-in with your Azure credentials. Visual Studio descarga y almacena la configuración de publicación directamente desde Azure.Visual Studio downloads and securely stores your publish settings directly from Azure.

  4. Elija su suscripción en Suscripción, seleccione Tipo de recurso en Vista, expanda Aplicación móvil y haga clic en el back-end de aplicación móvil y en Aceptar.Choose your Subscription, select Resource Type from View, expand Mobile App, and click your Mobile App backend, then click OK.

  5. Compruebe la información del perfil de publicación y haga clic en Publicar.Verify the publish profile information and click Publish.

    Cuando el back-end de la aplicación móvil se haya publicado correctamente, verá una página de aterrizaje que indica el éxito.When your Mobile App backend has published successfully, you see a landing page indicating success.

Instrucciones: Definición de un controlador de tablaHow to: Define a table controller

Defina un controlador de tabla para exponer una tabla de SQL para clientes móviles.Define a Table Controller to expose a SQL table to mobile clients. La configuración de un controlador de tabla requiere tres pasos:Configuring a Table Controller requires three steps:

  1. Creación de una clase Data Transfer Object (DTO).Create a Data Transfer Object (DTO) class.
  2. Configuración de una referencia de tabla en la clase Mobile DbContext.Configure a table reference in the Mobile DbContext class.
  3. Creación de un controlador de tabla.Create a table controller.

Un objeto de transferencia de datos (DTO) es un objeto de C# simple heredado de EntityData.A Data Transfer Object (DTO) is a plain C# object that inherits from EntityData. Por ejemplo:For example:

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

El objeto DTO se utiliza para definir la tabla en SQL Database.The DTO is used to define the table within the SQL database. Para crear la entrada de la base de datos, agregue una propiedad DbSet<> a la instancia de DbContext que esté utilizando.To create the database entry, add a DbSet<> property to the DbContext you are using. En la plantilla de proyecto predeterminada para Azure Mobile Apps, la instancia de DbContext se llama Models\MobileServiceContext.cs:In the default project template for Azure Mobile Apps, the DbContext is called Models\MobileServiceContext.cs:

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

Si tiene instalado Azure SDK, ahora puede crear un controlador de tabla de la plantilla como sigue:If you have the Azure SDK installed, you can now create a template table controller as follows:

  1. Haga clic con el botón derecho en la carpeta Controladores y seleccione Agregar > Controlador... .Right-click on the Controllers folder and select Add > Controller....
  2. Seleccione la opción Controlador de tabla de Azure Mobile Apps y haga clic en Agregar.Select the Azure Mobile Apps Table Controller option, then click Add.
  3. En el cuadro de diálogo Agregar controlador :In the Add Controller dialog:
    • En la lista desplegable Clase de modelo , seleccione el nuevo DTO.In the Model class dropdown, select your new DTO.
    • En la lista desplegable DbContext , seleccione la clase Mobile Service DbContext.In the DbContext dropdown, select the Mobile Service DbContext class.
    • Se crea el nombre del controlador.The Controller name is created for you.
  4. Haga clic en Agregar.Click Add.

El proyecto de servidor de inicio rápido contiene un ejemplo de un controlador TodoItemControllersimple.The quickstart server project contains an example for a simple TodoItemController.

Instrucciones: Cómo ajustar el tamaño de paginación de la tablaHow to: Adjust the table paging size

De forma predeterminada, Azure Mobile Apps devuelve 50 registros por solicitud.By default, Azure Mobile Apps returns 50 records per request. La paginación garantiza que el cliente no mantenga ocupado su subproceso de interfaz de usuario ni el servidor durante mucho tiempo, con lo que se asegura una buena experiencia del usuario.Paging ensures that the client does not tie up their UI thread nor the server for too long, ensuring a good user experience. Para cambiar el tamaño de paginación de la tabla, aumente el "tamaño de consulta permitido" del lado del servidor y cambie el tamaño de la página de lado del cliente. El "tamaño de consulta permitido" del lado del servidor se ajusta con el atributo EnableQuery:To change the table paging size, increase the server side "allowed query size" and the client-side page size The server side "allowed query size" is adjusted using the EnableQuery attribute:

[EnableQuery(PageSize = 500)]

Asegúrese de que el valor de PageSize sea igual o mayor que el tamaño solicitado por el cliente.Ensure the PageSize is the same or larger than the size requested by the client. Consulte la documentación de procedimientos para obtener más información sobre cómo cambiar el tamaño de página de cliente.Refer to the specific client HOWTO documentation for details on changing the client page size.

Procedimientos para: Cómo definir un controlador de API personalizadaHow to: Define a custom API controller

El controlador de API personalizada proporciona la funcionalidad más básica al back-end de la aplicación móvil mediante la exposición de un extremo.The custom API controller provides the most basic functionality to your Mobile App backend by exposing an endpoint. Puede registrar un controlador de API específico de dispositivos móviles con el atributo [MobileAppController].You can register a mobile-specific API controller using the [MobileAppController] attribute. El atributo MobileAppController registra la ruta, configura el serializador JSON de Mobile Apps y activa la comprobación de la versión del cliente.The MobileAppController attribute registers the route, sets up the Mobile Apps JSON serializer, and turns on client version checking.

  1. En Visual Studio, haga clic con el botón derecho en la carpeta Controladores y, luego, haga clic en Agregar > Controladores, seleccione Controlador de Web API 2—Vacío y haga clic en Agregar.In Visual Studio, right-click the Controllers folder, then click Add > Controller, select Web API 2 Controller—Empty and click Add.

  2. Proporcione un valor de Nombre de controlador, como CustomController, y haga clic en Agregar.Supply a Controller name, such as CustomController, and click Add.

  3. En el archivo de clase de controlador nuevo, agregue la siguiente instrucción Using:In the new controller class file, add the following using statement:

     using Microsoft.Azure.Mobile.Server.Config;
    
  4. Aplique el atributo [MobileAppController] a la definición de clase del controlador de API, como en el ejemplo siguiente:Apply the [MobileAppController] attribute to the API controller class definition, as in the following example:

     [MobileAppController]
     public class CustomController : ApiController
     {
           //...
     }
    
  5. En el archivo App_Start/Startup.MobileApp.cs, agregue una llamada al método de extensión MapApiControllers, como en el ejemplo siguiente:In App_Start/Startup.MobileApp.cs file, add a call to the MapApiControllers extension method, as in the following example:

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

También puede utilizar el método de extensión UseDefaultConfiguration(), en lugar de MapApiControllers().You can also use the UseDefaultConfiguration() extension method instead of MapApiControllers(). Los clientes pueden tener acceso a un controlador aunque este no tenga un elemento MobileAppControllerAttribute aplicado, pero puede que no lo consuman correctamente si usan un SDK de cliente de aplicación móvil.Any controller that does not have MobileAppControllerAttribute applied can still be accessed by clients, but it may not be correctly consumed by clients using any Mobile App client SDK.

Procedimientos para: Trabajar con la autenticaciónHow to: Work with authentication

Azure Mobile Apps usa la autenticación o autorización de App Service para proteger su back-end móvil.Azure Mobile Apps uses App Service Authentication / Authorization to secure your mobile backend. En esta sección se muestra cómo realizar las siguientes tareas relacionadas con la autenticación en el proyecto de servidor back-end. NET:This section shows you how to perform the following authentication-related tasks in your .NET backend server project:

Instrucciones: Cómo agregar autenticación a un proyecto de servidorHow to: Add authentication to a server project

Para agregar autenticación al proyecto de servidor, extienda el objeto MobileAppConfiguration y configure el middleware OWIN.You can add authentication to your server project by extending the MobileAppConfiguration object and configuring OWIN middleware. Cuando instale el paquete Microsoft.Azure.Mobile.Server.Quickstart y llame al método de extensión UseDefaultConfiguration , puede continuar desde el paso 3.When you install the Microsoft.Azure.Mobile.Server.Quickstart package and call the UseDefaultConfiguration extension method, you can skip to step 3.

  1. En Visual Studio, instale el paquete Microsoft.Azure.Mobile.Server.Authentication .In Visual Studio, install the Microsoft.Azure.Mobile.Server.Authentication package.

  2. En el archivo de proyecto Startup.cs, agregue la siguiente línea de código al principio del método Configuration :In the Startup.cs project file, add the following line of code at the beginning of the Configuration method:

     app.UseAppServiceAuthentication(config);
    

    Este componente del middleware OWIN valida los tokens emitidos por la puerta de enlace de App Service asociada.This OWIN middleware component validates tokens issued by the associated App Service gateway.

  3. Agregue el atributo [Authorize] a cualquier controlador o método que requiera autenticación.Add the [Authorize] attribute to any controller or method that requires authentication.

Para más información sobre cómo autenticar a los clientes en el back-end de Mobile Apps, consulte Incorporación de la autenticación a la aplicación.To learn about how to authenticate clients to your Mobile Apps backend, see Add authentication to your app.

Instrucciones: Uso de la autenticación personalizada en una aplicaciónHow to: Use custom authentication for your application

Importante

Con el fin de habilitar la autenticación personalizada, primero debe habilitar la autenticación de App Service sin seleccionar un proveedor para la instancia en Azure Portal.In order to enable custom authentication, you must first enable App Service Authentication without selecting a provider for your App Service in the Azure portal. Esto habilitará la variable de entorno WEBSITE_AUTH_SIGNING_KEY al hospedarla.This will enable the WEBSITE_AUTH_SIGNING_KEY environment variable when hosted.

Si no desea usar uno de los proveedores de autenticación y autorización de App Service, puede implementar su propio sistema de inicio de sesión.If you do not wish to use one of the App Service Authentication/Authorization providers, you can implement your own login system. Instale el paquete Microsoft.Azure.Mobile.Server.Login para ayudar a la generación de tokens de autenticación.Install the Microsoft.Azure.Mobile.Server.Login package to assist with authentication token generation. Proporcione su propio código para validar las credenciales del usuario.Provide your own code for validating user credentials. Por ejemplo, podría comprobar las contraseñas con sal y hash de una base de datos.For example, you might check against salted and hashed passwords in a database. En el ejemplo siguiente, el método isValidAssertion() (definido en otra parte) es responsable de estas comprobaciones.In the example below, the isValidAssertion() method (defined elsewhere) is responsible for these checks.

La autenticación personalizada se expone mediante la creación de un controlador ApiController y la exposición de las acciones register y login.The custom authentication is exposed by creating an ApiController and exposing register and login actions. El cliente debe utilizar una interfaz de usuario personalizada para recopilar la información del usuario.The client should use a custom UI to collect the information from the user. A continuación, la información se envía a la API con una llamada HTTP POST estándar.The information is then submitted to the API with a standard HTTP POST call. Una vez que el servidor valida la aserción, se emite un token con el método AppServiceLoginHandler.CreateToken() .Once the server validates the assertion, a token is issued using the AppServiceLoginHandler.CreateToken() method. El controlador ApiController no debería utilizar el atributo [MobileAppController].The ApiController should not use the [MobileAppController] attribute.

Ejemplo de la acción login :An example login action:

    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.In the preceding example, LoginResult and LoginResultUser are serializable objects exposing required properties. El cliente espera que las repuestas de inicio de sesión se devuelvan como objetos JSON con este formato:The client expects login responses to be returned as JSON objects of the form:

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

El método AppServiceLoginHandler.CreateToken() incluye un parámetro audience y un parámetro issuer.The AppServiceLoginHandler.CreateToken() method includes an audience and an issuer parameter. Ambos parámetros se establecen en la dirección URL de la raíz de la aplicación, mediante el esquema HTTPS.Both of these parameters are set to the URL of your application root, using the HTTPS scheme. De igual modo, debe establecer secretKey como el valor de la clave de firma de la aplicación.Similarly you should set secretKey to be the value of your application's signing key. No distribuya la clave de firma en un cliente, ya que se puede usar para inventar claves y suplantar a los usuarios.Do not distribute the signing key in a client as it can be used to mint keys and impersonate users. Puede obtener la clave de firma mientras se hospeda en App Service mediante la referencia a la variable de entorno WEBSITE_AUTH_SIGNING_KEY.You can obtain the signing key while hosted in App Service by referencing the WEBSITE_AUTH_SIGNING_KEY environment variable. Si es necesario en un contexto de depuración local, siga las instrucciones de la sección Depuración local con autenticación para recuperar la clave y almacenarla como un valor de configuración de la aplicación.If needed in a local debugging context, follow the instructions in the Local debugging with authentication section to retrieve the key and store it as an application setting.

El token emitido también puede incluir otras notificaciones y una fecha de expiración.The issued token may also include other claims and an expiry date. Como mínimo, el token emitido debe incluir una notificación de asunto (sub).Minimally, the issued token must include a subject (sub) claim.

Puede admitir el método loginAsync() del cliente estándar mediante la sobrecarga de la ruta de autenticación.You can support the standard client loginAsync() method by overloading the authentication route. Si el cliente llama a client.loginAsync('custom'); para iniciar sesión, la ruta debe ser /.auth/login/custom.If the client calls client.loginAsync('custom'); to log in, your route must be /.auth/login/custom. Puede establecer la ruta para el controlador de autenticación personalizada con MapHttpRoute():You can set the route for the custom authentication controller using MapHttpRoute():

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

Sugerencia

Con el enfoque loginAsync() se garantiza que el token de autenticación se asocia a cada llamada posterior al servicio.Using the loginAsync() approach ensures that the authentication token is attached to every subsequent call to the service.

Instrucciones: Recuperación de la información de usuario autenticadoHow to: Retrieve authenticated user information

Cuando un usuario se autentica mediante App Service, se puede tener acceso al id. de usuario asignado y otra información en el código del back-end. NET.When a user is authenticated by App Service, you can access the assigned user ID and other information in your .NET backend code. La información de usuario se puede utilizar para tomar decisiones de autorización en el back-end.The user information can be used for making authorization decisions in the backend. El código siguiente obtiene el identificador de usuario asociado a una solicitud:The following code obtains the user ID associated with a request:

// 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 un proveedor de inicio de sesión dados.The SID is derived from the provider-specific user ID and is static for a given user and login provider. El SID es nulo para los tokens de autenticación no válidos.The SID is null for invalid authentication tokens.

App Service también le permite solicitar notificaciones específicas de su proveedor de inicio de sesión.App Service also lets you request specific claims from your login provider. Cada proveedor de identidades puede proporcionar más información mediante el SDK del proveedor de identidades.Each identity provider can provide more information using the identity provider SDK. Por ejemplo, puede usar Graph API de Facebook para la información de los amigos.For example, you can use the Facebook Graph API for friends information. Puede especificar notificaciones solicitadas en la hoja del proveedor en Azure Portal.You can specify claims that are requested in the provider blade in the Azure portal. Algunas notificaciones requieren configuración adicional con el proveedor de identidades.Some claims require additional configuration with the identity provider.

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 Graph de Facebook:The following code calls the GetAppServiceIdentityAsync extension method to get the login credentials, which include the access token needed to make requests against the Facebook Graph API:

// 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 de uso para que System.Security.Principal proporcione el método de extensión GetAppServiceIdentityAsync .Add a using statement for System.Security.Principal to provide the GetAppServiceIdentityAsync extension method.

Instrucciones: Cómo restringir el acceso a datos para los usuarios autorizadosHow to: Restrict data access for authorized users

En la sección anterior, hemos mostrado cómo recuperar el identificador de usuario de un usuario autenticado.In the previous section, we showed how to retrieve the user ID of an authenticated user. Puede restringir el acceso a datos y otros recursos basándose en este valor.You can restrict access to data and other resources based on this value. Por ejemplo, agregar una columna de identificador de usuario (userId) a las tablas y filtrar los resultados de la consulta por el identificador de usuario es una manera sencilla de limitar los datos devueltos únicamente a los usuarios autorizados.For example, adding a userId column to tables and filtering the query results by the user ID is a simple way to limit returned data only to authorized users. El código siguiente solo devuelve filas de datos cuando el SID coincide con el valor de la columna UserId de la tabla TodoItem:The following code returns data rows only when the SID matches the value in the UserId column on the TodoItem table:

// 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.The Query() method returns an IQueryable that can be manipulated by LINQ to handle filtering.

Procedimientos para: Cómo agregar notificaciones push a un proyecto de servidorHow to: Add push notifications to a server project

Para agregar notificaciones push al proyecto de servidor, extienda el objeto MobileAppConfiguration y cree un cliente de Notification Hubs.Add push notifications to your server project by extending the MobileAppConfiguration object and creating a Notification Hubs client.

  1. En Visual Studio, haga clic con el botón derecho en el proyecto de servidor, haga clic en Administrar paquetes de NuGet, busque Microsoft.Azure.Mobile.Server.Notifications y, por último, haga clic en Instalar.In Visual Studio, right-click the server project and click Manage NuGet Packages, search for Microsoft.Azure.Mobile.Server.Notifications, then click Install.

  2. Repita este paso para instalar el paquete Microsoft.Azure.NotificationHubs , que incluye la biblioteca de cliente de Notification Hubs.Repeat this step to install the Microsoft.Azure.NotificationHubs package, which includes the Notification Hubs client library.

  3. En App_Start/Startup.MobileApp.cs, agregue una llamada al método de extensión AddPushNotifications() durante la inicialización:In App_Start/Startup.MobileApp.cs, and add a call to the AddPushNotifications() extension method during initialization:

     new MobileAppConfiguration()
         // other features...
         .AddPushNotifications()
         .ApplyTo(config);
    
  4. Agregue el siguiente código, que crea un nuevo cliente de Notification Hubs:Add the following code that creates a Notification Hubs client:

     // Get the settings for the server project.
     HttpConfiguration config = this.Configuration;
     MobileAppSettingsDictionary settings =
         config.GetMobileAppSettingsProvider().GetMobileAppSettings();
    
     // Get the Notification Hubs credentials for the Mobile App.
     string notificationHubName = settings.NotificationHubName;
     string notificationHubConnection = settings
         .Connections[MobileAppSettingsKeys.NotificationHubConnectionString].ConnectionString;
    
     // Create a new Notification Hub client.
     NotificationHubClient hub = NotificationHubClient
         .CreateClientFromConnectionString(notificationHubConnection, notificationHubName);
    

Ahora puede usar el cliente de Notification Hubs para enviar notificaciones push a dispositivos registrados.You can now use the Notification Hubs client to send push notifications to registered devices. Para más información, vea Incorporación de notificaciones push a la aplicación.For more information, see Add push notifications to your app. Aprenda más sobre Notification Hubs en la introducción a Notification Hubs.To learn more about Notification Hubs, see Notification Hubs Overview.

Instrucciones: Habilitación de la inserción de destino mediante etiquetasHow to: Enable targeted push using Tags

Notification Hubs permite enviar notificaciones dirigidas a registros específicos mediante el uso de etiquetas.Notification Hubs lets you send targeted notifications to specific registrations by using tags. Se crean varias etiquetas automáticamente:Several tags are created automatically:

  • El identificador de instalación identifica un dispositivo específico.The Installation ID identifies a specific device.
  • El identificador de usuario basado en el SID autenticado identifica un usuario específico.The User Id based on the authenticated SID identifies a specific user.

Se puede acceder al identificador de instalación desde la propiedad installationId en MobileServiceClient.The installation ID can be accessed from the installationId property on the MobileServiceClient. En el ejemplo siguiente se muestra cómo usar un identificador de instalación para agregar una etiqueta a una instalación específica en Notification Hubs:The following example shows how to use an installation ID to add a tag to a specific installation in Notification Hubs:

hub.PatchInstallation("my-installation-id", new[]
{
    new PartialUpdateOperation
    {
        Operation = UpdateOperationType.Add,
        Path = "/tags",
        Value = "{my-tag}"
    }
});

Al crear la instalación, el back-end ignora las etiquetas proporcionadas por el cliente durante el registro de notificaciones push.Any tags supplied by the client during push notification registration are ignored by the backend when creating the installation. Para que un cliente pueda agregar etiquetas a la instalación, debe crear una API personalizada que agregue etiquetas mediante el patrón anterior.To enable a client to add tags to the installation, you must create a custom API that adds tags using the preceding pattern.

Consulte la información sobre las etiquetas de notificaciones push agregadas por el cliente en el ejemplo de inicio rápido completado de App Service Mobile Apps para ver un ejemplo.See Client-added push notification tags in the App Service Mobile Apps completed quickstart sample for an example.

Instrucciones: Envío de notificaciones push a un usuario autenticadoHow to: Send push notifications to an authenticated user

Cuando un usuario autenticado se registra para las notificaciones push, se agrega automáticamente una etiqueta con el identificador de usuario al registro.When an authenticated user registers for push notifications, a user ID tag is automatically added to the registration. Mediante esta etiqueta, puede enviar notificaciones push a todos los dispositivos registrados por ese usuario.By using this tag, you can send push notifications to all devices registered by that person. El código siguiente obtiene el SID del usuario que realiza la solicitud y envía una notificación push de plantilla a cada registro de dispositivo para esa persona:The following code gets the SID of user making the request and sends a template push notification to every device registration for that person:

// Get the current user SID and create a tag for the current user.
var claimsPrincipal = this.User as ClaimsPrincipal;
string sid = claimsPrincipal.FindFirst(ClaimTypes.NameIdentifier).Value;
string userTag = "_UserId:" + sid;

// Build a dictionary for the template with the item message text.
var notification = new Dictionary<string, string> { { "message", item.Text } };

// Send a template notification to the user ID.
await hub.SendTemplateNotificationAsync(notification, userTag);

Cuando se registre para notificaciones push desde un cliente autenticado, asegúrese de que la autenticación se ha completado antes de intentar el registro.When registering for push notifications from an authenticated client, make sure that authentication is complete before attempting registration. Para más información, consulte Push to users (Notificación push a usuarios) en el ejemplo de inicio rápido de App Service Mobile Apps completado para el back-end de .NET.For more information, see Push to users in the App Service Mobile Apps completed quickstart sample for .NET backend.

Procedimientos para: Depuración y solución de problemas del SDK de .NET ServerHow to: Debug and troubleshoot the .NET Server SDK

Azure App Service proporciona varias técnicas de depuración y solución de problemas para las aplicaciones ASP.NET.Azure App Service provides several debugging and troubleshooting techniques for ASP.NET applications:

RegistroLogging

Puede escribir en registros de diagnóstico de App Service mediante la escritura de seguimiento estándar de ASP.NET.You can write to App Service diagnostic logs by using the standard ASP.NET trace writing. Antes de poder escribir en los registros, debe habilitar los diagnósticos en su back-end de aplicación móvil.Before you can write to the logs, you must enable diagnostics in your Mobile App backend.

Para habilitar los diagnósticos y escribir en los registros:To enable diagnostics and write to the logs:

  1. Siga los pasos que se indican en Habilitación de diagnósticos.Follow the steps in How to enable diagnostics.

  2. Agregue la siguiente instrucción using en el archivo de código:Add the following using statement in your code file:

     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, de la manera siguiente:Create a trace writer to write from the .NET backend to the diagnostic logs, as follows:

     ITraceWriter traceWriter = this.Configuration.Services.GetTraceWriter();
     traceWriter.Info("Hello, World");
    
  4. Vuelva a publicar el proyecto de servidor y acceda al back-end de aplicación móvil para ejecutar la ruta de acceso del código con el registro.Republish your server project, and access the Mobile App backend to execute the code path with the logging.

  5. Descargue y evalúe los registros, como se describe en Instrucciones: Descarga de registros.Download and evaluate the logs, as described in How to: Download logs.

Depuración local con autenticaciónLocal debugging with authentication

Puede ejecutar la aplicación localmente para probar los cambios antes de publicarlos en la nube.You can run your application locally to test changes before publishing them to the cloud. Para la mayoría de los servidores back-end de Azure Mobile Apps, presione F5 mientras está en Visual Studio.For most Azure Mobile Apps backends, press F5 while in Visual Studio. Sin embargo, hay algunas consideraciones adicionales cuando se usa la autenticación.However, there are some additional considerations when using authentication.

Debe tener una aplicación móvil basada en la nube que tenga configurada la característica Autenticación/autorización de App Service, y su cliente debe haber especificado el punto de conexión de nube como host de inicio de sesión alternativo.You must have a cloud-based mobile app with App Service Authentication/Authorization configured, and your client must have the cloud endpoint specified as the alternate login host. Consulte la documentación de la plataforma cliente para los pasos específicos requeridos.See the documentation for your client platform for the specific steps required.

Asegúrese de que el back-end tenga instalado Microsoft.Azure.Mobile.Server.Authentication .Ensure that your mobile backend has Microsoft.Azure.Mobile.Server.Authentication installed. Después, en la clase de inicio OWIN de la aplicación, agregue lo siguiente, después de aplicar MobileAppConfiguration a HttpConfiguration:Then, in your application's OWIN startup class, add the following, after MobileAppConfiguration has been applied to your 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 los parámetros de la aplicación authAudience y authIssuer en el archivo Web.config para que cada uno sea la dirección URL de la raíz de la aplicación; para ello, usará el esquema HTTPS.In the preceding example, you should configure the authAudience and authIssuer application settings within your Web.config file to each be the URL of your application root, using the HTTPS scheme. De igual modo, debe establecer authSigningKey como el valor de la clave de firma de la aplicación.Similarly you should set authSigningKey to be the value of your application's signing key. Para obtener la clave de firma:To obtain the signing key:

  1. Vaya a la aplicación en Azure PortalNavigate to your app within the Azure portal
  2. Haga clic en Herramientas, Kudu, Ir.Click Tools, Kudu, Go.
  3. En el sitio de administración de Kudu, haga clic en Entorno.In the Kudu Management site, click Environment.
  4. Busque el valor de WEBSITE_AUTH_SIGNING_KEY.Find the value for WEBSITE_AUTH_SIGNING_KEY.

Use la clave de firma para el parámetro authSigningKey en la configuración de la aplicación local. Ahora, el back-end móvil está equipado para validar los tokens cuando se ejecuta localmente; el cliente obtiene el token del punto de conexión basado en la nube.Use the signing key for the authSigningKey parameter in your local application config. Your mobile backend is now equipped to validate tokens when running locally, which the client obtains the token from the cloud-based endpoint.