Visión general de las integraciones de .NET AspireAzure

Azure es la plataforma en la nube más popular para compilar e implementar aplicaciones .NET. El SDK de Azure para .NET permite administrar y usar fácilmente los servicios de Azure. .NET Aspire proporciona un conjunto de integraciones con servicios Azure, donde puede agregar nuevos recursos o conectarse a los existentes. En este artículo se detallan algunos aspectos comunes de todas las integraciones de Azure en .NET Aspire y se pretende ayudarle a comprender cómo usarlos.

Añadir Azure recursos

Todas las integraciones de hospedaje de .NET AspireAzure exponen recursos Azure y por convención se agregan mediante AddAzure* API. Al añadir estos recursos a tu host de aplicación .NET Aspire, representan un servicio Azure. La API de AddAzure* devuelve un IResourceBuilder<T> donde T es el tipo de recurso de Azure. Estas interfaces de IResourceBuilder<T> (constructor) proporcionan una API fluida que permite configurar el recurso subyacente Azure dentro del modelo de aplicación. Hay API para agregar nuevos recursos de Azure, marcar los recursos como existentes y configurar cómo se comportan los recursos en varios contextos de ejecución.

Experiencia típica para desarrolladores

Cuando su .NET Aspire app host contiene recursos Azure, y la ejecuta localmente (experiencia típica de desarrollador F5 o dotnet run), los recursos Azure se aprovisionan en su suscripción Azure. Esta funcionalidad le permite a usted como desarrollador depurar estos elementos localmente en el contexto del host de su aplicación.

.NET .NET Aspire pretende minimizar los costos por defecto optando por Basic o StandardStock Keeping Unit (SKU) para sus integraciones de Azure. Aunque se proporcionan estos valores predeterminados razonables, puede personalizar los recursos de Azure para satisfacer sus necesidades. Además, algunas integraciones admiten emuladores o contenedores, que son útiles para el desarrollo, las pruebas y la depuración locales. De forma predeterminada, al ejecutar la aplicación localmente, los recursos de Azure usan el servicio Azure real. Sin embargo, puede configurarlos para que usen emuladores o contenedores locales, evitando los costos asociados con el servicio Azure real durante el desarrollo local.

Emuladores locales

Algunos servicios de Azure se pueden emular para ejecutarse localmente. Actualmente, .NET Aspire admite los siguientes emuladores de Azure:

Para que sus recursos Azure utilicen los emuladores locales, encadene una llamada al método RunAsEmulator en el compilador de recursos Azure. Este método configura el recurso Azure para usar el emulador local en lugar del servicio Azure real.

Contenedores locales

Algunos recursos Azure se pueden sustituir localmente mediante contenedores de código abierto o en las instalaciones. Para sustituir un recurso de Azure localmente en un contenedor, encadene una llamada al método RunAsContainer en el generador de recursos de Azure. Este método configura el recurso de Azure para usar una versión en contenedor del servicio para el desarrollo y las pruebas locales, en lugar del servicio Azure real.

Actualmente, .NET Aspire admite los siguientes servicios Azure como contenedores:

Descripción de las API de integración de Azure

La fuerza de .NET.NET Aspirereside en su capacidad para proporcionar un ciclo interno asombroso para desarrolladores. Las integraciones de Azure no son diferentes. Proporcionan un conjunto de API y patrones comunes que se comparten en todos los recursos de Azure. Estas APIs y patrones están diseñados para facilitar el trabajo con recursos Azure de manera coherente.

En la sección de contenedores precedentes, has visto cómo ejecutar Azure servicios en contenedores de forma local. Si está familiarizado con .NET.NET Aspire, es posible que se pregunte cómo llamar a AddAzureRedis("redis").RunAsContainer() para obtener un contenedor de docker.io/library/redis local difiere de AddRedis("redis"), ya que ambos dan como resultado el mismo contenedor local.

La respuesta es que no hay ninguna diferencia al ejecutarse localmente. Sin embargo, cuando se publican, consigues recursos diferentes:

Lo mismo sucede con los servicios SQL y PostgreSQL:

Para obtener más información sobre la diferencia entre los modos de ejecución y publicación, consulte .NET.NET Aspire host de la aplicación: Contexto de ejecución.

API para expresar recursos de Azure en distintos modos

El compilador de aplicaciones distribuidas, parte del app host, utiliza el patrón de compilador para AddAzure* recursos al modelo de aplicación. Los desarrolladores pueden configurar estos recursos y definir su comportamiento en distintos contextos de ejecución. Azure las integraciones de hospedaje proporcionan API para especificar cómo se deben "publicar" y "ejecutar" estos recursos.

