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

  • Article
  • 70 minutes de lecture

Par Rick Anderson et Kirk Larkin

Ce tutoriel explique les principes de base de la création d’une API web basée sur un contrôleur qui utilise une base de données. Une autre approche pour créer des API dans ASP.NET Core consiste à créer des API minimales. Pour obtenir de l’aide sur le choix entre les API minimales et les API basées sur un contrôleur, consultez Vue d’ensemble des API. Pour obtenir un tutoriel sur la création d’une API minimale, consultez Tutoriel : Créer une API minimale avec ASP.NET Core.

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.

Le client est représenté par une zone à gauche. Il envoie une demande et reçoit une réponse de l’application, une case dessinée à droite. Dans la zone application, trois zones représentent le contrôleur, le modèle et la couche d’accès aux données. La requête arrive dans le contrôleur de l’application et des opérations de lecture/écriture se produisent entre le contrôleur et la couche d’accès aux données. Le modèle est sérialisé et retourné au client dans la réponse.

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 7.0 (ou version ultérieure).
    • 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 figurant sous Installer et gérer des packages dans Flux de travail de la consommation des packages (documentation NuGet). Vérifiez les versions 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 :

Ce projet est configuré pour utiliser SSL. Pour éviter les avertissements SSL dans le navigateur, vous pouvez choisir d’approuver le certificat auto-signé que IIS Express a généré. Souhaitez-vous approuver le certificat SSL IIS Express ?

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

La boîte de dialogue suivante s’affiche :

Boîte de dialogue Avertissement de sécurité

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

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

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 GET>Essayer Exécuter>. La page 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 les types de mé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 de l’API web avec Swagger / OpenAPI.

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

JSON semblable à 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"
    }
]

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 de cette application est la TodoItem classe .

  • Dans l’Explorateur de solutions, cliquez avec le bouton droit sur le projet. Sélectionnez Ajouter un>nouveau dossier. Nommez le dossier Models.
  • Cliquez avec le bouton droit sur le Models dossier et sélectionnez Ajouter une>classe. Nommez la classe TodoItem et sélectionnez sur Ajouter.
  • Remplacez le code du modèle par ce qui suit :
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 Gestionnaire > de package NuGet 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 Projet 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 Ajouter une>classe. 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; } = 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 mis en évidence :

using Microsoft.EntityFrameworkCore;
using TodoApi.Models;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();
builder.Services.AddDbContext<TodoContext>(opt =>
    opt.UseInMemoryDatabase("TodoList"));
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

Le code précédent :

  • Ajoute des using directives.
  • 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 Ajouter un>nouvel élément de structure.

  • 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 Data.
    • Sélectionnez Ajouter.

    Si l’opération de génération de modèles échoue, sélectionnez Ajouter pour essayer de créer une structure une deuxième 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 des vues sont inclus [action] dans le modèle d’itinéraire.
  • 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 d’itinéraire, le nom de l’action (nom de la méthode) n’est pas inclus dans le point de terminaison. Autrement dit, le nom de méthode associé 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 pour PostTodoItem 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 HTTP POST méthode, comme indiqué par l’attribut [HttpPost] . La méthode obtient la valeur de à TodoItempartir du 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 pour une HTTP POST méthode 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.

Test PostTodoItem

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

  • Dans la fenêtre du navigateur Swagger, sélectionnez POST /api/TodoItems, puis essayer.

  • Dans la fenêtre d’entrée du corps de la demande, mettez à jour on JS. Par exemple :

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

  • Sélectionnez Exécuter.

    Swagger POST

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

Dans le post précédent, l’interface utilisateur Swagger affiche l’en-tête d’emplacement sous En-têtes de réponse. Par exemple : location: https://localhost:7260/api/TodoItems/1. L’en-tête d’emplacement affiche l’URI de la ressource créée.

Pour tester l’en-tête d’emplacement :

  • Dans la fenêtre du navigateur Swagger, sélectionnez GET /api/TodoItems/{id}, puis essayer.

  • Entrez 1 dans la id zone de saisie, puis sélectionnez Exécuter.

    Swagger GET

Examiner les méthodes GET

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

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

