Self-Host API Web ASP.NET 1 (C#)

par Mike Wasson

Ce tutoriel montre comment héberger une API web à l’intérieur d’une application console. API Web ASP.NET ne nécessite pas IIS. Vous pouvez auto-héberger une API web dans votre propre processus hôte.

Les nouvelles applications doivent utiliser OWIN pour auto-héberger l’API web. Consultez Utiliser OWIN pour Self-Host API Web ASP.NET 2.

Versions logicielles utilisées dans le tutoriel

• API web 1
• Visual Studio 2012

Créer le projet d’application console

Démarrez Visual Studio et sélectionnez Nouveau projet dans la page Démarrer . Ou, dans le menu Fichier , sélectionnez Nouveau , puis Projet.

Dans le volet Modèles , sélectionnez Modèles installés et développez le nœud Visual C# . Sous Visual C#, sélectionnez Windows. Dans la liste des modèles de projet, sélectionnez Application console. Nommez le projet « SelfHost », puis cliquez sur OK.

Définir l’infrastructure cible (Visual Studio 2010)

Si vous utilisez Visual Studio 2010, remplacez l’infrastructure cible par .NET Framework 4.0. (Par défaut, le modèle de projet cible le profil client .Net Framework.)

Dans Explorateur de solutions, cliquez avec le bouton droit sur le projet, puis sélectionnez Propriétés. Dans la liste déroulante Framework cible , remplacez l’infrastructure cible par .NET Framework 4.0. Lorsque vous êtes invité à appliquer la modification, cliquez sur Oui.

Installer le Gestionnaire de package NuGet

Le Gestionnaire de package NuGet est le moyen le plus simple d’ajouter les assemblys d’API web à un projet non-ASP.NET.

Pour case activée si le Gestionnaire de package NuGet est installé, cliquez sur le menu Outils dans Visual Studio. Si vous voyez un élément de menu appelé Gestionnaire de package NuGet, vous disposez du Gestionnaire de package NuGet.

Pour installer le Gestionnaire de package NuGet :

1. Démarrez Visual Studio.
2. Dans le menu Outils, sélectionnez Extensions et mises à jour.
3. Dans la boîte de dialogue Extensions et Mises à jour, sélectionnez En ligne.
4. Si vous ne voyez pas « Gestionnaire de package NuGet », tapez « gestionnaire de package nuget » dans la zone de recherche.
5. Sélectionnez le Gestionnaire de package NuGet, puis cliquez sur Télécharger.
6. Une fois le téléchargement terminé, vous êtes invité à installer.
7. Une fois l’installation terminée, vous serez peut-être invité à redémarrer Visual Studio.

Ajouter le package NuGet de l’API web

Une fois le Gestionnaire de package NuGet installé, ajoutez le package d’API web Self-Host à votre projet.

1. Dans le menu Outils , sélectionnez Gestionnaire de package NuGet. Remarque : si vous ne voyez pas cet élément de menu, assurez-vous que le Gestionnaire de package NuGet est correctement installé.
2. Sélectionnez Gérer les packages NuGet pour la solution
3. Dans la boîte de dialogue Gérer les packages NugGet , sélectionnez En ligne.
4. Dans la zone de recherche, tapez « Microsoft.AspNet.WebApi.SelfHost ».
5. Sélectionnez le package auto-hôte API Web ASP.NET, puis cliquez sur Installer.
6. Une fois le package installé, cliquez sur Fermer pour fermer la boîte de dialogue.

Notes

Veillez à installer le package nommé Microsoft.AspNet.WebApi.SelfHost, et non AspNetWebApi.SelfHost.

Créer le modèle et le contrôleur

Ce didacticiel utilise les mêmes classes de modèle et de contrôleur que le tutoriel Prise en main.

Ajoutez une classe publique nommée Product.

namespace SelfHost
{
    public class Product
    {
        public int Id { get; set; }
        public string Name { get; set; }
        public string Category { get; set; }
        public decimal Price { get; set; }
    }
}

Ajoutez une classe publique nommée ProductsController. Dérivez cette classe de System.Web.Http.ApiController.

namespace SelfHost
{
    using System;
    using System.Collections.Generic;
    using System.Linq;
    using System.Net;
    using System.Web.Http;
    
    public class ProductsController : ApiController
    {
        Product[] products = new Product[]  
        {  
            new Product { Id = 1, Name = "Tomato Soup", Category = "Groceries", Price = 1 },  
            new Product { Id = 2, Name = "Yo-yo", Category = "Toys", Price = 3.75M },  
            new Product { Id = 3, Name = "Hammer", Category = "Hardware", Price = 16.99M }  
        };

        public IEnumerable<Product> GetAllProducts()
        {
            return products;
        }

        public Product GetProductById(int id)
        {
            var product = products.FirstOrDefault((p) => p.Id == id);
            if (product == null)
            {
                throw new HttpResponseException(HttpStatusCode.NotFound);
            }
            return product;
        }

        public IEnumerable<Product> GetProductsByCategory(string category)
        {
            return products.Where(p => string.Equals(p.Category, category,
                    StringComparison.OrdinalIgnoreCase));
        }
    }
}

Pour plus d’informations sur le code de ce contrôleur, consultez le tutoriel Prise en main. Ce contrôleur définit trois actions GET :

URI	Description
/api/products	Obtenez la liste de tous les produits.
/api/products/id	Obtenir un produit par ID.
/api/products/?category=category	Obtenez la liste des produits par catégorie.

Héberger l’API web

Ouvrez le fichier Program.cs et ajoutez les instructions using suivantes :

using System.Web.Http;
using System.Web.Http.SelfHost;

Ajoutez le code suivant à la classe Program .

var config = new HttpSelfHostConfiguration("http://localhost:8080");

config.Routes.MapHttpRoute(
    "API Default", "api/{controller}/{id}", 
    new { id = RouteParameter.Optional });

using (HttpSelfHostServer server = new HttpSelfHostServer(config))
{
    server.OpenAsync().Wait();
    Console.WriteLine("Press Enter to quit.");
    Console.ReadLine();
}

(Facultatif) Ajouter une réservation d’espace de noms URL HTTP

Cette application écoute http://localhost:8080/. Par défaut, l’écoute à une adresse HTTP particulière nécessite des privilèges d’administrateur. Lorsque vous exécutez le tutoriel, vous pouvez donc obtenir cette erreur : « HTTP n’a pas pu inscrire l’URL http://+:8080/" Il existe deux façons d’éviter cette erreur :

• Exécutez Visual Studio avec des autorisations d’administrateur élevées, ou
• Utilisez Netsh.exe pour autoriser votre compte à réserver l’URL.

Pour utiliser Netsh.exe, ouvrez une invite de commandes avec des privilèges d’administrateur et entrez la commande suivante :

netsh http add urlacl url=http://+:8080/ user=machine\username

où machine\username est votre compte d’utilisateur.

Lorsque vous avez terminé l’auto-hébergement, veillez à supprimer la réservation :

netsh http delete urlacl url=http://+:8080/

Appeler l’API web à partir d’une application cliente (C#)

Écrivons une application console simple qui appelle l’API web.

Ajoutez un nouveau projet d’application console à la solution :

• Dans Explorateur de solutions, cliquez avec le bouton droit sur la solution et sélectionnez Ajouter un nouveau projet.
• Créez une application console nommée « ClientApp ».

Utilisez le Gestionnaire de package NuGet pour ajouter le package bibliothèques principales API Web ASP.NET :

• Dans le menu Outils, sélectionnez Gestionnaire de package NuGet.
• Sélectionnez Gérer les packages NuGet pour la solution
• Dans la boîte de dialogue Gérer les packages NuGet , sélectionnez En ligne.
• Dans la zone de recherche, tapez « Microsoft.AspNet.WebApi.Client ».
• Sélectionnez le package Bibliothèques clientes Microsoft API Web ASP.NET, puis cliquez sur Installer.

Ajoutez une référence dans ClientApp au projet SelfHost :

• Dans Explorateur de solutions, cliquez avec le bouton droit sur le projet ClientApp.
• Sélectionnez Ajouter une référence.
• Dans la boîte de dialogue Gestionnaire de références , sous Solution, sélectionnez Projets.
• Sélectionnez le projet SelfHost.
• Cliquez sur OK.

Ouvrez le fichier Client/Program.cs. Ajoutez l’instruction using suivante :

using System.Net.Http;

Ajoutez un instance HttpClient statique :

namespace Client
{
    class Program
    {
        static HttpClient client = new HttpClient();
    }
}

Ajoutez les méthodes suivantes pour répertorier tous les produits, répertorier un produit par ID et répertorier les produits par catégorie.

static void ListAllProducts()
{
    HttpResponseMessage resp = client.GetAsync("api/products").Result;
    resp.EnsureSuccessStatusCode();

    var products = resp.Content.ReadAsAsync<IEnumerable<SelfHost.Product>>().Result;
    foreach (var p in products)
    {
        Console.WriteLine("{0} {1} {2} ({3})", p.Id, p.Name, p.Price, p.Category);
    }
}

static void ListProduct(int id)
{
    var resp = client.GetAsync(string.Format("api/products/{0}", id)).Result;
    resp.EnsureSuccessStatusCode();

    var product = resp.Content.ReadAsAsync<SelfHost.Product>().Result;
    Console.WriteLine("ID {0}: {1}", id, product.Name);
}

static void ListProducts(string category)
{
    Console.WriteLine("Products in '{0}':", category);

    string query = string.Format("api/products?category={0}", category);

    var resp = client.GetAsync(query).Result;
    resp.EnsureSuccessStatusCode();

    var products = resp.Content.ReadAsAsync<IEnumerable<SelfHost.Product>>().Result;
    foreach (var product in products)
    {
        Console.WriteLine(product.Name);
    }
}

Chacune de ces méthodes suit le même modèle :

1. Appelez HttpClient.GetAsync pour envoyer une requête GET à l’URI approprié.
2. Appelez HttpResponseMessage.EnsureSuccessStatusCode. Cette méthode lève une exception si le status de réponse HTTP est un code d’erreur.
3. Appelez ReadAsAsync<T> pour désérialiser un type CLR à partir de la réponse HTTP. Cette méthode est une méthode d’extension, définie dans System.Net.Http.HttpContentExtensions.

Les méthodes GetAsync et ReadAsAsync sont asynchrones. Ils retournent des objets Task qui représentent l’opération asynchrone. L’obtention de la propriété Result bloque le thread jusqu’à ce que l’opération se termine.

Pour plus d’informations sur l’utilisation de HttpClient, notamment sur la façon d’effectuer des appels non bloquants, consultez Appel d’une API web à partir d’un client .NET.

Avant d’appeler ces méthodes, définissez la propriété BaseAddress sur le instance HttpClient sur «http://localhost:8080 ». Par exemple :

static void Main(string[] args)
{
    client.BaseAddress = new Uri("http://localhost:8080");

    ListAllProducts();
    ListProduct(1);
    ListProducts("toys");

    Console.WriteLine("Press Enter to quit.");
    Console.ReadLine();
}

Ceci doit générer ce qui suit. (N’oubliez pas d’exécuter d’abord l’application SelfHost.)

1 Tomato Soup 1.0 (Groceries)
2 Yo-yo 3.75 (Toys)
3 Hammer 16.99 (Hardware)
ID 1: Tomato Soup
Products in 'toys':
Yo-yo
Press Enter to quit.