Didacticiel : créer une API Web avec ASP.NET CoreTutorial: Create a web API with ASP.NET Core

De Rick Anderson et Mike WassonBy Rick Anderson and Mike Wasson

Ce tutoriel décrit les principes fondamentaux liés à la génération d’une API web avec ASP.NET Core.This tutorial teaches the basics of building a web API with ASP.NET Core.

Dans ce didacticiel, vous apprendrez à :In this tutorial, you learn how to:

  • Créer un projet d’API web.Create a web API project.
  • Ajouter une classe de modèle et un contexte de base de données.Add a model class and a database context.
  • Générer automatiquement des modèles pour un contrôleur avec des méthodes CRUD.Scaffold a controller with CRUD methods.
  • Configurer le routage, les chemins d’URL et les valeurs de retour.Configure routing, URL paths, and return values.
  • Appeler l’API web avec PostmanCall the web API with Postman.

À la fin, vous disposez d’une API web qui peut gérer des tâches stockées dans une base de données.At the end, you have a web API that can manage "to-do" items stored in a database.

Vue d'ensembleOverview

Ce didacticiel crée l’API suivante :This tutorial creates the following API:

APIAPI DescriptionDescription Corps de la requêteRequest body Corps de réponseResponse body
GET /api/TodoItemsGET /api/TodoItems Obtenir toutes les tâchesGet all to-do items aucune.None Tableau de tâchesArray of to-do items
GET /api/TodoItems/{id}GET /api/TodoItems/{id} Obtenir un élément par IDGet an item by ID aucune.None TâcheTo-do item
POST /api/TodoItemsPOST /api/TodoItems Ajouter un nouvel élémentAdd a new item TâcheTo-do item TâcheTo-do item
PUT /api/TodoItems/{id}PUT /api/TodoItems/{id} Mettre à jour un élément existant  Update an existing item   TâcheTo-do item aucune.None
DELETE /api/TodoItems/{id}    DELETE /api/TodoItems/{id}     Supprimer un élément    Delete an item     aucune.None aucune.None

Le diagramme suivant illustre la conception de l’application.The following diagram shows the design of the app.

Le client est représenté par une zone située à gauche.

Configuration requisePrerequisites

Créer un projet webCreate a web project

  • Dans le menu Fichier, sélectionnez Nouveau > Projet.From the File menu, select New > Project.
  • Sélectionnez le modèle Application web ASP.NET Core et cliquez sur Suivant.Select the ASP.NET Core Web Application template and click Next.
  • Nommez le projet TodoApi et cliquez sur Créer.Name the project TodoApi and click Create.
  • Dans la boîte de dialogue Créer une application web ASP.NET Core, vérifiez que .NET Core et ASP.NET Core 3.0 sont sélectionnés.In the Create a new ASP.NET Core Web Application dialog, confirm that .NET Core and ASP.NET Core 3.0 are selected. Sélectionnez le modèle API et cliquez sur Créer.Select the API template and click Create.

Boîte de dialogue de nouveau projet dans VS

Tester l’APITest the API

Le modèle de projet crée une API WeatherForecast.The project template creates a WeatherForecast API. Appelez la méthode Get à partir d’un navigateur pour tester l’application.Call the Get method from a browser to test the app.

Appuyez sur Ctrl+F5 pour exécuter l’application.Press Ctrl+F5 to run the app. 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.Visual Studio launches a browser and navigates to https://localhost:<port>/WeatherForecast, where <port> is a randomly chosen port number.

Si une boîte de dialogue apparaît vous demandant si vous devez approuver le certificat IIS Express, sélectionnez Oui.If you get a dialog box that asks if you should trust the IIS Express certificate, select Yes. Dans la boîte de dialogue Avertissement de sécurité qui s’affiche ensuite, sélectionnez Oui.In the Security Warning dialog that appears next, select Yes.

Un code JSON similaire au suivant est retourné :JSON similar to the following is returned:

[
    {
        "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èleAdd a model class

Un modèle est un ensemble de classes qui représentent les données gérées par l’application.A model is a set of classes that represent the data that the app manages. Le modèle pour cette application est une classe TodoItem unique.The model for this app is a single TodoItem class.

  • Dans l’Explorateur de solutions, cliquez avec le bouton droit sur le projet.In Solution Explorer, right-click the project. Sélectionnez Ajouter > Nouveau dossier.Select Add > New Folder. Nommez le dossier Models.Name the folder Models.

  • Cliquez avec le bouton droit sur le dossier Models et sélectionnez Ajouter > Classe.Right-click the Models folder and select Add > Class. Nommez la classe TodoItem et sélectionnez sur Ajouter.Name the class TodoItem and select Add.

  • Remplacez le code du modèle par le code suivant :Replace the template code with the following code:

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.The Id property functions as the unique key in a relational database.

Vous pouvez placer des classes de modèle n’importe où dans le projet, mais le dossier Models est utilisé par convention.Model classes can go anywhere in the project, but the Models folder is used by convention.

Ajouter un contexte de base de donnéesAdd a database context

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.The database context is the main class that coordinates Entity Framework functionality for a data model. Cette classe est créée en dérivant de la classe Microsoft.EntityFrameworkCore.DbContext.This class is created by deriving from the Microsoft.EntityFrameworkCore.DbContext class.

Ajouter Microsoft.EntityFrameworkCore.SqlServerAdd Microsoft.EntityFrameworkCore.SqlServer

  • Dans le menu Outils, sélectionnez Gestionnaire de package NuGet > Gérer les packages NuGet pour la solution.From the Tools menu, select NuGet Package Manager > Manage NuGet Packages for Solution.
  • Sélectionnez l’onglet Parcourir, puis entrez Microsoft.EntityFrameworkCore.SqlServer dans la zone de recherche.Select the Browse tab, and then enter Microsoft.EntityFrameworkCore.SqlServer in the search box.
  • Dans le volet gauche, sélectionnez Microsoft. EntityFrameworkCore. SqlServer .Select Microsoft.EntityFrameworkCore.SqlServer in the left pane.
  • Cochez la case Projet dans le volet droit, puis sélectionnez Installer.Select the Project check box in the right pane and then select Install.
  • Utilisez les instructions précédentes pour ajouter le package NuGet Microsoft.EntityFrameworkCore.InMemory.Use the preceding instructions to add the Microsoft.EntityFrameworkCore.InMemory NuGet package.

NuGet Package Manager

Ajouter le contexte de base de données TodoContextAdd the TodoContext database context

  • Cliquez avec le bouton droit sur le dossier Models et sélectionnez Ajouter > Classe.Right-click the Models folder and select Add > Class. Nommez la classe TodoContext et cliquez sur Ajouter.Name the class TodoContext and click Add.
  • Entrez le code suivant :Enter the following code:

    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éesRegister the database context

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.In ASP.NET Core, services such as the DB context must be registered with the dependency injection (DI) container. Le conteneur fournit le service aux contrôleurs.The container provides the service to controllers.

Mettez à jour Startup.cs avec le code en surbrillance suivant :Update Startup.cs with the following highlighted code:

// 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 :The preceding code:

  • Supprime les déclarations using inutilisées.Removes unused using declarations.
  • Ajoute le contexte de base de données au conteneur d’injection de dépendances.Adds the database context to the DI container.
  • Spécifie que le contexte de base de données utilise une base de données en mémoire.Specifies that the database context will use an in-memory database.

Générer automatiquement des modèles pour un contrôleurScaffold a controller

  • Cliquez avec le bouton droit sur le dossier Contrôleurs.Right-click the Controllers folder.

  • Sélectionnez Ajouter > Nouvel élément généré automatiquement.Select Add > New Scaffolded Item.

  • Sélectionnez Contrôleur d’API avec actions, utilisant Entity Framework, puis Ajouter.Select API Controller with actions, using Entity Framework, and then select Add.

  • Dans la boîte de dialogue Contrôleur d’API avec actions, utilisant Entity Framework :In the Add API Controller with actions, using Entity Framework dialog:

    • Sélectionnez TodoItem (TodoApi. Models) dans la classe de modèle.Select TodoItem (TodoApi.Models) in the Model class.
    • Sélectionnez TodoContext (TodoApi. Models) dans la classe de contexte de données.Select TodoContext (TodoApi.Models) in the Data context class.
    • Sélectionnez Ajouter .Select Add.

Le code généré :The generated code:

  • Définit une classe de contrôleur d’API sans méthodes.Defines an API controller class without methods.
  • Décore la classe avec l’attribut [ApiController].Decorates the class with the [ApiController] attribute. Cet attribut indique que le contrôleur répond aux requêtes de l’API web.This attribute indicates that the controller responds to web API requests. Pour plus d’informations sur les comportements spécifiques que permet l’attribut, consultez Créer des API web avec ASP.NET Core.For information about specific behaviors that the attribute enables, see 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.Uses DI to inject the database context (TodoContext) into the controller. Le contexte de base de données est utilisé dans chacune des méthodes la CRUD du contrôleur.The database context is used in each of the CRUD methods in the controller.

Examiner la méthode de création de PostTodoItemExamine the PostTodoItem create method

Remplacez l’instruction return dans PostTodoItem pour utiliser l’opérateur nameof :Replace the return statement in the PostTodoItem to use the nameof operator:

// 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].The preceding code is an HTTP POST method, as indicated by the [HttpPost] attribute. La méthode obtient la valeur de la tâche dans le corps de la requête HTTP.The method gets the value of the to-do item from the body of the HTTP request.

La méthode CreatedAtAction :The CreatedAtAction method:

  • Retourne un code d’état HTTP 201 en cas de réussite.Returns an HTTP 201 status code if successful. HTTP 201 est la réponse standard d’une méthode HTTP POST qui crée une ressource sur le serveur.HTTP 201 is the standard response for an HTTP POST method that creates a new resource on the server.
  • Ajoute un en-tête Location à la réponse.Adds a Location header to the response. L’en-tête Location spécifie l’URI de l’élément d’action qui vient d’être créé.The Location header specifies the URI of the newly created to-do item. Pour plus d’informations, consultez la section 10.2.2 201 Created.For more information, see 10.2.2 201 Created.
  • Fait référence à l’action GetTodoItem pour créer l’URI Location de l’en-tête.References the GetTodoItem action to create the Location header's URI. Le mot clé nameof C# est utilisé pour éviter de coder en dur le nom de l’action dans l’appel CreatedAtAction.The C# nameof keyword is used to avoid hard-coding the action name in the CreatedAtAction call.

Installer PostmanInstall Postman

Ce tutoriel utilise Postman pour tester l’API web.This tutorial uses Postman to test the web API.

  • Installez Postman.Install Postman
  • Démarrez l’application web.Start the web app.
  • Démarrez Postman.Start Postman.
  • Désactivez la vérification du certificat SSL.Disable SSL certificate verification
  • À partir de Fichier > Paramètres (onglet Général), désactivez Vérification du certificat SSL.From File > Settings (General tab), disable SSL certificate verification.

    Avertissement

    Réactivez la vérification du certificat SSL après avoir testé le contrôleur.Re-enable SSL certificate verification after testing the controller.

Tester PostTodoItem avec PostmanTest PostTodoItem with Postman

  • Créez une requête.Create a new request.

  • Affectez POST à la méthode HTTP.Set the HTTP method to POST.

  • Sélectionnez l’onglet Body (Corps).Select the Body tab.

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

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

  • Dans le corps de la demande, entrez la syntaxe JSON d’une tâche :In the request body enter JSON for a to-do item:

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

    Postman avec requête de création

Tester l’URI de l’en-tête d’emplacementTest the location header URI

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

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

    Onglet Headers de la console Postman

  • Définissez la méthode sur GET.Set the method to GET.

  • Collez l’URI (par exemple, https://localhost:5001/api/TodoItems/1).Paste the URI (for example, https://localhost:5001/api/TodoItems/1).

  • Sélectionnez Send (Envoyer).Select Send.

Examiner les méthodes GETExamine the GET methods

Ces méthodes implémentent deux points de terminaison GET :These methods implement two GET endpoints:

  • GET /api/TodoItems
  • GET /api/TodoItems/{id}

Testez l’application en appelant les deux points de terminaison à partir d’un navigateur ou de Postman.Test the app by calling the two endpoints from a browser or Postman. Exemple :For example:

Une réponse semblable à la suivante est produite par l’appel à GetTodoItems :A response similar to the following is produced by the call to GetTodoItems:

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

Tester Get avec PostmanTest Get with Postman

  • Créez une requête.Create a new request.
  • Définissez la méthode HTTP sur GET.Set the HTTP method to GET.
  • Définissez l’URL de la requête sur https://localhost:<port>/api/TodoItems.Set the request URL to https://localhost:<port>/api/TodoItems. Par exemple, https://localhost:5001/api/TodoItems.For example, https://localhost:5001/api/TodoItems.
  • Définissez l’affichage à deux volets dans Postman.Set Two pane view in Postman.
  • Sélectionnez Send (Envoyer).Select Send.

Cette application utilise une base de données en mémoire.This app uses an in-memory database. Si l’application est arrêtée et démarrée, la requête GET précédente ne retourne aucune donnée.If the app is stopped and started, the preceding GET request will not return any data. Si aucune donnée n’est retournée, publiez (POST) les données dans l’application.If no data is returned, POST data to the app.

Routage et chemins d’URLRouting and URL paths

L’attribut [HttpGet] désigne une méthode qui répond à une requête HTTP GET.The [HttpGet] attribute denotes a method that responds to an HTTP GET request. Le chemin d’URL pour chaque méthode est construit comme suit :The URL path for each method is constructed as follows:

  • Partez de la chaîne de modèle dans l’attribut Route du contrôleur :Start with the template string in the controller's Route attribute:

    [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 ».Replace [controller] with the name of the controller, which by convention is the controller class name minus the "Controller" suffix. Pour cet exemple, le nom de la classe du contrôleur étant TodoItemsController, le nom du contrôleur est « TodoItems ».For this sample, the controller class name is TodoItemsController, so the controller name is "TodoItems". Le routage d’ASP.NET Core ne respecte pas la casse.ASP.NET Core routing is case insensitive.

  • Si l’attribut [HttpGet] a un modèle de route (par exemple, [HttpGet("products")]), ajoutez-le au chemin.If the [HttpGet] attribute has a route template (for example, [HttpGet("products")]), append that to the path. Cet exemple n’utilise pas de modèle.This sample doesn't use a template. Pour plus d’informations, consultez Routage par attributs avec des attributs Http[Verbe].For more information, see Attribute routing with Http[Verb] attributes.

Dans la méthode GetTodoItem suivante, "{id}" est une variable d’espace réservé pour l’identificateur unique de la tâche.In the following GetTodoItem method, "{id}" is a placeholder variable for the unique identifier of the to-do item. Lorsque GetTodoItem est appelé, la valeur de "{id}" dans l’URL est fournie à la méthode dans son paramètre id.When GetTodoItem is invoked, the value of "{id}" in the URL is provided to the method in its id parameter.

// 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 retourReturn values

Le type de retour des méthodes GetTodoItems et GetTodoItem est type ActionResult<T>.The return type of the GetTodoItems and GetTodoItem methods is ActionResult<T> type. ASP.NET Core sérialise automatiquement l’objet en JSON et écrit le JSON dans le corps du message de réponse.ASP.NET Core automatically serializes the object to JSON and writes the JSON into the body of the response message. 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.The response code for this return type is 200, assuming there are no unhandled exceptions. Les exceptions non gérées sont converties en erreurs 5xx.Unhandled exceptions are translated into 5xx errors.

Les types de retour ActionResult peuvent représenter une large plage de codes d’état HTTP.ActionResult return types can represent a wide range of HTTP status codes. Par exemple, GetTodoItem peut retourner deux valeurs d’état différentes :For example, GetTodoItem can return two different status values:

  • Si aucun élément ne correspond à l’ID demandé, la méthode retourne un code d’erreur 404 introuvable.If no item matches the requested ID, the method returns a 404 NotFound error code.
  • Sinon, la méthode retourne 200 avec un corps de réponse JSON.Otherwise, the method returns 200 with a JSON response body. Le retour de item entraîne une réponse HTTP 200.Returning item results in an HTTP 200 response.

Méthode PutTodoItemThe PutTodoItem method

Examinez la méthode PutTodoItem :Examine the PutTodoItem method:

// 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.PutTodoItem is similar to PostTodoItem, except it uses HTTP PUT. La réponse est 204 (Pas de contenu).The response is 204 (No Content). 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.According to the HTTP specification, a PUT request requires the client to send the entire updated entity, not just the changes. Pour prendre en charge les mises à jour partielles, utilisez HTTP PATCH.To support partial updates, use 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.If you get an error calling PutTodoItem, call GET to ensure there's an item in the database.

Tester la méthode PutTodoItemTest the PutTodoItem method

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.This sample uses an in-memory database that must be initialized each time the app is started. La base de données doit contenir un élément avant que vous ne passiez un appel PUT.There must be an item in the database before you make a PUT call. Appelez GET pour vérifier qu’un élément existe dans la base de données avant d’effectuer un appel PUT.Call GET to insure there's an item in the database before making a PUT call.

Mettez à jour la tâche dont l’ID = 1 et nommez-la « feed fish » :Update the to-do item that has ID = 1 and set its name to "feed fish":

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

L’image suivante montre la mise à jour Postman :The following image shows the Postman update:

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

Méthode DeleteTodoItemThe DeleteTodoItem method

Examinez la méthode DeleteTodoItem :Examine the DeleteTodoItem method:

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

La réponse DeleteTodoItem est 204 (Pas de contenu).The DeleteTodoItem response is 204 (No Content).

Tester la méthode DeleteTodoItemTest the DeleteTodoItem method

Utilisez Postman pour supprimer une tâche :Use Postman to delete a to-do item:

  • Définissez la méthode sur DELETE.Set the method to DELETE.
  • Définissez l’URI de l’objet à supprimer (par exemple https://localhost:5001/api/TodoItems/1).Set the URI of the object to delete (for example https://localhost:5001/api/TodoItems/1).
  • Sélectionnez Send (Envoyer).Select Send.

Appelez l’API web avec JavaScriptCall the web API with JavaScript

Consultez Didacticiel : appeler une API web ASP.net core avec JavaScript.See Tutorial: Call an ASP.NET Core web API with JavaScript.

Dans ce didacticiel, vous apprendrez à :In this tutorial, you learn how to:

  • Créer un projet d’API web.Create a web API project.
  • Ajouter une classe de modèle et un contexte de base de données.Add a model class and a database context.
  • Ajouter un contrôleurAdd a controller.
  • Ajouter les méthodes CRUDAdd CRUD methods.
  • Configurer le routage et les chemins d’URLConfigure routing and URL paths.
  • Spécifier des valeurs de retourSpecify return values.
  • Appeler l’API web avec PostmanCall the web API with Postman.
  • Appeler l’API web avec JavaScript.Call the web API with JavaScript.

À la fin, vous disposez d’une API web qui peut gérer des tâches stockées dans une base de données relationnelle.At the end, you have a web API that can manage "to-do" items stored in a relational database.

Vue d'ensembleOverview

Ce didacticiel crée l’API suivante :This tutorial creates the following API:

APIAPI DescriptionDescription Corps de la requêteRequest body Corps de réponseResponse body
GET /api/TodoItemsGET /api/TodoItems Obtenir toutes les tâchesGet all to-do items aucune.None Tableau de tâchesArray of to-do items
GET /api/TodoItems/{id}GET /api/TodoItems/{id} Obtenir un élément par IDGet an item by ID aucune.None TâcheTo-do item
POST /api/TodoItemsPOST /api/TodoItems Ajouter un nouvel élémentAdd a new item TâcheTo-do item TâcheTo-do item
PUT /api/TodoItems/{id}PUT /api/TodoItems/{id} Mettre à jour un élément existant  Update an existing item   TâcheTo-do item aucune.None
DELETE /api/TodoItems/{id}    DELETE /api/TodoItems/{id}     Supprimer un élément    Delete an item     aucune.None aucune.None

Le diagramme suivant illustre la conception de l’application.The following diagram shows the design of the app.

Le client est représenté par une zone située à gauche.

Configuration requisePrerequisites

Avertissement

Si vous utilisez Visual Studio 2017, consultez le problème no 3124 dotnet/sdk pour plus d’informations sur les versions du Kit SDK .NET Core qui ne fonctionnent pas avec Visual Studio.If you use Visual Studio 2017, see dotnet/sdk issue #3124 for information about .NET Core SDK versions that don't work with Visual Studio.

Créer un projet webCreate a web project

  • Dans le menu Fichier, sélectionnez Nouveau > Projet.From the File menu, select New > Project.
  • Sélectionnez le modèle Application web ASP.NET Core et cliquez sur Suivant.Select the ASP.NET Core Web Application template and click Next.
  • Nommez le projet TodoApi et cliquez sur Créer.Name the project TodoApi and click Create.
  • Dans la boîte de dialogue Créer une application web ASP.NET Core, vérifiez que .NET Core et ASP.NET Core 2.2 sont sélectionnés.In the Create a new ASP.NET Core Web Application dialog, confirm that .NET Core and ASP.NET Core 2.2 are selected. Sélectionnez le modèle API et cliquez sur Créer.Select the API template and click Create. Ne sélectionnez pas Activer la prise en charge de Docker.Don't select Enable Docker Support.

Boîte de dialogue de nouveau projet dans VS

Tester l’APITest the API

Le modèle de projet crée une API values.The project template creates a values API. Appelez la méthode Get à partir d’un navigateur pour tester l’application.Call the Get method from a browser to test the app.

Appuyez sur Ctrl+F5 pour exécuter l’application.Press Ctrl+F5 to run the app. Visual Studio lance un navigateur et accède à https://localhost:<port>/api/values, où <port> est un numéro de port choisi de manière aléatoire.Visual Studio launches a browser and navigates to https://localhost:<port>/api/values, where <port> is a randomly chosen port number.

Si une boîte de dialogue apparaît vous demandant si vous devez approuver le certificat IIS Express, sélectionnez Oui.If you get a dialog box that asks if you should trust the IIS Express certificate, select Yes. Dans la boîte de dialogue Avertissement de sécurité qui s’affiche ensuite, sélectionnez Oui.In the Security Warning dialog that appears next, select Yes.

Le code JSON suivant est retourné :The following JSON is returned:

["value1","value2"]

Ajouter une classe de modèleAdd a model class

Un modèle est un ensemble de classes qui représentent les données gérées par l’application.A model is a set of classes that represent the data that the app manages. Le modèle pour cette application est une classe TodoItem unique.The model for this app is a single TodoItem class.

  • Dans l’Explorateur de solutions, cliquez avec le bouton droit sur le projet.In Solution Explorer, right-click the project. Sélectionnez Ajouter > Nouveau dossier.Select Add > New Folder. Nommez le dossier Models.Name the folder Models.

  • Cliquez avec le bouton droit sur le dossier Models et sélectionnez Ajouter > Classe.Right-click the Models folder and select Add > Class. Nommez la classe TodoItem et sélectionnez sur Ajouter.Name the class TodoItem and select Add.

  • Remplacez le code du modèle par le code suivant :Replace the template code with the following code:

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.The Id property functions as the unique key in a relational database.

Vous pouvez placer des classes de modèle n’importe où dans le projet, mais le dossier Models est utilisé par convention.Model classes can go anywhere in the project, but the Models folder is used by convention.

Ajouter un contexte de base de donnéesAdd a database context

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.The database context is the main class that coordinates Entity Framework functionality for a data model. Cette classe est créée en dérivant de la classe Microsoft.EntityFrameworkCore.DbContext.This class is created by deriving from the Microsoft.EntityFrameworkCore.DbContext class.

  • Cliquez avec le bouton droit sur le dossier Models et sélectionnez Ajouter > Classe.Right-click the Models folder and select Add > Class. Nommez la classe TodoContext et cliquez sur Ajouter.Name the class TodoContext and click Add.
  • Remplacez le code du modèle par le code suivant :Replace the template code with the following code:

    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éesRegister the database context

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.In ASP.NET Core, services such as the DB context must be registered with the dependency injection (DI) container. Le conteneur fournit le service aux contrôleurs.The container provides the service to controllers.

Mettez à jour Startup.cs avec le code en surbrillance suivant :Update Startup.cs with the following highlighted code:

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

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

        public IConfiguration Configuration { get; }

        // This method gets called by the runtime. Use this method to add services to the 
        //container.
        public void ConfigureServices(IServiceCollection services)
        {
            services.AddDbContext<TodoContext>(opt =>
                opt.UseInMemoryDatabase("TodoList"));
            services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);
        }

        // This method gets called by the runtime. Use this method to configure the HTTP 
        //request pipeline.
        public void Configure(IApplicationBuilder app, IHostingEnvironment env)
        {
            if (env.IsDevelopment())
            {
                app.UseDeveloperExceptionPage();
            }
            else
            {
                // The default HSTS value is 30 days. You may want to change this for 
                // production scenarios, see https://aka.ms/aspnetcore-hsts.
                app.UseHsts();
            }

            app.UseHttpsRedirection();
            app.UseMvc();
        }
    }
}

Le code précédent :The preceding code:

  • Supprime les déclarations using inutilisées.Removes unused using declarations.
  • Ajoute le contexte de base de données au conteneur d’injection de dépendances.Adds the database context to the DI container.
  • Spécifie que le contexte de base de données utilise une base de données en mémoire.Specifies that the database context will use an in-memory database.

Ajouter un contrôleurAdd a controller

  • Cliquez avec le bouton droit sur le dossier Contrôleurs.Right-click the Controllers folder.

  • Sélectionnez Ajouter > Nouvel élément.Select Add > New Item.

  • Dans la boîte de dialogue Ajouter un nouvel élément, sélectionnez le modèle Classe de contrôleur d’API.In the Add New Item dialog, select the API Controller Class template.

  • Nommez la classe TodoController et sélectionnez Ajouter.Name the class TodoController, and select Add.

    Boîte de dialogue Ajouter un nouvel élément avec contrôleur dans la zone de recherche et le contrôleur des API web sélectionné

  • Remplacez le code du modèle par le code suivant :Replace the template code with the following code:

    using Microsoft.AspNetCore.Mvc;
    using Microsoft.EntityFrameworkCore;
    using System.Collections.Generic;
    using System.Linq;
    using System.Threading.Tasks;
    using TodoApi.Models;
    
    namespace TodoApi.Controllers
    {
        [Route("api/[controller]")]
        [ApiController]
        public class TodoController : ControllerBase
        {
            private readonly TodoContext _context;
    
            public TodoController(TodoContext context)
            {
                _context = context;
    
                if (_context.TodoItems.Count() == 0)
                {
                    // Create a new TodoItem if collection is empty,
                    // which means you can't delete all TodoItems.
                    _context.TodoItems.Add(new TodoItem { Name = "Item1" });
                    _context.SaveChanges();
                }
            }
        }
    }
    

Le code précédent :The preceding code:

  • Définit une classe de contrôleur d’API sans méthodes.Defines an API controller class without methods.
  • Décore la classe avec l’attribut [ApiController].Decorates the class with the [ApiController] attribute. Cet attribut indique que le contrôleur répond aux requêtes de l’API web.This attribute indicates that the controller responds to web API requests. Pour plus d’informations sur les comportements spécifiques que permet l’attribut, consultez Créer des API web avec ASP.NET Core.For information about specific behaviors that the attribute enables, see 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.Uses DI to inject the database context (TodoContext) into the controller. Le contexte de base de données est utilisé dans chacune des méthodes la CRUD du contrôleur.The database context is used in each of the CRUD methods in the controller.
  • Ajoute un élément nommé Item1 à la base de données si celle-ci est vide.Adds an item named Item1 to the database if the database is empty. Ce code se trouvant dans le constructeur, il s’exécute chaque fois qu’une nouvelle requête HTTP existe.This code is in the constructor, so it runs every time there's a new HTTP request. Si vous supprimez tous les éléments, le constructeur recrée Item1 au prochain appel d’une méthode d’API.If you delete all items, the constructor creates Item1 again the next time an API method is called. Ainsi, il peut vous sembler à tort que la suppression n’a pas fonctionné.So it may look like the deletion didn't work when it actually did work.

Ajouter des méthodes GetAdd Get methods

Pour fournir une API qui récupère les tâches, ajoutez les méthodes suivantes à la classe TodoController :To provide an API that retrieves to-do items, add the following methods to the TodoController class:

// GET: api/Todo
[HttpGet]
public async Task<ActionResult<IEnumerable<TodoItem>>> GetTodoItems()
{
    return await _context.TodoItems.ToListAsync();
}

// GET: api/Todo/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;
}

Ces méthodes implémentent deux points de terminaison GET :These methods implement two GET endpoints:

  • GET /api/todo
  • GET /api/todo/{id}

Arrêtez l’application si elle est toujours en cours d’exécution.Stop the app if it's still running. Ensuite, réexécutez-la pour inclure les dernières modifications.Then run it again to include the latest changes.

Testez l’application en appelant les deux points de terminaison à partir d’un navigateur.Test the app by calling the two endpoints from a browser. Exemple :For example:

  • https://localhost:<port>/api/todo
  • https://localhost:<port>/api/todo/1

La réponse HTTP suivante est générée par l’appel à GetTodoItems :The following HTTP response is produced by the call to GetTodoItems:

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

Routage et chemins d’URLRouting and URL paths

L’attribut [HttpGet] désigne une méthode qui répond à une requête HTTP GET.The [HttpGet] attribute denotes a method that responds to an HTTP GET request. Le chemin d’URL pour chaque méthode est construit comme suit :The URL path for each method is constructed as follows:

  • Partez de la chaîne de modèle dans l’attribut Route du contrôleur :Start with the template string in the controller's Route attribute:

    namespace TodoApi.Controllers
    {
        [Route("api/[controller]")]
        [ApiController]
        public class TodoController : ControllerBase
        {
            private readonly TodoContext _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 ».Replace [controller] with the name of the controller, which by convention is the controller class name minus the "Controller" suffix. Pour cet exemple, le nom de classe du contrôleur étant TodoController, le nom du contrôleur est « todo ».For this sample, the controller class name is TodoController, so the controller name is "todo". Le routage d’ASP.NET Core ne respecte pas la casse.ASP.NET Core routing is case insensitive.

  • Si l’attribut [HttpGet] a un modèle de route (par exemple, [HttpGet("products")]), ajoutez-le au chemin.If the [HttpGet] attribute has a route template (for example, [HttpGet("products")]), append that to the path. Cet exemple n’utilise pas de modèle.This sample doesn't use a template. Pour plus d’informations, consultez Routage par attributs avec des attributs Http[Verbe].For more information, see Attribute routing with Http[Verb] attributes.

Dans la méthode GetTodoItem suivante, "{id}" est une variable d’espace réservé pour l’identificateur unique de la tâche.In the following GetTodoItem method, "{id}" is a placeholder variable for the unique identifier of the to-do item. Quand GetTodoItem est appelée, la valeur de "{id}" dans l’URL est fournie à la méthode dans son paramètre id.When GetTodoItem is invoked, the value of "{id}" in the URL is provided to the method in itsid parameter.

// GET: api/Todo/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 retourReturn values

Le type de retour des méthodes GetTodoItems et GetTodoItem est type ActionResult<T>.The return type of the GetTodoItems and GetTodoItem methods is ActionResult<T> type. ASP.NET Core sérialise automatiquement l’objet en JSON et écrit le JSON dans le corps du message de réponse.ASP.NET Core automatically serializes the object to JSON and writes the JSON into the body of the response message. 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.The response code for this return type is 200, assuming there are no unhandled exceptions. Les exceptions non gérées sont converties en erreurs 5xx.Unhandled exceptions are translated into 5xx errors.

Les types de retour ActionResult peuvent représenter une large plage de codes d’état HTTP.ActionResult return types can represent a wide range of HTTP status codes. Par exemple, GetTodoItem peut retourner deux valeurs d’état différentes :For example, GetTodoItem can return two different status values:

  • Si aucun élément ne correspond à l’ID demandé, la méthode retourne un code d’erreur 404 introuvable.If no item matches the requested ID, the method returns a 404 NotFound error code.
  • Sinon, la méthode retourne 200 avec un corps de réponse JSON.Otherwise, the method returns 200 with a JSON response body. Le retour de item entraîne une réponse HTTP 200.Returning item results in an HTTP 200 response.

Tester la méthode GetTodoItemsTest the GetTodoItems method

Ce tutoriel utilise Postman pour tester l’API web.This tutorial uses Postman to test the web API.

  • Installez le poste de publication.Install Postman.
  • Démarrez l’application web.Start the web app.
  • Démarrez Postman.Start Postman.
  • Désactivez la vérification du certificat SSL.Disable SSL certificate verification.
  • À partir de Fichier > Paramètres (onglet Général), désactivez Vérification du certificat SSL.From File > Settings (General tab), disable SSL certificate verification.

Avertissement

Réactivez la vérification du certificat SSL après avoir testé le contrôleur.Re-enable SSL certificate verification after testing the controller.

  • Créez une requête.Create a new request.
    • Définissez la méthode HTTP sur GET.Set the HTTP method to GET.
    • Définissez l’URL de la requête sur https://localhost:<port>/api/todo.Set the request URL to https://localhost:<port>/api/todo. Par exemple, https://localhost:5001/api/todo.For example, https://localhost:5001/api/todo.
  • Définissez l’affichage à deux volets dans Postman.Set Two pane view in Postman.
  • Sélectionnez Send (Envoyer).Select Send.

Postman avec requête Get

Ajouter une méthode CreateAdd a Create method

Ajoutez la méthode PostTodoItem suivante à Controllers/TodoController.cs :Add the following PostTodoItem method inside of Controllers/TodoController.cs:

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

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

Le code précédent est une méthode HTTP POST, comme indiqué par l’attribut [HttpPost].The preceding code is an HTTP POST method, as indicated by the [HttpPost] attribute. La méthode obtient la valeur de la tâche dans le corps de la requête HTTP.The method gets the value of the to-do item from the body of the HTTP request.

La méthode CreatedAtAction :The CreatedAtAction method:

  • Retourne un code d’état HTTP 201 en cas de réussite.Returns an HTTP 201 status code, if successful. HTTP 201 est la réponse standard d’une méthode HTTP POST qui crée une ressource sur le serveur.HTTP 201 is the standard response for an HTTP POST method that creates a new resource on the server.

  • Ajoute un en-tête Location à la réponse.Adds a Location header to the response. L’en-tête Location spécifie l’URI de l’élément d’action qui vient d’être créé.The Location header specifies the URI of the newly created to-do item. Pour plus d’informations, consultez la section 10.2.2 201 Created.For more information, see 10.2.2 201 Created.

  • Fait référence à l’action GetTodoItem pour créer l’URI Location de l’en-tête.References the GetTodoItem action to create the Location header's URI. Le mot clé nameof C# est utilisé pour éviter de coder en dur le nom de l’action dans l’appel CreatedAtAction.The C# nameof keyword is used to avoid hard-coding the action name in the CreatedAtAction call.

    // GET: api/Todo/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;
    }
    

Tester la méthode PostTodoItemTest the PostTodoItem method

  • Générez le projet.Build the project.

  • Dans Postman, définissez la méthode HTTP sur POST.In Postman, set the HTTP method to POST.

  • Sélectionnez l’onglet Body (Corps).Select the Body tab.

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

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

  • Dans le corps de la demande, entrez la syntaxe JSON d’une tâche :In the request body enter JSON for a to-do item:

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

    Postman avec requête de création

    Si vous obtenez une erreur 405 Méthode non autorisée, il est probable que le projet n’ait pas été compilé après l’ajout de la méthode PostTodoItem.If you get a 405 Method Not Allowed error, it's probably the result of not compiling the project after adding the PostTodoItem method.

Tester l’URI de l’en-tête d’emplacementTest the location header URI

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

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

    Onglet Headers de la console Postman

  • Définissez la méthode sur GET.Set the method to GET.

  • Collez l’URI (par exemple, https://localhost:5001/api/Todo/2).Paste the URI (for example, https://localhost:5001/api/Todo/2).

  • Sélectionnez Send (Envoyer).Select Send.

Ajouter une méthode PutTodoItemAdd a PutTodoItem method

Ajoutez la méthode PutTodoItem suivante :Add the following PutTodoItem method:

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

    _context.Entry(item).State = EntityState.Modified;
    await _context.SaveChangesAsync();

    return NoContent();
}

PutTodoItem est similaire à PostTodoItem, à la différence près qu’il utilise HTTP PUT.PutTodoItem is similar to PostTodoItem, except it uses HTTP PUT. La réponse est 204 (Pas de contenu).The response is 204 (No Content). 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.According to the HTTP specification, a PUT request requires the client to send the entire updated entity, not just the changes. Pour prendre en charge les mises à jour partielles, utilisez HTTP PATCH.To support partial updates, use 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.If you get an error calling PutTodoItem, call GET to ensure there's an item in the database.

Tester la méthode PutTodoItemTest the PutTodoItem method

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.This sample uses an in-memory database that must be initialized each time the app is started. La base de données doit contenir un élément avant que vous ne passiez un appel PUT.There must be an item in the database before you make a PUT call. Appelez GET pour vérifier qu’un élément existe dans la base de données avant d’effectuer un appel PUT.Call GET to insure there's an item in the database before making a PUT call.

Mettez à jour la tâche dont l’ID = 1 et nommez-la « feed fish » :Update the to-do item that has id = 1 and set its name to "feed fish":

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

L’image suivante montre la mise à jour Postman :The following image shows the Postman update:

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

Ajouter une méthode DeleteTodoItemAdd a DeleteTodoItem method

Ajoutez la méthode DeleteTodoItem suivante :Add the following DeleteTodoItem method:

// DELETE: api/Todo/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();
}

La réponse DeleteTodoItem est 204 (Pas de contenu).The DeleteTodoItem response is 204 (No Content).

Tester la méthode DeleteTodoItemTest the DeleteTodoItem method

Utilisez Postman pour supprimer une tâche :Use Postman to delete a to-do item:

  • Définissez la méthode sur DELETE.Set the method to DELETE.
  • Définissez l’URI de l’objet à supprimer (par exemple https://localhost:5001/api/todo/1).Set the URI of the object to delete (for example https://localhost:5001/api/todo/1).
  • Sélectionnez Send (Envoyer).Select Send.

L’exemple d’application vous permet de supprimer tous les éléments.The sample app allows you to delete all the items. Toutefois, quand le dernier élément est supprimé, un autre est créé par le constructeur de classe de modèle au prochain appel de l’API.However, when the last item is deleted, a new one is created by the model class constructor the next time the API is called.

Appelez l’API web avec JavaScriptCall the web API with JavaScript

Dans cette section, une page HTML qui utilise JavaScript pour appeler l’API web est ajoutée.In this section, an HTML page is added that uses JavaScript to call the web API. jQuery lance la demande.jQuery initiates the request. JavaScript met à jour la page avec les détails de la réponse de l’API Web.JavaScript updates the page with the details from the web API's response.

Configurez l’application pour traiter les fichiers statiques et activer le mappage de fichier par défaut en mettant à jour Startup.cs avec le code en surbrillance suivant :Configure the app to serve static files and enable default file mapping by updating Startup.cs with the following highlighted code:

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }
    else
    {
        // The default HSTS value is 30 days. You may want to change this for 
        // production scenarios, see https://aka.ms/aspnetcore-hsts.
        app.UseHsts();
    }

    app.UseDefaultFiles();
    app.UseStaticFiles();
    app.UseHttpsRedirection();
    app.UseMvc();
}

