integração .NET AspireAzureAzure SignalR Service

Inclui: integração de hospedagem, não Client integração

Azure SignalR Service é um serviço de mensagens em tempo real totalmente gerenciado que simplifica a adição de funcionalidade da Web em tempo real aos seus aplicativos. A .NET AspireAzureAzure SignalR Service integração permite que você provisione, configure e conecte facilmente seus .NET aplicativos a AzureAzure SignalR Service instâncias.

Este artigo descreve como se integrar AzureAzure SignalR Service aos aplicativos .NET Aspire , abrangendo a hospedagem e a integração do cliente.

Integração de hospedagem

Os modelos de integração de hospedagem .NET AspireAzureAzure SignalR Service estruturam recursos AzureSignalR como os seguintes tipos:

• AzureSignalRResource: representa um recurso de AzureAzure SignalR Service, incluindo informações de conexão para o recurso de Azure subjacente.
• AzureSignalREmulatorResource: representa um emulador para AzureAzure SignalR Service, permitindo o desenvolvimento e teste locais sem a necessidade de uma Azure subscrição.

Para acessar os tipos de hospedagem e as APIs para expressar esses recursos no construtor de aplicativos distribuídos, instale o 📦Aspire.Hospedagem.Azure.SignalR pacote NuGet em seu projeto de host do aplicativo:

.NET CLI

dotnet add package Aspire.Hosting.Azure.SignalR

PackageReference

<PackageReference Include="Aspire.Hosting.Azure.SignalR"
                  Version="*" />

Para obter mais informações, consulte dotnet add package ou Gerenciar dependências de pacotes em .NET aplicações.

Adicionar um recurso de AzureAzure SignalR Service

Para adicionar um AzureAzure SignalR Service recurso ao projeto de host do aplicativo, chame o AddAzureSignalR método:

var builder = DistributedApplication.CreateBuilder(args);

var signalR = builder.AddAzureSignalR("signalr");

var api = builder.AddProject<Projects.ApiService>("api")
                 .WithReference(signalR)
                 .WaitFor(signalR);

builder.AddProject<Projects.WebApp>("webapp")
       .WithReference(api)
       .WaitFor(api);

// Continue configuring and run the app...

No exemplo anterior:

• Um AzureAzure SignalR Service recurso nomeado signalr é adicionado.
• O signalr recurso é referenciado pelo api projeto.
• O projeto api é referenciado pelo projeto webapp.

Essa arquitetura permite que o webapp projeto se comunique com o api projeto, que, por sua vez, se comunica com o AzureAzure SignalR Service recurso.

Importante

A chamada AddAzureSignalR habilita o suporte ao provisionamento do Azure implicitamente. Verifique se o host do aplicativo está configurado com a assinatura e a localização apropriadas Azure . Para obter mais informações, consulte Provisionamento local: Configuração.

Provisionamento gerado por script Bicep

Quando você adiciona um recurso AzureAzure SignalR Service, .NET Aspire gera a infraestrutura de provisionamento usando Bicep. O Bicep gerado inclui configurações padrão para localização, SKU e atribuições de função.

@description('The location for the resource(s) to be deployed.')
param location string = resourceGroup().location

resource signalr 'Microsoft.SignalRService/signalR@2024-03-01' = {
  name: take('signalr-${uniqueString(resourceGroup().id)}', 63)
  location: location
  properties: {
    cors: {
      allowedOrigins: [
        '*'
      ]
    }
    features: [
      {
        flag: 'ServiceMode'
        value: 'Default'
      }
    ]
  }
  kind: 'SignalR'
  sku: {
    name: 'Free_F1'
    capacity: 1
  }
  tags: {
    'aspire-resource-name': 'signalr'
  }
}

output hostName string = signalr.properties.hostName

output name string = signalr.name

O Bicep gerado serve como ponto de partida e pode ser ainda mais personalizado.

Personalizar a infraestrutura de provisionamento

Todos os recursos .NET AspireAzure são subclasses do tipo AzureProvisioningResource. Isso permite a personalização do Bicep gerado fornecendo uma API fluente para configurar os recursos Azure usando a API ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>).

builder.AddAzureSignalR("signalr")
    .ConfigureInfrastructure(infra =>
    {
        var signalRService = infra.GetProvisionableResources()
                                  .OfType<SignalRService>()
                                  .Single();

        signalRService.Sku.Name = "Premium_P1";
        signalRService.Sku.Capacity = 10;
        signalRService.PublicNetworkAccess = "Enabled";
        signalRService.Tags.Add("ExampleKey", "Example value");
    });

O código anterior:

• Encadeia uma chamada para a API ConfigureInfrastructure:
  • O parâmetro infra é uma instância do tipo AzureResourceInfrastructure.
  • Os recursos provisionáveis são recuperados chamando o método GetProvisionableResources().
  • O único recurso SignalRService é recuperado.
  • A SignalRService.Sku propriedade recebe um nome Premium_P1 e uma capacidade de 10.
  • A propriedade SignalRService.PublicNetworkAccess está definida como Enabled.
  • Uma etiqueta é adicionada ao serviço de recurso SignalR com uma chave ExampleKey e um valor Example value.

