.NET Aspire 8'den Aspire 13.6'ya: Sürüm Geçmişi, Breaking Change'ler ve Eski Projeyi Taşımak

Sürüm notu: Bu yazıdaki kodlar .NET 10 ve Aspire CLI 13.6.5 ile derlenip denenmiştir; taşıdığımız proje Aspire 9.5.2 template'iyle ve net9.0 hedefiyle oluşturuldu. Sürüm tarihleri aspire.dev sürüm notlarından ve paketlerin NuGet'teki yayın tarihlerinden alındı.

Önce Tahmin Et

Elinde Aspire 9.5 ile yazılmış bir AppHost var: SDK proje dosyasında ayrı bir <Sdk> elementi, Angular'ı başlatan bir AddNpmApp, başlangıçta log yazan bir lifecycle hook. Aspire CLI 13.6.5 ile aspire update çalıştırıyorsun ve "Update successful" görüyorsun. Sence şu üçünden hangileri değişti: hedef framework (net9.0), adı değişen Aspire.Hosting.NodeJs paketi, ServiceDefaults'taki OpenTelemetry paketleri? Ve proje build olur mu, çalışır mı? Bu yazının ikinci yarısında bunu gerçek bir taşımayla görüyoruz; ilk yarısı aradaki iki yılın kısa bir haritası.

Sürüm Çizgisi: 8.0'dan 13.6'ya

9.5'ten sonra numara doğrudan 13'e geçti; 10–12 sürümleri yok. 13.x'te minor sürümler ortalama iki ayda bir çıktı ve her biri kendi breaking change listesiyle geliyor. Bu yüzden "Aspire'ı en son ne zaman güncelledik?" sorusu, bir .NET sürüm yükseltmesinden daha sık sorulmalı.

8.x: Workload, Manifest ve azd

İlk sürümde Aspire bir .NET workload'uydu: dotnet workload install aspire ile SDK'nın içine kuruluyor, AppHost projesi <IsAspireHost>true</IsAspireHost> ile işaretleniyordu. Bu, Aspire sürümünü makinedeki SDK kurulumuna bağlıyordu: aynı makinede iki farklı Aspire sürümüyle çalışmak zordu, CI'da da workload kurulumu ayrı bir adımdı. Deploy tarafında AppHost bir manifest (aspire-manifest.json) üretiyordu ve bu manifest'i Azure Developer CLI (azd) okuyup Azure Container Apps'e çeviriyordu. Bu bölümü çalıştırmadık: workload kurmak makinedeki .NET SDK kurulumunu değiştirir. Doküman 8.x'ten gelen projeler için önce 9.x'e, sonra 13'e geçmeyi öneriyor.

9.x: Workload'suz SDK, WaitFor ve CLI

9.0 (12 Kasım 2024) workload'u kaldırdı: AppHost proje dosyasına <Sdk Name="Aspire.AppHost.Sdk" Version="9.0.0" /> satırı ve Aspire.Hosting.AppHost paketi eklendi, template'ler dotnet new install Aspire.ProjectTemplates ile NuGet paketi olarak geldi. Böylece Aspire sürümü projeyle birlikte gidiyor. Aynı sürüm bu serinin 02. yazısındaki üç özelliği getirdi: WaitFor ve WaitForCompletion, ContainerLifetime.Persistent ve dashboard'a eklenebilen resource komutları. 9.x boyunca .NET 8 ve 9 destekleniyordu. 9.4 (29 Temmuz 2025) Aspire CLI'ı GA yaptı (aspire new, aspire run, aspire add; aspire publish preview, aspire deploy ise bir feature flag arkasındaydı), dış servisleri modellemek için AddExternalService'i getirdi ve YARP integration'ında kırıcı bir değişiklik yaptı: WithConfigFile kaldırıldı, yerine 03'te kullandığımız kodla configuration (WithConfiguration) geldi.

13.0: Aspire Adı, .NET 10 ve Pipeline

13.0 (11 Kasım 2025) en büyük kırılma noktası. Ürünün adı ".NET Aspire"dan "Aspire"a döndü, dokümanlar aspire.dev'e taşındı ve Python ile JavaScript resource'ları birinci sınıf hâle geldi. Taşıma açısından önemli olanlar:

