Inner loop networking article (#279)

* Draft bits for networking

* More updates to the networking content

* Update hub and toc

* Update diagrams

* More updates and clean up

* More fixes

* More updates

* Smaller images

* Apply suggestions from code review

Co-authored-by: Genevieve Warren <[email protected]>

* Add proxy endpoint details for WithRef API.

---------

Co-authored-by: Genevieve Warren <[email protected]>

docs/fundamentals/networking-overview.md

@@ -0,0 +1,144 @@
+---
+title: .NET Aspire inner loop networking overview
+description: Learn how .NET Aspire handles networking and service bindings, and how you can use them in your app code.
+ms.date: 01/12/2024
+ms.topic: overview
+---
+
+# .NET Aspire inner-loop networking overview
+
+One of the advantages of developing with .NET Aspire is that it enables you to develop, test, and debug cloud-native apps locally. Inner-loop networking is a key aspect of .NET Aspire that allows your apps to communicate with each other in your development environment. In this article, you learn how .NET Aspire handles various networking scenarios with proxies, service bindings, endpoint configurations, and launch profiles.
+
+## Networking in the inner loop
+
+The inner loop is the process of developing and testing your app locally before deploying it to a target environment. .NET Aspire provides several tools and features to simplify and enhance the networking experience in the inner loop, such as:
+
+- **Launch profiles**: Launch profiles are configuration files that specify how to run your app locally. You can use launch profiles (such as the _launchSettings.json_ file) to define the service bindings, environment variables, and launch settings for your app.
+- **Service bindings/Endpoint configurations**: Service bindings are the connections between your app and the services it depends on, such as databases, message queues, or APIs. Service bindings provide information such as the service name, host port, scheme, and environment variable. You can add service bindings to your app either implicitly (via launch profiles) or explicitly by calling <xref:Aspire.Hosting.ResourceBuilderExtensions.WithServiceBinding%2A>.
+- **Proxies**: .NET Aspire automatically launches a proxy for each service binding you add to your app, and assigns a port for the proxy to listen on. The proxy then forwards the requests to the port that your app listens on, which might be different from the proxy port. This way, you can avoid port conflicts and access your app and services using consistent and predictable URLs.
+
+## How service bindings work
+
+A service binding in .NET Aspire involves two components: a **service** representing an external resource your app requires (for example, a database, message queue, or API), and a **binding** that establishes a connection between your app and the service and provides necessary information.
+
+.NET Aspire supports two service binding types: **implicit**, automatically created based on specified launch profiles defining app behavior in different environments, and **explicit**, manually created using <xref:Aspire.Hosting.ResourceBuilderExtensions.WithServiceBinding%2A>.
+
+Upon creating a binding, whether implicit or explicit, .NET Aspire launches a lightweight reverse proxy on a specified port, handling routing and load balancing for requests from your app to the service. The proxy is a .NET Aspire implementation detail, requiring no configuration or management concern.
+
+To help visualize how service bindings work, consider the .NET Aspire starter templates inner-loop networking diagram:
+
+:::image type="content" source="media/networking/networking-proxies-1x.png" lightbox="media/networking/networking-proxies.png" alt-text=".NET Aspire Starter Application template inner loop networking diagram.":::
+
+## Launch profiles
+
+When you call <xref:Aspire.Hosting.ProjectResourceBuilderExtensions.AddProject%2A>, the app host looks for _Properties/launchSettings.json_ to determine the default set of service bindings. The app host selects a specific launch profile using the following rules:
+
+1. An explicit <xref:Aspire.Hosting.ProjectResourceBuilderExtensions.WithLaunchProfile%2A> call on the `IResourceBuilder<ProjectResource>`.
+1. The `DOTNET_LAUNCH_PROFILE` environment variable. For more information, see [.NET environment variables](/dotnet/core/tools/dotnet-environment-variables).
+1. The first launch profile defined in _launchSettings.json_.
+
+Consider the following _launchSettings.json_ file:
+
+:::code language="json" source="snippets/networking/Networking.Frontend/Networking.Frontend/Properties/launchSettings.json":::
+
+For the remainder of this article, imagine that you've created an <xref:Aspire.Hosting.IDistributedApplicationBuilder> assigned to a variable named `builder` with the <xref:Aspire.Hosting.DistributedApplication.CreateBuilder> API:
+
+```csharp
+var builder = DistributedApplication.CreateBuilder(args);
+```
+
+To specify that the **https** launch profile should be used, call <xref:Aspire.Hosting.ProjectResourceBuilderExtensions.WithLaunchProfile%2A>:
+
+:::code source="snippets/networking/Networking.AppHost/Program.WithLaunchProfile.cs" id="withlaunchprofile":::
+
+This will select the **https** launch profile from _launchSettings.json_. The `applicationUrl` of that launch profile is used to create a service binding for this project. This is the equivalent of:
+
+:::code source="snippets/networking/Networking.AppHost/Program.WithLaunchProfile.cs" id="verbose":::
+
+> [!IMPORTANT]
+> If there's no _launchSettings.json_ (or launch profile), there are no bindings by default.
+
+## Ports and proxies
+
+When defining a service binding, the host port is *always* given to the proxy that sits in front of the service. This allows single or multiple replicas of a service to behave similarly. Additionally, all resource dependencies that use the <xref:Aspire.Hosting.ResourceBuilderExtensions.WithReference%2A> API rely of the proxy endpoint from the environment variable.
+
+Consider the following method chain that calls <xref:Aspire.Hosting.ProjectResourceBuilderExtensions.AddProject%2A>, <xref:Aspire.Hosting.ResourceBuilderExtensions.WithServiceBinding%2A>, and then <xref:Aspire.Hosting.ProjectResourceBuilderExtensions.WithReplicas%2A>:
+
+:::code source="snippets/networking/Networking.AppHost/Program.WithReplicas.cs" id="withreplicas":::
+
+The preceding code results in the following networking diagram:
+
+:::image type="content" source="media/networking/proxy-with-replicas-1x.png" lightbox="media/networking/proxy-with-replicas.png" alt-text=".NET Aspire frontend app networking diagram with specific host port and two replicas.":::
+
+The preceding diagram depicts the following:
+
+- A web browser as an entry point to the app.
+- A host port of 5066.
+- The frontend proxy sitting between the web browser and the frontend service replicas, listening on port 5066.
+- The `frontend_0` frontend service replica listening on the randomly assigned port 65001.
+- The `frontend_1` frontend service replica listening on the randomly assigned port 65002.
+
+Without the call to `WithReplicas`, there's only one frontend service. The proxy still listens on port 5066, but the frontend service listens on a random port:
+
+:::code source="snippets/networking/Networking.AppHost/Program.HostPortAndRandomPort.cs" id="hostport":::
+
+There are two ports defined:
+
+- A host port of 5066.
+- A random proxy port that the underlying service will be bound to.
+
+:::image type="content" source="media/networking/proxy-host-port-and-random-port-1x.png" lightbox="media/networking/proxy-host-port-and-random-port.png" alt-text=".NET Aspire frontend app networking diagram with specific host port and random port.":::
+
+The preceding diagram depicts the following:
+
+- A web browser as an entry point to the app.
+- A host port of 5066.
+- The frontend proxy sitting between the web browser and the frontend service, listening on port 5066.
+- The frontend service listening on random port of 65001.
+
+The underlying service is fed this port via `ASPNETCORE_URLS` for project resources. Other resources access to this port by specifying an environment variable on the service binding:
+
+:::code source="snippets/networking/Networking.AppHost/Program.EnvVarPort.cs" id="envvarport":::
+
+The previous code makes the random port available in the `PORT` environment variable. The app uses this port to listen to incoming connections from the proxy. Consider the following diagram:
+
+:::image type="content" source="media/networking/proxy-with-env-var-port-1x.png" lightbox="media/networking/proxy-with-env-var-port.png" alt-text=".NET Aspire frontend app networking diagram with specific host port and environment variable port.":::
+
+The preceding diagram depicts the following:
+
+- A web browser as an entry point to the app.
+- A host port of 5607.
+- The frontend proxy sitting between the web browser and the frontend service, listening on port 5607.
+- The frontend service listening on an environment 65001.
+
+## Omit the host port
+
+When you omit the host port, .NET Aspire generates a random port for both host and service port. This is useful when you want to avoid port conflicts and don't care about the host or service port. Consider the following code:
+
+:::code source="snippets/networking/Networking.AppHost/Program.OmitHostPort.cs" id="omithostport":::
+
+In this scenario, both the host and service ports are random, as shown in the following diagram:
+
+:::image type="content" source="media/networking/proxy-with-random-ports-1x.png" lightbox="media/networking/proxy-with-random-ports.png" alt-text=".NET Aspire frontend app networking diagram with random host port and proxy port.":::
+
+The preceding diagram depicts the following:
+
+- A web browser as an entry point to the app.
+- A random host port of 65000.
+- The frontend proxy sitting between the web browser and the frontend service, listening on port 65000.
+- The frontend service listening on a random port of 65001.
+
+## Container ports
+
+When you add a container resource, .NET Aspire automatically assigns a random port to the container. To specify a container port, configure the container resource with the desired port:
+
+:::code source="snippets/networking/Networking.AppHost/Program.ContainerPort.cs" id="containerport":::
+
+The preceding code:
+
+- Creates a container resource named `frontend`, from the `mcr.microsoft.com/dotnet/samples:aspnetapp` image.
+- Binds the host to port 8000 and the container port to 8080 with the `http` scheme.
+
+Consider the following diagram:
+
+:::image type="content" source="media/networking/proxy-with-docker-port-mapping-1x.png" alt-text=".NET Aspire frontend app networking diagram with a docker host.":::

docs/fundamentals/snippets/networking/Networking.AppHost/Networking.AppHost.csproj

@@ -0,0 +1,19 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net8.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <IsAspireHost>true</IsAspireHost>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Aspire.Hosting" Version="8.0.0-preview.2.23619.3" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\Networking.Frontend\Networking.Frontend\Networking.Frontend.csproj" />
+  </ItemGroup>
+
+</Project>

docs/fundamentals/snippets/networking/Networking.AppHost/Program.ContainerPort.cs

@@ -0,0 +1,10 @@
+public static partial class Program
+{
+    public static void ContainerPort(IDistributedApplicationBuilder builder)
+    {
+        // <containerport>
+        builder.AddContainer("frontend", "mcr.microsoft.com/dotnet/samples", "aspnetapp")
+               .WithServiceBinding(hostPort: 8000, containerPort: 8080, scheme: "http");
+        // </containerport>
+    }
+}

docs/fundamentals/snippets/networking/Networking.AppHost/Program.EnvVarPort.cs

@@ -0,0 +1,10 @@
+public static partial class Program
+{
+    public static void EnvVarPort(IDistributedApplicationBuilder builder)
+    {
+        // <envvarport>
+        builder.AddNpmApp("frontend", "../NodeFrontend", "watch")
+               .WithServiceBinding(hostPort: 5067, scheme: "http", env: "PORT");
+        // </envvarport>
+    }
+}

docs/fundamentals/snippets/networking/Networking.AppHost/Program.HostPortAndRandomPort.cs

@@ -0,0 +1,10 @@
+public static partial class Program
+{
+    public static void HostPortWithRandomServicePort(IDistributedApplicationBuilder builder)
+    {
+        // <hostport>
+        builder.AddProject<Projects.Networking_Frontend>("frontend")
+               .WithServiceBinding(hostPort: 5066, scheme: "http");
+        // </hostport>
+    }
+}

docs/fundamentals/snippets/networking/Networking.AppHost/Program.OmitHostPort.cs

@@ -0,0 +1,10 @@
+public static partial class Program
+{
+    public static void OmitHostPort(IDistributedApplicationBuilder builder)
+    {
+        // <omithostport>
+        builder.AddProject<Projects.Networking_Frontend>("frontend")
+               .WithServiceBinding(scheme: "http");
+        // </omithostport>
+    }
+}

docs/fundamentals/snippets/networking/Networking.AppHost/Program.WithLaunchProfile.cs

@@ -0,0 +1,16 @@
+public static partial class Program
+{
+    public static void WithLaunchProfile(IDistributedApplicationBuilder builder)
+    {
+        // <withlaunchprofile>
+        builder.AddProject<Projects.Networking_Frontend>("frontend")
+               .WithLaunchProfile("https");
+        // </withlaunchprofile>
+
+        // <verbose>
+        builder.AddProject<Projects.Networking_Frontend>("frontend")
+               .WithServiceBinding(hostPort: 5066, scheme: "http")
+               .WithServiceBinding(hostPort: 7239, scheme: "https");
+        // </verbose>
+    }
+}

docs/fundamentals/snippets/networking/Networking.AppHost/Program.WithReplicas.cs

@@ -0,0 +1,11 @@
+public static partial class Program
+{
+    public static void WithReplicas(IDistributedApplicationBuilder builder)
+    {
+        // <withreplicas>
+        builder.AddProject<Projects.Networking_Frontend>("frontend")
+               .WithServiceBinding(hostPort: 5066, scheme: "http")
+               .WithReplicas(2);
+        // </withreplicas>
+    }
+}

docs/fundamentals/snippets/networking/Networking.AppHost/Program.cs

@@ -0,0 +1,10 @@
+var builder = DistributedApplication.CreateBuilder(args);
+
+// ContainerPort(builder);
+// EnvVarPort(builder);
+// HostPortWithRandomServicePort(builder);
+// OmitHostPort(builder);
+// WithReplicas(builder);
+// WithLaunchProfile(builder);
+
+builder.Build().Run();

docs/fundamentals/snippets/networking/Networking.AppHost/Properties/launchSettings.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "http://json.schemastore.org/launchsettings.json",
+  "profiles": {
+    "http": {
+      "commandName": "Project",
+      "dotnetRunMessages": true,
+      "launchBrowser": true,
+      "applicationUrl": "http://localhost:15021",
+      "environmentVariables": {
+        "ASPNETCORE_ENVIRONMENT": "Development",
+        "DOTNET_ENVIRONMENT": "Development",
+        "DOTNET_DASHBOARD_OTLP_ENDPOINT_URL": "http://localhost:16244"
+      }
+    }
+  }
+}

