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
<PackageReference Include="KoalaSoft.Aspire.Hosting.ServiceSources" Version="0.8.0" />
<PackageVersion Include="KoalaSoft.Aspire.Hosting.ServiceSources" Version="0.8.0" />
<PackageReference Include="KoalaSoft.Aspire.Hosting.ServiceSources" />
paket add KoalaSoft.Aspire.Hosting.ServiceSources --version 0.8.0
#r "nuget: KoalaSoft.Aspire.Hosting.ServiceSources, 0.8.0"
#:package KoalaSoft.Aspire.Hosting.ServiceSources@0.8.0
#addin nuget:?package=KoalaSoft.Aspire.Hosting.ServiceSources&version=0.8.0
#tool nuget:?package=KoalaSoft.Aspire.Hosting.ServiceSources&version=0.8.0
Aspire.Hosting.ServiceSources
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
- Sources — every way to resolve a service.
- Authoring the catalog in code — the full catalog API, in C# and TypeScript.
- Non-.NET services — JavaScript, Java, or your own
kind. - Backing services — databases, brokers and caches.
- Samples — runnable C# and TypeScript AppHosts.
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 | Versions 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. |
-
net10.0
- Aspire.Hosting (>= 13.6.1)
- YamlDotNet (>= 18.1.0)
-
net8.0
- Aspire.Hosting (>= 13.6.1)
- YamlDotNet (>= 18.1.0)
-
net9.0
- Aspire.Hosting (>= 13.6.1)
- YamlDotNet (>= 18.1.0)
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.
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