Come usare ASP.NET Framework SDK per app per dispositivi mobili di Azure

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. Azure Mobile Apps SDK aiuta a lavorare con i client mobili dall'applicazione ASP.NET.

Creare un back-end di App per dispositivi mobili di Azure ASP.NET Framework

È possibile creare un'app ASP.NET Framework usando Visual Studio 2019.

• Scegliere il modello applicazione Web ASP.NET (.NET Framework). Se si verificano problemi durante l'individuazione di questo modello, selezionare C#, Tutte le piattaforme e Web.
• Dopo aver selezionato un nome e un percorso per l'applicazione, selezionare il modello di progetto API Web. Verrà installata la raccolta corretta di servizi di base per l'applicazione.

scaricare e inizializzare l'SDK

L'SDK è disponibile in NuGet.org e fornisce la funzionalità di base necessaria per iniziare a usare App per dispositivi mobili di Azure. Per installare il pacchetto:

1. Fare clic con il pulsante destro del mouse sul progetto, quindi scegliere Gestisci pacchetti NuGet.
2. Nella scheda Sfoglia immettere Microsoft.Azure.Mobile.Server nella casella di ricerca e quindi premere INVIO.
3. Selezionare il Microsoft.Azure.Mobile.Server.Quickstart pacchetto.
4. Fare clic su Installa.
5. Seguire le istruzioni per completare l'installazione.

Ripetere anche il processo di installazione Microsoft.Owin.Host.SystemWeb .

Inizializzare il progetto server

Un progetto server di App per dispositivi mobili di Azure viene inizializzato in modo simile ad altri progetti di ASP.NET Framework; includendo una classe OWIN Startup. Per aggiungere una classe OWIN Startup:

1. Fare clic con il pulsante destro del mouse sul progetto, quindi scegliere Aggiungi>nuovo elemento

2. Selezionare Web>Generale e quindi selezionare il modello di classe OWIN Startup.

3. Immettere il nome come nome Startup.cs di avvio.

4. Il contenuto del Startup.cs file dovrebbe essere simile al codice seguente:

   using Microsoft.Azure.Mobile.Server.Config;
   using Microsoft.Owin;
   using Owin;
   using System.Web.Http;
   
   [assembly: OwinStartup(typeof(WebApplication1.Startup))]
   namespace WebApplication1
   {
       public class Startup
       {
           public void Configuration(IAppBuilder app)
           {
               HttpConfiguration config = new HttpConfiguration();
               new MobileAppConfiguration()
                   // no added features
                   .ApplyTo(config);
               app.UseWebApi(config);
           }
       }
   }
   

   Il OwinStartupnome , lo spazio dei nomi e la classe saranno diversi, a seconda del progetto. In particolare, è necessario sostituire il contenuto del Configuration() metodo e regolare le using direttive di conseguenza.

Per abilitare le singole funzionalità, è necessario chiamare i metodi di estensione nell'oggetto MobileAppConfiguration prima di chiamare ApplyTo. Ad esempio, il codice seguente aggiunge le route predefinite a tutti i controller API che hanno l'attributo [MobileAppController] durante l'inizializzazione:

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

La configurazione seguente è considerata un utilizzo "normale" che consente ai controller di tabella e API di usare Entity Framework per accedere a un servizio SQL.

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

I metodi di estensione usati sono:

• AddMobileAppHomeController() fornisce la home page di App per dispositivi mobili di Azure predefinita.
• MapApiControllers() fornisce le funzionalità API per i controller WebAPI decorati con l'attributo [MobileAppController].
• AddTables() fornisce una mapping degli endpoint /tables ai controller delle tabelle.
• AddTablesWithEntityFramework() è una sintassi abbreviata per il mapping degli endpoint /tables con i controller basati su Entity Framework.
• MapLegacyCrossDomainController() fornisce intestazioni CORS standard per lo sviluppo locale.

Estensioni SDK

I pacchetti di estensione basati su NuGet seguenti forniscono diverse funzionalità per dispositivi mobili che l'applicazione può usare. È possibile abilitare le estensioni durante l'inizializzazione usando l'oggetto MobileAppConfiguration .

