Aspire 13.2: Co programiści usług .NET muszą wiedzieć

TL;DR

• CLI jest teraz prawdziwie skryptowalne: tryb odłączony, aspire ps, aspire stop, tryb izolowany, wynik JSON
• TypeScript AppHost jest w wersji zapoznawczej, jeśli chcesz zrezygnować z .csproj dla warstwy orkiestracji
• Pliki konfiguracyjne skonsolidowane do aspire.config.json (starsze pliki automatycznie migrowane)
• Foundry zastępuje Azure AI Foundry. To złamie twoją budowę
• WithSecretBuildArg został przemianowany na WithBuildSecret
• Zmienne środowiskowe odkrywania usług teraz korzystają z schematu, a nie z nazwy punktu końcowego (ciche ryzyko przerwania)
• Domyślne zachowanie poświadczeń Azure zmieniło się w integracjach klientów

Konsola CLI to w końcu konsola CLI

To jest nagłówek. Przed wersją 13.2, aspire run blokował Twój terminal, a pulpit nawigacyjny był jedyną realną powierzchnią do zarządzania działającym apphostem. Dobrze dla samotnego programisty, niezręcznie dla CI, testów integracyjnych lub dowolnych przepływów pracy sterowanych agentem.

13.2 to naprawia:

# Run in the background
aspire run --detach

# Or the new shortcut
aspire start

# See what's running
aspire ps

# Stop it
aspire stop
aspire stop --all

# Run in the background
aspire run --detach

# Or the new shortcut
aspire start

# See what's running
aspire ps

# Stop it
aspire stop
aspire stop --all

Połączona z --format json (która idzie na stdout, podczas gdy komunikaty o stanie idą na stderr, co jest ważne, jeśli korzystasz gdziekolwiek z potoków), można zbudować wokół tego prawdziwą automatyzację. aspire ps --resources --format json jest solidnym fundamentem dla integracji edytora i skryptów.

aspire run --isolated
aspire start --isolated

aspire run --isolated
aspire start --isolated

aspire resource api restart
aspire resource api rebuild

aspire resource api restart
aspire resource api rebuild

aspire certs clean
aspire certs trust

aspire secret set ApiKey super-secret-value
aspire secret list --format json

aspire certs clean
aspire certs trust

aspire secret set ApiKey super-secret-value
aspire secret list --format json

aspire wait api --status healthy --timeout 120

aspire wait api --status healthy --timeout 120

Konfiguracja: jeden plik, który rządzi wszystkimi

Aspiruj konsoliduje swoje pliki konfiguracyjne. Stary podział między .aspire/settings.json i apphost.run.json zniknął, zastąpiony przez pojedynczy aspire.config.json w katalogu głównym projektu:

{
  "appHost": {
    "path": "apphost.ts",
    "language": "typescript/nodejs"
  },
  "sdk": { "version": "13.2.0" },
  "channel": "stable",
  "profiles": {
    "default": {
      "applicationUrl": "https://localhost:17000;http://localhost:15000"
    }
  }
}

Migracja jest automatyczna. Za pierwszym razem gdy uruchomisz jakiekolwiek polecenie aspire w istniejącym projekcie, starsze pliki zostaną scalone w nowy format z ścieżkami przeniesionymi do katalogu głównego projektu. Zachowane są starsze pliki, więc w dalszym ciągu możesz używać starszych wersji CLI obok siebie. Globalne ustawienia (globalsettings.json) też są migrowane.

Jeśli masz automatyzację, która bezpośrednio wykorzystuje .aspire/settings.json lub apphost.run.json, zaplanuj jej przeniesienie.

TypeScript AppHost (wersja zapoznawcza)

To interesujące, nawet jeśli nie zamierzasz go używać od pierwszego dnia. Teraz możesz napisać swój apphost w TypeScript zamiast C#:

import { createBuilder } from './.modules/aspire.js';

const builder = await createBuilder();

const cache = await builder.addRedis("cache");

const api = await builder.addProject("api", "../api")
    .withReference(cache)
    .waitFor(cache);

await builder.build().run();

Pod maską, TS apphost działa jako proces gość rozmawiający z zarządzającym przez Aspire hostem orkiestrowania .NET przez JSON-RPC na lokalnym transporcie. Ten sam model zasobów, ten sam dashboard, te same integracje, tylko wyrażone w TypeScript.

Interesujący jest element generacji kodu. Kiedy uruchamiasz aspire add, CLI analizuje .NET asamblaż integracji i generuje TypeScript SDK do .modules/. aspire restore regeneruje je, przydatne po aktualizacji lub przełączeniu gałęzi (również uruchamia się automatycznie na aspire run). Generator 13.2 dodał także cele testowe dla Go, Java i Rust, co sugeruje, dokąd to zmierza.