docs/fundamentals/snippets/networking/Networking.AppHost/appsettings.Development.json

@@ -0,0 +1,8 @@
+{
+    "Logging": {
+        "LogLevel": {
+            "Default": "Information",
+            "Microsoft.AspNetCore": "Warning"
+        }
+    }
+}

docs/fundamentals/snippets/networking/Networking.AppHost/appsettings.json

@@ -0,0 +1,9 @@
+{
+    "Logging": {
+        "LogLevel": {
+            "Default": "Information",
+            "Microsoft.AspNetCore": "Warning",
+            "Aspire.Hosting.Dcp": "Warning"
+        }
+    }
+}

docs/fundamentals/snippets/networking/Networking.Frontend/Networking.Frontend.Client/Networking.Frontend.Client.csproj

@@ -0,0 +1,15 @@
+<Project Sdk="Microsoft.NET.Sdk.BlazorWebAssembly">
+
+  <PropertyGroup>
+    <TargetFramework>net8.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <NoDefaultLaunchSettingsFile>true</NoDefaultLaunchSettingsFile>
+    <StaticWebAssetProjectMode>Default</StaticWebAssetProjectMode>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Microsoft.AspNetCore.Components.WebAssembly" Version="8.0.0" />
+  </ItemGroup>
+
+</Project>