• Microsoft.Azure.Mobile.Server.Quickstart Supporta la configurazione di base di app per dispositivi mobili. Viene aggiunta alla configurazione chiamando il metodo di estensione UseDefaultConfiguration durante l'inizializzazione. Questa estensione include le estensioni seguenti: pacchetti Notifications, Authentication, Entity, Tables, Crossdomain e Home.
• Microsoft.Azure.Mobile.Server.Home Implementa la pagina predefinita this mobile app is up and running per la radice del sito Web. Viene aggiunta alla configurazione chiamando il metodo di estensione AddMobileAppHomeController .
• Microsoft.Azure.Mobile.Server.Tables include le classi per usare i dati e configura la pipeline dei dati. Viene aggiunta alla configurazione chiamando il metodo di estensione AddTables .
• Microsoft.Azure.Mobile.Server.Entity consente a Entity Framework di accedere ai dati nel database SQL. Viene aggiunta alla configurazione chiamando il metodo di estensione AddTablesWithEntityFramework .
• Microsoft.Azure.Mobile.Server.Authentication Consente l'autenticazione e configura il middleware OWIN usato per convalidare i token. Viene aggiunta alla configurazione chiamando i metodi di estensione AddAppServiceAuthentication e IAppBuilder.UseAppServiceAuthentication.
• Microsoft.Azure.Mobile.Server.Notifications Consente le notifiche push e definisce un endpoint di registrazione push. Viene aggiunta alla configurazione chiamando il metodo di estensione AddPushNotifications .
• Microsoft.Azure.Mobile.Server.CrossDomain Crea un controller che fornisce i dati ai Web browser legacy dall'app per dispositivi mobili. Viene aggiunta alla configurazione chiamando il metodo di estensione MapLegacyCrossDomainController .
• Microsoft.Azure.Mobile.Server.Login Fornisce il AppServiceLoginHandler.CreateToken() metodo , che è un metodo statico usato durante scenari di autenticazione personalizzati.

pubblicare il progetto server

Questa sezione illustra come pubblicare il progetto back-end .NET da Visual Studio. Esistono altri metodi con cui è possibile pubblicare l'applicazione. Per altre informazioni, vedere la documentazione del servizio app Azure.

1. In Visual Studio compilare nuovamente il progetto per ripristinare i pacchetti NuGet.
2. In Esplora soluzioni fare clic con il pulsante destro del mouse sul progetto, quindi scegliere Pubblica.
3. Se il progetto non è stato pubblicato in precedenza, si configurerà la pubblicazione.
   • Selezionare Azure per la destinazione.
   • Selezionare app Azure Servizio (Windows) per la destinazione specifica.
   • Selezionare l'istanza del servizio app in cui si vuole eseguire la distribuzione. Se non ne hai uno, usa per + crearne uno.
   • Fare clic su Fine.
4. Se in precedenza non è stato collegato un database SQL, fare clic su Configura accanto al database SQL.
   • Selezionare database SQL di Azure
   • Selezionare il database. Se non si ha uno o si vuole usare un altro, fare clic su + per creare un nuovo database e un nuovo server.
   • Immettere MS_TableConnectionString come nome stringa di connessione database. Immettere il nome utente e la password nelle caselle specificate.
   • Fare clic su Fine
5. Fare clic su Pubblica.

La pubblicazione in Azure richiede tempo. Per altre informazioni, vedere la documentazione di Visual Studio.

definire un controller tabelle

Definire un controller tabelle per esporre una tabella SQL ai client per dispositivi mobili. Per configurare un controller tabelle, sono necessari tre passaggi:

1. Creare una classe di oggetti di trasferimento dei dati.
2. Configurare un riferimento a tabella nella classe DbContext per dispositivi mobili.
3. Creare un controller tabelle.

Un oggetto di trasferimento dei dati è un oggetto C# normale che eredita EntityData. Ad esempio:

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. Per creare la voce del database, aggiungere una DbSet<> proprietà all'oggetto DbContext in uso:

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

Infine, creare un nuovo controller:

1. Fare clic con il pulsante destro del mouse sulla Controllers cartella .

2. Selezionare Web API Web API>2 Controller - Vuoto

3. Immettere un nome per il controller.