Créez un dossier wwwroot dans le répertoire du projet.Create a wwwroot folder in the project directory.

Ajoutez un fichier HTML nommé index.html au répertoire wwwroot.Add an HTML file named index.html to the wwwroot directory. Remplacez son contenu par le balisage suivant :Replace its contents with the following markup:

<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <title>To-do CRUD</title>
    <style>
        input[type='submit'], button, [aria-label] {
            cursor: pointer;
        }

        #spoiler {
            display: none;
        }

        table {
            font-family: Arial, sans-serif;
            border: 1px solid;
            border-collapse: collapse;
        }

        th {
            background-color: #0066CC;
            color: white;
        }

        td {
            border: 1px solid;
            padding: 5px;
        }
    </style>
</head>
<body>
    <h1>To-do CRUD</h1>
    <h3>Add</h3>
    <form action="javascript:void(0);" method="POST" onsubmit="addItem()">
        <input type="text" id="add-name" placeholder="New to-do">
        <input type="submit" value="Add">
    </form>

    <div id="spoiler">
        <h3>Edit</h3>
        <form class="my-form">
            <input type="hidden" id="edit-id">
            <input type="checkbox" id="edit-isComplete">
            <input type="text" id="edit-name">
            <input type="submit" value="Save">
            <a onclick="closeInput()" aria-label="Close">&#10006;</a>
        </form>
    </div>

    <p id="counter"></p>

    <table>
        <tr>
            <th>Is Complete</th>
            <th>Name</th>
            <th></th>
            <th></th>
        </tr>
        <tbody id="todos"></tbody>
    </table>

    <script src="https://code.jquery.com/jquery-3.3.1.min.js"
            integrity="sha256-FgpCb/KJQlLNfOu91ta32o/NMZxltwRo8QtmkMRdAu8="
            crossorigin="anonymous"></script>
    <script src="site.js"></script>
