Usare l'SDK del server back-end .NET per App per dispositivi mobili di AzureWork with the .NET backend server SDK for Azure Mobile Apps

Questo argomento mostra come usare l'SDK del server back-end .NET in scenari chiave di App per dispositivi mobili del servizio app di Azure.This topic shows you how to use the .NET backend server SDK in key Azure App Service Mobile Apps scenarios. Azure Mobile Apps SDK aiuta a lavorare con i client mobili dall'applicazione ASP.NET.The Azure Mobile Apps SDK helps you work with mobile clients from your ASP.NET application.

Suggerimento

L'SDK del server .NET per App per dispositivi mobili di Azure è open source su GitHub.The .NET server SDK for Azure Mobile Apps is open source on GitHub. Il repository contiene tutto il codice sorgente, incluso l'intero gruppo di unit test dell'SDK del server, e alcuni progetti di esempio.The repository contains all source code including the entire server SDK unit test suite and some sample projects.

Documentazione di riferimentoReference documentation

La documentazione di riferimento per l'SDK del server è disponibile qui: Riferimento .NET di App per dispositivi mobili di Azure.The reference documentation for the server SDK is located here: Azure Mobile Apps .NET Reference.

Procedura: Creare un back-end dell'app per dispositivi mobili .NETHow to: Create a .NET Mobile App backend

Se si inizia un nuovo progetto, è possibile creare un'applicazione del servizio app usando il portale di Azure 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. È possibile eseguire l'applicazione del servizio app localmente o pubblicare il progetto nell'app per dispositivi mobili del servizio app basata sul cloud.You can run the App Service application locally or publish the project to your cloud-based App Service mobile app.

Se si devono aggiungere funzionalità per dispositivi mobili a un progetto esistente, vedere la sezione Scaricare e inizializzare l'SDK .If you are adding mobile capabilities to an existing project, see the Download and initialize the SDK section.

Creare un back-end .NET usando il portale di AzureCreate a .NET backend using the Azure portal

Per creare un back-end per dispositivi mobili del servizio app, seguire l'esercitazione introduttiva oppure questi passaggi:To create an App Service mobile backend, either follow the Quickstart tutorial or follow these steps:

  1. Accedere al portale di Azure.Log in at the [Azure Portal].
  2. Fare clic su +NUOVO > Web e dispositivi mobili > App per dispositivi mobili e quindi specificare un nome per il back-end dell'app per dispositivi mobili.Click +NEW > Web + Mobile > Mobile App, then provide a name for your Mobile App backend.
  3. In Gruppo di risorseselezionare un gruppo di risorse esistente o crearne uno nuovo usando lo stesso nome dell'app.For the Resource Group, select an existing resource group, or create a new one (using the same name as your app.)

    È possibile selezionare un altro piano del servizio app o crearne uno nuovo.You can either select another App Service plan or create a new one. Per altre informazioni sui piani di Servizi app e su come creare un nuovo piano in un piano tariffario diverso e nella località preferita, vedere Panoramica approfondita dei piani del servizio app di Azure.For more about App Services 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.

  4. Per Piano di Servizio appviene selezionato il piano predefinito nel livello Standard.For the App Service plan, the default plan (in the Standard tier) is selected. È anche possibile selezionare un piano diverso oppure crearne uno nuovo.You can also select a different plan, or create a new one. Le impostazioni del piano di servizio app determinano località, funzionalità, costo e risorse di calcolo associati all'app.The App Service plan's settings determine the location, features, cost and compute resources associated with your app.

    Dopo aver scelto il piano, fare clic su Crea.After you decide on the plan, click Create. Verrà creato il back-end dell'app per dispositivi mobili.This creates the Mobile App backend.

  5. Nel pannello Impostazioni relativo al nuovo back-end dell'app per dispositivi mobili, fare clic su Avvio rapido > piattaforma dell'app client > Connetti al database.In the Settings blade for the new Mobile App backend, click Quick start > your client app platform > Connect a database.

  6. Nel pannello Aggiungi connessione dati fare clic su Database SQL > Crea un nuovo database, immettere il nome del database, scegliere un piano tariffario e quindi fare clic su Server.In the Add data connection blade, click SQL Database > Create a new database, type the database Name, choose a pricing tier, then click Server. È possibile riutilizzare questo nuovo database.You can reuse this new database. Se si ha già un database nella stessa località, è possibile scegliere Usare un database esistente.If you already have a database in the same location, you can instead choose Use an existing database. Non è consigliabile usare un database in una località diversa a causa dei costi di larghezza di banda e della latenza più elevata.The use of a database in a different location isn't recommended due to bandwidth costs and higher latency.

  7. Nel pannello Nuovo server digitare un nome del server univoco nel campo Nome server, specificare un account di accesso e una password, selezionare Consenti ai servizi di Azure di accedere al server e fare clic su OK.In the New server blade, type a unique server name in the Server name field, provide a login and password, check Allow azure services to access server, and click OK. Verrà creato il nuovo database.This creates the new database.
  8. Nel pannello Aggiungi connessione dati fare clic su Stringa di connessione, immettere i valori per l'account di accesso e la password del database e fare clic su OK.Back in the Add data connection blade, click Connection string, type the login and password values for your database, and click OK. Prima di procedere, attendere alcuni minuti che a distribuzione del database venga completata.Wait a few minutes for the database to be deployed successfully before proceeding.

