Important: This is a point-in-time snapshot of background work used to create a formal plan. The updated issues in the docs repo more accurately reflect the plan.
Using this resource:
- Consider the H2s as a good roadmap for where content should go.
- Consider lower level headers inasmuch as they show where existing articles will move over time.
- Articles will be combined and archived to keep the C# guide current.
The H2s are:
- Get Started. This node focuses on the top tasks for those customers that are new to software development, or new to .NET and C#. It focuses on the core skills every C# developer needs to know, regardless of the workload or application they intend to build. It's heavily tilted toward introductory tutorials and beginner concepts. The articles are
- What's new. This node is one of the most visited for those customers that are already using the .NET platform. It's the entry point to explore new features and new scenarios supported by the C# language. One of the key learnings from Ignite 2018 was that existing customers are not aware of recent improvements, many of which are aimed cloud scenarios. This project describes some of the work already done to increase awareness for these capabilities and scenarios.
- Task asynchronous programming model. The TAP programming model has generated more issues and requests than any other area of the C# language. Locating all the information about TAP under a single TOC node enables customers to find this information quickly and easily.
- Language Integrated Query (LINQ). LINQ remains one of the key value propositions for choosing the C# programming language. This H2 highlights this programming model for developers examining .NET for possible adoption.
- Advanced. These techniques are specialized areas that apply to only some scenarios. Separating them from more common scenarios shields inexperienced developers from finding these scenarios until needed. We do need to publish these techniques because many of our key enterprise customers depend on these advanced scenarios.
- .NET Compiler platform SDK. This is a large advanced SDK that enables partners and OSS library developers to ship tools that analyze code and offer suggestions. The content is primarily written by the product team.
- Abridged reference. The abridged reference provides readers with "the flavor" of each feature, without providing all the details in the specification. This area concentrates on informative text, where the specification concentrates on normative text. For historical reasons, the current reference branched from the C# specification at version 2.0. Since then, the reference has added more informative text, while retaining the fork of the normative text. The result is significant duplication and numerous inconsistencies between the language reference and the specification. This separation addresses both of those concerns.
- Specifications and proposals. The latest approved ECMA specification is C# 5.0. We publish the C# 6.0 draft, maintained by the product team. This draft will be submitted to the ECMA committee soon for adoption. The committee will determine if they want to work on C# 6 as a standard, or skip to C# 7.0. (Note: Bill is one of the members of the C# ECMA standards committee.) Microsoft has already shipped C# 7.0, 7.1, 7.2, 7.3, and C# 8.0 preview 2. For that reason, we are publishing the draft proposals for the features in those versions. We can link to them from other areas of the C# guide to direct users for detailed reference information.
The C# Guide is existing published content. This TOC represents a significant re-organization and consolidation of existing content, along with new content that addresses modern scenarios. The proposed TOC contains links where the nodes represent existing content. Nodes that include the wrench icon (🔧) represent new articles. Nodes with neither represent articles that will be created based on existing content. The TOC below has more depth where existing content is used.
Major sections are being re-organized out of existence in this proposed TOC:
- C# Concepts (primarily moved to the "get started" task.)
- Programming Guide (This section contains several subsections, numbering more than 500 articles)
- How To Guides (The existing How to articles are short, focused answers, somewhat different from the C & AI How To articles)
- Walkthroughs (Primarily moving to "tutorials" in different sections.)
Of these three, the "How To" section is the most interesting. In the proposed TOC, these articles are moved to the appropriate H2 by task. They are keeping the "How to" branding, even though these aren't strictly following the APEX content model definition of a "How to". We haven't found a more accurate term. Titles and H1's will be updated to focus more on the scenario / task, and less on the feature. (For example, "How to: use expression trees to make dynamic queries" will likely change to something similar to "How to dynamically query data sources using expression trees".) The existing titles are used in this TOC to provide a better roadmap on existing content.
The updated TOC with notes follows. The TOC is in markdown format to facilitate links to existing source, and provide an easier way to browse the outline.
- one page that points to other guides for .NET Core based workloads (ASP.NET, WPF, Windows Forms, etc).
- Tutorial will use EF Core.
- This is likely multiple tutorials for each Azure based storage model where the API includes a LINQ provider.
- all about keeping the UI responsive
- all about not blocking threads for scale out
This is a stacked TOC H1. The compiler platform SDK is specialized use of the compiler APIs to write static analysis tools.
- PR open for an updated overview.
- all about keeping the UI responsive
- all about not blocking threads for scale out
- where we explain that locks are often not needed for asyn
- Short focused answers toc common async questions. Examples include WhenAll vs. WhenAny, when to use ConfigureAwait, when to consider ContinueWith, when to use ValueTask, and so on.
This is a stacked TOC H1. LINQ is a major set of language features and APIs that enables querying data sources. It uses its own techniques and style.
####Query expression basics ####LINQ in C#
- Tutorial will use EF Core.
- This is likely multiple tutorials for each Azure based storage model where the API includes a LINQ provider.
- This section catalogs the current content of short samples and how to content. Many of these are likely cancidates for consolidation or archival.
- unsafe code and pointers
- stack allocations
- ref safe to escape
These two existing article provide source material
- Cover all .NET Core platforms
This is a stacked TOC H1. The compiler platform SDK is specialized use of the compiler APIs to write static analysis tools.
The roslyn-analyzers project contains many analyzers and code fixes that ship with Visual Studio. this is a great resource to learn more about writing analyzers, code fixes, and refactorings. This article will provide information about those analyzers and links to the source.
The purpose of this section is for readers to find summary information on the C# language. As such, each topic is a short definition for the token, operator, statement or expression. A common scenario or two will be shown as a sample. Links direct those readers that want more detail to the spec or updated spec proposal.
- bool
- enum
- sbyte
- byte
- short
- ushort
- int
- uint
- long
- ulong
- char
- decimal
- float
- double
- object
- dynamic
- string
- array
- delegate
- null
- true
- false
- default
++(prefix and postfix)--(prefix and postfix)+(unary and binary addition of numeric operands)-(unary and binary subtraction of numeric operands)*(multiplication)/(division)%(remainder)- corresponding compound assignment operators
checked/unchecked
&(bitwise AND for integral operands)|(bitwise OR for integral operands)^(bitwise exclusive-OR for integral operands)~(bitwise negation)<<and>>(shift operators)- corresponding compound assignment operators
&(logical AND forbooloperands)|(logical OR forbooloperands)^(logical exclusive-OR forbooloperands)!(logical negation)&&and||(conditional logical AND and OR operators)trueandfalseoperators (note: it's still might be a separate article on its own and only referenced from the overview)
<(less than)>(greater than)<=(less than or equal)>=(greater than or equal)
==(equal)!=(not equal)
&(address-of)*(pointer indirection)->(pointer member access)
Pointer arithmetic with
++,--,+, and-might also be included into the overview.
.(member access)[](array or indexer access)?.and?[](null-conditional access)()(method call)
=(assignment)?(nullable)!(null forgiveness)typeofoperator(T)explicit cast
is(and is with assignment)asswitchexpressions
?:(conditional operator). Somehow, it feels out of tune with the logical operators.??(null coalescing). It also feels not in the logical operations group. Most probably, it's because I limit logical operations to those onbooloperands.+,+=(string concatenation and delegate combination)-,-=(delegate removal)::(namespace alias qualifier)nameofsizeofawait=>(lambda declaration)@string literal token$interpolated string token
- namespace
- class
- struct
- interface
- partial (class and method)
- where (generic constraint)
- abstract
- in / out (variance)
- sealed
- static
Includes discussion of boxing structs.
- add / remove (event handlers)
- get / set (properties and indexers)
- value
- partial (class and method)
- where (generic constraint)
- yield (iterator method)
- void
- var
- abstract
- async
- const
- event
- extern
- in / out (variance)
- override
- sealed
- static
- virtual
- volatile
- in / ref / out (parameter, local, return value)
- stackalloc
- unsafe
- explicit, implicit
- operator
Cover default value of variables
- public
- protected
- internal
- private
- protected internal
- private protected
- readonly
- base
- this
- using, static using
- lock
- if / else
- switch
- break
- continue
- goto
- return
- do
- for
- foreach, in
- while
- throw
- try / catch
- try / finally
- try / catch / finally
- when (exception filter)
- from
- where
- select
- group
- into
- orderby / ascending / descending
- join
- let
- on
- equals
- by
- in
- Implicit conversions
- Explicit conversions
- Standard conversions
- User-defined conversions
- Anonymous function conversions
- Method group conversions
- Attribute classes
- Attribute specification
- Attribute instances
- Reserved attributes
- Attributes for Interoperation
- Unsafe contexts
- Pointer types
- Fixed and moveable variables
- Pointer conversions
- Pointers in expressions
- Fixed size buffers
- Stack allocation
- Dynamic memory allocation
The current TOC has a page for each option. (59 in total). I propose consolidating into one larger page and using H2s for each option:
- -addmodule
- -appconfig
- -baseaddress
- -bugreport
- -checked
- -codepage
- -debug
- -define
- -delaysign
- -deterministic
- -doc
- -errorreport
- -filealign
- -fullpaths
- -help, -?
- -highentropyva
- -keycontainer
- -keyfile
- -langversion
- -lib
- -link
- -linkresource
- -main
- -moduleassemblyname
- -noconfig
- -nologo
- -nostdlib
- -nowarn
- -nowin32manifest
- -optimize
- -out
- -pathmap
- -pdb
- -platform
- -preferreduilang
- -publicsign
- -recurse
- -reference
- -refout
- -refonly
- -resource
- -subsystemversion
- -target
- -target:appcontainerexe
- -target:exe
- -target:library
- -target:module
- -target:winexe
- -target:winmdobj
- -unsafe
- -utf8output
- -warn
- -warnaserror
- -win32icon
- -win32manifest
- -win32res
Some of these are in the TOC, many are not. They are also in two folders: csharp/misc (793 files) and csharp/language-reference/compiler-messages.md (135 files). The articles have not been updated since version 5.0. There are roughly 700 errors and warnings that have not been documented. None of these pages get significant traffic, but the readers that land here do so because they are completely blocked. I propose the following:
- Create one index page with a scoped search for message keys (e.g. CS5001)
- Create and migrate pages to that single folder.
- Only have the single index page in the TOC.
Note that adding currently undocumented messages is a P2 issue, and could be assigned to a vendor once this reorganization is done. See dotnet/docs#5410 for details.
[C# 7.2: private protected](https://github.com/dotnet/csharplang/blob/master/proposals/csharp-7.2/private protected.md)
[C# 7.2: Non-trailing named arguments](https://github.com/dotnet/csharplang/blob/master/proposals/csharp-7.2/non-trailing named arguments.md)
C# 7.3: Indexing fixed fields should not require pinning regardless of the movable/unmovable context
- short one pager that directs people to the external contributor guide + the .NET specific pages in the external contributor guide.
@BillWagner my thoughts throughout reading this gist:
I like the fact that both C# concepts and C# programming guide sections disappear.
The Get started TOC item contains two similar nodes: "Error reporting and handling with exceptions" and "Errors and Exceptions". Is this intentional or an accident?
The Get started -> Object oriented techniques. What if to show another side as well by adding the article about functional programming approach? Latest tutorials about pattern matching seem to be more on a FP side.
I'm missing this tutorial on string interpolation. Though, it's more a how-to type article.
Async tutorials are duplicated: I see them in the Tutorials part and the Task asynchronous programming model section. The same comment applies to the LINQ tutorials. Is that by design to make those tutorials easier to find?
As for LINQ and TAP, shouldn't they be in the .NET guide? Now, the .NET guide doesn't contain a lot about LINQ, only this page: https://docs.microsoft.com/en-us/dotnet/standard/using-linq
However, tasks and TPL have a bigger coverage there:
https://docs.microsoft.com/en-us/dotnet/standard/parallel-programming/
https://docs.microsoft.com/en-us/dotnet/standard/async-in-depth
Definitely, both concepts should be mentioned in both guides. The question is which of the guides contains detailed coverage of the feature and which one serves as an introduction and a portal to another guide. Also, the Visual Basic guide covers those features as well.
By the way, is there a line between a how-to article and a tutorial. I guess, now, some tutorials might be renamed to how-to.
As for the C# reference, we've discussed earlier that the "simple types" term is taken, so better not to make an article about them that excludes numeric types. Conclusion was to have separate TOC nodes for both
enumandbool. Also, forchar, effectively removing it from the numeric types article.I suggest one more article for the types section: Unmanaged types. That would contain the list of unmanaged types and refer to places where those types are used (pointer types,
sizeofoperator,unmanagedconstraint (?)). Also, those places would refer to that article for the definition of an unmanaged type. Currently, this information is duplicated throughout the docs.According to this issue the pattern matching operators are merged with assignment and conversion operators. Is it still the case and this gist a bit out-of-date? Or vice versa?
Not-in-any-group operators should include
new(didn't find it in this TOC) andstackalloc(this one now in Declaring members)The
lockstatement really stands out in its Controlling access group.I didn't check all statements, but where do
checkedanduncheckedstatements (not operators) go?