</body>
</html>

Ajoutez un fichier JavaScript nommé site.js au répertoire wwwroot.Add a JavaScript file named site.js to the wwwroot directory. Remplacez son contenu par le code suivant :Replace its contents with the following code:

const uri = "api/todo";
let todos = null;
function getCount(data) {
  const el = $("#counter");
  let name = "to-do";
  if (data) {
    if (data > 1) {
      name = "to-dos";
    }
    el.text(data + " " + name);
  } else {
    el.text("No " + name);
  }
}

$(document).ready(function() {
  getData();
});

function getData() {
  $.ajax({
    type: "GET",
    url: uri,
    cache: false,
    success: function(data) {
      const tBody = $("#todos");

      $(tBody).empty();

      getCount(data.length);

      $.each(data, function(key, item) {
        const tr = $("<tr></tr>")
          .append(
            $("<td></td>").append(
              $("<input/>", {
                type: "checkbox",
                disabled: true,
                checked: item.isComplete
              })
            )
          )
          .append($("<td></td>").text(item.name))
          .append(
            $("<td></td>").append(
              $("<button>Edit</button>").on("click", function() {
                editItem(item.id);
              })
            )
          )
          .append(
            $("<td></td>").append(
              $("<button>Delete</button>").on("click", function() {
                deleteItem(item.id);
              })
            )
          );

        tr.appendTo(tBody);
      });

      todos = data;
    }
  });
}

