Comment utiliser le Kit de développement logiciel (SDK) ASP.NET Framework pour Azure Mobile Apps

Note

Ce produit est mis hors service. Pour un remplacement des projets utilisant .NET 8 ou version ultérieure, consultez la bibliothèque Datasync Community Toolkit.

Cette rubrique vous montre comment utiliser le Kit de développement logiciel (SDK) du serveur principal .NET dans les scénarios Azure App Service Mobile Apps clés. Le Kit de développement logiciel (SDK) Azure Mobile Apps vous aide à utiliser des clients mobiles à partir de votre application ASP.NET.

Avertissement

Cet article décrit les informations relatives à la version de la bibliothèque v4.2.0, qui est superposée par la bibliothèque v5.0.0. Pour obtenir les informations les plus récentes, consultez l’article relatif à la dernière version

Créer un serveur principal Azure Mobile Apps ASP.NET Framework

Vous pouvez créer une application ASP.NET Framework à l’aide de Visual Studio 2019.

• Choisissez le modèle application web (.NET Framework) ASP.NET. Si vous rencontrez des difficultés pour localiser ce modèle, sélectionnez C#, toutes les plateformeset Web.
• Après avoir sélectionné un nom et un emplacement pour l’application, sélectionnez le modèle de projet API web. La collection correcte des services de base pour votre application est installée.

Télécharger et initialiser le Kit de développement logiciel (SDK)

Le Kit de développement logiciel (SDK) est disponible sur NuGet.orget fournit les fonctionnalités de base requises pour commencer à utiliser Azure Mobile Apps. Pour installer le package :

1. Cliquez avec le bouton droit sur le projet, puis sélectionnez Gérer les packages NuGet....
2. Dans l’onglet Parcourir, entrez Microsoft.Azure.Mobile.Server dans la zone de recherche, puis appuyez sur Entrée.
3. Sélectionnez le package Microsoft.Azure.Mobile.Server.Quickstart.
4. Cliquez sur Installer.
5. Suivez les invites pour terminer l’installation.

Répétez également le processus d’installation de Microsoft.Owin.Host.SystemWeb.

Note

Ne mettez pas à jour les packages utilisés comme dépendances, tels que Newtonsoft.JSON ou System.IdentityModel.Jwt. Les API de ces packages ont, dans de nombreux cas, changé et sont désormais incompatibles avec Azure Mobile Apps pour ASP.NET Framework.

Initialiser le projet de serveur

Un projet de serveur Azure Mobile Apps est initialisé similaire à d’autres projets ASP.NET Framework ; en incluant une classe OWIN Startup. Pour ajouter une classe OWIN Startup :

1. Cliquez avec le bouton droit sur le projet, puis sélectionnez Ajouter>nouvel élément

2. Sélectionnez >général, puis sélectionnez le modèle classe OWIN Startup.

3. Entrez le nom Startup.cs comme nom de démarrage.

4. Le contenu du fichier Startup.cs doit être similaire au code suivant :

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

   Le nom de la OwinStartup, de l’espace de noms et de la classe sera différent, en fonction de votre projet. Plus précisément, vous devez remplacer le contenu de la méthode Configuration() et ajuster les directives using en conséquence.

Pour activer des fonctionnalités individuelles, vous devez appeler des méthodes d’extension sur l’objet MobileAppConfiguration avant d’appeler ApplyTo. Par exemple, le code suivant ajoute les itinéraires par défaut à tous les contrôleurs d’API qui ont l’attribut [MobileAppController] lors de l’initialisation :

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

La configuration suivante est considérée comme une utilisation « normale » qui permet aux contrôleurs de table et d’API à l’aide d’Entity Framework d’accéder à un service SQL.

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

Les méthodes d’extension utilisées sont les suivantes :

• AddMobileAppHomeController() fournit la page d’accueil Par défaut d’Azure Mobile Apps.
• MapApiControllers() fournit des fonctionnalités d’API personnalisées pour les contrôleurs WebAPI décorés avec l’attribut [MobileAppController].
• AddTables() fournit un mappage des points de terminaison /tables aux contrôleurs de table.
• AddTablesWithEntityFramework() est un raccourci pour mapper les points de terminaison /tables à l’aide de contrôleurs basés sur Entity Framework.
• MapLegacyCrossDomainController() fournit des en-têtes CORS standard pour le développement local.

