what is that kind of instance name being omitted?

Question

I have a question about this "shortcut" found in the ASP.NET 5 template:

public Startup(IHostingEnvironment env, IApplicationEnvironment appEnv)
    {          
        var builder = new ConfigurationBuilder(appEnv.ApplicationBasePath)
            .AddJsonFile("config.json")
            .AddJsonFile($"config.{env.EnvironmentName}.json", optional: true);

The last two lines are only method calls, obviously of a builder. I think this is 100% the same:

var builder = new ConfigurationBuilder(appEnv.ApplicationBasePath);
builder.AddJsonFile("config.json");
builder.AddJsonFile($"config.{env.EnvironmentName}.json", optional: true);

What do you call this syntax where the object name is omitted? Is it only possible when calling NEW/ctor? Can someone point me to that part of C# language definition?

I've googled this, but cannot find the answer.

Edit: this question obviously is very similar to other method-chaining questions, if you already know the term, but my question wasn't meant to implement that, only to use it correctly and get the correct documentation of it. may be this question is nice for being googled, as I used well known source code from VS templates.

Both of your code samples are effectively the same... Google for: c# chaining — Paul Zahra, Oct 19 '15 at 15:16
WOW!! Thanks to all that answered so fast and perfectly matching to my Q. I'll need to dig in some of the links, as I'm quite a newbie. No idea which of the answer to pick as best? please vote for it! — Falco Alexander, Oct 19 '15 at 15:26

David · Accepted Answer · 2015-10-19T15:32:03.473

I've heard this concept referred to as "method chaining" or "fluent syntax" (depending on the semantics of the methods). You see it a lot in things like jQuery, for example. The idea is simply that a method on an object will modify that object and return the modified version. So another method can be immediately called on the return value, and so on.

The code isn't "omitting" the builder variable. It's just that new ConfigurationBuilder(appEnv.ApplicationBasePath) returns a ConfigurationBuilder object. And when you call .AddJsonFile() on a ConfigurationBuilder, it modifies the object and then returns it again. So you can chain as many calls to that as you like and still end up with the object.

Technically that first example is all one line of code. The carriage returns are for readability. (Note there is no semicolon until the end.) C# simply ignores whitespace and continues to process the code until the end of the statement (a semicolon) is reached. Contrast this with languages like VB where a carriage return is part of the language and itself terminates a statement.

thx! this seems to be a like pattern which is implicitly done with C# and used a lot with LINQ? how comes there is nearly nothing being found even with the right term inside MSDN sites as reference? only indirectly by using LINQ there are some. most explanations are 3rd party. — Falco Alexander, Oct 19 '15 at 15:59
@FalcoAlexander: It's not really "implicitly" done. Though you are correct that LINQ also makes heavy use of this concept. At its core, it's nothing more than a method which returns the object on which it operates. In LINQ it's done with static extension method which return the `this` parameter, but instance methods can accomplish the same thing by returning `this` itself. — David, Oct 19 '15 at 16:01

score 1 · Answer 2 · answered Oct 19 '15 at 15:15

This is called Method Chaining.

The principle is that you return a reference to this, so that another method on the same object can be called directly.

This can be done on every method that does not return a value, but is mostly used on "setup" or "configuration" functions, like in your example.

score 1 · Answer 3 · edited May 23 '17 at 12:23

1

Take at look here: you can see how a class looks that supports method chaining (call methods after each other in one statement)

Fluent Interfaces - Method Chaining

"All you need to do is create an object whose methods always return the object itself." Afterwards you can "chain" the mathods (complete example in the link provided)

edited May 23 '17 at 12:23

Community

1
1

answered Oct 19 '15 at 15:17

Marc Wittmann

2,286
2
28
41

score 1 · Answer 4 · answered Oct 19 '15 at 15:18

1

You can achieve this your self really easy by simply returning this

IBuilder AddJsonFile(string path) {
 // some code
 return this;
}

answered Oct 19 '15 at 15:18

Calin

6,661
7
49
80

what is that kind of instance name being omitted?

4 Answers4