Merge pull request #3 from dotnet/main

Push to live

.openpublishing.publish.config.json

@@ -2,7 +2,7 @@
   "docsets_to_publish": [
     {
       "docset_name": "dotnet-aspire-docs",
-      "build_source_folder": "docs-aspire",
+      "build_source_folder": "docs",
       "build_output_subfolder": "dotnet-aspire-docs",
       "locale": "en-us",
       "monikers": [],

README.md

@@ -1,3 +1,17 @@
+# .NET Aspire docs
+
+This repository contains the conceptual documentation for .NET Aspire. The [.NET Aspire documentation site](https://learn.microsoft.com/dotnet/aspire).
+
+## :purple_heart: Contribute
+
+We welcome contributions to help us improve and complete the .NET docs. This is a very large repo, covering a large area. If this is your first visit, see our [labels and projects roadmap](https://learn.microsoft.com/contribute/content/dotnet/labels-projects) for help navigating the issues and projects in this repository. If your contribution includes third-party dependencies, see our guidance on using [third-party dependencies :link:](https://github.com/dotnet/docs/blob/main/styleguide/3rdPartyDependencies.md).
+
+To contribute, see:
+
+- The [.NET Contributor Guide :ledger:](https://learn.microsoft.com/contribute/dotnet/dotnet-contribute) for instructions on procedures we use.
+- Issues labeled [`help wanted` :label:](https://github.com/dotnet/docs-aspire/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22+) for ideas.
+- [#Hacktoberfest and Microsoft Docs :jack_o_lantern:](https://learn.microsoft.com/contribute/hacktoberfest) for details on our participation in the annual event.
+
 ## Microsoft Open Source Code of Conduct
-This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
-For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [[email protected]](mailto:[email protected]) with any additional questions or comments.
+
+This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [[email protected]](mailto:[email protected]) with any additional questions or comments.

docs-aspire.sln

@@ -0,0 +1,79 @@
+
+Microsoft Visual Studio Solution File, Format Version 12.00
+# Visual Studio Version 17
+VisualStudioVersion = 17.5.002.0
+MinimumVisualStudioVersion = 10.0.40219.1
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "docs-aspire", "docs-aspire", "{AE9A30E3-518E-4DEF-8423-0ACB32A24449}"
+EndProject
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "docs", "docs", "{912F6F6C-1477-440F-94D3-B0A0430D6019}"
+EndProject
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "snippets", "snippets", "{FC3A43C6-9BC2-4C30-8D7A-821D4C56981E}"
+EndProject
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "template", "template", "{1436F2AE-B9B8-4D92-9CFF-4AC4C7409F9B}"
+EndProject
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "YourAppName.ServiceDefaults", "docs-aspire\docs\snippets\template\YourAppName\YourAppName.ServiceDefaults.csproj", "{6C6010A8-3CE1-4F68-AB00-9A601FF54E45}"
+EndProject
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "get-started", "get-started", "{545520F8-51D0-4196-B908-363169FC95A6}"
+EndProject
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "snippets", "snippets", "{17677120-8D22-4EB6-8BD6-AD984B4B9B52}"
+EndProject
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "quickstart", "quickstart", "{B1C729EB-9086-41D6-8C01-DE359CE13C2E}"
+EndProject
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "AspireSample", "AspireSample", "{0EBF4E97-EA69-44D3-B4C7-A54914E60EC8}"
+EndProject
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "AspireSample.ApiService", "docs-aspire\docs\get-started\snippets\quickstart\AspireSample\AspireSample.ApiService\AspireSample.ApiService.csproj", "{41DA518C-5374-42FC-B2BD-37D777D7E74F}"
+EndProject
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "AspireSample.AppHost", "docs-aspire\docs\get-started\snippets\quickstart\AspireSample\AspireSample.AppHost\AspireSample.AppHost.csproj", "{CC5399E0-F64B-4E51-88F8-8C3CFC4E2D40}"
+EndProject
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "AspireSample.ServiceDefaults", "docs-aspire\docs\get-started\snippets\quickstart\AspireSample\AspireSample.ServiceDefaults\AspireSample.ServiceDefaults.csproj", "{227A0A1A-705F-4432-83C4-3DE1FBD3D460}"
+EndProject
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "AspireSample.Web", "docs-aspire\docs\get-started\snippets\quickstart\AspireSample\AspireSample.Web\AspireSample.Web.csproj", "{815DECB1-1B19-4008-A75B-AA670CBA0A3C}"
+EndProject
+Global
+	GlobalSection(SolutionConfigurationPlatforms) = preSolution
+		Debug|Any CPU = Debug|Any CPU
+		Release|Any CPU = Release|Any CPU
+	EndGlobalSection
+	GlobalSection(ProjectConfigurationPlatforms) = postSolution
+		{6C6010A8-3CE1-4F68-AB00-9A601FF54E45}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{6C6010A8-3CE1-4F68-AB00-9A601FF54E45}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{6C6010A8-3CE1-4F68-AB00-9A601FF54E45}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{6C6010A8-3CE1-4F68-AB00-9A601FF54E45}.Release|Any CPU.Build.0 = Release|Any CPU
+		{41DA518C-5374-42FC-B2BD-37D777D7E74F}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{41DA518C-5374-42FC-B2BD-37D777D7E74F}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{41DA518C-5374-42FC-B2BD-37D777D7E74F}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{41DA518C-5374-42FC-B2BD-37D777D7E74F}.Release|Any CPU.Build.0 = Release|Any CPU
+		{CC5399E0-F64B-4E51-88F8-8C3CFC4E2D40}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{CC5399E0-F64B-4E51-88F8-8C3CFC4E2D40}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{CC5399E0-F64B-4E51-88F8-8C3CFC4E2D40}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{CC5399E0-F64B-4E51-88F8-8C3CFC4E2D40}.Release|Any CPU.Build.0 = Release|Any CPU
+		{227A0A1A-705F-4432-83C4-3DE1FBD3D460}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{227A0A1A-705F-4432-83C4-3DE1FBD3D460}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{227A0A1A-705F-4432-83C4-3DE1FBD3D460}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{227A0A1A-705F-4432-83C4-3DE1FBD3D460}.Release|Any CPU.Build.0 = Release|Any CPU
+		{815DECB1-1B19-4008-A75B-AA670CBA0A3C}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{815DECB1-1B19-4008-A75B-AA670CBA0A3C}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{815DECB1-1B19-4008-A75B-AA670CBA0A3C}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{815DECB1-1B19-4008-A75B-AA670CBA0A3C}.Release|Any CPU.Build.0 = Release|Any CPU
+	EndGlobalSection
+	GlobalSection(SolutionProperties) = preSolution
+		HideSolutionNode = FALSE
+	EndGlobalSection
+	GlobalSection(NestedProjects) = preSolution
+		{912F6F6C-1477-440F-94D3-B0A0430D6019} = {AE9A30E3-518E-4DEF-8423-0ACB32A24449}
+		{FC3A43C6-9BC2-4C30-8D7A-821D4C56981E} = {912F6F6C-1477-440F-94D3-B0A0430D6019}
+		{1436F2AE-B9B8-4D92-9CFF-4AC4C7409F9B} = {FC3A43C6-9BC2-4C30-8D7A-821D4C56981E}
+		{6C6010A8-3CE1-4F68-AB00-9A601FF54E45} = {1436F2AE-B9B8-4D92-9CFF-4AC4C7409F9B}
+		{545520F8-51D0-4196-B908-363169FC95A6} = {912F6F6C-1477-440F-94D3-B0A0430D6019}
+		{17677120-8D22-4EB6-8BD6-AD984B4B9B52} = {545520F8-51D0-4196-B908-363169FC95A6}
+		{B1C729EB-9086-41D6-8C01-DE359CE13C2E} = {17677120-8D22-4EB6-8BD6-AD984B4B9B52}
+		{0EBF4E97-EA69-44D3-B4C7-A54914E60EC8} = {B1C729EB-9086-41D6-8C01-DE359CE13C2E}
+		{41DA518C-5374-42FC-B2BD-37D777D7E74F} = {0EBF4E97-EA69-44D3-B4C7-A54914E60EC8}
+		{CC5399E0-F64B-4E51-88F8-8C3CFC4E2D40} = {0EBF4E97-EA69-44D3-B4C7-A54914E60EC8}
+		{227A0A1A-705F-4432-83C4-3DE1FBD3D460} = {0EBF4E97-EA69-44D3-B4C7-A54914E60EC8}
+		{815DECB1-1B19-4008-A75B-AA670CBA0A3C} = {0EBF4E97-EA69-44D3-B4C7-A54914E60EC8}
+	EndGlobalSection
+	GlobalSection(ExtensibilityGlobals) = postSolution
+		SolutionGuid = {CEB52216-522A-43F1-927F-49316D53B6CB}
+	EndGlobalSection
+EndGlobal

docs/app-host-overview.md

@@ -0,0 +1,155 @@
+---
+title: .NET Aspire orchestration overview
+description: Learn the fundamental concepts of .NET Aspire orchestration.
+ms.date: 11/11/2023
+ms.topic: overview
+ms.prod: dotnet
+---
+
+# .NET Aspire orchestration overview
+
+.NET Aspire provides APIs for expressing resources and dependencies within your distributed application.
+
+Before continuing, consider some common terminology used in .NET Aspire:
+
+- **App model**: A collection of resources that make up your distributed application (`DistributedApplication`). For a more formal definition, see [App model](#app-model).
+- **App host/Orchestrator project**: The .NET project that orchestrates the _app model_, named with the _*.AppHost_ suffix (by convention).
+- **Resource**: A [resource](#built-in-resource-types) is a dependent part of your distributed application, such as a project, container, or an executable—all.
+- **Reference**: A reference defines a connection between resources. For more information, see [Reference a resource](#reference-a-resource).
+
+## App model
+
+.NET Aspire empowers you to seamlessly build, provision, deploy, configure, test, run, and observe your cloud application. This is achieved through the utilization of an application model (app model) that outlines the resources in your app and their relationships. These resources encompass projects, executables, containers, as well as external services and cloud resources that your app depends on. Within every .NET Aspire app, there is a designated [AppHost project](#orchestration-project), where the app model is precisely defined using methods available on the `IDistributedApplicationBuilder`. This builder is obtained by invoking `DistributedApplication.CreateBuilder(args)`.
+
+## Orchestration project
+
+The app host project handles running all of the projects that are part of the .NET Aspire application. The following code describes an application with two projects and a redis cache:
+
+```csharp
+var builder = DistributedApplication.CreateBuilder(args);
+
+var cache = builder.AddRedisContainer("cache");
+
+var apiservice = builder.AddProject<Projects.AspireApp_ApiService>("apiservice");
+
+builder.AddProject<Projects.AspireApp_Web>("webfrontend")
+    .WithReference(cache)
+    .WithReference(apiservice);
+
+builder.Build().Run();
+```
+
+The help visualize the relationship between the app host project and the other projects, consider the following diagram:
+
+:::image type="content" source="media/app-host-resource-diagram.png" lightbox="media/app-host-resource-diagram.png" alt-text="The relationship between the projects in the .NET Aspire Starter Application template.":::
+
+Each resource must be uniquely named. This diagram shows each resource and the relationships between them. The container resource is named "cache" and the project resources are named "apiservice" and "webfrontend". The web frontend project references the cache and API service projects.
+
+## Built-in resource types
+
+.NET Aspire apps are made up of a set of resources. There are three base types of compute resources:
+
+| Method | Resource type | Description |
+|--|--|--|
+| `AddProject` | `ProjectResource` | A .NET project, for example ASP.NET Core web apps. |
+| `AddContainer` | `ContainerResource` | A container image, such as a Docker image. |
+| `AddExecutable` | `ExecutableResource` | An executable file. |
+
+Project resources are .NET projects that are part of the app model. When you add a project reference to the app host project, the app host generates a type in the `Projects` namespace for each referenced project.
+
+To add a project to the app model, use the `AddProject` method:
+
+```csharp
+// Adds the project "apiservice" of type "Projects.AspireApp_ApiService".
+var apiservice = builder.AddProject<Projects.AspireApp_ApiService>("apiservice");
+```
+
+## Reference resources
+
+A reference represents a dependency between resources. Consider the following:
+
+```csharp
+var cache = builder.AddRedisContainer("cache");
+
+builder.AddProject<Projects.AspireApp_Web>("webfrontend")
+    .WithReference(cache);
+```
+
+The "webfrontend" project resource uses `WithReference` to add a dependency on the "cache" container resource. These dependencies can represent connection strings or service discovery information. In the preceding example, an environment variable is injected into the "webfronend" resource with the name `ConnectionStrings__cache`. This enviroment variable contains
+a connection string that the webfrontend can use to connect to redis via the .NET Aspire Redis component, for example, `ConnectionStrings__cache="localhost:6379"`.
+
+### Connection string and endpoint references
+
+It's also possible to have dependencies between project resources. Consider the following example code:
+
+```csharp
+var cache = builder.AddRedisContainer("cache");
+
+var apiservice = builder.AddProject<Projects.AspireApp_ApiService>("apiservice");
+
+builder.AddProject<Projects.AspireApp_Web>("webfrontend")
+    .WithReference(cache)
+    .WithReference(apiservice);
+```
+
+Project-to-project references are handled differently than resources that have well defined connection strings. Instead of connection string being injected into the "webfrontend" resource, environment variables to support service discovery are injected.
+
+| Method | Environment variable |
+|--|--|
+| `WithReference(cache)` | `ConnectionStrings__cache="localhost:6379"` |
+| `WithReference(apiservice)` | `services__apiservice__0="http://_http.localhost:8034"`<br />`services__apiservice__1="http://localhost:8034"` |
+
+Adding a reference to the "apiservice" project results in service discovery environment variables being added to the front-end. This is because typically, project to project communication occurs over HTTP/gRPC. For more information, see [.NET Aspire service discovery](service-discovery/overview.md).
+
+It's possible to get specific endpoints from a container or executable using the `GetEndpoint` method:
+
+```csharp
+var customContainer = builder.AddContainer("myapp", "mycustomcontainer")
+                             .WithServiceBinding(containerPort: 9043, name: "endpoint");
+
+var endpoint = customContainer.GetEndpoint("endpoint");
+
+var apiservice = builder.AddProject<Projects.AspireApp_ApiService>("apiservice")
+                        .WithReference(endpoint);
+```
+
+| Method | Environment variable |
+|--|--|
+| `WithReference(endpoint)` | `services__myapp__0=http://_http.localhost:8034` |
+
+### APIs to add resources
+
+Beyond the base resource types, `ProjectResource`, `ContainerResource`, and `ExecutableResource`, .NET Aspire provides extension methods to add common resources to your app model. The following table lists the methods and their corresponding resource types:
+
+**Cloud agnostic resources available in the [Aspire.Hosting](https://www.nuget.org/packages/Aspire.Hosting) NuGet package (available by default in .NET Aspire templates):**
+
+| Method | Resource type | Description |
+|--|--|--|
+| `AddPostgresConnection` | `PostgresConnectionResource` | Adds a Postgres connection resource. |
+| `AddPostgresContainer` | `PostgresContainerResource` | Adds a Postgres container resource. |
+| `AddPostgresContainer(...).AddDatabase` | `PostgresDatabaseResource` | Adds a Postgres database resource. |
+| `AddRabbitMQConnection` | `RabbitMQConnectionResource` | Adds a RabbitMQ connection resource. |
+| `AddRabbitMQContainer` | `RabbitMQContainerResource` | Adds a RabbitMQ container resource. |
+| `AddRedisContainer` | `RedisContainerResource` | Adds a Redis container resource. |
+| `AddSqlServerConnection` | `SqlServerConnectionResource` | Adds a SQL Server connection resource. |
+| `AddSqlServerContainer` | `SqlServerContainerResource` | Adds a SQL Server container resource. |
+| `AddSqlServerContainer(...).AddDatabase` | `SqlServerDatabaseResource` | Adds a SQL Server database resource. |
+
+**Azure specific resources available in the [Aspire.Hosting.Azure](https://www.nuget.org/packages/Aspire.Hosting.Azure) NuGet package:**
+
+| Method | Resource type | Description |
+|--|--|--|
+| `AddAzureStorage` | `AzureStorageResource` | Adds an Azure Storage resource. |
+| `AddAzureStorage(...).AddBlobs` | `AzureBlobStorageResource` | Adds an Azure Blob Storage resource. |
+| `AddAzureStorage(...).AddQueues` | `AzureQueueStorageResource` | Adds an Azure Queue Storage resource. |
+| `AddAzureStorage(...).AddTables` | `AzureTableStorageResource` | Adds an Azure Table Storage resource. |
+| `AddAzureCosmosDB` | `AzureCosmosDBResource` | Adds an Azure Cosmos DB resource. |
+| `AddAzureKeyVault` | `AzureKeyVaultResource` | Adds an Azure Key Vault resource. |
+| `AddAzureRedisResource` | `AzureRedisResource` | Adds an Azure Redis resource. |
+| `AddAzureServiceBus` | `AzureServiceBusResource` | Adds an Azure Service Bus resource. |
+
+## See also
+
+- [.NET Aspire components overview](components-overview.md)
+- [Service discovery in .NET Aspire](service-discovery/overview.md)
+- [.NET Aspire service defaults](service-defaults.md)

docs/breadcrumb/toc.yml

@@ -0,0 +1,12 @@
+items:
+  - name: Learn
+    tocHref: /
+    topicHref: /
+    items:
+      - name: .NET
+        tocHref: /dotnet/
+        topicHref: /dotnet/index
+        items:
+          - name: .NET Aspire
+            tocHref: /dotnet/aspire/
+            topicHref: /dotnet/aspire/index