Nel pannello Attività iniziali in Create a table API (Creare un'API di tabella) scegliere C# come Backend language (Linguaggio back-end).Back in the Get started blade, under Create a table API, choose C# as your Backend language. Fare clic su Download, estrarre i file di progetto compressi nel computer locale e aprire la soluzione in Visual Studio.Click Download, extract the compressed project files to your local computer, and open the solution in Visual Studio.

Creare un back-end .NET usando Visual Studio 2013 e Visual Studio 2015Create a .NET backend using Visual Studio 2013 and Visual Studio 2015

Per creare un progetto App per dispositivi mobili di Azure in Visual Studio, installare Azure SDK per .NET (versione 2.9.0 o successiva).Install the Azure SDK for .NET (version 2.9.0 or later) to create an Azure Mobile Apps project in Visual Studio. Dopo avere installato l'SDK, creare un'applicazione ASP.NET seguendo questa procedura:Once you have installed the SDK, create an ASP.NET application using the following steps:

  1. Aprire la finestra di dialogo Nuovo progetto (da File > Nuovo > Progetto...).Open the New Project dialog (from File > New > Project...).
  2. Espandere Modelli > Visual C# e selezionare Web.Expand Templates > Visual C#, and select Web.
  3. Selezionare Applicazione Web ASP.NET.Select ASP.NET Web Application.
  4. Immettere il nome del progetto.Fill in the project name. Fare quindi clic su OK.Then click OK.
  5. In Modelli ASP.NET 4.5.2 selezionare App mobile di Azure.Under ASP.NET 4.5.2 Templates, select Azure Mobile App. Selezionare Host nel cloud per creare un back-end mobile nel cloud in cui è possibile pubblicare questo progetto.Check Host in the cloud to create a mobile backend in the cloud to which you can publish this project.
  6. Fare clic su OK.Click OK.

Procedura: Scaricare e inizializzare l'SDKHow to: Download and initialize the SDK

L'SDK è disponibile in NuGet.org. Il pacchetto include le funzionalità di base necessarie per iniziare a usare l'SDK.The SDK is available on NuGet.org. This package includes the base functionality required to get started using the SDK. Per inizializzare l'SDK, è necessario eseguire alcune operazioni nell'oggetto HttpConfiguration .To initialize the SDK, you need to perform actions on the HttpConfiguration object.

Installare l'SDKInstall the SDK

Per installare l'SDK, fare clic con il pulsante destro del mouse sul progetto server in Visual Studio, scegliere Gestisci pacchetti NuGet, cercare il pacchetto Microsoft.Azure.Mobile.Server e quindi fare clic su Installa.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.

Inizializzare il progetto serverInitialize the server project

Un progetto server back-end .NET viene inizializzato in modo simile ad altri progetti ASP.NET, includendo una classe di avvio OWIN.A .NET backend server project is initialized similar to other ASP.NET projects, by including an OWIN startup class. Assicurarsi che si sia fatto riferimento al pacchetto NuGet Microsoft.Owin.Host.SystemWeb.Ensure that you have referenced the NuGet package Microsoft.Owin.Host.SystemWeb. Per aggiungere questa classe in Visual Studio, fare clic con il pulsante destro del mouse sul progetto server e scegliere Aggiungi > Nuovo elemento, quindi Web > Generale > Classe di avvio di 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. Viene generata una classe con l'attributo seguente:A class is generated with the following attribute:

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

Nel metodo Configuration() della classe di avvio OWIN usare un oggetto HttpConfiguration per configurare l'ambiente di App per dispositivi mobili di Azure.In the Configuration() method of your OWIN startup class, use an HttpConfiguration object to configure the Azure Mobile Apps environment. L'esempio seguente inizializza il progetto server senza funzionalità aggiuntive: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);
}

Per abilitare le singole funzionalità, è necessario chiamare i metodi di estensione nell'oggetto MobileAppConfiguration prima di chiamare ApplyTo.To enable individual features, you must call extension methods on the MobileAppConfiguration object before calling ApplyTo. Ad esempio, il codice seguente aggiunge le route predefinite a tutti i controller API che hanno l'attributo [MobileAppController] durante l'inizializzazione: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);

L'avvio rapido del server nel portale di Azure chiama UseDefaultConfiguration().The server quickstart from the Azure portal calls UseDefaultConfiguration(). Questo equivale alla configurazione seguente: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);

