KoalaSoft.Aspire.Hosting.ServiceSources 0.8.0

dotnet add package KoalaSoft.Aspire.Hosting.ServiceSources --version 0.8.0
                    
NuGet\Install-Package KoalaSoft.Aspire.Hosting.ServiceSources -Version 0.8.0
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="KoalaSoft.Aspire.Hosting.ServiceSources" Version="0.8.0" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="KoalaSoft.Aspire.Hosting.ServiceSources" Version="0.8.0" />
                    
Directory.Packages.props
<PackageReference Include="KoalaSoft.Aspire.Hosting.ServiceSources" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add KoalaSoft.Aspire.Hosting.ServiceSources --version 0.8.0
                    
#r "nuget: KoalaSoft.Aspire.Hosting.ServiceSources, 0.8.0"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package KoalaSoft.Aspire.Hosting.ServiceSources@0.8.0
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=KoalaSoft.Aspire.Hosting.ServiceSources&version=0.8.0
                    
Install as a Cake Addin
#tool nuget:?package=KoalaSoft.Aspire.Hosting.ServiceSources&version=0.8.0
                    
Install as a Cake Tool

Aspire.Hosting.ServiceSources

NuGet Downloads License: MIT Docs

An Aspire AppHost extension that lets builder.AddService("orders") resolve to a real, running resource whose source is chosen per developer, not baked into the AppHost.

The AppHost says what it depends on; each developer's own config file decides where it comes from — a managed git checkout ("repository"), a directory already checked out beside the AppHost ("path"), a kubectl port-forward against a dev cluster ("kubernetes"), a fixed URL ("url"), a published container image ("container"), or nothing at all ("disabled"). The AppHost code never changes when a developer switches.

📖 Documentation: https://aspire-servicesources.readthedocs.io/

Install

dotnet add package KoalaSoft.Aspire.Hosting.ServiceSources

Requires .NET 8+ and Aspire 13.6.1+ — move your AppHost's Aspire.AppHost.Sdk to 13.6.1 or later at the same time, or you get a mixed Aspire family. Services in other languages need one extra package each. See Installation.

Quickstart

1. Declare the catalog and the services in the AppHost's Program.cs:

using Aspire.Hosting.ServiceSources;

var builder = DistributedApplication.CreateBuilder(args);

builder.AddServiceCatalog(catalog =>
{
    catalog.AddService("orders")
        .WithRepository("https://github.com/example/orders", defaultRef: "main")
        .WithProject("src/Orders.Api/Orders.Api.csproj");

    catalog.AddService("storefront")
        .WithRepository("https://github.com/example/storefront", defaultRef: "main")
        .WithProject("src/Storefront/Storefront.csproj");
});

var orders = builder.AddService("orders");

builder.AddService("storefront")
    .WithReference(orders);

builder.Build().Run();

