Comment démarrer avec ASP.NET pour le développement d’API

ASP.NET est une plate-forme de création d’API Web avec C # et .NET. Il est couramment utilisé pour les backends d’applications et peut sérialiser automatiquement les classes en JSON. Nous allons passer en revue la configuration d’un service qui communique avec une base de données et stocke une liste d’objets.

Créer un projet

Nous utiliserons Visual Studio, car il fournit une excellente prise en charge .NET prête à l’emploi. Créez un nouveau projet à l’aide du modèle «Application Web ASP.NET Core»:

Donnez-lui un nom et sélectionnez «API», car nous ne construisons pas ici une interface ASP.NET.

Cela initialisera votre solution avec tout le passe-partout nécessaire pour obtenir une API de base opérationnelle. Si vous cliquez sur le bouton Exécuter (intitulé IIS Express, qui démarre un serveur Web IIS), vous verrez l’API affichant des données factices sur la météo.

Nous utiliserons cette base pour configurer une API simple qui se connectera à une base de données et lira et écrira des objets personnalisés. Dans ce cas, il s’agit d’une collection de données utilisateur, mais l’API fonctionnera largement de la même manière pour les modèles d’entités plus complexes.

Connexion d’une base de données

C’est une bonne idée de séparer la logique de traitement des requêtes et la logique de gestion des conversations avec la base de données. Nous allons créer un service de base de données avec quelques fonctions de lecture et d’écriture, puis un contrôleur API qui répondra aux requêtes en parlant au service de base de données. La première chose à faire, cependant, est de faire parler ASP.NET à une base de données en premier lieu.

Nous aurons besoin d’installer des packages pour travailler avec une base de données. Cliquez sur Outils> Gestionnaire de packages NuGet, puis sélectionnez « Gérer les packages NuGet pour la solution ».

Si vous utilisez une base de données SQL, la connexion à la base de données est gérée avec des packages de plugins spécifiques qui implémentent EntityFrameworkCore pour la base de données sous-jacente. Il s’agit d’un framework qui mappe des objets C # à une base de données relationnelle et vous permet d’utiliser des requêtes LINQ et d’autres outils natifs pour interagir avec elle. Vous pouvez trouver une liste complète des fournisseurs de bases de données ici pour les bases de données relationnelles les plus populaires.

Nous allons utiliser MongoDB ici, car les bases de données de documents NoSQL se traduisent en List<Object> de manière assez transparente, et le pilote MongoDB prend en charge les requêtes LINQ tout comme EF Core.

Installez le package MongoDB.Driver:

Créez un nouveau dossier à la racine de votre projet appelé «Modèles». Dans celui-ci, créez un modèle d’entité appelé User.cs, qui sera le schéma de la collection stockée dans la base de données. Vous pouvez utiliser le [BsonId] et [BsonRepresentation(BsonType.ObjectId)] attributs pour indiquer au pilote MongoDB que cette chaîne d’ID doit être interprétée comme l’ID de collection et peut être passée en tant que type string même si Mongo veut du type en interne ObjectId.

using MongoDB.Bson;
using MongoDB.Bson.Serialization.Attributes;
using System;

namespace ExampleService.Models
{
    public class User
    {
        [BsonId]
        [BsonRepresentation(BsonType.ObjectId)]
        public string Id { get; set; }
        
        [BsonElement("Name")]
        public string Name { get; set; }
        public string Email { get; set; }
        // etc...
    }
}

Dans ce même dossier, créez un fichier appelé DatabaseSettings.cs, qui stockera une classe et une interface pour les paramètres de la base de données.

namespace ExampleService.Models
{
    public class ExampleDatabaseSettings : IExampleDatabaseSettings
    {
        public string ExampleCollectionName { get; set; }
        public string ConnectionString { get; set; }
        public string DatabaseName { get; set; }
    }

    public interface IExampleDatabaseSettings
    { 
        string ExampleCollectionName { get; set; }
        string ConnectionString { get; set; }
        string DatabaseName { get; set; }
    }
}

Nous pouvons renseigner ces valeurs de propriété dans appsettings.json, en ajoutant la configuration suivante:

"ExampleDatabaseSettings": {
    "ExampleCollectionName": "Users",
    "ConnectionString": "mongodb://localhost:27017",
    "DatabaseName": "Example"
}

Vous devrez bien sûr créer ou renommer le Example base de données, ainsi que créer la Users collection en elle.

Enfin, nous ajouterons du code dans Startup.cs dans le ConfigureServices , qui récupérera les paramètres de la appsettings.json et enregistrez l’interface via Dependency Injection:

public void ConfigureServices(IServiceCollection services)
{
    services.Configure<ExampleDatabaseSettings>(
      Configuration.GetSection(nameof(ExampleDatabaseSettings)));

    services.AddSingleton<IExampleDatabaseSettings>(sp =>
      sp.GetRequiredService<IOptions<ExampleDatabaseSettings>>().Value);

    services.AddControllers();
}

Vous devrez ajouter une directive en haut en utilisant votre espace de noms Models.

Ecrire un service de base de données CRUD

Une fois la base de données connectée, vous pouvez ajouter le service qui parlera. La classe suivante contient un IMongoCollection qui représente la collection MongoDB dans un format avec lequel C # peut facilement interagir. Les lectures, écritures, mises à jour et suppressions affecteront directement la collection sous-jacente.

La méthode constructeur prend les paramètres de la base de données, démarre un nouveau client, récupère la base de données, puis initialise le _users collection.

