microsoft / microsoft/aspire

Make `ReferenceExpressionBuilder` Fluent

Open
#7,598 0 comments 0 reactions 0 assignees View on GitHub
area-app-model
Dominant language
C#
Stars
6.3k
Forks
991
Avg merge
2d 15h
Merged PRs (30d)
196

Description

## Background and Motivation

`ReferenceExpressionBuilder` is a really useful way of building up a longer reference expression when you may need to encode multiple distinct values into a single environment variable.

```cs
var expression = new ReferenceExpressionBuilder();
expression.AppendLiteral("user=admin;")
expression.Append($"host={endpoint.Property(EndpointProperty.Host)};")
expression.Append($"port={endpoint.Property(EndpointProperty.Port)};")
return expression.Build();
```

Whilst the API works, it would be a lot more convenient if the API could used in a fluent manner, simplifying the above to:

```cs
return new ReferenceExpressionBuilder();
.AppendLiteral("user=admin;")
.Append($"host={endpoint.Property(EndpointProperty.Host)};")
.Append($"port={endpoint.Property(EndpointProperty.Port)};")
.Build();
```

## Proposed API

```diff
namespace Aspire.Hosting.ApplicationModel;
public class ReferenceExpressionBuilder
{
- public void Append([InterpolatedStringHandlerArgument("")] in ReferenceExpressionBuilderInterpolatedStringHandler handler)
+ public ReferenceExpressionBuilder Append([InterpolatedStringHandlerArgument("")] in ReferenceExpressionBuilderInterpolatedStringHandler handler)
- public void AppendLiteral(string value)
+ public ReferenceExpressionBuilder AppendLiteral(string value)
- public void AppendFormatted(string? value)
+ public ReferenceExpressionBuilder AppendFormatted(string? value)
- public void AppendFormatted(T valueProvider) where T : IValueProvider, IManifestExpressionProvider
+ public ReferenceExpressionBuilder AppendFormatted(T valueProvider) where T : IValueProvider, IManifestExpressionProvider
}
```

This changes each `void` method into returning `ReferenceExpressionBuilder`. Each method's implementation would remain the same as the old version but with the addition of `return this;` at the end of each method to support a fluent api.

## Usage Examples

```cs
return new ReferenceExpressionBuilder();
.Append($"foo,")
.Append($"bar")
.Build();
```

## Alternative Designs

No alternative designs considered. This new design mirrors `StringBuilder`'s fluent API.

## Risks

This is an API breaking change by changing the method return types from void to `ReferenceExpressionBuilder `

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.