Conectar-se a um AzureAzure SignalR Service existente

Você pode ter uma AzureAzure SignalR Service existente à qual deseja se conectar. Você pode encadear uma chamada para anotar que seu AzureSignalRResource é um recurso existente:

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...

Para obter mais informações sobre como tratar recursos AzureSignalR como recursos existentes, consulte Usar recursos de Azure existentes.

Como alternativa, em vez de representar um recurso de AzureSignalR, você pode adicionar uma cadeia de conexão ao host do aplicativo. Que é uma abordagem de tipo fraco que se baseia apenas em um valor string. Para adicionar uma conexão a um AzureAzure SignalR Serviceexistente, chame o método AddConnectionString:

var builder = DistributedApplication.CreateBuilder(args);

var signalr = builder.ExecutionContext.IsPublishMode
    ? builder.AddAzureSignalR("signalr")
    : builder.AddConnectionString("signalr");

builder.AddProject<Projects.ApiService>("apiService")
       .WithReference(signalr);

Observação

As cadeias de conexão são usadas para representar uma ampla gama de informações de conexão, incluindo conexões de banco de dados, agentes de mensagens, URIs de ponto de extremidade e outros serviços. Em .NET.NET Aspire nomenclatura, o termo "cadeia de conexão" é usado para representar qualquer tipo de informação de conexão.

A cadeia de conexão é configurada na configuração do host do aplicativo, normalmente em Segredos do Usuário, na ConnectionStrings seção:

{
  "ConnectionStrings": {
    "signalr": "Endpoint=https://your-signalr-instance.service.signalr.net;AccessKey=your-access-key;Version=1.0;"
  }
}

Para obter mais informações, consulte Adicionar recursos existentes com cadeias de conexãoAzure.

Adicionar um AzureAzure SignalR Service recurso do emulador

O AzureAzure SignalR Serviceemulador é uma ferramenta de desenvolvimento e teste local que emula o comportamento de AzureAzure SignalR Service. Esse emulador só dá suporte ao modo sem servidor, que requer uma configuração específica ao usar o emulador.

Para usar o emulador, encadeia uma chamada ao RunAsEmulator(IResourceBuilder<AzureSignalRResource>, Action<IResourceBuilder<AzureSignalREmulatorResource>>) método:

using Aspire.Hosting.Azure;

var builder = DistributedApplication.CreateBuilder(args);

var signalR = builder.AddAzureSignalR("signalr", AzureSignalRServiceMode.Serverless)
                     .RunAsEmulator();

builder.AddProject<Projects.ApiService>("apiService")
       .WithReference(signalR)
       .WaitFor(signalR);

// After adding all resources, run the app...

No exemplo anterior, o RunAsEmulator método configura o AzureAzure SignalR Service recurso a ser executado como um emulador. O emulador é baseado na imagem do mcr.microsoft.com/signalr/signalr-emulator:latest contêiner. O emulador é iniciado quando o host do aplicativo é executado e é parado quando o host do aplicativo é parado.

Azure Azure SignalR Service Modos

Embora o AzureAzure SignalR Service emulador dê suporte apenas ao modo sem servidor , o AzureAzure SignalR Service recurso pode ser configurado para usar qualquer um dos seguintes modos:

• AzureSignalRServiceMode.Default
• AzureSignalRServiceMode.Serverless

O modo padrão é a configuração "padrão" para AzureAzure SignalR Service. Cada modo tem seu próprio conjunto de recursos e limitações. Para obter mais informações, consulte AzureAzure SignalR Service os modos.

Importante

O AzureAzure SignalR Service emulador funciona apenas no modo sem servidor e o AddNamedAzureSignalR método não dá suporte ao modo sem servidor .

Integração do host do hub

Não há uma integração oficial .NET AspireAzureSignalRdo cliente. No entanto, há suporte limitado para experiências semelhantes. Nesses cenários, o AzureAzure SignalR Service atua como um proxy entre o servidor (onde o Hub ou Hub<T> estão hospedados) e o cliente (onde o SignalR cliente está hospedado). O AzureAzure SignalR Service encaminha o tráfego entre o servidor e o cliente, permitindo a comunicação em tempo real.

Importante

É importante desambiguar entre as integrações de cliente .NET Aspire e o cliente .NETSignalR. SignalR expõe hubs — que funcionam como conceito de servidor — e SignalR os clientes se conectam a esses hubs. Os projetos .NET que hospedam os hubs SignalR são onde você se integra com .NET Aspire. O SignalR cliente é uma biblioteca separada que se conecta a esses hubs, em um projeto diferente.

Há dois pacotes disponíveis, cada um abordando cenários específicos, como gerenciar a conexão do cliente com AzureAzure SignalR Service e conectar-se ao recurso AzureAzure SignalR Service. Para começar, instale o 📦 Microsoft.Azure.SignalR Pacote NuGet no projeto que hospeda seu SignalR hub.

