Project Resource v2

[karolz-ms]

This issue describes the goals, key design decisions, and roadmap for version 2 of the Project resource. Project resource represents a C# program that is part of an Aspire application.

[karolz-ms]

Goals and Design Principles

Loose coupling with application host (Project v2 as "ordinary" resource)

C# application host that uses Project v2 resources does not have a reference to C# service project(s) (unlike Project v1). There is no special code generation.

C# projects are added to the model using relative paths just like Aspire application services implemented in other languages.

Programmatic build configuration

Build configuration and launch/debug options can be controlled from Aspire model.

Build configuration in Aspire model can also be applied to deployment.

Integrations can override build configuration defaults

Application host code can override build configuration defaults

Improved watch experience (via new aspire-watch)

Rebuild and re-start occurs reliably for service code changes and for shared library changes.

Watch server is started/stopped automatically as hidden, system resource.

Partial runs (ability to running subset of services)

Launch groups specify resources to include.

Aspire app model computes transitive closure of resources to run. Resources outside of the closure are not part of the run.

Resources within closure are built efficiently and correctly (e.g. via temporary SLNX files).

Persistent execution

Running projects can survive application host shutdown and can be re-used for subsequent application runs.

Requires new "persistent Executables" feature from DCP.

Container-based execution

Project v2 resources can optionally be launched as containers instead of running as ordinary OS processes.

Scope might be limited to projects that use SDK-based container image build.

Debugging

Starting Projects v2 under debugger works ("F5" from IDE), including debugging startup code.

Attaching to running service works.

"Run under debugger" + watch might be impossible initially; attach should work).

Model events and callbacks review

Part of the Project v2 work should include review and re-design (as necessary) of related model events and callback contracts. For various execution scenarios we should be clear about:

• What events are MUST be raised vs what events MAY be raised
• Any ordering and concurrency guarantees (event X will be raised before Y; event X handlers must complete before event Y is raised etc.)
• Any cardinality guarantees (how many times an event may be raised)

The same applies for callbacks (e.g. environment variable- and invocation parameter callbacks).

Illustrative issue: environment variable callback may need to be invoked to compute transitive closure of resources for partial run, even if the associated resource is NOT part of the run.

Orthogonal capabilities

To the largest extent possible, the design should allow for free combination of capabilities listed above. For example, it should be possible to have a partial run with some projects using persistent execution, all in watch mode.

[karolz-ms]

Proposal: improved watch as initial vertical slice

Scope:

• Project v2 resource, instantiated via experimental DistributedApplicationBuilder API
• Watch server as hidden, system resource
• Resources built implicitly by watch server
• Handles service changes and shared library changes

Tracking issue: #15710

[mitchdenny]

Will persistent project v2 also encompass generic executables. Thinking about this for WithTerminal(...).

[eerhardt]

Project v2 resources can optionally be launched as containers instead of running as ordinary OS processes.

Do we need this?

[afscrome]

I'd love it if the ProjectV2 resource could discriminate based on annotations, rather than base classes. That would better allow substitution (e.g. I want a custom resource to be container / dotnet tool based based when I publish it as a nuget package, but a project when working with the source solution. As well as allowing me to strongly type my resources.

At least from DCP / Aspire Hosting perspective. If you want to have the default implementation be a concrete type so you can cleanly target extension methods, that's totally fine.

Project v2 resources can optionally be launched as containers instead of running as ordinary OS processes.

Do we need this?

I do find myself conflicted. I've found that a lot of people ask for this, to make their dev environment more production like, but assume that it is zero compromise. But there are compromises.

• Complexity - involving the container runtime adds more complexity, with more opportunities for things to go wrong
• Time costs - building the container add extra time
  Hopefully the aspire integration can hide a lot of the complexity, but even if hiding it, the complexity will still be ther eunder the hood. And complexity == opportunity for things to go wrong.

So yes it's a useful capability, but I do always want to ask people whether they're sure, as often the answer is they don't need it.

But there are cases where it's absolutely necessary - particularly if you're interoping with native code, running that code in the container base image you'll deploy to production with is beneficial (and in some cases required if the library doesn't' support your host OS), so it is a useful capability to have.

[karolz-ms]

Will persistent project v2 also encompass generic executables. Thinking about this for WithTerminal(...).

Project v2 is about C# programs, so technically no because terminal support is really independent from the implementation language of the program. That said, it is absolutely a requirement that Project v2 plays well with whatever we decide to support for all executables including terminal integration. How this is actually expressed in Aspire (runtime) code is an open question.

[karolz-ms]

Alex nailed the business case for running-as-container.

From the roadmap perspective I do not think it is part of MVP (minimum viable product), but I do think Project v2 should be designed in a way that adding container execution should be relatievely easy (on top of MVP).

[adamint]

Partial runs (ability to running subset of services)

Sorry for the ignorance, why is that feature wrapped up in this epic? How does it relate?