C# Programming guide: Top-level statements #23234

tdykstra · 2021-03-09T17:59:45Z

Fixes #20586

Youssef1313 · 2021-03-09T18:50:42Z

docs/csharp/programming-guide/main-and-command-args/how-to-display-command-line-arguments.md

 helpviewer_keywords: 
  - "command-line arguments [C#], displaying"
 ms.assetid: b8479f2d-9e05-4d38-82da-2e61246e5437
 ---
 # How to display command-line arguments (C# Programming Guide)

-Arguments provided to an executable on the command line are accessible through an optional parameter to `Main`. The arguments are provided in the form of an array of strings. Each element of the array contains one argument. White-space between arguments is removed. For example, consider these command-line invocations of a fictitious executable:  
+Arguments provided to an executable on the command line are accessible in [top-level statements](top-level-statements.md) and through an optional parameter to `Main`. The arguments are provided in the form of an array of strings. Each element of the array contains one argument. White-space between arguments is removed. For example, consider these command-line invocations of a fictitious executable:  


Is "and" extra?

It was intentional, as these are two different options -- top-level statements (implicit Main) and explicit Main. But I'll change "and" to "or" as that may be clearer.

docs/csharp/programming-guide/main-and-command-args/index.md

...-guide/main-and-command-args/snippets/top-level-statements-1/top-level-statements (2).csproj

...ming-guide/main-and-command-args/snippets/top-level-statements-3/top-level-statements.csproj

Youssef1313 · 2021-03-09T18:56:08Z

docs/csharp/programming-guide/main-and-command-args/top-level-statements.md

@@ -0,0 +1,90 @@
+---
+title: "Top-level statements - C# Programming Guide"


The feature is also known as "simple programs" if I recall correctly. You may want to include this name for SEO purposes.

Where did you see this name?

Frequently used in Roslyn repo

For example:

https://github.com/dotnet/roslyn/blob/main/src/Compilers/CSharp/Portable/Symbols/Synthesized/SynthesizedSimpleProgramEntryPointSymbol.cs

https://github.com/dotnet/roslyn/issues?q=is%3Aopen+is%3Aissue+label%3A%22New+Language+Feature+-+Simple+Programs%22

Probably ask Roslyn team for guidance whether this name should be advertised in docs?

The public messaging has been consistently to call this feature "top-level statements," and with "simple programs" showing up only in the Roslyn repo, I think using that as an alternate feature name would be unnecessarily confusing, but I'll follow the lead of the top-level statements tutorial and work in the phrase "simple programs" into the text.

"Top level statements" is the official name. The product team followed our lead here to avoid the use of "simple". The goal is that programs that use "top level statements" need not be "simple". See FeatherApp for one example of possibilities.

Youssef1313 · 2021-03-09T18:58:17Z

docs/csharp/programming-guide/main-and-command-args/top-level-statements.md

+---
+# Top-level statements (C# Programming Guide)
+
+Starting in C# 9, you don't have to explicitly include a `Main` method in a console application project. Instead, you can use the *top-level statements* feature to minimize the code you have to write. In this case, the compiler provides an implicit class and `Main` method entry point for the application.


I personally lean towards using main without backticks instead of Main. Because the method the compiler generates isn't called Main, but <Main>$.

I think "implicit" clarifies the status of Main, but in this instance it will be clearer to repeat "implicit" directly before Main.

I don't think "implicit" resolves this. It could be implicit and called Main, but the compiler implementation decided it's called <Main>$.

And actually, from a compiler-point of view, it's not implicit at all (see discussion at dotnet/roslyn#48199), but it's okay to mention implicit for the purpose of this article I think?

As I mentioned in the other thread, I'll add an explanation that the actual generated name is an implementation detail.

docs/csharp/programming-guide/main-and-command-args/top-level-statements.md

tdykstra · 2021-03-09T22:55:41Z

