Självstudie: Skapa ett kontrollantbaserat webb-API med ASP.NET Core

Av Tim Deschryver och Rick Anderson

I den här självstudien lär du dig grunderna i att skapa ett kontrollantbaserat webb-API som använder en databas. En annan metod för att skapa API:er i ASP.NET Core är att skapa minimala API:er. Hjälp med att välja mellan minimala API:er och kontrollantbaserade API:er finns i översikten över API:er. En självstudiekurs om hur du skapar ett minimalt API finns i Självstudie: Skapa ett minimalt API med ASP.NET Core.

Överblick

I den här handledningen skapas följande API:

API	Beskrivning	Begäransinnehåll	Svarskropp
GET /api/todoitems	Hämta alla to-do objekt	Ingen	Matris med to-do objekt
GET /api/todoitems/{id}	Hämta ett objekt efter ID	Ingen	Att göra-objekt
POST /api/todoitems	Lägga till ett nytt objekt	Att göra-objekt	Att göra-objekt
PUT /api/todoitems/{id}	Uppdatera ett befintligt objekt	Att göra-objekt	Ingen
DELETE /api/todoitems/{id}	Ta bort ett objekt	Ingen	Ingen

Följande diagram visar appens design.

Förutsättningar

Visual Studio

• Visual Studio 2022 med arbetsbelastningen ASP.NET och webbutveckling.

  

Visual Studio Code

• Visual Studio Code
• C# Dev Kit för Visual Studio Code
• .NET 9.0 SDK

Du kan följa Visual Studio Code-instruktionerna i macOS, Linux eller Windows. Ändringar kan krävas om du använder en annan integrerad utvecklingsmiljö (IDE) än Visual Studio Code.

Skapa ett webb-API-projekt

Visual Studio

• På menyn Arkiv väljer du Nytt>Projekt.
• Ange Web-API i sökrutan.
• Välj mallen ASP.NET Core Web API och välj Nästa.
• I dialogrutan Konfigurera det nya projektetnamnger du projektet TodoApi och väljer Nästa.
• I dialogrutan Ytterligare information:
  • Bekräfta att Framework är .NET 9.0 (Standardtermstöd).
  • Bekräfta att kryssrutan för Aktivera OpenAPI-stöd är markerad.
  • Bekräfta kryssrutan för Använd kontrollanter (avmarkera om du vill använda minimala API:er) är markerad.
  • Välj Skapa.

Lägga till ett NuGet-paket

Ett NuGet-paket måste läggas till för att stödja databasen som används i den här guiden.

• På menyn Verktyg väljer du NuGet Package Manager > Manage NuGet Packages for Solution.
• Välj fliken Bläddra.
• Ange Microsoft.EntityFrameworkCore.InMemory i sökrutan och välj sedan Microsoft.EntityFrameworkCore.InMemory.
• Markera kryssrutan Project i panelen till höger och välj sedan Install.

Visual Studio Code

• Öppna den integrerade terminalen.

• Ändra kataloger (cd) till mappen som ska innehålla projektmappen.

• Kör följande kommandon:

  dotnet new webapi --use-controllers -o TodoApi
  cd TodoApi
  dotnet add package Microsoft.EntityFrameworkCore.InMemory
  code -r ../TodoApi
  

  Följande kommandon:

  • Skapa ett nytt webb-API-projekt och öppna det i Visual Studio Code.
  • Lägg till ett NuGet-paket som behövs för nästa avsnitt.
  • Öppna mappen TodoApi i den aktuella instansen av Visual Studio Code.

Visual Studio Code kan visa en dialogruta som frågar: Litar du på filförfattarna i den här mappen?

• Om du litar på alla filer i den överordnade mappen väljer du Lita på författarna till alla filer i den överordnade mappen.
• Välj Ja, jag litar på författarna eftersom projektmappen har filer som genererats av .NET.
• När Visual Studio Code begär att du lägger till resurser för att skapa och felsöka projektet väljer du Ja. Om Visual Studio Code inte föreslår att du lägger till bygg- och felsökningsfiler väljer du Visa>Kommandopaletten och skriver ".NET" i sökrutan. Välj i kommandolistan kommandot .NET: Generate Assets for Build and Debug.