I metodi di estensione usati sono:The extension methods used are:

  • AddMobileAppHomeController() fornisce la home page di App per dispositivi mobili di Azure predefinita.AddMobileAppHomeController() provides the default Azure Mobile Apps home page.
  • MapApiControllers() fornisce le funzionalità API per i controller WebAPI decorati con l'attributo [MobileAppController].MapApiControllers() provides custom API capabilities for WebAPI controllers decorated with the [MobileAppController] attribute.
  • AddTables() fornisce una mapping degli endpoint /tables ai controller delle tabelle.AddTables() provides a mapping of the /tables endpoints to table controllers.
  • AddTablesWithEntityFramework() è una sintassi abbreviata per il mapping degli endpoint /tables con i controller basati su Entity Framework.AddTablesWithEntityFramework() is a short-hand for mapping the /tables endpoints using Entity Framework based controllers.
  • AddPushNotifications() fornisce un semplice metodo di registrazione dei dispositivi per Hub di notifica.AddPushNotifications() provides a simple method of registering devices for Notification Hubs.
  • MapLegacyCrossDomainController() fornisce intestazioni CORS standard per lo sviluppo locale.MapLegacyCrossDomainController() provides standard CORS headers for local development.

Estensioni SDKSDK extensions

I pacchetti di estensione basati su NuGet seguenti forniscono diverse funzionalità per dispositivi mobili che l'applicazione può usare.The following NuGet-based extension packages provide various mobile features that can be used by your application. È possibile abilitare le estensioni durante l'inizializzazione usando l'oggetto MobileAppConfiguration .You enable extensions during initialization by using the MobileAppConfiguration object.

  • Microsoft.Azure.Mobile.Server.Quickstart Supporta la configurazione di base di app per dispositivi mobili.Microsoft.Azure.Mobile.Server.Quickstart Supports the basic Mobile Apps setup. Viene aggiunta alla configurazione chiamando il metodo di estensione UseDefaultConfiguration durante l'inizializzazione.Added to the configuration by calling the UseDefaultConfiguration extension method during initialization. Questa estensione include le estensioni seguenti: pacchetti Notifications, Authentication, Entity, Tables, Crossdomain e Home.This extension includes following extensions: Notifications, Authentication, Entity, Tables, Cross-domain, and Home packages. Questo pacchetto viene usato da Avvio rapido di App per dispositivi mobili disponibile nel portale di Azure.This package is used by the Mobile Apps Quickstart available on the Azure portal.
  • Microsoft.Azure.Mobile.Server.Home Implementa la pagina predefinita this mobile app is up and running per la radice del sito Web.Microsoft.Azure.Mobile.Server.Home Implements the default this mobile app is up and running page for the web site root. Viene aggiunta alla configurazione chiamando il metodo di estensione AddMobileAppHomeController .Add to the configuration by calling the AddMobileAppHomeController extension method.
  • Microsoft.Azure.Mobile.Server.Tables include le classi per usare i dati e configura la pipeline dei dati.Microsoft.Azure.Mobile.Server.Tables includes classes for working with data and sets-up the data pipeline. Viene aggiunta alla configurazione chiamando il metodo di estensione AddTables .Add to the configuration by calling the AddTables extension method.
  • Microsoft.Azure.Mobile.Server.Entity consente a Entity Framework di accedere ai dati nel database SQL.Microsoft.Azure.Mobile.Server.Entity Enables the Entity Framework to access data in the SQL Database. Viene aggiunta alla configurazione chiamando il metodo di estensione AddTablesWithEntityFramework .Add to the configuration by calling the AddTablesWithEntityFramework extension method.
  • Microsoft.Azure.Mobile.Server.Authentication Consente l'autenticazione e configura il middleware OWIN usato per convalidare i token.Microsoft.Azure.Mobile.Server.Authentication Enables authentication and sets-up the OWIN middleware used to validate tokens. Viene aggiunta alla configurazione chiamando i metodi di estensione AddAppServiceAuthentication e IAppBuilder.UseAppServiceAuthentication.Add to the configuration by calling the AddAppServiceAuthentication and IAppBuilder.UseAppServiceAuthentication extension methods.
  • Microsoft.Azure.Mobile.Server.Notifications Consente le notifiche push e definisce un endpoint di registrazione push.Microsoft.Azure.Mobile.Server.Notifications Enables push notifications and defines a push registration endpoint. Viene aggiunta alla configurazione chiamando il metodo di estensione AddPushNotifications .Add to the configuration by calling the AddPushNotifications extension method.
  • Microsoft.Azure.Mobile.Server.CrossDomain Crea un controller che fornisce i dati ai Web browser legacy dall'app per dispositivi mobili.Microsoft.Azure.Mobile.Server.CrossDomain Creates a controller that serves data to legacy web browsers from your Mobile App. Viene aggiunta alla configurazione chiamando il metodo di estensione MapLegacyCrossDomainController .Add to the configuration by calling the MapLegacyCrossDomainController extension method.
  • Microsoft.Azure.Mobile.Server.Login offre il metodo AppServiceLoginHandler.CreateToken(), che è un metodo statico usato negli scenari di autenticazione personalizzati.Microsoft.Azure.Mobile.Server.Login Provides the AppServiceLoginHandler.CreateToken() method, which is a static method used during custom authentication scenarios.

Procedura: Pubblicare il progetto serverHow to: Publish the server project

