Tutoriel : Création d’une API web avec ASP.NET Core

Par Rick Anderson et Kirk Larkin

Ce tutoriel décrit les principes fondamentaux liés à la génération d’une API web avec ASP.NET Core.

Dans ce tutoriel, vous allez apprendre à :

  • Créer un projet d’API web.
  • Ajouter une classe de modèle et un contexte de base de données.
  • Générer automatiquement des modèles pour un contrôleur avec des méthodes CRUD.
  • Configurer le routage, les chemins d’URL et les valeurs de retour.
  • Appeler l’API web avec Postman

À la fin, vous disposez d’une API web qui peut gérer des tâches stockées dans une base de données.

Vue d’ensemble

Ce didacticiel crée l’API suivante :

API Description Corps de la demande Response body
GET /api/todoitems Obtenir toutes les tâches None Tableau de tâches
GET /api/todoitems/{id} Obtenir un élément par ID None Tâche
POST /api/todoitems Ajouter un nouvel élément Tâche Tâche
PUT /api/todoitems/{id} Mettre à jour un élément existant Tâche None
DELETE /api/todoitems/{id}     Supprimer un élément None None

Le diagramme suivant illustre la conception de l’application.

The client is represented by a box on the left. It submits a request and receives a response from the application, a box drawn on the right. Within the application box, three boxes represent the controller, the model, and the data access layer. The request comes into the application's controller, and read/write operations occur between the controller and the data access layer. The model is serialized and returned to the client in the response.

Prérequis

Créer un projet web

  • Dans le menu Fichier, sélectionnez Nouveau>Projet.
  • Entrez API web dans le champ de recherche.
  • Sélectionnez le modèle d’API web ASP.NET Core, puis sélectionnez Suivant.
  • Dans la boîte de dialogue Configurer votre nouveau projet, nommez le projet TodoApi , puis sélectionnez Suivant.
  • Dans la boîte de dialogue Informations supplémentaires :
    • Vérifiez que le framework est .NET 6.0 (prise en charge à long terme).
    • Vérifiez que la case à cocher Utiliser des contrôleurs (décocher pour utiliser les API minimales) est cochée.
    • Sélectionnez Create (Créer).

Notes

Pour obtenir des conseils sur l’ajout de packages à des applications .NET, consultez les articles sous Installer et gérer des packages dans le flux de travail consommation des packages (NuGet documentation). Confirmez les versions correctes du package sur NuGet.org.

Tester le projet

Le modèle de projet crée une WeatherForecast API avec prise en charge de Swagger.

Appuyez sur Ctrl+F5 pour exécuter sans le débogueur.

Visual Studio affiche la boîte de dialogue suivante lorsqu’un projet n’est pas encore configuré pour utiliser SSL :

This project is configured to use SSL. To avoid SSL warnings in the browser you can choose to trust the self-signed certificate that IIS Express has generated. Would you like to trust the IIS Express SSL certificate?

Sélectionnez Oui si vous faites confiance au certificat SSL d’IIS Express.

La boîte de dialogue suivante s’affiche :

Security warning dialog

Sélectionnez Oui si vous acceptez d’approuver le certificat de développement.

Pour plus d’informations sur l’approbation du navigateur Firefox, consultez Firefox SEC_ERROR_INADEQUATE_KEY_USAGE erreur de certificat.

Visual Studio lance le navigateur par défaut et accède à https://localhost:<port>/swagger/index.html, où <port> est un numéro de port choisi de manière aléatoire.

La page /swagger/index.html Swagger s’affiche. Sélectionnez GETTry>outExecute>. La page s’affiche :

  • Commande Curl pour tester l’API WeatherForecast.
  • URL pour tester l’API WeatherForecast.
  • Code de réponse, corps et en-têtes.
  • Zone de liste déroulante avec des types multimédias et l’exemple de valeur et de schéma.

Si la page Swagger n’apparaît pas, consultez ce problème GitHub.

Swagger est utilisé pour générer de la documentation et des pages d’aide utiles pour les API web. Ce tutoriel se concentre sur la création d’une API web. Pour plus d’informations sur Swagger, consultez ASP.NET Core documentation sur l’API web avec Swagger / OpenAPI.

Copiez et collez l’URL de la requête dans le navigateur : https://localhost:<port>/weatherforecast

JSON similaire à l’exemple suivant est retourné :

[
    {
        "date": "2019-07-16T19:04:05.7257911-06:00",
        "temperatureC": 52,
        "temperatureF": 125,
        "summary": "Mild"
    },
    {
        "date": "2019-07-17T19:04:05.7258461-06:00",
        "temperatureC": 36,
        "temperatureF": 96,
        "summary": "Warm"
    },
    {
        "date": "2019-07-18T19:04:05.7258467-06:00",
        "temperatureC": 39,
        "temperatureF": 102,
        "summary": "Cool"
    },
    {
        "date": "2019-07-19T19:04:05.7258471-06:00",
        "temperatureC": 10,
        "temperatureF": 49,
        "summary": "Bracing"
    },
    {
        "date": "2019-07-20T19:04:05.7258474-06:00",
        "temperatureC": -1,
        "temperatureF": 31,
        "summary": "Chilly"
    }
]

Mettre à jour le launchUrl

Dans Properties\launchSettings.json, mettez à "api/todoitems"jour launchUrl à partir de "swagger" :

"launchUrl": "api/todoitems",

Étant donné que Swagger est supprimé, le balisage précédent modifie l’URL lancée vers la méthode GET du contrôleur ajoutée dans les sections suivantes.

Ajouter une classe de modèle

Un modèle est un ensemble de classes qui représentent les données gérées par l’application. Le modèle pour cette application est une classe TodoItem unique.

  • Dans l’Explorateur de solutions, cliquez avec le bouton droit sur le projet. Sélectionnez AddNew>Folder. Nommez le dossier Models.

  • Cliquez avec le bouton droit sur le Models dossier et sélectionnez AddClass>. Nommez la classe TodoItem et sélectionnez sur Ajouter.

  • Remplacez le code de modèle par les éléments suivants :

namespace TodoApi.Models
{
    public class TodoItem
    {
        public long Id { get; set; }
        public string? Name { get; set; }
        public bool IsComplete { get; set; }
    }
}

La propriété Id fonctionne comme la clé unique dans une base de données relationnelle.

Les classes de modèle peuvent aller n’importe où dans le projet, mais le Models dossier est utilisé par convention.

Ajouter un contexte de base de données

Le contexte de base de données est la classe principale qui coordonne les fonctionnalités d’Entity Framework pour un modèle de données. Cette classe est créée en dérivant de la classe Microsoft.EntityFrameworkCore.DbContext.

Ajouter des packages NuGet

  • Dans le menu Outils, sélectionnez NuGet Gestionnaire de package Gérer les > packages NuGet pour la solution.
  • Sélectionnez l’onglet Parcourir , puis entrez Microsoft.EntityFrameworkCore.InMemory dans la zone de recherche.
  • Sélectionnez Microsoft.EntityFrameworkCore.InMemory dans le volet gauche.
  • Cochez la case Project dans le volet droit, puis sélectionnez Installer.

Ajouter le contexte de base de données TodoContext

  • Cliquez avec le bouton droit sur le Models dossier et sélectionnez AddClass>. Nommez la classe TodoContext et cliquez sur Ajouter.
  • Entrez le code suivant :

    using Microsoft.EntityFrameworkCore;
    using System.Diagnostics.CodeAnalysis;
    
    namespace TodoApi.Models
    {
        public class TodoContext : DbContext
        {
            public TodoContext(DbContextOptions<TodoContext> options)
                : base(options)
            {
            }
    
            public DbSet<TodoItem> TodoItems { get; set; } = null!;
        }
    }
    

Inscrire le contexte de base de données

Dans ASP.NET Core, les services tels que le contexte de base de données doivent être inscrits auprès du conteneur d’injection de dépendances. Le conteneur fournit le service aux contrôleurs.

Mettez à jour Program.cs avec le code suivant :

using Microsoft.EntityFrameworkCore;
using TodoApi.Models;


var builder = WebApplication.CreateBuilder(args);

// Add services to the container.

builder.Services.AddControllers();
builder.Services.AddDbContext<TodoContext>(opt =>
    opt.UseInMemoryDatabase("TodoList"));
//builder.Services.AddSwaggerGen(c =>
//{
//    c.SwaggerDoc("v1", new() { Title = "TodoApi", Version = "v1" });
//});

var app = builder.Build();

// Configure the HTTP request pipeline.
if (builder.Environment.IsDevelopment())
{
    app.UseDeveloperExceptionPage();
    //app.UseSwagger();
    //app.UseSwaggerUI(c => c.SwaggerEndpoint("/swagger/v1/swagger.json", "TodoApi v1"));
}

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

Le code précédent :

  • Supprime les appels Swagger.
  • Supprime les directives inutilisées using .
  • Ajoute le contexte de base de données au conteneur d’injection de dépendances.
  • Spécifie que le contexte de base de données utilise une base de données en mémoire.