docs/fundamentals/snippets/networking/Networking.Frontend/Networking.Frontend.Client/Pages/Counter.razor

@@ -0,0 +1,19 @@
+@page "/counter"
+@rendermode InteractiveWebAssembly
+
+<PageTitle>Counter</PageTitle>
+
+<h1>Counter</h1>
+
+<p role="status">Current count: @currentCount</p>
+
+<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>
+
+@code {
+    private int currentCount = 0;
+
+    private void IncrementCount()
+    {
+        currentCount++;
+    }
+}

docs/fundamentals/snippets/networking/Networking.Frontend/Networking.Frontend.Client/Program.cs

@@ -0,0 +1,5 @@
+using Microsoft.AspNetCore.Components.WebAssembly.Hosting;
+
+var builder = WebAssemblyHostBuilder.CreateDefault(args);
+
+await builder.Build().RunAsync();

docs/fundamentals/snippets/networking/Networking.Frontend/Networking.Frontend.Client/_Imports.razor

@@ -0,0 +1,9 @@
+@using System.Net.Http
+@using System.Net.Http.Json
+@using Microsoft.AspNetCore.Components.Forms
+@using Microsoft.AspNetCore.Components.Routing
+@using Microsoft.AspNetCore.Components.Web
+@using static Microsoft.AspNetCore.Components.Web.RenderMode
+@using Microsoft.AspNetCore.Components.Web.Virtualization
+@using Microsoft.JSInterop
+@using Networking.Frontend.Client