function addItem() {
  const item = {
    name: $("#add-name").val(),
    isComplete: false
  };

  $.ajax({
    type: "POST",
    accepts: "application/json",
    url: uri,
    contentType: "application/json",
    data: JSON.stringify(item),
    error: function(jqXHR, textStatus, errorThrown) {
      alert("Something went wrong!");
    },
    success: function(result) {
      getData();
      $("#add-name").val("");
    }
  });
}

function deleteItem(id) {
  $.ajax({
    url: uri + "/" + id,
    type: "DELETE",
    success: function(result) {
      getData();
    }
  });
}

function editItem(id) {
  $.each(todos, function(key, item) {
    if (item.id === id) {
      $("#edit-name").val(item.name);
      $("#edit-id").val(item.id);
      $("#edit-isComplete")[0].checked = item.isComplete;
    }
  });
  $("#spoiler").css({ display: "block" });
}

$(".my-form").on("submit", function() {
  const item = {
    name: $("#edit-name").val(),
    isComplete: $("#edit-isComplete").is(":checked"),
    id: $("#edit-id").val()
  };

  $.ajax({
    url: uri + "/" + $("#edit-id").val(),
    type: "PUT",
    accepts: "application/json",
    contentType: "application/json",
    data: JSON.stringify(item),
    success: function(result) {
      getData();
    }
  });

  closeInput();
  return false;
});