Questa sezione illustra come pubblicare il progetto back-end .NET da Visual Studio.This section shows you how to publish your .NET backend project from Visual Studio. È inoltre possibile distribuire il progetto back-end usando Git o uno qualsiasi degli altri metodi disponibili.You can also deploy your backend project using Git or any of the other methods available there.

  1. In Visual Studio compilare nuovamente il progetto per ripristinare i pacchetti NuGet.In Visual Studio, rebuild the project to restore NuGet packages.
  2. In Esplora soluzioni fare clic con il pulsante destro del mouse sul progetto, quindi scegliere Pubblica.In Solution Explorer, right-click the project, click Publish. La prima volta che si crea una pubblicazione, è necessario definire un profilo di pubblicazione.The first time you publish, you need to define a publishing profile. Se si ha già un profilo definito, è possibile selezionarlo e fare clic su Pubblica.When you already have a profile defined, you can select it and click Publish.
  3. Se viene richiesto di selezionare una destinazione di pubblicazione, fare clic su Servizio app di Microsoft Azure > Avanti e quindi, se necessario, accedere con le credenziali di 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 scaricherà e memorizzerà le impostazioni di pubblicazione direttamente da Azure.Visual Studio downloads and securely stores your publish settings directly from Azure.

  4. Scegliere la Sottoscrizione, selezionare Tipo di risorsa da Visualizza, espandere App per dispositivi mobili e fare clic sul back-end di App per dispositivi mobili, quindi su OK.Choose your Subscription, select Resource Type from View, expand Mobile App, and click your Mobile App backend, then click OK.

  5. Verificare le informazioni sul profilo di pubblicazione e fare clic su Pubblica.Verify the publish profile information and click Publish.

    Quando il back-end dell'app per dispositivi mobili ha eseguito la pubblicazione, viene visualizzata una pagina di destinazione.When your Mobile App backend has published successfully, you see a landing page indicating success.

Procedura: Definire un controller tabelleHow to: Define a table controller

Definire un controller tabelle per esporre una tabella SQL ai client per dispositivi mobili.Define a Table Controller to expose a SQL table to mobile clients. Per configurare un controller tabelle, sono necessari tre passaggi:Configuring a Table Controller requires three steps:

  1. Creare una classe di oggetti di trasferimento dei dati.Create a Data Transfer Object (DTO) class.
  2. Configurare un riferimento a tabella nella classe DbContext per dispositivi mobili.Configure a table reference in the Mobile DbContext class.
  3. Creare un controller tabelle.Create a table controller.

Un oggetto di trasferimento dei dati è un oggetto C# normale che eredita EntityData.A Data Transfer Object (DTO) is a plain C# object that inherits from EntityData. Ad esempio: For example:

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

L'oggetto di trasferimento dei dati viene usato per definire la tabella nel database SQL.The DTO is used to define the table within the SQL database. Per creare la voce del database, aggiungere una proprietà DbSet<> alla classe DbContext usata.To create the database entry, add a DbSet<> property to the DbContext you are using. Nel modello di progetto predefinito per App per dispositivi mobili di Azure DbContext è chiamata 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()));
    }
}

Se Azure SDK è installato, ora è possibile creare un controller tabelle per il modello, come segue:If you have the Azure SDK installed, you can now create a template table controller as follows:

  1. Fare clic con il pulsante destro del mouse sulla cartella Controller e quindi scegliere Aggiungi > Controller.Right-click on the Controllers folder and select Add > Controller....
  2. Selezionare l'opzione Controller tabelle di App mobili di Azure, quindi fare clic su Aggiungi.Select the Azure Mobile Apps Table Controller option, then click Add.
  3. Nella finestra di dialogo Aggiungi controller :In the Add Controller dialog:
    • Nell'elenco a discesa Classe modello selezionare il nuovo oggetto di trasferimento dei dati.In the Model class dropdown, select your new DTO.
    • Nell'elenco a discesa DbContext selezionare la classe DbContext di Servizi mobili.In the DbContext dropdown, select the Mobile Service DbContext class.
    • Viene automaticamente creato il nome Controller.The Controller name is created for you.
  4. Fare clic su Aggiungi.Click Add.

Il progetto server di Avvio rapido contiene un esempio di TodoItemControllersemplice.The quickstart server project contains an example for a simple TodoItemController.

Procedura: Modificare le dimensioni di paging delle tabelleHow to: Adjust the table paging size

Per impostazione predefinita, App mobili di Azure restituisce 50 record per ogni richiesta.By default, Azure Mobile Apps returns 50 records per request. Il paging garantisce che il client non occupi il thread dell'interfaccia utente o il server troppo a lungo e quindi un'esperienza utente ottimale.Paging ensures that the client does not tie up their UI thread nor the server for too long, ensuring a good user experience. Per modificare le dimensioni di paging delle tabelle, aumentare le "dimensioni della query consentite" lato server e le dimensioni della pagina lato client. Le "dimensioni della query consentite" lato server vengono regolate usando l'attributo 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)]

