Init-parameters: methods with initializers

[amal-stack]

Motivation

C# offers a convenient syntax for object and collection initialization, by adding a set of curly braces after a constructor invocation. This post-construction initializer list can:

1. Set properties on the created instance.

HttpClient client = new()
{
    BaseAddress = new Uri("https://example.com"),
};

2. Set indexers on the created instance.

Dictionary<int, string> dict = new() 
{
    [0] = "Zero",
};

3. Invoke Add methods on the created instance (if present as a member or extension).

Dictionary<int, string> dict = new() 
{
    { 0, "Zero" },
};

In this case, this is called a collection initializer instead; C# defines it as a distinct construct altogether and it cannot be combined with object initialization. (it's either Add calls (collection initializer) or property/indexer setting (object initializer)).

4. Do all of the above for existing instances of nested objects of the created instance (This is different from assigning a nested object in the list with a new instance because in this case, the nested object is already created and may even be read-only, but still a nested set of curly braces can do 1 to 3 above).
   For example, adding headers via the DefaultRequestHeaders in an HttpClient:

var client = HttpClient () 
{
    DefaultRequestHeaders =     // this is a read-only property 
   {
       { "Header1", "Value1", },      // Calls Add on the existing instance
       { "Header2", "Value2", },     
   }
}

With required and init-only properties, their use is even more encouraged and enforced. Unfortunately, they can only appear just after a constructor invocation and cannot be used anywhere else. They would be especially useful if they were allowed to appear after a method invocation. This would bring in many benefits like concise factory methods and better DSL capabilities just to name a few.

Solution: init-parameters

Introduce a new parameter modifier, called init. When a method has an init parameter, the caller can provide its value using an initializer block, similar to how constructors work.

class Person
{
    async Task<Person> Create(init PersonInfo info) 
    {

    }
}

where PersonInfo is the following:

class PersonInfo 
{
    public required string FirstName { get; init; }
    public required string LastName { get; init; }
    public int? Age { get; set; }
}

Since the info parameter in the Create method above is marked with init, it can be called as:

Person.Create() 
{
   FirstName = "John",
   LastName = "Doe"
};

Or with the parentheses omitted when no other parameters exist:

Person.Create
{
   FirstName = "John",
   LastName = "Doe"
};

The compiler can replace this call with a parameterless constructor invocation of the init parameter followed by the provided initializer list:

Person.Create(
  new PersonInfo 
  {
     FirstName = "John",
     LastName = "Doe"
  }
);

Other parameters can also exist for a method using init parameters:

async Task<Person> Create(int id, string source, init PersonInfo info) 
{

}

which can be invoked as:

Person.Create(42, "Database") 
{
     FirstName = "John",
     LastName = "Doe"
};

We can also allow collection types or types with an Add method to be marked as an init parameter:

void SetHeaders(init Dictionary<string, string> headers) 
{
}

which can then be invoked as:

SetHeaders 
{
    { "H1", "V1" },
    { "H2", "V2"  },
};

Rules

• Any type that has a parameterless constructor and can have an initializer list can be marked as an init parameter.
• The rules of required and init-only properties can be the same as other initialization lists, as per the properties declared in the type that is marked as an init parameter.
• There can only be one init parameter per method and it should preferably be the last one.
• Constructors cannot have init parameters (they already support initializer lists).

Benefits

1. Factory methods can use initializer lists just like constructors, even if they are async and return a Task<T>, a subtype or any type.

2. Provides better DSL capabilities. For instance, consider the following:

AddSomeService(options => {
    options.Prop1 = "V1";
    options.Prop2 = 2;
    options.SomeList.Add(100);
    options.SomeList.Add(200);
})

This can be rewritten as:

AddSomeService 
{
   Prop1 = "V1",
   Prop2 = 2,
   SomeList = { 100, 200 }
};

3. Provides a way to support parameters that are always "named":
   C# currently has named parameters but specifying names are completely optional and there is no way to force the client to always specify parameter names. Languages like Python and Dart provide a syntax for named-only parameters. Initializer lists provide a natural way to achieve required named parameters as the property names are always required.

4. Allows the notion of "optional" parameters: since non-required properties need not be set.

5. Improved consistency with modern object modeling using required and init.

Real-world examples

Here are some examples of APIs where incorporating init parameters can improve readability and user experience:

1. Json serialization

Before:

JsonSerializer.Serialize(obj, new JsonSerializerOptions
{
    PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
    WriteIndented = true
});

The JsonSerializerOptions can be marked init for more concise syntax.
After:

JsonSerializer.Serialize(obj)
{
    PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
    WriteIndented = true
};

2. Service collection extensions

Before:

builder.services.AddAuthentication(options =>
{
    options.DefaultScheme = JwtBearerDefaults.AuthenticationScheme;
    options.DefaultChallengeScheme = JwtBearerDefaults.AuthenticationScheme;
    options.RequireAuthenticatedByDefault = false;
}
.AddJwtBearer("some-scheme", jwtOptions =>
{
	jwtOptions.MetadataAddress = builder.Configuration["Api:MetadataAddress"];
	jwtOptions.Authority = builder.Configuration["Api:Authority"];
	jwtOptions.Audience = builder.Configuration["Api:Audience"];
	jwtOptions.TokenValidationParameters = new TokenValidationParameters
	{
		ValidateIssuer = true,
		ValidateAudience = true,
		ValidateIssuerSigningKey = true,
		ValidAudiences = builder.Configuration.GetSection("Api:ValidAudiences").Get<string[]>(),
		ValidIssuers = builder.Configuration.GetSection("Api:ValidIssuers").Get<string[]>()
	};

	jwtOptions.MapInboundClaims = false;
});

After:

builder.services.AddAuthentication
{
    DefaultScheme = JwtBearerDefaults.AuthenticationScheme,
    DefaultChallengeScheme = JwtBearerDefaults.AuthenticationScheme,
    RequireAuthenticatedByDefault = false,
}
.AddJwtBearer("some-scheme")
{
    MetadataAddress = builder.Configuration["Api:MetadataAddress"],
    Authority = builder.Configuration["Api:Authority"],
    Audience = builder.Configuration["Api:Audience"],
    TokenValidationParameters = new TokenValidationParameters
    {
	ValidateIssuer = true,
	ValidateAudience = true,
	ValidateIssuerSigningKey = true,
	ValidAudiences = builder.Configuration.GetSection("Api:ValidAudiences").Get<string[]>(),
	ValidIssuers = builder.Configuration.GetSection("Api:ValidIssuers").Get<string[]>()
    },
    MapInboundClaims = false,
};

3. HttpClient configuration

Before:

var client = httpClientFactory.CreateClient();
client.BaseAddress = new Uri("https://api.example.com");
client.DefaultRequestHeaders.Add("X-API-Version", "v2");
client.DefaultRequestHeaders.Add("User-Agent", "MyApp/1.0");
client.Timeout = TimeSpan.FromSeconds(30);

After:

var client = httpClientFactory.CreateClient
{
    BaseAddress = new Uri("https://api.example.com"),
    DefaultRequestHeaders = {
        { "X-API-Version", "v2" },
        { "User-Agent", "MyApp/1.0" }
    },
    Timeout = TimeSpan.FromSeconds(30)
};

Potential Challenges

1. Overload Ambiguity

How would method overloads that differ only on the type of their init parameters be handled?
Consider the following case where two Create overloads exist:

class Button 
{
  static Button Create(init ButtonStyle) {..}
  static Button Create(int Size) {..}
}
class ButtonStyle 
{
  public required Color Foreground { get; init; }
  public required Color Background { get; init; }
}
class Size
{
  public required double Width { get; init; }
  public required double Height { get; init; }
}

Now at the call site:

var button = Button.Create 
{
     // does this create a ButtonStyle or Size
};

Solution:
In such cases where an ambiguity exists, the init parameter can be explicitly supplied:

var button = Button.Create(new ButtonStyle
{
    Foreground = Colors.Primary, Background = Colors.PrimaryBg,
});

2. Lambda/delegate considerations

The nested closure pattern is extremely common and heavily used all over .NET. For instance, see the 2nd example in the "Real world examples" section. To support the "after" variant, the method signature, instead of this:

AuthenticationBuilder AddAuthentication(this IServiceCollection services, Action<AuthenticationOptions> configureOptions) 
{
}

the method signature will have to be this:

AuthenticationBuilder AddAuthentication(this IServiceCollection services, init AuthenticationOptions options) 
{
}

Solution: init Action<T> parameters. Since, accepting an Action delegate is a common pattern, we could allow a method defined like this:

AuthenticationBuilder AddAuthentication(this IServiceCollection services, Action<AuthenticationOptions> configureOptions) {}

to be called as:

AddAuthentication
{
    DefaultScheme = JwtBearerDefaults.AuthenticationScheme,
    DefaultChallengeScheme = JwtBearerDefaults.AuthenticationScheme,
    RequireAuthenticatedByDefault = false,
})

where the property assignments set the properties on the parameter passed to the Action delegate instead of creating a fresh instance. So, in case of an init Action<T> parameter, the above is equivalent to:

AddAuthentication(options =>
{
    options.DefaultScheme = JwtBearerDefaults.AuthenticationScheme;
    options.DefaultChallengeScheme = JwtBearerDefaults.AuthenticationScheme;
    options.RequireAuthenticatedByDefault = false;
}

Allowing this also brings in other advantages, like allowing modification of an existing object instead of creating a fresh object using the parameterless constructor of the init parameter. This useful if we want to allow overriding values or configuring a partially initialized object.
See also: #2781 (Kotlin/Swift style trailing closure blocks)

3. Requires a type

This syntax requires introducing a new type that will be marked as the init parameter.

Solution: We could allow something like an inline type declaration:

async Task<Person> Create(init T info)  
    where T : {required string FirstName, required string LastName, int? Age}
{
}

4. Generic init parameters

Should generic init parameters be allowed?

5. Using dynamic

We could allow dynamic/object init-parameters which could allow passing an anonymous type in an initializer list.

// dynamic init: allows passing an anonymous type
Person Create(init dynamic info) {..}

// Usage
Create { FirstName = "John", LastName = "Doe", ArbitraryProperty = "Value" };