Samouczek: łączenie aplikacji ASP.NET Core z SQL Server przy użyciu .NET Aspire i Entity Framework Core

Artykuł
03/05/2025

W tym samouczku utworzysz aplikację ASP.NET Core korzystającą z integracji .NET AspireEntity Framework CoreSQL Server w celu nawiązania połączenia z SQL Server w celu odczytu i zapisu danych zgłoszenia do pomocy technicznej. Entity Framework Core jest uproszczonym, rozszerzalnym maperem relacyjnym typu open source, który umożliwia deweloperom .NET pracę z bazami danych przy użyciu obiektów .NET. Dowiesz się, jak wykonywać następujące działania:

Tworzenie podstawowej aplikacji .NET skonfigurowanej do korzystania z integracji .NET Aspire
Dodaj integrację .NET Aspire, aby połączyć się z SQL Server
Konfigurowanie i używanie funkcji składnika .NET.NET Aspire do odczytu i zapisu z bazy danych

Warunki wstępne

Aby pracować z .NET.NET Aspire, musisz zainstalować lokalnie:

.NET 8.0 lub .NET 9.0
Środowisko uruchomieniowe kontenera zgodne ze standardem OCI, takie jak:
- Docker Desktop lub Podman. Aby uzyskać więcej informacji, zobacz Container Runtime.
Zintegrowane środowisko deweloperskie (IDE) lub edytor kodu, takie jak:
- Visual Studio 2022 w wersji 17.9 lub nowszej (opcjonalnie)
- Visual Studio Code (opcjonalnie)
  - C# Dev Kit: Rozszerzenie (opcjonalnie)
- JetBrains Rider z wtyczką .NET.NET Aspire (opcjonalnie)

Aby uzyskać więcej informacji, zobacz .NET.NET Aspire setup and toolingi .NET.NET Aspire SDK.

Tworzenie przykładowego rozwiązania

U góry Visual Studioprzejdź do Plik>Nowy>Projekt.
W oknie dialogowym wyszukaj Blazor i wybierz Blazor Web App. Wybierz pozycję Dalej.
Na ekranie Skonfiguruj swój nowy projekt:
- Wprowadź nazwę projektuAspireSQLEFCore.
- Pozostaw pozostałe wartości domyślne i wybierz pozycję Dalej.
Na ekranie Dodatkowe informacje:
- Upewnij się, że wybrano .NET 9.0.
- Upewnij się, że tryb renderowania interaktywnego ma ustawioną wartość None.
- Zaznacz opcję Zarejestruj się w .NET.NET Aspire orchestration i wybierz Utwórz.

Visual Studio tworzy nowe rozwiązanie ASP.NET Core zaprojektowane do wykorzystywania .NET Aspire. Rozwiązanie składa się z następujących projektów:

AspireSQLEFCore: projekt Blazor, który zależy od ustawień domyślnych usługi.
AspireSQLEFCore.AppHost: projekt orkiestratora zaprojektowany pod kątem łączenia i konfigurowania różnych projektów i usług aplikacji. Orkiestrator powinien być ustawiony jako projekt startowy.
AspireSQLEFCore.ServiceDefaults: udostępniona biblioteka klas do przechowywania konfiguracji, które mogą być ponownie wykorzystywane w projektach rozwiązania.

Tworzenie modelu bazy danych i klas kontekstu

Aby reprezentować wniosek o pomoc zgłoszony przez użytkownika, dodaj następującą klasę modelu SupportTicket w głównej strukturze projektu AspireSQLEFCore.

using System.ComponentModel.DataAnnotations;

namespace AspireSQLEFCore;

public sealed class SupportTicket
{
    public int Id { get; set; }
    [Required]
    public string Title { get; set; } = string.Empty;
    [Required]
    public string Description { get; set; } = string.Empty;
}

Na poziomie głównym projektu AspireSQLEFCore dodaj następującą klasę kontekstu danych TicketDbContext. Klasa dziedziczy System.Data.Entity.DbContext, aby współpracować z Entity Framework i reprezentować bazę danych.

using Microsoft.EntityFrameworkCore;
using System.Reflection.Metadata;

namespace AspireSQLEFCore;

public class TicketContext(DbContextOptions options) : DbContext(options)
{
    public DbSet<SupportTicket> Tickets => Set<SupportTicket>();
}

Dodawanie integracji .NET Aspire do aplikacji Blazor

Dodaj pakiet biblioteki Sql do projektu AspireSQLEFCore:

dotnet add package Aspire.Microsoft.EntityFrameworkCore.SqlServer

Twój projekt AspireSQLEFCore jest teraz skonfigurowany do korzystania z integracji .NET.NET Aspire. Oto zaktualizowany plik AspireSQLEFCore.csproj:

<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFramework>net9.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Aspire.Microsoft.EntityFrameworkCore.SqlServer" Version="9.1.0" />
  </ItemGroup>

  <ItemGroup>
    <ProjectReference Include="..\AspireSQLEFCore.ServiceDefaults\AspireSQLEFCore.ServiceDefaults.csproj" />
  </ItemGroup>

</Project>

Konfigurowanie integracji .NET.NET Aspire

W pliku Program.cs projektu AspireSQLEFCore dodaj wywołanie metody rozszerzenia AddSqlServerDbContext po utworzeniu builder, ale przed wywołaniem AddServiceDefaults. Aby uzyskać więcej informacji, zobacz ustawienia domyślne usługi .NET.NET Aspire. Podaj nazwę ciągu połączenia jako parametr.

using AspireSQLEFCore;
using AspireSQLEFCore.Components;

var builder = WebApplication.CreateBuilder(args);
builder.AddSqlServerDbContext<TicketContext>("sqldata");

builder.AddServiceDefaults();

// Add services to the container.
builder.Services.AddRazorComponents().AddInteractiveServerComponents();

var app = builder.Build();

app.MapDefaultEndpoints();

Ta metoda wykonuje następujące zadania:

Rejestruje TicketContext w kontenerze DI na potrzeby połączenia z konteneryzowaną bazą danych SQL Azure.
Automatyczne włączanie odpowiednich kontroli kondycji, rejestrowania i telemetrii.

Tworzenie bazy danych

Podczas tworzenia aplikacji lokalnie należy utworzyć bazę danych wewnątrz kontenera SQL Server. Zaktualizuj plik Program.cs przy użyciu następującego kodu:

using AspireSQLEFCore;
using AspireSQLEFCore.Components;

var builder = WebApplication.CreateBuilder(args);
builder.AddSqlServerDbContext<TicketContext>("sqldata");

builder.AddServiceDefaults();

// Add services to the container.
builder.Services.AddRazorComponents().AddInteractiveServerComponents();

var app = builder.Build();

app.MapDefaultEndpoints();

if (app.Environment.IsDevelopment())
{
    using (var scope = app.Services.CreateScope())
    {
        var context = scope.ServiceProvider.GetRequiredService<TicketContext>();
        context.Database.EnsureCreated();
    }
}
else
{
    app.UseExceptionHandler("/Error", createScopeForErrors: true);
    // The default HSTS value is 30 days.
    // You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
    app.UseHsts();
}

Powyższy kod:

Sprawdza, czy aplikacja jest uruchomiona w środowisku projektowym.
Jeśli tak jest, pobiera usługę TicketContext z kontenera DI i wywołuje Database.EnsureCreated(), aby utworzyć bazę danych, jeśli jeszcze nie istnieje.

Notatka

Należy pamiętać, że EnsureCreated() nie jest odpowiednia dla środowisk produkcyjnych i tworzy bazę danych tylko zgodnie z definicją w kontekście. Nie stosuje żadnych migracji. Aby uzyskać więcej informacji na temat migracji Entity Framework Core w .NET Aspire, zobacz , jak zastosować migracje Entity Framework Core w .NET Aspire.

Tworzenie formularza

Aplikacja wymaga formularza, aby użytkownik mógł przesyłać informacje o zgłoszeniach pomocy technicznej i zapisywać te dane w bazie danych.

Użyj następującego znacznika Razor, aby utworzyć podstawowy formularz, zastępując zawartość pliku Home.razor w katalogu AspireSQLEFCore/Components/Pages.

@page "/"
@inject TicketContext context
@using Microsoft.EntityFrameworkCore

<div class="row">
    <div class="col-md-6">
        <div>
            <h1 class="display-4">Request Support</h1>
        </div>
        <EditForm Model="@Ticket" FormName="Tickets" method="post"
                  OnValidSubmit="@HandleValidSubmit" class="mb-4">
            <DataAnnotationsValidator />
            <div class="mb-4">
                <label>Issue Title</label>
                <InputText class="form-control" @bind-Value="@Ticket.Title" />
                <ValidationMessage For="() => Ticket.Title" />
            </div>
            <div class="mb-4">
                <label>Issue Description</label>
                <InputText class="form-control" @bind-Value="@Ticket.Description" />
                <ValidationMessage For="() => Ticket.Description" />
            </div>
            <button class="btn btn-primary" type="submit">Submit</button>
            <button class="btn btn-danger mx-2" type="reset" @onclick=@ClearForm>Clear</button>
        </EditForm>

        <table class="table table-striped">
            @foreach (var ticket in Tickets)
            {
                <tr>
                    <td>@ticket.Id</td>
                    <td>@ticket.Title</td>
                    <td>@ticket.Description</td>
                </tr>
            }
        </table>
    </div>
</div>

@code {
    [SupplyParameterFromForm(FormName = "Tickets")]
    private SupportTicket Ticket { get; set; } = new();

    private List<SupportTicket> Tickets = [];

    private void ClearForm() => Ticket = new();

    protected override async Task OnInitializedAsync()
    {
        Tickets = await context.Tickets.ToListAsync();
    }

    private async Task HandleValidSubmit()
    {
        context.Tickets.Add(Ticket);

        await context.SaveChangesAsync();

        Tickets = await context.Tickets.ToListAsync();

        ClearForm();
    }
}

Aby uzyskać więcej informacji na temat tworzenia formularzy w Blazor, zobacz omówienie formularzy ASP.NET CoreBlazor.

Konfigurowanie hosta AppHost

Projekt AspireSQLEFCore.AppHost jest koordynatorem dla twojej aplikacji. Odpowiada za łączenie i konfigurowanie różnych projektów i usług aplikacji. Orkiestrator powinien być ustawiony jako projekt startowy.

Dodaj pakiet .NET Aspire Hosting Sql Server NuGet do projektu AspireStorage.AppHost:

dotnet add package Aspire.Hosting.SqlServer

Zastąp zawartość pliku w projekcie AspireSQLEFCore.AppHost następującym kodem:

var builder = DistributedApplication.CreateBuilder(args);

var sql = builder.AddSqlServer("sql")
                 .AddDatabase("sqldata");

builder.AddProject<Projects.AspireSQLEFCore>("aspiresql")
       .WithReference(sql)
       .WaitFor(sql);

builder.Build().Run();

Powyższy kod dodaje do aplikacji zasób kontenera SQL Server i konfiguruje połączenie z bazą danych o nazwie sqldata. Skonfigurowane wcześniej klasy programu Entity Framework będą automatycznie używać tego połączenia podczas migrowania i nawiązywania połączenia z bazą danych.

Uruchamianie i testowanie aplikacji lokalnie

Przykładowa aplikacja jest teraz gotowa do testowania. Sprawdź, czy przesłane dane formularza są utrwalane w bazie danych, wykonując następujące czynności:

Wybierz przycisk uruchamiania w górnej części Visual Studio (lub F5), aby uruchomić pulpit nawigacyjny projektu .NET.NET Aspire w przeglądarce.
Na stronie projektów, w wierszu AspireSQLEFCore, kliknij link w kolumnie Endpoints, aby otworzyć interfejs użytkownika aplikacji.
Wprowadź przykładowe dane w polach formularza Title i Description.
Wybierz przycisk Prześlij, a formularz przesyła zgłoszenie do pomocy technicznej do przetworzenia — (a następnie wybierz Wyczyść, aby wyczyścić formularz).
Przesłane dane są wyświetlane w tabeli w dolnej części strony po ponownym załadowaniu strony.
Zamknij karty przeglądarki internetowej, które wyświetlają aplikację internetową AspireSQL i pulpit nawigacyjny .NET.NET Aspire.
Przejdź do Visual Studio i, aby zatrzymać debugowanie, wybierz przycisk zatrzymania lub naciśnij Shift + F5.
Aby rozpocząć debugowanie po raz drugi, wybierz przycisk uruchamiania w górnej części Visual Studio (lub F5).
Na panelu sterowania .NET.NET Aspire, na stronie projektów, w wierszu AspireSQLEFCore, kliknij link w kolumnie Endpoints, aby otworzyć interfejs użytkownika Twojej aplikacji.
Zwróć uwagę, że strona nie wyświetla zgłoszenia utworzonego w poprzednim uruchomieniu.
Zamknij karty przeglądarki internetowej, które wyświetlają aplikację internetową AspireSQL i pulpit nawigacyjny .NET.NET Aspire.
Przejdź do Visual Studio i, aby zatrzymać debugowanie, wybierz przycisk zatrzymania lub naciśnij Shift + F5.

Utrwalanie danych przez ponowne uruchomienia

Deweloperzy często wolą, aby ich dane były trwałe przez kolejne ponowne uruchomienia w środowisku deweloperskim, aby móc testować kod na bardziej realistycznej bazie danych. Aby zaimplementować trwałość w .NET.NET Aspire, użyj metody WithDataVolume. Ta metoda dodaje wolumin Docker do kontenera bazy danych, który nie zostanie zniszczony za każdym razem, gdy ponownie uruchomisz debugowanie.

W Visual Studiow projekcie AspireSQLEFCore.AppHost kliknij dwukrotnie plik źródłowy Program.cs.

Znajdź następujący kod:

var sql = builder.AddSqlServer("sql")
                 .AddDatabase("sqldata");

Zmodyfikuj ten kod, aby był zgodny z następującymi elementami:

var sql = builder.AddSqlServer("sql")
                 .WithDataVolume()
                 .AddDatabase("sqldata");

Uruchamianie i testowanie trwałości danych

Sprawdźmy, jak wolumin danych zmienia zachowanie rozwiązania:

Wybierz przycisk uruchamiania w górnej części Visual Studio (lub F5), aby uruchomić pulpit nawigacyjny projektu .NET.NET Aspire w przeglądarce.
Na stronie projektów, w wierszu AspireSQLEFCore, kliknij link w kolumnie Endpoints, aby otworzyć interfejs użytkownika aplikacji.
Wprowadź przykładowe dane w polach formularza Title i Description.
Wybierz przycisk Prześlij, a formularz wyśle zgłoszenie pomocy technicznej do przetworzenia — następnie wybierz przycisk Wyczyść, aby wyczyścić formularz.
Przesłane dane są wyświetlane w tabeli w dolnej części strony po ponownym załadowaniu strony.
Zamknij karty przeglądarki internetowej, które wyświetlają aplikację internetową AspireSQL i pulpit nawigacyjny .NET.NET Aspire.
Przejdź do Visual Studio i, aby zatrzymać debugowanie, wybierz przycisk zatrzymania lub naciśnij Shift + F5.
Aby rozpocząć debugowanie po raz drugi, wybierz przycisk uruchamiania w górnej części Visual Studio (lub F5).
W panelu sterowania .NET.NET Aspire, na stronie projektów, w wierszu AspireSQLEFCore, kliknij link w kolumnie Endpoints, aby otworzyć interfejs użytkownika swojej aplikacji.
Zwróć uwagę, że strona teraz wyświetla zgłoszenie utworzone w poprzednim cyklu.

Udostępnij za pośrednictwem