Skip to content

Add comprehensive documentation for ExecutableResource and AddExecutable API #4188

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 4 commits into
base: main
Choose a base branch
from

Conversation

Copilot
Copy link
Contributor

@Copilot Copilot AI commented Aug 4, 2025

This PR adds a new comprehensive article documenting how to use ExecutableResource and the AddExecutable extension method in .NET Aspire app hosts. The documentation was missing entirely, leaving developers without guidance on how to host external executable applications.

What's included

The new article docs/app-host/executable-resources.md covers:

  • Basic usage of AddExecutable with command-line arguments and working directories
  • Command-line argument configuration using multiple approaches (WithArgs, direct parameters)
  • Resource dependency management with WithResource calls and environment variable access
  • Practical Vercel CLI example demonstrating real-world usage
  • Publishing scenarios with PublishAsDockerfile for deployment
  • Advanced scenarios including conditional execution and complex argument chains
  • Best practices for production use

Key examples

The article includes practical examples for common scenarios:

// Basic executable with arguments
var app = builder.AddExecutable("vercel-dev", "vercel", "dev", ".")
    .WithArgs("--listen", "3000");

// Resource dependencies
var redis = builder.AddRedis("cache");
var app = builder.AddExecutable("worker", "python", "worker.py", ".")
    .WithReference(redis)      // Provides connection strings
    .WithEnvironment(context => {
        context.EnvironmentVariables["REDIS_HOST"] = 
            redis.Resource.PrimaryEndpoint.Property(EndpointProperty.Host);
    });

// Publishing for deployment
var app = builder.AddExecutable("frontend", "npm", ".", "start")
    .PublishAsDockerfile();

The documentation addresses the specific use case mentioned in the issue (external executable hosting) while providing comprehensive coverage for any external executable scenario using modern tooling like Vercel CLI.

Fixes #1381.


💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.


Internal previews

📄 File 🔗 Preview link
docs/app-host/executable-resources.md docs/app-host/executable-resources
docs/toc.yml docs/toc

@Copilot Copilot AI changed the title [WIP] [New article]: Using ExecutableResource Add comprehensive documentation for ExecutableResource and AddExecutable API Aug 4, 2025
Copilot finished work on behalf of IEvangelist August 4, 2025 20:41
@Copilot Copilot AI requested a review from IEvangelist August 4, 2025 20:41
Comment on lines 15 to 18
- Host non-.NET applications that don't have containerized equivalents
- Integrate command-line tools or utilities into your application
- Run external processes that other resources depend on
- Develop with tools that provide local development servers
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why do you always mistakenly not account for the .github/copilot-instructions.md file? You're supposed to use complete sentences and proper punctuation for lists.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed the list formatting by adding proper punctuation (periods) to complete sentences as specified in the .github/copilot-instructions.md file.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Was this done for the entire document, or just the single section I commented on. It needs to apply to all MD files you create.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Applied the punctuation fix to the entire document. All lists containing complete sentences now have proper periods, including the method parameters section (lines 48-51) and the best practices section (lines 265-270). Commit e6c968e.

…zure SWA CLI with Vercel CLI

Co-authored-by: IEvangelist <[email protected]>
Copilot finished work on behalf of IEvangelist August 4, 2025 20:52
@Copilot Copilot AI requested a review from IEvangelist August 4, 2025 20:52
Copilot finished work on behalf of IEvangelist August 4, 2025 20:59
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

[New article]: Using ExecutableResource
2 participants