Быстрый старт: Создание первого Aspire решения

Облачные приложения часто требуют подключения к различным службам, таким как базы данных, хранилища и кэширование решений, поставщиков сообщений или других веб-служб. Aspire предназначен для упрощения подключений и конфигураций между этими типами служб. В этом кратком руководстве показано, как создать шаблонное решение начального приложения Aspire.

В этом кратком руководстве вы изучите следующие задачи:

Prerequisites

Для работы с Aspire вам потребуется установить следующее локально:

• .NET 8.0 или .NET 9.0.
  • Начиная с Aspire версии 9.4, поддерживается .NET версия 10, предварительная версия 5 или более поздняя.
• Подсистема выполнения контейнера, совместимая с OCI, например:
  • Docker рабочий стол или Podman. Дополнительные сведения см. в Контейнерная среда выполнения.
• Интегрированная среда разработки (IDE) или редактор кода, например:
  • Visual Studio 2022 версия 17.9 или более поздняя (необязательно)
  • Visual Studio Code (необязательно)
    • C# Dev Kit: расширение (необязательно)
  • JetBrains Rider с плагином Aspire (необязательно)

Дополнительные сведения см. о Aspire настройке и инструментах и Aspire SDK.

Создайте шаблон Aspire

Чтобы создать новое начальное приложение Aspire, можно использовать Visual Studio, Visual Studio Codeили интерфейс командной строки .NET.

dotnet new install Aspire.ProjectTemplates

dotnet new aspire-starter --use-redis-cache --output AspireSample

Дополнительные сведения о доступных шаблонах см. в Aspire шаблоны.

Тестирование приложения локально

Пример приложения включает фронтенд-приложение Blazor, которое взаимодействует с проектом минимального API. Проект API используется для предоставления поддельных погодных данных интерфейсу. Интерфейсное приложение настроено на использование обнаружения служб для подключения к проекту API. Проект API настроен на использование кэширования выходных данных с помощью Redis. Пример приложения теперь готов к тестированию. Вы хотите проверить следующие условия:

• Данные о погоде извлекаются из проекта API с помощью обнаружения служб и отображаются на странице погоды.
• Последующие запросы обрабатываются с помощью кэширования выходных данных, настроенного интеграцией AspireRedis.

dotnet dev-certs https --trust

dotnet run --project AspireSample/AspireSample.AppHost

1. Приложение отображает Aspire панель управления в веб-браузере. Более подробно посмотрите на панель мониторинга позже. Теперь найдите в списке ресурсов проект веб-интерфейса , и выберите конечную точку проекта localhost.

   

   Домашняя страница приложения веб-интерфейса отображает "Привет, мир!"

2. Перейдите с домашней страницы на страницу погоды в левой части навигации. На странице погоды отображаются данные о погоде. Запишите некоторые значения, представленные в таблице прогнозов.

3. Продолжайте периодически обновлять страницу в течение 10 секунд. В течение 10 секунд кэшированные данные возвращаются. В конечном итоге появляется другой набор погодных данных, так как данные создаются случайным образом и кэш обновляется.

🤓 Поздравляю! Вы создали и запустили свое первое Aspire решение! Чтобы остановить приложение, закройте окно браузера.

Затем изучите структуру и другие функции нового Aspire решения.

Изучите Aspire панель управления

При запуске Aspire проекта панель мониторинга запускается для мониторинга различных частей приложения. Панель мониторинга похожа на следующий снимок экрана:

Посетите каждую страницу с помощью навигации слева, чтобы просмотреть различные сведения о ресурсах Aspire :

• ресурсы: содержит базовую информацию для всех отдельных проектов .NET в проекте Aspire, таких как состояние приложения, адреса конечных точек и загруженные переменные среды.

• Консоль: отображает результаты консоли для каждого из проектов в вашем приложении.

• Структурированные: отображает структурированные логи в табличном формате. Эти журналы также поддерживают базовую фильтрацию, поиск в свободной форме и фильтрацию на уровне журнала. Вы должны увидеть логи из apiservice и webfrontend. Вы можете развернуть сведения о каждой записи журнала, нажав кнопку Просмотреть в правом конце строки.

• трассировки: отображает трассировки вашего приложения, которые могут отслеживать пути запросов через ваш приложение. Найдите запрос /weather и выберите Просмотр в правой части страницы. Панель мониторинга должна отображать запрос на этапах по мере перемещения по различным частям приложения.

  Aspire

• Метрики: Показывает различные инструменты и метрики, отображаемые в приложении, и их соответствующие размеры. Метрики условно отображают фильтры в зависимости от доступных измерений.

  

Для получения дополнительной информации см. обзор панели мониторинга Aspire.

Общие сведения о Aspire структуре решения

Решение состоит из следующих проектов:

• AspireSample.ApiService: проект минимального API используется для предоставления данных интерфейсу. Этот проект зависит от общего проекта AspireSample.ServiceDefaults.
• AspireSample.AppHost: проект оркестратора, предназначенный для подключения и настройки различных проектов и служб приложения. Оркестратор должен быть задан в качестве проекта запуска, и он зависит от проектов AspireSample.ApiService и AspireSample.Web.
• AspireSample.ServiceDefaults: Aspire общий проект для управления конфигурациями, которые повторно используются в проектах в решении, связанном с устойчивостью, обнаружением служб и телеметрией.
• AspireSample.Web: проект приложения ASP.NET CoreBlazor с конфигурациями службы Aspire по умолчанию, этот проект зависит от проекта AspireSample.ServiceDefaults. Дополнительные сведения см. в разделеAspire по умолчанию службы.

Каталог AspireSample должен выглядеть следующим образом:

└───📂 AspireSample
     ├───📂 AspireSample.ApiService
     │    ├───📂 Properties
     │    │    └─── launchSettings.json
     │    ├─── appsettings.Development.json
     │    ├─── appsettings.json
     │    ├─── AspireSample.ApiService.csproj
     │    └─── Program.cs
     ├───📂 AspireSample.AppHost
     │    ├───📂 Properties
     │    │    └─── launchSettings.json
     │    ├─── appsettings.Development.json
     │    ├─── appsettings.json
     │    ├─── AspireSample.AppHost.csproj
     │    └─── AppHost.cs
     ├───📂 AspireSample.ServiceDefaults
     │    ├─── AspireSample.ServiceDefaults.csproj
     │    └─── Extensions.cs
     ├───📂 AspireSample.Web
     │    ├───📂 Components
     │    │    ├───📂 Layout
     │    │    │    ├─── MainLayout.razor
     │    │    │    ├─── MainLayout.razor.css
     │    │    │    ├─── NavMenu.razor
     │    │    │    └─── NavMenu.razor.css
     │    │    ├───📂 Pages
     │    │    │    ├─── Counter.razor
     │    │    │    ├─── Error.razor
     │    │    │    ├─── Home.razor
     │    │    │    └─── Weather.razor
     │    │    ├─── _Imports.razor
     │    │    ├─── App.razor
     │    │    └─── Routes.razor
     │    ├───📂 Properties
     │    │    └─── launchSettings.json
     │    ├───📂 wwwroot
     │    │    ├───📂 bootstrap
     │    │    │    ├─── bootstrap.min.css
     │    │    │    └─── bootstrap.min.css.map
     │    │    ├─── app.css
     │    │    └─── favicon.png
     │    ├─── appsettings.Development.json
     │    ├─── appsettings.json
     │    ├─── AspireSample.Web.csproj
     │    ├─── Program.cs
     │    └─── WeatherApiClient.cs
     └─── AspireSample.sln

Изучение начальных проектов

Каждый проект в Aspire решении играет роль в структуре вашего приложения. *.Web проект — это стандартное ASP.NET CoreBlazor приложение, которое предоставляет интерфейс пользователя. Дополнительные сведения см. в статье Новые возможности ASP.NET Core 9.0: Blazor. *. Проект ApiService — это стандартный проект минимального API шаблона ASP.NET Core. Оба этих проекта зависят от проекта *.ServiceDefaults, который является общим и используется для управления конфигурациями, повторно применяемыми в проектах вашего решения.

Два проекта, представляющие интерес в этом кратком руководстве, - это проекты *.AppHost и *.ServiceDefaults, подробно описанные в следующих разделах.

Aspire хост-проект

*. Проект AppHost отвечает за выполнение роли локального оркестратора разработки:

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

  <Sdk Name="Aspire.AppHost.Sdk" Version="9.5.2" />

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net9.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
    <UserSecretsId>2aa31fdb-0078-4b71-b953-d23432af8a36</UserSecretsId>
  </PropertyGroup>

  <ItemGroup>
    <ProjectReference Include="..\AspireSample.ApiService\AspireSample.ApiService.csproj" />
    <ProjectReference Include="..\AspireSample.Web\AspireSample.Web.csproj" />
  </ItemGroup>

  <ItemGroup>
    <PackageReference Include="Aspire.Hosting.AppHost" Version="9.5.2" />
    <PackageReference Include="Aspire.Hosting.Redis" Version="9.5.2" />
  </ItemGroup>

</Project>

Дополнительные сведения см. в Aspire обзоре оркестрации и пакете Aspire SDK.

Рассмотрим файл AppHost.cs проекта AspireSample.AppHost:

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddRedis("cache");

var apiService = builder.AddProject<Projects.AspireSample_ApiService>("apiservice");

builder.AddProject<Projects.AspireSample_Web>("webfrontend")
    .WithExternalHttpEndpoints()
    .WithReference(cache)
    .WaitFor(cache)
    .WithReference(apiService)
    .WaitFor(apiService);

builder.Build().Run();

Если вы использовали универсальный.NET узел или веб-узел до этого, модель программирования AppHost и ASP.NET Core шаблон построителя должны быть знакомы с вами. Предыдущий код:

• Создает экземпляр IDistributedApplicationBuilder путем вызова DistributedApplication.CreateBuilder().
• Вызывает AddRedis с именем "cache", чтобы добавить в приложение сервер Redis, назначив возвращаемое значение переменной с именем cache, которая имеет тип IResourceBuilder<RedisResource>.
• Вызывает AddProject с помощью параметра универсального типа с подробными сведениями о проекте, добавив проект AspireSample.ApiService в модель приложения. Это один из основных стандартных блоков Aspire, который используется для настройки обнаружения служб и обмена данными между проектами в приложении. Аргумент имени "apiservice" используется для идентификации проекта в модели приложения и используется позже проектами, которые хотят взаимодействовать с ним.
• Вызывает AddProject снова, на этот раз добавляя проект AspireSample.Web в модель приложения. Он также объединяет несколько вызовов к WithReference, передавая переменные cache и apiService. WithReference API является еще одним фундаментальным API системы Aspire, который добавляет информацию об обнаружении сервисов или конфигурацию строки подключения в проект, интегрированный в модель приложения. Кроме того, вызовы API WaitFor используются для обеспечения доступности cache и apiService ресурсов до запуска проекта AspireSample.Web. Дополнительные сведения см. в разделе Aspire Управление — ожидание ресурсов.

Наконец, приложение создается и запускается. Метод DistributedApplication.Run() отвечает за запуск приложения и всех зависимостей. Дополнительные сведения см. в обзореAspire оркестрации.

Aspire проект настроек по умолчанию службы

*.ServiceDefaults проект — это общий проект, используемый для управления конфигурациями, которые повторно используются в проектах вашего решения. Этот проект гарантирует, что все зависимые службы обладают одинаковыми характеристиками устойчивости, сервисом обнаружения и конфигурацией OpenTelemetry. Общий Aspire файл проекта содержит свойство IsAspireSharedProject, установленное как true.

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

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

  <ItemGroup>
    <FrameworkReference Include="Microsoft.AspNetCore.App" />

    <PackageReference Include="Microsoft.Extensions.Http.Resilience" Version="9.10.0" />
    <PackageReference Include="Microsoft.Extensions.ServiceDiscovery" Version="9.5.2" />
    <PackageReference Include="OpenTelemetry.Exporter.OpenTelemetryProtocol" Version="1.13.1" />
    <PackageReference Include="OpenTelemetry.Extensions.Hosting" Version="1.13.1" />
    <PackageReference Include="OpenTelemetry.Instrumentation.AspNetCore" Version="1.13.0" />
    <PackageReference Include="OpenTelemetry.Instrumentation.Http" Version="1.13.0" />
    <PackageReference Include="OpenTelemetry.Instrumentation.Runtime" Version="1.13.0" />
  </ItemGroup>

</Project>

Проект настроек службы по умолчанию предоставляет метод расширения для типа IHostApplicationBuilder с именем AddServiceDefaults. Проект службы по умолчанию из шаблона является отправной точкой, и ее можно настроить в соответствии с вашими потребностями. Дополнительные сведения см. в разделеAspire по умолчанию службы.

Организация взаимодействия сервисов

Aspire предоставляет функции оркестрации для настройки подключений и обмена данными между различными частями приложения. Проект AspireSample.AppHost добавил в модель приложения проекты AspireSample.ApiService и AspireSample.Web. Он также обозначил их как "webfrontend" для внешнего интерфейса Blazor и "apiservice" для ссылки на проект API. Кроме того, добавлен ресурс сервера Redis с меткой "cache". Эти имена используются для настройки обнаружения служб и обмена данными между проектами в приложении.

Фронтенд-приложение определяет типизированный HttpClient, который используется для взаимодействия с API-проектом.

namespace AspireSample.Web;

public class WeatherApiClient(HttpClient httpClient)
{
    public async Task<WeatherForecast[]> GetWeatherAsync(
        int maxItems = 10,
        CancellationToken cancellationToken = default)
    {
        List<WeatherForecast>? forecasts = null;

        await foreach (var forecast in 
            httpClient.GetFromJsonAsAsyncEnumerable<WeatherForecast>(
                "/weatherforecast", cancellationToken))
        {
            if (forecasts?.Count >= maxItems)
            {
                break;
            }
            if (forecast is not null)
            {
                forecasts ??= [];
                forecasts.Add(forecast);
            }
        }

        return forecasts?.ToArray() ?? [];
    }
}

public record WeatherForecast(DateOnly Date, int TemperatureC, string? Summary)
{
    public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
}

HttpClient настроено на использование службы обнаружения. Рассмотрим следующий код из файла Program.cs проекта AspireSample.Web:

using AspireSample.Web;
using AspireSample.Web.Components;

var builder = WebApplication.CreateBuilder(args);

// Add service defaults & Aspire client integrations.
builder.AddServiceDefaults();
builder.AddRedisOutputCache("cache");

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

builder.Services.AddHttpClient<WeatherApiClient>(client =>
    {
        // This URL uses "https+http://" to indicate HTTPS is preferred over HTTP.
        // Learn more about service discovery scheme resolution at https://aka.ms/dotnet/sdschemes.
        client.BaseAddress = new("https+http://apiservice");
    });

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    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();
}

app.UseHttpsRedirection();

app.UseAntiforgery();

app.UseOutputCache();

app.MapStaticAssets();

app.MapRazorComponents<App>()
    .AddInteractiveServerRenderMode();

app.MapDefaultEndpoints();

app.Run();

Предыдущий код:

• Вызовы AddServiceDefaults настраивают общие параметры приложения.
• Вызывает AddRedisOutputCache с использованием того же connectionName, который использовался при добавлении контейнера Redis"cache" в модель приложения. Это настраивает приложение для использования Redis для кэширования выходных данных.
• Вызывает AddHttpClient и настраивает HttpClient.BaseAddress так, чтобы это было "https+http://apiservice". Это название использовалось при добавлении проекта API в модель приложения, а благодаря настроенной службе обнаружения оно автоматически преобразуется в правильный адрес API-проекта.

Дополнительные сведения см. в статье Создание HTTP-запросов с помощью класса HttpClient.

Aspire CLI (интерфейс командной строки)

Aspire Cli (aspireкоманда) — это кроссплатформенное средство, которое предоставляет функциональные возможности командной строки для создания, управления, запуска и публикации проектов polyglotAspire. Aspire Используйте интерфейс командной строки для упрощения рабочих процессов разработки и координации служб для распределенных приложений.

Дополнительные сведения см. в разделеAspire "Обзор интерфейса командной строки" и "Установка Aspire ИНТЕРФЕЙСА командной строки".

См. также

• Aspire Общие сведения об интеграции
• Обнаружение служб в Aspire
• Aspire Значения по умолчанию службы
• Проверка состояния здоровья Aspire
• Aspire телеметрия
• Решение проблем с ненадежным сертификатом localhost в Aspire

Дальнейшие шаги