function closeInput() {
  $("#spoiler").css({ display: "none" });
}

Vous devrez peut-être changer les paramètres de lancement du projet ASP.NET Core pour tester la page HTML localement :A change to the ASP.NET Core project's launch settings may be required to test the HTML page locally:

  • Ouvrez Properties\launchSettings.json.Open Properties\launchSettings.json.
  • Supprimez la propriété launchUrl pour forcer l’utilisation du fichier index.html (fichier par défaut du projet) à l’ouverture de l’application.Remove the launchUrl property to force the app to open at index.html—the project's default file.

Cet exemple appelle toutes les méthodes CRUD de l’API web.This sample calls all of the CRUD methods of the web API. Les explications suivantes traitent des appels à l’API.Following are explanations of the calls to the API.

Obtenir une liste de tâchesGet a list of to-do items

jQuery envoie une requête HTTP obtenir à l’API Web, qui retourne JSON représentant un tableau d’éléments de tâche.jQuery sends an HTTP GET request to the web API, which returns JSON representing an array of to-do items. La fonction de rappel success est appelée si la requête réussit.The success callback function is invoked if the request succeeds. Dans le rappel, le DOM est mis à jour avec les informations des tâches.In the callback, the DOM is updated with the to-do information.

$(document).ready(function() {
  getData();
});