4. Sostituire il contenuto del nuovo controller con il codice seguente:

   public class TodoItemController : TableController<TodoItem>
   {
       protected override void Initialize(HttpControllerContext controllerContext)
       {
           base.Initialize(controllerContext);
           ZUMOAPPNAMEContext context = new ZUMOAPPNAMEContext();
           DomainManager = new EntityDomainManager<TodoItem>(context, Request);
       }
   
       // GET tables/TodoItem
       public IQueryable<TodoItem> GetAllTodoItems()
       {
           return Query();
       }
   
       // GET tables/TodoItem/48D68C86-6EA6-4C25-AA33-223FC9A27959
       public SingleResult<TodoItem> GetTodoItem(string id)
       {
           return Lookup(id);
       }
   
       // PATCH tables/TodoItem/48D68C86-6EA6-4C25-AA33-223FC9A27959
       public Task<TodoItem> PatchTodoItem(string id, Delta<TodoItem> patch)
       {
           return UpdateAsync(id, patch);
       }
   
       // POST tables/TodoItem
       public async Task<IHttpActionResult> PostTodoItem(TodoItem item)
       {
           TodoItem current = await InsertAsync(item);
           return CreatedAtRoute("Tables", new { id = current.Id }, current);
       }
   
       // DELETE tables/TodoItem/48D68C86-6EA6-4C25-AA33-223FC9A27959
       public Task DeleteTodoItem(string id)
       {
           return DeleteAsync(id);
       }
   }
   

modificare le dimensioni di paging delle tabelle

Per impostazione predefinita, App mobili di Azure restituisce 50 record per ogni richiesta. 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. 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:

[EnableQuery(PageSize = 500)]

Verificare che il valore di PageSize sia uguale o maggiore delle dimensioni richieste dal client. Fare riferimento alle procedure specifiche del client per informazioni dettagliate su come modificare le dimensioni di pagina del client.

definire un controller API personalizzato

Il controller API personalizzato fornisce le funzionalità di base per il back-end dell'app per dispositivi mobili esponendo un endpoint. È possibile registrare un controller API specifico per dispositivi mobili usando l'attributo [MobileAppController]. L'attributo MobileAppController registra la route, configura il serializzatore JSON di App per dispositivi mobili e attiva il controllo della versione del client.

Il contenuto del controller API personalizzato è:

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

Dopo aver configurato con l'attributo MobileAppController , è possibile definire l'API personalizzata nello stesso modo di qualsiasi altra API Web.

usare l'autenticazione

App per dispositivi mobili di Azure usa l'autenticazione/autorizzazione del servizio app per proteggere il back-end mobile. Questa sezione illustra come eseguire le attività seguenti relative all'autenticazione nel progetto server back-end .NET:

• Aggiungere l'autenticazione a un progetto server
• Usare l'autenticazione personalizzata per l'applicazione
• Recuperare le informazioni utente autenticate
• Limitare l'accesso ai dati per gli utenti autorizzati

aggiungere l'autenticazione a un progetto server

È possibile aggiungere l'autenticazione al progetto server estendendo l'oggetto MobileAppConfiguration e configurando il middleware OWIN.

1. In Visual Studio installare il pacchetto Microsoft.Azure.Mobile.Server.Authentication .

2. Nel file di Startup.cs progetto aggiungere la riga di codice seguente all'inizio del metodo Configuration :

   app.UseAppServiceAuthentication(config);
   

   Questo componente del middleware OWIN convalida i token rilasciati dal gateway del servizio app associato.

3. Aggiungere l'attributo [Authorize] a qualsiasi controller o metodo che richiede l'autenticazione.

usare l'autenticazione personalizzata per la propria applicazione

L'autenticazione personalizzata viene esposta creando un ApiController ed esponendo le azioni register e login. Il client dovrà usare un'interfaccia utente personalizzata per raccogliere le informazioni dall'utente. Le informazioni vengono quindi inviate all'API con una chiamata HTTP POST standard. Dopo la convalida dell'asserzione da parte del server, viene rilasciato un token con il metodo AppServiceLoginHandler.CreateToken() . ApiController non dovrà usare l'attributo [MobileAppController].

Azione login di esempio:

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 LoginResult precedente e LoginResultUser sono oggetti serializzabili che espongono le proprietà obbligatorie. Il client si aspetta che le risposte di accesso vengano restituite come oggetti JSON nel formato:

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

Il metodo AppServiceLoginHandler.CreateToken() include un parametro audience e un parametro issuer. Entrambi i parametri vengono impostati sull'URL della radice dell'applicazione, usando lo schema HTTPS. Allo stesso modo, è consigliabile impostare secretKey come valore della chiave per la firma dell'applicazione. Non distribuire la chiave di firma in un client perché può essere usata per creare chiavi e rappresentare utenti. È possibile ottenere la chiave di firma mentre è ospitata in servizio app facendo riferimento alla WEBSITE_AUTH_SIGNING_KEY variabile di ambiente. 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.