• .NET 10 SDK şartı. AppHost proje dosyası tek satırlık SDK biçimine geçti (<Project Sdk="Aspire.AppHost.Sdk/13.0.0">) ve Aspire.Hosting.AppHost paket referansı gereksiz oldu.
• Aspire.Hosting.NodeJs paketinin adı Aspire.Hosting.JavaScript oldu; AddNpmApp'in yerine AddJavaScriptApp geldi (args parametresi yok, WithArgs ya da package.json script'i kullanılıyor), AddNodeApp'in imzası değişti.
• Publish API'leri (PublishingContext, WithPublishingCallback, IDistributedApplicationPublisher ve ilgili tipler) kaldırıldı; deploy, 07'de kullandığımız pipeline ve aspire do üzerine yeniden yazıldı.
• Lifecycle hook'lar obsolete: IDistributedApplicationLifecycleHook yerine IDistributedApplicationEventingSubscriber, AddLifecycleHook yerine AddEventingSubscriber.
• aspire run --watch kaldırıldı; veritabanı integration'ları 02'de gördüğümüz connection property'lerini (X_HOST, X_URI…) vermeye başladı.

13.1–13.6: Neler Eklendi, Neler Kırıldı

13.x minor sürümlerinin her biri breaking change içeriyor; bu seride karşımıza çıkanları sürüm notlarından topladık. 13.2'de service discovery environment variable'ları endpoint adı yerine endpoint scheme'ini kullanmaya başladı, resource komutlarının adı resource-start'tan start'a değişti ve .aspire/settings.json ile apphost.run.json yerine tek bir aspire.config.json geldi (CLI eski dosyaları ilk çalıştırmada kendisi taşıyor). 13.3'te aspire publish ve aspire deploy'daki --log-level, --pipeline-log-level oldu ve aspire init AppHost'u tek başına tamamen kurmayı bıraktı. 13.4'te aspire exec kaldırıldı ve varsayılan image'lar yükseldi: RabbitMQ 4.3 (05'teki container'ımız) ve PostgreSQL 18.3; ikincisi PostgreSQL 17'nin data volume'larını açamıyor, eski veriyle çalışıyorsan WithImageTag("17.6")'yı WithDataVolume()'dan önce sabitlemen gerekiyor. 13.5'te PublishAsConnectionString obsolete oldu (yerine AddConnectionString) ve hosting context tiplerindeki ServiceProvider property'si Services oldu. 13.6'da dashboard telemetry'yi SQLite'ta saklamaya başladı (04), MongoDB lokal çalıştırmada otomatik TLS (şifreli bağlantı) kullanmaya başladı ve Azure Cosmos DB (Azure'un NoSQL veritabanı servisi) emulator'ü Linux tabanlı sürüme geçti. Ders şu: bir minor sürümü atlamak, o sürümün breaking change'lerini de atlamak demek değil; yükseltirken aradaki her sürümün notlarını oku.

Eski Bir Projeyi Taşımak: aspire update

Aspire 9.5.2 template'iyle (dotnet new aspire-starter -f net9.0), sitedeki serilerin ortak örnek uygulaması Bookstore'un (bir online kitapçı) eski tarzda bir prototipini oluşturduk: bir API, bir Blazor arayüzü ve ServiceDefaults. Üstüne 9.x döneminin iki tipik parçasını ekledik: back office için küçük bir Node.js uygulamasını başlatan AddNpmApp ve açılışta log yazan bir lifecycle hook:

builder.Services.TryAddLifecycleHook<StartupBanner>();
...
builder.AddNpmApp("admin", "../admin-web", "start")
    .WithHttpEndpoint(env: "PORT")
    .WithReference(apiService);

internal sealed class StartupBanner(ILogger<StartupBanner> logger) : IDistributedApplicationLifecycleHook
{
    public Task BeforeStartAsync(DistributedApplicationModel appModel, CancellationToken cancellationToken = default)
    {
        logger.LogInformation("Starting Bookstore with {Count} resources", appModel.Resources.Count);
        return Task.CompletedTask;
    }
}

Proje 9.5.2 ile hatasız build oldu, ama NuGet bugün bu sürümler için güvenlik uyarısı veriyor; taşımanın en somut gerekçesi bu:

warning NU1903: Package 'Aspire.Hosting.AppHost' 9.5.2 has a known high severity vulnerability, https://github.com/advisories/GHSA-f7vh-h5g3-7jrh
warning NU1904: Package 'Aspire.Dashboard.Sdk.<platform>' 9.5.2 has a known critical severity vulnerability, https://github.com/advisories/GHSA-4g86-54fm-h9h8
warning NU1902: Package 'OpenTelemetry.Exporter.OpenTelemetryProtocol' 1.12.0 has a known moderate severity vulnerability, https://github.com/advisories/GHSA-4625-4j76-fww9

Aspire CLI 13.6.5 ile güncelledik:

aspire update --apphost Bookstore.AppHost/Bookstore.AppHost.csproj --yes --non-interactive --channel stable

💾 Created settings file at 'aspire.config.json'.
Checking for updates...
Analyzing project...

