Draft - WIP.

Author: IEvangelist

docs/real-time/azure-signalr-scenario.md

@@ -1,11 +1,13 @@
 ---
 title: .NET Aspire Azure SignalR Service integration
 description: Learn how to integrate Azure SignalR Service with .NET Aspire.
-ms.date: 03/05/2025
+ms.date: 03/06/2025
 ---
 
 # .NET Aspire Azure SignalR Service integration
 
+[!INCLUDE [includes-hosting](../includes/includes-hosting.md)]
+
 [Azure SignalR Service](/azure/azure-signalr/signalr-overview) is a fully managed real-time messaging service that simplifies adding real-time web functionality to your applications. The .NET Aspire Azure SignalR Service integration enables you to easily provision, configure, and connect your .NET applications to Azure SignalR Service instances.
 
 This article describes how to integrate Azure SignalR Service into your .NET Aspire applications, covering both hosting and client integration.
@@ -17,7 +19,7 @@ The .NET Aspire Azure SignalR Service hosting integration models Azure SignalR r
 - <xref:Aspire.Hosting.Azure.AzureSignalRResource>: Represents an Azure SignalR Service resource, including connection information to the underlying Azure resource.
 - <xref:Aspire.Hosting.Azure.AzureSignalREmulatorResource>: Represents an emulator for Azure SignalR Service, allowing local development and testing without requiring an Azure subscription.
 