Verificare che il valore di PageSize sia uguale o maggiore delle dimensioni richieste dal client.Ensure the PageSize is the same or larger than the size requested by the client. Fare riferimento alle procedure specifiche del client per informazioni dettagliate su come modificare le dimensioni di pagina del client.Refer to the specific client HOWTO documentation for details on changing the client page size.

Procedura: Definire un controller API personalizzatoHow to: Define a custom API controller

Il controller API personalizzato fornisce le funzionalità di base per il back-end dell'app per dispositivi mobili esponendo un endpoint.The custom API controller provides the most basic functionality to your Mobile App backend by exposing an endpoint. È possibile registrare un controller API specifico per dispositivi mobili usando l'attributo [MobileAppController].You can register a mobile-specific API controller using the [MobileAppController] attribute. L'attributo MobileAppController registra la route, configura il serializzatore JSON delle app per dispositivi mobili e attiva i controlli di versione client.The MobileAppController attribute registers the route, sets up the Mobile Apps JSON serializer, and turns on client version checking.

  1. In Visual Studio fare clic con il pulsante destro del mouse sulla cartella Controller e quindi scegliere Aggiungi > Controller, selezionare Controller API Web 2—Vuoto e fare clic su Aggiungi.In Visual Studio, right-click the Controllers folder, then click Add > Controller, select Web API 2 Controller—Empty and click Add.
  2. Specificare un nome in Nome controller, ad esempio CustomController, e fare clic su Aggiungi.Supply a Controller name, such as CustomController, and click Add.
  3. Nella nuovo file della classe controller aggiungere l'istruzione using seguente:In the new controller class file, add the following using statement:

     using Microsoft.Azure.Mobile.Server.Config;
    
  4. Applicare l'attributo [MobileAppController] alla definizione di classe controller API, come nell'esempio seguente:Apply the [MobileAppController] attribute to the API controller class definition, as in the following example:

     [MobileAppController]
     public class CustomController : ApiController
     {
           //...
     }
    
  5. Nel file App_Start/Startup.MobileApp.cs aggiungere una chiamata al metodo di estensione MapApiControllers, come nell'esempio seguente: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);
    

È anche possibile usare il metodo di estensione UseDefaultConfiguration() invece di MapApiControllers().You can also use the UseDefaultConfiguration() extension method instead of MapApiControllers(). I controller a cui non è applicato MobileAppControllerAttribute continuano a essere accessibili da parte dei client, ma potrebbero non essere usati correttamente dai client con l'SDK client di App per dispositivi mobili.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.

Procedura: Usare l'autenticazioneHow to: Work with authentication

App per dispositivi mobili di Azure usa l'autenticazione/autorizzazione del servizio app per proteggere il back-end mobile.Azure Mobile Apps uses App Service Authentication / Authorization to secure your mobile backend. Questa sezione illustra come eseguire le attività seguenti relative all'autenticazione nel progetto server back-end .NET:This section shows you how to perform the following authentication-related tasks in your .NET backend server project:

Procedura: Aggiungere l'autenticazione a un progetto serverHow to: Add authentication to a server project

È possibile aggiungere l'autenticazione al progetto server estendendo l'oggetto MobileAppConfiguration e configurando il middleware OWIN.You can add authentication to your server project by extending the MobileAppConfiguration object and configuring OWIN middleware. Quando si installa il pacchetto Microsoft.Azure.Mobile.Server.Quickstart e si chiama il metodo di estensione UseDefaultConfiguration , è possibile andare al passaggio 3.When you install the Microsoft.Azure.Mobile.Server.Quickstart package and call the UseDefaultConfiguration extension method, you can skip to step 3.

  1. In Visual Studio installare il pacchetto Microsoft.Azure.Mobile.Server.Authentication .In Visual Studio, install the Microsoft.Azure.Mobile.Server.Authentication package.
  2. Nel file di progetto Startup.cs aggiungere la riga di codice seguente all'inizio del metodo Configuration :In the Startup.cs project file, add the following line of code at the beginning of the Configuration method:

     app.UseAppServiceAuthentication(config);
    

    Questo componente del middleware OWIN convalida i token rilasciati dal gateway del servizio app associato.This OWIN middleware component validates tokens issued by the associated App Service gateway.

  3. Aggiungere l'attributo [Authorize] a qualsiasi controller o metodo che richiede l'autenticazione.Add the [Authorize] attribute to any controller or method that requires authentication.

Per informazioni su come autenticare i client nel back-end di App per dispositivi mobili, vedere l'articolo Aggiungere l'autenticazione all'app.To learn about how to authenticate clients to your Mobile Apps backend, see Add authentication to your app.

Procedura: Usare l'autenticazione personalizzata per la propria applicazioneHow to: Use custom authentication for your application

Importante

Per abilitare l'autenticazione personalizzata, è prima necessario abilitare l'autenticazione del servizio app senza selezionare un provider per il servizio app nel portale di Azure.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. In tal modo, viene abilitata la variabile di ambiente WEBSITE_AUTH_SIGNING_KEY quando ospitata.This will enable the WEBSITE_AUTH_SIGNING_KEY environment variable when hosted.