@Youssef1313 Thanks for the preliminary review (this is still a draft PR) -- what do you think of my rewrite of the Implicit Main method signature section intro text? I also am considering removing this section as it's non-necessary background information. I added it thinking it might help to understand one aspect of what's going on behind the scenes.

BillWagner

This is excellent work @tdykstra

I had a few small comments, and then this is ready to merge.

Thanks again.

docs/csharp/programming-guide/classes-and-structs/methods.md

BillWagner · 2021-03-11T15:20:55Z

docs/csharp/programming-guide/main-and-command-args/main-return-values.md

@@ -17,7 +17,12 @@ It can also return an `int`:

 [!code-csharp[csProgGuideMain#13](~/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideMain/CS/Class3.cs#13)]

-If the return value from `Main` is not used, returning `void` allows for slightly simpler code. However, returning an integer enables the program to communicate status information to other programs or scripts that invoke the executable file. The return value from `Main` is treated as the exit code for the process. If `void` is returned from `Main`, the exit code will be implicitly `0`. The following example shows how the return value from `Main` can be accessed.
+If the return value from `Main` is not used, returning `void` allows for slightly simpler code. However, returning an integer enables the program to communicate status information to other programs or scripts that invoke the executable file.


Not related to your PR, but this article should include that Main can return Task or Task<int>.

If we don't add it now, we should make an issue for that.

Adding it now.

BillWagner · 2021-03-11T15:25:00Z

docs/csharp/programming-guide/main-and-command-args/top-level-statements.md

@@ -0,0 +1,90 @@
+---
+title: "Top-level statements - C# Programming Guide"


"Top level statements" is the official name. The product team followed our lead here to avoid the use of "simple". The goal is that programs that use "top level statements" need not be "simple". See FeatherApp for one example of possibilities.

BillWagner · 2021-03-11T15:26:07Z

docs/csharp/programming-guide/main-and-command-args/top-level-statements.md

+
+:::code language="csharp" source="snippets/top-level-statements-1/Program.cs":::
+
+Top-level statements let you write simple programs for small utilities such as Azure Functions and GitHub Actions. They also make it simpler for new C# programmers to get started learning and writing code.


This use of "simple programs" is fine because it does flow naturally with the concept. I like how you've done this Tom.

BillWagner · 2021-03-11T15:28:33Z

docs/csharp/programming-guide/main-and-command-args/top-level-statements.md

+
+> CS7022 The entry point of the program is global code; ignoring 'Main()' entry point.
+
+In a project with top-level statements, you can't use the [-main](../../language-reference/compiler-options/main-compiler-option.md) compiler option to select the entry point, even if the project has one or more `Main` methods.


Note for me, depending on how soon we merge this: I'm update the options section to use the new MSBuild properties rather than the csc spellings. I'll have to update his depending on the order of merging. See #22797 for the work in progress.

BillWagner · 2021-03-11T15:30:14Z

docs/csharp/programming-guide/main-and-command-args/top-level-statements.md

+
+The compiler generates a method to serve as the program entry point for a project with top-level statements. The name of this method isn't actually `Main`, it's an implementation detail that your code can't reference directly. The signature of the method depends on whether the top-level statements contain the `await` keyword or the `return` statement. The following table shows what the method signature would look like, using the method name `Main` in the table for convenience.
+
+| Top-level code contains| Implicit `Main` signature                    |


I like this table. See my previous comment about the return value of Main. Adding this table there would be perfect.

Adding a slightly modified table to both the return value and command-line args docs.

BillWagner · 2021-03-11T15:31:18Z

docs/csharp/programming-guide/main-and-command-args/top-level-statements.md

+## C# language specification
+
+[!INCLUDE[CSharplangspec](~/includes/csharplangspec-md.md)]
+


I'd add a link to the top level statements speclet. The link would be ~/_csharplang/proposals/csharp-9.0/top-level-statements.md

This note is important, and is added to a file that will be deleted in this PR.

Co-authored-by: Bill Wagner <wiwagn@microsoft.com>

docs/csharp/programming-guide/main-and-command-args/top-level-statements.md

…to toplevel

…statements.md Co-authored-by: Youssef Victor <youssefvictor00@gmail.com>

…to toplevel

This note is important, and is added to a file that will be deleted in this PR.

* Consolidate how to set options Move all information pertaining to how to set compiler options into the index topic for this section. fix markdown lint warning * Consolidate optimizations section remove links to old content * finish the output section. Update listed-by-category.md * finish the input section * first pass at the resources section * Finish the code generation section * Add errors and warning sections. * Finish the language section. * Finish the security section. * Finish Miscellaneous section. * first pass at advanced session is finished 2nd pass through security. * update the miscellaneous section * finish the consolidation of the advanced section * add info on missing options * Finish the grammar check. * clean links in this folder. * Add note from #23234 This note is important, and is added to a file that will be deleted in this PR. * update links to compiler options area Most of these updates were straightforward substitutions of the new option for the old. There are a few exceptions: - Some of the links were from Visual Basic content, but the destination was C# content. Where possible, the link changed to the appropriate VB equivalent. - The displayed hyperlink text was not changed for the F# links. - Some warning and error messages only applied when the command line (older) syntax was used. In those cases, the link was updated, but the displayed text remained the same. - A small number of links were to options no longer supported. These were from error messages for those options. The corresponding supported option was linked in a note about updating. * fix bugs in this section. * edit descriptions and introductions * Final review * Remove extra XML tag. * Apply suggestions from code review Co-authored-by: Tom Dykstra <tdykstra@microsoft.com> * Update docs/csharp/language-reference/compiler-options/advanced.md Co-authored-by: Tom Dykstra <tdykstra@microsoft.com> * Update docs/csharp/language-reference/compiler-options/advanced.md Co-authored-by: Tom Dykstra <tdykstra@microsoft.com> * Update docs/csharp/language-reference/compiler-options/advanced.md Co-authored-by: Tom Dykstra <tdykstra@microsoft.com> * respond to feedback. * markdown lint error. Co-authored-by: Tom Dykstra <tdykstra@microsoft.com>

tdykstra added 4 commits March 8, 2021 09:06

draft

4f49533

draft

0fc1b4b

acrolinx

22155f4

tweaks

ccea1b3

dotnet-bot added this to the March 2021 milestone Mar 9, 2021

dotnet-bot added fundamentals/subsvc get-started/subsvc lang-reference/subsvc dotnet-csharp/svc labels Mar 9, 2021

Youssef1313 reviewed Mar 9, 2021

View reviewed changes

docs/csharp/programming-guide/main-and-command-args/index.md Outdated Show resolved Hide resolved

Youssef1313 reviewed Mar 9, 2021

View reviewed changes

...-guide/main-and-command-args/snippets/top-level-statements-1/top-level-statements (2).csproj Outdated Show resolved Hide resolved

Youssef1313 reviewed Mar 9, 2021

View reviewed changes

...ming-guide/main-and-command-args/snippets/top-level-statements-3/top-level-statements.csproj Outdated Show resolved Hide resolved

Youssef1313 reviewed Mar 9, 2021

View reviewed changes

docs/csharp/programming-guide/main-and-command-args/top-level-statements.md Show resolved Hide resolved

Youssef1313 reviewed Mar 9, 2021

View reviewed changes

docs/csharp/programming-guide/main-and-command-args/top-level-statements.md Show resolved Hide resolved

tdykstra added 2 commits March 9, 2021 12:49

address feedback

a811f38

address feedback

9353918

tdykstra added 2 commits March 9, 2021 14:59

tweak wording

c9bf7ee

minor tweaks

5168b47

tdykstra marked this pull request as ready for review March 10, 2021 22:59

tdykstra requested a review from BillWagner as a code owner March 10, 2021 22:59

fix link

2ca6d58

BillWagner approved these changes Mar 11, 2021

View reviewed changes

BillWagner added a commit to BillWagner/docs that referenced this pull request Mar 11, 2021

Add note from dotnet#23234

6a63eaa

This note is important, and is added to a file that will be deleted in this PR.

Update docs/csharp/programming-guide/classes-and-structs/methods.md

fddbebe

Co-authored-by: Bill Wagner <wiwagn@microsoft.com>

Youssef1313 reviewed Mar 11, 2021

View reviewed changes

docs/csharp/programming-guide/main-and-command-args/top-level-statements.md Outdated Show resolved Hide resolved

address feedback

383f32d

tdykstra and others added 4 commits March 11, 2021 09:37

Merge branch 'toplevel' of https://github.com/tdykstra/dotnet-docs in…

8a9f5ea

…to toplevel

Update docs/csharp/programming-guide/main-and-command-args/top-level-…

5f7e6fe

…statements.md Co-authored-by: Youssef Victor <youssefvictor00@gmail.com>

add to toc

6dca758

Merge branch 'toplevel' of https://github.com/tdykstra/dotnet-docs in…

3d85dcd

…to toplevel

tdykstra merged commit 667c70d into dotnet:main Mar 11, 2021

tdykstra deleted the toplevel branch March 11, 2021 18:00

BillWagner added a commit to BillWagner/docs that referenced this pull request Mar 11, 2021

Add note from dotnet#23234

e3e4b6b

This note is important, and is added to a file that will be deleted in this PR.

BillWagner added a commit to BillWagner/docs that referenced this pull request Mar 11, 2021

Add note from dotnet#23234

aa94679

This note is important, and is added to a file that will be deleted in this PR.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

C# Programming guide: Top-level statements #23234

C# Programming guide: Top-level statements #23234

tdykstra commented Mar 9, 2021

Youssef1313 Mar 9, 2021

tdykstra Mar 9, 2021

Youssef1313 Mar 9, 2021

tdykstra Mar 9, 2021

Youssef1313 Mar 9, 2021 •

edited

Loading

tdykstra Mar 9, 2021

BillWagner Mar 11, 2021

Youssef1313 Mar 9, 2021

tdykstra Mar 9, 2021

Youssef1313 Mar 9, 2021

tdykstra Mar 9, 2021

tdykstra commented Mar 9, 2021

BillWagner left a comment

BillWagner Mar 11, 2021

tdykstra Mar 11, 2021

BillWagner Mar 11, 2021

BillWagner Mar 11, 2021

BillWagner Mar 11, 2021

BillWagner Mar 11, 2021

tdykstra Mar 11, 2021

BillWagner Mar 11, 2021

		@@ -0,0 +1,90 @@
		---
		title: "Top-level statements - C# Programming Guide"


		:::code language="csharp" source="snippets/top-level-statements-1/Program.cs":::

		Top-level statements let you write simple programs for small utilities such as Azure Functions and GitHub Actions. They also make it simpler for new C# programmers to get started learning and writing code.


		> CS7022 The entry point of the program is global code; ignoring 'Main()' entry point.

		In a project with top-level statements, you can't use the [-main](../../language-reference/compiler-options/main-compiler-option.md) compiler option to select the entry point, even if the project has one or more `Main` methods.


		The compiler generates a method to serve as the program entry point for a project with top-level statements. The name of this method isn't actually `Main`, it's an implementation detail that your code can't reference directly. The signature of the method depends on whether the top-level statements contain the `await` keyword or the `return` statement. The following table shows what the method signature would look like, using the method name `Main` in the table for convenience.

		\| Top-level code contains\| Implicit `Main` signature \|

		## C# language specification

		[!INCLUDE[CSharplangspec](~/includes/csharplangspec-md.md)]

C# Programming guide: Top-level statements #23234

C# Programming guide: Top-level statements #23234

Conversation

tdykstra commented Mar 9, 2021

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Youssef1313 Mar 9, 2021 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tdykstra commented Mar 9, 2021

BillWagner left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Youssef1313 Mar 9, 2021 •

edited

Loading