dotnet / docs-aspire

This repository contains .NET Aspire documentation.
https://learn.microsoft.com/dotnet/aspire
MIT License
80 stars 105 forks source link

Integration docs promote misconception that Aspire is .Net only. #1763

Open afscrome opened 1 month ago

afscrome commented 1 month ago

Describe the issue or suggestion

When trying to promote use of aspire within my organisation, I hit the same two misconceptions over and over again

  1. We can't use Aspire as we have components that aren't .Net based
  2. Various forms of "We can't / don't want to use the client integration packages.
    • If we only use aspire integration for local dev, why are any aspire packages being shipped to prod
    • Aspire's opinionated way doesn't work with us.

The integration docs help encourage these misconceptions. For example the SQL Integration page doesn't have any mention of how to use SQL in non .Net languages.

I'd like to see each of the integration pages include a section on how to use the integrations "raw" within the client - this would apply. For example with SQL, explain how the following could be used to integration with non .Net apps, or for .Net apps that don't fir the .Net Client Integration package opinions.

var app = builder.AddExecutable("app", "whatever", ".")
    .WithReference(db) // connection string becomes the environment variable "ConnectionStrings_{db.Name}"
    .WithEnvironment(c =>
    {
        c.EnvironmentVariables["sql_connectionString"] = db.Resource.ConnectionStringExpression;

        c.EnvironmentVariables["sql_server"] = sql.Resource.PrimaryEndpoint.Property(EndpointProperty.Host);
        c.EnvironmentVariables["sql_port"] = sql.Resource.PrimaryEndpoint.Property(EndpointProperty.Port);
        c.EnvironmentVariables["sql_username"] = "sa";
        c.EnvironmentVariables["sql_password"] = sql.Resource.PasswordParameter;
        c.EnvironmentVariables["sql_database"] = db.Resource.Name;
    });

Which results in the environment variables:

image
davidfowl commented 1 month ago

Before addressing how we handle usage in non .NET contexts (which is pretty bespoke at the moment), I think we could mention more about how hosting integrations can be used with any type of application in the overview

https://learn.microsoft.com/en-us/dotnet/aspire/fundamentals/integrations-overview#hosting-integrations

Maybe this could lead to a more standard way of exposing properties across these resources in order to use them outside. I’m a bit hesitant to add other languages to the docs (outside of the ones we have integrations for) without more complete end to end samples and testing