Networking refinements (#1440)

* Initial updates * More updates * Added a few more endpoint examples * Fix id * Added tip and reorganized content * Move a few bits in the TOC * Add see also * Apply suggestions from code review Co-authored-by: Genevieve Warren <[email protected]> --------- Co-authored-by: Genevieve Warren <[email protected]>
dotnet · Jul 31, 2024 · 180520d · 180520d
1 parent 8d9a090
commit 180520d
Show file tree

Hide file tree

Showing 10 changed files with 106 additions and 48 deletions.
diff --git a/docs/fundamentals/launch-profiles.md b/docs/fundamentals/launch-profiles.md
@@ -131,3 +131,7 @@ builder.AddProject<Projects.InventoryService>("inventoryservice")
 ```
 
 The preceding code shows how to disable the reverse proxy that .NET Aspire deploys in front for the .NET Core application and instead allows the .NET Core application to respond directly on requests over HTTP(S). For more information on networking options within .NET Aspire see [.NET Aspire inner loop networking overview](./networking-overview.md).
+
+## See also
+
+- [Kestrel configured endpoints](networking-overview.md#kestrel-configured-endpoints)
diff --git a/docs/fundamentals/networking-overview.md b/docs/fundamentals/networking-overview.md
@@ -14,6 +14,7 @@ One of the advantages of developing with .NET Aspire is that it enables you to d
 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.
+- **Kestrel configuration**: Kestrel configuration allows you to specify the endpoints that the Kestrel web server listens on. You can configure Kestrel endpoints in your app settings, and .NET Aspire automatically uses these settings to create service bindings.
 - **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.WithEndpoint%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.
 
@@ -56,6 +57,25 @@ To specify the **http** and **https** launch profiles, configure the `applicatio
 
 For more information, see [.NET Aspire and launch profiles](launch-profiles.md).
 
+## Kestrel configured endpoints
+
+.NET Aspire supports Kestrel endpoint configuration. For example, consider an _appsettings.json_ file for a project that defines a Kestrel endpoint with the HTTPS scheme and port 7001:
+
+:::code language="json" source="snippets/networking/Networking.Frontend/Networking.Frontend/appsettings.Development.json" highlight="8-14":::
+
+The preceding configuration specifies an `Https` endpoint. The `Url` property is set to `https://*:7001`, which means the endpoint listens on all interfaces on port 7001. For more information, see [Configure endpoints for the ASP.NET Core Kestrel web server](/aspnet/core/fundamentals/servers/kestrel/endpoints).
+
+With the Kestrel endpoint configured, the project should remove any configured `applicationUrl` from the _launchSettings.json_ file.
+
+> [!NOTE]
+> If the `applicationUrl` is present in the _launchSettings.json_ file and the Kestrel endpoint is configured, the app host will throw an exception.
+
+When you add a project resource, there's an overload that lets you specify that the Kestrel endpoint should be used instead of the _launchSettings.json_ file:
+
+:::code source="snippets/networking/Networking.AppHost/Program.KestrelConfiguration.cs" id="kestrel":::
+
+For more information, see <xref:Aspire.Hosting.ProjectResourceBuilderExtensions.AddProject%2A>.
+
 ## 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.
@@ -109,6 +129,9 @@ The preceding diagram depicts the following:
 - The frontend proxy sitting between the web browser and the frontend service, listening on port 5067.
 - The frontend service listening on an environment 65001.
 
+> [!TIP]
+> To avoid an endpoint being proxied, set the `IsProxied` property to `false` when calling the `WithEndpoint` extension method. For more information, see [Endpoint extensions: additional considerations](#additional-considerations).
+
 ## 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:
@@ -172,3 +195,11 @@ The `Name` property identifies the service, whereas the `Port` and `TargetPort`
 For network communication, the `Protocol` property supports **TCP** and **UDP**, with potential for more in the future, and the `Transport` property indicates the transport protocol (**HTTP**, **HTTP2**, **HTTP3**). Lastly, if the service is URI-addressable, the `UriScheme` property provides the URI scheme for constructing the service URI.
 
 For more information, see the available properties of the [EndpointAnnotation properties](/dotnet/api/aspire.hosting.applicationmodel.endpointannotation#properties).
+
+## Endpoint filtering
+
+All .NET Aspire project resource endpoints follow a set of default heuristics. Some endpoints are included in `ASPNETCORE_URLS` at runtime, some are published as `HTTP/HTTPS_PORTS`, and some configurations are resolved from Kestrel configuration. Regardless of the default behavior, you can filter the endpoints that are included in environment variables by using the <xref:Aspire.Hosting.ProjectResourceBuilderExtensions.WithEndpointsInEnvironment%2A> extension method:
+
+:::code source="snippets/networking/Networking.AppHost/Program.EndpointFilter.cs" id="filter":::
+
+The preceding code adds a default HTTPS endpoint, as well as an `admin` endpoint on port 19227. However, the `admin` endpoint is excluded from the environment variables. This is useful when you want to expose an endpoint for internal use only.
diff --git a/docs/fundamentals/snippets/networking/Networking.AppHost/Program.EndpointFilter.cs b/docs/fundamentals/snippets/networking/Networking.AppHost/Program.EndpointFilter.cs
@@ -0,0 +1,16 @@
+public static partial class Program
+{
+    public static void FilterEndpoint(IDistributedApplicationBuilder builder)
+    {
+        // <filter>
+        builder.AddProject<Projects.Networking_ApiService>("apiservice")
+            .WithHttpsEndpoint() // Adds a default "https" endpoint
+            .WithHttpsEndpoint(port: 19227, name: "admin")
+            .WithEndpointsInEnvironment(
+                filter: static endpoint =>
+                {
+                    return endpoint.Name is not "admin";
+                });
+        // </filter>
+    }
+}
diff --git a/docs/fundamentals/snippets/networking/Networking.AppHost/Program.KestrelConfiguration.cs b/docs/fundamentals/snippets/networking/Networking.AppHost/Program.KestrelConfiguration.cs
@@ -0,0 +1,19 @@
+public static partial class Program
+{
+    public static IResourceBuilder<ProjectResource> WithKestrelConfig(IDistributedApplicationBuilder builder)
+    {
+        var project =
+        // <kestrel>
+        builder.AddProject<Projects.Networking_ApiService>(
+            name: "apiservice",
+            configure: static project =>
+            {
+                project.ExcludeLaunchProfile = true;
+                project.ExcludeKestrelEndpoints = false;
+            })
+            .WithHttpsEndpoint();
+        // </kestrel>
+
+        return project;
+    }
+}
diff --git a/docs/fundamentals/snippets/networking/Networking.AppHost/Program.cs b/docs/fundamentals/snippets/networking/Networking.AppHost/Program.cs
@@ -1,15 +1,12 @@
 var builder = DistributedApplication.CreateBuilder(args);
 
-var apiService = builder.AddProject<Projects.Networking_ApiService>("apiService")
-    .WithEndpoint("admin", static endpoint =>
-    {
-        endpoint.Port = 17003;
-        endpoint.UriScheme = "http";
-        endpoint.Transport = "http";
-    });
+var apiservice =
+    builder.AddProject<Projects.Networking_ApiService>(
+        name: "apiservice",
+        launchProfileName: null);
 
 builder.AddProject<Projects.Networking_Frontend>("frontend")
-       .WithReference(apiService);
+       .WithReference(apiservice);
 
 // WithEndpoint(builder);
 // ContainerPort(builder);

diff --git a/docs/fundamentals/snippets/networking/Networking.AppHost/Properties/launchSettings.json b/docs/fundamentals/snippets/networking/Networking.AppHost/Properties/launchSettings.json
@@ -9,7 +9,8 @@
       "environmentVariables": {
         "ASPNETCORE_ENVIRONMENT": "Development",
         "DOTNET_ENVIRONMENT": "Development",
-        "DOTNET_DASHBOARD_OTLP_ENDPOINT_URL": "http://localhost:16244"
+        "DOTNET_DASHBOARD_OTLP_ENDPOINT_URL": "http://localhost:16244",
+        "ASPIRE_ALLOW_UNSECURED_TRANSPORT": "true"
       }
     }
   }

diff --git a/docs/fundamentals/snippets/networking/Networking.Frontend/Networking.Frontend/Program.cs b/docs/fundamentals/snippets/networking/Networking.Frontend/Networking.Frontend/Program.cs
@@ -10,7 +10,7 @@
     .AddInteractiveWebAssemblyComponents();
 
 builder.Services.AddHttpClient<WeatherApiClient>(
-    client => client.BaseAddress = new("http://_admin.apiservice"));
+    client => client.BaseAddress = new("https+http://apiservice"));
 
 var app = builder.Build();
 

