Scott Hanselman

The Microsoft Docs at https://docs.microsoft.com are really fantastic lately. All the .NET Docs are on GitHub https://github.com/dotnet/docs/ and you can contribute to them. However, in the world of software engineering (here some a bad, mixed metaphor) there's instructions on how to use a faucet and there's instructions on how to build and design plumbing from scratch.

There's additional DEEP docs that don't really belong on the docs site. It's the Book of the Runtime and for now it's on GitHub. Here's the BotR FAQ.

If you're interested in the internals of a system like the .NET Runtime, these docs are a gold mine for you.

The Book of the Runtime is a set of documents that describe components in the CLR and BCL. They are intended to focus more on architecture and invariants and not an annotated description of the codebase.

It was originally created within Microsoft in ~ 2007, including this document. Developers were responsible to document their feature areas. This helped new devs joining the team and also helped share the product architecture across the team.

We realized that the BotR is even more valuable now, with CoreCLR being open source on GitHub. We are publishing BotR chapters to help a new set of CLR developers.

This book likely isn't for you if you're an app developer. Who is it for?

• Developers who are working on bugs that impinge on an area and need a high level overview of the component.
• Developers working on new features with dependencies on a component need to know enough about it to ensure the new feature will interact correctly with existing components.
• New developers need this chapter to maintain a given component.

These aren't design documents, these are docs that were written after features are implemented in order to explain how they work in practice.

Recently Carol Eidt wrote an amazing walkthrough to .NET Core's JIT engine. Perhaps start at the JIT Overview and move to the deeper walkthrough. Both are HUGELY detailed and a fascinating read if you're interested in how .NET makes Dynamic Code Execution near-native speed with the RyuJIT - the next-gen Just in Time compiler.

Here's a few highlights I enjoyed but you should read the whole thing yourself. It covers the high level phases and then digs deeper into the responsibilities of each. You also get a sense of why the RyuJIT is NOT the same JITter from 15+ years ago - both the problem space and processors have changed.

This is the 10,000 foot view of RyuJIT. It takes in MSIL (aka CIL) in the form of byte codes, and the Importer phase transforms these to the intermediate representation used in the JIT. The IR operations are called “GenTrees”, as in “trees for code generation”. This format is preserved across the bulk of the JIT, with some changes in form and invariants along the way. Eventually, the code generator produces a low-level intermediate called InstrDescs, which simply capture the instruction encodings while the final mappings are done to produce the actual native code and associated tables.

This is just one single comprehensive doc in a collection of documents. As for the rest of the Book of the Runtime, here's the ToC as of today, but there may be new docs in the repository as it's a living book.

• Book of the Runtime FAQ
• Introduction to the Common Language Runtime
• Garbage Collection Design
• Threading
• RyuJIT Overview
  • Porting RyuJIT to other platforms
• Type System
• Type Loader
• Method Descriptor
• Virtual Stub Dispatch
• Stack Walking
• Mscorlib and Calling Into the Runtime
• Data Access Component (DAC) Notes
• Profiling
• Implementing Profilability
• What Every Dev needs to Know About Exceptions in the Runtime
• ReadyToRun Overview
• CLR ABI
• Cross-platform Minidumps

Check it out!

Sponsor: Check out JetBrains Rider: a new cross-platform .NET IDE. Edit, refactor, test and debug ASP.NET, .NET Framework, .NET Core, Xamarin or Unity applications. Learn more and download a 30-day trial!

About Scott

Scott Hanselman is a former professor, former Chief Architect in finance, now speaker, consultant, father, diabetic, and Microsoft employee. He is a failed stand-up comic, a cornrower, and a book author.

About   Newsletter

Hosting By