Générer automatiquement des modèles pour un contrôleur

  • Cliquez avec le bouton droit sur le dossier Contrôleurs.

  • Sélectionnez AddNew>Scaffolded Item.

  • Sélectionnez Contrôleur d’API avec actions, utilisant Entity Framework, puis Ajouter.

  • Dans la boîte de dialogue Contrôleur d’API avec actions, utilisant Entity Framework :

    • Sélectionnez TodoItem (TodoApi.Models) dans la classe Model.
    • Sélectionnez TodoContext (TodoApi.Models) dans la classe de contexte de données.
    • Sélectionnez Ajouter.

    Si l’opération de génération échoue, sélectionnez Ajouter pour essayer de créer une seconde fois.

Le code généré :

  • Marque la classe avec l’attribut [ApiController] . Cet attribut indique que le contrôleur répond aux requêtes de l’API web. Pour plus d’informations sur les comportements spécifiques activés par l’attribut, consultez Créer des API web avec ASP.NET Core.
  • Utilise l’injection de dépendances pour injecter le contexte de base de données (TodoContext) dans le contrôleur. Le contexte de base de données est utilisé dans chacune des méthodes la CRUD du contrôleur.

Modèles ASP.NET Core pour :

  • Les contrôleurs avec vues sont inclus [action] dans le modèle de routage.
  • Les contrôleurs d’API n’incluent [action] pas dans le modèle d’itinéraire.

Lorsque le [action] jeton n’est pas dans le modèle de routage, le nom de l’action est exclu de l’itinéraire. Autrement dit, le nom de la méthode associée de l’action n’est pas utilisé dans l’itinéraire correspondant.

Mettre à jour la méthode de création PostTodoItem

Mettez à jour l’instruction return dans le PostTodoItem pour utiliser l’opérateur nameof :

[HttpPost]
public async Task<ActionResult<TodoItem>> PostTodoItem(TodoItem todoItem)
{
    _context.TodoItems.Add(todoItem);
    await _context.SaveChangesAsync();

    //return CreatedAtAction("GetTodoItem", new { id = todoItem.Id }, todoItem);
    return CreatedAtAction(nameof(GetTodoItem), new { id = todoItem.Id }, todoItem);
}

Le code précédent est une méthode HTTP POST, comme indiqué par l’attribut [HttpPost] . La méthode obtient la valeur de la tâche dans le corps de la requête HTTP.

Pour plus d’informations, consultez Routage par attributs avec des attributs Http[Verbe].

La méthode CreatedAtAction :

  • Retourne un code d’état HTTP 201 en cas de réussite. HTTP 201 est la réponse standard d’une méthode HTTP POST qui crée une ressource sur le serveur.
  • Ajoute un en-tête Location à la réponse. L’en-tête Location spécifie l’URI de l’élément d’action qui vient d’être créé. Pour plus d’informations, consultez la section 10.2.2 201 Created.
  • Fait référence à l’action GetTodoItem pour créer l’URI Location de l’en-tête. Le mot clé nameof C# est utilisé pour éviter de coder en dur le nom de l’action dans l’appel CreatedAtAction.

Installer http-repl

Ce didacticiel utilise http-repl pour tester l’API web.

  • À une invite de commandes, exécutez la commande suivante :

    dotnet tool install -g Microsoft.dotnet-httprepl
    
  • Si le SDK ou le runtime .NET 6.0 n’est pas installé, installez le runtime .NET 6.0.

Tester PostTodoItem

  • Appuyez sur Ctrl+F5 pour exécuter l’application.

  • Ouvrez une nouvelle fenêtre de terminal et exécutez les commandes suivantes. Si votre application utilise un autre numéro de port, remplacez 5001 dans la commande httprepl par votre numéro de port.

    httprepl https://localhost:5001/api/todoitems
    post -h Content-Type=application/json -c "{"name":"walk dog","isComplete":true}"
    

    Voici un exemple de sortie de la commande :

    HTTP/1.1 201 Created
    Content-Type: application/json; charset=utf-8
    Date: Tue, 07 Sep 2021 20:39:47 GMT
    Location: https://localhost:5001/api/TodoItems/1
    Server: Kestrel
    Transfer-Encoding: chunked
    
    {
      "id": 1,
      "name": "walk dog",
      "isComplete": true
    }
    

Tester l’URI de l’en-tête d’emplacement

Pour tester l’en-tête d’emplacement, copiez et collez-le dans une commande httprepl get .

L’exemple suivant suppose que vous êtes toujours dans une session httprepl. Si vous avez terminé la session httprepl précédente, remplacez-la connecthttprepl par les commandes suivantes :

connect https://localhost:5001/api/todoitems/1
get

Voici un exemple de sortie de la commande :

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: Tue, 07 Sep 2021 20:48:10 GMT
Server: Kestrel
Transfer-Encoding: chunked

{
  "id": 1,
  "name": "walk dog",
  "isComplete": true
}

Examiner les méthodes GET

Deux points de terminaison GET sont implémentés :

  • GET /api/todoitems
  • GET /api/todoitems/{id}

Vous venez de voir un exemple de la /api/todoitems/{id} route. Testez l’itinéraire /api/todoitems :

connect https://localhost:5001/api/todoitems
get

Voici un exemple de sortie de la commande :

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: Tue, 07 Sep 2021 20:59:21 GMT
Server: Kestrel
Transfer-Encoding: chunked

[
  {
    "id": 1,
    "name": "walk dog",
    "isComplete": true
  }
]

Cette fois, le JSON retourné est un tableau d’un élément.

Cette application utilise une base de données en mémoire. Si l’application est arrêtée et démarrée, la requête GET précédente ne retourne aucune donnée. Si aucune donnée n’est retournée, publiez (POST) les données dans l’application.

Routage et chemins d’URL

L’attribut [HttpGet] désigne une méthode qui répond à une requête HTTP GET. Le chemin d’URL pour chaque méthode est construit comme suit :

  • Partez de la chaîne de modèle dans l’attribut Route du contrôleur :

    [Route("api/[controller]")]
    [ApiController]
    public class TodoItemsController : ControllerBase
    
  • Remplacez [controller] par le nom du contrôleur qui, par convention, est le nom de la classe du contrôleur sans le suffixe « Controller ». Pour cet exemple, le nom de la classe du contrôleur étant TodoItemsController, le nom du contrôleur est « TodoItems ». Le routage d’ASP.NET Core ne respecte pas la casse.

  • Si l’attribut [HttpGet] a un modèle de route (par exemple, [HttpGet("products")]), ajoutez-le au chemin. Cet exemple n’utilise pas de modèle. Pour plus d’informations, consultez Routage par attributs avec des attributs Http[Verbe].

Dans la méthode GetTodoItem suivante, "{id}" est une variable d’espace réservé pour l’identificateur unique de la tâche. Lorsqu’elle GetTodoItem est appelée, la valeur de "{id}" l’URL est fournie à la méthode dans son id paramètre.

[HttpGet("{id}")]
public async Task<ActionResult<TodoItem>> GetTodoItem(long id)
{
    var todoItem = await _context.TodoItems.FindAsync(id);

    if (todoItem == null)
    {
        return NotFound();
    }

    return todoItem;
}

Valeurs de retour

Le type de retour des méthodes et GetTodoItem le GetTodoItemstype ActionResultT<.> ASP.NET Core sérialise automatiquement l’objet en JSON et écrit le JSON dans le corps du message de réponse. Le code de réponse de ce type de retour est 200 OK, en supposant qu’il n’existe aucune exception non gérée. Les exceptions non gérées sont converties en erreurs 5xx.

Les types de retour ActionResult peuvent représenter une large plage de codes d’état HTTP. Par exemple, GetTodoItem peut retourner deux valeurs d’état différentes :

  • Si aucun élément ne correspond à l’ID demandé, la méthode retourne un code d’erreur d’étatNotFound 404.
  • Sinon, la méthode retourne 200 avec un corps de réponse JSON. Le retour de item entraîne une réponse HTTP 200.

Méthode PutTodoItem

Examinez la méthode PutTodoItem :

[HttpPut("{id}")]
public async Task<IActionResult> PutTodoItem(long id, TodoItem todoItem)
{
    if (id != todoItem.Id)
    {
        return BadRequest();
    }

    _context.Entry(todoItem).State = EntityState.Modified;

    try
    {
        await _context.SaveChangesAsync();
    }
    catch (DbUpdateConcurrencyException)
    {
        if (!TodoItemExists(id))
        {
            return NotFound();
        }
        else
        {
            throw;
        }
    }

    return NoContent();
}

PutTodoItem est similaire à PostTodoItem, à la différence près qu’il utilise HTTP PUT. La réponse est 204 (aucun contenu). D’après la spécification HTTP, une requête PUT nécessite que le client envoie toute l’entité mise à jour, et pas seulement les changements. Pour prendre en charge les mises à jour partielles, utilisez HTTP PATCH.