2. Pick your source in servicesources.local.json next to the AppHost project (gitignore this file — it's per-developer):

{
  "services": {
    "orders": { "source": "repository" },
    "storefront": { "source": "repository" }
  }
}

Run the AppHost: each service is cloned into .servicesources/checkouts/<service>/, checked out at main, and run by Aspire, with storefront wired to orders through service discovery. Switch orders to a dev cluster, a URL or a container by editing only servicesources.local.json. The full walkthrough is in the Quickstart; prefer a committed servicesources.yaml over code? See The YAML catalog.

Using AddService() with existing AppHost helpers

AddService() returns an IResourceBuilder<ServiceResource>. ServiceResource does not inherit ProjectResource — a service isn't always a project, and the type shouldn't reveal which source resolved it — so a helper hard-typed to IResourceBuilder<ProjectResource> won't accept it. Two approaches cover most cases.

1. Widen your own helpers to a generic constrained to the capabilities their body uses, instead of a concrete resource type. A helper that only calls WithReference, WaitFor and WithEnvironment needs nothing more than the interfaces behind them:

static class AppHostExtensions
{
    // was: this IResourceBuilder<ProjectResource> app
    public static IResourceBuilder<T> AddOllama<T>(
        this IResourceBuilder<T> app,
        IResourceBuilder<IResourceWithServiceDiscovery> ollama,
        string model)
        where T : IResourceWithEnvironment, IResourceWithWaitSupport
    {
        return app.WithReference(ollama).WaitFor(ollama).WithEnvironment("OLLAMA_MODEL", model);
    }
}

This accepts a project, a container or a ServiceResource. ServiceResource implements IResourceWithServiceDiscovery, IResourceWithEnvironment, IResourceWithArgs, IResourceWithEndpoints and IResourceWithWaitSupport; parameters that take another resource should use the same interface-typed form (IResourceBuilder<IResourceWithServiceDiscovery>) rather than IResourceBuilder<ProjectResource>.

2. Use GetServiceEndpoint() where an API takes only an EndpointReference. Many integrations accept the resource builder through an interface-typed overload, and those take a service as is (Aspire.Hosting.Yarp's AddCluster has an IResourceBuilder<IResourceWithServiceDiscovery> overload). Where one accepts only an EndpointReference, or you need the service's URL as a value, GetServiceEndpoint() returns the https endpoint, else http, else the service's only endpoint — whichever source resolved it:

var commonAuth = builder.AddService("common-auth");

builder.AddProject<Projects.Web>("web")
    .WithEnvironment("Services__CommonAuth", commonAuth.GetServiceEndpoint());

It throws ServiceSourcesConfigurationException if the service exposes no endpoints, or several and none named http or https; name the one you mean with GetEndpoint("..."). The endpoint is chosen when you call it, so call it after any Configure(...) that adds an endpoint.

Learn more

Status

Early stage, evolving fast; while below 1.0.0, a minor release can break. See the changelog, SECURITY.md for the trust model a resolved service runs under, and RELEASING.md for how a release is cut. Licensed under MIT.

Product Compatible and additional computed target framework versions.
.NET net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed.  net9.0 is compatible.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed.  net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (2)

Showing the top 2 NuGet packages that depend on KoalaSoft.Aspire.Hosting.ServiceSources:

Package Downloads
KoalaSoft.Aspire.Hosting.ServiceSources.JavaScript

JavaScript support for KoalaSoft.Aspire.Hosting.ServiceSources — runs a "local"-sourced service with kind "javascript" through Aspire.Hosting.JavaScript.

KoalaSoft.Aspire.Hosting.ServiceSources.Java

Java support for KoalaSoft.Aspire.Hosting.ServiceSources — lets an AddService() "local" source clone and run a Java service (Maven goal, Gradle task, or a jar) via the .NET Aspire Community Toolkit's Java integration.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
0.8.0 249 10/23/2026
0.7.0 366 9/28/2026
0.6.0 110 9/24/2026
0.5.1 183 9/7/2026
0.4.1 180 9/5/2026
0.4.0 156 9/3/2026
0.3.1 158 8/27/2026
0.3.0 123 8/27/2026
0.2.0 132 8/18/2026
0.1.0 133 8/18/2026

Breaking

- Deferred checkout is now the default for a cold `"repository"` service; `UseDeferredCheckout()` is
 obsolete (#216). A service whose managed clone does not exist yet used to block
 `AddService()` until the checkout landed; it now registers stopped and starts once the clone
 finishes, so the dashboard comes up immediately and one failed clone costs one service rather
 than the whole AppHost. This is the behaviour `UseDeferredCheckout()` used to opt into — nothing
 changes for a warm checkout, a `path` override, or `aspire publish`.

 `UseDeferredCheckout()` is now redundant — deferred is what it always asked for, and that is
 already the default — so it is `[Obsolete]`; delete the call. The new
 `builder.SetCheckoutTiming(CheckoutTiming.Eager)` is the opt-out for an AppHost that needs every
 service running by the time `Build()` returns, kept permanently rather than as a migration
 window, since the package cannot detect an AppHost relying on the old ordering. A deferred
 `dotnet` service should still declare its own endpoints — `Configure<IResourceWithEndpoints>` in
 C#, or `withServiceHttpsEndpoint()`/`withServiceHttpEndpoint()` in a guest language (#208) —
 since a deferred checkout has no launch profile for Aspire to read endpoints from while
 composing.

 `java` and `javascript` are affected too, not only `dotnet`: both built-in kinds already
 supported deferral, so a cold checkout of either now defers by default as well, with no endpoint
 caveat (`java.port` and `javascript`'s allocated `http` endpoint are already fully known from the
 catalog, not synthesised from a launch profile). One consequence worth calling out: a `prepare`
 step's post-clone validation — and any `ServiceSourcesConfigurationException` the kind would have
 thrown at composition on the eager path (a missing wrapper, a bad `workingDirectory`) — now
 surfaces later, as that service's own resource state, rather than failing the AppHost synchronously
 at `AddService()`.

- The Aspire floor is now 13.6.1 (was 13.5.2). `Aspire.Hosting` and `Aspire.Hosting.JavaScript`
 are floored at 13.6.1, so an AppHost still on Aspire 13.5.x gets a mixed Aspire family at restore
 (`NU1605` against its own `Aspire.AppHost.Sdk` and `Aspire.Hosting.AppHost`). Move the AppHost's
 `Aspire.AppHost.Sdk`, and any `Aspire.Hosting.JavaScript` reference, to 13.6.1 or later. The
 generated-code sample now needs Aspire CLI 13.6.1 or later.

Added

- An AppHost run from a linked git worktree starts from the main worktree's state. Its first run
 copies `servicesources.local.json` and the saved source picks from the main worktree's AppHost, and
 a cold `"repository"` checkout borrows objects from the main worktree's checkout of the same
 repository instead of downloading everything. Seeding happens once; afterwards the worktree's
 files and checkouts are independent. A copied `path` override that resolves differently from the
 worktree is reported at startup.

- `kind: java` also runs on Aspire's official `Aspire.Hosting.Java` integration (preview).
 Reference it instead of `CommunityToolkit.Aspire.Hosting.Java` and `java` services run
 through it, with no catalog or AppHost change. When both are referenced the Community Toolkit's
 is used, so a package that arrives transitively changes nothing. An official preview older than
 `13.6.1-preview.1.26506.6` is reported at build time (`SERVICESOURCES003`), or else when the
 first `java` service resolves. The preview pins package versions that NuGet
 audit flags; see Installation (docs/getting-started/installation.md#non-net-services). `Unwrap<T>` takes the installed integration's resource type: `Aspire.Hosting.Java.JavaAppResource` for the
 official package, `JavaAppExecutableResource` for the Community Toolkit's.

- A `dotnet` service can select its launch profile (#415). A new `dotnet:` block in the yaml
 catalog takes `launchProfileName` (run under that `launchSettings.json` profile) and
 `excludeLaunchProfile` (run with none), and `WithLaunchProfile(...)` /
 `ExcludeLaunchProfile()` (`withLaunchProfile` / `excludeLaunchProfile` from TypeScript) are
 the code-catalog equivalents. It works on the `repository` source (including a deferred first
 checkout) and the `path` source. Three configuration errors come with it: naming a profile
 while excluding launch profiles, naming a profile the project's `launchSettings.json` does
 not contain (or a project with no `launchSettings.json` at all), and a `dotnet:` block, or
 the code-catalog calls, on a service whose kind is not `dotnet`.

- A `repositories.<name>` entry can use the `"path"` source to point a whole `repositoryRef` group
 at an existing checkout (#416). `{ "source": "path", "path": { "path": "../eShop" } }` (or
 `ServiceSources__Repositories__<name>__Source` and `__Path__Path`) redirects every grouped member
 whose source is `repository` or `path`, so a monorepo AppHost keeps its grouping without repeating
 a `path.path` per service. A member's own `path.path` still wins, and so does a `path:` its catalog
 entry declares for a `path` member (the author's layout, not a developer override); members on
 `url`, `container` or `kubernetes` are left alone, a member that sets its own `repository.ref` is
 refused at `AddService` whatever the checkout timing (a group's ref is shared, so no member's own
 applies), a group `ref` is ignored while the group is on `path`, and the builds of the members are
 serialized like any other `"path"` services in one repository. A
 `repositories` entry naming no declared repository is now reported at startup, as is a
 `repositories.<name>.path.path` set without `source`, which would otherwise be silently unread.
 A `prepare` on a `repositories.<name>` entry is never run, so it is ignored with a startup warning
 (#448); set `path.prepare` on each member service instead. An entry with `source: path` and no
 `path.path` is refused when the configuration is read.

Changed

- Docs: build serialization needs `ServiceSources:RepositoryRoot` or `buildGroup` when there is no
 `.git` (#449). Without either, a `repositories.<name>` group directory and a sibling with its own
 `path.path` inside it are separate build groups and can build concurrently. A test now pins the
 layout; no behavior changed.
- A cold `"repository"` checkout is no longer cloned at `AddService()`; the dashboard asks which
 ones to clone and start (#271). In run mode, once the AppHost starts, one dialog lists the
 services whose managed clone does not exist yet, all checked. Checked services are cloned and
 started as before; unchecked ones are not cloned (unless a service sharing the repository is
 picked) and show a `Skipped` state. The answer is
 remembered in `.servicesources/selection.json` (git-ignored), so the next run asks only about
 services it has no entry for; delete the file, or one service's entry, to be asked again. Nothing
 here fails to build, but a service that used to start unattended now waits for the answer.

 An unanswered dialog does not hang the AppHost: closing it, or no answer within 5 minutes, starts
 every service that was waiting on it, as before, and saves nothing. A run with no dashboard to ask
 through never prompts and starts every service that has no saved choice, and so does a run where
 any of the `CI`, `TF_BUILD` (Azure Pipelines) or `JENKINS_URL` (Jenkins) environment variables is
 set (set `SERVICESOURCES_INTERACTIVE=true` to be asked anyway, or `false` to never be asked). A saved choice made for a different repository than the service now
 points at is asked about again. A warm checkout, a `path`
 override, `aspire publish` and `SetCheckoutTiming(CheckoutTiming.Eager)` are unchanged and never
 prompt. A service that `WaitFor`s a skipped service keeps waiting; the dialog lists what waits on
 each one. To get the previous behaviour back, call `builder.SetCheckoutTiming(CheckoutTiming.Eager)`
 before the first `AddService()`.

 Until a deferred service is ready, `aspire resource <name> start`, `stop`, `restart` and `rebuild` are refused
 with a message saying why (#473, #480); the dashboard disables Start while the clone or a dialog is pending, and keeps it
 enabled on a `Skipped` service to show that message. A Start or Rebuild refused while the service is still
 on its way leaves it as it was: it still starts by itself once ready, and anything that
 `WaitFor`s or `WaitForCompletion`s it keeps waiting instead of failing.

- A changed `prepare` command is confirmed in the dashboard before it re-runs (#298). When
 the catalog's `prepare` command for a warm managed checkout is not the one that last succeeded
 there, the dashboard now shows the command and asks before running it; a first use, a moved
 commit and `always` mode still run unprompted. Only an explicit "Run"
 runs the step: closing the dialog, no answer within 5 minutes or a dialog that cannot be shown
 declines, and the service shows `Skipped` (restart the AppHost to be asked again). That
 deliberately differs from the cold-checkout source pick, which starts on timeout, because this is
 a consent gate on changed catalog code. With no dashboard the step runs unprompted and the log says
 why. Cost: the one run that needs asking is deferred even though the checkout is warm, so it loses
 composition-time launch-profile fidelity; `SetCheckoutTiming(CheckoutTiming.Eager)`, `aspire
 publish` and kinds that cannot defer are unchanged.

 While the dialog is open, and after Skip, Start is refused rather than running the service
 without the step you were asked to approve (#473).

Fixed

- Start no longer runs a deferred service that is still checking out or preparing, and the dashboard
 no longer offers a Stop that fails with a raw DCP 404 (#473, #480). A Start sent while the
 service showed `Checking out` or `Preparing` reported success and ran against a checkout that was
 not ready; it is now refused with a message saying so, and the dashboard hides Stop and disables
 Restart for those states, and for the other pre-start states, where Stop used to fail because nothing was
 running.

- Checkout progress lines show paths as written (#481). `Resolving checkout of … into …` and
 `Checkout ready at …` showed `C:\\Users\\…` for `C:\Users\…`, doubling every backslash in a Windows
 path; they now read as the path on disk.

- Configuration errors show file paths as written (#486). The "no source configured" error and the
 other messages that name a file or directory on this machine (a misspelled root key, a missing
 launch settings file, a `path` service that does not exist, a worktree path override, and the like)
 showed `C:\\Users\\…` for `C:\Users\…`, doubling every backslash in a Windows path; they now read as
 the path on disk. Values you typed into the configuration are still echoed escaped.

- `asJava`/`asJavaScript` inside an `addServiceCatalog` callback no longer hang a TypeScript
 AppHost (#463). The first call made inside the nested callback never returned, and after 60s
 both callbacks timed out with `Callback 'callback_2_…' timed out after 60s` and the AppHost
 failed. `AsJava()` and `AsJavaScript()` now run off the RPC thread, as `AddServiceCatalog()`
 already did. C# AppHosts were not affected.

- A `"repository"` clone no longer fails on Windows for repositories with long paths, and its
 leftovers no longer linger (#462). git is now run with `core.longpaths=true` on Windows, the
 staging directory is named `.incoming-<8 hex>` instead of embedding the service name and a
 32-character GUID, and a staging directory whose clone died is removed by the next clone in that
 `checkouts` folder instead of after 24 hours. A clone still running in another AppHost is never
 touched, and read-only files git leaves in `.git` no longer block the cleanup. See
 Troubleshooting (docs/troubleshooting.md#long-paths-on-windows). A clone whose pack files —
 including the temporary ones git writes when it repacks to borrow objects or during a later
 fetch — would pass `MAX_PATH`, which `core.longpaths` cannot fix, is now refused up front with the
 length it needs and the fix, each clone keeps `core.longpaths=true` in its own config, and the sweep logs
 each leftover it removes (#474).
- Two `"path"` services in one repository no longer race on a shared project's `bin/` and
 `obj/` (#397). Aspire starts independent resources at once, so two services whose projects
 share a `ProjectReference` ran two builds over the same output directory and one failed
 intermittently with `MSB4018` or `CS2012`
 (microsoft/aspire#15190 (https://github.com/microsoft/aspire/issues/15190)). Their builds now run
 one at a time, before the processes start; the processes still run concurrently. The group is the
 git repository the service directory sits in, and a new optional `buildGroup` catalog field
 (`WithBuildGroup` in code) names one explicitly for projects shared across repositories.
 `buildGroup` is now a reserved key, so a yaml service cannot use a custom `kind` of that name. Managed
 checkouts are unchanged, and the gate does not apply when an IDE or `dotnet watch` builds the
 project.

- A failed clone's git output is shown as git wrote it (#465 (https://github.com/flojon/aspire-servicesources/issues/465)). The failure message and the resource log escaped backslashes and apostrophes, so a Windows path read as `D:\\Source\\…` and an apostrophe as `\u0027`; they now appear as written, with git's lines joined by ` | `.
- The error for a `disabled` service's endpoint reads as a sentence and no longer assumes a yaml catalog (#465 (https://github.com/flojon/aspire-servicesources/issues/465)). The advice now starts with a capital and says "catalog entry" rather than `servicesources.yaml` entry, which is wrong for a catalog defined in code, and names the code-catalog helpers (`WithRepository`, `WithSharedRepository`, `WithContainer`; `WithProject` for a missing `project`).

Full changelog: https://github.com/flojon/aspire-servicesources/blob/main/CHANGELOG.md