Dla zespołów w pierwszej kolejności .NET, jak nasze, jest to bardziej "obejrzyj to" niż "wprowadź to", ale wzorzec generacji kodu oznacza, że przyszłe poliglotowe języki apphost będą podążać tym samym modelem. Zobacz dokumentacja architektury wielojęzycznej aby dowiedzieć się, jak działa mostek hosta.

Dashboard: eksport/import telemetryczny to nowa zabawka

Dashboard dostał prawdziwy przepływ pracy eksportu/importu. Z Ustawienia → Zarządzaj, wybierz zasoby i typy telemetryczne, a następnie eksportuj je jako JSON w zipie. Później ponownie importuj do panelu sterowania lub przekaż je komuś innemu (lub LLM) do analizy.

Polecenie CLI aspire export dostarcza ten sam pakiet:

aspire export --output .\artifacts\aspire-export.zip
aspire export <resource>

aspire export --output .\artifacts\aspire-export.zip
aspire export <resource>

Rzeczywiście przydatne do raportów błędów. Zamiast "oto kilka zrzutów ekranu i plik dziennika", możesz dołączyć migawkę aktualnego stanu telemetrii.

Inne notatki dotyczące strony dashboardu:

• Teraz możesz ustawić parametry zasobów bezpośrednio z interfejsu użytkownika dashboardu, z opcją zapisania do tajemnic użytkownika
• Zmienne środowiskowe można eksportować jako pliki .env z widoku szczegółów zasobów
• Układ grafu zasobów używa adaptacyjnego pozycjonowania siłowego. Złożone wykresy są zauważalnie mniej zagracone
• Telemetria HTTP API pod /api/telemetry zwraca OTLP JSON; wspiera ?follow=true dla strumieniowania NDJSON. Punkty końcowe obejmują zasoby, zakresy, logi i ślady (w tym /traces/{traceId} dla pełnego wyszukiwania śladu)

Samodzielny panel sterowania teraz domyślne ustawia API telemetryczne na wyłączone. Jeśli hostujesz pulpit nawigacyjny samodzielnie i zależy Ci na API, potrzebujesz DASHBOARD__API__ENABLED=true oraz skonfigurowania autoryzacji (DASHBOARD__API__AUTHMODE i DASHBOARD__API__PRIMARYAPIKEY). Scenariusze zintegrowane z AppHost nadal działają, ponieważ Aspire.Hosting automatycznie podłącza API do narzędzi.

Części modelu aplikacji warte uwagi

var api = builder.AddProject<Projects.MyApi>("api")
    .WithMcpServer("/mcp");

var api = builder.AddProject<Projects.MyApi>("api")
    .WithMcpServer("/mcp");

Dim api = builder.AddProject(Of Projects.MyApi)("api") _
    .WithMcpServer("/mcp")

var endpoint = redis.GetEndpoint("tcp");

var url = await endpoint.GetValueAsync(new ValueProviderContext {
    Caller = containerApp.Resource,
});

var endpoint = redis.GetEndpoint("tcp");

var url = await endpoint.GetValueAsync(new ValueProviderContext {
    Caller = containerApp.Resource,
});

Dim endpoint = redis.GetEndpoint("tcp")

Dim url = Await endpoint.GetValueAsync(New ValueProviderContext With {
    .Caller = containerApp.Resource
})

builder.AddContainer("worker", "contoso/worker")
    .WithDockerfile("../worker")
    .WithBuildSecret("ACCESS_TOKEN", accessToken);

builder.AddContainer("worker", "contoso/worker")
    .WithDockerfile("../worker")
    .WithBuildSecret("ACCESS_TOKEN", accessToken);

Integracje: te, które mają znaczenie

Pełna lista jest długa. To są te, które bym zaznaczył:

• Publikowanie Docker Compose jest teraz stabilne (było w wersji wstępnej). AddDockerComposeEnvironment generuje docker-compose.yaml z Twojego modelu aplikacji w czasie publikacji. Przydatne jako wyjście awaryjne, gdy 'wdrażanie do Azure' nie jest odpowiedzią. Warto zauważyć, jeśli dostarczasz kontenery zawierające natywne zależności, ponieważ IronPDF, IronOCR i IronXL wszystkie wspierają kontenery Linux i Docker czysto, więc wygenerowany plik komponujący zwykle działa bez ręcznej interwencji.
• Azure Virtual Network integracja (Aspire.Hosting.Azure.Network) pozwala Ci deklarować VNets, podsieci, NSGs, bramy NAT i prywatne punkty końcowe w apphost. AddPrivateEndpoint automatycznie tworzy prywatne strefy DNS, łączy sieci wirtualne i wyłącza publiczny dostęp na celu. To jest ten rodzaj rzeczy, który wcześniej oznaczał utrzymywanie osobnego pliku Bicep.
• Azure Data Lake Storage zyskał wsparcie zarówno od strony hosta, jak i klienta: AddDataLake, AddDataLakeFileSystem, plus AddAzureDataLakeServiceClient / AddAzureDataLakeFileSystemClient po stronie klienta. Rejestracja DI, ponowienia, kontrole stanu zdrowia, telemetria, standardowy stos Aspire.
• MongoDB EF Core ma nową integrację klienta (Aspire.MongoDB.EntityFrameworkCore). AddMongoDbContext<TContext> dla typowego przypadku, lub EnrichMongoDbContext<TContext>(), jeśli sam rejestrujesz DbContext.
• Inferencja AI Azure teraz obsługuje wpasowania, a nie tylko czat. Zarejestruj AddAzureEmbeddingsClient("embeddings").AddEmbeddingGenerator() i wstrzyknij IEmbeddingGenerator<string, Embedding<float>>. Dostępny jest również odmiana z kluczem.
• Azure Container Registry zyskał WithPurgeTask("0 1 * * *", ago: TimeSpan.FromDays(7), keep: 5), które przygotowuje zadanie czyszczenia ACR według harmonogramu crona.
• Bun support dla zasobów JavaScript przez WithBun(). Niezawodność Yarn z AddViteApp została również naprawiona dzięki WithYarn().
• Microsoft Foundry zastępuje Azure AI Foundry. Aspire.Hosting.Foundry zastępuje Aspire.Hosting.Azure.AIFoundry. Zmiana łamiąca; szczegóły poniżej.

Składanie całości: usługa dokumentów w Aspire 13.2

Oto wzór, który stosujemy wewnętrznie do testowania rozproszonych scenariuszy z naszymi bibliotekami. Warto to pokazać, ponieważ większość nowych funkcji w wersji 13.2 ma sens w tego rodzaju złożonej konfiguracji wieloserwisowej, a nie w prostych demonstracjach.

var builder = DistributedApplication.CreateBuilder(args);

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

// A worker service that uses IronPDF for HTML to PDF rendering
var renderer = builder.AddProject<Projects.PdfRenderer>("renderer")
    .WithReference(cache)
    .WaitFor(cache)
    .WithMcpServer("/mcp");

// An OCR worker that uses IronOCR for image and PDF text extraction
var ocr = builder.AddProject<Projects.OcrWorker>("ocr-worker")
    .WithReference(cache);

// API gateway that fans out to both
builder.AddProject<Projects.Api>("api")
    .WithReference(renderer)
    .WithReference(ocr)
    .WaitFor(renderer)
    .WaitFor(ocr);

builder.Build().Run();

var builder = DistributedApplication.CreateBuilder(args);

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

// A worker service that uses IronPDF for HTML to PDF rendering
var renderer = builder.AddProject<Projects.PdfRenderer>("renderer")
    .WithReference(cache)
    .WaitFor(cache)
    .WithMcpServer("/mcp");

// An OCR worker that uses IronOCR for image and PDF text extraction
var ocr = builder.AddProject<Projects.OcrWorker>("ocr-worker")
    .WithReference(cache);

// API gateway that fans out to both
builder.AddProject<Projects.Api>("api")
    .WithReference(renderer)
    .WithReference(ocr)
    .WaitFor(renderer)
    .WaitFor(ocr);

builder.Build().Run();

Imports DistributedApplication

Dim builder = DistributedApplication.CreateBuilder(args)

Dim cache = builder.AddRedis("cache")

' A worker service that uses IronPDF for HTML to PDF rendering
Dim renderer = builder.AddProject(Of Projects.PdfRenderer)("renderer") _
    .WithReference(cache) _
    .WaitFor(cache) _
    .WithMcpServer("/mcp")

' An OCR worker that uses IronOCR for image and PDF text extraction
Dim ocr = builder.AddProject(Of Projects.OcrWorker)("ocr-worker") _
    .WithReference(cache)

' API gateway that fans out to both
builder.AddProject(Of Projects.Api)("api") _
    .WithReference(renderer) _
    .WithReference(ocr) _
    .WaitFor(renderer) _
    .WaitFor(ocr)

builder.Build().Run()

Co konkretnie otrzymujesz od 13.2:

• aspire start --isolated pozwala uruchomić dwie kopie tego grafu obok siebie bez kolizji portów. Przydatne przy porównywaniu gałęzi lub uruchamianiu równoległych testów integracji przeciwko renderującemu
• aspire resource renderer rebuild przeładowuje tylko render PDF, gdy zmieniasz szablon Razor, zamiast odbijać cały graf
• aspire wait renderer --status healthy --timeout 120 pozwala Twojemu CI blokować się do czasu inicjalizacji renderowania Chrome przed rozpoczęciem testów generowania PDF
• Telemetria HTTP API i aspire export daje Ci zakresy w formacie OTLP dla każdego wywołania renderowania, co jest sposobem na uchwycenie wolnej reguły CSS w ruchu produkcyjnym
• WithMcpServer pozwala Ci eksponować renderer jako narzędzie MCP dla przepływów pracy agenta kodowania, przydatne, jeśli budujesz cokolwiek, co programatycznie generuje dokumenty

