Aspire 13.2: .NET Servis Geliştiricilerinin Bilmesi Gerekenler

Özet

• CLI artık gerçekten script yazılabilir: ayrık mod, aspire ps, aspire dur, izole mod, JSON çıktısı
• TypeScript AppHost, örgü katmanı için .csproj bırakmak isterseniz önizlemede
• Konfigürasyon dosyaları aspire.config.json 'a birleştirildi (eski dosyalar otomatik olarak taşınır)
• Foundry, Azure AI Foundry'nin yerine geçti. Bu, yapınızı bozacaktır
• WithSecretBuildArg, WithBuildSecret olarak yeniden adlandırıldı
• Hizmet keşfi ortam değişkenleri şimdi uç nokta adı yerine şemayı kullanır (sessiz kırılma riski)
• Klient entegrasyonlarında varsayılan Azure kimlik bilgisi davranışı değişti

CLI nihayet bir CLI

Bu başlıktır. 13.2 Öncesi, aspire run terminalinizi kilitlerdi ve gösterge tablası, çalışan bir apphost'u yönetmek için tek gerçekçi yüzeydi. Tek geliştirici için iyi, CI, entegrasyon testleri veya herhangi bir ajan odaklı iş akışı için garip.

13.2 bunu düzeltiyor:

# Run in the background
aspire run --detach

# Or the new shortcut
aspire start

# See what's running
aspire ps

# Stop it
aspire dur
aspire dur --all

# Run in the background
aspire run --detach

# Or the new shortcut
aspire start

# See what's running
aspire ps

# Stop it
aspire dur
aspire dur --all

Bu, --format json ile birleştiğinde (durum mesajları stderr'e giderken stdout'a gider, herhangi bir yere yönlendiriyorsanız önemlidir), bunun etrafında gerçek otomasyon kurabilirsiniz. aspire ps --resources --format json, editör entegrasyonları ve scriptler için sağlam bir yapı taşıdır.

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

Yapılandırma: hepsini yöneten bir dosya

Aspire yapılandırma dosyalarını birleştiriyor. Eski .aspire/settings.json ve apphost.run.json arasındaki ayrım ortadan kalktı, projenin kökünde tek bir aspire.config.json ile değiştirildi:

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

Göç otomatik. Mevcut bir projede herhangi bir aspire komutunu ilk çalıştırdığınızda, eski dosyalar yeni biçime proje köküne yeniden temellendirilerek birleşir. Eski dosyalar korunur, böylece eski CLI sürümlerini yan yana kullanabilirsiniz. Küresel ayarlar (globalsettings.json) da taşınır.

.aspire/settings.json veya apphost.run.json 'ya doğrudan erişen otomasyonunuz varsa, bunu taşımayı planlayın.

TypeScript AppHost (önizleme)

Bu, ilk gün kullanmayacak olsanız bile ilginç. Artık uygulama barındırıcınızı TypeScript ile yazabilirsiniz:

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

Arkada, TS uygulama barındırıcısı, Aspire'ın .NET orkestrasyon barındırıcısı ile JSON-RPC üzerinden yerel bir iletimde konuşan bir misafir süreci olarak çalışır. Aynı kaynak modeli, aynı gösterge paneli, aynı entegrasyonlar, sadece TypeScript ile ifade edilir.

İlginç kısım kod üretimidir. Ne zaman aspire add çalıştırırsanız, CLI entegrasyonun .NET bileşimini inceler ve .modules/ 'e bir TypeScript SDK oluşturur. aspire restore onları yeniden oluşturur, yükseltme veya dallar arasında geçiş yaptıktan sonra kullanışlıdır (aynı zamanda aspire run üzerinde otomatik olarak çalışır). 13.2 jeneratörü ayrıca Go, Java ve Rust test hedeflerini ekledi, bu da bunun nereye gittiğini ima eder.

.NET-öncelikli ekipler için bu "bunu izleyin" daha çok "bunu yayım yapın" demek, ancak kod üretim deseni, gelecekteki çok dilli uygulama barındırıcı dillerinin tümünün aynı modelli izlemesi anlamına gelir. Ev sahibi köprünün nasıl çalıştığı hakkında bilgi için çok dilli mimari belgelerine bakın.

Gösterge Paneli: telemetri dışa aktarma/içe aktarma yeni oyuncak

