Docs: Epic: New features for C# 9

[BillWagner]

Track this at the feature status page on the roslyn repository. Those features with "Merged" status are already available in preview.

tasks for each C# 9.0 feature

• [x] Build plan for each feature
• [x] Create issues for updated reference material
• [x] Create issues for planned tutorials
• [ ] Create "Update your skills" section for "what's new" based tutorials.
• [x] Update "what's new in C#" page
• [ ] C# 6 - 7.3 content gets moved from "What's new" to appropriate locations as it's not new.

The Records and Pattern matching enhancements will likely affect the new Fundamentals sections. Other features may be covered in advanced, or primarily in update your skills

[BillWagner]

related: #19705

[BillWagner]

List of tasks for Records:

• Update language reference for classes & structs to include a section on records.
• Add a new language reference article for records. This should include information on the compiler generated members, and how to override them. In addition, it should explain inheritance rules for records, primary constructors, with-ers, and deconstruction methods.
• Add a tutorial that uses records and a number of the record features. Readers should learn how to decide between classes, structs, and records. This should go in the fundamentals section.
• Update the "Programming Guide->Types->Use and define types" article to mention records.
• Update the "Programming Guide -> Classes and structs" with an article on records. The new article should explain records and when to use them over class types.

[BillWagner]

List of tasks for Top-level statements*:

• Update the Tour of C# "hello world" example to show both formats of the program.
• Provide "upgrade your skills" tutorial for Azure functions using a program with top-level statements. This should include handling command line arguments.
• Update language reference to include the new valid entry points for a C# program. This should include the restrictions on top-level statements and multiple files. This should also include how the synthesized Main method responds to the presence of await expressions in top-level statements.

[BillWagner]

List of tasks for Pattern matching enhancements:

• Update pattern matching tutorial tp include examples using range patterns.
• Update pattern matching language reference with and, or, not and parentheses in patterns.
• Consider How-To articles for range patterns (character, number, etc)
• Additional How-to articles for combining patterns.
• Update nullable type articles to include new pattern based null checks. (both nullable value types and nullable reference types) e is not null syntax
• Language reference needs updates for the is keyword, the switch expression page.

[BillWagner]

List of tasks for Init only setters:

• Add new "upgrade your skills" tutorial to show how init only setters support immutability.
• Update articles on immutable types to include discussion of init only setters.
• Add init keywords to property accessors in language reference.
• Find readonly struct mentions and add a note that init cannot be added to properties in readonly structs.

[BillWagner]

Other features: My current opinion is the other new features are both targeted in scope and impact for most developers that the following should happen:

• update pertinent language reference section.
• Mention in "what's new" article with a small scoped sample.
• Consider an exploration of all these features (linking to larger tutorials)

Full task list

Native sized integers

The nint and nuint types need to be added to the language reference page on built-in types. The key points are that max value is for a 32 bit machine, and that constant folding is constrained to 32 bits.

Function pointers

• The "Programming guide -> Unsafe code and pointers" needs a new article on function pointer syntax.
• The language reference for delegate should include the delegate* syntax.

Target type new

• The language reference pages for new needs to be updated to add the new syntax.
• The language reference page for var needs to point to target type new as an alternative.
• The "Programming guide -> Classes and structs -> Methods -> Parameters -> Passing parameters" page should be updated to add that new() can be used to create the default instance of an argument type.

Other

• Language reference page for override should include the new rules for covariant return types.
• Language reference for foreach in should add that GetEnumerator could be an extension method.
• The page on discards should mention they can be used with lambda expressions.
• The page on lambda expressions should mention that they can specify discards as parameters.
• The articles on local functions should include that attributes can be applied to local functions. The pages on nullable attributes should mention that these can be applied to local functions.
• The conditional expression page should make sure it is not too restrictive to accommodate target type conditional expressions.
• The language reference for partial methods must be updated with the new rules. This must include how the language differentiates between the new and old versions of partial methods because the new style must have an implementation.
• Attributes interpreted by the compiler needs to add ModuleInitializerAttribute. All the rules on the initializer must be detailed.
• Attributes interpreted by the compiler needs to add SkipLocalsInitAttribute.