Initial drafts of .NET Aspire CLI docs #3905
Conversation
Co-authored-by: David Pine <[email protected]>
|
For 9.4, these are the commands and their preview status:
@maddymontaquila to configure status of each command. |
|
|
||
| While command line parameters can be used to automate the creation of an Aspire project, the Aspire CLI is an interactive-first experience. | ||
|
|
||
| ## Run the apphost project |
There was a problem hiding this comment.
Nit: I worry this title might be confusing to people who are not familiar with what the app host is. It might imply that the app host is the only thing that is launched when in reality it launches all projects and containers in the model.
There was a problem hiding this comment.
Do you like "Aspire run" here better?
|
|
||
| ## Publish Aspire applications (preview) | ||
|
|
||
| The `aspire publish` command publishes resources, serializing data into JSON format. When this command is run, Aspire invokes registered <xref:Aspire.Hosting.ApplicationModel.PublishingCallbackAnnotation> annotations for resources. These annotations serialize a resource so that it can be consumed by deployment tools. |
There was a problem hiding this comment.
The command doesn't necessarily serialize things into a JSON format. It'll do whatever the PublishingCallbackAnnotations do which might write JSON or Bicep or YAML or a number of other things.
|
|
||
| ## Publish Aspire applications (preview) | ||
|
|
||
| The `aspire publish` command publishes resources, serializing data into JSON format. When this command is run, Aspire invokes registered <xref:Aspire.Hosting.ApplicationModel.PublishingCallbackAnnotation> annotations for resources. These annotations serialize a resource so that it can be consumed by deployment tools. |
There was a problem hiding this comment.
It might be helpful to document here that the PublishingCallbackAnnotations are executed in order of appearance in the application model.
| ## Publish Aspire applications (preview) | ||
|
|
||
| The `aspire publish` command publishes resources, serializing data into JSON format. When this command is run, Aspire invokes registered <xref:Aspire.Hosting.ApplicationModel.PublishingCallbackAnnotation> annotations for resources. These annotations serialize a resource so that it can be consumed by deployment tools. | ||
|
|
There was a problem hiding this comment.
We should add a section here that outlines the publishers that are included in the different integrations and the code they emit. These include:
- AzureEnvironmentResource / AddAzureEnvironment / Generates Bicep assets for projects
- DockerComposeEnvironmentResource / AddDockerCompose / Generates docker-compose yaml
- KubernetesEnvironmentResource / AddKubernetesEnvironment / Generates Kubernetes Helm chart
|
|
||
| ## Deploy Aspire applications (preview) | ||
|
|
||
| The `aspire deploy` command is similar to `aspire publish`, except that in addition to serializing resources, it also deploys resources that have registered a `DeployingCallbackAnnotation` annotation. |
There was a problem hiding this comment.
We don't include any default deployment implementations out of the box for 9.4. Might be worth calling out that users can start building on these abstractions by registering DeployingCallbackAnnotation's themselves.
| ## Deploy Aspire applications (preview) | ||
|
|
||
| The `aspire deploy` command is similar to `aspire publish`, except that in addition to serializing resources, it also deploys resources that have registered a `DeployingCallbackAnnotation` annotation. | ||
|
|
There was a problem hiding this comment.
We should add a section here that outlines that the annotations are invoked in order of appearance and they are invoked after all the publishing callback annotations are invoked.
|
|
||
| --> | ||
|
|
||
| ## Create projects |
There was a problem hiding this comment.
Nit: maybe templates instead? Not all templates are project templates, for example the starter template is a whole solution (which was unique at that time).
docs/cli/overview.md
Outdated
|
|
||
| ## Run the apphost project | ||
|
|
||
| The `aspire run` command runs the apphost project in development mode, which configures the Aspire environment, builds the apphost, launches the web dashboard, and displays a terminal-based dashboard. This is similar to running the apphost project in your IDE of choice, however, a terminal dashboard is also visible. |
There was a problem hiding this comment.
I know Maddy and Fowler, really like "AppHost", but I'm still not convinced it's correct. It's an overload phrase, are we talking about the concept of the orchestrator, the project itself, the project template, the AppHost.cs file? There are way too many things that this could be referring to, and it's becoming ambiguous. I've historically tried to combat that by saying:
- AppHost project: when talking about the project (modified template).
- AppHost template: when talking about the template (starting point).
- AppHost.cs: when talking about the entry point.
- App host: when talking about it conceptually.
This isn't perfect, but one thing we haven't done is call it apphost.
Fixes #4027
Internal previews