Gösterge paneli gerçek bir dışa aktarma/içe aktarma iş akışı kazandı. Ayarlar → Yönet bölümünden kaynakları ve telemetri türlerini seçin ve bunları bir zip içinde JSON olarak dışa aktarın. Daha sonra kontrol paneline geri getirin veya başkasına (veya bir LLM'ye) analiz için teslim edin.

aspire export CLI komutu aynı demeti üretir:

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

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

Gerçekten hata raporları için faydalıdır. "İşte bazı ekran görüntüleri ve bir günlük dosyası" yerine, gerçek telemetri durumunun bir anlık görüntüsünü ekleyebilirsiniz.

Diğer kontrol paneli notları:

• Artık kaynak parametrelerini gösterge panosu UI'sinden doğrudan ayarlayabilirsiniz, kullanıcı sırlarına kalıcı hale getirme seçeneği ile
• Ortam değişkenleri .env dosyaları olarak kaynak detay görünümünden dışa aktarılabilir
• Kaynak grafiği yerleşimi uyarlanabilir güç yönlendirmeli konumlandırma kullanır. Karmaşık grafikler fark edilir şekilde daha az karışık
• Telemetri HTTP API /api/telemetry OTLP JSON döndürür; NDJSON akışı için ?follow=true 'ı destekler. Uç noktalar, kaynakları, süreleri, günlükleri ve izleri kapsar (tam iz araması için /traces/{traceId} dahil)

Bağımsız gösterge paneli artık varsayılan olarak telemetri API'sını kapalı olarak ayarlar. Gösterge panelini kendiniz barındırıyorsanız ve API'ye güveniyorsanız, DASHBOARD__API__ENABLED=true artı kimlik doğrulama yapılandırmasına (DASHBOARD__API__AUTHMODE ve DASHBOARD__API__PRIMARYAPIKEY) ihtiyacınız var. AppHost ile entegre senaryolar hala çalışır çünkü Aspire.Hosting, API'yi otomatik olarak araçlar için bağlar.

Uygulama modeli önemli parçalar

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

Entegrasyonlar: önemli olanlar

Tam liste uzundur. Bunlar üzerinde duracağım başlıca olanlar:

• Docker Compose yayınlama artık kararlı (önizleme sürümündeydi). AddDockerComposeEnvironment yayınlama sırasında uygulama modelinizden bir docker-compose.yaml oluşturur. 'Azure'a dağıt' cevabı olmadığında kullanışlı bir kaçış kapısı. Eğer yerleşik bağımlılıkları içeren konteynerleri yayımlıyorsanız not almaya değer, çünkü IronPDF, IronOCR ve IronXL hepsi Linux konteynerleri ve Docker'ı temiz bir şekilde destekler, bu yüzden üretilen compose dosyası genellikle manuel cerrahiye ihtiyaç duymadan çalışır.
• Azure Sanal Ağ entegrasyonu (Aspire.Hosting.Azure.Network) apphost içinde VNet'ler, alt ağlar, NSG'ler, NAT geçitleri ve özel uç noktalar beyan etmenize olanak tanır. AddPrivateEndpoint hedef üzerinde otomatik olarak özel DNS bölgeleri, sanal ağ bağlantıları oluşturur ve genel erişimi devre dışı bırakır. Bu, daha önce ayrı bir Bicep dosyasının korunması anlamına geliyordu.
• Azure Veri Gölü Depolaması hem barındırma hem de istemci desteği aldı: AddDataLake, AddDataLakeFileSystem, artı istemci tarafında AddAzureDataLakeServiceClient / AddAzureDataLakeFileSystemClient. DI kayıt, yeniden denemeler, sağlık kontrolleri, telemetri, olağan Aspire yığını.
• MongoDB EF Core yeni bir istemci entegrasyonuna sahiptir (Aspire.MongoDB.EntityFrameworkCore). Tipik durum için AddMongoDbContext<TContext> veya DbContext'i kendiniz kaydediyorsanız EnrichMongoDbContext<TContext>().
• Azure AI Çıkarım artık yalnızca sohbet değil, gömülü tanıtımlar destekler. AddAzureEmbeddingsClient("embeddings").AddEmbeddingGenerator()'yi kaydedin ve IEmbeddingGenerator<string, Embedding<float>>'i enjekte edin. Anahtar varyantı da mevcut.
• Azure Container Registry, bir cron zamanlamasında bir ACR temizleme görevi sağlayan WithPurgeTask("0 1 * * *", ago: TimeSpan.FromDays(7), keep: 5) aldı.
• JavaScript kaynakları için WithBun() ile Bun desteği. Yarn güvenilirliği AddViteApp ile WithYarn() üzerinden düzeltildi.
• Microsoft Foundry, Azure AI Foundry'nin yerini aldı. Aspire.Hosting.Foundry, Aspire.Hosting.Azure.AIFoundry yerine geçer. Kırıcı değişiklik; ayrıntılar aşağıda.

Birleştirmek: Aspire 13.2'de bir belge hizmeti

Kütüphanelerimizle dağıtılmış senaryoları test etmek için dahili olarak çalıştırdığımız desen burada. Gösterilmeye değer çünkü çoğu yeni 13.2 özelliği bu tür bir çoklu hizmet kurulumunda ödül verir, oyuncak demolarında değil.

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

13.2'den özel olarak elde ettikleriniz:

• aspire start --isolated, bu grafikten iki kopyayı yan yana çalıştırmanıza olanak tanır, aynı port çakışması olmadan. Dalların karşılaştırılması veya paralel entegrasyon testlerinin oluşturucuya karşı çalıştırılması sırasında faydalıdır
• aspire resource renderer rebuild, bir Razor şablonunu değiştirdiğinizde, tüm grafiği dalgalanmaktan ziyade yalnızca PDF oluşturucusunu yeniden yükler
• aspire wait renderer --status healthy --timeout 120, Chrome oluşturma başlatılana kadar CI'nizin blok yapmasına ve PDF üretim testlerini çalıştırmadan önce beklemesine olanak tanır
• Telemetri HTTP API ve aspire export size her render çağrısı için OTLP formatlı süreler verir, bu da aslında üretim trafiğinde yavaş bir CSS kuralını yakalamanızın yoludur
• WithMcpServer, kodlama-ajans iş akışları için oluşturucu olarak MCP aracı olarak kullanmanıza olanak tanır, bir şey programlı olarak belgeler üretici oluşturuyorsanız kullanışlıdır

Yukarıdaki render gibi bir hizmet oluşturmak istiyorsanız, IronPDF'nin HTML to PDF eğitimi C# tarafını anlatır. OCR işçisi için, IronOCR başlangıç kılavuzu temelleri kapsar.

Gerçekten sizi etkileyecek olan köklü değişiklikler

Karşılaşma olasılığınıza göre kabaca sırayla:

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

Yükseltme yapmalı mısınız?

Çok servisli uygulamaları yerel olarak çalıştıran bir .NET dükkanı için, evet, yukarıdaki bozucu değişiklikleri envanterine almışsanız. Sadece CLI iyileştirmeleri bile buna değer kılıyor. Özellikle ayrılmış mod ve izole mod, gerçek iş akışı problemlerini düzeltir.

Foundry kullanıcıları için: Bu sürümden yeni bir şey istiyorsanız, yeniden adlandırma zorunlu bir geçiştir, bu nedenle buna göre plan yapın.

TypeScript meraklıları için: 13.2, TS apphost'un değerlendirilebilecek kadar gerçek olduğu ilk sürümdür. Hâlâ önizleme, ama bir cuma öğleden sonrası için değer.

Zaten 13.x sürümündeyseniz, yükseltme işlemi sadece tek satırlık bir işlemdir:

aspire update --self
aspire update

aspire update --self
aspire update

12.x ya da daha önceki bir sürümü kullanıyorsanız, önce yükseltme kılavuzu'na göz atın. 13.0'da atlayamayacağınız bir adım var.

Belge iş yükleri ile dağıtılmış .NET uygulamaları mı geliştiriyorsunuz?

Hizmetleriniz PDF oluşturma, OCR, Excel işleme, barkodlar veya kapsadığımız diğer formatları yapıyorsa, kütüphanelerimiz Aspire'ın düzenlediği çoklu hizmet ve konteyner dostu kuruluma tam olarak uyacak şekilde tasarlanmıştır. Her şey .NET 10, 9, 8, 7, 6, Framework ve Core'u destekler ve Linux konteynerlerinde, Azure, AWS ve yerinde çalışır.

Başlamak için birkaç yer:

• IronPDF ile HTML'den PDF'ye dönüştürme, PDF düzenleme, imzalama ve formlar için. Eğitim merkezi çalışan bir render hizmetine erişmenin en hızlı yoludur
• IronOCR ile 125'ten fazla dilde görüntü ve PDF metin çıkarımı
• IronXL ile Office Interop kullanmadan Excel okuma/yazma
• IronWord ile DOCX oluşturma ve düzenleme
• IronBarcode ve IronQR ile barkod ve QR oluşturma ve tarama
• Iron Suite yukarıdakilerden birden fazlasına ihtiyacınız varsa

Bir 30 günlük deneme anahtarı alabilir ve bir Aspire apphost içinde çalışan bir PDF veya OCR servisine bir saatten kısa sürede sahip olabilirsiniz. Beklenmedik bir durumla karşılaşırsanız, destek ekibimiz bir bilet önceliklendirme kuyruğu değil, gerçek mühendislerden oluşmaktadır.

İşte bu kadar. Bir sonraki sürümde görüşmek üzere.