Il token rilasciato può anche includere altre attestazioni e una data di scadenza. Il token rilasciato deve includere almeno un'attestazione soggetto (sub).

È possibile supportare il metodo loginAsync() client standard tramite l'overload della route di autenticazione. Se il client chiama client.loginAsync('custom'); per eseguire l'accesso, la route deve essere /.auth/login/custom. È possibile impostare la route per il controller di autenticazione personalizzata usando MapHttpRoute():

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

recuperare le informazioni sull'utente autenticato

Quando un utente viene autenticato dal servizio app, è possibile accedere all'ID utente assegnato e ad altre informazioni nel codice di back-end .NET. Le informazioni utente possono essere usate per prendere decisioni relative all'autorizzazione nel back-end. Il codice seguente ottiene l'ID utente associato a una richiesta:

// 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. Il SID è null per i token di autenticazione non validi.

Il servizio app consente anche di richiedere le attestazioni specifiche dal provider di accesso. Ogni provider di identità può fornire altre informazioni usando l'SDK del provider di identità. È possibile, ad esempio, usare l'API Graph Facebook per informazioni sugli amici. È possibile specificare le attestazioni richieste nel pannello del provider nel portale di Azure. Alcune attestazioni richiedono più configurazione con il provider di identità.

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:

// 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.

limitare l’accesso ai dati per gli utenti autorizzati

Nella sezione precedente, è stato illustrato come recuperare l'ID utente di un utente autenticato. È possibile limitare l'accesso ai dati e ad altre risorse in base a questo valore. 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. Il codice seguente restituisce righe di dati solo quando il SID corrisponde al valore nella colonna UserId nella tabella TodoItem:

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

// Only return data rows that belong to the current user.
return Query().Where(t => t.UserId == sid);

Il metodo Query() restituisce IQueryable che può essere modificato da LINQ per gestire i filtri.

eseguire il debug e risolvere i problemi di .NET Server SDK

Il servizio app di Azure offre diverse tecniche di debug e risoluzione dei problemi per le applicazioni ASP.NET:

• Monitoraggio del servizio app di Azure
• Abilitare la registrazione diagnostica nel servizio app di Azure
• Risoluzione dei problemi di un Servizio app di Azure in Visual Studio

Registrazione

È possibile scrivere nei log di diagnostica del servizio app usando la scrittura di tracce ASP.NET standard: Prima di poter scrivere nei log, è necessario abilitare la diagnostica nel back-end di App per dispositivi mobili di Azure.

Per abilitare la diagnostica e scrivere nei log:

1. Seguire la procedura descritta in Abilitare la registrazione delle applicazioni (Windows).Follow the steps in Enable application logging (Windows).

2. Aggiungere l'istruzione using seguente al file del codice:

   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:

   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 di Azure per eseguire il percorso del codice con la registrazione.

5. Scaricare e valutare i log, come descritto in Accedere ai file di log.

Debug locale con autenticazione

È possibile eseguire l'applicazione in locale per testare le modifiche prima di pubblicarle nel cloud. Per la maggior parte dei back-end di App per dispositivi mobili di Azure, premere F5 in Visual Studio. Tuttavia, esistono alcune considerazioni aggiuntive quando si usa l'autenticazione.

È 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. Per i passaggi specifici da eseguire, vedere la documentazione della piattaforma client.

Verificare che nel back-end mobile sia installato Microsoft.Azure.Mobile.Server.Authentication . Quindi nella classe di avvio OWIN dell'applicazione aggiungere quanto segue, dopo che MobileAppConfiguration è stato applicato a 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. Allo stesso modo, è consigliabile impostare authSigningKey come valore della chiave per la firma dell'applicazione.

Per ottenere la chiave di firma:

1. Andare all'app nel portale di Azure
2. Fare clic su Strumenti>Kudu>Go.
3. Nel sito di gestione di Kudu fare clic su Environment(Ambiente).
4. Trovare il valore per WEBSITE_AUTH_SIGNING_KEY.

Usare la chiave di firma per il parametro authSigningKey nella configurazione dell'applicazione locale. Il back-end mobile è ora dotato di convalidare i token durante l'esecuzione in locale, che il client ottiene il token dall'endpoint basato sul cloud.