Personalización de las cadenas de conexión mediante manifiestos .NET Aspire

  • 7 minutos

Las herramientas de implementación como Visual Studio o Azure Developer CLI crean archivos de manifiesto que describen el contenido de una solución .NET Aspire. Si desea personalizar su implementación, puede realizar cambios en el archivo de manifiesto directamente.

En su tienda de equipamiento para exteriores, ha decidido utilizar una instancia de Azure Cache for Redis existente para alojar la caché de salida de su microservicio de aplicación web. Debe asegurarse de que el servicio de la aplicación web se conecta a la instancia correcta de Azure Cache for Redis.

En esta unidad, aprenderá a modificar las cadenas de conexión a los servicios de respaldo en el archivo de manifiesto de .NET Aspire.

Generar un archivo de manifiesto utilizando la CLI .NET

Durante el desarrollo local y la depuración, .NET Aspire no crea un archivo de manifiesto. A la hora de la implementación, .NET debe describir el contenido de la solución .NET Aspire, incluidos sus microservicios, servicios de respaldo y configuración. El archivo de manifiesto cumple esta función. Describe la solución en formato JSON.

Para crear el archivo de manifiesto, tanto Visual Studio como Azure Developer CLI ejecutan un comando .NET CLI run con un objetivo específico. Puede ejecutar manualmente el mismo comando para crear su propio archivo de manifiesto de la siguiente manera:

dotnet run --project eShop.AppHost\eShop.AppHost.csproj `
    --publisher manifest `
    --output-path ../aspire-manifest.json

Nota:

Asegúrese de especificar el proyecto host de la aplicación con la opción --project.

El comando produce una salida similar a este texto:

Building...
info: Aspire.Hosting.DistributedApplication[0]
      Aspire version: 8.0.1+a6e341ebbf956bbcec0dda304109815fcbae70c9
info: Aspire.Hosting.Publishing.ManifestPublisher[0]
      Published manifest to: C:\repos\eShop\aspire-manifest.json

También puede utilizar un perfil de ejecución para ejecutar el comando dotnet. Un perfil de lanzamiento es un grupo de parámetros que configura un proyecto .NET cuando se ejecuta. Por ejemplo, la plantilla .NET Aspire Starter crea estos perfiles de lanzamiento:

"profiles": {
  "https": {
    "commandName": "Project",
    "dotnetRunMessages": true,
    "launchBrowser": true,
    "applicationUrl": "https://localhost:17170;http://localhost:15281",
    "environmentVariables": {
      "ASPNETCORE_ENVIRONMENT": "Development",
      "DOTNET_ENVIRONMENT": "Development",
      "DOTNET_DASHBOARD_OTLP_ENDPOINT_URL": "https://localhost:21147",
      "DOTNET_RESOURCE_SERVICE_ENDPOINT_URL": "https://localhost:22239"
    }
  },
  "http": {
    "commandName": "Project",
    "dotnetRunMessages": true,
    "launchBrowser": true,
    "applicationUrl": "http://localhost:15281",
    "environmentVariables": {
      "ASPNETCORE_ENVIRONMENT": "Development",
      "DOTNET_ENVIRONMENT": "Development",
      "DOTNET_DASHBOARD_OTLP_ENDPOINT_URL": "http://localhost:19197",
      "DOTNET_RESOURCE_SERVICE_ENDPOINT_URL": "http://localhost:20233"
    }
  }
}

Agregue un perfil de lanzamiento para crear un archivo de manifiesto con código JSON similar a este texto:

"profiles": {
  "generate-manifest": {
    "commandName": "Project",
    "launchBrowser": false,
    "dotnetRunMessages": true,
    "commandLineArgs": "--publisher manifest --output-path aspire-manifest.json"
  }
}

En Visual Studio, puede elegir el perfil de generación de manifiesto al iniciar la depuración. En la línea de comandos, utilice la opción --launch-profile:

dotnet run --launch-profile generate-manifest

Formato del archivo de manifiesto

El manifiesto es un archivo JSON con un único elemento de nivel superior llamado resources. Dentro de ese objeto se encuentra un objeto para cada microservicio y servicio de respaldo. Para cada uno de estos objetos, la configuración incluye cadenas de conexión, variables de entorno y nombres de imagen de contenedor.

