Add how-to guide for adopting Aspire in existing applications

[Copilot]

Add how-to guide for adopting Aspire in existing applications

✅ All Feedback Addressed

Addresses #60 by documenting the gradual adoption path for adding Aspire orchestration to existing .NET applications using aspire init.

Changes

New how-to guide

• Added /get-started/add-aspire-existing-app/ covering the incremental adoption workflow
• Explains file-based AppHost (apphost.cs) created by aspire init
• Documents the three-phase optional approach: aspire init → ServiceDefaults → integrations
• Supports polyglot applications (C#, Python, JavaScript)

Key sections

• Initialize: aspire init interactive mode walkthrough for creating file-based AppHost
• Add applications: Register C#, Python, and JavaScript applications
• Telemetry: Optional OpenTelemetry configuration for all languages
• Integrations: Example migration using Redis with automatic configuration injection
• Verification: Running with aspire run and dashboard exploration

Latest fixes

• ✅ Added missing PeriodicExportingMetricReader import to JavaScript telemetry example (commit d9bfcd4)
• ✅ Added "How-to" badge back to sidebar navigation with translations (commit current)

Configuration injection

Explains how Aspire's AppHost automatically injects configuration from hosting integrations into dependent resources:

• Connection strings
• URLs
• Environment variables
• Service-specific settings

These are passed through .NET's standard configuration system, eliminating manual connection string management.

Example: Adding Redis integration

// AppHost: Add Redis resource
var cache = builder.AddRedis("cache");
var api = builder.AddProject<Projects.YourApi>("api")
    .WithReference(cache);  // Aspire injects connection info automatically

// Service: Configure client
builder.AddRedisClient("cache");  // Connection string injected via configuration

Navigation

• Added to sidebar under "Get started" with "How-to" badge
• Includes translations for 15 languages
• Links to CLI reference documentation throughout

The guide emphasizes minimal code changes and non-invasive integration, addressing the OP's request for "where to start from" and "how to do this gradually."

Original prompt

Please start a draft PR to address #60 - use aspire init and describe what that does, link to cli reference in a learn more. Consider everything the op is specifically asking for and also have a look at what we've done on Learn from this here https://learn.microsoft.com/dotnet/aspire/get-started/add-aspire-existing-app

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[IEvangelist]

Hey @copilot, please address feedback.

[Copilot]

Hey @copilot, please address feedback.

All feedback addressed in commit 11c311f:

• Changed badge to "How-to" with translations
• Removed project-based AppHost references (only file-based apphost.cs)
• Added configuration injection explanation
• Fixed mark highlighting

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• telemetry.astro.build
  • Triggering command: node /home/REDACTED/.npm/_npx/aa98e6899c6baff3/node_modules/.bin/astro build (dns block)
  • Triggering command: node /home/REDACTED/work/aspire.dev/aspire.dev/src/frontend/node_modules/.bin/astro dev (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

[Copilot]

Pull Request Overview

This PR adds a comprehensive how-to guide for adopting Aspire orchestration in existing applications. The guide demonstrates using aspire init to incrementally add Aspire to C#, Python, and JavaScript applications without requiring a full rewrite.

Key changes:

• New documentation file explaining the gradual adoption workflow using file-based AppHosts
• Updated InstallPackage component to support omitting PackageReference tab for certain scenarios
• Added sidebar navigation entry with internationalized translations across 15 languages

Reviewed Changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

File	Description
src/frontend/src/content/docs/get-started/add-aspire-existing-app.mdx	Complete how-to guide covering aspire init, polyglot orchestration, telemetry setup, and integrations
src/frontend/src/components/InstallPackage.astro	Added optional omitPackageReference prop to conditionally hide PackageReference tab
src/frontend/sidebar.topics.ts	Added sidebar entry with translations for the new guide
src/frontend/src/data/aspire-integrations.json	Updated NuGet package download counts (automated update)

Comments suppressed due to low confidence (1)

src/frontend/src/components/InstallPackage.astro:31

• The title variable uses AppHost.cs (uppercase) but the tab label on line 54 uses apphost.cs (lowercase). For consistency with file-based AppHosts, the title should be C# — apphost.cs to match the lowercase convention used throughout the codebase for file-based AppHosts.

const appHostTitle = `C# — AppHost.cs`;

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[IEvangelist]

@copilot apply changes based on the comments in this thread

[Copilot]

Just as a heads up, I was blocked by some firewall rules while working on your feedback. Expand below for details.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• telemetry.astro.build
  • Triggering command: node /home/REDACTED/work/aspire.dev/aspire.dev/src/frontend/node_modules/.bin/astro dev (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

[Copilot]

@copilot apply changes based on the comments in this thread

Added the "How-to" badge back to the sidebar navigation with variant "note" and translations for all 15 languages in commit fbac9b8.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• telemetry.astro.build
  • Triggering command: node /home/REDACTED/work/aspire.dev/aspire.dev/src/frontend/node_modules/.bin/astro dev (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

[Meir017]

Minor comments here

[Meir017]

@IEvangelist It might be better to have a single location that describes the requirements for aspire (.NET version and IDEs) abd then reference it, instead of having minimal instructions in multiple pages

[IEvangelist]

@IEvangelist It might be better to have a single location that describes the requirements for aspire (.NET version and IDEs) abd then reference it, instead of having minimal instructions in multiple pages

You're right! This is what we did on Learn, where we had a Setup and tooling doc with environment selector. Seems similar to what @mitchdenny was suggesting here too in #64.