Si vous recevez une erreur d’appel PutTodoItem dans la section suivante, appelez GET pour vous assurer qu’il existe un élément dans la base de données.

Tester la méthode PutTodoItem

Cet exemple utilise une base de données en mémoire qui doit être initialisée chaque fois que l’application est démarrée. La base de données doit contenir un élément avant que vous ne passiez un appel PUT. Appelez GET pour vous assurer qu’il existe un élément dans la base de données avant d’effectuer un appel PUT.

Mettez à jour l’élément de tâche qui a l’ID = 1 et définissez son nom sur "feed fish":

connect https://localhost:5001/api/todoitems/1
put -h Content-Type=application/json -c "{"id":1,"name":"feed fish","isComplete":true}"

Voici un exemple de sortie de la commande :

HTTP/1.1 204 No Content
Date: Tue, 07 Sep 2021 21:20:47 GMT
Server: Kestrel

Méthode DeleteTodoItem

Examinez la méthode DeleteTodoItem :

[HttpDelete("{id}")]
public async Task<IActionResult> DeleteTodoItem(long id)
{
    var todoItem = await _context.TodoItems.FindAsync(id);
    if (todoItem == null)
    {
        return NotFound();
    }

    _context.TodoItems.Remove(todoItem);
    await _context.SaveChangesAsync();

    return NoContent();
}

Tester la méthode DeleteTodoItem

Supprimez l’élément de tâche qui a l’ID = 1 :

connect https://localhost:5001/api/todoitems/1
delete

Voici un exemple de sortie de la commande :

HTTP/1.1 204 No Content
Date: Tue, 07 Sep 2021 21:43:00 GMT
Server: Kestrel

Empêcher la sur-publication

Actuellement, l’exemple d’application expose l’objet entier TodoItem . Les applications de production limitent généralement les données entrées et retournées à l’aide d’un sous-ensemble du modèle. Il existe plusieurs raisons pour lesquelles cela est dû, et la sécurité est une raison majeure. Le sous-ensemble d’un modèle est généralement appelé modèle de transfert de données (DTO), modèle d’entrée ou modèle de vue. DTO est utilisé dans ce didacticiel.

Un DTO peut être utilisé pour :

  • Empêcher la sur-publication.
  • Masquer les propriétés que les clients ne sont pas censés afficher.
  • Omettez certaines propriétés pour réduire la taille de la charge utile.
  • Aplatir les graphiques d’objets qui contiennent des objets imbriqués. Les graphiques d’objets aplatis peuvent être plus pratiques pour les clients.

Pour illustrer l’approche DTO, mettez à jour la TodoItem classe pour inclure un champ secret :

namespace TodoApi.Models
{
    public class TodoItem
    {
        public long Id { get; set; }
        public string? Name { get; set; }
        public bool IsComplete { get; set; }
        public string? Secret { get; set; }
    }
}

Le champ secret doit être masqué dans cette application, mais une application administrative peut choisir de l’exposer.

Vérifiez que vous pouvez publier et obtenir le champ secret.

Créez un modèle DTO :

namespace TodoApi.Models
{
    public class TodoItemDTO
    {
        public long Id { get; set; }
        public string? Name { get; set; }
        public bool IsComplete { get; set; }
    }
}

Mettez à jour l’option TodoItemsController à utiliser TodoItemDTO:

using Microsoft.AspNetCore.Mvc;
using Microsoft.EntityFrameworkCore;
using TodoApi.Models;

namespace TodoApi.Controllers
{
    [Route("api/[controller]")]
    [ApiController]
    public class TodoItemsController : ControllerBase
    {
        private readonly TodoContext _context;

        public TodoItemsController(TodoContext context)
        {
            _context = context;
        }

        // GET: api/TodoItems
        [HttpGet]
        public async Task<ActionResult<IEnumerable<TodoItemDTO>>> GetTodoItems()
        {
            return await _context.TodoItems
                .Select(x => ItemToDTO(x))
                .ToListAsync();
        }

        // GET: api/TodoItems/5
        [HttpGet("{id}")]
        public async Task<ActionResult<TodoItemDTO>> GetTodoItem(long id)
        {
            var todoItem = await _context.TodoItems.FindAsync(id);

            if (todoItem == null)
            {
                return NotFound();
            }

            return ItemToDTO(todoItem);
        }
        // PUT: api/TodoItems/5
        // To protect from overposting attacks, see https://go.microsoft.com/fwlink/?linkid=2123754
        [HttpPut("{id}")]
        public async Task<IActionResult> UpdateTodoItem(long id, TodoItemDTO todoItemDTO)
        {
            if (id != todoItemDTO.Id)
            {
                return BadRequest();
            }

            var todoItem = await _context.TodoItems.FindAsync(id);
            if (todoItem == null)
            {
                return NotFound();
            }

            todoItem.Name = todoItemDTO.Name;
            todoItem.IsComplete = todoItemDTO.IsComplete;

            try
            {
                await _context.SaveChangesAsync();
            }
            catch (DbUpdateConcurrencyException) when (!TodoItemExists(id))
            {
                return NotFound();
            }

            return NoContent();
        }
        // POST: api/TodoItems
        // To protect from overposting attacks, see https://go.microsoft.com/fwlink/?linkid=2123754
        [HttpPost]
        public async Task<ActionResult<TodoItemDTO>> CreateTodoItem(TodoItemDTO todoItemDTO)
        {
            var todoItem = new TodoItem
            {
                IsComplete = todoItemDTO.IsComplete,
                Name = todoItemDTO.Name
            };

            _context.TodoItems.Add(todoItem);
            await _context.SaveChangesAsync();

            return CreatedAtAction(
                nameof(GetTodoItem),
                new { id = todoItem.Id },
                ItemToDTO(todoItem));
        }

        // DELETE: api/TodoItems/5
        [HttpDelete("{id}")]
        public async Task<IActionResult> DeleteTodoItem(long id)
        {
            var todoItem = await _context.TodoItems.FindAsync(id);

            if (todoItem == null)
            {
                return NotFound();
            }

            _context.TodoItems.Remove(todoItem);
            await _context.SaveChangesAsync();

            return NoContent();
        }

        private bool TodoItemExists(long id)
        {
            return _context.TodoItems.Any(e => e.Id == id);
        }

        private static TodoItemDTO ItemToDTO(TodoItem todoItem) =>
            new TodoItemDTO
            {
                Id = todoItem.Id,
                Name = todoItem.Name,
                IsComplete = todoItem.IsComplete
            };
    }
}

Vérifiez que vous ne pouvez pas publier ou obtenir le champ secret.

Appelez l’API web avec JavaScript

Consultez le tutoriel : Appeler une API web ASP.NET Core avec JavaScript.

Dans ce tutoriel, vous allez apprendre à :

  • Créer un projet d’API web.
  • Ajouter une classe de modèle et un contexte de base de données.
  • Générer automatiquement des modèles pour un contrôleur avec des méthodes CRUD.
  • Configurer le routage, les chemins d’URL et les valeurs de retour.
  • Appeler l’API web avec Postman

À la fin, vous disposez d’une API web qui peut gérer des tâches stockées dans une base de données.

Vue d’ensemble

Ce didacticiel crée l’API suivante :

API Description Corps de la demande Response body
GET /api/todoitems Obtenir toutes les tâches None Tableau de tâches
GET /api/todoitems/{id} Obtenir un élément par ID None Tâche
POST /api/todoitems Ajouter un nouvel élément Tâche Tâche
PUT /api/todoitems/{id} Mettre à jour un élément existant Tâche None
DELETE /api/todoitems/{id}     Supprimer un élément None None

Le diagramme suivant illustre la conception de l’application.

The client is represented by a box on the left. It submits a request and receives a response from the application, a box drawn on the right. Within the application box, three boxes represent the controller, the model, and the data access layer. The request comes into the application's controller, and read/write operations occur between the controller and the data access layer. The model is serialized and returned to the client in the response.

Prérequis

Créer un projet web

  • Dans le menu Fichier, sélectionnez Nouveau>Projet.
  • Sélectionnez le modèle d’API web ASP.NET Core, puis cliquez sur Suivant.
  • Nommez le projet TodoApi et cliquez sur Créer.
  • Dans la boîte de dialogue Créer une application web ASP.NET Core, vérifiez que .NET Core et ASP.NET Core 5.0 sont sélectionnés. Sélectionnez le modèle API et cliquez sur Créer.

VS new project dialog

Notes

Pour obtenir des conseils sur l’ajout de packages à des applications .NET, consultez les articles sous Installer et gérer des packages dans le flux de travail consommation des packages (NuGet documentation). Confirmez les versions correctes du package sur NuGet.org.

Tester le projet

Le modèle de projet crée une WeatherForecast API avec prise en charge de Swagger.