Cuando se ejecuta el host de la aplicación, se usa el contexto de ejecución para determinar si el host de la aplicación está en modo Run o Publish. Las convenciones de nomenclatura de estas API indican la acción prevista para el recurso.

En la tabla siguiente se resumen las convenciones de nomenclatura que se usan para expresar los recursos de Azure:

Para obtener más información sobre los modos de ejecución, vea contexto de ejecución.

Casos de uso de la API del modo de ejecución general

Use RunAsExisting cuando necesite interactuar dinámicamente con un recurso existente durante el tiempo de ejecución sin necesidad de implementarlo ni actualizarlo. Use PublishAsExisting al declarar los recursos existentes como parte de una configuración de implementación, lo que garantiza que se aplican los ámbitos y permisos correctos. Por último, use AsExisting<T>(IResourceBuilder<T>, IResourceBuilder<ParameterResource>, IResourceBuilder<ParameterResource>) al declarar los recursos existentes en ambas configuraciones, con un requisito para parametrizar las referencias.

Puede consultar si un recurso está marcado como un recurso existente llamando al método de extensión IsExisting(IResource) en el IResource. Para obtener más información, consulte Uso de Azure recursos existentes.

Usa los recursos existentes Azure

.NET Aspire proporciona soporte para referenciar los recursos existentes de Azure. Marca un recurso existente a través de las API de PublishAsExisting, RunAsExistingy AsExisting. Estas API permiten a los desarrolladores hacer referencia a recursos de Azure ya implementados, configurarlos y generar manifiestos de implementación adecuados mediante plantillas de Bicep.

Los recursos existentes referenciados con estas API se pueden mejorar con asignaciones de roles y otras personalizaciones que están disponibles con las .NET de .NET Aspire. Estas APIs se limitan a recursos Azure que se pueden implementar con plantillas de Bicep.

Configurar los recursos de Azure existentes para el modo de ejecución

El método RunAsExisting se usa cuando una aplicación distribuida se ejecuta en modo "ejecutar". En este modo, se supone que el recurso de Azure al que se hace referencia ya existe y se integra con él durante la ejecución sin aprovisionar el recurso. Para marcar un recurso Azure como existente, llame al método RunAsExisting en el generador de recursos. Tenga en cuenta el ejemplo siguiente:

var builder = DistributedApplication.CreateBuilder();

var existingServiceBusName = builder.AddParameter("existingServiceBusName");
var existingServiceBusResourceGroup = builder.AddParameter("existingServiceBusResourceGroup");

var serviceBus = builder.AddAzureServiceBus("messaging")
                        .RunAsExisting(existingServiceBusName, existingServiceBusResourceGroup);

serviceBus.AddServiceBusQueue("queue");

El código anterior:

• Crea una nueva instancia de builder.
• Agrega un parámetro denominado existingServiceBusName al constructor.
• Agrega un recurso Azure Service Bus denominado messaging al constructor.
• Llama al método RunAsExisting en el generador de recursos serviceBus, pasando el parámetro existingServiceBusName; alternativamente, puede usar la sobrecarga del parámetro string.
• Añade una cola denominada queue al recurso serviceBus.

De forma predeterminada, se supone que la referencia de parámetros de Service Bus está en el mismo grupo de recursos Azure. Sin embargo, si se encuentra en otro grupo de recursos, puede pasar el grupo de recursos explícitamente como parámetro para especificar correctamente la agrupación de recursos adecuada.

Configurar los recursos de Azure existentes para el modo de publicación

El método PublishAsExisting se usa en modo "publicar" cuando la intención es declarar y hacer referencia a un recurso de Azure ya existente durante el modo de publicación. Esta API facilita la creación de manifiestos y plantillas que incluyen definiciones de recursos que se asignan a los recursos existentes en Bicep.

Para marcar un recurso de Azure como existente en para el modo "publicar", llame al método PublishAsExisting en el generador de recursos. Tenga en cuenta el ejemplo siguiente:

var builder = DistributedApplication.CreateBuilder();

var existingServiceBusName = builder.AddParameter("existingServiceBusName");
var existingServiceBusResourceGroup = builder.AddParameter("existingServiceBusResourceGroup");

var serviceBus = builder.AddAzureServiceBus("messaging")
                        .PublishAsExisting(existingServiceBusName, existingServiceBusResourceGroup);

serviceBus.AddServiceBusQueue("queue");

El código anterior:

• Crea una nueva instancia de builder.
• Agrega un parámetro denominado existingServiceBusName al constructor.
• Agrega un recurso Azure Service Bus denominado messaging al constructor.
• Llama al método PublishAsExisting en el generador de recursos serviceBus, pasando el parámetro existingServiceBusName; alternativamente, puede usar la sobrecarga del parámetro string.
• Añade una cola denominada queue al recurso serviceBus.

Una vez ejecutado el host de la aplicación en modo de publicación, el archivo de manifiesto generado incluirá el parámetro existingResourceName, que se puede usar para hacer referencia al recurso Azure existente. Tenga en cuenta el siguiente fragmento de código parcial generado del archivo de manifiesto:

"messaging": {
  "type": "azure.bicep.v0",
  "connectionString": "{messaging.outputs.serviceBusEndpoint}",
  "path": "messaging.module.bicep",
  "params": {
    "existingServiceBusName": "{existingServiceBusName.value}",
    "principalType": "",
    "principalId": ""
  }
},
"queue": {
  "type": "value.v0",
  "connectionString": "{messaging.outputs.serviceBusEndpoint}"
}

Para obtener más información sobre el archivo de manifiesto, vea .NET.NET Aspire formato de manifiesto para los generadores de herramientas de implementación.

Además, la plantilla de Bicep generada incluye el parámetro existingResourceName, que se puede usar para hacer referencia al recurso Azure existente. Considere la siguiente plantilla generada en Bicep:

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

param existingServiceBusName string

param principalType string

param principalId string

resource messaging 'Microsoft.ServiceBus/namespaces@2024-01-01' existing = {
  name: existingServiceBusName
}

resource messaging_AzureServiceBusDataOwner 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(messaging.id, principalId, subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '090c5cfd-751d-490a-894a-3ce6f1109419'))
  properties: {
    principalId: principalId
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '090c5cfd-751d-490a-894a-3ce6f1109419')
    principalType: principalType
  }
  scope: messaging
}

resource queue 'Microsoft.ServiceBus/namespaces/queues@2024-01-01' = {
  name: 'queue'
  parent: messaging
}

output serviceBusEndpoint string = messaging.properties.serviceBusEndpoint

Para obtener más información sobre las plantillas de Bicep generadas, consulte Personalización Azure de recursos y consideración de otras API de publicación.

Configurar recursos Azure existentes en todos los modos

El método AsExisting<T>(IResourceBuilder<T>, IResourceBuilder<ParameterResource>, IResourceBuilder<ParameterResource>) se usa cuando la aplicación distribuida se ejecuta en modo "ejecutar" o "publicar". Dado que el método AsExisting funciona en ambos escenarios, solo admite una referencia con parámetros al nombre del recurso o al nombre del grupo de recursos. Este enfoque ayuda a evitar el uso del mismo recurso en entornos de prueba y producción.

Para marcar un recurso Azure como existente, llame al método AsExisting en el generador de recursos. Tenga en cuenta el ejemplo siguiente:

var builder = DistributedApplication.CreateBuilder();

var existingServiceBusName = builder.AddParameter("existingServiceBusName");
var existingServiceBusResourceGroup = builder.AddParameter("existingServiceBusResourceGroup");

var serviceBus = builder.AddAzureServiceBus("messaging")
                        .AsExisting(existingServiceBusName, existingServiceBusResourceGroup);

serviceBus.AddServiceBusQueue("queue");

El código anterior:

• Crea una nueva instancia de builder.
• Agrega un parámetro denominado existingServiceBusName al constructor.
• Agrega un recurso Azure Service Bus denominado messaging al constructor.
• Llama al método AsExisting en el generador de recursos de serviceBus y pasa el parámetro existingServiceBusName.
• Añade una cola denominada queue al recurso serviceBus.

Añade recursos Azure existentes con cadenas de conexión

.NET .NET Aspire proporciona la capacidad de conectarse a los recursos existentes, incluidos los recursos Azure. Expresar cadenas de conexión resulta útil cuando tiene recursos Azure existentes que desea usar en la aplicación de .NET Aspire. La API de AddConnectionString se usa con el contexto de ejecución del host de la aplicación para agregar condicionalmente una cadena de conexión al modelo de aplicación.

Tenga en cuenta el ejemplo siguiente, donde en modo de publicación agrega un recurso de Almacenamiento Azure, mientras que en modo de ejecución agrega una cadena de conexión a un Almacenamiento Azure existente.

var builder = DistributedApplication.CreateBuilder(args);