-To access the hosting APIs, install the [📦 Aspire.Hosting.Azure.SignalR](https://www.nuget.org/packages/Aspire.Hosting.Azure.SignalR) NuGet package in your [app host](../fundamentals/app-host-overview.md#app-host-project) project:
+To access the hosting types and APIs for expressing these resources in the distributed application builder, install the [📦 Aspire.Hosting.Azure.SignalR](https://www.nuget.org/packages/Aspire.Hosting.Azure.SignalR) NuGet package in your [app host](../fundamentals/app-host-overview.md#app-host-project) project:
 
 ### [.NET CLI](#tab/dotnet-cli)
 
@@ -38,7 +40,7 @@ For more information, see [dotnet add package](/dotnet/core/tools/dotnet-add-pac
 
 ### Add an Azure SignalR Service resource
 
-To add an Azure SignalR Service resource to your app host project, call the `AddAzureSignalR` method:
+To add an Azure SignalR Service resource to your app host project, call the <xref:Aspire.Hosting.AzureSignalRExtensions.AddAzureSignalR*> method:
 
 ```csharp
 var builder = DistributedApplication.CreateBuilder(args);
@@ -128,7 +130,7 @@ var signalR = builder.AddAzureSignalR("signalr")
                      .ConfigureInfrastructure(infra =>
                      {
                          var resources = infra.GetProvisionableResources();
-                         var signalRResource = resources.OfType<Azure.Provisioning.SignalR.SignalRService>().Single();
+                         var signalRResource = resources.OfType<SignalRService>().Single();
 
                          signalRResource.Sku.Name = "Premium_P1";
                          signalRResource.Sku.Capacity = 2;
@@ -139,18 +141,41 @@ var signalR = builder.AddAzureSignalR("signalr")
 
 ### Connect to an existing Azure SignalR Service
 
-To connect to an existing Azure SignalR Service, use the `AddConnectionString` method:
+You might have an existing Azure SignalR Service that you want to connect to. You can chain a call to annotate that your <xref:Aspire.Hosting.ApplicationModel.AzureSignalRResource> is an existing resource:
+
+```csharp
+var builder = DistributedApplication.CreateBuilder(args);
+
+var existingSignalRName = builder.AddParameter("existingSignalRName");
+var existingSignalRResourceGroup = builder.AddParameter("existingSignalRResourceGroup");
+
+var signalr = builder.AddAzureSignalR("signalr")
+                     .AsExisting(existingSignalRName, existingSignalRResourceGroup);
+
+builder.AddProject<Projects.ExampleProject>()
+       .WithReference(signalr);
+
+// After adding all resources, run the app...
+```
+
+For more information on treating Azure SignalR resources as existing resources, see [Use existing Azure resources](../azure/integrations-overview.md#use-existing-azure-resources).
+
+Alternatively, instead of representing an Azure SignalR resource, you can add a connection string to the app host. Which is a weakly-typed approach that's based solely on a `string` value. To add a connection to an existing Azure SignalR Service, call the <xref:Aspire.Hosting.ParameterResourceBuilderExtensions.AddConnectionString%2A> method:
 
 ```csharp
 var builder = DistributedApplication.CreateBuilder(args);
 
-var signalR = builder.AddConnectionString("signalr");
+var signalr = builder.ExecutionContext.IsPublishMode
+    ? builder.AddAzureSignalR("signalr")
+    : builder.AddConnectionString("signalr");
 
 builder.AddProject<Projects.ApiService>("apiService")
-       .WithReference(signalR);
+       .WithReference(signalr);
 ```
 
-The connection string is configured in the app host's configuration, typically under [User Secrets](/aspnet/core/security/app-secrets):
+[!INCLUDE [connection-strings-alert](../includes/connection-strings-alert.md)]
+
+The connection string is configured in the app host's configuration, typically under [User Secrets](/aspnet/core/security/app-secrets), under the `ConnectionStrings` section:
 
 ```json
 {
@@ -160,13 +185,34 @@ The connection string is configured in the app host's configuration, typically u
 }
 ```
 
-## Client integration
+For more information, see [Add existing Azure resources with connection strings](../azure/integrations-overview.md#add-existing-azure-resources-with-connection-strings).
+
+### Add an Azure SignalR Service emulator resource
+
+The Azure SignalR Service emulator is a local development and testing tool that emulates the behavior of Azure SignalR Service. This emulator only supports [Serverless_ mode](/azure/azure-signalr/concept-service-mode#serverless-mode), which requires a specific configuration when using the emulator.
+
+To use the emulator, chain a call to the <xref:Aspire.Hosting.AzureSignalRExtensions.RunAsEmulator(Aspire.Hosting.ApplicationModel.IResourceBuilder{Aspire.Hosting.ApplicationModel.AzureSignalRResource},System.Action{Aspire.Hosting.ApplicationModel.IResourceBuilder{Aspire.Hosting.Azure.AzureSignalREmulatorResource}})> method:
+
+```csharp
+using Aspire.Hosting.Azure;
+
+var builder = DistributedApplication.CreateBuilder(args);
+
+var signalR = builder.AddAzureSignalR("signalr", AzureSignalRServiceMode.Serverless)
+                     .RunAsEmulator();
 
-The client integration enables your ASP.NET Core application to use Azure SignalR Service for real-time messaging.
+builder.AddProject<Projects.ApiService>("apiService")
+       .WithReference(signalR)
+       .WaitFor(signalR);
 
-### Install the NuGet package
+// After adding all resources, run the app...
+```
+
+In the preceding example, the `RunAsEmulator` method configures the Azure SignalR Service resource to run as an emulator. The emulator is started when the app host is run, and it will be stopped when the app host is stopped.
 
-Install the [📦 Microsoft.Azure.SignalR](https://www.nuget.org/packages/Microsoft.Azure.SignalR) NuGet package in the project hosting your SignalR hub:
+## Client integration
+
+There isn't an official .NET Aspire Azure SignalR client integration. However, there is limited support for similar experiences. There are two specific packages available for [.NET from the Azure team](https://github.com/Azure/azure-signalr) that enable scenarios such as managing the client connection to Azure SignalR Service, and hooking up to the Azure SignalR Service resource. To get started, install the [📦 Microsoft.Azure.SignalR](https://www.nuget.org/packages/Microsoft.Azure.SignalR) NuGet package in the project hosting your SignalR hub.
 
 ### [.NET CLI](#tab/dotnet-cli)
 
@@ -183,6 +229,23 @@ dotnet add package Microsoft.Azure.SignalR
 
 ---
 
+If you're app host is using the Azure SignalR emulator, you'll also need to install the [📦 Microsoft.Azure.SignalR.Management](https://www.nuget.org/packages/Microsoft.Azure.SignalR.Management) NuGet package.
+
+### [.NET CLI](#tab/dotnet-cli)
+
+```dotnetcli
+dotnet add package Microsoft.Azure.SignalR.Management
+```
+
+### [PackageReference](#tab/package-reference)
+
+```xml
+<PackageReference Include="Microsoft.Azure.SignalR.Management"
+                  Version="*" />
+```
+
+---
+
 ### Configure the SignalR client
 
 In your SignalR hub host project, configure Azure SignalR Service using the `AddNamedAzureSignalR` extension method chained to `AddSignalR`:

docs/real-time/snippets/signalr/SignalR.ApiService/Program.cs

@@ -1,18 +1,48 @@
-var builder = WebApplication.CreateBuilder(args);
+using Microsoft.Azure.SignalR.Management;
+
+var builder = WebApplication.CreateBuilder(args);
 
 builder.AddServiceDefaults();
 
 builder.Services.AddProblemDetails();
 
-builder.Services.AddSignalR()
-                .AddNamedAzureSignalR("signalr");
+builder.Services.AddSignalR();
+                //.AddNamedAzureSignalR("signalr");
+
+builder.Services.AddSingleton(sp =>
+{
+    return new ServiceManagerBuilder()
+        .WithOptions(options =>
+        {
+            options.ConnectionString = builder.Configuration.GetConnectionString("signalr");
+        })
+        .WithLoggerFactory(sp.GetRequiredService<ILoggerFactory>())
+        .BuildServiceManager();
+});
 
 var app = builder.Build();
 
 app.UseExceptionHandler();
 
 app.MapHub<ChatHub>(HubEndpoints.ChatHub);
 
+app.MapPost("/negotiate", async (ServiceManager serviceManager, string? userId) =>
+{
+    var healthy = await serviceManager.IsServiceHealthy(CancellationToken.None);
+    if (healthy is false)
+    {
+        return Results.Problem("SignalR service is not healthy.");
+    }
+
+    var hubContext = await serviceManager.CreateHubContextAsync(HubEndpoints.ChatHub, default);
+    var negotiateResponse = await hubContext.NegotiateAsync(new NegotiationOptions
+    {
+        UserId = userId ?? "user1"
+    });
+
+    return Results.Ok(negotiateResponse);
+});
+
 app.MapDefaultEndpoints();
 
 app.Run();

docs/real-time/snippets/signalr/SignalR.ApiService/SignalR.ApiService.csproj

@@ -9,6 +9,7 @@
 
   <ItemGroup>
     <PackageReference Include="Microsoft.Azure.SignalR" Version="1.30.2" />
+    <PackageReference Include="Microsoft.Azure.SignalR.Management" Version="1.30.2" />
   </ItemGroup>
 
   <ItemGroup>

docs/real-time/snippets/signalr/SignalR.AppHost/Program.cs

@@ -1,6 +1,8 @@
-var builder = DistributedApplication.CreateBuilder(args);
+using Aspire.Hosting.Azure;
 
-var signalR = builder.AddAzureSignalR("signalr")
+var builder = DistributedApplication.CreateBuilder(args);
+
+var signalR = builder.AddAzureSignalR("signalr", AzureSignalRServiceMode.Serverless)
                      .RunAsEmulator();
 
 var apiService = builder.AddProject<Projects.SignalR_ApiService>("apiservice")