Se non si vuole usare uno dei provider di autenticazione/autorizzazione del servizio app, è possibile implementare il proprio sistema di accesso.If you do not wish to use one of the App Service Authentication/Authorization providers, you can implement your own login system. Installare il pacchetto Microsoft.Azure.Mobile.Server.Login per facilitare la generazione dei token di autenticazione.Install the Microsoft.Azure.Mobile.Server.Login package to assist with authentication token generation. Fornire il proprio codice per la convalida delle credenziali utente.Provide your own code for validating user credentials. È possibile, ad esempio, confrontare le password con salting e hashing in un database.For example, you might check against salted and hashed passwords in a database. Nell'esempio seguente il metodo isValidAssertion() (definito altrove) è responsabile di questi controlli.In the example below, the isValidAssertion() method (defined elsewhere) is responsible for these checks.

L'autenticazione personalizzata viene esposta creando un ApiController ed esponendo le azioni register e login.The custom authentication is exposed by creating an ApiController and exposing register and login actions. Il client dovrà usare un'interfaccia utente personalizzata per raccogliere le informazioni dall'utente.The client should use a custom UI to collect the information from the user. Le informazioni vengono quindi inviate all'API con una chiamata HTTP POST standard.The information is then submitted to the API with a standard HTTP POST call. Dopo la convalida dell'asserzione da parte del server, viene rilasciato un token con il metodo AppServiceLoginHandler.CreateToken() .Once the server validates the assertion, a token is issued using the AppServiceLoginHandler.CreateToken() method. ApiController non dovrà usare l'attributo [MobileAppController].The ApiController should not use the [MobileAppController] attribute.

Azione login di esempio: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();
        }
    }

Nell'esempio precedente LoginResult e LoginResultUser sono oggetti serializzabili che espongono le proprietà necessarie.In the preceding example, LoginResult and LoginResultUser are serializable objects exposing required properties. Il client si aspetta che le risposte di accesso vengano restituite come oggetti JSON nel formato:The client expects login responses to be returned as JSON objects of the form:

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

Il metodo AppServiceLoginHandler.CreateToken() include un parametro audience e un parametro issuer.The AppServiceLoginHandler.CreateToken() method includes an audience and an issuer parameter. Entrambi i parametri vengono impostati sull'URL della radice dell'applicazione, usando lo schema HTTPS.Both of these parameters are set to the URL of your application root, using the HTTPS scheme. Allo stesso modo, è consigliabile impostare secretKey come valore della chiave per la firma dell'applicazione.Similarly you should set secretKey to be the value of your application's signing key. Non distribuire la chiave di firma in un client perché può essere usata per creare chiavi e rappresentare utenti.Do not distribute the signing key in a client as it can be used to mint keys and impersonate users. È possibile ottenere la chiave di firma mentre è ospitata nel servizio app facendo riferimento alla variabile di ambiente WEBSITE_AUTH_SIGNING_KEY.You can obtain the signing key while hosted in App Service by referencing the WEBSITE_AUTH_SIGNING_KEY environment variable. Se necessario in un contesto di debug locale, seguire le istruzioni nella sezione Debug locale con autenticazione per recuperare la chiave e archiviarla come impostazione dell'applicazione.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.

Il token rilasciato può anche includere altre attestazioni e una data di scadenza.The issued token may also include other claims and an expiry date. Il token rilasciato deve includere almeno un'attestazione soggetto (sub).Minimally, the issued token must include a subject (sub) claim.

È possibile supportare il metodo loginAsync() client standard tramite l'overload della route di autenticazione.You can support the standard client loginAsync() method by overloading the authentication route. Se il client chiama client.loginAsync('custom'); per eseguire l'accesso, la route deve essere /.auth/login/custom.If the client calls client.loginAsync('custom'); to log in, your route must be /.auth/login/custom. È possibile impostare la route per il controller di autenticazione personalizzata usando MapHttpRoute():You can set the route for the custom authentication controller using MapHttpRoute():

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

Suggerimento

Usare l'approccio loginAsync() assicura che il token di autenticazione sia collegato a ogni chiamata successiva al servizio.Using the loginAsync() approach ensures that the authentication token is attached to every subsequent call to the service.

Procedura: Recuperare le informazioni sull'utente autenticatoHow to: Retrieve authenticated user information

Quando un utente viene autenticato dal servizio app, è possibile accedere all'ID utente assegnato e ad altre informazioni nel codice di 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. Le informazioni utente possono essere usate per prendere decisioni relative all'autorizzazione nel back-end.The user information can be used for making authorization decisions in the backend. Il codice seguente ottiene l'ID utente associato a una richiesta: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;

Il SID è derivato dall'ID utente specifico del provider ed è statico per un determinato utente e provider di accesso.The SID is derived from the provider-specific user ID and is static for a given user and login provider. Il SID è null per i token di autenticazione non validi.The SID is null for invalid authentication tokens.

