Connect to flagd

⭐ Community Toolkit

This page describes how consuming apps connect to a flagd resource that’s already modeled in your AppHost. For the AppHost API surface — adding a flagd resource, file sync, port configuration, log levels, and health checks — see flagd Hosting integration.

When you reference a flagd resource from your AppHost, Aspire injects the connection information into the consuming app as environment variables. There isn’t a dedicated Aspire client package for flagd, so each app configures a stable OpenFeature SDK and flagd provider directly.

Connection properties

Aspire exposes each property as an environment variable named [RESOURCE]_[PROPERTY]. For instance, the Uri property of a resource called flagd becomes FLAGD_URI.

The flagd resource exposes the following connection properties:

Property Name	Description
Host	The hostname or IP address of the flagd server
Port	The port number of the flagd HTTP/gRPC endpoint
Uri	The endpoint URI, with the format http://{Host}:{Port}

For a resource named flagd, Aspire injects both ConnectionStrings__flagd and individual connection properties:

ConnectionStrings__flagd=http://localhost:8013
FLAGD_HOST=localhost
FLAGD_PORT=8013
FLAGD_URI=http://localhost:8013

Connect from your app

Pick the language your consuming app is written in. Each example assumes your AppHost adds a flagd resource named flagd and references it from the consuming app.

C#

For C# apps, use the OpenFeature SDK with the flagd provider. Install the 📦 OpenFeature.Providers.Flagd NuGet package in the consuming project:

.NET CLI

.NET CLI — Add OpenFeature.Providers.Flagd package

dotnet add package OpenFeature.Providers.Flagd

