MQ Guidelines Initiative: .NET TODOs

[annelo-msft]

Summary

Per the MQ Guidelines initiative to fill gaps in the guidelines across languages, we are moving to a new common structure for the guidelines and calling out areas where there are content gaps -- i.e. one or more of he other language guidelines have guidance that is not language-specific that is not represented in this language's guidelines.

This PR shifts the .NET sections into the new structure, fixes a few .md bugs, and adds the TODOs identifying gap areas.

This corresponds to the following work items:

• .NET Guidelines: Updates to out of date guidelines #2086: Updates to out of date guidelines
• .NET Guidelines: Fill in cross-language gaps in Design page #2087: Gaps in Design section
• .NET Guidelines: Fill in cross-language gaps in Implementation page #2091: Gaps in Implementation section

New Structure

(Numbers for ease of reading here, but won't be shown in the guidelines page TOC)

Design

1. Introduction
   1. Design Principles
   2. General Guidelines
   3. Non-HTTP Libraries
2. Azure SDK API Design
   1. Service Client
      1. Service Client Constructors
      2. Service Methods
      3. Service Method Return Types
      4. Service Method Parameters
      5. Methods Returning Collections (Paging)
      6. Methods Invoking Long Running Operations
      7. Conditional Request Methods
   2. Supporting Types
      1. Model Types
      2. Enumerations
      3. Using Azure Core Types
      4. Using Primitive Types
   3. Exceptions (Errors)
   4. Authentication
   5. Namespaces
   6. Support for Mocking
   7. Hierarchical Clients
3. Azure SDK Libraries (Packages)
   1. Packaging
   2. Versioning
   3. Dependencies
   4. Doc Comments
4. Repository Guidelines
   1. Documentation Style
   2. README
   3. Samples

Implementation

1. API Implementation
   1. Service Client
      1. Service Methods
         1. HttpPipeline
         2. HttpPipelinePolicy
      2. Service Method Parameters
         1. Parameter Validation
   2. Supporting Types
      1. Serialization
      2. Enumeration-like Structs
2. SDK Feature Implementation
   1. Configuration
   2. Logging
   3. Distributed Tracing
   4. Telemetry
3. Testing
4. Language-specific other: Ecosystem Integration

[salameer]

Part of MQ reorganization efforts

[KrzysztofCwalina]

Could we rename these heading to "Implementation Considerations" or something like that? I would like to avoid having the term "API" used in this heading so readers don't think that this is the way to define the APIs.

[annelo-msft]

Yes, we can do that.

[KrzysztofCwalina]

Do we expect to have content here by EOY? Do we expect any content any time soon? If by EOY or soon, I would add a TBD note pointing to a workitem issue in GitHub. If we don't have concrete plans for what to have in this section, I would remove the section, and simply start with the Using HttpPipeline section

[annelo-msft]

The thinking here was that the implementation TOC would largely mirror the design TOC, where Using HttpPipeline is a subsection of The Service Client (because that's what it's used inside of). I see your point, though, this looks empty without anything there. I'll add a TBD.