Il servizio app consente anche di richiedere le attestazioni specifiche dal provider di accesso.App Service also lets you request specific claims from your login provider. Ogni provider di identità può fornire altre informazioni usando l'SDK del provider di identità.Each identity provider can provide more information using the identity provider SDK. È possibile, ad esempio, usare l'API Graph Facebook per informazioni sugli amici.For example, you can use the Facebook Graph API for friends information. È possibile specificare le attestazioni richieste nel pannello del provider nel portale di Azure.You can specify claims that are requested in the provider blade in the Azure portal. Alcune attestazioni richiedono una configurazione aggiuntiva con il provider di identità.Some claims require additional configuration with the identity provider.

Il codice seguente chiama il metodo di estensione GetAppServiceIdentityAsync per ottenere le credenziali di accesso, che includono il token di accesso necessario per effettuare richieste nell'API Graph di 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();
}

Aggiungere un'istruzione using per System.Security.Principal per fornire il metodo di estensione GetAppServiceIdentityAsync.Add a using statement for System.Security.Principal to provide the GetAppServiceIdentityAsync extension method.

Procedura: Limitare l'accesso ai dati per gli utenti autorizzatiHow to: Restrict data access for authorized users

Nella sezione precedente, è stato illustrato come recuperare l'ID utente di un utente autenticato.In the previous section, we showed how to retrieve the user ID of an authenticated user. È possibile limitare l'accesso ai dati e ad altre risorse in base a questo valore.You can restrict access to data and other resources based on this value. Ad esempio, l'aggiunta di una colonna userId alle tabelle e l'applicazione di filtri ai risultati delle query in base all'ID utente sono modi semplici per limitare i dati restituiti solo agli utenti autorizzati.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. Il codice seguente restituisce righe di dati solo quando il SID corrisponde al valore nella colonna UserId nella tabella 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);

Il metodo Query() restituisce IQueryable che può essere modificato da LINQ per gestire i filtri.The Query() method returns an IQueryable that can be manipulated by LINQ to handle filtering.

Procedura: Aggiungere notifiche push a un progetto serverHow to: Add push notifications to a server project

Aggiungere notifiche push al progetto server estendendo l'oggetto MobileAppConfiguration e creando un client di Hub di notifica.Add push notifications to your server project by extending the MobileAppConfiguration object and creating a Notification Hubs client.

  1. In Visual Studio fare clic con il pulsante destro del mouse sul progetto server, quindi scegliere Gestisci pacchetti NuGet, cercare Microsoft.Azure.Mobile.Server.Notifications e infine fare clic su Installa.In Visual Studio, right-click the server project and click Manage NuGet Packages, search for Microsoft.Azure.Mobile.Server.Notifications, then click Install.
  2. Ripetere questo passaggio per installare il pacchetto Microsoft.Azure.NotificationHubs , che include la libreria client di Hub di notifica.Repeat this step to install the Microsoft.Azure.NotificationHubs package, which includes the Notification Hubs client library.
  3. In App_Start/Startup.MobileApp.cs aggiungere una chiamata al metodo di estensione AddPushNotifications() durante l'inizializzazione: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. Aggiungere il codice seguente per creare un client di Hub di notifica: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);
    

Ora è possibile usare il client di Hub di notifica per inviare notifiche push ai dispositivi registrati.You can now use the Notification Hubs client to send push notifications to registered devices. Per altre informazioni, vedere Aggiungere notifiche push all'app.For more information, see Add push notifications to your app. Per altre informazioni su Hub di notifica, vedere Panoramica di Hub di notifica.To learn more about Notification Hubs, see Notification Hubs Overview.

Procedura: Abilitare le notifiche push mirate usando i tagHow to: Enable targeted push using Tags

Hub di notifica consente di inviare notifiche mirate a registrazioni specifiche tramite tag.Notification Hubs lets you send targeted notifications to specific registrations by using tags. Diversi tag vengono creati automaticamente:Several tags are created automatically:

  • L'ID installazione identifica un dispositivo specifico.The Installation ID identifies a specific device.
  • L'ID utente basato sul SID autenticato identifica un utente specifico.The User Id based on the authenticated SID identifies a specific user.

È possibile accedere all'ID di installazione dalla proprietà installationId inMobileServiceClient.The installation ID can be accessed from the installationId property on the MobileServiceClient. L'esempio seguente illustra come usare un ID di installazione per aggiungere un tag a una specifica installazione di Hub di notifica: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}"
    }
});

I tag forniti dal client durante la registrazione per le notifiche push vengono ignorati dal back-end durante la creazione dell'installazione.Any tags supplied by the client during push notification registration are ignored by the backend when creating the installation. Per consentire a un client di aggiungere tag all'installazione, è necessario creare un'API personalizzata che aggiunge tag usando il modello precedente.To enable a client to add tags to the installation, you must create a custom API that adds tags using the preceding pattern.

Per un esempio, vedere Client-added push notification tags (Tag di notifica push aggiunti dal client) nell'esempio di avvio rapido completato di app per dispositivi mobili del servizio app.See Client-added push notification tags in the App Service Mobile Apps completed quickstart sample for an example.