📦 Aspire.AppHost.Sdk 9.5.2 to 13.6.5

Applying updates...
Executing: Update package Aspire.AppHost.Sdk from 9.5.2 to 13.6.5
Migrated to new project format: <Project Sdk="Aspire.AppHost.Sdk/13.6.5">
Removed obsolete Aspire.Hosting.AppHost package reference
Restoring packages...

✅ Update successful!

Proje dosyasındaki fark tam olarak bu üç satır: <Project Sdk="Microsoft.NET.Sdk"> ve ayrı <Sdk> elementi tek satıra indi, Aspire.Hosting.AppHost referansı silindi ve bir aspire.config.json eklendi. Build:

warning CS0618: 'IDistributedApplicationLifecycleHook' is obsolete: 'Use IDistributedApplicationEventingSubscriber instead.'
warning CS0618: 'LifecycleHookServiceCollectionExtensions.TryAddLifecycleHook<T>(IServiceCollection)' is obsolete: 'Use EventingSubscriberServiceCollectionExtensions.TryAddEventingSubscriber instead.'
warning NU1902: Package 'OpenTelemetry.Exporter.OpenTelemetryProtocol' 1.12.0 has a known moderate severity vulnerability, ...
warning ASPIRE010: Bookstore.AppHost is configured with AspireUseCliBundle=false. Some Aspire features require the Aspire CLI bundle. ...
    0 Error(s)

Önce Tahmin Et'in cevabı: hedef framework net9.0 olarak kaldı, Aspire.Hosting.NodeJs 9.5.2'de kaldı (adı değişmiş bir paketi güncelleyecek bir şey yok) ve ServiceDefaults'taki OpenTelemetry ile Microsoft.Extensions.* paketlerine dokunulmadı; onlar Aspire paketi değil. aspire update --migrate da "Nothing to migrate" dedi. Proje build oluyor ama işimiz bitmedi.

aspire update'in Yapmadıkları

İlk aspire start AppHost'u açamadı: makinede .NET 9 runtime'ı yoktu ve net9.0 hedefli AppHost Framework: 'Microsoft.NETCore.App', version '9.0.0' bulamadan çıktı. Aspire 13 zaten .NET 10 SDK istiyor; dört projenin hedefini net10.0'a çektik. İkinci deneme başka bir hatayla durdu:

Microsoft.Extensions.Options.OptionsValidationException: The 'applicationUrl' setting must be an https address unless the
'ASPIRE_ALLOW_UNSECURED_TRANSPORT' environment variable is set to true. ...

9.5 template'inin http launch profile'ında bu değişken yoktu; 13.6 template'i ise onu ekliyor (01'den beri kullandığımız profile'da var). Değişkeni ekleyince uygulama açıldı ve dikkat çekici bir şey oldu: Aspire.Hosting 13.6.5'in yanında 9.5.2 sürümündeki Aspire.Hosting.NodeJs ile AddNpmApp çalıştı, back office uygulaması API adresini doğru aldı:

curl http://localhost:55633
Bookstore back office. API: http://localhost:5471

Çalışıyor olması doğru olduğu anlamına gelmiyor: iki ana sürüm geride, artık güncellenmeyen bir paket bu ve bir sonraki yükseltmede kırılabilir. Kalan adımları elle yaptık:

// AppHost.cs: lifecycle hook yerine eventing subscriber, AddNpmApp yerine AddJavaScriptApp
builder.Services.TryAddEventingSubscriber<StartupBanner>();
...
builder.AddJavaScriptApp("admin", "../admin-web", "start")
    .WithHttpEndpoint(env: "PORT")
    .WithReference(apiService);

internal sealed class StartupBanner(ILogger<StartupBanner> logger) : IDistributedApplicationEventingSubscriber
{
    public Task SubscribeAsync(IDistributedApplicationEventing eventing, DistributedApplicationExecutionContext executionContext, CancellationToken cancellationToken)
    {
        eventing.Subscribe<BeforeStartEvent>((@event, ct) =>
        {
            logger.LogInformation("Starting Bookstore with {Count} resources", @event.Model.Resources.Count);
            return Task.CompletedTask;
        });
        return Task.CompletedTask;
    }
}

Proje dosyalarında Aspire.Hosting.NodeJs 9.5.2 yerine Aspire.Hosting.JavaScript 13.6.5, AppHost'a <AspireUseCliBundle>true</AspireUseCliBundle> (13.5'ten beri yeni AppHost'ların varsayılanı), ServiceDefaults'ta OpenTelemetry paketleri 1.12.0'dan 1.21.0'a ve Microsoft.Extensions.Http.Resilience ile Microsoft.Extensions.ServiceDiscovery 10.11.0'a çıktı. Sonuç: 0 Warning(s), 0 Error(s). Taşınmış hâli repoda samples/aspire-9-migration klasöründe. Çalıştırdığımızda bir yenilik daha göründü: AddJavaScriptApp, 02'de Angular için gördüğümüz gibi npm install'ı yapan gizli bir admin-installer resource'u ekliyor; eski AddNpmApp paketleri kurmayı sana bırakıyordu. AppHost'un log'unda yeni subscriber da çalıştı:

[INFO] [AppHost/StartupBanner] Starting Bookstore with 7 resources

Deploy tarafında da bir not: 13.6 AppHost'u hâlâ --publisher manifest --output-path aspire-manifest.json argümanlarıyla 8.x'teki manifest biçimini yazabiliyor (denedik, "type": "project.v0" kayıtlarıyla 2,3 KB'lık bir dosya üretti). Manifest + azd ile kurulmuş bir hattı hemen bırakmak zorunda değilsin, ama yeni hedefler (Compose, Kubernetes) ve aspire destroy yalnız pipeline tarafında var.

Üretimde Dikkat

Aspire paketlerini düzenli güncelle; NuGet'in bu yazıdaki uyarıları 9.5.2 için "critical" seviyesinde bir dashboard açığı gösteriyordu. Dashboard production'da çalışmasa bile geliştirici makinelerinde ve CI'da çalışıyor.

Yükseltmeyi bir sürüm atlayarak yapıyorsan aradaki her sürümün breaking change listesini oku; bu yazıdaki örnekler (PostgreSQL 18 volume'u, service discovery değişken adları, komut adları) build hatası vermeden çalışma anında ortaya çıkıyor.

Yükseltmeden sonra yalnız build'e değil, aspire publish çıktısının farkına da bak. Image sürümleri, environment variable adları ve deploy artifact'leri sessizce değişebiliyor; 07'deki gibi publish çıktısını pull request'te gözden geçirmek bunu yakalıyor.

CPM (Central Package Management; paket sürümlerini tek dosyada toplayan NuGet özelliği) kullanıyorsan aspire update sürümleri Directory.Packages.props'ta güncelliyor; Aspire dışı paketler (OpenTelemetry, Microsoft.Extensions.*) için ayrıca dotnet list package --outdated çalıştır.

Sık Düşülen Tuzaklar

"Update successful"ı taşımanın sonu sanmak. Hedef framework, adı değişen paketler, obsolete API'ler ve launch profile'lar elle yapılan işler.

Obsolete uyarılarını bastırmak. 13.0'da obsolete olan API'ler bir sonraki ana sürümde kaldırılacak; TreatWarningsAsErrors açık bir projede bunlar zaten build'i durdurur.

Eski bir integration paketini yeni Aspire ile bırakmak. Bizim denememizde çalıştı, ama desteklenen bir kombinasyon olduğunu gösteren bir şey yok.

8.x'ten doğrudan 13'e atlamak. Doküman önce 9.x'e geçmeyi öneriyor; workload'dan SDK'ya geçiş ve 13'teki kırılmalar ayrı ayrı daha kolay ayrıştırılıyor.

Eski blog yazılarındaki kodu birebir kopyalamak. "dotnet workload install aspire", AddNpmApp, IsAspireHost ya da WithConfigFile görüyorsan, yazı bugünkü Aspire'dan en az bir ana sürüm geride.

Küçük Bir Deneme

★☆☆ Kendi projende aspire update --channel stable'ı bir branch'te çalıştır ve git diff'e bak. Neler değişti, neler değişmedi?

★★☆ 9.5 template'iyle bir proje oluştur ve AddNpmApp yerine AddJavaScriptApp'e geçtiğinde dashboard'da beliren -installer resource'unun ne yaptığını log'undan çıkar.

★★★ Bu serinin AppHost'unu (07 sonundaki hâli) bir sonraki Aspire minor sürümüne yükselt: sürüm notlarındaki breaking change'lerden hangileri Bookstore'u etkiliyor? Testleri (06) ve aspire publish çıktısını (07) yükseltmeden önce ve sonra karşılaştır.

Seri burada bitiyor. Bookstore'u bir AppHost'la tek komutla çalıştırmaktan başladık; service discovery, dashboard, integration'lar, uçtan uca testler ve deploy ile aynı model geliştirme makinesinden Compose'a ve Kubernetes'e kadar uzandı. Aspire'ın en çok işe yaradığı yer, bu modelin ekipteki herkes için tek ve çalıştırılabilir bir tarif olması; Bookstore'un service'lere nasıl bölündüğü ve iş akışları .NET ile Mikroservis Uygulaması serisinde devam ediyor.