Program.cs (C# file-based app)

Program.cs

#:package OpenFeature.Providers.Flagd@*

PackageReference (*.csproj)

XML — Add OpenFeature.Providers.Flagd package reference

<PackageReference Include="OpenFeature.Providers.Flagd" Version="*" />

In Program.cs, read the Aspire-injected connection string and register the flagd provider with the OpenFeature SDK:

Program.cs

using OpenFeature;
using OpenFeature.Providers.Flagd;

var connectionString = builder.Configuration.GetConnectionString("flagd");

await OpenFeature.Api.Instance.SetProviderAsync(
    new FlagdProvider(new Uri(connectionString!)));

Tip

The connection name passed to GetConnectionString must match the flagd resource name from the AppHost. For more information, see Add flagd resource.

Obtain a client and evaluate feature flags:

ExampleService.cs

var flagClient = OpenFeature.Api.Instance.GetClient();

var welcomeBanner = await flagClient.GetBooleanValueAsync(
    "welcome-banner",
    defaultValue: false);

var backgroundColor = await flagClient.GetStringValueAsync(
    "background-color",
    defaultValue: "#000000");

Read environment variables in C#

If you prefer to read the connection URI from environment variables directly rather than through IConfiguration:

Program.cs

using OpenFeature;
using OpenFeature.Providers.Flagd;

var uri = Environment.GetEnvironmentVariable("FLAGD_URI");

await OpenFeature.Api.Instance.SetProviderAsync(
    new FlagdProvider(new Uri(uri!)));

For more information, see the OpenFeature .NET SDK documentation and the flagd .NET provider.

Go

Install the OpenFeature Go SDK and flagd provider:

Terminal

go get github.com/open-feature/go-sdk/openfeature
go get github.com/open-feature/go-sdk-contrib/providers/flagd/pkg

Read the injected environment variable, parse the URI, and configure the provider:

main.go

package main

import (
    "context"
    "net/url"
    "os"
    "strconv"

    "github.com/open-feature/go-sdk/openfeature"
    flagd "github.com/open-feature/go-sdk-contrib/providers/flagd/pkg"
)

func main() {
    // Read the Aspire-injected connection URI
    uri, err := url.Parse(os.Getenv("FLAGD_URI"))
    if err != nil {
        panic(err)
    }

    port, _ := strconv.Atoi(uri.Port())

    provider, err := flagd.NewProvider(
        flagd.WithHost(uri.Hostname()),
        flagd.WithPort(uint16(port)),
    )
    if err != nil {
        panic(err)
    }

    openfeature.SetProvider(provider)

    client := openfeature.NewClient("app")

    enabled, _ := client.BooleanValue(
        context.Background(),
        "welcome-banner",
        false,
        openfeature.NewEvaluationContext("", nil),
    )
    _ = enabled
}

For more information, see the OpenFeature Go SDK and the flagd Go provider.

Python

Install the OpenFeature SDK and flagd provider:

Terminal

pip install openfeature-sdk openfeature-provider-flagd

Read the injected environment variable, parse the URI, and configure the provider:

app.py

import os
from urllib.parse import urlparse
from openfeature import api
from openfeature.contrib.provider.flagd import FlagdProvider

# Read the Aspire-injected connection URI
uri = urlparse(os.getenv("FLAGD_URI"))

api.set_provider(FlagdProvider(
    host=uri.hostname,
    port=uri.port,
))

client = api.get_client()

welcome_banner = client.get_boolean_value("welcome-banner", False)
background_color = client.get_string_value("background-color", "#000000")

For more information, see the OpenFeature Python SDK and the flagd Python provider.

TypeScript

Install the OpenFeature Server SDK and flagd provider:

Terminal

npm install @openfeature/server-sdk @openfeature/flagd-provider

Read the injected environment variable, parse the URI, and configure the provider:

index.ts

import { OpenFeature } from '@openfeature/server-sdk';
import { FlagdProvider } from '@openfeature/flagd-provider';

// Read the Aspire-injected connection URI
const uri = new URL(process.env.FLAGD_URI!);

OpenFeature.setProvider(
  new FlagdProvider({
    host: uri.hostname,
    port: Number(uri.port),
  })
);

const client = OpenFeature.getClient();

const welcomeBanner = await client.getBooleanValue('welcome-banner', false);
const backgroundColor = await client.getStringValue(
  'background-color',
  '#000000'
);

For more information, see the OpenFeature JavaScript SDK and the flagd Node.js provider.

Use OFREP provider

As an alternative to the native provider, you can connect to flagd using the OFREP (OpenFeature Remote Evaluation Protocol). OFREP is a standardized HTTP/REST-based protocol for remote feature flag evaluation, making it language-agnostic and well-suited for polyglot environments.

Install the OFREP provider

Install the 📦 OpenFeature.Providers.Ofrep NuGet package in the client-consuming project:

dotnet add package OpenFeature.Providers.Ofrep

Configure the AppHost

In your AppHost, retrieve the OFREP endpoint from the flagd resource and pass it to your consuming project as an environment variable:

C#

AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var flagd = builder.AddFlagd("flagd")
    .WithBindFileSync("./flags/");

var ofrepEndpoint = flagd.GetEndpoint("ofrep");

builder.AddProject<Projects.ExampleProject>("api")
    .WaitFor(flagd)
    .WithEnvironment("OFREP_ENDPOINT", ofrepEndpoint);

// After adding all resources, run the app...
builder.Build().Run();

TypeScript

apphost.mts

import { createBuilder } from './.aspire/modules/aspire.mjs';

const builder = await createBuilder();

const flagd = await builder.addFlagd('flagd');
await flagd.withBindFileSync('./flags/');

const ofrepEndpoint = await flagd.ofrepEndpoint();

const api = await builder.addProject(
  'api',
  '../ExampleProject/ExampleProject.csproj'
);
await api.waitFor(flagd);
await api.withEnvironment('OFREP_ENDPOINT', ofrepEndpoint);

await builder.build().run();

Configure the client

In the Program.cs file of your client-consuming project, register the OpenFeature SDK with the OFREP provider using dependency injection:

using OpenFeature.Providers.Ofrep;
using OpenFeature.Providers.Ofrep.DependencyInjection;

builder.Services.AddOpenFeature(featureBuilder =>
{
    featureBuilder.AddOfrepProvider(options =>
    {
        // Leave BaseUrl unset so the provider falls back to the
        // OFREP_ENDPOINT environment variable injected by the AppHost.
    });
});

The OFREP provider automatically reads the OFREP_ENDPOINT environment variable to discover the flagd OFREP endpoint. You can then evaluate feature flags by injecting IFeatureClient:

using OpenFeature;

app.MapGet("/", async (IFeatureClient flagClient) =>
{
    var welcomeBanner = await flagClient.GetBooleanValueAsync(
        "welcome-banner",
        defaultValue: false);

    var backgroundColor = await flagClient.GetStringValueAsync(
        "background-color",
        defaultValue: "#000000");

    return Results.Ok(new { welcomeBanner, backgroundColor });
});

For more information on the OFREP specification, see the OFREP specification.