Procedura: Inviare notifiche push agli utenti autenticatiHow to: Send push notifications to an authenticated user

Se un utente autenticato esegue la registrazione per le notifiche push, viene automaticamente aggiunto un tag con l'ID utente.When an authenticated user registers for push notifications, a user ID tag is automatically added to the registration. Usando questo tag, è possibile inviare notifiche push a tutti i dispositivi registrati da tale persona.By using this tag, you can send push notifications to all devices registered by that person. Il codice seguente ottiene il SID dell'utente che esegue la richiesta e invia un modello di notifica push a ogni registrazione del dispositivo per tale 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);

Durante la registrazione per le notifiche push da un client autenticato, assicurarsi che l'autenticazione sia stata completata prima di tentare la registrazione.When registering for push notifications from an authenticated client, make sure that authentication is complete before attempting registration. Per altre informazioni, vedere Push to users (Eseguire il push agli utenti) nell'esempio di avvio rapido completato per le app per dispositivi mobili del servizio app per back-end .NET.For more information, see Push to users in the App Service Mobile Apps completed quickstart sample for .NET backend.

Procedura: Eseguire il debug e risolvere i problemi di .NET Server SDKHow to: Debug and troubleshoot the .NET Server SDK

Il servizio app di Azure offre diverse tecniche di debug e risoluzione dei problemi per le applicazioni ASP.NET:Azure App Service provides several debugging and troubleshooting techniques for ASP.NET applications:

RegistrazioneLogging

È possibile scrivere nei log di diagnostica del servizio app usando la scrittura di tracce ASP.NET standard:You can write to App Service diagnostic logs by using the standard ASP.NET trace writing. Prima di poter scrivere nei log, è necessario abilitare la diagnostica nel back-end di App per dispositivi mobili.Before you can write to the logs, you must enable diagnostics in your Mobile App backend.

Per abilitare la diagnostica e scrivere nei log:To enable diagnostics and write to the logs:

  1. Seguire i passaggi in Come abilitare la diagnostica.Follow the steps in How to enable diagnostics.
  2. Aggiungere l'istruzione using seguente al file del codice:Add the following using statement in your code file:

     using System.Web.Http.Tracing;
    
  3. Creare un writer di traccia per scrivere dal back-end .NET nei log di diagnostica, come indicato di seguito: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. Ripubblicare il progetto server e accedere al back-end di App per dispositivi mobili per eseguire il percorso del codice con la registrazione.Republish your server project, and access the Mobile App backend to execute the code path with the logging.
  5. Scaricare e valutare i log, come descritto in Procedura: Scaricare i log.Download and evaluate the logs, as described in How to: Download logs.

Debug locale con autenticazioneLocal debugging with authentication

È possibile eseguire l'applicazione in locale per testare le modifiche prima di pubblicarle nel cloud.You can run your application locally to test changes before publishing them to the cloud. Per la maggior parte dei back-end di App per dispositivi mobili di Azure, premere F5 in Visual Studio.For most Azure Mobile Apps backends, press F5 while in Visual Studio. Esistono però alcune considerazioni aggiuntive quando si usa l'autenticazione.However, there are some additional considerations when using authentication.

È necessaria un'app per dispositivi mobili basata sul cloud con l'autenticazione/autorizzazione del servizio app configurata e il client deve avere l'endpoint cloud specificato come host di accesso 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. Per i passaggi specifici da eseguire, vedere la documentazione della piattaforma client.See the documentation for your client platform for the specific steps required.

Verificare che nel back-end mobile sia installato Microsoft.Azure.Mobile.Server.Authentication .Ensure that your mobile backend has Microsoft.Azure.Mobile.Server.Authentication installed. Quindi nella classe di avvio OWIN dell'applicazione aggiungere quanto segue, dopo che MobileAppConfiguration è stato applicato 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()
    });

Nell'esempio precedente è consigliabile configurare le impostazioni dell'applicazione authAudience e authIssuer nel file Web.config in modo che ognuna sia l'URL della radice dell'applicazione, usando lo schema 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. Allo stesso modo, è consigliabile impostare authSigningKey come valore della chiave per la firma dell'applicazione.Similarly you should set authSigningKey to be the value of your application's signing key. Per ottenere la chiave di firma:To obtain the signing key:

  1. Andare all'app nel portale di AzureNavigate to your app within the [Azure portal]
  2. Fare clic su Strumenti, Kudu, Vai.Click Tools, Kudu, Go.
  3. Nel sito di gestione di Kudu fare clic su Environment(Ambiente).In the Kudu Management site, click Environment.
  4. Trovare il valore di WEBSITE_AUTH_SIGNING_KEY.Find the value for WEBSITE_AUTH_SIGNING_KEY.

Usare la chiave di firma per il parametro authSigningKey nel file di configurazione dell'applicazione locale. Il back-end mobile, quando è in esecuzione in locale, ora riesce a convalidare i token che il client ottiene dall'endpoint basato sul cloud.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.