Este es un manifiesto de ejemplo para la plantilla .NET Aspire Starter sin modificaciones. Un tipo de contenido duplicado:

{
  "resources": {
    "cache": {
      "type": "container.v0",
      "connectionString": "{cache.bindings.tcp.host}:{cache.bindings.tcp.port}",
      "image": "docker.io/library/redis:7.2",
      "bindings": {
        "tcp": {
          "scheme": "tcp",
          "protocol": "tcp",
          "transport": "tcp",
          "targetPort": 6379
        }
      }
    },
    "apiservice": {
      "type": "project.v0",
      "path": "AspireStarter.ApiService/AspireStarter.ApiService.csproj",
      "env": {
        "OTEL_DOTNET_EXPERIMENTAL_OTLP_EMIT_EXCEPTION_LOG_ATTRIBUTES": "true",
        "OTEL_DOTNET_EXPERIMENTAL_OTLP_EMIT_EVENT_LOG_ATTRIBUTES": "true",
        "OTEL_DOTNET_EXPERIMENTAL_OTLP_RETRY": "in_memory",
        "ASPNETCORE_FORWARDEDHEADERS_ENABLED": "true"
      },
      "bindings": {
        "http": {
          "scheme": "http",
          "protocol": "tcp",
          "transport": "http"
        },
        "https": {
          "scheme": "https",
          "protocol": "tcp",
          "transport": "http"
        }
      }
    },
    "webfrontend": {
      "type": "project.v0",
      "path": "AspireStarter.Web/AspireStarter.Web.csproj",
      "env": {
        "OTEL_DOTNET_EXPERIMENTAL_OTLP_EMIT_EXCEPTION_LOG_ATTRIBUTES": "true",
        "OTEL_DOTNET_EXPERIMENTAL_OTLP_EMIT_EVENT_LOG_ATTRIBUTES": "true",
        "OTEL_DOTNET_EXPERIMENTAL_OTLP_RETRY": "in_memory",
        "ASPNETCORE_FORWARDEDHEADERS_ENABLED": "true",
        "ConnectionStrings__cache": "{cache.connectionString}",
        "services__apiservice__http__0": "{apiservice.bindings.http.url}",
        "services__apiservice__https__0": "{apiservice.bindings.https.url}"
      },
      "bindings": {
        "http": {
          "scheme": "http",
          "protocol": "tcp",
          "transport": "http",
          "external": true
        },
        "https": {
          "scheme": "https",
          "protocol": "tcp",
          "transport": "http",
          "external": true
        }
      }
    }
  }
}

Cadenas de conexión y referencias vinculantes

En el ejemplo del manifiesto, hay tres recursos:

  • webfrontend: Este recurso es el microservicio que presenta una interfaz web a los clientes.
  • apiservice: Este recurso es la API REST a la que webfrontend llama. En el modelo, esta llamada es para obtener datos meteorológicos.
  • cache: Este recurso es la caché Redis, utilizada para optimizar el rendimiento del microservicio webfrontend.

Tenga en cuenta que cada uno de los tres recursos incluye una sección bindings que especifica los protocolos que puede utilizar para conectarse a ese recurso.

En el archivo Program.cs del host de la aplicación, el proyecto webfrontend depende de cache y apiservice:

var cache = builder.AddRedis("cache");

var apiService = builder.AddProject<Projects.AspireStarter_ApiService>("apiservice");

builder.AddProject<Projects.AspireStarter_Web>("webfrontend")
    .WithExternalHttpEndpoints()
    .WithReference(cache)
    .WithReference(apiService);

En el archivo de manifiesto, estas dependencias se expresan como variables de entorno:

"env": {
  "ConnectionStrings__cache": "{cache.connectionString}",
  "services__apiservice__http__0": "{apiservice.bindings.http.url}",
  "services__apiservice__https__0": "{apiservice.bindings.https.url}"
}

Diagrama que muestra cómo las dependencias de un proyecto .NET Aspire generan referencias en un archivo de manifiesto.

Las dependencias utilizan cadenas de marcadores de posición que hacen referencia a la estructura del archivo de manifiesto. Por ejemplo, la tercera dependencia hace referencia a la vinculación HTTPS del servicio API:

Diagrama que muestra cómo se crean los marcadores de posición en un archivo de manifiesto .NET Aspire.

Saber más