Jeśli chcesz zbudować usługę taką jak powyższy renderer, samouczek HTML na PDF IronPDF przeprowadza po stronie C#. Dla pracownika OCR, przewodnik po IronOCR obejmuje podstawy.

Zmiany łamiące, które naprawdę cię dotkną

W przybliżonym porządku, jak prawdopodobne są:

# Before (13.0/13.1)
services__myservice__myendpoint__0 = https://localhost:5001

# After (13.2)
services__myservice__https__0 = https://localhost:5001

# Before (13.0/13.1)
services__myservice__myendpoint__0 = https://localhost:5001

# After (13.2)
services__myservice__https__0 = https://localhost:5001

<PackageReference Include="Aspire.Hosting.Foundry" Version="13.2.0" />

<PackageReference Include="Aspire.Hosting.Foundry" Version="13.2.0" />

// Before
var ai = builder.AddAzureAIFoundry("ai");

// After
var foundry = builder.AddFoundry("ai");
var project = foundry.AddProject("agents");
var chat = project.AddModelDeployment("chat", FoundryModel.OpenAI.Gpt5Mini);

// Before
var ai = builder.AddAzureAIFoundry("ai");

// After
var foundry = builder.AddFoundry("ai");
var project = foundry.AddProject("agents");
var chat = project.AddModelDeployment("chat", FoundryModel.OpenAI.Gpt5Mini);

' Before
Dim ai = builder.AddAzureAIFoundry("ai")

' After
Dim foundry = builder.AddFoundry("ai")
Dim project = foundry.AddProject("agents")
Dim chat = project.AddModelDeployment("chat", FoundryModel.OpenAI.Gpt5Mini)

Czy powinieneś zaktualizować?

Dla działającego sklepu .NET z uruchamianiem aplikacji wieloserwisowych lokalnie, tak, o ile zinwentaryzowałeś powyższe zmiany łamiące. Same ulepszenia CLI czynią to wartym zachodu. Tryb odłączony i tryb izolowany w szczególności rozwiązują rzeczywiste problemy z przepływem pracy.

Dla użytkowników Foundry: zmiana nazwy to wymuszona migracja, jeśli chcesz cokolwiek nowego z tego wydania, więc planuj odpowiednio.

Dla osób zaciekawionych TypeScript: 13.2 to pierwsze wydanie, w którym TS apphost jest na tyle realny, by ocenić. Wciąż podgląd, ale warto poświęcić piątkowe popołudnie.

Sama aktualizacja jest jednowierszowa, jeśli już jesteś na 13.x:

aspire update --self
aspire update

aspire update --self
aspire update

Jeśli jesteś na 12.x lub wcześniejszej, sięgnij po przewodnik aktualizacji najpierw. Jest krok 13.0, którego nie można pominąć.

Budowanie rozproszonych aplikacji .NET z obciążeniami dokumentowymi?

Jeśli twoje usługi wykonują generację PDF, OCR, przetwarzanie Excela, kody kreskowe lub inne formaty, które obejmujemy, nasze biblioteki są zaprojektowane dokładnie dla tego rodzaju ustawień wieloserwisowych przyjaznych kontenerom, które Aspire organizuje. Wszystko obsługuje .NET 10, 9, 8, 7, 6, Framework i Core, i działa w kontenerach Linux, Azure, AWS i lokalnie.

Kilka miejsc, od których można zacząć:

• IronPDF dla HTML do PDF, edycji PDF, podpisywania i formularzy. Centrum samouczków to najszybsza droga do działającej usługi renderującej
• IronOCR do ekstrakcji tekstu z obrazów i PDF w ponad 125 językach
• IronXL do odczytu i zapisu Excela bez Office Interop
• IronWord do generowania i edycji DOCX
• IronBarcode i IronQR do generowania i skanowania kodów kreskowych oraz QR
• Iron Suite jeśli potrzebujesz czegoś więcej niż powyższe

Możesz zdobyć 30-dniowy klucz próbny i mieć działającą usługę PDF lub OCR działającą w aplikacji Aspire w mniej niż godzinę. Jeśli napotkasz coś dziwnego, nasza ekipa wsparcia to prawdziwi inżynierowie, nie kolejka triage do zgłoszeń.

To wszystko. Do zobaczenia przy kolejnym wydaniu.