Extensions du Kit de développement logiciel (SDK

Les packages d’extension NuGet suivants fournissent différentes fonctionnalités mobiles qui peuvent être utilisées par votre application. Vous activez les extensions pendant l’initialisation à l’aide de l’objet MobileAppConfiguration .

• Démarrage rapide microsoft.Azure.Mobile.Server.Quickstart Prend en charge la configuration de base de Mobile Apps. Ajouté à la configuration en appelant la méthode d’extension UseDefaultConfiguration lors de l’initialisation. Cette extension inclut les extensions suivantes : Notifications, Authentification, Entité, Tables, Inter-domaines et packages Home.
• Microsoft.Azure.Mobile.Server.Home Implémente la par défaut que cette application mobile est opérationnelle pour la racine du site web. Ajoutez à la configuration en appelant la méthode d’extension AddMobileAppHomeController.
• Microsoft.Azure.Mobile.Server.Tables inclut des classes permettant d’utiliser des données et de configurer le pipeline de données. Ajoutez à la configuration en appelant la méthode d’extension addTables .
• Microsoft.Azure.Mobile.Server.Entity permet à Entity Framework d’accéder aux données dans la base de données SQL. Ajoutez à la configuration en appelant la méthode d’extension AddTablesWithEntityFramework.
• Microsoft.Azure.Mobile.Server.Authentication Active l’authentification et configure le middleware OWIN utilisé pour valider les jetons. Ajoutez à la configuration en appelant le AddAppServiceAuthentication et IAppBuilder.méthodes d’extension UseAppServiceAuthentication.
• Microsoft.Azure.Mobile.Server.Notifications Active les notifications Push et définit un point de terminaison d’inscription Push. Ajoutez à la configuration en appelant la méthode d’extension AddPushNotifications.
• Microsoft.Azure.Mobile.Server.CrossDomain Crée un contrôleur qui sert des données aux navigateurs web hérités à partir de votre application mobile. Ajoutez à la configuration en appelant la méthode d’extension MapLegacyCrossDomainController.
• Microsoft.Azure.Mobile.Server.Login Fournit la méthode AppServiceLoginHandler.CreateToken(), qui est une méthode statique utilisée pendant les scénarios d’authentification personnalisés.

Publier le projet de serveur

Cette section vous montre comment publier votre projet principal .NET à partir de Visual Studio. Il existe d’autres méthodes par lesquelles vous pouvez publier votre application. Pour plus d’informations, consultez la documentation Azure App Service.

1. Dans Visual Studio, régénérez le projet pour restaurer des packages NuGet.
2. Dans l’Explorateur de solutions, cliquez avec le bouton droit sur le projet, cliquez sur Publier.
3. Si vous n’avez pas déjà publié ce projet, vous allez configurer la publication.
   • Sélectionnez Azure pour la cible.
   • Sélectionnez Azure App Service (Windows) pour la cible spécifique.
   • Sélectionnez l’instance app service sur laquelle vous souhaitez effectuer le déploiement. Si vous n’en avez pas, utilisez la + pour en créer une.
   • Cliquez sur Terminer.
4. Si vous n’avez pas déjà lié une base de données SQL, cliquez sur Configurer en regard de la base de données SQL.
   • Sélectionnez Azure SQL Database
   • Sélectionnez votre base de données. Si vous n’en avez pas ou si vous souhaitez en utiliser un autre, cliquez sur le + pour créer une base de données et un serveur.
   • Entrez MS_TableConnectionString comme nom de chaîne de connexion de base de données. Renseignez le nom d’utilisateur et le mot de passe dans les zones fournies.
   • Cliquez sur Terminer
5. Cliquez sur publier

La publication sur Azure prend un certain temps. Pour plus d’informations, consultez la documentation visual Studio.

Définir un contrôleur de table

Définissez un contrôleur de table pour exposer une table SQL aux clients mobiles. La configuration d’un contrôleur de table nécessite trois étapes :

1. Créez une classe DTO (Data Transfer Object).
2. Configurez une référence de table dans la classe Mobile DbContext.
3. Créez un contrôleur de table.

Un objet DTO (Data Transfer Object) est un objet C# brut qui hérite de EntityData. Par exemple:

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

Le DTO est utilisé pour définir la table dans la base de données SQL. Pour créer l’entrée de base de données, ajoutez une propriété DbSet<> au DbContext que vous utilisez :

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

Enfin, créez un contrôleur :

1. Cliquez avec le bouton droit sur le dossier Controllers.

2. Sélectionnez contrôleur d’API web>API web 2 - vide

3. Entrez un nom pour le contrôleur.

4. Remplacez le contenu du nouveau contrôleur par le code suivant :

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

Ajuster la taille de pagination de la table

Par défaut, Azure Mobile Apps retourne 50 enregistrements par requête. La pagination garantit que le client ne lie pas son thread d’interface utilisateur ni le serveur pendant trop longtemps, ce qui garantit une bonne expérience utilisateur. Pour modifier la taille de pagination de la table, augmentez la « taille de requête autorisée » côté serveur et la taille de page côté client La taille de la page côté serveur « taille de requête autorisée » est ajustée à l’aide de l’attribut EnableQuery :

[EnableQuery(PageSize = 500)]

Vérifiez que PageSize est identique ou supérieur à la taille demandée par le client. Pour plus d’informations sur la modification de la taille de page du client, reportez-vous à la documentation HOWTO spécifique du client.

Définir un contrôleur d’API personnalisé

Le contrôleur d’API personnalisé fournit les fonctionnalités les plus élémentaires à votre back-end d’application mobile en exposant un point de terminaison. Vous pouvez inscrire un contrôleur d’API spécifique à un mobile à l’aide de l’attribut [MobileAppController]. L’attribut MobileAppController inscrit l’itinéraire, configure le sérialiseur JSON Mobile Apps et active la vérification de version du client.

Le contenu du contrôleur d’API personnalisé est le suivant :

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

Une fois configuré avec l’attribut MobileAppController, vous pouvez définir l’API personnalisée de la même façon que n’importe quelle autre API web.

Utiliser l’authentification

Azure Mobile Apps utilise l’authentification/l’autorisation App Service pour sécuriser votre back-end mobile. Cette section vous montre comment effectuer les tâches liées à l’authentification suivantes dans votre projet de serveur principal .NET :

• Ajouter l’authentification à un projet de serveur
• Utiliser l’authentification personnalisée pour votre application
• Récupérer les informations utilisateur authentifiées
• restreindre l’accès aux données pour les utilisateurs autorisés

Ajouter l’authentification à un projet de serveur

Vous pouvez ajouter l’authentification à votre projet de serveur en étendant l’objet MobileAppConfiguration et en configurant l’intergiciel OWIN.

1. Dans Visual Studio, installez le package Microsoft.Azure.Mobile.Server.Authentication.

2. Dans le fichier projet Startup.cs, ajoutez la ligne de code suivante au début de la méthode Configuration :

   app.UseAppServiceAuthentication(config);
   

   Ce composant d’intergiciel OWIN valide les jetons émis par la passerelle App Service associée.

3. Ajoutez l’attribut [Authorize] à n’importe quel contrôleur ou méthode qui nécessite l’authentification.

Utiliser l’authentification personnalisée pour votre application

Important

Pour activer l’authentification personnalisée, vous devez d’abord activer l’authentification App Service sans sélectionner de fournisseur pour votre App Service dans le portail Azure. Cela active la variable d’environnement WEBSITE_AUTH_SIGNING_KEY lors de l’hébergement.

Si vous ne souhaitez pas utiliser l’un des fournisseurs d’authentification/autorisation App Service, vous pouvez implémenter votre propre système de connexion. Installez le package microsoft.Azure.Mobile.Server.Login pour faciliter la génération de jetons d’authentification. Fournissez votre propre code pour valider les informations d’identification de l’utilisateur. Par exemple, vous pouvez vérifier les mots de passe salés et hachés dans une base de données. Dans l’exemple ci-dessous, la méthode isValidAssertion() (définie ailleurs) est responsable de ces vérifications.

L’authentification personnalisée est exposée en créant un ApiController et en exposant register et login actions. Le client doit utiliser une interface utilisateur personnalisée pour collecter les informations de l’utilisateur. Les informations sont ensuite envoyées à l’API avec un appel HTTP POST standard. Une fois que le serveur valide l’assertion, un jeton est émis à l’aide de la méthode AppServiceLoginHandler.CreateToken(). Le ApiController ne doit pas utiliser l’attribut [MobileAppController].

Exemple d’action 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();
    }
}