function getData() {
  $.ajax({
    type: "GET",
    url: uri,
    cache: false,
    success: function(data) {
      const tBody = $("#todos");

      $(tBody).empty();

      getCount(data.length);

      $.each(data, function(key, item) {
        const tr = $("<tr></tr>")
          .append(
            $("<td></td>").append(
              $("<input/>", {
                type: "checkbox",
                disabled: true,
                checked: item.isComplete
              })
            )
          )
          .append($("<td></td>").text(item.name))
          .append(
            $("<td></td>").append(
              $("<button>Edit</button>").on("click", function() {
                editItem(item.id);
              })
            )
          )
          .append(
            $("<td></td>").append(
              $("<button>Delete</button>").on("click", function() {
                deleteItem(item.id);
              })
            )
          );

        tr.appendTo(tBody);
      });

      todos = data;
    }
  });
}

Ajouter une tâcheAdd a to-do item

jQuery envoie une requête HTTP POSTÉRIEURe avec l’élément de tâche dans le corps de la demande.jQuery sends an HTTP POST request with the to-do item in the request body. Les options accepts et contentType sont définies avec la valeur application/json pour spécifier le type de média qui est reçu et envoyé.The accepts and contentType options are set to application/json to specify the media type being received and sent. La tâche est convertie au format JSON à l’aide de JSON.stringify.The to-do item is converted to JSON by using JSON.stringify. Quand l’API retourne un code d’état de réussite, la fonction getData est appelée pour mettre à jour la table HTML.When the API returns a successful status code, the getData function is invoked to update the HTML table.