docs/fundamentals/snippets/networking/Networking.Frontend/Networking.Frontend.Client/wwwroot/appsettings.Development.json

@@ -0,0 +1,8 @@
+{
+  "Logging": {
+    "LogLevel": {
+      "Default": "Information",
+      "Microsoft.AspNetCore": "Warning"
+    }
+  }
+}

docs/fundamentals/snippets/networking/Networking.Frontend/Networking.Frontend.Client/wwwroot/appsettings.json

@@ -0,0 +1,8 @@
+{
+  "Logging": {
+    "LogLevel": {
+      "Default": "Information",
+      "Microsoft.AspNetCore": "Warning"
+    }
+  }
+}

docs/fundamentals/snippets/networking/Networking.Frontend/Networking.Frontend/Components/App.razor

@@ -0,0 +1,20 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <base href="/" />
+    <link rel="stylesheet" href="bootstrap/bootstrap.min.css" />
+    <link rel="stylesheet" href="app.css" />
+    <link rel="stylesheet" href="Networking.Frontend.styles.css" />
+    <link rel="icon" type="image/png" href="favicon.png" />
+    <HeadOutlet />
+</head>
+
+<body>
+    <Routes />
+    <script src="_framework/blazor.web.js"></script>
+</body>
+
+</html>

docs/fundamentals/snippets/networking/Networking.Frontend/Networking.Frontend/Components/Layout/MainLayout.razor

@@ -0,0 +1,23 @@
+@inherits LayoutComponentBase
+
+<div class="page">
+    <div class="sidebar">
+        <NavMenu />
+    </div>
+
+    <main>
+        <div class="top-row px-4">
+            <a href="https://learn.microsoft.com/aspnet/core/" target="_blank">About</a>
+        </div>
+
+        <article class="content px-4">
+            @Body
+        </article>
+    </main>
+</div>
+
+<div id="blazor-error-ui">
+    An unhandled error has occurred.
+    <a href="" class="reload">Reload</a>
+    <a class="dismiss">🗙</a>
+</div>