Dans l’exemple précédent, LoginResult et LoginResultUser sont des objets sérialisables exposant les propriétés requises. Le client s’attend à ce que les réponses de connexion soient retournées en tant qu’objets JSON du formulaire :

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

La méthode inclut un d’audience et un paramètre émetteur. Ces deux paramètres sont définis sur l’URL de la racine de votre application, à l’aide du schéma HTTPS. De même, vous devez définir secretKey comme valeur de la clé de signature de votre application. Ne distribuez pas la clé de signature dans un client, car elle peut être utilisée pour créer des clés et emprunter l’identité des utilisateurs. Vous pouvez obtenir la clé de signature lors de l’hébergement dans App Service en référençant la variable d’environnement WEBSITE_AUTH_SIGNING_KEY. Si nécessaire dans un contexte de débogage local, suivez les instructions de la section Débogage local avec l’authentification section pour récupérer la clé et la stocker en tant que paramètre d’application.

Le jeton émis peut également inclure d’autres revendications et une date d’expiration. Minimalement, le jeton émis doit inclure une revendication d’objet (sous-).

Vous pouvez prendre en charge la méthode loginAsync() client standard en surchargeant l’itinéraire d’authentification. Si le client appelle client.loginAsync('custom'); pour vous connecter, votre itinéraire doit être /.auth/login/custom. Vous pouvez définir l’itinéraire du contrôleur d’authentification personnalisé à l’aide de MapHttpRoute():

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

