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

von Mike Wasson

In diesem Lernprogramm wird gezeigt, wie Sie eine Web-API in einer Konsolenanwendung hosten. ASP.NET Web-API erfordert IIS nicht. Sie können eine Web-API in Ihrem eigenen Hostprozess selbst hosten.

Neue Anwendungen sollten OWIN verwenden, um die Web-API selbst zu hosten. Siehe OWIN verwenden für das Selbst-Hosting von ASP.NET Web API 2.

Im Lernprogramm verwendete Softwareversionen

• Web-API 1
• Visual Studio 2012

Erstellen des Konsolenanwendungsprojekts

Starten Sie Visual Studio, und wählen Sie auf der Startseite "Neues Projekt" aus. Oder wählen Sie im Menü "Datei " die Option "Neu " und dann "Projekt" aus.

Wählen Sie im Bereich "Vorlagen " die Option "Installierte Vorlagen " aus, und erweitern Sie den Knoten "Visual C# ". Wählen Sie unter Visual C#die Option "Windows" aus. Wählen Sie in der Liste der Projektvorlagen die Option "Konsolenanwendung" aus. Nennen Sie das Projekt "SelfHost", und klicken Sie auf "OK".

Festlegen des Zielframeworks (Visual Studio 2010)

Wenn Sie Visual Studio 2010 verwenden, ändern Sie das Zielframework in .NET Framework 4.0. (Standardmäßig zielt die Projektvorlage auf das .Net Framework-Clientprofil ab.)

Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf das Projekt, und wählen Sie "Eigenschaften" aus. Ändern Sie in der Dropdownliste des Zielframeworks das Zielframework in .NET Framework 4.0. Wenn Sie aufgefordert werden, die Änderung anzuwenden, klicken Sie auf "Ja".

Installieren des NuGet-Paket-Managers

Der NuGet-Paket-Manager ist die einfachste Möglichkeit, die Web-API-Assemblys zu einem non-ASP.NET Projekt hinzuzufügen.

Um zu überprüfen, ob der NuGet-Paket-Manager installiert ist, klicken Sie in Visual Studio auf das Menü "Extras ". Wenn ein Menüelement namens NuGet-Paket-Manager angezeigt wird, verfügen Sie über den NuGet-Paket-Manager.

So installieren Sie den NuGet-Paket-Manager:

1. Starten Sie Visual Studio.
2. Wählen Sie im Menü "Extras" die Option "Erweiterungen und Updates" aus.
3. Wählen Sie im Dialogfeld "Erweiterungen und Updates " die Option "Online" aus.
4. Wenn "NuGet-Paket-Manager" nicht angezeigt wird, geben Sie "nuget package manager" in das Suchfeld ein.
5. Wählen Sie den NuGet-Paket-Manager aus, und klicken Sie auf "Herunterladen".
6. Nach Abschluss des Downloads werden Sie aufgefordert, die Installation durchzuführen.
7. Nach Abschluss der Installation werden Sie möglicherweise aufgefordert, Visual Studio neu zu starten.

Hinzufügen des Web-API-NuGet-Pakets

Fügen Sie nach der Installation des NuGet-Paket-Managers das Web-API-Self-Host Paket zu Ihrem Projekt hinzu.

1. Wählen Sie im Menü "Extras " die Option "NuGet-Paket-Manager" aus. Hinweis: Wenn dieses Menüelement nicht angezeigt wird, stellen Sie sicher, dass der NuGet-Paket-Manager ordnungsgemäß installiert ist.
2. Wählen Sie "NuGet-Pakete für Lösung verwalten" aus.
3. Wählen Sie im Dialogfeld "NugGet-Pakete verwalten " die Option "Online" aus.
4. Geben Sie im Suchfeld "Microsoft.AspNet.WebApi.SelfHost" ein.
5. Wählen Sie das ASP.NET Web-API-SelfHost-Paket aus, und klicken Sie auf "Installieren".
6. Klicken Sie nach der Installation des Pakets auf "Schließen ", um das Dialogfeld zu schließen.

Erstellen des Modells und des Controllers

In diesem Lernprogramm werden die gleichen Modell- und Controllerklassen wie das Lernprogramm "Erste Schritte " verwendet.

Fügen Sie eine öffentliche Klasse mit dem Namen Producthinzu.

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

Fügen Sie eine öffentliche Klasse mit dem Namen ProductsControllerhinzu. Leiten Sie diese Klasse von System.Web.Http.ApiController ab.

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

Weitere Informationen zum Code in diesem Controller finden Sie im Lernprogramm "Erste Schritte ". Dieser Controller definiert drei GET-Aktionen:

Hosten der Web-API

Öffnen Sie die Datei Program.cs, und fügen Sie die folgenden using-Anweisungen hinzu:

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

Fügen Sie der Program-Klasse den folgenden Code hinzu.

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();
}

(Optional) Hinzufügen einer HTTP-URL-Namespacereservierung

Diese Anwendung lauscht auf http://localhost:8080/. Standardmäßig erfordert das Lauschen an einer bestimmten HTTP-Adresse Administratorrechte. Wenn Sie das Lernprogramm ausführen, wird möglicherweise dieser Fehler angezeigt: "HTTP konnte URL http://+:8080/"nicht registrieren; Es gibt zwei Möglichkeiten, diesen Fehler zu vermeiden:

• Ausführen von Visual Studio mit erhöhten Administratorberechtigungen oder
• Verwenden Sie Netsh.exe, um Ihrem Konto Berechtigungen zum Reservieren der URL zu erteilen.

Um Netsh.exezu verwenden, öffnen Sie eine Eingabeaufforderung mit Administratorrechten, und geben Sie den folgenden Befehl ein:

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

dabei ist Computer\Benutzername Ihr Benutzerkonto.

Wenn Sie mit dem Self-Hosting abgeschlossen haben, vergessen Sie nicht, die Reservierung zu löschen.

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

Aufrufen der Web-API aus einer Clientanwendung (C#)

Schreiben wir eine einfache Konsolenanwendung, die die Web-API aufruft.

Fügen Sie der Lösung ein neues Konsolenanwendungsprojekt hinzu:

• Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf die Projektmappe und wählen Sie „Neues Projekt hinzufügen“ aus.
• Erstellen Sie eine neue Konsolenanwendung mit dem Namen "ClientApp".

Verwenden Sie den NuGet-Paket-Manager, um das Paket ASP.NET Web-API-Kernbibliotheken hinzuzufügen:

• Wählen Sie im Menü "Extras" die Option "NuGet-Paket-Manager" aus.
• Wählen Sie "NuGet-Pakete für Lösung verwalten" aus.
• Wählen Sie im Dialogfeld "NuGet-Pakete verwalten " die Option "Online" aus.
• Geben Sie im Suchfeld "Microsoft.AspNet.WebApi.Client" ein.
• Wählen Sie das Microsoft ASP.NET Web-API-Clientbibliothekspaket aus, und klicken Sie auf "Installieren".

Fügen Sie dem SelfHost-Projekt einen Verweis in ClientApp hinzu:

• Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf das ClientApp-Projekt.
• Wählen Sie "Verweis hinzufügen" aus.
• Wählen Sie im Dialogfeld "Verweis-Manager" unter ProjektmappeProjekte aus.
• Wählen Sie das SelfHost-Projekt aus.
• Klicke auf OK.

Öffnen Sie die Datei "Client/Program.cs". Fügen Sie die folgende using-Anweisung hinzu:

using System.Net.Http;

Hinzufügen einer statischen HttpClient-Instanz :

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

Fügen Sie die folgenden Methoden hinzu, um alle Produkte auflisten, ein Produkt nach ID auflisten und Produkte nach Kategorie auflisten.

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

Jede dieser Methoden folgt demselben Muster:

1. Rufen Sie HttpClient.GetAsync auf, um eine GET-Anforderung an den entsprechenden URI zu senden.
2. Rufen Sie HttpResponseMessage.EnsureSuccessStatusCode auf. Diese Methode löst eine Ausnahme aus, wenn der HTTP-Antwortstatus ein Fehlercode ist.
3. Rufen Sie ReadAsAsync<T> auf, um einen CLR-Typ aus der HTTP-Antwort zu deserialisieren. Diese Methode ist eine Erweiterungsmethode, die in System.Net.Http.HttpContentExtensions definiert ist.

Die Methoden GetAsync und ReadAsAsync sind asynchron. Sie geben Task-Objekte zurück, die den asynchronen Vorgang darstellen. Durch Abrufen der Result-Eigenschaft wird der Thread blockiert, bis der Vorgang abgeschlossen ist.

Weitere Informationen zur Verwendung von HttpClient, einschließlich der Verwendung von nicht blockierenden Aufrufen, finden Sie unter Aufrufen einer Web-API von einem .NET-Client.

Legen Sie vor dem Aufrufen dieser Methoden die BaseAddress-Eigenschaft für die HttpClient-Instanz auf "http://localhost:8080" fest. Beispiel:

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();
}

Dies sollte Folgendes ausgeben. (Denken Sie daran, zuerst die SelfHost-Anwendung auszuführen.)

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.