using ExampleService.Models;
using MongoDB.Driver;
using System.Collections.Generic;
using System.Linq;

namespace ExampleService.Services
{
    public class ExampleService
    {
        private readonly IMongoCollection<User> _users;

        public UserService(IExampleDatabaseSettings settings)
        {
            var client = new MongoClient(settings.ConnectionString);
            var database = client.GetDatabase(settings.DatabaseName);

            _users = database.GetCollection<User>(settings.ExampleCollectionName);
        }

        public List<User> Get() =>
            _users.Find(user => true).ToList();

        public User Get(string id) =>
            _users.Find<User>(user => user.Id == id).FirstOrDefault();

        public User Create(User user)
        {
            _users.InsertOne(user);
            return user;
        }

        public void Update(string id, User userIn) =>
            _users.ReplaceOne(user=> user.Id == id, userIn);

        public void Remove(User userIn) =>
            _users.DeleteOne(user => user.Id == userIn.Id);

        public void Remove(string id) => 
            _users.DeleteOne(user=> user.Id == id);
    }
}

Le reste de la classe est simplement un ensemble d’opérations CRUD pour interagir avec la base de données. N’hésitez pas à implémenter ici toute logique personnalisée.

De retour Startup.cs, vous voudrez l’ajouter en tant que service au démarrage:

public void ConfigureServices(IServiceCollection services)
{
    services.Configure<ExampleDatabaseSettings>(
      Configuration.GetSection(nameof(ExampleDatabaseSettings)));

    services.AddSingleton<IExampleDatabaseSettings>(sp =>
      sp.GetRequiredService<IOptions<ExampleDatabaseSettings>>().Value);

    services.AddSingleton<ExampleService>();

    services.AddControllers();
}

Vous aurez encore besoin d’un autre using directive, cette fois pour ExampleService.Services.

Configuration d’un contrôleur d’API

Ensuite, vous aurez besoin d’un contrôleur pour gérer les actions de l’API. Heureusement, Visual Studio rend cela facile; vous pouvez faire un clic droit sur «Contrôleurs» pour ajouter un nouveau contrôleur, avec des actions de lecture / écriture. Cela créera un nouveau contrôleur avec quelques méthodes de base.

L’itinéraire est défini en haut. Par défaut, il est défini sur /api/controller, où contrôleur est le nom du contrôleur (moins la partie «Contrôleur»). Vous pouvez changer cela si vous le souhaitez, mais c’est un bon modèle pour la plupart des gens.

[Route("api/[controller]")]

Vous voudrez ajouter une référence à votre service de base de données en haut de la classe et la remplir dans le constructeur:

private readonly ExampleService _exampleService;

public ExampleController(ExampleService exampleService)
{
    _exampleService = exampleService;
}

Vous voudrez changer la méthode HttpGet pour renvoyer un ActionResult<List<T>> du schéma que vous stockez. (Vous devrez bien sûr ajouter une référence à votre espace de noms Models.) ActionResult est un type dynamique qui encapsule soit la valeur TV à l’intérieur, soit un résultat de réponse HTTP.

[HttpGet]
public ActionResult<List<User>> Get()
{
    return _exampleService.Get();
}

Si vous souhaitez ajouter une autre méthode Get, mais sur une route différente, vous pouvez la passer en paramètre dans l’attribut:

[HttpGet("otherroute")]
public ActionResult<List<User>> GetSomeThingElse()
{
    return _exampleService.GetSomeThingElse();
}

Ensuite, pour la méthode HttpPost, appelez la méthode Create de votre service de base de données et renvoyez CreatedAtRoute, qui enverra une réponse 201 au client l’informant que la création de l’objet a réussi.

[HttpPost]
public ActionResult<User> Create(User userIn)
{
    _exampleService.Create(userIn);

    return CreatedAtRoute("GetUser", new { id = userIn.Id.ToString() }, userIn);
}

Pour les autres itinéraires, vous pouvez les configurer comme vous le souhaitez. L’idée générale est de gérer l’entrée de l’utilisateur, d’effectuer toutes les validations dont vous avez besoin et d’appeler les actions de base de données appropriées, en retournant à l’utilisateur un élément utile ou un code d’état lui indiquant ce qui s’est passé.

À ce stade, cependant, vous devriez pouvoir appuyer sur le bouton d’exécution d’IIS Express en haut et tester l’API. L’itinéraire par défaut sera l’API des services météorologiques fournie avec le passe-partout, donc plutôt que de le saisir à chaque fois, vous pouvez modifier l’itinéraire de débogage sous Projet> Propriétés> Déboguer et en modifiant l’option Lancer le navigateur.

Une fois que vous souhaitez tester sur un serveur distant, vous pouvez créer une version de production à partir de Build> Publish Service. Sélectionnez la sortie du fichier et modifiez la configuration en fonction de vos besoins. Par exemple, vous pouvez choisir de créer de manière autonome, ce qui regroupera toutes les dépendances .NET avec la génération, et également de publier en tant qu’exécutable unique. Vous pouvez également modifier le runtime cible ici.

Si vous souhaitez publier sur Linux, vous devrez ajouter un identifiant d’exécution à votre .csproj fichier.

<RuntimeIdentifier>linux-x64</RuntimeIdentifier>

Bien entendu, l’API présentée ici n’est pas sécurisée. ASP.NET dispose d’un excellent système d’authentification, offrant une prise en charge des jetons basés sur JWT, et peut être configuré pour fonctionner avec des fournisseurs OAuth tels que Google et Facebook.