Pourboire

L’utilisation de l’approche loginAsync() garantit que le jeton d’authentification est attaché à chaque appel ultérieur au service.

Récupérer les informations utilisateur authentifiées

Lorsqu’un utilisateur est authentifié par App Service, vous pouvez accéder à l’ID d’utilisateur affecté et à d’autres informations dans votre code principal .NET. Les informations utilisateur peuvent être utilisées pour prendre des décisions d’autorisation dans le back-end. Le code suivant obtient l’ID utilisateur associé à une requête :

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

Le SID est dérivé de l’ID utilisateur spécifique au fournisseur et est statique pour un utilisateur et un fournisseur de connexion donnés. Le SID est null pour les jetons d’authentification non valides.

App Service vous permet également de demander des revendications spécifiques à votre fournisseur de connexion. Chaque fournisseur d’identité peut fournir plus d’informations à l’aide du Kit de développement logiciel (SDK) du fournisseur d’identité. Par exemple, vous pouvez utiliser l’API Facebook Graph pour obtenir des informations sur vos amis. Vous pouvez spécifier des revendications demandées dans le panneau fournisseur dans le portail Azure. Certaines revendications nécessitent davantage de configuration avec le fournisseur d’identité.

Le code suivant appelle la méthode d’extension GetAppServiceIdentityAsync pour obtenir les informations d’identification de connexion, notamment le jeton d’accès nécessaire pour effectuer des demandes sur l’API Facebook Graph :

// Get the credentials for the logged-in user.
var credentials = await this.User.GetAppServiceIdentityAsync<FacebookCredentials>(this.Request);