Appuyez sur Ctrl+F5 pour exécuter sans le débogueur.

Visual Studio affiche la boîte de dialogue suivante lorsqu’un projet n’est pas encore configuré pour utiliser SSL :

This project is configured to use SSL. To avoid SSL warnings in the browser you can choose to trust the self-signed certificate that IIS Express has generated. Would you like to trust the IIS Express SSL certificate?

Sélectionnez Oui si vous faites confiance au certificat SSL d’IIS Express.

La boîte de dialogue suivante s’affiche :

Security warning dialog

Sélectionnez Oui si vous acceptez d’approuver le certificat de développement.

Pour plus d’informations sur l’approbation du navigateur Firefox, consultez Firefox SEC_ERROR_INADEQUATE_KEY_USAGE erreur de certificat.

Visual Studio lance :

  • Serveur web IIS Express.
  • Le navigateur par défaut et accède à https://localhost:<port>/swagger/index.html, où <port> il s’agit d’un numéro de port choisi de manière aléatoire.

La page /swagger/index.html Swagger s’affiche. Sélectionnez GETTry>itoutExecute>. La page affiche :

  • Commande Curl pour tester l’API WeatherForecast.
  • URL de test de l’API WeatherForecast.
  • Code de réponse, corps et en-têtes.
  • Zone de liste déroulante avec des types multimédias et l’exemple de valeur et de schéma.

Si la page Swagger n’apparaît pas, consultez ce problème GitHub.

Swagger est utilisé pour générer de la documentation et des pages d’aide utiles pour les API web. Ce tutoriel se concentre sur la création d’une API web. Pour plus d’informations sur Swagger, consultez ASP.NET Core documentation sur l’API web avec Swagger / OpenAPI.

Copiez et collez l’URL de la requête dans le navigateur : https://localhost:<port>/weatherforecast

Un code JSON similaire au suivant est retourné :

[
    {
        "date": "2019-07-16T19:04:05.7257911-06:00",
        "temperatureC": 52,
        "temperatureF": 125,
        "summary": "Mild"
    },
    {
        "date": "2019-07-17T19:04:05.7258461-06:00",
        "temperatureC": 36,
        "temperatureF": 96,
        "summary": "Warm"
    },
    {
        "date": "2019-07-18T19:04:05.7258467-06:00",
        "temperatureC": 39,
        "temperatureF": 102,
        "summary": "Cool"
    },
    {
        "date": "2019-07-19T19:04:05.7258471-06:00",
        "temperatureC": 10,
        "temperatureF": 49,
        "summary": "Bracing"
    },
    {
        "date": "2019-07-20T19:04:05.7258474-06:00",
        "temperatureC": -1,
        "temperatureF": 31,
        "summary": "Chilly"
    }
]

Mettre à jour le launchUrl

Dans Properties\launchSettings.json, mettez à "api/todoitems"jour launchUrl à partir de "swagger" :

"launchUrl": "api/todoitems",

Étant donné que Swagger est supprimé, le balisage précédent modifie l’URL lancée vers la méthode GET du contrôleur ajoutée dans les sections suivantes.

Ajouter une classe de modèle

Un modèle est un ensemble de classes qui représentent les données gérées par l’application. Le modèle pour cette application est une classe TodoItem unique.

  • Dans l’Explorateur de solutions, cliquez avec le bouton droit sur le projet. Sélectionnez AddNew>Folder. Nommez le dossier Models.

  • Cliquez avec le bouton droit sur le Models dossier et sélectionnez AddClass>. Nommez la classe TodoItem et sélectionnez sur Ajouter.

  • Remplacez le code de modèle par les éléments suivants :

namespace TodoApi.Models
{
    public class TodoItem
    {
        public long Id { get; set; }
        public string Name { get; set; }
        public bool IsComplete { get; set; }
    }
}

La propriété Id fonctionne comme la clé unique dans une base de données relationnelle.

Les classes de modèle peuvent aller n’importe où dans le projet, mais le Models dossier est utilisé par convention.

Ajouter un contexte de base de données

Le contexte de base de données est la classe principale qui coordonne les fonctionnalités d’Entity Framework pour un modèle de données. Cette classe est créée en dérivant de la classe Microsoft.EntityFrameworkCore.DbContext.

Ajouter des packages NuGet

  • Dans le menu Outils, sélectionnez NuGet Gestionnaire de package Gérer les > packages NuGet pour la solution.
  • Sélectionnez l’onglet Parcourir , puis entrez Microsoft.EntityFrameworkCore.InMemory dans la zone de recherche.
  • Sélectionnez Microsoft.EntityFrameworkCore.InMemory dans le volet gauche.
  • Cochez la case Project dans le volet droit, puis sélectionnez Installer.

NuGet Package Manager

Ajouter le contexte de base de données TodoContext

  • Cliquez avec le bouton droit sur le Models dossier et sélectionnez AddClass>. Nommez la classe TodoContext et cliquez sur Ajouter.
  • Entrez le code suivant :

    using Microsoft.EntityFrameworkCore;
    
    namespace TodoApi.Models
    {
        public class TodoContext : DbContext
        {
            public TodoContext(DbContextOptions<TodoContext> options)
                : base(options)
            {
            }
    
            public DbSet<TodoItem> TodoItems { get; set; }
        }
    }
    

Inscrire le contexte de base de données

Dans ASP.NET Core, les services tels que le contexte de base de données doivent être inscrits auprès du conteneur d’injection de dépendances. Le conteneur fournit le service aux contrôleurs.

Mettez à jour Startup.cs avec le code suivant :

// Unused usings removed
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.EntityFrameworkCore;
using TodoApi.Models;

namespace TodoApi
{
    public class Startup
    {
        public Startup(IConfiguration configuration)
        {
            Configuration = configuration;
        }

        public IConfiguration Configuration { get; }

        public void ConfigureServices(IServiceCollection services)
        {
            services.AddControllers();

            services.AddDbContext<TodoContext>(opt =>
                                               opt.UseInMemoryDatabase("TodoList"));
            //services.AddSwaggerGen(c =>
            //{
            //    c.SwaggerDoc("v1", new OpenApiInfo { Title = "TodoApi", Version = "v1" });
            //});
        }

        public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
        {
            if (env.IsDevelopment())
            {
                app.UseDeveloperExceptionPage();
                //app.UseSwagger();
                //app.UseSwaggerUI(c => c.SwaggerEndpoint("/swagger/v1/swagger.json", "TodoApi v1"));
            }

            app.UseHttpsRedirection();
            app.UseRouting();

            app.UseAuthorization();

            app.UseEndpoints(endpoints =>
            {
                endpoints.MapControllers();
            });
        }
    }
}

Le code précédent :

  • Supprime les appels Swagger.
  • Supprime les déclarations using inutilisées.
  • Ajoute le contexte de base de données au conteneur d’injection de dépendances.
  • Spécifie que le contexte de base de données utilise une base de données en mémoire.

Générer automatiquement des modèles pour un contrôleur

  • Cliquez avec le bouton droit sur le dossier Contrôleurs.

  • Sélectionnez AddNew>Scaffolded Item.

  • Sélectionnez Contrôleur d’API avec actions, utilisant Entity Framework, puis Ajouter.

  • Dans la boîte de dialogue Contrôleur d’API avec actions, utilisant Entity Framework :

    • Sélectionnez TodoItem (TodoApi.Models) dans la classe Model.
    • Sélectionnez TodoContext (TodoApi.Models) dans la classe de contexte de données.
    • Sélectionnez Ajouter.

Le code généré :

  • Marque la classe avec l’attribut [ApiController] . Cet attribut indique que le contrôleur répond aux requêtes de l’API web. Pour plus d’informations sur les comportements spécifiques activés par l’attribut, consultez Créer des API web avec ASP.NET Core.
  • Utilise l’injection de dépendances pour injecter le contexte de base de données (TodoContext) dans le contrôleur. Le contexte de base de données est utilisé dans chacune des méthodes la CRUD du contrôleur.

Modèles ASP.NET Core pour :

  • Les contrôleurs avec vues sont inclus [action] dans le modèle de routage.
  • Les contrôleurs d’API n’incluent [action] pas dans le modèle d’itinéraire.

Lorsque le [action] jeton n’est pas dans le modèle de routage, le nom de l’action est exclu de l’itinéraire. Autrement dit, le nom de la méthode associée de l’action n’est pas utilisé dans l’itinéraire correspondant.

Mettre à jour la méthode de création PostTodoItem

Mettez à jour l’instruction return dans le PostTodoItem pour utiliser l’opérateur nameof :

// POST: api/TodoItems
[HttpPost]
public async Task<ActionResult<TodoItem>> PostTodoItem(TodoItem todoItem)
{
    _context.TodoItems.Add(todoItem);
    await _context.SaveChangesAsync();

    //return CreatedAtAction("GetTodoItem", new { id = todoItem.Id }, todoItem);
    return CreatedAtAction(nameof(GetTodoItem), new { id = todoItem.Id }, todoItem);
}

