.NET 5 Wave - Reorganization

[IEvangelist]

For .NET 5, we are reorganizing the content to match the workloads describing what you can build with .NET. Each child project contains the issues (tasks) for that specific workload area. The amount of work reflects the organization of content that no longer reflects the modern .NET vision. Visitors should not need to understand the history of .NET to find information to build .NET apps now.

However, existing customers should be able to easily find content based on their current knowledge of the product and its brand names.

Meta-project: .NET 5 Wave

• .NET Fundamentals - @IEvangelist, @tdykstra, @scottaddie
  • Microsoft.Extensions: DI, config, logging, generic host, and options pattern
  • Cross platform
  • Open source
• .NET Languages (C#, F#, Visual Basic) - @BillWagner
• What's new - automated
  • Include links to all .NET content:  ASP.NET, Xamarin, Azure SDK for .NET
  • Generate separate pages for major areas of .NET each month.
• .NET Web - @scottaddie
• .NET Data - @CamSoper, @JeremyLikness, @mamccrea
• .NET Cloud - @CamSoper
• .NET Mobile - @davidbritch
• .NET Desktop - @adegeo
• .NET Game development - @adegeo
  • Focus will be on Unity and MonoGame
• .NET Machine Learning - @luisquintanilla
• .NET Internet of Things (IoT) - @CamSoper
• .NET Architecture - @nishanil
• .NET Framework 4.x - @gewarren
  • This content gets minimal changes, reflecting the roadmap for .NET Framework 4.x*

[Youssef1313]

.NET Web
.NET Mobile

Will these replace the asp and xamarin documentation (e.g, the asp and xamarin docs gets merged in here)?

[BillWagner]

@Youssef1313

Will these replace the asp and xamarin documentation (e.g, the asp and xamarin docs gets merged in here)?

Yes and no, and on different schedules. I'll defer to the respective issues and projects for a detailed discussion. Here's a brief version:

In both cases, these docsets will appear under the docs.microsoft.com/dotnet docset. The ASP.NET Core docs will be published under docs.microsoft.com/dotnet/web. Some xamarin docs will be published under docs.microsoft.com/dotnet/mobile.

However, we're not moving the source or closing those repositories. Instead, we'll update build scripts to chagne the active URL. We will keep history and the repository organization.

[twsouthwick]

This is great! Will this affect the docs at https://docs.microsoft.com/en-us/dotnet/core/porting/? We've been investigating what content is missing from this area and have found its organization to be very difficult to work through. I want to make sure that we won't end up duplicating any effort here if that will be included in this reorganization.

[IEvangelist]

This is great! Will this affect the docs at https://docs.microsoft.com/en-us/dotnet/core/porting/? We've been investigating what content is missing from this area and have found its organization to be very difficult to work through. I want to make sure that we won't end up duplicating any effort here if that will be included in this reorganization.

Hi @twsouthwick,

Yes, if you're tasking out any work in this area - let's place those issues in the correct corresponding parent project for transparency. These efforts should be placed under the .NET Framework (.NET 5 Wave) project, as issues.

[Gavin-Williams]

Can the gaming section please not focus on Unity. Just put a link in there to Unity forums and documentation. Please focus on game / tool development using .Net 5, C++/CX and C++/WinRT. Document how to make a game engine with either CoreWindow or XamlWindow. Document how to do interop between C# an C++. Document modern C++ game development, because most people are still using 20 year old C/C++ patterns, just look at some of the major education streams such as HandmadeHero or TheCherno to see that there's no modern Windows game development story.

And ... monogame? Are you guys serious? Doesn't it use Dx9 ? based on XNA a framework that you killed. Why would you want anyone to use Monogame? Even SharpDX is miles ahead of Monogame with it's Dx11/Dx12 support and that's a stale project, and there are newer frameworks being worked on that have both Dx11 and Dx12 for C#. Please update your view on game development for Windows.

And it's actually incredible that you don't have a game development strategy for your own primary language!

[svick]

@Gavin-Williams

Document modern C++ game development

Why would that be part of .Net documentation?

Even SharpDX is miles ahead of Monogame

SharpDX is just a DirectX binding, while Monogame is a framework for developing games, so I don't think it makes sense to compare the two. In fact, Monogame uses SharpDX on Windows: MonoGame/MonoGame#6691.

there are newer frameworks being worked on that have both Dx11 and Dx12 for C#

Do you have a suggestions for widely-used stable game development frameworks that should be included there?

[Gavin-Williams]

Prescript: Tried not to rant, but I think it's good to expand the ideas

@svick "Why would that be part of .Net documentation?" Well, that's a fair question. And my comment was a bit off track. Except the documentation for C# and C++ is heavily overlapped with UWP and it should be also with .Net 5. In fact, for many tasks, the discussion is the same, and docs should generally include sample code for multiple languages (C++,C#,Rust etc). Having docs cover different languages together is best - and task oriented, which is the goal of the reorganization. I guess when I think about game development, both C# and C++ are interchangeable, the WinRT API's are the same (or very similar) as well for each language. So I do sometimes find myself reading C++ code to create C# code. And in that case, C++/CX is best at being interchangeable with C#. Microsoft documentation is sometimes lacking in certain areas, particularly in game/tool dev.

Look at this very simple example...

https://docs.microsoft.com/en-us/uwp/api/windows.applicationmodel.core.coreapplicationview?view=winrt-19041

The language drop down shows C#, VB, C++/CX, C++/WinRT. It has C++/CX and C++/WinRT sample code to set up CoreWindow, but it lacks C# code .. why? C# is the primary development language, why would they not cover C# here? CoreWindow is actually a really important construct in C# as well as C++, because it gives raw access to the window without any Xaml framework over the top. These constructs and what we can do with them need to be presented in the documentation. Of course you'll find CoreWindow in various C++/Dx samples. But C# is used to perform the same tasks. Why should I need to understand the ideologies and biases of Microsoft engineers and management in order to work out how to bind a swapchain to a CoreWindow in C#?

Microsoft should look at games/graphics as one of the problem spaces for C#, in the same way they do for C++. Shouldn't we be able to look at how to set up a game loop and graphics device / swapchain - and while reading the documentation, just select which language we are interested in using? That's the way I see it. Why shouldn't both languages be covered together. This thread is about bringing tech together under task/topic - how do i do this or that - and getting away from having to know historical reasons why things are separated.

Of course there's the elephant in the room - lack of C# bindings to Dx11 & Dx12. But whatever the case, Microsoft need to widen their field of view regarding game/gfx/tool development. They've done nothing but point to Unity and Monogame in recent years, they've done a little in the C++ space. But really, we need more docs on setting up hardware rendering in C#, on dealing with the particular challenges of graphics and game programming. I believe the game market represents close to 50% of the value of all sofware sold at the retail level (or at least a fair chunk of it). When I look through Microsoft documentation and particular at samples, I don't get that impression.

And it's right that Microsoft point to Unity and Monogame, but I would suggest they also show how to bypass frameworks, how to work directly (or indirectly) with DirectX. Some obvious choices to explore: C++/CX, C++/WinRT, SharpDX, TerraFX, Vortice, or make up a new way to interop between C# and C++/DirectX, just give us good docs and samples to refer to. I've been programming for a few years now and I still often wish I had more and better documentation and sample code. The interop problem is challenging, and not dealt with to my satisfaction. It just got a lot harder with C++/WinRT.

I wonder if when Microsoft dumped XNA, they thought 'well it's not our problem anymore'. Meanwhile, many old and new developers are looking to make games and tools and graphical apps, while Microsoft is very laissez-faire about it. Graphics and game development are very enticing fields. I'm in a few game-oriented discord servers, one is a game (engine) development server (TheCherno Servo) with 10,000 members, 2200+ online right now. There are some notable games made with C#. And there is so much interest. But don't ask Microsoft how to make a game using .Net 5, they don't have an answer. Let's fix that through documentation.

[pjmlp]

The game section for .NET should focus on .NET languages, please stop destroying .NET adoption efforts for game development pushing the C++ agenda.

Managed DirectX, XNA, all killed in name of C++ teams at Microsoft.

As if using DirectXTK is anyway better for most .NET devs that were using XNA ,thankfully the community rose up and we got MonoGame.

The we have the complete refusal to expose DirectX via WinRT, althought both are COM based, because every .NET developer should just learn C++, while dealing with the primitive C++/WinRT VS tooling ATL style, because C++/CX was too good for us to keep using, and got the axe just like Managed DirectX and XNA.

So no, it should not only talk about Unity and MonoGame, but also about Stride (nee Xenko) and other approaches to do game engines in .NET.

EDIT: It came out a bit ranty, but the point stands, provide documentation and give first tier support for writing games in .NET with Microsoft technologies, instead of outsourcing efforts to 3rd party libraries or expecting that every .NET dev will happily learn C++.

[adegeo]

@pjmlp Hi! Regarding the game section, I fully agree. Unfortunately though, resourcing is a problem. We can't make getting started or tutorial series for a lot of different game engines. Does this mean they won't eventually appear? No. But right now we'll focus on those two as some of the most popular .NET game frameworks. The landing page for the area though would link off to other game engines/frameworks, hopefully featuring those that promote .NET 5 (maybe 3.1 as a minimum?) such as Wave and Stride. As other engines move out of Mono/Framework to .NET 5 (FNA, Duality, others?) then we would want to feature them also. It's all still a bit up-in-the-air as to the landing page, but we would want to promote .NET.

[heron1]

I just wanted to be a small voice to come here and say I like the original documentation proposal with Unity etc. and not incorporating the C++ suggestions that some users gave. When I view the .NET documentation I'd like it to be related to the .NET language stack, including how I can use C# (via Unity etc.) to develop computer games, an already challenging enough field in and of itself. If I'm interested in Game Engine development (a different field) in C++, the .NET documents wouldn't be the place I'd look for that. Furthermore, I'd imagine any company that would be capable of writing both its own game engine from scratch and releasing a polished commercial game on top of it based on that engine wouldn't be in need of any game engine development tutorials in the .NET documents sections.

The original documentation outline by IEvangelist seems consistent with the overall .NET vibe, and the future direction I'm hoping .NET will take with managed languages, and most importantly, unified development across all platforms.

[pjmlp]

@heron1 While Microsoft DirectX team refuses to support .NET bindings as WinRT components, and wasn't welcoming to Managed DirectX and XNA efforts, but has DirectXTK for C++ devs, every .NET developer
into games programming needs to routinely brush up their C++ skills.

[adegeo]

I wanted to point out this blog post announcing the game dev landing pages https://devblogs.microsoft.com/dotnet/game-development-with-net/