Aspire 13.2 : Ce que les développeurs de services .NET doivent savoir

TL;DR

• CLI est maintenant vraiment scriptable : mode détaché, aspire ps, aspire arrêter, mode isolé, sortie JSON
• TypeScript AppHost est en aperçu si vous voulez abandonner le .csproj pour la couche d'orchestration
• Les fichiers de config sont consolidés dans aspire.config.json (les fichiers hérités migrent automatiquement)
• Foundry remplace Azure AI Foundry. Celui-ci cassera votre build
• WithSecretBuildArg est renommé en WithBuildSecret
• Les variables d'environnement de découverte de services utilisent désormais le schéma, pas le nom de l'endpoint (risque de rupture silencieuse)
• Comportement de la crédential par défaut d'Azure modifié dans les intégrations des clients

Le CLI est enfin un CLI

C'est le titre principal. Avant la version 13.2, aspire run bloquait votre terminal et le tableau de bord était la seule surface réaliste pour gérer un apphost en cours d'exécution. Bien pour un développeur solo, gênant pour le CI, les tests d'intégration, ou tout flux de travail dirigé par un agent.

La version 13.2 corrige cela :

# Run in the background
aspire run --detach

# Or the new shortcut
aspire start

# See what's running
aspire ps

# Stop it
aspire arrêter
aspire arrêter --all

# Run in the background
aspire run --detach

# Or the new shortcut
aspire start

# See what's running
aspire ps

# Stop it
aspire arrêter
aspire arrêter --all

Combiné avec --format json (qui se dirige vers stdout tandis que les messages de statut vont vers stderr, important si vous redirigez quelque part), vous pouvez construire une véritable automatisation autour de cela. aspire ps --resources --format json est un solide bloc de construction pour les intégrations éditeur et les scripts.

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

Configuration : un fichier pour les régner tous

Aspire consolide ses fichiers de configuration. L'ancienne séparation entre .aspire/settings.json et apphost.run.json a disparu, remplacée par un seul aspire.config.json à la racine du projet :

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

La migration est automatique. La première fois que vous exécutez une commande aspire dans un projet existant, les fichiers hérités sont fusionnés dans le nouveau format avec les chemins réattribués à la racine du projet. Les fichiers hérités sont conservés afin que vous puissiez encore utiliser d'anciennes versions du CLI côte à côte. Les paramètres globaux (globalsettings.json) migrent également.

Si vous avez une automatisation qui s'adresse directement à .aspire/settings.json ou apphost.run.json, prévoyez de la déplacer.

TypeScript AppHost (aperçu)

Cela est intéressant même si vous ne l'utilisez pas dès le premier jour. Vous pouvez maintenant écrire votre apphost en TypeScript au lieu de 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();

Sous le capot, l'apphost TS fonctionne comme un processus invité communiquant avec l'hôte d'orchestration .NET d'Aspire via JSON-RPC sur un transport local. Même modèle de ressources, même tableau de bord, mêmes intégrations, exprimé en TypeScript.