var storage = builder.ExecutionContext.IsPublishMode
    ? builder.AddAzureStorage("storage")
    : builder.AddConnectionString("storage");

builder.AddProject<Projects.Api>("api")
       .WithReference(storage);

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

El código anterior:

• Crea una nueva instancia de builder.
• Agrega un recurso de Azure Storage denominado storage en modo "publicar".
• Agrega una cadena de conexión en modo 'run' a un almacenamiento Azure existente denominado storage.
• Añade un proyecto denominado api al compilador.
• El proyecto api hace referencia al recurso storage independientemente del modo.

El proyecto de API de consumo usa la información de la cadena de conexión sin saber cómo lo configuró el host de la aplicación. En el modo "publicar", el código agrega un nuevo recurso de almacenamiento Azure, que se reflejaría adecuadamente en el manifiesto de implementación de . Cuando está en modo "ejecutar", la cadena de conexión corresponde a un valor de configuración visible para el host de la aplicación. Se supone que todas las asignaciones de roles para el recurso de destino están configuradas. Esto significa que es probable que configure una variable de entorno o un secreto de usuario para almacenar la cadena de conexión. La configuración se resuelve desde la clave de configuración ConnectionStrings__storage (o ConnectionStrings:storage). Estos valores de configuración se pueden ver cuando se ejecuta la aplicación. Para obtener más información, consulte Detalles del recurso.

A diferencia de los recursos existentes modelados con la API AsExisting de primera clase, los recursos existentes modelados como cadenas de conexión no se pueden mejorar con asignaciones de roles adicionales ni personalizaciones de infraestructura.

Publicar como Azure Container App

.NET .NET Aspire permite publicar recursos primitivos como Azure Container Apps, una plataforma sin servidor que reduce la administración de infraestructuras. Los tipos de recurso admitidos incluyen:

• ContainerResource: representa un contenedor especificado.
• ExecutableResource: representa un proceso ejecutable especificado.
• ProjectResource: representa un proyecto de .NET especificado.

Para publicar estos recursos, use las SIGUIENTES API:

• AzureContainerAppContainerExtensions.PublishAsAzureContainerApp<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure,ContainerApp>)
• AzureContainerAppExecutableExtensions.PublishAsAzureContainerApp<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure,ContainerApp>)
• AzureContainerAppProjectExtensions.PublishAsAzureContainerApp<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure,ContainerApp>)

Estas APIs configuran el recurso que se va a publicar como una Aplicación de Contenedor Azure y llaman de manera implícita a AddAzureContainerAppsInfrastructure(IDistributedApplicationBuilder) para agregar la infraestructura necesaria y los archivos de Bicep al host de su aplicación. Por ejemplo, considere el código siguiente:

var builder = DistributedApplication.CreateBuilder();

var env = builder.AddParameter("env");

var api = builder.AddProject<Projects.AspireApi>("api")
                 .PublishAsAzureContainerApp<Projects.AspireApi>((infra, app) =>
                 {
                     app.Template.Containers[0].Value!.Env.Add(new ContainerAppEnvironmentVariable
                     {
                         Name = "Hello",
                         Value = env.AsProvisioningParameter(infra)
                     });
                 });

El código anterior:

• Crea una nueva instancia de builder.
• Agrega un parámetro denominado env al constructor.
• Añade un proyecto denominado api al compilador.
• Llama al método PublishAsAzureContainerApp en el generador de recursos de api, pasando una expresión lambda que configura la infraestructura de Azure Container App, donde infra es el AzureResourceInfrastructure y app es el ContainerApp.
  • Agrega una variable de entorno denominada Hello a la aplicación contenedora mediante el parámetro env.
  • El método AsProvisioningParameter se usa para tratar env como una nueva ProvisioningParameter en la infraestructura o reutiliza un parámetro bicep existente si ya existe uno con el mismo nombre.

Para configurar el Azure entorno de la aplicación contenedora, consulte Configuración Azure Container Apps de entornos. Para obtener más información, consulte ContainerApp y AsProvisioningParameter.

Publicación

Cuando publica su app, el aprovisionamiento Azure generado Bicep es utilizado por el Azure Developer CLI para crear los recursos Azure en su suscripción Azure. .NET .NET Aspire genera una manifiesto de publicación, que también es una parte fundamental del proceso de publicación. El Azure Developer CLI es una herramienta de línea de comandos que proporciona un conjunto de comandos para administrar Azure recursos.

Para obtener más información sobre la publicación e implementación, consulte Implementación de un proyecto de .NET Aspire en Azure Container Apps mediante la Azure Developer CLI (guía detallada).