function addItem() {
  const item = {
    name: $("#add-name").val(),
    isComplete: false
  };

  $.ajax({
    type: "POST",
    accepts: "application/json",
    url: uri,
    contentType: "application/json",
    data: JSON.stringify(item),
    error: function(jqXHR, textStatus, errorThrown) {
      alert("Something went wrong!");
    },
    success: function(result) {
      getData();
      $("#add-name").val("");
    }
  });
}

Mettre à jour une tâcheUpdate a to-do item

La mise à jour d’une tâche est similaire à l’ajout d’une tâche.Updating a to-do item is similar to adding one. L’identificateur unique de la tâche est ajouté à l’url et le type est PUT.The url changes to add the unique identifier of the item, and the type is PUT.

$.ajax({
  url: uri + "/" + $("#edit-id").val(),
  type: "PUT",
  accepts: "application/json",
  contentType: "application/json",
  data: JSON.stringify(item),
  success: function(result) {
    getData();
  }
});

Supprimer une tâcheDelete a to-do item

Pour supprimer une tâche, vous devez définir le type sur l’appel AJAX avec la valeur DELETE et spécifier l’identificateur unique de l’élément dans l’URL.Deleting a to-do item is accomplished by setting the type on the AJAX call to DELETE and specifying the item's unique identifier in the URL.

$.ajax({
  url: uri + "/" + id,
  type: "DELETE",
  success: function(result) {
    getData();
  }
});

Ajouter la prise en charge de l’authentification à une API WebAdd authentication support to a web API

ASP.NET Core identité ajoute la fonctionnalité de connexion de l’interface utilisateur à ASP.NET Core Web Apps.ASP.NET Core Identity adds user interface (UI) login functionality to ASP.NET Core web apps. Pour sécuriser les API Web et la commande SPAs, utilisez l’une des méthodes suivantes :To secure web APIs and SPAs, use one of the following:

IdentityServer4 est un Framework OpenID Connect et OAuth 2,0 pour ASP.NET Core 3,0.IdentityServer4 is an OpenID Connect and OAuth 2.0 framework for ASP.NET Core 3.0. IdentityServer4 active les fonctionnalités de sécurité suivantes :IdentityServer4 enables the following security features:

  • Authentification en tant que service (AaaS)Authentication as a Service (AaaS)
  • Authentification unique (SSO) sur plusieurs types d’applicationsSingle sign-on/off (SSO) over multiple application types
  • Contrôle d’accès pour les APIAccess control for APIs
  • Passerelle de FédérationFederation Gateway

Pour plus d’informations, consultez Bienvenue dans IdentityServer4.For more information, see Welcome to IdentityServer4.

Ressources supplémentairesAdditional resources

Affichez ou téléchargez l’exemple de code de ce tutoriel.View or download sample code for this tutorial. Consultez Guide pratique pour télécharger.See how to download.

Pour plus d'informations, reportez-vous aux ressources suivantes :For more information, see the following resources: