Краткое руководство: создание вашего первого решения .NET.NET Aspire

Статья
12/12/2024

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

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

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

Необходимые условия

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

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

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

Создание шаблона .NET.NET Aspire

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

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

В верхней части окна Visual Studioвыберите команду Файл>Создать>Проект.
В диалоговом окне найдите Aspire и выберите приложение .NET.NET Aspire Starter App. Выберите Далее.
На экране "Настройка нового проекта":
- Введите имя проектаAspireSample.
- Оставьте rest значений по умолчанию и выберите Далее.
На экране Дополнительная информация:
- Убедитесь, что выбран .NET 9.0 (Стандартная поддержка терминов).
- Убедитесь, что установлен флажок Использовать Redis для кэширования (требуется поддерживаемая среда выполнения контейнера), и выберите Создать.
- При необходимости можно выбрать создать проект тестов. Дополнительные сведения см. в статье Запись первого теста .NET.NET Aspire.

Visual Studio создает новое решение, структурированное для применения .NET Aspire.

Visual Studio Code предоставляет шаблоны проектов .NET Aspire, которые обрабатывают некоторые конфигурации начальной настройки. Выполните следующие действия, чтобы создать проект для этого быстрого запуска.

В новом экземпляре Visual Studio Code (без открытой папки) выберите кнопку Создать проект .NET.
Выберите шаблон .NET.NET Aspire начального приложения.

Если вы еще не установили шаблоны .NET.NET Aspire, выполните следующую команду dotnet new install:

dotnet new install Aspire.ProjectTemplates

Предыдущая команда CLI .NET гарантирует наличие доступных шаблонов .NET Aspire. Чтобы создать стартовое приложение .NET.NET Aspire из шаблона, выполните следующую команду dotnet new.

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

Дополнительные сведения см. в статье dotnet new. Интерфейс командной строки .NET создает новое решение, структурированное для использования .NET Aspire.

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

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

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

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

В Visual Studioзадайте проект AspireSample.AppHost в качестве запускаемого проекта, щелкнув проект правой кнопкой мыши в обозревателе решений и выбрав Задать в качестве запускаемого проекта. Возможно, он уже был автоматически задан в качестве запускаемого проекта. После установки нажмите клавиши F5 или (CTRL + F5 для запуска приложения без отладки).

Перед запуском приложения необходимо доверять сертификату ASP.NET Corelocalhost. Выполните следующую команду:

dotnet dev-certs https --trust

Дополнительные сведения см. в статье Устранение неполадок с ненадежным сертификатом localhost в .NET Aspire. Подробные сведения об устранении неполадок с сертификатами localhost на Linuxсм. в статье ASP.NET Core: проблема с репозиторием GitHub #32842.

В Visual Studio Codeнажмите клавишу F5, чтобы запустить приложение. Вам предлагается выбрать язык, и предлагается C#. Выберите C# и выберите проект AspireSample.AppHost сконфигурации по умолчанию:

Если это первый раз, когда вы запускаете .NET Aspire, или это новый компьютер с новой установкой .NET, вам будет предложено установить самозаверяющий сертификат localhost, и проект не сможет запустить:

Выберите Да, и появится информационное сообщение, указывающее, что самозаверяющий сертификат успешно создан:

Если у вас по-прежнему возникла проблема, закройте все окна браузера и повторите попытку. Дополнительные сведения см. в статье Устранение неполадок с ненадежным сертификатом localhost в .NET Aspire.

Совет

Если вы находитесь в MacOS и используете Safari, когда браузер открывается, если страница пуста, может потребоваться вручную обновить страницу.

dotnet run --project AspireSample/AspireSample.AppHost

Для получения дополнительной информации, см. dotnet run.

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

Домашняя страница веб- приложения отображает "Hello, world!"
Перейдите с домашней страницы на страницу погоды в левой части навигации. На странице погоды отображаются данные о погоде. Запишите некоторые значения, представленные в таблице прогнозов.
Продолжайте периодически обновлять страницу в течение 10 секунд. В течение 10 секунд кэшированные данные возвращаются. В конечном итоге появляется другой набор погодных данных, так как данные создаются случайным образом и кэш обновляется.

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

Чтобы остановить приложение в Visual Studio, выберите остановить отладку в меню Отладка.

Чтобы остановить приложение в Visual Studio Code, нажмите клавиши Shift + F5или нажмите кнопку Остановить в центре верхней части окна:

Чтобы остановить приложение, нажмите клавиши CTRL + C в окне терминала.

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

Исследуйте панель мониторинга .NET.NET Aspire

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

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

ресурсы: содержит базовую информацию для всех отдельных проектов .NET в проекте .NET Aspire, таких как состояние приложения, адреса конечных точек и загруженные переменные среды.
Консоль : отображает вывод консоли для каждого проекта в вашем приложении.
Структурированные: отображает структурированные логи в табличном формате. Эти журналы также поддерживают базовую фильтрацию, поиск в свободной форме и фильтрацию на уровне журнала. Вы должны увидеть журналы из apiservice и webfrontend. Вы можете развернуть сведения о каждой записи журнала, нажав кнопку Просмотреть в правом конце строки.
трассировки: отображает трассировки вашего приложения, которые могут отслеживать пути запросов через ваш приложение. Найдите запрос /weather и выберите Просмотр в правой части страницы. Панель мониторинга должна отображать запрос на этапах по мере перемещения по различным частям приложения.
метрик: отображает различные инструменты и метрики, предоставляемые и соответствующие измерения для приложения. Метрики условно предоставляют фильтры на основе их доступных измерений.

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

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

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

AspireSample.ApiService: для предоставления данных интерфейсу используется проект ASP.NET Core Минимального API. Этот проект зависит от общего проекта AspireSample.ServiceDefaults.
AspireSample.AppHost: проект оркестратора, предназначенный для подключения и настройки различных проектов и служб приложения. Оркестратор должен быть задан в качестве проекта запуска, и он зависит от проектов AspireSample.ApiService и AspireSample.Web.
AspireSample.ServiceDefaults: общий проект .NET.NET Aspire для управления конфигурациями, которые повторно используются в проектах в решении, связанных с устойчивостью, обнаружением служби телеметрии.
AspireSample.Web: проект приложения ASP.NET CoreBlazor с конфигурациями службы .NET Aspire по умолчанию, этот проект зависит от проекта AspireSample.ServiceDefaults. Дополнительные сведения см. в разделе .NET.NET 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
     │    └─── Program.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

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

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

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

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

*. Проект AppHost отвечает за роль оркестратора и задает свойство IsAspireHost файла проекта true:

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

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

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net9.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
    <IsAspireHost>true</IsAspireHost>
    <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.0.0" />
    <PackageReference Include="Aspire.Hosting.Redis" Version="9.0.0" />
  </ItemGroup>

</Project>

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

Рассмотрим файл Program.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 универсальный узел, либо ASP.NET Core веб-узел, то модель программирования узла приложения и шаблон построителя должны быть вам знакомы. Предыдущий код:

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

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

Совет

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

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

*.ServiceDefaults проект — это общий проект, используемый для управления конфигурациями, которые повторно используются в проектах вашего решения. Этот проект гарантирует, что все зависимые службы обладают одинаковыми характеристиками устойчивости, сервисом обнаружения и конфигурацией OpenTelemetry. Общий файл проекта .NET.NET 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.0.0" />
    <PackageReference Include="Microsoft.Extensions.ServiceDiscovery" Version="9.0.0" />
    <PackageReference Include="OpenTelemetry.Exporter.OpenTelemetryProtocol" Version="1.10.0" />
    <PackageReference Include="OpenTelemetry.Extensions.Hosting" Version="1.10.0" />
    <PackageReference Include="OpenTelemetry.Instrumentation.AspNetCore" Version="1.10.1" />
    <PackageReference Include="OpenTelemetry.Instrumentation.Http" Version="1.10.0" />
    <PackageReference Include="OpenTelemetry.Instrumentation.Runtime" Version="1.10.0" />
  </ItemGroup>

</Project>

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

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

.NET .NET Aspire предоставляет функции оркестрации для настройки подключений и обмена данными между различными частями приложения. Проект AspireSample.AppHost добавил в модель приложения проекты AspireSample.ApiService и AspireSample.Web. Он также объявил их имена как "webfrontend" для внешнего интерфейса Blazor, "apiservice" для ссылки на проект API. Кроме того, добавлен Redisserver ресурс с меткой "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.

См. также

Обзор интеграции
Обнаружение служб в .NET.NET Aspire
.NET .NET Aspire настройки службы по умолчанию
проверка работоспособности в .NET.NET Aspire
.NET .NET Aspire телеметрии
Решение проблем с ненадежным сертификатом localhost в .NET Aspire

Дальнейшие действия

Руководство по . Добавление .NET Aspire в существующее приложение .NET

Поделиться через