La partie intéressante est le codegen. Lorsque vous exécutez aspire add, le CLI inspecte l'assembly .NET de l'intégration et génère un SDK TypeScript dans .modules/. aspire restore les régénère, utile après une mise à niveau ou un changement de branche (s'exécute également automatiquement sur aspire run). Le générateur 13.2 a également ajouté des cibles de test pour Go, Java et Rust, ce qui indique où cela se dirige.

Pour les équipes prioritairement .NET comme la nôtre, c'est plus "regardez ça" que "expédiez ça", mais le schéma de codegen signifie que les futurs langages d'apphost polyglottes suivent tous le même modèle. Voir la documentation sur l'architecture multilingue pour voir comment fonctionne le pont hôte.

Tableau de bord : export/import de télémétrie est le nouveau jouet

Le tableau de bord a obtenu un véritable flux de travail d'exportation/importation. Depuis Paramètres → Gérer, sélectionnez les ressources et les types de télémétrie et exportez-les au format JSON dans une archive zip. Réimportez-les plus tard dans le tableau de bord ou transmettez-les à une autre personne (ou à un LLM) pour analyse.

La commande CLI aspire export produit le même paquet :

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

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

Vraiment utile pour les rapports de bugs. Au lieu de "voici quelques captures d'écran et un fichier journal", vous pouvez joindre un instantané de l'état réel de la télémétrie.

Autres notes du tableau de bord :

• Vous pouvez maintenant définir des paramètres de ressources directement depuis l'interface utilisateur du tableau de bord, avec une option pour les persister dans les secrets utilisateur
• Les variables d'environnement peuvent être exportées sous forme de fichiers .env depuis la vue des détails des ressources
• La disposition du graphe de ressources utilise un positionnement dirigé adaptatif. Les graphiques complexes sont visiblement moins encombrés
• L'API HTTP de télémétrie à /api/telemetry renvoie un JSON OTLP ; prend en charge ?follow=true pour le streaming NDJSON. Les points de terminaison couvrent les ressources, les intervalles, les journaux et les traces (y compris /traces/{traceId} pour une recherche de trace complète)

Le tableau de bord autonome désactive désormais par défaut l'API de télémétrie. Si vous hébergez vous-même le tableau de bord et que vous dépendez de l'API, vous avez besoin de DASHBOARD__API__ENABLED=true plus la configuration d'authentification (DASHBOARD__API__AUTHMODE et DASHBOARD__API__PRIMARYAPIKEY). Les scénarios intégrés à AppHost fonctionnent toujours car Aspire.Hosting connecte automatiquement l'API pour les outils.

Éléments du modèle d'application à noter

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

Intégrations : celles qui comptent

La liste complète est longue. Voici celles que je soulignerais :

• La publication Docker Compose est maintenant stable (était en préversion). AddDockerComposeEnvironment génère un docker-compose.yaml à partir de votre modèle d'application au moment de la publication. Une échappatoire utile lorsque "déployer sur Azure" n'est pas la réponse. Cela vaut la peine de noter si vous livrez des conteneurs qui incluent des dépendances natives, car IronPDF, IronOCR et IronXL prennent tous en charge les conteneurs Linux et Docker proprement, donc le fichier de composition généré fonctionne généralement sans intervention manuelle.
• L'intégration au réseau virtuel Azure (Aspire.Hosting.Azure.Network) vous permet de déclarer des VNets, sous-réseaux, NSGs, passerelles NAT et points de terminaison privés dans l'apphost. AddPrivateEndpoint crée automatiquement des zones DNS privées, des liens de réseaux virtuels et désactive l'accès public sur la cible. C'est le genre de chose qui nécessitait auparavant un fichier Bicep séparé.
• Le Azure Data Lake Storage a obtenu un support d'hébergement et client : AddDataLake, AddDataLakeFileSystem, plus AddAzureDataLakeServiceClient / AddAzureDataLakeFileSystemClient côté client. Enregistrement DI, reprises, vérifications de santé, télémétrie, la pile Aspire habituelle.
• MongoDB EF Core dispose d'une nouvelle intégration client (Aspire.MongoDB.EntityFrameworkCore). AddMongoDbContext<TContext> pour le cas typique, ou EnrichMongoDbContext<TContext>() si vous enregistrez vous-même le DbContext.
• Inference AI Azure prend désormais en charge les embeddings, pas seulement le chat. Enregistrez AddAzureEmbeddingsClient("embeddings").AddEmbeddingGenerator() et injectez IEmbeddingGenerator<string, Embedding<float>>. La variante clé est également disponible.
• Le registre de conteneurs Azure a obtenu WithPurgeTask("0 1 * * *", ago: TimeSpan.FromDays(7), keep: 5), qui prévoit une tâche de purge ACR sur un calendrier cron.
• Support de Bun pour les ressources JavaScript via WithBun(). La fiabilité de Yarn avec AddViteApp a également été corrigée via WithYarn().
• Foundry Microsoft remplace Azure AI Foundry. Aspire.Hosting.Foundry remplace Aspire.Hosting.Azure.AIFoundry. Changement de rupture ; détails ci-dessous.

Mettre le tout ensemble : un service de document dans Aspire 13.2

Voici le schéma que nous utilisons en interne pour tester des scénarios distribués avec nos bibliothèques. Cela vaut la peine de le montrer car la plupart des nouvelles fonctionnalités de la version 13.2 sont payantes dans ce type de configuration multi-services, pas dans les démonstrations gadgets.

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()

Ce que vous obtenez spécifiquement de 13.2 :

• aspire start --isolated vous permet d'exécuter deux copies de ce graphique côte à côte sans conflits de port. Utile lors de la comparaison des branches ou de l'exécution de tests d'intégration parallèles contre le moteur de rendu
• aspire resource renderer rebuild recharge uniquement le moteur de rendu PDF lorsque vous changez un modèle Razor, au lieu de redémarrer l'ensemble du graphique
• aspire wait renderer --status healthy --timeout 120 permet à votre CI de bloquer jusqu'à ce que le rendu Chrome soit initialisé avant d'effectuer les tests de génération PDF
• L'API HTTP de télémétrie et aspire export vous donnent des intervalles formatés OTLP pour chaque appel de rendu, ce qui est la façon dont vous attraperiez réellement une règle CSS lente dans le trafic de production
• WithMcpServer vous permet d'exposer le moteur de rendu comme un outil MCP pour les flux de travail d'agents de codage, utile si vous construisez quelque chose qui génère programmatique des documents

Si vous souhaitez créer un service comme le moteur de rendu ci-dessus, le tutoriel HTML to PDF d'IronPDF passe en revue le côté C#. Pour le travailleur OCR, le guide de démarrage IronOCR couvre les bases.

Changements significatifs qui vont vraiment vous affecter

Dans l'ordre approximatif de probabilité de les rencontrer :

# 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)

Faut-il effectuer la mise à jour ?

Pour un atelier .NET fonctionnel exécutant des applications multi-services localement, oui, à condition d'avoir inventorié les changements significatifs ci-dessus. Les améliorations du CLI à elles seules en valent la peine. Le mode détaché et le mode isolé en particulier corrigent de réels problèmes de workflow.

Pour les utilisateurs de Foundry : le renommage est une migration forcée si vous souhaitez des nouveautés de cette version, planifiez donc en conséquence.

Pour les personnes curieuses de TypeScript : 13.2 est la première version où le hôte d'application TS est suffisamment réel pour être évalué. Encore en prévisualisation, mais ça vaut un vendredi après-midi.

La mise à jour elle-même est une simple ligne de commande si vous êtes déjà sur la version 13.x :

aspire update --self
aspire update

aspire update --self
aspire update

Si vous êtes sur la version 12.x ou antérieure, consultez d'abord le guide de mise à jour. Il y a une étape 13.0 que vous ne pouvez pas ignorer.

Construire des applications .NET distribuées avec des charges de documents ?

Si vos services effectuent de la génération de PDF, de l'OCR, du traitement Excel, des codes-barres ou d'autres formats que nous couvrons, nos bibliothèques sont conçues pour ce type d'installation multi-services, compatible avec les conteneurs qu'Aspire orchestre. Tout prend en charge .NET 10, 9, 8, 7, 6, Framework, et Core, et fonctionne dans les conteneurs Linux, Azure, AWS et sur site.

Quelques endroits pour commencer :

• IronPDF pour la conversion HTML en PDF, l'édition de PDF, la signature et les formulaires. Le centre de tutoriels est le chemin le plus rapide vers un service de rendu fonctionnel
• IronOCR pour l'extraction de texte d'images et de PDF dans plus de 125 langues
• IronXL pour la lecture et écriture d'Excel sans Interop Office
• IronWord pour la génération et l'édition de DOCX
• IronBarcode et IronQR pour la génération et la numérisation de code-barres et de QR
• Iron Suite si vous avez besoin de plus d'un des éléments ci-dessus

Vous pouvez obtenir une clé d'essai de 30 jours et avoir un service PDF ou OCR fonctionnel dans une application Aspire en moins d'une heure. Si vous rencontrez quelque chose d'étrange, notre équipe de support est constituée de véritables ingénieurs, pas d'une file d'attente de triage de tickets.

C'est ça. À la prochaine version.