diff --git a/...nippets/networking/Networking.Frontend/Networking.Frontend/Properties/launchSettings.json b/...nippets/networking/Networking.Frontend/Networking.Frontend/Properties/launchSettings.json
@@ -1,41 +1,24 @@
 {
   "$schema": "http://json.schemastore.org/launchsettings.json",
-    "iisSettings": {
-      "windowsAuthentication": false,
-      "anonymousAuthentication": true,
-      "iisExpress": {
-        "applicationUrl": "http://localhost:64225",
-        "sslPort": 44368
+  "profiles": {
+    "http": {
+      "commandName": "Project",
+      "dotnetRunMessages": true,
+      "launchBrowser": false,
+      "inspectUri": "{wsProtocol}://{url.hostname}:{url.port}/_framework/debug/ws-proxy?browser={browserInspectUri}",
+      "environmentVariables": {
+        "ASPNETCORE_ENVIRONMENT": "Development"
       }
     },
-    "profiles": {
-      "http": {
-        "commandName": "Project",
-        "dotnetRunMessages": true,
-        "launchBrowser": true,
-        "inspectUri": "{wsProtocol}://{url.hostname}:{url.port}/_framework/debug/ws-proxy?browser={browserInspectUri}",
-        "applicationUrl": "http://localhost:5066",
-        "environmentVariables": {
-          "ASPNETCORE_ENVIRONMENT": "Development"
-        }
-      },
-      "https": {
-        "commandName": "Project",
-        "dotnetRunMessages": true,
-        "launchBrowser": true,
-        "inspectUri": "{wsProtocol}://{url.hostname}:{url.port}/_framework/debug/ws-proxy?browser={browserInspectUri}",
-        "applicationUrl": "https://localhost:7239;http://localhost:5066",
-        "environmentVariables": {
-          "ASPNETCORE_ENVIRONMENT": "Development"
-        }
-      },
-      "IIS Express": {
-        "commandName": "IISExpress",
-        "launchBrowser": true,
-        "inspectUri": "{wsProtocol}://{url.hostname}:{url.port}/_framework/debug/ws-proxy?browser={browserInspectUri}",
-        "environmentVariables": {
-          "ASPNETCORE_ENVIRONMENT": "Development"
-        }
+    "https": {
+      "commandName": "Project",
+      "dotnetRunMessages": true,
+      "launchBrowser": true,
+      "inspectUri": "{wsProtocol}://{url.hostname}:{url.port}/_framework/debug/ws-proxy?browser={browserInspectUri}",
+      "applicationUrl": "https://localhost:7239;http://localhost:5066",
+      "environmentVariables": {
+        "ASPNETCORE_ENVIRONMENT": "Development"
       }
     }
   }
+}
diff --git a/.../snippets/networking/Networking.Frontend/Networking.Frontend/appsettings.Development.json b/.../snippets/networking/Networking.Frontend/Networking.Frontend/appsettings.Development.json
@@ -4,5 +4,12 @@
       "Default": "Information",
       "Microsoft.AspNetCore": "Warning"
     }
+  },
+  "Kestrel": {
+    "Endpoints": {
+      "Https": {
+        "Url": "https://*:5271"
+      }
+    }
   }
 }
diff --git a/docs/toc.yml b/docs/toc.yml
@@ -63,6 +63,10 @@ items:
         href: service-discovery/overview.md
       - name: Service defaults
         href: fundamentals/service-defaults.md
+      - name: .NET Aspire and launch profiles
+        href: fundamentals/launch-profiles.md
+      - name: Health checks
+        href: fundamentals/health-checks.md
       - name: Telemetry
         href: fundamentals/telemetry.md
 
@@ -288,12 +292,8 @@ items:
 
   - name: Reference
     items:
-      - name: .NET Aspire and launch profiles
-        href: fundamentals/launch-profiles.md
       - name: Diagnostics overview
         href: diagnostics/overview.md
-      - name: Health checks
-        href: fundamentals/health-checks.md
       - name: .NET Aspire API reference
         href:  /dotnet/api?view=dotnet-aspire-8.0&preserve-view=true
       - name: .NET Aspire FAQ