Le code précédent est une méthode HTTP POST, comme indiqué par l’attribut [HttpPost] . La méthode obtient la valeur de la tâche dans le corps de la requête HTTP.

Pour plus d’informations, consultez Routage par attributs avec des attributs Http[Verbe].

La méthode CreatedAtAction :

  • Retourne un code d’état HTTP 201 en cas de réussite. HTTP 201 est la réponse standard d’une méthode HTTP POST qui crée une ressource sur le serveur.
  • Ajoute un en-tête Location à la réponse. L’en-tête Location spécifie l’URI de l’élément d’action qui vient d’être créé. Pour plus d’informations, consultez la section 10.2.2 201 Created.
  • Fait référence à l’action GetTodoItem pour créer l’URI Location de l’en-tête. Le mot clé nameof C# est utilisé pour éviter de coder en dur le nom de l’action dans l’appel CreatedAtAction.

Installer Postman

Ce tutoriel utilise Postman pour tester l’API web.

  • Installer Postman
  • Démarrez l’application web.
  • Démarrez Postman.
  • Désactivez la vérification du certificat SSL :
    • Postman pour Windows : sélectionnez Fichier>Paramètres (onglet Général), désactivez la vérification du certificat SSL.
    • Postman pour macOS : Sélectionnez Postman>Paramètres (onglet Général), désactivez la vérification du certificat SSL.

      Avertissement

      Réactivez la vérification du certificat SSL après avoir testé le contrôleur.

Tester PostTodoItem avec Postman

  • Créez une requête.

  • Affectez POST à la méthode HTTP.

  • Définissez l’URI sur https://localhost:<port>/api/todoitems. Par exemple : https://localhost:5001/api/todoitems.

  • Sélectionnez l’onglet Corps .

  • Sélectionnez la case d’option raw (données brutes).

  • Définissez le type sur JSON (application/json).

  • Dans le corps de la demande, entrez la syntaxe JSON d’une tâche :

    {
      "name":"walk dog",
      "isComplete":true
    }
    
  • Sélectionnez Envoyer.

    Postman with create request

Tester l’URI de l’en-tête d’emplacement

L’URI d’en-tête d’emplacement peut être testé dans le navigateur. Copiez et collez l’URI d’en-tête d’emplacement dans le navigateur.

Pour tester dans Postman :

  • Sélectionnez l’onglet Headers (En-têtes) dans le volet Response (Réponse).

  • Copiez la valeur d’en-tête Location (Emplacement) :

    Headers tab of the Postman console

  • Affectez GET à la méthode HTTP.

  • Définissez l’URI sur https://localhost:<port>/api/todoitems/1. Par exemple : https://localhost:5001/api/todoitems/1.

  • Sélectionnez Envoyer.

Examiner les méthodes GET

Deux points de terminaison GET sont implémentés :

  • GET /api/todoitems
  • GET /api/todoitems/{id}

Testez l’application en appelant les deux points de terminaison à partir d’un navigateur ou de Postman. Par exemple :

  • https://localhost:5001/api/todoitems
  • https://localhost:5001/api/todoitems/1

Une réponse semblable à la suivante est produite par l’appel à GetTodoItems :

[
  {
    "id": 1,
    "name": "Item1",
    "isComplete": false
  }
]

Tester Get avec Postman

  • Créez une requête.
  • Définissez la méthode HTTP sur GET.
  • Définissez l’URI de requête sur https://localhost:<port>/api/todoitems. Par exemple : https://localhost:5001/api/todoitems.
  • Définissez l’affichage à deux volets dans Postman.
  • Sélectionnez Envoyer.

Cette application utilise une base de données en mémoire. Si l’application est arrêtée et démarrée, la requête GET précédente ne retourne aucune donnée. Si aucune donnée n’est retournée, publiez (POST) les données dans l’application.

Routage et chemins d’URL

