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

Articolo
12/19/2022

Nota

Questo prodotto viene ritirato. Per una sostituzione dei progetti che usano .NET 8 o versione successiva, vedere la libreria datasync di Community Toolkit.

Questo argomento illustra come usare l'SDK del server back-end .NET negli scenari principali di App per dispositivi mobili del servizio app di Azure. Azure Mobile Apps SDK consente di usare i client per dispositivi mobili dall'applicazione ASP.NET.

Avvertimento

Questo articolo illustra le informazioni per la versione della libreria v4.2.0, sostituita dalla libreria v5.0.0. Per informazioni più aggiornate, vedere l'articolo relativo alla versione più recente

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 di applicazione Web ASP.NET (.NET Framework). Se si verificano problemi durante l'individuazione di questo modello, selezionare C#, Tutte le piattaformee 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.orge fornisce la funzionalità di base necessaria per iniziare a usare App per dispositivi mobili di Azure. Per installare il pacchetto:

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

Ripetere il processo per installare anche Microsoft.Owin.Host.SystemWeb.

Nota

Non aggiornare i pacchetti usati come dipendenze, ad esempio Newtonsoft.JSON o System.IdentityModel.Jwt. Le API di questi pacchetti includono, in molti casi, modifiche e sono ora incompatibili con App per dispositivi mobili di Azure per ASP.NET Framework.

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:

Fare clic con il pulsante destro del mouse sul progetto, quindi selezionare Aggiungi>nuovo elemento
Selezionare WebGeneralee quindi selezionare il modello classe di avvio OWIN .
Immettere il nome Startup.cs come nome di avvio.

Il contenuto del file Startup.cs 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 OwinStartup, lo spazio dei nomi e il nome della classe saranno diversi, a seconda del progetto. In particolare, è necessario sostituire il contenuto del metodo Configuration() e regolare di conseguenza le direttive using.

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 con 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 predefinita di App per dispositivi mobili di Azure.
MapApiControllers() fornisce funzionalità API personalizzate per i controller WebAPI decorati con l'attributo [MobileAppController].
AddTables() fornisce un mapping degli endpoint /tables ai controller di tabella.
AddTablesWithEntityFramework() è una breve operazione per eseguire il mapping degli endpoint /tables usando controller basati su Entity Framework.
MapLegacyCrossDomainController() fornisce intestazioni CORS standard per lo sviluppo locale.

Estensioni SDK

I pacchetti di estensione basati su NuGet seguenti offrono varie funzionalità per dispositivi mobili che possono essere usate dall'applicazione. È possibile abilitare le estensioni durante l'inizializzazione usando l'oggetto MobileAppConfiguration .

Microsoft.Azure.Mobile.Server.Quickstart Supporta la configurazione di base delle app per dispositivi mobili. Aggiunta alla configurazione chiamando il metodo di estensione UseDefaultConfiguration durante l'inizializzazione. Questa estensione include le estensioni seguenti: Notifiche, Autenticazione, Entità, Tabelle, Cross-domain e Pacchetti Home.
Microsoft.Azure.Mobile.Server.Home Implementa l'impostazione predefinita questa app per dispositivi mobili è attiva e in esecuzione di pagina per la radice del sito Web. Aggiungere alla configurazione chiamando il metodo di estensione AddMobileAppHomeController.
Microsoft.Azure.Mobile.Server.Tables include classi per l'uso dei dati e la configurazione della pipeline di dati. Aggiungere alla configurazione chiamando il metodo di estensione addTables .
Microsoft.Azure.Mobile.Server.Entity Consente a Entity Framework di accedere ai dati nel database SQL. Aggiungere alla configurazione chiamando il metodo di estensione AddTablesWithEntityFramework.
Microsoft.Azure.Mobile.Server.Authentication Abilita l'autenticazione e configura il middleware OWIN usato per convalidare i token. Aggiungere alla configurazione chiamando il AddAppServiceAuthentication e IAppBuilder.Metodi di estensione UseAppServiceAuthentication.
Microsoft.Azure.Mobile.Server.Notifications Abilita le notifiche push e definisce un endpoint di registrazione push. Aggiungere alla configurazione chiamando il metodo di estensione AddPushNotifications.
Microsoft.Azure.Mobile.Server.CrossDomain Crea un controller che gestisce i dati ai Web browser legacy dall'app per dispositivi mobili. Aggiungere alla configurazione chiamando il metodo di estensione MapLegacyCrossDomainController.
Microsoft.Azure.Mobile.Server.Login Fornisce il metodo AppServiceLoginHandler.CreateToken(), 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 servizio app di Azure.

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

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

Definire un controller di tabella

Definire un controller di tabella per esporre una tabella SQL ai client mobili. La configurazione di un controller di tabella richiede tre passaggi:

Creare una classe DTO (Data Transfer Object).
Configurare un riferimento a una tabella nella classe Mobile DbContext.
Creare un controller di tabella.

Un oggetto DTO (Data Transfer Object) è un oggetto C# normale che eredita da EntityData. Per esempio:

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

L'oggetto DTO viene usato per definire la tabella all'interno del database SQL. Per creare la voce del database, aggiungere una proprietà DbSet<> al 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:

Fare clic con il pulsante destro del mouse sulla cartella Controllers.
Selezionare 'API Web>Controller API Web 2 - Vuoto
Immettere un nome per il controller.

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 del paging della tabella