La section précédente a montré un exemple de route /api/todoitems/{id} .

Suivez les instructions POST pour ajouter un autre élément todo, puis testez l’itinéraire à l’aide de /api/todoitems Swagger.

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 HTTP GET demande. 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. Quand GetTodoItem est appelé, la valeur de "{id}" dans 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 retournées

Le type de retour des GetTodoItems méthodes et GetTodoItem est le type T> ActionResult<. ASP.NET Core sérialise automatiquement l’objet sur JSON et écrit l’on JSdans le corps du message de réponse. Le code de réponse pour ce type de retour est 200 OK, en supposant qu’il n’existe aucune exception non prise en charge. 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 JScorps de réponse ON. Le retour item entraîne une HTTP 200 réponse.

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, sauf qu’il utilise HTTP PUT. La réponse est 204 (Aucun contenu). Selon la spécification HTTP, une PUT requête exige que le client envoie l’ensemble de l’entité mise à jour, pas seulement les modifications. Pour prendre en charge les mises à jour partielles, utilisez HTTP PATCH.

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.

À l’aide de l’interface utilisateur Swagger, utilisez le bouton PUT pour mettre à jour le TodoItem qui a ID = 1 et définissez son nom sur "feed fish". Notez que la réponse est HTTP 204 No Content.

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

Utilisez l’interface utilisateur Swagger pour supprimer le TodoItemqui a ID = 1. Notez que la réponse est HTTP 204 No Content.

Test avec http-repl, Postman ou curl

http-repl, Postman et curl sont souvent utilisés pour tester les API. Swagger utilise curl et affiche la commande qu’il curl a envoyée.

Pour obtenir des instructions sur ces outils, consultez les liens suivants :

Pour plus d’informations sur http-repl, consultez Tester les API web avec HttpRepl.

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 y a plusieurs raisons à cela, et la sécurité en est une majeure. 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 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 afin de réduire la taille de la charge utile.
  • Graphiques 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 de 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 pour 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
    // <snippet_GetByID>
    [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);
    }
    // </snippet_GetByID>

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

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

        todoItem.Name = todoDTO.Name;
        todoItem.IsComplete = todoDTO.IsComplete;

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

        return NoContent();
    }
    // </snippet_Update>

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

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

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

    // 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 Tutoriel : Appeler une API web ASP.NET Core avec JavaScript.

Série de vidéos sur l’API web

Consultez Vidéo : Série pour débutants sur : API web.

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.
  • Appelez l’API web avec http-repl.

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

Le client est représenté par une zone à gauche. Il envoie une demande et reçoit une réponse de l’application, une zone dessinée à droite. Dans la zone d’application, trois zones représentent le contrôleur, le modèle et la couche d’accès aux données. La demande entre dans le contrôleur de l’application, et des opérations de lecture/écriture se produisent entre le contrôleur et la couche d’accès aux données. Le modèle est sérialisé et retourné au client dans la réponse.

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 figurant sous Installer et gérer des packages dans Flux de travail de la consommation des packages (documentation NuGet). Vérifiez les versions 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 :

Ce projet est configuré pour utiliser SSL. Pour éviter les avertissements SSL dans le navigateur, vous pouvez choisir d’approuver le certificat auto-signé que IIS Express a généré. Voulez-vous approuver le certificat SSL IIS Express ?

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

La boîte de dialogue suivante s’affiche :

Boîte de dialogue Avertissement de sécurité

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

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

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 GET>Try it out>Execute . La page 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 les types de média, ainsi que 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 de l’API web avec Swagger / OpenAPI.

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

JSON, comme dans 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 launchUrl

Dans Propriétés\launchSettings.json, mettez à jour launchUrl à partir de "swagger" vers "api/todoitems":

"launchUrl": "api/todoitems",