L’attribut [HttpGet] désigne une méthode qui répond à une requête HTTP GET. Le chemin d’URL pour chaque méthode est construit comme suit :

  • Partez de la chaîne de modèle dans l’attribut Route du contrôleur :

    [Route("api/[controller]")]
    [ApiController]
    public class TodoItemsController : ControllerBase
    {
        private readonly TodoContext _context;
    
        public TodoItemsController(TodoContext context)
        {
            _context = context;
        }
    
  • Remplacez [controller] par le nom du contrôleur qui, par convention, est le nom de la classe du contrôleur sans le suffixe « Controller ». Pour cet exemple, le nom de la classe du contrôleur étant TodoItemsController, le nom du contrôleur est « TodoItems ». Le routage d’ASP.NET Core ne respecte pas la casse.

  • Si l’attribut [HttpGet] a un modèle de route (par exemple, [HttpGet("products")]), ajoutez-le au chemin. Cet exemple n’utilise pas de modèle. Pour plus d’informations, consultez Routage par attributs avec des attributs Http[Verbe].

Dans la méthode GetTodoItem suivante, "{id}" est une variable d’espace réservé pour l’identificateur unique de la tâche. Quand GetTodoItem elle est appelée, la valeur de "{id}" l’URL est fournie à la méthode dans son id paramètre.

// GET: api/TodoItems/5
[HttpGet("{id}")]
public async Task<ActionResult<TodoItem>> GetTodoItem(long id)
{
    var todoItem = await _context.TodoItems.FindAsync(id);

    if (todoItem == null)
    {
        return NotFound();
    }

    return todoItem;
}

Valeurs de retour

Le type de retour des méthodes et GetTodoItem le GetTodoItemstype ActionResultT<.> ASP.NET Core sérialise automatiquement l’objet en JSON et écrit le JSON dans le corps du message de réponse. Le code de réponse de ce type de retour est 200 OK, en supposant qu’il n’existe aucune exception non gérée. Les exceptions non gérées sont converties en erreurs 5xx.

Les types de retour ActionResult peuvent représenter une large plage de codes d’état HTTP. Par exemple, GetTodoItem peut retourner deux valeurs d’état différentes :

  • Si aucun élément ne correspond à l’ID demandé, la méthode retourne un code d’erreur d’étatNotFound 404.
  • Sinon, la méthode retourne 200 avec un corps de réponse JSON. Le retour de item entraîne une réponse HTTP 200.

Méthode PutTodoItem

Examinez la méthode PutTodoItem :

// PUT: api/TodoItems/5
[HttpPut("{id}")]
public async Task<IActionResult> PutTodoItem(long id, TodoItem todoItem)
{
    if (id != todoItem.Id)
    {
        return BadRequest();
    }

    _context.Entry(todoItem).State = EntityState.Modified;

    try
    {
        await _context.SaveChangesAsync();
    }
    catch (DbUpdateConcurrencyException)
    {
        if (!TodoItemExists(id))
        {
            return NotFound();
        }
        else
        {
            throw;
        }
    }

    return NoContent();
}

PutTodoItem est similaire à PostTodoItem, à la différence près qu’il utilise HTTP PUT. La réponse est 204 (aucun contenu). D’après la spécification HTTP, une requête PUT nécessite que le client envoie toute l’entité mise à jour, et pas seulement les changements. Pour prendre en charge les mises à jour partielles, utilisez HTTP PATCH.

Si vous obtenez une erreur en appelant PutTodoItem, appelez GET pour vérifier que la base de données contient un élément.

Tester la méthode PutTodoItem

Cet exemple utilise une base de données en mémoire qui doit être initialisée chaque fois que l’application est démarrée. La base de données doit contenir un élément avant que vous ne passiez un appel PUT. Appelez GET pour vous assurer qu’il existe un élément dans la base de données avant d’effectuer un appel PUT.

Mettez à jour l’élément à faire qui a l’ID = 1 et définissez son nom sur "feed fish":

  {
    "Id":1,
    "name":"feed fish",
    "isComplete":true
  }

L’image suivante montre la mise à jour Postman :

Postman console showing 204 (No Content) response

Méthode DeleteTodoItem

Examinez la méthode DeleteTodoItem :

// DELETE: api/TodoItems/5
[HttpDelete("{id}")]
public async Task<IActionResult> DeleteTodoItem(long id)
{
    var todoItem = await _context.TodoItems.FindAsync(id);
    if (todoItem == null)
    {
        return NotFound();
    }

    _context.TodoItems.Remove(todoItem);
    await _context.SaveChangesAsync();

    return NoContent();
}

Tester la méthode DeleteTodoItem

Utilisez Postman pour supprimer une tâche :

  • Définissez la méthode sur DELETE.
  • Définissez l’URI de l’objet à supprimer (par exemple https://localhost:5001/api/todoitems/1).
  • Sélectionnez Envoyer.

Empêcher la sur-publication

Actuellement, l’exemple d’application expose l’objet entier TodoItem . Les applications de production limitent généralement les données entrées et retournées à l’aide d’un sous-ensemble du modèle. Il existe plusieurs raisons derrière cela et la sécurité est une principale. Le sous-ensemble d’un modèle est généralement appelé objet de transfert de données (DTO), modèle d’entrée ou modèle d’affichage. DTO est utilisé dans cet article.

Un DTO peut être utilisé pour :

  • Empêcher la sur-publication.
  • Masquer les propriétés que les clients ne sont pas censés afficher.
  • Omettez certaines propriétés pour réduire la taille de la charge utile.
  • Graphes d’objets aplatis qui contiennent des objets imbriqués. Les graphiques d’objets aplatis peuvent être plus pratiques pour les clients.

Pour illustrer l’approche DTO, mettez à jour la TodoItem classe pour inclure un champ secret :

namespace TodoApi.Models
{
    public class TodoItem
    {
        public long Id { get; set; }
        public string Name { get; set; }
        public bool IsComplete { get; set; }
        public string Secret { get; set; }
    }
}

Le champ secret doit être masqué de cette application, mais une application administrative peut choisir de l’exposer.

Vérifiez que vous pouvez publier et obtenir le champ secret.

Créez un modèle DTO :

public class TodoItemDTO
{
    public long Id { get; set; }
    public string Name { get; set; }
    public bool IsComplete { get; set; }
}

Mettez à jour l’utilisation TodoItemsControllerTodoItemDTO:

// GET: api/TodoItems
[HttpGet]
public async Task<ActionResult<IEnumerable<TodoItemDTO>>> GetTodoItems()
{
    return await _context.TodoItems
        .Select(x => ItemToDTO(x))
        .ToListAsync();
}

[HttpGet("{id}")]
public async Task<ActionResult<TodoItemDTO>> GetTodoItem(long id)
{
    var todoItem = await _context.TodoItems.FindAsync(id);

    if (todoItem == null)
    {
        return NotFound();
    }

    return ItemToDTO(todoItem);
}

[HttpPut("{id}")]
public async Task<IActionResult> UpdateTodoItem(long id, TodoItemDTO todoItemDTO)
{
    if (id != todoItemDTO.Id)
    {
        return BadRequest();
    }

    var todoItem = await _context.TodoItems.FindAsync(id);
    if (todoItem == null)
    {
        return NotFound();
    }

    todoItem.Name = todoItemDTO.Name;
    todoItem.IsComplete = todoItemDTO.IsComplete;

    try
    {
        await _context.SaveChangesAsync();
    }
    catch (DbUpdateConcurrencyException) when (!TodoItemExists(id))
    {
        return NotFound();
    }

    return NoContent();
}

[HttpPost]
public async Task<ActionResult<TodoItemDTO>> CreateTodoItem(TodoItemDTO todoItemDTO)
{
    var todoItem = new TodoItem
    {
        IsComplete = todoItemDTO.IsComplete,
        Name = todoItemDTO.Name
    };

    _context.TodoItems.Add(todoItem);
    await _context.SaveChangesAsync();

    return CreatedAtAction(
        nameof(GetTodoItem),
        new { id = todoItem.Id },
        ItemToDTO(todoItem));
}

[HttpDelete("{id}")]
public async Task<IActionResult> DeleteTodoItem(long id)
{
    var todoItem = await _context.TodoItems.FindAsync(id);

    if (todoItem == null)
    {
        return NotFound();
    }

    _context.TodoItems.Remove(todoItem);
    await _context.SaveChangesAsync();

    return NoContent();
}

private bool TodoItemExists(long id) =>
     _context.TodoItems.Any(e => e.Id == id);

private static TodoItemDTO ItemToDTO(TodoItem todoItem) =>
    new TodoItemDTO
    {
        Id = todoItem.Id,
        Name = todoItem.Name,
        IsComplete = todoItem.IsComplete
    };

Vérifiez que vous ne pouvez pas publier ou obtenir le champ secret.

Appelez l’API web avec JavaScript

Consultez le tutoriel : Appeler une API web ASP.NET Core avec JavaScript.

Dans ce tutoriel, vous allez apprendre à :

  • Créer un projet d’API web.
  • Ajouter une classe de modèle et un contexte de base de données.
  • Générer automatiquement des modèles pour un contrôleur avec des méthodes CRUD.
  • Configurer le routage, les chemins d’URL et les valeurs de retour.
  • Appeler l’API web avec Postman

À la fin, vous disposez d’une API web qui peut gérer des tâches stockées dans une base de données.

Vue d’ensemble

Ce didacticiel crée l’API suivante :

API Description Corps de la demande Response body
GET /api/todoitems Obtenir toutes les tâches None Tableau de tâches
GET /api/todoitems/{id} Obtenir un élément par ID None Tâche
POST /api/todoitems Ajouter un nouvel élément Tâche Tâche
PUT /api/todoitems/{id} Mettre à jour un élément existant Tâche None
DELETE /api/todoitems/{id}     Supprimer un élément None None

Le diagramme suivant illustre la conception de l’application.

The client is represented by a box on the left. It submits a request and receives a response from the application, a box drawn on the right. Within the application box, three boxes represent the controller, the model, and the data access layer. The request comes into the application's controller, and read/write operations occur between the controller and the data access layer. The model is serialized and returned to the client in the response.

Prérequis

Créer un projet web

  • Dans le menu Fichier, sélectionnez Nouveau>Projet.
  • Sélectionnez le modèle Application web ASP.NET Core et cliquez sur Suivant.
  • Nommez le projet TodoApi et cliquez sur Créer.
  • Dans la boîte de dialogue Créer une application web ASP.NET Core, vérifiez que .NET Core et ASP.NET Core 3.1 sont sélectionnés. Sélectionnez le modèle API et cliquez sur Créer.

VS new project dialog

Notes

Pour obtenir des conseils sur l’ajout de packages à des applications .NET, consultez les articles sous Installer et gérer des packages dans le flux de travail consommation des packages (NuGet documentation). Confirmez les versions correctes du package sur NuGet.org.

Tester l’API

Le modèle de projet crée une API WeatherForecast. Appelez la méthode Get à partir d’un navigateur pour tester l’application.

Appuyez sur Ctrl+F5 pour exécuter l’application. Visual Studio lance un navigateur et accède à https://localhost:<port>/weatherforecast, où <port> est un numéro de port choisi de manière aléatoire.

Si une boîte de dialogue apparaît vous demandant si vous devez approuver le certificat IIS Express, sélectionnez Oui. Dans la boîte de dialogue Avertissement de sécurité qui s’affiche ensuite, sélectionnez Oui.

Un code JSON similaire au suivant est retourné :

[
    {
        "date": "2019-07-16T19:04:05.7257911-06:00",
        "temperatureC": 52,
        "temperatureF": 125,
        "summary": "Mild"
    },
    {
        "date": "2019-07-17T19:04:05.7258461-06:00",
        "temperatureC": 36,
        "temperatureF": 96,
        "summary": "Warm"
    },
    {
        "date": "2019-07-18T19:04:05.7258467-06:00",
        "temperatureC": 39,
        "temperatureF": 102,
        "summary": "Cool"
    },
    {
        "date": "2019-07-19T19:04:05.7258471-06:00",
        "temperatureC": 10,
        "temperatureF": 49,
        "summary": "Bracing"
    },
    {
        "date": "2019-07-20T19:04:05.7258474-06:00",
        "temperatureC": -1,
        "temperatureF": 31,
        "summary": "Chilly"
    }
]

Ajouter une classe de modèle

Un modèle est un ensemble de classes qui représentent les données gérées par l’application. Le modèle pour cette application est une classe TodoItem unique.

  • Dans l’Explorateur de solutions, cliquez avec le bouton droit sur le projet. Sélectionnez AddNew>Folder. Nommez le dossier Models.

  • Cliquez avec le bouton droit sur le Models dossier et sélectionnez AddClass>. Nommez la classe TodoItem et sélectionnez sur Ajouter.

  • Remplacez le code du modèle par le code suivant :

public class TodoItem
{
    public long Id { get; set; }
    public string Name { get; set; }
    public bool IsComplete { get; set; }
}

La propriété Id fonctionne comme la clé unique dans une base de données relationnelle.

Les classes de modèle peuvent aller n’importe où dans le projet, mais le Models dossier est utilisé par convention.

Ajouter un contexte de base de données

Le contexte de base de données est la classe principale qui coordonne les fonctionnalités d’Entity Framework pour un modèle de données. Cette classe est créée en dérivant de la classe Microsoft.EntityFrameworkCore.DbContext.

Ajouter des packages NuGet

  • Dans le menu Outils, sélectionnez NuGet Gestionnaire de package Gérer les > packages NuGet pour la solution.
  • Sélectionnez l’onglet Parcourir , puis entrez Microsoft.EntityFrameworkCore.InMemory dans la zone de recherche.
  • Sélectionnez Microsoft.EntityFrameworkCore.InMemory dans le volet gauche.
  • Cochez la case Project dans le volet droit, puis sélectionnez Installer.

NuGet Package Manager

Ajouter le contexte de base de données TodoContext

  • Cliquez avec le bouton droit sur le Models dossier et sélectionnez AddClass>. Nommez la classe TodoContext et cliquez sur Ajouter.
  • Entrez le code suivant :

    using Microsoft.EntityFrameworkCore;
    
    namespace TodoApi.Models
    {
        public class TodoContext : DbContext
        {
            public TodoContext(DbContextOptions<TodoContext> options)
                : base(options)
            {
            }
    
            public DbSet<TodoItem> TodoItems { get; set; }
        }
    }
    

Inscrire le contexte de base de données

Dans ASP.NET Core, les services tels que le contexte de base de données doivent être inscrits auprès du conteneur d’injection de dépendances. Le conteneur fournit le service aux contrôleurs.

Mettez à jour Startup.cs avec le code mis en surbrillance suivant :

// Unused usings removed
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.EntityFrameworkCore;
using TodoApi.Models;

namespace TodoApi
{
    public class Startup
    {
        public Startup(IConfiguration configuration)
        {
            Configuration = configuration;
        }

        public IConfiguration Configuration { get; }

        public void ConfigureServices(IServiceCollection services)
        {
            services.AddDbContext<TodoContext>(opt =>
               opt.UseInMemoryDatabase("TodoList"));
            services.AddControllers();
        }

        public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
        {
            if (env.IsDevelopment())
            {
                app.UseDeveloperExceptionPage();
            }

            app.UseHttpsRedirection();

            app.UseRouting();

            app.UseAuthorization();

            app.UseEndpoints(endpoints =>
            {
                endpoints.MapControllers();
            });
        }
    }
}

Le code précédent :

  • Supprime les déclarations using inutilisées.
  • Ajoute le contexte de base de données au conteneur d’injection de dépendances.
  • Spécifie que le contexte de base de données utilise une base de données en mémoire.

Générer automatiquement des modèles pour un contrôleur

  • Cliquez avec le bouton droit sur le dossier Contrôleurs.

  • Sélectionnez AddNew>Scaffolded Item.

  • Sélectionnez Contrôleur d’API avec actions, utilisant Entity Framework, puis Ajouter.

  • Dans la boîte de dialogue Contrôleur d’API avec actions, utilisant Entity Framework :

    • Sélectionnez TodoItem (TodoApi.Models) dans la classe Model.
    • Sélectionnez TodoContext (TodoApi.Models) dans la classe de contexte de données.
    • Sélectionnez Ajouter.

Le code généré :

  • Marque la classe avec l’attribut [ApiController] . Cet attribut indique que le contrôleur répond aux requêtes de l’API web. Pour plus d’informations sur les comportements spécifiques activés par l’attribut, consultez Créer des API web avec ASP.NET Core.
  • Utilise l’injection de dépendances pour injecter le contexte de base de données (TodoContext) dans le contrôleur. Le contexte de base de données est utilisé dans chacune des méthodes la CRUD du contrôleur.

Modèles ASP.NET Core pour :

  • Les contrôleurs avec vues sont inclus [action] dans le modèle de routage.
  • Les contrôleurs d’API n’incluent [action] pas dans le modèle d’itinéraire.

Lorsque le [action] jeton n’est pas dans le modèle de routage, le nom de l’action est exclu de l’itinéraire. Autrement dit, le nom de la méthode associée de l’action n’est pas utilisé dans l’itinéraire correspondant.

Examiner la méthode de création de PostTodoItem

Remplacez l’instruction return dans PostTodoItem pour utiliser l’opérateur nameof :

// POST: api/TodoItems
[HttpPost]
public async Task<ActionResult<TodoItem>> PostTodoItem(TodoItem todoItem)
{
    _context.TodoItems.Add(todoItem);
    await _context.SaveChangesAsync();

    //return CreatedAtAction("GetTodoItem", new { id = todoItem.Id }, todoItem);
    return CreatedAtAction(nameof(GetTodoItem), new { id = todoItem.Id }, todoItem);
}

Le code précédent est une méthode HTTP POST, comme indiqué par l’attribut [HttpPost] . La méthode obtient la valeur de la tâche dans le corps de la requête HTTP.

Pour plus d’informations, consultez Routage par attributs avec des attributs Http[Verbe].

La méthode CreatedAtAction :

  • Retourne un code d’état HTTP 201 en cas de réussite. HTTP 201 est la réponse standard d’une méthode HTTP POST qui crée une ressource sur le serveur.
  • Ajoute un en-tête Location à la réponse. L’en-tête Location spécifie l’URI de l’élément d’action qui vient d’être créé. Pour plus d’informations, consultez la section 10.2.2 201 Created.
  • Fait référence à l’action GetTodoItem pour créer l’URI Location de l’en-tête. Le mot clé nameof C# est utilisé pour éviter de coder en dur le nom de l’action dans l’appel CreatedAtAction.

Installer Postman

Ce tutoriel utilise Postman pour tester l’API web.

  • Installer Postman
  • Démarrez l’application web.
  • Démarrez Postman.
  • Désactivez la vérification du certificat SSL :
    • Postman pour Windows : Postman pour Windows fichier>Paramètres (onglet Général), désactivez la vérification du certificat SSL.
    • Postman pour macOS : Postman pour Windows Postman>Paramètres (onglet Général), désactivez la vérification du certificat SSL.

      Avertissement

      Réactivez la vérification du certificat SSL après avoir testé le contrôleur.

Tester PostTodoItem avec Postman

  • Créez une requête.

  • Affectez POST à la méthode HTTP.

  • Définissez l’URI sur https://localhost:<port>/api/todoitems. Par exemple : https://localhost:5001/api/todoitems.

  • Sélectionnez l’onglet Corps .

  • Sélectionnez la case d’option raw (données brutes).

  • Définissez le type sur JSON (application/json).

  • Dans le corps de la demande, entrez la syntaxe JSON d’une tâche :

    {
      "name":"walk dog",
      "isComplete":true
    }
    
  • Sélectionnez Envoyer.

    Postman with create request

Tester l’URI d’en-tête d’emplacement avec Postman

  • Sélectionnez l’onglet Headers (En-têtes) dans le volet Response (Réponse).

  • Copiez la valeur d’en-tête Location (Emplacement) :

    Headers tab of the Postman console

  • Affectez GET à la méthode HTTP.

  • Définissez l’URI sur https://localhost:<port>/api/todoitems/1. Par exemple : https://localhost:5001/api/todoitems/1.

  • Sélectionnez Envoyer.

Examiner les méthodes GET

Ces méthodes implémentent deux points de terminaison GET :

  • GET /api/todoitems
  • GET /api/todoitems/{id}

Testez l’application en appelant les deux points de terminaison à partir d’un navigateur ou de Postman. Par exemple :

  • https://localhost:5001/api/todoitems
  • https://localhost:5001/api/todoitems/1

Une réponse semblable à la suivante est produite par l’appel à GetTodoItems :

[
  {
    "id": 1,
    "name": "Item1",
    "isComplete": false
  }
]

Tester Get avec Postman

  • Créez une requête.
  • Définissez la méthode HTTP sur GET.
  • Définissez l’URI de requête sur https://localhost:<port>/api/todoitems. Par exemple : https://localhost:5001/api/todoitems.
  • Définissez l’affichage à deux volets dans Postman.
  • Sélectionnez Envoyer.

Cette application utilise une base de données en mémoire. Si l’application est arrêtée et démarrée, la requête GET précédente ne retourne aucune donnée. Si aucune donnée n’est retournée, publiez (POST) les données dans l’application.

Routage et chemins d’URL

L’attribut [HttpGet] désigne une méthode qui répond à une requête HTTP GET. Le chemin d’URL pour chaque méthode est construit comme suit :

  • Partez de la chaîne de modèle dans l’attribut Route du contrôleur :

    [Route("api/[controller]")]
    [ApiController]
    public class TodoItemsController : ControllerBase
    {
        private readonly TodoContext _context;
    
        public TodoItemsController(TodoContext context)
        {
            _context = context;
        }
    
  • Remplacez [controller] par le nom du contrôleur qui, par convention, est le nom de la classe du contrôleur sans le suffixe « Controller ». Pour cet exemple, le nom de la classe du contrôleur étant TodoItemsController, le nom du contrôleur est « TodoItems ». Le routage d’ASP.NET Core ne respecte pas la casse.

  • Si l’attribut [HttpGet] a un modèle de route (par exemple, [HttpGet("products")]), ajoutez-le au chemin. Cet exemple n’utilise pas de modèle. Pour plus d’informations, consultez Routage par attributs avec des attributs Http[Verbe].

Dans la méthode GetTodoItem suivante, "{id}" est une variable d’espace réservé pour l’identificateur unique de la tâche. Quand GetTodoItem elle est appelée, la valeur de "{id}" l’URL est fournie à la méthode dans son id paramètre.

// GET: api/TodoItems/5
[HttpGet("{id}")]
public async Task<ActionResult<TodoItem>> GetTodoItem(long id)
{
    var todoItem = await _context.TodoItems.FindAsync(id);

    if (todoItem == null)
    {
        return NotFound();
    }

    return todoItem;
}

Valeurs de retour

Le type de retour des méthodes et GetTodoItem le GetTodoItemstype ActionResultT<.> ASP.NET Core sérialise automatiquement l’objet en JSON et écrit le JSON dans le corps du message de réponse. Le code de réponse pour ce type de retour est 200, en supposant qu’il n’existe pas d’exception non gérée. Les exceptions non gérées sont converties en erreurs 5xx.

Les types de retour ActionResult peuvent représenter une large plage de codes d’état HTTP. Par exemple, GetTodoItem peut retourner deux valeurs d’état différentes :

  • Si aucun élément ne correspond à l’ID demandé, la méthode retourne un code d’erreur 404 NotFound .
  • Sinon, la méthode retourne 200 avec un corps de réponse JSON. Le retour de item entraîne une réponse HTTP 200.

Méthode PutTodoItem

Examinez la méthode PutTodoItem :

// PUT: api/TodoItems/5
[HttpPut("{id}")]
public async Task<IActionResult> PutTodoItem(long id, TodoItem todoItem)
{
    if (id != todoItem.Id)
    {
        return BadRequest();
    }

    _context.Entry(todoItem).State = EntityState.Modified;

    try
    {
        await _context.SaveChangesAsync();
    }
    catch (DbUpdateConcurrencyException)
    {
        if (!TodoItemExists(id))
        {
            return NotFound();
        }
        else
        {
            throw;
        }
    }

    return NoContent();
}

PutTodoItem est similaire à PostTodoItem, à la différence près qu’il utilise HTTP PUT. La réponse est 204 (aucun contenu). D’après la spécification HTTP, une requête PUT nécessite que le client envoie toute l’entité mise à jour, et pas seulement les changements. Pour prendre en charge les mises à jour partielles, utilisez HTTP PATCH.

Si vous obtenez une erreur en appelant PutTodoItem, appelez GET pour vérifier que la base de données contient un élément.

Tester la méthode PutTodoItem

Cet exemple utilise une base de données en mémoire qui doit être initialisée chaque fois que l’application est démarrée. La base de données doit contenir un élément avant que vous ne passiez un appel PUT. Appelez GET pour vous assurer qu’il existe un élément dans la base de données avant d’effectuer un appel PUT.

Mettez à jour l’élément à faire qui a l’ID = 1 et définissez son nom sur « poisson d’alimentation » :

  {
    "id":1,
    "name":"feed fish",
    "isComplete":true
  }

L’image suivante montre la mise à jour Postman :

Postman console showing 204 (No Content) response

Méthode DeleteTodoItem

Examinez la méthode DeleteTodoItem :

// DELETE: api/TodoItems/5
[HttpDelete("{id}")]
public async Task<ActionResult<TodoItem>> DeleteTodoItem(long id)
{
    var todoItem = await _context.TodoItems.FindAsync(id);
    if (todoItem == null)
    {
        return NotFound();
    }

    _context.TodoItems.Remove(todoItem);
    await _context.SaveChangesAsync();

    return todoItem;
}

Tester la méthode DeleteTodoItem

Utilisez Postman pour supprimer une tâche :

  • Définissez la méthode sur DELETE.
  • Définissez l’URI de l’objet à supprimer (par exemple https://localhost:5001/api/todoitems/1).
  • Sélectionnez Envoyer.

Empêcher la sur-publication

Actuellement, l’exemple d’application expose l’objet entier TodoItem . Les applications de production limitent généralement les données entrées et retournées à l’aide d’un sous-ensemble du modèle. Il existe plusieurs raisons derrière cela et la sécurité est une principale. Le sous-ensemble d’un modèle est généralement appelé objet de transfert de données (DTO), modèle d’entrée ou modèle d’affichage. DTO est utilisé dans cet article.

Un DTO peut être utilisé pour :

  • Empêcher la sur-publication.
  • Masquer les propriétés que les clients ne sont pas censés afficher.
  • Omettez certaines propriétés pour réduire la taille de la charge utile.
  • Graphes d’objets aplatis qui contiennent des objets imbriqués. Les graphiques d’objets aplatis peuvent être plus pratiques pour les clients.

Pour illustrer l’approche DTO, mettez à jour la TodoItem classe pour inclure un champ secret :

public class TodoItem
{
    public long Id { get; set; }
    public string Name { get; set; }
    public bool IsComplete { get; set; }
    public string Secret { get; set; }
}

Le champ secret doit être masqué de cette application, mais une application administrative peut choisir de l’exposer.

Vérifiez que vous pouvez publier et obtenir le champ secret.

Créez un modèle DTO :

public class TodoItemDTO
{
    public long Id { get; set; }
    public string Name { get; set; }
    public bool IsComplete { get; set; }
}

Mettez à jour l’utilisation TodoItemsControllerTodoItemDTO:

    [HttpGet]
    public async Task<ActionResult<IEnumerable<TodoItemDTO>>> GetTodoItems()
    {
        return await _context.TodoItems
            .Select(x => ItemToDTO(x))
            .ToListAsync();
    }

    [HttpGet("{id}")]
    public async Task<ActionResult<TodoItemDTO>> GetTodoItem(long id)
    {
        var todoItem = await _context.TodoItems.FindAsync(id);

        if (todoItem == null)
        {
            return NotFound();
        }

        return ItemToDTO(todoItem);
    }

    [HttpPut("{id}")]
    public async Task<IActionResult> UpdateTodoItem(long id, TodoItemDTO todoItemDTO)
    {
        if (id != todoItemDTO.Id)
        {
            return BadRequest();
        }

        var todoItem = await _context.TodoItems.FindAsync(id);
        if (todoItem == null)
        {
            return NotFound();
        }

        todoItem.Name = todoItemDTO.Name;
        todoItem.IsComplete = todoItemDTO.IsComplete;

        try
        {
            await _context.SaveChangesAsync();
        }
        catch (DbUpdateConcurrencyException) when (!TodoItemExists(id))
        {
            return NotFound();
        }

        return NoContent();
    }

    [HttpPost]
    public async Task<ActionResult<TodoItemDTO>> CreateTodoItem(TodoItemDTO todoItemDTO)
    {
        var todoItem = new TodoItem
        {
            IsComplete = todoItemDTO.IsComplete,
            Name = todoItemDTO.Name
        };

        _context.TodoItems.Add(todoItem);
        await _context.SaveChangesAsync();

        return CreatedAtAction(
            nameof(GetTodoItem),
            new { id = todoItem.Id },
            ItemToDTO(todoItem));
    }

    [HttpDelete("{id}")]
    public async Task<IActionResult> DeleteTodoItem(long id)
    {
        var todoItem = await _context.TodoItems.FindAsync(id);

        if (todoItem == null)
        {
            return NotFound();
        }

        _context.TodoItems.Remove(todoItem);
        await _context.SaveChangesAsync();

        return NoContent();
    }

    private bool TodoItemExists(long id) =>
         _context.TodoItems.Any(e => e.Id == id);

    private static TodoItemDTO ItemToDTO(TodoItem todoItem) =>
        new TodoItemDTO
        {
            Id = todoItem.Id,
            Name = todoItem.Name,
            IsComplete = todoItem.IsComplete
        };       
}

Vérifiez que vous ne pouvez pas publier ou obtenir le champ secret.

Appelez l’API web avec JavaScript

Consultez le tutoriel : Appeler une API web ASP.NET Core avec JavaScript.

Ajouter la prise en charge de l’authentification à une API web

ASP.NET Core Identityajoute la fonctionnalité de connexion de l’interface utilisateur à ASP.NET Core applications web. Pour sécuriser les API web et les spAs, utilisez l’une des options suivantes :

Duende Identity Server est une infrastructure OpenID Connecter et OAuth 2.0 pour ASP.NET Core. Le serveur Duende Identity active les fonctionnalités de sécurité suivantes :

  • Authentification en tant que service (AaaS)
  • Authentification unique/authentification unique (SSO) sur plusieurs types d’application
  • Contrôle d’accès pour les API
  • Passerelle de fédération

Important

Duende Software peut nécessiter que vous payiez des frais de licence pour l’utilisation de Duende Identity Server. Pour plus d’informations, consultez Migrer de ASP.NET Core 5.0 vers 6.0.

Pour plus d’informations, consultez la documentation du Serveur Duende (site web Duende Identity Software).

Publication dans Azure

Pour plus d’informations sur le déploiement sur Azure, consultez Démarrage rapide : Déployer une application web ASP.NET.

Ressources supplémentaires

Affichez ou téléchargez l’exemple de code de ce tutoriel. Consultez Guide pratique pour télécharger.

Pour plus d’informations, consultez les ressources suivantes :