diff --git a/package.json b/package.json index 286b910b..b50ddcaa 100644 --- a/package.json +++ b/package.json @@ -1,14 +1,14 @@ { - "name": "root", - "private": true, - "description": "Root-level package.json delegating to src/frontend.", - "scripts": { - "install": "cd src/frontend && pnpm i", - "dev": "cd src/frontend && pnpm dev", - "build": "cd src/frontend && pnpm build", - "preview": "cd src/frontend && pnpm preview", - "lint": "cd src/frontend && pnpm lint", - "format": "cd src/frontend && pnpm format", - "update:all": "cd src/frontend && pnpm update:all" - } -} \ No newline at end of file + "name": "root", + "private": true, + "description": "Root-level package.json delegating to src/frontend.", + "scripts": { + "install": "pnpm --dir ./src/frontend i", + "dev": "pnpm --dir ./src/frontend run dev", + "build": "pnpm --dir ./src/frontend run build", + "preview": "pnpm --dir ./src/frontend run preview", + "lint": "pnpm --dir ./src/frontend run lint", + "format": "pnpm --dir ./src/frontend run format", + "update:all": "pnpm run update:all --dir ./src/frontend" + } +} diff --git a/src/frontend/config/sidebar/docs.topics.ts b/src/frontend/config/sidebar/docs.topics.ts index 8548a699..52012927 100644 --- a/src/frontend/config/sidebar/docs.topics.ts +++ b/src/frontend/config/sidebar/docs.topics.ts @@ -89,48 +89,128 @@ export const docsTopics: StarlightSidebarTopicsUserConfig = { }, items: [ { - label: 'Prerequisites', + label: 'Setup and tooling', + collapsed: true, translations: { - da: 'Forudsætninger', - de: 'Voraussetzungen', - en: 'Prerequisites', - es: 'Requisitos previos', - fr: 'Prérequis', - hi: 'पूर्वापेक्षाएँ', - id: 'Prasyarat', - it: 'Prerequisiti', - ja: '事前準備', - ko: '전제 조건', - 'pt-BR': 'Pré-requisitos', - 'pt-PT': 'Pré-requisitos', - ru: 'Предварительные требования', - tr: 'Ön koşullar', - uk: 'Попередні вимоги', - 'zh-CN': '先决条件', - }, - slug: 'get-started/prerequisites', - }, - { - label: 'Install CLI', - translations: { - da: 'Installer CLI', - de: 'CLI installieren', - en: 'Install CLI', - es: 'Instalar CLI', - fr: 'Installer CLI', - hi: 'CLI इंस्टॉल करें', - id: 'Instal CLI', - it: 'Installa CLI', - ja: 'CLI をインストールする', - ko: 'CLI 설치', - 'pt-BR': 'Instalar CLI', - 'pt-PT': 'Instalar CLI', - ru: 'Установить CLI', - tr: 'CLI Kur', - uk: 'Встановити CLI', - 'zh-CN': '安装 CLI', - }, - slug: 'get-started/install-cli', + da: 'Opsætning og værktøjer', + de: 'Einrichtung und Werkzeuge', + en: 'Setup and tooling', + es: 'Configuración y herramientas', + fr: 'Configuration et outils', + hi: 'सेटअप और टूलिंग', + id: 'Pengaturan dan alat', + it: 'Configurazione e strumenti', + ja: 'セットアップとツール', + ko: '설정 및 도구', + 'pt-BR': 'Configuração e ferramentas', + 'pt-PT': 'Configuração e ferramentas', + ru: 'Настройка и инструменты', + tr: 'Kurulum ve araçlar', + uk: 'Налаштування та інструменти', + 'zh-CN': '设置和工具', + }, + items: [ + { + label: 'Prerequisites', + translations: { + da: 'Forudsætninger', + de: 'Voraussetzungen', + en: 'Prerequisites', + es: 'Requisitos previos', + fr: 'Prérequis', + hi: 'पूर्वापेक्षाएँ', + id: 'Prasyarat', + it: 'Prerequisiti', + ja: '事前準備', + ko: '전제 조건', + 'pt-BR': 'Pré-requisitos', + 'pt-PT': 'Pré-requisitos', + ru: 'Предварительные требования', + tr: 'Ön koşullar', + uk: 'Попередні вимоги', + 'zh-CN': '先决条件', + }, + slug: 'get-started/prerequisites', + }, + { + label: 'Install CLI', + translations: { + da: 'Installer CLI', + de: 'CLI installieren', + en: 'Install CLI', + es: 'Instalar CLI', + fr: 'Installer CLI', + hi: 'CLI इंस्टॉल करें', + id: 'Instal CLI', + it: 'Installa CLI', + ja: 'CLI をインストールする', + ko: 'CLI 설치', + 'pt-BR': 'Instalar CLI', + 'pt-PT': 'Instalar CLI', + ru: 'Установить CLI', + tr: 'CLI Kur', + uk: 'Встановити CLI', + 'zh-CN': '安装 CLI', + }, + slug: 'get-started/install-cli', + }, + { + label: 'VS Code extension', + translations: { + da: 'VS Code-udvidelse', + de: 'VS Code-Erweiterung', + en: 'VS Code extension', + es: 'Extensión de VS Code', + fr: 'Extension VS Code', + hi: 'VS Code एक्सटेंशन', + id: 'Ekstensi VS Code', + it: 'Estensione VS Code', + ja: 'VS Code 拡張機能', + ko: 'VS Code 확장', + 'pt-BR': 'Extensão VS Code', + 'pt-PT': 'Extensão VS Code', + ru: 'Расширение VS Code', + tr: 'VS Code uzantısı', + uk: 'Розширення VS Code', + 'zh-CN': 'VS Code 扩展', + }, + slug: 'get-started/aspire-vscode-extension', + }, + { + label: 'Dev Containers', + slug: 'get-started/dev-containers', + }, + { + label: 'GitHub Codespaces', + slug: 'get-started/github-codespaces', + }, + { + label: 'Aspire SDK', + slug: 'get-started/aspire-sdk', + }, + { + label: 'Aspire templates', + translations: { + da: 'Aspire-skabeloner', + de: 'Aspire-Vorlagen', + en: 'Aspire templates', + es: 'Plantillas de Aspire', + fr: 'Modèles Aspire', + hi: 'Aspire टेम्प्लेट', + id: 'Template Aspire', + it: 'Modelli Aspire', + ja: 'Aspire テンプレート', + ko: 'Aspire 템플릿', + 'pt-BR': 'Modelos do Aspire', + 'pt-PT': 'Modelos do Aspire', + ru: 'Шаблоны Aspire', + tr: 'Aspire şablonları', + uk: 'Шаблони Aspire', + 'zh-CN': 'Aspire 模板', + }, + slug: 'get-started/aspire-sdk-templates', + }, + ], }, { label: 'Build your first app', diff --git a/src/frontend/src/assets/get-started/aspire-dashboard-in-devcontainer.png b/src/frontend/src/assets/get-started/aspire-dashboard-in-devcontainer.png new file mode 100644 index 00000000..09f7600a Binary files /dev/null and b/src/frontend/src/assets/get-started/aspire-dashboard-in-devcontainer.png differ diff --git a/src/frontend/src/assets/get-started/browser-certificate-error.png b/src/frontend/src/assets/get-started/browser-certificate-error.png new file mode 100644 index 00000000..f69efa83 Binary files /dev/null and b/src/frontend/src/assets/get-started/browser-certificate-error.png differ diff --git a/src/frontend/src/assets/get-started/building-codespace-image.png b/src/frontend/src/assets/get-started/building-codespace-image.png new file mode 100644 index 00000000..918860c6 Binary files /dev/null and b/src/frontend/src/assets/get-started/building-codespace-image.png differ diff --git a/src/frontend/src/assets/get-started/code-extension-create-aspire-project-light.png b/src/frontend/src/assets/get-started/code-extension-create-aspire-project-light.png new file mode 100644 index 00000000..c44094cf Binary files /dev/null and b/src/frontend/src/assets/get-started/code-extension-create-aspire-project-light.png differ diff --git a/src/frontend/src/assets/get-started/code-extension-create-aspire-project.png b/src/frontend/src/assets/get-started/code-extension-create-aspire-project.png new file mode 100644 index 00000000..d25978dc Binary files /dev/null and b/src/frontend/src/assets/get-started/code-extension-create-aspire-project.png differ diff --git a/src/frontend/src/assets/get-started/codespace-launch-apphost.png b/src/frontend/src/assets/get-started/codespace-launch-apphost.png new file mode 100644 index 00000000..57b0496a Binary files /dev/null and b/src/frontend/src/assets/get-started/codespace-launch-apphost.png differ diff --git a/src/frontend/src/assets/get-started/codespace-terminal.png b/src/frontend/src/assets/get-started/codespace-terminal.png new file mode 100644 index 00000000..f15e2715 Binary files /dev/null and b/src/frontend/src/assets/get-started/codespace-terminal.png differ diff --git a/src/frontend/src/assets/get-started/codespaces-debug-console.png b/src/frontend/src/assets/get-started/codespaces-debug-console.png new file mode 100644 index 00000000..94672ab2 Binary files /dev/null and b/src/frontend/src/assets/get-started/codespaces-debug-console.png differ diff --git a/src/frontend/src/assets/get-started/codespaces-explorer-panel.png b/src/frontend/src/assets/get-started/codespaces-explorer-panel.png new file mode 100644 index 00000000..c283cc92 Binary files /dev/null and b/src/frontend/src/assets/get-started/codespaces-explorer-panel.png differ diff --git a/src/frontend/src/assets/get-started/codespaces-translated-urls.png b/src/frontend/src/assets/get-started/codespaces-translated-urls.png new file mode 100644 index 00000000..d260045c Binary files /dev/null and b/src/frontend/src/assets/get-started/codespaces-translated-urls.png differ diff --git a/src/frontend/src/assets/get-started/create-codespace-from-repository.png b/src/frontend/src/assets/get-started/create-codespace-from-repository.png new file mode 100644 index 00000000..bc08d2e5 Binary files /dev/null and b/src/frontend/src/assets/get-started/create-codespace-from-repository.png differ diff --git a/src/frontend/src/assets/get-started/devcontainer-build-completed.png b/src/frontend/src/assets/get-started/devcontainer-build-completed.png new file mode 100644 index 00000000..82333fc0 Binary files /dev/null and b/src/frontend/src/assets/get-started/devcontainer-build-completed.png differ diff --git a/src/frontend/src/assets/get-started/install-aspire-code-extension-light.png b/src/frontend/src/assets/get-started/install-aspire-code-extension-light.png new file mode 100644 index 00000000..6fdb15a9 Binary files /dev/null and b/src/frontend/src/assets/get-started/install-aspire-code-extension-light.png differ diff --git a/src/frontend/src/assets/get-started/install-aspire-code-extension.png b/src/frontend/src/assets/get-started/install-aspire-code-extension.png new file mode 100644 index 00000000..7c874a7e Binary files /dev/null and b/src/frontend/src/assets/get-started/install-aspire-code-extension.png differ diff --git a/src/frontend/src/assets/get-started/new-repository-from-template.png b/src/frontend/src/assets/get-started/new-repository-from-template.png new file mode 100644 index 00000000..5a0a5afc Binary files /dev/null and b/src/frontend/src/assets/get-started/new-repository-from-template.png differ diff --git a/src/frontend/src/assets/get-started/reopen-in-container.png b/src/frontend/src/assets/get-started/reopen-in-container.png new file mode 100644 index 00000000..25ae0595 Binary files /dev/null and b/src/frontend/src/assets/get-started/reopen-in-container.png differ diff --git a/src/frontend/src/assets/get-started/vs-create-dotnet-aspire-proj.png b/src/frontend/src/assets/get-started/vs-create-dotnet-aspire-proj.png new file mode 100644 index 00000000..5817073d Binary files /dev/null and b/src/frontend/src/assets/get-started/vs-create-dotnet-aspire-proj.png differ diff --git a/src/frontend/src/assets/get-started/vscode-run-button.png b/src/frontend/src/assets/get-started/vscode-run-button.png new file mode 100644 index 00000000..542365aa Binary files /dev/null and b/src/frontend/src/assets/get-started/vscode-run-button.png differ diff --git a/src/frontend/src/components/PivotSelector.astro b/src/frontend/src/components/PivotSelector.astro index 346707e8..ce4836b6 100644 --- a/src/frontend/src/components/PivotSelector.astro +++ b/src/frontend/src/components/PivotSelector.astro @@ -571,10 +571,7 @@ const { options, key, title } = Astro.props; // Collapse/Expand functionality const collapseBtn = document.getElementById(`pivot-collapse-${key}`); const expandBtn = document.getElementById(`pivot-expand-${key}`); - const collapseStorageKey = `${key}-collapsed`; - // Check if user previously collapsed this pivot, default to true (collapsed) - const wasCollapsed = localStorage.getItem(collapseStorageKey) !== 'false'; let isCollapsed = false; let autoCollapseTimer = null; let userExpanded = false; // Track if user manually expanded @@ -585,12 +582,10 @@ const { options, key, title } = Astro.props; if (collapsed) { container.classList.add('collapsed'); - localStorage.setItem(collapseStorageKey, 'true'); clearAutoCollapseTimer(); enableScrollCollapse = false; } else { container.classList.remove('collapsed'); - localStorage.setItem(collapseStorageKey, 'false'); // If user manually expanded, mark it and start auto-collapse timer if (isUserAction) { @@ -619,8 +614,8 @@ const { options, key, title } = Astro.props; } } - // Restore collapsed state if it was floating and previously collapsed - if (wasCollapsed && isFloating) { + // Always start collapsed when floating + if (isFloating) { setCollapsed(true); } @@ -674,8 +669,8 @@ const { options, key, title } = Astro.props; const wasFloatingBefore = isFloating; originalUpdateFloatingState(); - // If we just became floating and user had it collapsed, restore that state - if (!wasFloatingBefore && isFloating && wasCollapsed) { + // Always collapse when becoming floating + if (!wasFloatingBefore && isFloating) { setCollapsed(true); } // If we're no longer floating, remove collapsed state @@ -685,10 +680,6 @@ const { options, key, title } = Astro.props; userExpanded = false; enableScrollCollapse = false; } - // If we just became floating and it's not collapsed, start auto-collapse timer - if (!wasFloatingBefore && isFloating && !isCollapsed) { - startAutoCollapseTimer(); - } }; } diff --git a/src/frontend/src/content/docs/get-started/aspire-sdk-templates.mdx b/src/frontend/src/content/docs/get-started/aspire-sdk-templates.mdx new file mode 100644 index 00000000..e21b8ab6 --- /dev/null +++ b/src/frontend/src/content/docs/get-started/aspire-sdk-templates.mdx @@ -0,0 +1,174 @@ +--- +title: Aspire templates +description: Learn about the Aspire templates and how to use them to create new apps. +--- + +import { Image } from 'astro:assets'; +import ThemeImage from '@components/ThemeImage.astro'; +import createProject from '@assets/get-started/code-extension-create-aspire-project.png'; +import createProjectLight from '@assets/get-started/code-extension-create-aspire-project-light.png'; +import vsCreateProj from '@assets/get-started/vs-create-dotnet-aspire-proj.png'; +import PivotSelector from '@components/PivotSelector.astro'; +import Pivot from '@components/Pivot.astro'; +import LearnMore from '@components/LearnMore.astro'; + +Aspire provides a number of project templates to help you create new apps. You can use these templates to create full Aspire solutions, or add individual projects to existing Aspire solutions. + +The Aspire templates are available in the [📦 Aspire.ProjectTemplates](https://www.nuget.org/packages/Aspire.ProjectTemplates) NuGet package. + +## Available templates + +The Aspire templates allow you to create new apps pre-configured with the Aspire solutions structure and default settings. These projects also provide a unified debugging experience across the different resources of your app. + +Aspire templates are available in two categories: solution templates and project templates. Solution templates create a new Aspire solution with multiple projects, while project templates create individual projects that can be added to an existing Aspire solution. + +### Solution templates + +The following Aspire solution templates are available (assume the solution is named _AspireSample_): + +- **Aspire Empty App**: A minimal Aspire project that includes the following: + - **AspireSample.AppHost**: An orchestrator project designed to connect and configure the different projects and services of your app. + - **AspireSample.ServiceDefaults**: An Aspire shared project to manage configurations that are reused across the projects in your solution related to [resilience](https://learn.microsoft.com/dotnet/core/resilience/http-resilience), [service discovery](/fundamentals/service-discovery/), and [telemetry](/fundamentals/telemetry/). + +- **Aspire Starter App**: In addition to the AppHost and ServiceDefaults projects, the Aspire Starter App also includes the following: + - **AspireSample.ApiService**: An [ASP.NET Core Minimal API](https://learn.microsoft.com/aspnet/core/fundamentals/minimal-apis) project is used to provide data to the frontend. This project depends on the shared ServiceDefaults project. + - **AspireSample.Web**: An [ASP.NET Core Blazor App](https://learn.microsoft.com/aspnet/core/blazor) project with default Aspire service configurations, this project depends on the ServiceDefaults project. + - **AspireSample.Test**: Either an MSTest, NUnit, or xUnit test project with project references to the AppHost and an example _WebTests.cs_ file demonstrating an integration test. + +- **Aspire Starter App with ASP.NET Core and React**: This template includes the AppHost and ServiceDefaults projects, plus: + - **AspireSample.ApiService**: An [ASP.NET Core Minimal API](https://learn.microsoft.com/aspnet/core/fundamentals/minimal-apis) project that provides data to the frontend. + - **AspireSample.Web**: A React-based frontend application with TypeScript configured to work with the Aspire app. + +- **Aspire Starter App with FastAPI and React**: This template provides a Python-based starter app with the following projects: + - **AspireSample.AppHost**: The orchestrator project for managing the app's services. + - **AspireSample.ApiService**: A [FastAPI](https://fastapi.tiangolo.com/) Python backend service that provides data to the frontend. + - **AspireSample.Web**: A React-based frontend application with TypeScript. + + For more information on getting started with Python in Aspire, see [Build your first app](/get-started/first-app/?lang=python). + +### Project templates + +The following Aspire project templates are available: + +- **Aspire AppHost**: A standalone AppHost project that can be used to orchestrate and manage the different projects and services of your app. + +- **Aspire Test projects**: These project templates are used to create test projects for your Aspire app, and they're intended to represent functional and integration tests. The test projects include the following templates: + - **MSTest**: A project that contains MSTest integration of an Aspire AppHost project. + - **NUnit**: A project that contains NUnit integration of an Aspire AppHost project. + - **xUnit**: A project that contains xUnit.net integration of an Aspire AppHost project. + + For more information on the test templates, see [Testing overview](/testing/overview/). + +- **Aspire Service Defaults**: A standalone ServiceDefaults project that can be used to manage configurations that are reused across the projects in your solution related to [resilience](https://learn.microsoft.com/dotnet/core/resilience/http-resilience), [service discovery](/fundamentals/service-discovery/), and [telemetry](/fundamentals/telemetry/). + +:::caution +The service defaults project template takes a `FrameworkReference` dependency on `Microsoft.AspNetCore.App`. This may not be ideal for some project types. For more information, see [Aspire service defaults](/fundamentals/service-defaults/). +::: + +## Install the Aspire templates + +The Aspire templates are included with the Aspire workload. To install the templates, run the following command: + +```bash title=".NET CLI" +dotnet new install Aspire.ProjectTemplates +``` + +:::tip +To install a specific version of the Aspire templates, use the `::{version}` syntax. For example, to install version 13.1.0, run the following command: + +```bash title=".NET CLI" +dotnet new install Aspire.ProjectTemplates::13.1.0 +``` +::: + +## Create solutions and projects using templates + +To create an Aspire solution or project, use Visual Studio, Visual Studio Code, or the Aspire CLI, and base it on the available templates. Explore additional Aspire templates in the [Aspire samples](https://github.com/dotnet/aspire-samples) repository. + +
+ + + + +To create an Aspire project using Visual Studio, search for *Aspire* in the Visual Studio new project window and select your desired template. + +Visual Studio: Aspire templates showing various Aspire project templates available for selection. + +Follow the prompts to configure your project or solution from the template, and then select **Create**. + + + + +To create an Aspire project using Visual Studio Code, search for *Aspire* in the Visual Studio Code new project window and select your desired template. + + + +Select the desired location, enter a name, and select **Create**. + + + + +To create an Aspire solution or project using the Aspire CLI, use the `aspire new` command and specify which template you would like to create. + + + For detailed information about the `aspire new` command and all available options, see the [aspire new command reference](/reference/cli/commands/aspire-new/). + + +Consider the following examples: + +To create an empty AppHost project: + +```bash title="Aspire CLI" +aspire new aspire-apphost-singlefile +``` + +To create an Aspire starter app (ASP.NET Core/Blazor), which is a full solution with a sample UI and backing API: + +```bash title="Aspire CLI" +aspire new aspire-starter +``` + +To create an Aspire starter app with ASP.NET Core and React: + +```bash title="Aspire CLI" +aspire new aspire-ts-cs-starter +``` + +To create an Aspire starter app with FastAPI and React: + +```bash title="Aspire CLI" +aspire new aspire-py-starter +``` + +:::tip +The `aspire new` command runs in interactive mode by default. When you don't provide options like `--name` or `--output`, the command prompts you for these values. To run non-interactively, provide all required options: + +```bash title="Aspire CLI" +aspire new aspire-starter --name MyApp --output ./projects +``` +::: + +You need to trust the ASP.NET Core localhost certificate before running the app. Run the following command: + +```bash title=".NET CLI" +dotnet dev-certs https --trust +``` + +For more information, see [Troubleshoot untrusted localhost certificate](https://learn.microsoft.com/dotnet/aspire/troubleshooting/untrusted-localhost-certificate). For in-depth details about troubleshooting localhost certificates on Linux, see [ASP.NET Core: GitHub repository issue #32842](https://github.com/dotnet/aspnetcore/issues/32842). + + diff --git a/src/frontend/src/content/docs/get-started/aspire-sdk.mdx b/src/frontend/src/content/docs/get-started/aspire-sdk.mdx new file mode 100644 index 00000000..c0a31d10 --- /dev/null +++ b/src/frontend/src/content/docs/get-started/aspire-sdk.mdx @@ -0,0 +1,72 @@ +--- +title: Aspire SDK +description: Learn about the Aspire SDK and how it simplifies orchestrating Aspire applications. +--- + +import { Tabs, TabItem } from '@astrojs/starlight/components'; + +The Aspire SDK is intended for [AppHost projects](/get-started/app-host/), which serve as the orchestrator for Aspire applications. These projects are designated by their usage of the `Aspire.AppHost.Sdk` in the project file. The SDK provides features that simplify the development of Aspire apps. + +The [📦 Aspire.AppHost.Sdk](https://www.nuget.org/packages/Aspire.AppHost.Sdk) is used for building Aspire apps. + + + + + +The `Aspire.AppHost.Sdk` is defined in the top-level `Project` node's `Sdk` attribute: + +```xml title='XML — *.csproj file' {1} + + + + Exe + net10.0 + + + + + +``` + + + + +The `Aspire.AppHost.Sdk` is defined in a file-based app's source file using the `#:sdk` directive: + +```csharp title='C# — file-based app' {1} +#:sdk Aspire.AppHost.Sdk@13.1.0 + +var builder = DistributedApplication.CreateBuilder(args); + +// Omitted for brevity +``` + + + + + +The preceding example defines the top-level SDK as `Aspire.AppHost.Sdk`. The project also references the [📦 Aspire.Hosting.AppHost](https://www.nuget.org/packages/Aspire.Hosting.AppHost) package which brings in a number of Aspire-related dependencies. + +## SDK Features + +The Aspire SDK provides several key features. + +### Project references + +Each `ProjectReference` in the AppHost project isn't treated as standard project references. Instead, they enable the AppHost to execute these projects as part of its orchestration. Each project reference triggers a generator to create a `class` that represents the project as an `IProjectMetadata`. This metadata is used to populate the named projects in the generated `Projects` namespace. When you call the `AddProject` API, the `Projects` namespace is used to reference the project—passing the generated class as a generic-type parameter. + +:::tip +To prevent a project from being treated as an Aspire resource in the AppHost, set the `IsAspireProjectResource` attribute on the `ProjectReference` element to `false`, as shown in the following example: + +```xml + +``` + +Otherwise, by default, the `ProjectReference` is treated as Aspire project resource. +::: + +### Orchestrator dependencies + +The Aspire SDK dynamically adds references to the [Aspire dashboard](/dashboard/overview/) and other AppHost dependencies, such as the developer control plane (DCP) packages. These dependencies are specific to the platform that the AppHost is built on. + +When the AppHost project runs, the orchestrator relies on these dependencies to provide the necessary functionality to the AppHost. For more information, see [Aspire orchestration overview](/get-started/app-host/). diff --git a/src/frontend/src/content/docs/get-started/aspire-vscode-extension.mdx b/src/frontend/src/content/docs/get-started/aspire-vscode-extension.mdx new file mode 100644 index 00000000..f275323c --- /dev/null +++ b/src/frontend/src/content/docs/get-started/aspire-vscode-extension.mdx @@ -0,0 +1,233 @@ +--- +title: Aspire Visual Studio Code extension +description: Learn how to use the Aspire Visual Studio Code extension to create, configure, run, and deploy Aspire solutions. +--- + +import { Steps } from '@astrojs/starlight/components'; +import ThemeImage from '@components/ThemeImage.astro'; +import installExtension from '@assets/get-started/install-aspire-code-extension.png'; +import installExtensionLight from '@assets/get-started/install-aspire-code-extension-light.png'; +import createProject from '@assets/get-started/code-extension-create-aspire-project.png'; +import createProjectLight from '@assets/get-started/code-extension-create-aspire-project-light.png'; +import { Kbd } from 'starlight-kbd/components'; + +The Aspire Visual Studio Code extension provides a set of commands and tools to streamline your work with Aspire within Visual Studio Code. The extension includes commands to create projects, add integrations, configure solutions, and manage deployments. The extension requires the Aspire CLI and provides similar functionality on the Visual Studio Code command palette. + +## Prerequisites + +Before you can use the Aspire Visual Studio Code extension, you need: + +- The [Aspire CLI](/reference/cli/overview/) installed and available on your PATH + +## Install the Aspire extension + +To install the Aspire VS Code extension: + + + +1. Open VS Code. +1. Open the **Extensions** view by selecting **View** > **Extensions** or pressing . +1. Search for "aspire" in the Extensions marketplace. +1. Select the **Aspire** extension published by **Microsoft**. +1. Select **Install**. + + + + + +Alternatively, you can install the extension directly from the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=microsoft-aspire.aspire-vscode). + +## Access extension commands + +All Aspire extension commands are available from the VS Code Command Palette: + + + +1. Open the Command Palette by pressing . +1. Type "Aspire" to filter and display all available Aspire commands. +1. Select the desired command from the list. + + + +All commands are grouped under the **Aspire** category in the Command Palette for easy discovery. + +## Available commands + +The Aspire VS Code extension provides the following commands: + +| Command | Description | Availability | +|--|--|--| +| Aspire: New Aspire project | Create a new Aspire apphost or starter app from a template. | Available | +| Aspire: Add an integration | Add a hosting integration (`Aspire.Hosting.*`) to the Aspire apphost. | Available | +| Aspire: Configure launch.json | Adds the default Aspire debugger launch configuration to your workspace's `launch.json`, which will detect and run the apphost in the workspace. | Available | +| Aspire: Manage configuration settings | Manage configuration settings including feature flags. | Available | +| Aspire: Open Aspire terminal | Open an Aspire VS Code terminal for working with Aspire projects. | Available | +| Aspire: Publish deployment artifacts | Generates deployment artifacts for an Aspire apphost. | Preview | +| Aspire: Deploy app | Deploy the contents of an Aspire apphost to its defined deployment targets. | Preview | +| Aspire: Update integrations | Update hosting integrations and Aspire SDK in the apphost. | Preview | + +## Create a new Aspire app + +To create a new Aspire app using the extension: + + + +1. Open the Command Palette (). +1. Run the **Aspire: New Aspire project** command. +1. Select the desired template. +1. Specify the project name and location. + + + + + +The extension creates the project and opens it in VS Code. + +## Add an integration to the Aspire solution + +Aspire integrations provide pre-configured connections to various cloud services and dependencies. To add an integration: + + + +1. Open the Command Palette. +1. Run the **Aspire: Add an integration** command. +1. Browse or search for the desired integration package. +1. Select the integration to add it to your AppHost project. + + + +The extension adds the appropriate NuGet package reference to your AppHost project. + +:::note +The **Add an integration** command adds a hosting integration to the AppHost project. It doesn't add the corresponding client integration to any consuming projects. +::: + +## Configure an Aspire solution + +The Aspire extension includes several commands that configure the behavior of Aspire and the Aspire CLI during development: + +### Configure launch.json for debugging + +To run and debug your Aspire application in VS Code, you need to configure the `launch.json` file: + + + +1. Open the Command Palette. +1. Run the **Aspire: Configure launch.json** command. +1. The extension adds a default Aspire debugger configuration to your workspace's `launch.json` file. + + + +The default configuration looks like this: + +```json title='.vscode/launch.json' +{ + "type": "aspire", + "request": "launch", + "name": "Aspire: Launch Default AppHost", + "program": "${workspaceFolder}" +} +``` + +You can customize the `program` field to point to a specific AppHost project file. For example: + +```json title='.vscode/launch.json' +{ + "type": "aspire", + "request": "launch", + "name": "Aspire: Launch MyAppHost", + "program": "${workspaceFolder}/MyAppHost/MyAppHost.csproj" +} +``` + +### Manage configuration settings + +The **Aspire: Manage configuration settings** command executes `aspire config` request options and displays the results in the VS Code terminal. Use `get` and `set` commands to configure the Aspire CLI. Use the `list` command to show current configuration values. + +## Run an Aspire solution in development mode + +To run your Aspire application in development mode: + + + +1. Ensure you have configured `launch.json` as described in the [Configure launch.json for debugging](#configure-launchjson-for-debugging) section. +1. Open the Run and Debug view by selecting **View** > **Run** or pressing . +1. Select your Aspire launch configuration from the dropdown. +1. Select the green **Start Debugging** button or press . + + + +The extension builds and starts the AppHost project, launches the Aspire dashboard in your browser, and enables debugging for all resources in your solution. + +Alternatively, you can open an Aspire VS Code terminal using `Aspire: Open Aspire terminal` and run `aspire run --start-debug-session` to start a VS Code debug session. + +### Run or debug from the editor + +When an AppHost project is detected in your workspace, you can also run or debug it directly from the editor. Use the run buttons in the editor title bar when viewing an AppHost file. + +## Publish deployment artifacts + +:::caution +This feature is in **Preview**. +::: + +The **Aspire: Publish deployment artifacts** command generates deployment artifacts for your Aspire AppHost. This command serializes resources to disk, allowing them to be consumed by deployment tools. + +To publish deployment artifacts: + + + +1. Open the Command Palette. +1. Run the **Aspire: Publish deployment artifacts** command. +1. Select the output location for the generated artifacts. + + + +The command invokes registered publishing callback annotations to generate artifacts such as: + +- Bicep files for Azure resources. +- Docker Compose YAML files. +- Kubernetes Helm charts. + +For more information about Aspire publishing, see [Aspire publishing and deployment overview](/deployment/overview/). + +## Deploy an Aspire solution + +:::caution +This feature is in **Preview**. +::: + +The **Aspire: Deploy app host** command deploys the contents of an Aspire AppHost to its defined deployment targets. + +To deploy an Aspire solution: + + + +1. Open the Command Palette. +1. Run the **Aspire: Deploy app host** command. +1. Follow the prompts to select deployment targets and provide any required configuration. + + + +The command publishes deployment artifacts and then invokes deployment callback annotations to deploy resources to the specified targets. + +For more information about Aspire deployment, see [Aspire publishing and deployment overview](/deployment/overview/). + +## Open Aspire terminal + +The **Aspire: Open Aspire terminal** command opens a terminal window configured for working with Aspire projects. This terminal provides easy access to Aspire CLI commands and is preconfigured with the appropriate environment variables. + +## Feedback and issues + +To report issues or request features for the Aspire VS Code extension: + +1. Visit the [Aspire GitHub repository](https://github.com/dotnet/aspire/issues). +1. Create a new issue and add the `area-extension` label. diff --git a/src/frontend/src/content/docs/get-started/dev-containers.mdx b/src/frontend/src/content/docs/get-started/dev-containers.mdx new file mode 100644 index 00000000..68717237 --- /dev/null +++ b/src/frontend/src/content/docs/get-started/dev-containers.mdx @@ -0,0 +1,320 @@ +--- +title: Dev Containers in Visual Studio Code +description: Learn how to use Aspire with Dev Containers in Visual Studio Code for containerized development environments. +--- + +import { Image } from 'astro:assets'; +import { FileTree, Steps } from '@astrojs/starlight/components'; +import { Kbd } from 'starlight-kbd/components'; +import newRepoFromTemplate from '@assets/get-started/new-repository-from-template.png'; +import reopenInContainer from '@assets/get-started/reopen-in-container.png'; +import devcontainerBuildCompleted from '@assets/get-started/devcontainer-build-completed.png'; +import vscodeRunButton from '@assets/get-started/vscode-run-button.png'; +import browserCertError from '@assets/get-started/browser-certificate-error.png'; +import aspireDashboard from '@assets/get-started/aspire-dashboard-in-devcontainer.png'; + +The [Dev Containers Visual Studio Code extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) provides a way for development teams to develop within a containerized environment where all dependencies are preconfigured. With Aspire 9.1, there's added logic to better support working with Aspire within a Dev Container environment by automatically configuring port forwarding. + +Before Aspire 9.1, it was possible to use Aspire within a Dev Container, however more manual configuration was required. + +## Dev Containers vs. GitHub Codespaces + +Using Dev Containers in Visual Studio Code is similar to using GitHub Codespaces. With the release of Aspire 9.1, support for both Dev Containers in Visual Studio Code and GitHub Codespaces was enhanced. Although the experiences are similar, there are some differences. For more information on using Aspire with GitHub Codespaces, see [Aspire and GitHub Codespaces](/get-started/github-codespaces/). + +## Quick start using template repository + +To configure Dev Containers in Visual Studio Code, use the `.devcontainer/devcontainer.json` file in your repository. The simplest way to get started is by creating a new repository from our [template repository](https://github.com/dotnet/aspire-devcontainer). Consider the following steps: + + + +1. [Create a new repository](https://github.com/new?template_name=aspire-devcontainer&template_owner=dotnet) using our template. + + Screenshot showing how to create a new repository from the Aspire devcontainer template on GitHub. + + Once you provide the details and select **Create repository**, the repository is created and shown in GitHub. + +1. Clone the repository to your local developer workstation using the following command: + + ```bash + git clone https://github.com/// + ``` + +1. Open the repository in Visual Studio Code. After a few moments Visual Studio Code detects the `.devcontainer/devcontainer.json` file and prompts to open the repository inside a container. Select whichever option is most appropriate for your workflow. + + Screenshot showing VS Code prompt to open the repository inside a container. + + After a few moments, the list of files become visible and the local build of the dev container will be completed. + + Screenshot showing the dev container build completed notification in VS Code. + +1. Open a new terminal window in Visual Studio Code () and create a new Aspire project using the Aspire CLI. + + ```bash + aspire new aspire-starter -n HelloAspire + ``` + + After a few moments, the project will be created and initial dependencies restored. + +1. Open the `HelloAspire.AppHost/AppHost.cs` file in the editor and select the run button on the top right corner of the editor window. + + Screenshot showing the run button in the VS Code editor toolbar. + + Visual Studio Code builds and starts the Aspire AppHost and automatically opens the Aspire Dashboard. Because the endpoints hosted in the container are using a self-signed certificate the first time, you access an endpoint for a specific Dev Container you're presented with a certificate error. + + Screenshot showing the browser certificate error when accessing the dashboard. + + The certificate error is expected. Once you've confirmed that the URL being requested corresponds to the dashboard in the Dev Container you can ignore this warning. + + Screenshot of the Aspire dashboard running successfully in the Dev Container. + + Aspire automatically configures forwarded ports so that when you select on the endpoints in the Aspire dashboard they're tunneled to processes and nested containers within the Dev Container. + +1. Commit changes to the GitHub repository. + + After successfully creating the Aspire project and verifying that it launches and you can access the dashboard, it's a good idea to commit the changes to the repository. + + + +## Manually configuring devcontainer.json + +The preceding walkthrough demonstrates the streamlined process of creating a Dev Container using the Aspire Dev Container template. If you already have an existing repository and wish to utilize Dev Container functionality with Aspire, add a `devcontainer.json` file to the `.devcontainer` folder within your repository: + + +- .devcontainer + - devcontainer.json + + +The [template repository](https://github.com/dotnet/aspire-devcontainer) contains a copy of the `devcontainer.json` file that you can use as a starting point, which should be sufficient for Aspire. + +## Dev Container scenarios + +The basic Aspire Dev Container template works well for simple scenarios, but you might need additional configuration depending on your specific requirements. The following sections provide examples for various common scenarios. + +### Stateless .NET apps only + +For simple Aspire projects that only use .NET project resources without external containers or complex orchestration, you can use a minimal Dev Container configuration: + +```json +{ + "name": "Aspire - Simple", + "image": "mcr.microsoft.com/devcontainers/dotnet:9.0-bookworm", + "onCreateCommand": "dotnet new install Aspire.ProjectTemplates --force", + "postStartCommand": "dotnet dev-certs https --trust", + "customizations": { + "vscode": { + "extensions": ["ms-dotnettools.csdevkit"] + } + } +} +``` + +This minimal configuration is suitable for Aspire apps that orchestrate only .NET services without external dependencies. + +### Adding Node.js resources + +If your Aspire app includes Node.js resources, add the Node.js feature to your Dev Container: + +```json +{ + "name": "Aspire with Node.js", + "image": "mcr.microsoft.com/devcontainers/dotnet:9.0-bookworm", + "features": { + "ghcr.io/devcontainers/features/node:1": { + "version": "lts" + } + }, + "onCreateCommand": "dotnet new install Aspire.ProjectTemplates --force", + "postStartCommand": "dotnet dev-certs https --trust", + "customizations": { + "vscode": { + "extensions": [ + "ms-dotnettools.csdevkit", + "ms-vscode.vscode-typescript-next" + ] + } + } +} +``` + +This configuration provides both .NET and Node.js development capabilities within the same container environment. + +### Container orchestration with Docker-in-Docker + +When your Aspire app orchestrates container resources, you need Docker-in-Docker (DinD) support. Here's a basic configuration: + +```json +{ + "name": "Aspire with Containers", + "image": "mcr.microsoft.com/devcontainers/dotnet:9.0-bookworm", + "features": { + "ghcr.io/devcontainers/features/docker-in-docker:2": { + "version": "latest", + "enableNonRootDocker": true, + "moby": true + } + }, + "hostRequirements": { + "cpus": 4, + "memory": "16gb", + "storage": "32gb" + }, + "onCreateCommand": "dotnet new install Aspire.ProjectTemplates --force", + "postStartCommand": "dotnet dev-certs https --trust", + "customizations": { + "vscode": { + "extensions": ["ms-dotnettools.csdevkit", "ms-azuretools.vscode-docker"] + } + } +} +``` + +#### Advanced container networking + +If you encounter networking issues between containers or need IPv6 support, you can add additional network configuration: + +```json +{ + "name": "Aspire with Advanced Networking", + "image": "mcr.microsoft.com/devcontainers/dotnet:9.0-bookworm", + "features": { + "ghcr.io/devcontainers/features/docker-in-docker:2": { + "version": "latest", + "enableNonRootDocker": true, + "moby": true + } + }, + "runArgs": [ + "--sysctl", + "net.ipv6.conf.all.disable_ipv6=0", + "--sysctl", + "net.ipv6.conf.default.forwarding=1", + "--sysctl", + "net.ipv6.conf.all.forwarding=1" + ], + "hostRequirements": { + "cpus": 8, + "memory": "32gb", + "storage": "64gb" + }, + "onCreateCommand": "dotnet new install Aspire.ProjectTemplates --force", + "postStartCommand": "dotnet dev-certs https --trust", + "customizations": { + "vscode": { + "extensions": ["ms-dotnettools.csdevkit", "ms-azuretools.vscode-docker"] + } + } +} +``` + +:::caution[Docker-in-Docker considerations] + +- Docker-in-Docker requires higher resource allocation including increased CPU, memory, and storage. +- The advanced networking configuration above includes IPv6 forwarding settings that may be needed for complex container-to-container communication scenarios. +- This configuration works with Docker Desktop but may have limitations with Rancher Desktop. +- Network connectivity between containers might require additional configuration depending on your specific use case. + ::: + +### Dapr integration examples + +For Aspire apps that integrate with Dapr, you can set up Dapr components in your Dev Container. For more information, see [Aspire Dapr integration](/integrations/frameworks/dapr/). + +#### Basic Dapr setup + +```json +{ + "name": "Aspire with Dapr", + "image": "mcr.microsoft.com/devcontainers/dotnet:9.0-bookworm", + "features": { + "ghcr.io/devcontainers/features/docker-in-docker:2": { + "enableNonRootDocker": true + }, + "ghcr.io/dapr/cli/dapr-cli:0": {} + }, + "onCreateCommand": "dotnet new install Aspire.ProjectTemplates --force", + "postCreateCommand": "dotnet dev-certs https --trust && dapr init", + "customizations": { + "vscode": { + "extensions": ["ms-dotnettools.csdevkit", "ms-azuretools.vscode-dapr"] + } + } +} +``` + +#### Dapr with external backends + +For more complex Dapr scenarios that use external backends (Redis, PostgreSQL), you can use Docker Compose: + +```json +{ + "name": "Aspire with Dapr and Backends", + "image": "mcr.microsoft.com/devcontainers/dotnet:9.0-bookworm", + "features": { + "ghcr.io/devcontainers/features/docker-in-docker:2": { + "enableNonRootDocker": true + }, + "ghcr.io/dapr/cli/dapr-cli:0": {} + }, + "runArgs": ["--sysctl", "net.ipv6.conf.all.disable_ipv6=0"], + "onCreateCommand": "dotnet new install Aspire.ProjectTemplates --force", + "postCreateCommand": [ + "dotnet dev-certs https --trust", + "docker compose up -d", + "dapr init" + ], + "customizations": { + "vscode": { + "extensions": [ + "ms-dotnettools.csdevkit", + "ms-azuretools.vscode-dapr", + "ms-azuretools.vscode-docker" + ] + } + } +} +``` + +## Common considerations + +When using Dev Containers with Aspire, keep the following considerations in mind: + +**Resource requirements** + +- **Basic .NET apps**: Standard Dev Container resources are sufficient for simple scenarios. +- **Container orchestration**: A minimum of 8 CPUs, 32GB memory, and 64GB storage is recommended. +- **Complex scenarios with Dapr/Kubernetes**: Higher resource allocation is recommended for optimal performance. + +**Networking** + +- IPv6 configuration may be required for container-to-container communication. +- Port forwarding is automatically handled by Aspire 9.1 and later versions. +- External service connectivity depends on your container runtime configuration. + +**Performance** + +- Docker-in-Docker scenarios incur performance overhead compared to native Docker. +- Consider using Docker outside of Docker (DooD) for production workflows. +- Local development and deployment scenarios may require different configurations. + +**Security** + +- Dev Containers run with elevated privileges when using Docker-in-Docker. +- SSL certificate trust is handled automatically in most scenarios. +- Consider security implications when exposing ports in cloud environments. diff --git a/src/frontend/src/content/docs/get-started/github-codespaces.mdx b/src/frontend/src/content/docs/get-started/github-codespaces.mdx new file mode 100644 index 00000000..f15317ff --- /dev/null +++ b/src/frontend/src/content/docs/get-started/github-codespaces.mdx @@ -0,0 +1,141 @@ +--- +title: Aspire and GitHub Codespaces +description: Learn how to use Aspire with GitHub Codespaces for cloud-based development. +--- + +import { Image } from 'astro:assets'; +import { FileTree, Steps } from '@astrojs/starlight/components'; +import newRepoFromTemplate from '@assets/get-started/new-repository-from-template.png'; +import createCodespace from '@assets/get-started/create-codespace-from-repository.png'; +import buildingCodespace from '@assets/get-started/building-codespace-image.png'; +import codespaceTerminal from '@assets/get-started/codespace-terminal.png'; +import codespacesExplorer from '@assets/get-started/codespaces-explorer-panel.png'; +import launchAppHost from '@assets/get-started/codespace-launch-apphost.png'; +import debugConsole from '@assets/get-started/codespaces-debug-console.png'; +import translatedUrls from '@assets/get-started/codespaces-translated-urls.png'; + +[GitHub Codespaces](https://github.com/features/codespaces) offers a cloud-hosted development environment based on Visual Studio Code. It can be accessed directly from a web browser or through Visual Studio Code locally, where Visual Studio Code acts as a client connecting to a cloud-hosted backend. With Aspire 9.1, comes logic to better support GitHub Codespaces including: + +- Automatically configure port forwarding with the correct protocol. +- Automatically translate URLs in the Aspire dashboard. + +Before Aspire 9.1 it was still possible to use Aspire within a GitHub Codespace, however more manual configuration was required. + +## GitHub Codespaces vs. Dev Containers + +GitHub Codespaces builds upon Visual Studio Code and the [Dev Containers specification](https://containers.dev/implementors/spec/). In addition to supporting GitHub Codespaces, Aspire 9.1 enhances support for using Visual Studio Code and locally hosted Dev Containers. While the experiences are similar, there are some differences. For more information, see [Aspire and Visual Studio Code Dev Containers](/get-started/dev-containers/). + +## Quick start using template repository + +To configure GitHub Codespaces for Aspire, use the `.devcontainer/devcontainer.json` file in your repository. The simplest way to get started is by creating a new repository from our [template repository](https://github.com/dotnet/aspire-devcontainer). Consider the following steps: + + + +1. [Create a new repository](https://github.com/new?template_name=aspire-devcontainer&template_owner=dotnet) using our template. + + Screenshot showing how to create a new repository from the Aspire devcontainer template on GitHub. + + Once you provide the details and select **Create repository**, the repository is created and shown in GitHub. + +1. From the new repository, select on the Code button and select the Codespaces tab and then select **Create codespace on main**. + + Screenshot showing how to create a new codespace from the repository on GitHub. + + After you select **Create codespace on main**, you navigate to a web-based version of Visual Studio Code. Before you use the Codespace, the containerized development environment needs to be prepared. This process happens automatically on the server and you can review progress by selecting the **Building codespace** link on the notification in the bottom right of the browser window. + + Screenshot showing the building codespace notification in VS Code. + + When the container image has finished being built the **Terminal** prompt appears which signals that the environment is ready to be interacted with. + + Screenshot showing the terminal prompt ready for use in the codespace. + + At this point, the Aspire templates have been installed and the ASP.NET Core developer certificate has been added and accepted. + +1. Create a new Aspire project using the starter template. + + ```bash + dotnet new aspire-starter --name HelloAspire + ``` + + This results in many files and folders being created in the repository, which are visible in the **Explorer** panel on the left side of the window. + + Screenshot of the VS Code Explorer panel showing the newly created Aspire project structure. + +1. Launch the AppHost via the `HelloAspire.AppHost/AppHost.cs` file, by selecting the **Run project** button near the top-right corner of the **Tab bar**. + + Screenshot showing how to launch the AppHost using the Run project button in VS Code. + + After a few moments the **Debug Console** panel is displayed, and it includes a link to the Aspire dashboard exposed on a GitHub Codespaces endpoint with the authentication token. + + Screenshot of the Debug Console showing the Aspire dashboard URL with authentication token. + +1. Open the Aspire dashboard by selecting the dashboard URL in the **Debug Console**. This opens the Aspire dashboard in a separate tab within your browser. + + You notice on the dashboard that all HTTP/HTTPS endpoints defined on resources have had their typical `localhost` address translated to a unique fully qualified subdomain on the `app.github.dev` domain. + + Screenshot of the Aspire dashboard showing translated URLs using GitHub Codespaces domains. + + Traffic to each of these endpoints is automatically forwarded to the underlying process or container running within the Codespace. This includes development time tools such as PgAdmin and Redis Insight. + + :::note + In addition to the authentication token embedded within the URL of the dashboard link of the **Debug Console**, endpoints also require authentication via your GitHub identity to avoid port forwarded endpoints being accessible to everyone. For more information on port forwarding in GitHub Codespaces, see [Forwarding ports in your codespace](https://docs.github.com/codespaces/developing-in-a-codespace/forwarding-ports-in-your-codespace?tool=webui). + ::: + +1. Commit changes to the GitHub repository. + + GitHub Codespaces doesn't automatically commit your changes to the branch you're working on in GitHub. You have to use the **Source Control** panel to stage and commit the changes and push them back to the repository. + + Working in a GitHub Codespace is similar to working with Visual Studio Code on your own machine. You can checkout different branches and push changes just like you normally would. In addition, you can easily spin up multiple Codespaces simultaneously if you want to quickly work on another branch without disrupting your existing debug session. For more information, see [Developing in a codespace](https://docs.github.com/codespaces/developing-in-a-codespace/developing-in-a-codespace?tool=webui). + +1. Clean up your Codespace. + + GitHub Codespaces are temporary development environments and while you might use one for an extended period of time, they should be considered a disposable resource that you recreate as needed (with all of the customization/setup contained within the `devcontainer.json` and associated configuration files). + + To delete your GitHub Codespace, visit the GitHub Codespaces page. This shows you a list of all of your Codespaces. From here you can perform management operations on each Codespace, including deleting them. + + GitHub charges for the use of Codespaces. For more information, see [Managing the cost of GitHub Codespaces in your organization](https://docs.github.com/codespaces/managing-codespaces-for-your-organization/choosing-who-owns-and-pays-for-codespaces-in-your-organization). + + :::note + Aspire supports the use of Dev Containers in Visual Studio Code independent of GitHub Codespaces. For more information on how to use Dev Containers locally, see [Aspire and Dev Containers in Visual Studio Code](/get-started/dev-containers/). + ::: + + + +## Manually configuring devcontainer.json + +The preceding walkthrough demonstrates the streamlined process of creating a GitHub Codespace using the Aspire Devcontainer template. If you already have an existing repository and wish to utilize Devcontainer functionality with Aspire, add a `devcontainer.json` file to the `.devcontainer` folder within your repository: + + +- .devcontainer + - devcontainer.json + + +The [template repository](https://github.com/dotnet/aspire-devcontainer) contains a copy of the `devcontainer.json` file that you can use as a starting point, which should be sufficient for Aspire. + +## Speed up Codespace creation + +Creating a GitHub Codespace can take some time as it prepares the underlying container image. To expedite this process, you can utilize _prebuilds_ to significantly reduce the creation time to approximately 30-60 seconds (exact timing might vary). For more information on GitHub Codespaces prebuilds, see [GitHub Codespaces prebuilds](https://docs.github.com/codespaces/prebuilding-your-codespaces/about-github-codespaces-prebuilds). diff --git a/src/frontend/src/content/docs/get-started/install-cli.mdx b/src/frontend/src/content/docs/get-started/install-cli.mdx index dd1a8445..087bf00f 100644 --- a/src/frontend/src/content/docs/get-started/install-cli.mdx +++ b/src/frontend/src/content/docs/get-started/install-cli.mdx @@ -5,7 +5,7 @@ lastUpdated: true tableOfContents: true --- -import AsciinemaPlayer from "@components/AsciinemaPlayer.astro"; +import AsciinemaPlayer from '@components/AsciinemaPlayer.astro'; import InstallAspireCLI from '@components/InstallAspireCLI.astro'; import LearnMore from '@components/LearnMore.astro'; import OsAwareTabs from '@components/OsAwareTabs.astro'; @@ -14,7 +14,8 @@ import { Aside, Code, Steps } from '@astrojs/starlight/components'; Aspire provides a command-line interface (CLI) tool to help you create and manage Aspire-based apps. The CLI streamlines your development workflow with an interactive-first experience. This guide shows you how to install the Aspire CLI on your system. The Aspire CLI requires the [.NET 10.0 SDK](https://dotnet.microsoft.com/download/dotnet/10.0). -Before installing the Aspire CLI, ensure you have the [required prerequisites](/get-started/prerequisites/) set up. + Before installing the Aspire CLI, ensure you have the [required + prerequisites](/get-started/prerequisites/) set up. ## Install the Aspire CLI @@ -25,19 +26,20 @@ To install the Aspire CLI download and run the install script: You can download and run the installation script in a single command to install the Aspire CLI: - - + + The script installs the latest stable release of Aspire CLI. See [Validation](#validation) to verify the installation. + ### Two-step installation process @@ -46,47 +48,51 @@ Alternatively, you can download the script and run it as a two-step process: -01. Open a terminal. -01. Download the script and save it as a file: +1. Open a terminal. +1. Download the script and save it as a file: - - + + -01. Run the script to install the stable release build of Aspire. +1. Run the script to install the stable release build of Aspire. You should see output similar to the following snippet: -
- ```txt title="Output" frame="terminal" - Downloading from: https://aka.ms/dotnet/9/aspire/ga/daily/aspire-cli-linux-x64.tar.gz - Aspire CLI successfully installed to: /home/username/.aspire/bin/aspire - Added /home/username/.aspire/bin to PATH for current session - Added /home/username/.aspire/bin to PATH in /home/username/.bashrc - - The aspire cli is now available for use in this and new sessions. - ``` -
-
- ```txt title="Output" frame="terminal" - Downloading from: https://aka.ms/dotnet/9/aspire/ga/daily/aspire-cli-win-x64.zip - Aspire CLI successfully installed to: C:\Users\name\.aspire\bin\aspire.exe - Added C:\Users\username\.aspire\bin to PATH for current session - Added C:\Users\username\.aspire\bin to user PATH environment variable - - The aspire cli is now available for use in this and new sessions. - ``` -
+
+ + ```txt title="Output" frame="terminal" data-disable-copy + Downloading from: + https://aka.ms/dotnet/9/aspire/ga/daily/aspire-cli-linux-x64.tar.gz + Aspire CLI successfully installed to: /home/username/.aspire/bin/aspire + Added /home/username/.aspire/bin to PATH for current session Added + /home/username/.aspire/bin to PATH in /home/username/.bashrc The aspire + cli is now available for use in this and new sessions. + ``` + +
+
+ + ```txt title="Output" frame="terminal" data-disable-copy + Downloading from: https://aka.ms/dotnet/9/aspire/ga/daily/aspire-cli-win-x64.zip + Aspire CLI successfully installed to: + C:\Users\name\.aspire\bin\aspire.exe Added C:\Users\username\.aspire\bin + to PATH for current session Added C:\Users\username\.aspire\bin to user + PATH environment variable The aspire cli is now available for use in + this and new sessions. + ``` + +
@@ -102,26 +108,30 @@ aspire --version Consider the following example of running the command: If that command works, you're presented with the version of the Aspire CLI tool: -```bash title="Aspire CLI — Output" +```bash title="Aspire CLI — Output" data-disable-copy 13.0.0+{commitSHA} ``` The `+{commitSHA}` suffix indicates the specific commit from which the Aspire CLI was built. This suffix is included in pre-release builds and may not be present in stable releases. -Learn more by reading the [Aspire CLI reference](/reference/cli/overview/) documentation. + Learn more by reading the [Aspire CLI reference](/reference/cli/overview/) + documentation. - diff --git a/src/frontend/src/styles/site.css b/src/frontend/src/styles/site.css index 84017f20..94a25cae 100644 --- a/src/frontend/src/styles/site.css +++ b/src/frontend/src/styles/site.css @@ -944,7 +944,9 @@ a.clickable-card article:hover { } table td code, -table th code { +table th code, +table td a, +sl-sidebar-state-persist a { white-space: nowrap; } @@ -953,6 +955,7 @@ table th { vertical-align: top; } -table td a { - white-space: nowrap; -} +* { + scrollbar-width: thin; + scrollbar-color: var(--aspire-color-secondary) var(--sl-color-bg-nav); +} \ No newline at end of file