Per impostazione predefinita, App per dispositivi mobili di Azure restituisce 50 record per richiesta. Il paging garantisce che il client non riordina il thread dell'interfaccia utente né il server per troppo tempo, garantendo un'esperienza utente ottimale. Per modificare le dimensioni del paging della tabella, aumentare le dimensioni delle query sul lato server e le dimensioni della pagina lato client Il lato server "allowed query size" viene modificato usando l'attributo EnableQuery:

[EnableQuery(PageSize = 500)]

Verificare che PageSize sia uguale o maggiore delle dimensioni richieste dal client. Per informazioni dettagliate sulla modifica delle dimensioni della pagina client, vedere la documentazione HOWTO del client specifica.

Definire un controller API personalizzato

Il controller API personalizzato fornisce la funzionalità di base al 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 delle 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 per dispositivi mobili. Questa sezione illustra come eseguire le attività correlate all'autenticazione seguenti 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.

In Visual Studio installare il pacchetto Microsoft.Azure.Mobile.Server.Authentication.
Nel file di progetto aggiungere la riga di codice seguente all'inizio del metodo Configuration :
```
app.UseAppServiceAuthentication(config);
```
Questo componente middleware OWIN convalida i token emessi dal gateway del servizio app associato.
Aggiungere l'attributo [Authorize] a qualsiasi controller o metodo che richiede l'autenticazione.

Usare l'autenticazione personalizzata per l'applicazione

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 questo modo verrà abilitata la variabile di ambiente WEBSITE_AUTH_SIGNING_KEY quando è ospitata.

Se non si vuole usare uno dei provider di autenticazione/autorizzazione del servizio app, è possibile implementare il proprio sistema di accesso. Installare il pacchetto Microsoft.Azure.Mobile.Server.Login per facilitare la generazione di token di autenticazione. Specificare il proprio codice per la convalida delle credenziali utente. Ad esempio, è possibile controllare le password con salted e con hash in un database. Nell'esempio seguente il metodo isValidAssertion() (definito altrove) è responsabile di questi controlli.

L'autenticazione personalizzata viene esposta creando un ApiController ed esponendo register e login azioni. Il client deve 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 che il server convalida l'asserzione, viene emesso un token usando il metodo AppServiceLoginHandler.CreateToken(). Il ApiController non deve usare l'attributo [MobileAppController].

Esempio di azione login:

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. Il client prevede che le risposte di accesso vengano restituite come oggetti JSON del modulo:

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

Il metodo include un gruppo di destinatari e un parametro dell'autorità emittente . Entrambi questi parametri sono impostati sull'URL della radice dell'applicazione, usando lo schema HTTPS. Analogamente, è necessario impostare secretKey come valore della chiave di firma dell'applicazione. Non distribuire la chiave di firma in un client perché può essere usata per coniare le chiavi e rappresentare gli utenti. È possibile ottenere la chiave di firma mentre è ospitata nel servizio app facendo riferimento alla variabile di ambiente WEBSITE_AUTH_SIGNING_KEY. 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 emesso può includere anche altre attestazioni e una data di scadenza. Minimamente, il token rilasciato deve includere un'attestazione subject (sub).

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

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

Mancia

L'uso dell'approccio loginAsync() garantisce che il token di autenticazione sia associato a ogni chiamata successiva al servizio.

Recuperare le informazioni utente autenticate

Quando un utente viene autenticato dal servizio app, è possibile accedere all'ID utente assegnato e ad altre informazioni nel codice back-end .NET. Le informazioni utente possono essere usate per prendere decisioni di 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 attestazioni specifiche dal provider di accesso. Ogni provider di identità può fornire altre informazioni usando l'SDK del provider di identità. Ad esempio, è possibile usare l'API Graph di Facebook per informazioni sugli amici. È possibile specificare 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 all'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 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 il filtro dei risultati della query in base all'ID utente è un modo semplice 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 della 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 un IQueryable che può essere modificato da LINQ per gestire il filtro.

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

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

Registrazione

È possibile scrivere nei log di diagnostica del servizio app usando la scrittura standard ASP.NET traccia. 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:

Seguire i passaggi descritti in Abilitare la registrazione delle applicazioni (Windows).
Aggiungere l'istruzione using seguente nel file di codice:
```
using System.Web.Http.Tracing;
```

Creare un writer di traccia da scrivere dal back-end .NET ai log di diagnostica, come indicato di seguito:

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

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

È necessario avere 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 necessari, vedere la documentazione relativa alla piattaforma client.

Assicurarsi che nel back-end per dispositivi mobili sia installato Microsoft.Azure.Mobile.Server. Authentication. Quindi, nella classe di avvio OWIN dell'applicazione aggiungere quanto segue, dopo che MobileAppConfiguration è stato applicato al 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 è necessario configurare il authAudience e authIssuer impostazioni dell'applicazione all'interno del file Web.config in modo che siano l'URL della radice dell'applicazione usando lo schema HTTPS. Analogamente, è necessario impostare authSigningKey come valore della chiave di firma dell'applicazione.

Per ottenere la chiave di firma:

Passare all'app all'interno del portale di Azure
Fare clic su Tools>Kudu>Go.
Nel sito di gestione Kudu fare clic su Ambiente.
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.

Condividi tramite