.NET CLI

dotnet add package Microsoft.Azure.SignalR

PackageReference

<PackageReference Include="Microsoft.Azure.SignalR"
                  Version="*" />

Configurar AzureAzure SignalR Service nomeado no modo Padrão

No modo Padrão , seu projeto de consumo precisa contar com um recurso nomeado AzureAzure SignalR Service . Considere o diagrama a seguir que ilustra a arquitetura do AzureAzure SignalR Service no modo Padrão:

Para obter mais informações sobre o modo Padrão , consulte AzureAzure SignalR Service: modo padrão.

No projeto de host do seu SignalR hub, configure AzureAzure SignalR Service encadeando chamadas para .AddSignalR().AddNamedAzureSignalR("name"):

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddSignalR()
                .AddNamedAzureSignalR("signalr");

var app = builder.Build();

app.MapHub<ChatHub>("/chat");

app.Run();

O AddNamedAzureSignalR método configura o projeto para usar o AzureAzure SignalR Service recurso chamado signalr. A cadeia de conexão é lida da chave ConnectionStrings:signalrde configuração e as configurações adicionais são carregadas da Azure:SignalR:signalr seção de configuração.

Observação

Se você estiver usando o AzureSignalR emulador, não poderá usar o AddNamedAzureSignalR método.

Configurar AzureAzure SignalR Service no modo sem servidor

Se o host do aplicativo estiver usando o AzureSignalR emulador, você também precisará instalar o 📦 Microsoft.Azure.SignalR.Management NuGet package.

.NET CLI

dotnet add package Microsoft.Azure.SignalR.Management

PackageReference

<PackageReference Include="Microsoft.Azure.SignalR.Management"
                  Version="*" />

Azure SignalR O modo sem servidor não requer que um servidor hub esteja em execução. O AzureAzure SignalR Service é responsável por manter as conexões de cliente. Além disso, nesse modo, você não pode usar Hubs tradicionais SignalR , como Hub, Hub<T>ou IHubContext<THub>. Em vez disso, configure um ponto de extremidade upstream que geralmente é um Azure gatilho de Função SignalR. Considere o diagrama a seguir que ilustra a arquitetura do AzureAzure SignalR Service modo sem servidor :

Para obter mais informações sobre o modo sem servidor , consulte AzureAzure SignalR Service: modo sem servidor.

Em um projeto que se destina a se comunicar com o AzureAzure SignalR Service, registre os serviços apropriados chamando AddSignalR, em seguida, registre o ServiceManager usando a cadeia de conexão signalr e adicione um endpoint /negotiate:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddSingleton(sp =>
{
   return new ServiceManagerBuilder()
       .WithOptions(options =>
       {
           options.ConnectionString = builder.Configuration.GetConnectionString("signalr");
       })
       .BuildServiceManager();
});

var app = builder.Build();

app.MapPost("/negotiate", async (string? userId, ServiceManager sm, CancellationToken token) =>
{
    // The creation of the ServiceHubContext is expensive, so it's recommended to 
    // only create it once per named context / per app run if possible.
    var context = await sm.CreateHubContextAsync("messages", token);
    
    var negotiateResponse = await context.NegotiateAsync(new NegotiationOptions
    {
        UserId = userId
    }, token);
    
    // The JSON serializer options need to be set to ignore null values, otherwise the
    // response will contain null values for the properties that are not set.
    // The .NET SignalR client will not be able to parse the response if the null values are present.
    // For more information, see https://github.com/dotnet/aspnetcore/issues/60935.
    return Results.Json(negotiateResponse, new JsonSerializerOptions(JsonSerializerDefaults.Web)
    {
        DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull
    });
});

app.Run();

O código anterior configura o AzureAzure SignalR Service usando a classe ServiceManagerBuilder, mas não chama AddSignalR ou MapHub. Essas duas extensões não são necessárias com o modo sem servidor . A cadeia de conexão é lida da chave de configuração ConnectionStrings:signalr. Ao usar o emulador, somente o ponto de extremidade HTTP está disponível. No aplicativo, você pode usar a ServiceManager instância para criar um ServiceHubContext. O ServiceHubContext é usado para transmitir mensagens e gerenciar conexões com clientes.

O /negotiate ponto de extremidade é necessário para estabelecer uma conexão entre o cliente de conexão e o AzureAzure SignalR Service. O ServiceHubContext é criado usando o método ServiceManager.CreateHubContextAsync, que usa o nome do hub como parâmetro. O NegotiateAsync método é chamado para negociar a conexão com o AzureAzure SignalR Service, que retorna um token de acesso e a URL para o cliente se conectar.

Para obter mais informações, consulte Usar AzureSignalR o SDK de Gerenciamento.

Consulte também

• visão geral AzureAzure SignalR Service
• Ampliar ASP.NET CoreSignalR aplicativos com AzureAzure SignalR Service
• visão geral das integrações .NET AspireAzure
• integrações .NET.NET Aspire
• .NET Aspire GitHub repo