if (credentials.Provider == "Facebook")
{
    // Create a query string with the Facebook access token.
    var fbRequestUrl = "https://graph.facebook.com/me/feed?access_token="
        + credentials.AccessToken;

    // Create an HttpClient request.
    var client = new System.Net.Http.HttpClient();

    // Request the current user info from Facebook.
    var resp = await client.GetAsync(fbRequestUrl);
    resp.EnsureSuccessStatusCode();

    // Do something here with the Facebook user information.
    var fbInfo = await resp.Content.ReadAsStringAsync();
}

Ajoutez une instruction using pour System.Security.Principal pour fournir la méthode d’extension GetAppServiceIdentityA sync.

Restreindre l’accès aux données pour les utilisateurs autorisés

Dans la section précédente, nous avons montré comment récupérer l’ID d’utilisateur d’un utilisateur authentifié. Vous pouvez restreindre l’accès aux données et à d’autres ressources en fonction de cette valeur. Par exemple, l’ajout d’une colonne userId aux tables et le filtrage des résultats de la requête par l’ID utilisateur est un moyen simple de limiter les données retournées uniquement aux utilisateurs autorisés. Le code suivant retourne des lignes de données uniquement lorsque le SID correspond à la valeur de la colonne UserId de la table 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);

La méthode Query() retourne une IQueryable qui peut être manipulée par LINQ pour gérer le filtrage.

Déboguer et dépanner le Kit de développement logiciel (SDK) du serveur .NET

Azure App Service fournit plusieurs techniques de débogage et de résolution des problèmes pour les applications ASP.NET :

• Supervision des Azure App Service
• Activer la journalisation des diagnostics dans Azure App Service
• résoudre les problèmes d’azure App Service dans Visual Studio

Exploitation forestière

Vous pouvez écrire dans les journaux de diagnostic App Service à l’aide de l’écriture de trace ASP.NET standard. Avant de pouvoir écrire dans les journaux, vous devez activer les diagnostics dans votre back-end Azure Mobile Apps.

Pour activer les diagnostics et écrire dans les journaux :

1. Suivez les étapes décrites dans Activer la journalisation des applications (Windows).

2. Ajoutez l’instruction using suivante dans votre fichier de code :

   using System.Web.Http.Tracing;
   

3. Créez un enregistreur de trace pour écrire à partir du back-end .NET dans les journaux de diagnostic, comme suit :

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

4. Republiez votre projet de serveur et accédez au back-end Azure Mobile Apps pour exécuter le chemin du code avec la journalisation.

5. Téléchargez et évaluez les journaux, comme décrit dans fichiers journaux Access.

Débogage local avec authentification

Vous pouvez exécuter votre application localement pour tester les modifications avant de les publier dans le cloud. Pour la plupart des back-ends Azure Mobile Apps, appuyez sur F5 dans Visual Studio. Toutefois, il existe des considérations supplémentaires lors de l’utilisation de l’authentification.

Vous devez disposer d’une application mobile basée sur le cloud avec l’authentification/autorisation App Service configurée, et votre client doit avoir le point de terminaison cloud spécifié comme autre hôte de connexion. Consultez la documentation de votre plateforme cliente pour connaître les étapes spécifiques requises.

Vérifiez que votre serveur principal mobile a Microsoft.Azure.Mobile.Server.Authentication installé. Ensuite, dans la classe de démarrage OWIN de votre application, ajoutez ce qui suit, une fois que MobileAppConfiguration a été appliqué à votre HttpConfiguration:

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

Dans l’exemple précédent, vous devez configurer l'authAudience et les paramètres de l’application au sein de votre fichier Web.config pour chacune être l’URL de la racine de votre application, à l’aide du schéma HTTPS. De même, vous devez définir authSigningKey comme valeur de la clé de signature de votre application.

Pour obtenir la clé de signature :

1. Accédez à votre application dans le portail Azure
2. Cliquez sur Tools>Kudu>Go.
3. Dans le site De gestion Kudu, cliquez sur Environnement.
4. Recherchez la valeur de WEBSITE_AUTH_SIGNING_KEY.

Utilisez la clé de signature pour le paramètre authSigningKey dans la configuration de votre application locale. Votre back-end mobile est maintenant équipé pour valider les jetons lors de l’exécution locale, que le client obtient le jeton à partir du point de terminaison cloud.