Visual Studio Code lägger till en .vscode mapp med genererade launch.json och tasks.json filer.

Not

Mer information om hur du lägger till paket i .NET-appar finns i artiklarna under Installera och hantera paket på Arbetsflöde för paketförbrukning (NuGet-dokumentation). Bekräfta rätt paketversioner på NuGet.org.

Kör projektet

Projektmallen skapar ett WeatherForecast API med stöd för OpenAPI-.

Visual Studio

Tryck på Ctrl+F5 för att köra utan felsökningsprogrammet.

Visual Studio visar följande dialogruta när ett projekt ännu inte har konfigurerats för att använda SSL:

Välj Ja om du litar på IIS Express SSL-certifikatet.

Följande dialogruta visas:

Välj Ja om du samtycker till att lita på utvecklingscertifikatet.

Information om hur du kan lita på webbläsaren Firefox finns i Firefox SEC_ERROR_INADEQUATE_KEY_USAGE certifikatfel.

Visual Studio startar ett terminalfönster och visar URL:en för appen som körs. API:et finns på https://localhost:<port>, där <port> är ett slumpmässigt valt portnummer som anges när projektet skapas.

...
info: Microsoft.Hosting.Lifetime[14]
   Now listening on: https://localhost:7260
info: Microsoft.Hosting.Lifetime[14]
   Now listening on: http://localhost:7261
info: Microsoft.Hosting.Lifetime[0]
   Application started. Press Ctrl+C to shut down.
...

Ctrl+klicka på den HTTPS-URL som finns i utgångsdatan för att testa webbappen i en webbläsare. Det finns ingen slutpunkt på https://localhost:<port>, så webbläsaren returnerar HTTP 404 Hittades inte.

Lägg till /weatherforecast till URL:en för att testa WeatherForecast-API:et. Webbläsaren visar JSON som liknar följande exempel:

[
    {
        "date": "2025-07-16",
        "temperatureC": 52,
        "temperatureF": 125,
        "summary": "Mild"
    },
    {
        "date": "2025-07-17",
        "temperatureC": 36,
        "temperatureF": 96,
        "summary": "Warm"
    },
    {
        "date": "2025-07-18",
        "temperatureC": 39,
        "temperatureF": 102,
        "summary": "Cool"
    },
    {
        "date": "2025-07-19",
        "temperatureC": 10,
        "temperatureF": 49,
        "summary": "Bracing"
    },
    {
        "date": "2025-07-20",
        "temperatureC": -1,
        "temperatureF": 31,
        "summary": "Chilly"
    }
]

Visual Studio Code

• Lita på HTTPS-utvecklingscertifikatet genom att köra följande kommando:

  dotnet dev-certs https --trust
  

  Föregående kommando visar följande dialogruta, förutsatt att certifikatet tidigare inte var betrott.

  

• Välj Ja om du samtycker till att lita på utvecklingscertifikatet.

  Mer information finns i avsnittet Lita på ASP.NET Core HTTPS-utvecklingscertifikatet i artikeln Framtvinga SSL-.

Information om hur du kan lita på webbläsaren Firefox finns i Firefox SEC_ERROR_INADEQUATE_KEY_USAGE certifikatfel.

Kör appen:

• Kör följande kommando för att starta appen på https-profilen:

  dotnet run --launch-profile https
  

Utdata visar meddelanden som liknar följande, som anger att appen körs och väntar på begäranden:

...
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: https://localhost:{port}
...

• Ctrl+klicka på HTTPS-URL:en i resultatet för att testa webbappen i en webbläsare.

• Standardwebbläsaren startas till https://localhost:<port>, där <port> är det slumpmässigt valda portnumret som visas i utdata. Det finns ingen slutpunkt på https://localhost:<port>, så webbläsaren returnerar HTTP 404 Hittades inte.

• Lägg till /weatherforecast till URL:en för att testa WeatherForecast-API:et. Webbläsaren visar JSON som liknar följande exempel:

[
    {
        "date": "2025-07-16",
        "temperatureC": 52,
        "temperatureF": 125,
        "summary": "Mild"
    },
    {
        "date": "2025-07-17",
        "temperatureC": 36,
        "temperatureF": 96,
        "summary": "Warm"
    },
    {
        "date": "2025-07-18",
        "temperatureC": 39,
        "temperatureF": 102,
        "summary": "Cool"
    },
    {
        "date": "2025-07-19",
        "temperatureC": 10,
        "temperatureF": 49,
        "summary": "Bracing"
    },
    {
        "date": "2025-07-20",
        "temperatureC": -1,
        "temperatureF": 31,
        "summary": "Chilly"
    }
]

• När du har testat webbappen med hjälp av följande instruktion trycker du på Ctrl+C i den integrerade terminalen för att stänga den.

Testa projektet

Visual Studio

I den här handledningen används Endpoints Explorer och .http-filer för att testa API:t.

Visual Studio Code

Skapa API-testgränssnitt med Swagger

Det finns många tillgängliga verktyg för webb-API-testning att välja mellan, och du kan följa den här självstudiekursens inledande API-teststeg med önskat verktyg.

I den här självstudien används .NET-paketet NSwag.AspNetCore, som integrerar Swagger-verktyg för att generera ett testgränssnitt som följer OpenAPI-specifikationen:

• NSwag: Ett .NET-bibliotek som integrerar Swagger direkt i ASP.NET Core-program, vilket ger mellanprogram och konfiguration.
• Swagger: En uppsättning verktyg med öppen källkod som OpenAPIGenerator och SwaggerUI som genererar API-testsidor som följer OpenAPI-specifikationen.
• OpenAPI-specifikation: Ett dokument som beskriver funktionerna i API:et, baserat på XML- och attributanteckningarna i kontrollanterna och modellerna.

Mer information om hur du använder OpenAPI och NSwag med ASP.NET finns i ASP.NET Core web API-dokumentation med Swagger/OpenAPI.

Installera Swagger-verktyg

• Kör följande kommando:

  dotnet add package NSwag.AspNetCore
  

Föregående kommando lägger till paketet NSwag.AspNetCore, som innehåller verktyg för att generera Swagger-dokument och användargränssnitt. Eftersom vårt projekt använder OpenAPI använder vi bara NSwag-paketet för att generera Swagger-användargränssnittet.

Konfigurera Swagger-mellanprogram

• I Program.cslägger du till följande markerade kod:

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
    app.UseSwaggerUi(options =>
    {
        options.DocumentPath = "/openapi/v1.json";
    });
}

Den tidigare koden aktiverar Swagger-mellanprogrammet för att hantera det genererade JSON-dokumentet med hjälp av Swagger-användargränssnittet. Swagger är endast aktiverat i en utvecklingsmiljö. Om du aktiverar Swagger i en produktionsmiljö kan potentiellt känslig information om API:ets struktur och implementering exponeras.

Appen använder OpenAPI-dokumentet som genereras av OpenApi, som finns på /openapi/v1.json, för att generera användargränssnittet. Visa den genererade OpenAPI-specifikationen för WeatherForecast-API:et medan projektet körs genom att navigera till https://localhost:<port>/openapi/v1.json i webbläsaren.

OpenAPI-specifikationen är ett dokument i JSON-format som beskriver strukturen och funktionerna i ditt API, inklusive slutpunkter, format för begäran/svar, parametrar med mera. Det är i princip en skiss av ditt API som kan användas av olika verktyg för att förstå och interagera med ditt API.

Lägga till en modellklass

En modell är en uppsättning klasser som representerar de data som appen hanterar. Modellen för den här appen är klassen TodoItem.

Visual Studio

• Högerklicka på projektet i Solution Explorer. Välj Lägg till>ny mapp. Ge mappen namnet Models.
• Högerklicka på mappen Models och välj Lägg till>klass. Ge klassen namnet TodoItem och välj Lägg till.
• Ersätt mallkoden med följande:

namespace TodoApi.Models;

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

Visual Studio Code

• Lägg till en mapp med namnet Models.
• Lägg till en TodoItem.cs-fil i mappen Models med följande kod:

namespace TodoApi.Models;

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

Egenskapen Id fungerar som den unika nyckeln i en relationsdatabas.

Modellklasser kan placeras var som helst i projektet, men mappen Models används enligt konvention.

Lägga till en databaskontext

Den databaskontexten är huvudklassen som samordnar Entity Framework-funktioner för en datamodell. Den här klassen skapas genom att härledas från klassen Microsoft.EntityFrameworkCore.DbContext.

Visual Studio

• Högerklicka på mappen Models och välj Lägg till>klass. Ge klassen namnet TodoContext och klicka på Lägg till.

• Ange följande kod:

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

Visual Studio Code

• Lägg till en TodoContext.cs fil i mappen Models.

• Ange följande kod:

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

Registrera databaskontexten

I ASP.NET Core måste tjänster som DB-kontexten registreras i beroendeinjektion (DI)-containern. Containern tillhandahåller tjänsten till kontrollanter.

Uppdatera Program.cs med följande markerade kod:

using Microsoft.EntityFrameworkCore;
using TodoApi.Models;

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
}

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

Föregående kod:

• Lägger till using direktiv.
• Lägger till databaskontexten i DI-containern.
• Anger att databaskontexten ska använda en minnesintern databas.

Generera en styrenhet

Visual Studio

• Högerklicka på mappen Controllers.

• Välj Lägg till>New Scaffolded Item.

• Välj API-kontrollant med åtgärder, använd Entity Frameworkoch välj sedan Lägg till.

• I dialogrutan Lägg till API-kontroller med åtgärder, använd Entity Framework:

  • Välj TodoItem (TodoApi.Models) i klassen Model.
  • Välj TodoContext (TodoApi.Models) i den datakontextklassen .
  • Välj Lägg till.

  Om scaffolding-åtgärden misslyckas väljer du Lägg till för att prova scaffolding igen.

Det här steget lägger till Microsoft.VisualStudio.Web.CodeGeneration.Design- och Microsoft.EntityFrameworkCore.Tools NuGet-paket i projektet. Dessa paket krävs för ramverk.

Visual Studio Code

Kontrollera att alla dina ändringar hittills har sparats.

• Högerklicka (eller kommandoklicka på macOS) projektet TodoAPI och välj Öppna i Terminal. Terminalen öppnas i projektmappen TodoAPI. Kör följande kommandon:

dotnet add package Microsoft.VisualStudio.Web.CodeGeneration.Design
dotnet add package Microsoft.EntityFrameworkCore.Design
dotnet add package Microsoft.EntityFrameworkCore.SqlServer
dotnet add package Microsoft.EntityFrameworkCore.Tools
dotnet tool uninstall -g dotnet-aspnet-codegenerator
dotnet tool install -g dotnet-aspnet-codegenerator
dotnet tool update -g dotnet-aspnet-codegenerator

Föregående kommandon:

• Lägg till de NuGet-paket som krävs för att bygga struktur.
• Installera byggnadsställningsmotorn (dotnet-aspnet-codegenerator) när du har avinstallerat alla möjliga tidigare versioner.

För Linux lägger du till katalogen .NET-verktyg i systemsökvägen med följande kommando:

echo 'export PATH=$HOME/.dotnet/tools:$PATH' >> ~/.bashrc
source ~/.bashrc

Not

Som standard representerar arkitekturen för de .NET-binärfiler som ska installeras den operativsystemarkitektur som körs. Information om hur du anger en annan operativsystemarkitektur finns i dotnet tool install, --arch option. Mer information finns i GitHub-problem dotnet/AspNetCore.Docs #29262.

Skapa projektet.

Kör följande kommando:

dotnet aspnet-codegenerator controller -name TodoItemsController -async -api -m TodoItem -dc TodoContext -outDir Controllers

Föregående kommando ställer in TodoItemsController.

Den genererade koden:

• Markerar klassen med attributet [ApiController]. Det här attributet anger att kontrollanten svarar på webb-API-begäranden. Information om specifika beteenden som attributet aktiverar finns i Skapa webb-API:er med ASP.NET Core.
• Använder DI för att mata in databaskontexten (TodoContext) i kontrollanten. Databaskontexten används i var och en av de CRUD- metoderna i kontrollanten.

ASP.NET Core-mallarna för:

• Kontrollanter med vyer innehåller [action] i routningsmallen.
• API-kontrollanter inkluderar inte [action] i routningsmallen.

När [action] token inte finns i routningsmallen inkluderas inte -åtgärden namn (metodnamn) i slutpunkten. Åtgärdens associerade metodnamn används alltså inte i matchande väg.

Uppdatera metoden PostTodoItem create

Uppdatera retursatsen i PostTodoItem för att använda nameof operatorn:

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

Föregående kod är en HTTP POST metod, vilket anges av attributet [HttpPost]. Metoden hämtar värdet för TodoItem från brödtexten i HTTP-begäran.

För mer information, se Attributdirigering med Http[Verb]-attribut.

Metoden CreatedAtAction:

• Returnerar en HTTP 201-statuskod om den lyckas. HTTP 201 är standardsvaret för en HTTP POST-metod som skapar en ny resurs på servern.
• Lägger till en Location-rubrik i svaret. Location-huvudet anger URI- för det nyligen skapade to-do objektet. Mer information finns i 10.2.2 201 Skapad.
• Refererar till åtgärden GetTodoItem för att skapa Location-huvudets URI. Nyckelordet C# nameof används för att undvika hårdkodning av åtgärdsnamnet i CreatedAtAction-anropet.

Test PostTodoItem

Visual Studio

• Välj Visa>Andra Fönster>Slutpunkter Utforskare.

• Högerklicka på slutpunkten POST och välj Generera begäran.

  

  En ny fil skapas i projektmappen med namnet TodoApi.http, med innehåll som liknar följande exempel:

  @TodoApi_HostAddress = https://localhost:49738
  
  POST {{TodoApi_HostAddress}}/api/todoitems
  Content-Type: application/json
  
  {
    //TodoItem
  }
  
  ###
  

  • Den första raden skapar en variabel som används för alla slutpunkter.
  • Nästa rad definierar en POST-begäran.
  • Raderna efter POST-begäranderaden definierar rubrikerna och en platshållare för begärandetexten.
  • Trippelhashtag-raden (###) är en begäranavgränsare: vad som följer efter är för en annan begäran.

• POST-begäran förväntar sig en TodoItem. För att definiera todo, ersätt //TodoItem-kommentaren med följande JSON:

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

  Filen TodoApi.http bör nu se ut som i följande exempel, men med portnumret:

  @TodoApi_HostAddress = https://localhost:7260
  
  Post {{TodoApi_HostAddress}}/api/todoitems
  Content-Type: application/json
  
  {
    "name": "walk dog",
    "isComplete": true
  }
  
  ###
  

• Kör appen.

• Välj länken Skicka begäran som ligger ovanför POST begäranderaden.

  

  POST-begäran skickas till appen och svaret visas i fönstret Svar.

  

Visual Studio Code

• När appen fortfarande körs går du till https://localhost:<port>/swagger i webbläsaren för att visa den API-testsida som genererats av Swagger. Klicka på TodoItems för att expandera åtgärderna.

  

• På testsidan för Swagger API väljer du Publicera /api/todoitems>Prova.

• Observera att fältet Begärandetext innehåller ett genererat exempelformat som återspeglar parametrarna för API:et.

• I begärandetexten anger du JSON för ett to-do objekt, utan att ange den valfria id:

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

• Välj Kör.

  

• Swagger innehåller ett svar fönster nedanför knappen Kör.

  

Observera några av de användbara detaljerna:

• cURL: Swagger innehåller ett exempel på ett cURL-kommando i Unix/Linux-syntaxen, som kan köras på kommandoraden med alla bash-gränssnitt som använder Unix/Linux-syntax, inklusive Git Bash från Git för Windows.
• Begärande-URL: En förenklad representation av HTTP-begäran som görs av Swagger UI:s JavaScript-kod för API-anropet. Faktiska begäranden kan innehålla information som rubriker och frågeparametrar och en begärandetext.
• Serversvar: Innehåller svarstexten och rubrikerna. Svarstexten visar att id har angetts till 1.
• Svarskod: En statuskod för 201 HTTP returnerades, vilket indikerar att begäran har bearbetats och resulterat i skapandet av en ny resurs.

Testa platsrubrikens URI

Visual Studio

Testa appen genom att anropa GET slutpunkter från en webbläsare eller med hjälp av Endpoints Explorer. Följande steg gäller för Endpoints Explorer.

• I Endpoints Explorerhögerklickar du på den första GET-slutpunkten och väljer Generera begäran.

  Följande innehåll läggs till i filen TodoApi.http:

  GET {{TodoApi_HostAddress}}/api/todoitems
  
  ###
  

• Välj länken Skicka begäran som ligger ovanför den nya GET begäranderaden.

  GET-begäran skickas till appen och svaret visas i fönstret Svar.

• Svarstexten liknar följande JSON:

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

• I Endpoints Explorerhögerklickar du på slutpunkten /api/todoitems/{id}GET och väljer Generera begäran. Följande innehåll läggs till i filen TodoApi.http:

  @id=0
  GET {{TodoApi_HostAddress}}/api/todoitems/{{id}}
  
  ###
  

• Tilldela {@id} till 1 (i stället för 0).

• Välj länken Skicka begäran som ligger ovanför den nya GET-begäranderaden.

  GET-begäran skickas till appen och svaret visas i fönstret Svar.

• Svarstexten liknar följande JSON:

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

Visual Studio Code

Testa appen genom att anropa slutpunkterna från en webbläsare eller Swagger.

• I Swagger väljer du GET /api/todoitems>Prova>Kör.

• Du kan också anropa GET /api/todoitems från en webbläsare genom att ange URI-https://localhost:<port>/api/todoitems. Till exempel: https://localhost:7260/api/todoitems

Anropet till GET /api/todoitems genererar ett svar som liknar följande:

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

• Anropa GET /api/todoitems/{id} i Swagger för att returnera data från ett specifikt ID:

  • Välj GET /api/todoitems>Prova.
  • Ställ in fältet id till 1 och välj Kör.

• Du kan också anropa GET /api/todoitems från en webbläsare genom att ange URI-https://localhost:<port>/api/todoitems/1. Till exempel: https://localhost:7260/api/todoitems/1

• Svaret liknar följande:

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

Granska GET-metoderna

Två GET-slutpunkter implementeras:

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

Föregående avsnitt visade ett exempel på vägen /api/todoitems/{id}.

Följ anvisningarna i POST för att lägga till en annan att-göra-post och testa sedan /api/todoitems vägen med hjälp av Swagger.

Den här appen använder en minnesintern databas. Om appen stoppas och startas returnerar inte den föregående GET-begäran några data. Om ingen data returneras, ska POST data till appen.

Routnings- och URL-sökvägar

Attributet [HttpGet] anger en metod som svarar på en HTTP GET begäran. URL-sökvägen för varje metod konstrueras på följande sätt:

• Börja med mallsträngen i kontrollantens Route-attribut:

  [Route("api/[controller]")]
  [ApiController]
  public class TodoItemsController : ControllerBase
  

• Ersätt [controller] med namnet på kontrollanten, som enligt konventionen är kontrollantens klassnamn minus suffixet "Controller". I det här exemplet är kontrollantklassnamnet TodoItemsController, så kontrollantnamnet är "TodoItems". ASP.NET Core routning är skiftlägesokänsligt.

• Om attributet [HttpGet] har en routningsmall (till exempel [HttpGet("products")]) lägger du till den i sökvägen. Det här exemplet använder ingen mall. För mer information, se Attributdirigering med Http[Verb]-attribut.

I följande GetTodoItem-metod är "{id}" en platshållarvariabel för den unika identifieraren för det to-do objektet. När GetTodoItem anropas anges värdet för "{id}" i URL:en till metoden i parametern id.

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

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

    return todoItem;
}

Returnera värden

Returtypen för metoderna GetTodoItems och GetTodoItem är ActionResult<T> typ. ASP.NET Core serialiserar automatiskt objektet till JSON- och skriver JSON i brödtexten i svarsmeddelandet. Svarskoden för den här returtypen är 200 OK, förutsatt att det inte finns några ohanterade undantag. Ohanterade undantag översätts till 5xx-fel.

ActionResult returtyper kan representera ett brett utbud av HTTP-statuskoder. Till exempel kan GetTodoItem returnera två olika statusvärden:

• Om inget objekt matchar det begärda ID:t returnerar metoden en 404-statusNotFound felkod.
• Annars returnerar metoden 200 med en JSON-svarstext. Om du returnerar item resulterar det i ett HTTP 200 svar.

PutTodoItem-metoden

Granska metoden 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 liknar PostTodoItem, förutom att den använder HTTP PUT. Svaret är 204 (inget innehåll). Enligt HTTP-specifikationen kräver en PUT begäran att klienten skickar hela den uppdaterade entiteten, inte bara ändringarna. Om du vill ha stöd för partiella uppdateringar använder du HTTP PATCH-.

Testa metoden PutTodoItem

Det här exemplet använder en minnesintern databas som måste initieras varje gång appen startas. Det måste finnas ett objekt i databasen innan du gör ett PUT-anrop. Anropa GET för att se till att det finns ett objekt i databasen innan du gör ett PUT-anrop.

Använd metoden PUT för att uppdatera TodoItem som har ID = 1 och ange dess namn till "feed fish". Observera att svaret är HTTP 204 No Content.

Visual Studio

• I Endpoints Explorerhögerklickar du på slutpunkten PUT och väljer Generera begäran.

  Följande innehåll läggs till i filen TodoApi.http:

  PUT {{TodoApi_HostAddress}}/api/todoitems/{{id}}
  Content-Type: application/json
  
  {
    //TodoItem
  }
  
  ###
  

• Ersätt {{id}} med 1på PUT-begäranderaden.

• Ersätt platshållaren //TodoItem med följande rader:

  PUT {{TodoApi_HostAddress}}/api/todoitems/1
  Content-Type: application/json
  
  {
    "id": 1,
    "name": "feed fish",
    "isComplete": false
  }
  

• Välj länken Skicka begäran som ligger ovanför den nya PUT-begäranderaden.

  PUT-begäran skickas till appen och svaret visas i fönstret Svar. Svarstexten är tom och statuskoden är 204.

Visual Studio Code

Använd Swagger för att skicka en PUT-begäran:

• Välj Placera /api/todoitems/{id}>Prova.

• Ange fältet id till 1.

• Ställ in förfrågningskroppen som följande JSON:

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

• Välj Kör.

Metoden DeleteTodoItem

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

Testa metoden DeleteTodoItem

Använd metoden DELETE för att ta bort TodoItem som har ID = 1. Observera att svaret är HTTP 204 No Content.

Visual Studio

• I Endpoints Explorerhögerklickar du på slutpunkten DELETE och väljer Generera begäran.

  En DELETE-begäran läggs till i TodoApi.http.

• Byt ut {{id}} i raden för DELETE-begäran mot 1. DELETE-begäran bör se ut som i följande exempel:

  DELETE {{TodoApi_HostAddress}}/api/todoitems/{{id}}
  
  ###
  

• Välj länken Skicka begäran för DELETE-begäran.

  DELETE-begäran skickas till appen och svaret visas i fönstret Svar. Svarstexten är tom och statuskoden är 204.

Visual Studio Code

Använd Swagger för att skicka en DELETE-begäran:

• Välj DELETE /api/todoitems/{id}>Prova.

• Ställ in fältet ID till 1 och klicka på Kör.

  DELETE-begäran skickas till appen och svaret visas i fönstret Svar. Svarstexten är tom och Server-svaret statuskod är 204.

Testa med andra verktyg

Det finns många andra verktyg som kan användas för att testa webb-API:er, till exempel:

• http-repl
• curl. Swagger använder curl och visar de curl kommandon som skickas.
• Fiddler

Mer information finns i:

• Installera och testa API:er med http-repl

Förhindra överpublicering

För närvarande exponerar exempelappen hela TodoItem objektet. Produktionsappar begränsar vanligtvis de data som matas in och returneras med hjälp av en delmängd av modellen. Det finns flera orsaker till detta, och säkerheten är viktig. Delmängden av en modell kallas vanligtvis för ett dataöverföringsobjekt (DTO), indatamodell eller vymodell. DTO- används i den här handledningen.

En DTO kan användas för att:

• Förhindra överpublicering.
• Dölj egenskaper som klienter inte ska visa.
• Utelämna vissa egenskaper för att minska nyttolaststorleken.
• Platta ut objektdiagram som innehåller kapslade objekt. Utplattade objektdiagram kan vara enklare för klienter.

Om du vill demonstrera DTO-metoden uppdaterar du klassen TodoItem så att den innehåller ett hemligt fält:

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

Det hemliga fältet måste vara dolt från den här appen, men en administrativ app kan välja att exponera det.

Kontrollera att du kan skicka och hämta det hemliga fältet.

Skapa en DTO-modell i en Models/TodoItemsDTO.cs-fil.

namespace TodoApi.Models;

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

Uppdatera TodoItemsController för att använda 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
       };
}

Kontrollera att du inte kan publicera eller hämta det hemliga fältet.

Anropa webb-API:et med JavaScript

Se Självstudie: Anropa ett ASP.NET Core-webb-API med JavaScript.

Videoserie för webb-API

Se Video om: Ny serie för nybörjare om web API:er.

Mönster för företagswebbappar

Vägledning om hur du skapar en tillförlitlig, säker, högpresterande, testbar och skalbar ASP.NET Core-app finns i Enterprise-webbappmönster. En komplett exempelwebbapp av produktionskvalitet som implementerar mönstren är tillgänglig.

Lägga till autentiseringsstöd i ett webb-API

ASP.NET Core Identity lägger till inloggningsfunktioner för användargränssnitt (UI) i ASP.NET Core-webbappar. Om du vill skydda webb-API:er och SPA:er använder du något av följande:

• Microsoft Entra ID
• Azure Active Directory B2C (Azure AD B2C)
• Duende Identity Server

Duende Identity Server är ett OpenID Connect- och OAuth 2.0-ramverk för ASP.NET Core. Duende Identity Server aktiverar följande säkerhetsfunktioner:

• Autentisering som en tjänst (AaaS)
• Enkel inloggning/av(SSO) över flera programtyper
• Åtkomstkontroll för API:er
• Federation Gateway

Viktig

Duende Software kan kräva att du betalar en licensavgift för produktionsanvändning av Duende Identity Server. Mer information finns i Migrera från ASP.NET Core 5.0 till 6.0.

Mer information finns i Duende Identity Server-dokumentationen (Duende Software-webbplatsen).

Publicera till Azure

Information om hur du distribuerar till Azure finns i Snabbstart: Distribuera en ASP.NET webbapp.

Ytterligare resurser

Visa eller ladda ner exempelkod för den här handledningen. Se hur du laddar ned.

Mer information finns i följande resurser:

• Skapa webb-API:er med ASP.NET Core
• Självstudie: Skapa ett minimalt API med ASP.NET Core
• Använd de genererade OpenAPI-dokumenten
• ASP.NET Core web API-dokumentation med Swagger/OpenAPI
• Razor Sidor som använder Entity Framework Core i ASP.NET Core – Guide 1 av 8
• Routning till kontrollantåtgärder i ASP.NET Core
• Controller-åtgärd returnerar typer i ASP.NET Core-webb-API:et
• Distribuera ASP.NET Core-appar till Azure App Service
• Värdskap och distribution av ASP.NET Core
• Skapa ett webb-API med ASP.NET Core