Étant donné que Swagger sera supprimé, le balisage précédent modifie l’URL lancée en 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 Ajouter un>nouveau dossier. Nommez le dossier Models.

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

  • Remplacez le code du modèle par ce qui suit :

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 Gestionnaire > de package NuGet 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 Projet 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 Ajouter une>classe. 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 à l’aide du 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 Ajouter un>nouvel élément généré automatiquement.

  • 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 Data.
    • Sélectionnez Ajouter.

    Si l’opération de génération de modèles échoue, sélectionnez Ajouter pour essayer de créer une structure une deuxième 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 des vues sont inclus [action] dans le modèle d’itinéraire.
  • 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 d’itinéraire, le nom de l’action est exclu de l’itinéraire. Autrement dit, le nom de méthode associé 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 pour PostTodoItem 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 tutoriel 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 vous n’avez pas installé le kit de développement logiciel (SDK) ou le runtime .NET 6.0, installez le runtime .NET 6.0.

Test 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-le 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 connect par httprepl dans 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 route /api/todoitems/{id} . 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, l’on JSretourné 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. Quand GetTodoItem est appelé, la valeur de "{id}" dans 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 retournées

Le type de retour des GetTodoItems méthodes et GetTodoItem est le type T> ActionResult<. ASP.NET Core sérialise automatiquement l’objet sur JSON et écrit l’on JSdans le corps du message de réponse. Le code de réponse pour ce type de retour est 200 OK, en supposant qu’il n’existe aucune exception non prise en charge. 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 JScorps de réponse ON. 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 y a 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 à faire qui a 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 à faire qui a 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 y a plusieurs raisons à cela, et la sécurité en est une majeure. 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 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 afin de réduire la taille de la charge utile.
  • Graphiques 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é 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 pour 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 Tutoriel : Appeler une API web ASP.NET Core avec JavaScript.

Série de vidéos d’API web

Consultez Vidéo : API de séries pour débutants à : web.

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.

Le client est représenté par une zone à gauche. Il envoie une demande et reçoit une réponse de l’application, une case dessinée à droite. Dans la zone application, trois zones représentent le contrôleur, le modèle et la couche d’accès aux données. La requête arrive dans le contrôleur de l’application et des opérations de lecture/écriture se produisent entre le contrôleur et la couche d’accès aux données. Le modèle est sérialisé et retourné au client dans la réponse.

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.

Boîte de dialogue de nouveau projet dans VS

Notes

Pour obtenir des conseils sur l’ajout de packages à des applications .NET, consultez les articles figurant sous Installer et gérer des packages dans Flux de travail de la consommation des packages (documentation NuGet). Vérifiez les versions 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 :

Ce projet est configuré pour utiliser SSL. Pour éviter les avertissements SSL dans le navigateur, vous pouvez choisir d’approuver le certificat auto-signé que IIS Express a généré. Souhaitez-vous approuver le certificat SSL IIS Express ?

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

La boîte de dialogue suivante s’affiche :

Boîte de dialogue Avertissement de sécurité

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

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

Visual Studio lance :

  • Serveur web IIS Express.
  • Navigateur par défaut et accède à https://localhost:<port>/swagger/index.html, où <port> est un numéro de port choisi aléatoirement.

La page /swagger/index.html Swagger s’affiche. Sélectionnez GET>Essayer Exécuter>. La page 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 les types de mé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 de l’API web avec Swagger / OpenAPI.

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

JSON semblable à ce qui suit 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 Propriétés\launchSettings.json, mettez à jour launchUrl à partir de "swagger" vers "api/todoitems":

"launchUrl": "api/todoitems",

Étant donné que Swagger sera supprimé, le balisage précédent modifie l’URL lancée en 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 Ajouter un>nouveau dossier. Nommez le dossier Models.

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

  • Remplacez le code du modèle par ce qui suit :

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 Gestionnaire > de package NuGet 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 Projet dans le volet droit, puis sélectionnez Installer.

Gestionnaire de package NuGet

Ajouter le contexte de base de données TodoContext

  • Cliquez avec le bouton droit sur le Models dossier et sélectionnez Ajouter une>classe. 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 à l’aide du 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 Ajouter un>nouvel élément généré automatiquement.

  • 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 Data.
    • 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 d’itinéraire.
  • 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 d’itinéraire, le nom de l’action est exclu de l’itinéraire. Autrement dit, le nom de méthode associé à 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 pour PostTodoItem 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 201 Créé.
  • 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ésactiver la vérification du certificat SSL :
    • Postman pour Windows : sélectionnezParamètresde fichier> (onglet Général), désactivez la vérification du certificat SSL.
    • Postman pour macOS : sélectionnezParamètresPostman> (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 surJS ON (application/json).

  • Dans le corps de la demande, entrez JSON pour un élément de tâche :

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

  • Sélectionnez Envoyer.

    Postman avec requête de création

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) :

    Onglet Headers de la console Postman

  • 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 est appelé, la valeur de "{id}" dans 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 retournées

Le type de retour des GetTodoItems méthodes et est GetTodoItemde type ActionResult<T>. ASP.NET Core sérialise automatiquement l’objet sur JSON et écrit l’objet JSON dans le corps du message de réponse. Le code de réponse pour 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 JScorps de réponse ON. 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 de tâche 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 :

Console Postman montrant la réponse 204 (Pas de contenu)

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 le sur-affichage

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 à cela et la sécurité en est une majeure. 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 de vue. 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 afin de 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 de 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 :

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

Mettez à jour pour TodoItemsController utiliser TodoItemDTO:

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

Le client est représenté par une zone à gauche. Il envoie une demande et reçoit une réponse de l’application, une zone dessinée à droite. Dans la zone d’application, trois zones représentent le contrôleur, le modèle et la couche d’accès aux données. La demande entre dans le contrôleur de l’application, et des opérations de lecture/écriture se produisent entre le contrôleur et la couche d’accès aux données. Le modèle est sérialisé et retourné au client dans la réponse.

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.

Boîte de dialogue de nouveau projet dans VS

Notes

Pour obtenir des conseils sur l’ajout de packages à des applications .NET, consultez les articles figurant sous Installer et gérer des packages dans Flux de travail de la consommation des packages (documentation NuGet). Vérifiez les versions 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.

JSON semblable à ce qui suit 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 Ajouter un>nouveau dossier. Nommez le dossier Models.

  • Cliquez avec le bouton droit sur le Models dossier et sélectionnez Ajouter une>classe. 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 Gestionnaire > de package NuGet 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 Projet dans le volet droit, puis sélectionnez Installer.

Gestionnaire de package NuGet

Ajouter le contexte de base de données TodoContext

  • Cliquez avec le bouton droit sur le Models dossier et sélectionnez Ajouter une>classe. 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 mis en évidence :

// 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 Ajouter un>nouvel élément généré automatiquement.

  • 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 Data.
    • 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 d’itinéraire.
  • 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 d’itinéraire, le nom de l’action est exclu de l’itinéraire. Autrement dit, le nom de méthode associé à 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 201 Créé.
  • 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ésactiver la vérification du certificat SSL :
    • Postman pour Windows :Paramètresde fichier> Postman pour Windows (onglet Général), désactivez la vérification du certificat SSL.
    • Postman pour macOS :ParamètresPostman pour Windows Postman> (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 surJS ON (application/json).

  • Dans le corps de la demande, entrez JSON pour un élément de tâche :

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

  • Sélectionnez Envoyer.

    Postman avec requête de création

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) :

    Onglet Headers de la console Postman

  • 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 est appelé, la valeur de "{id}" dans 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 retournées

Le type de retour des GetTodoItems méthodes et est GetTodoItemde type ActionResult<T>. ASP.NET Core sérialise automatiquement l’objet sur JSON et écrit l’objet 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 JScorps de réponse ON. 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 de tâche qui a l’ID = 1 et définissez son nom sur « nourrir les poissons » :

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

L’image suivante montre la mise à jour Postman :

Console Postman montrant la réponse 204 (Pas de contenu)

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 le sur-affichage

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 à cela et la sécurité en est une majeure. 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 de vue. 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 afin de 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 de 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é 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 :

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

Mettez à jour pour TodoItemsController utiliser TodoItemDTO:

    [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 Tutoriel : Appeler une API web ASP.NET Core avec JavaScript.

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

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

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

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

Important

Duende Software peut vous demander de payer des frais de licence pour une utilisation en production 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 Identity (site web Deende 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 :