Scott Hanselman

The Book of the Runtime - The internals of the .NET Runtime that you won't find in the documentation

September 27, '17 Comments [6] Posted in DotNetCore
Sponsored By

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.

RyuJIT High level overview

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.

ryujit-phase-diagram

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.

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.

facebook twitter subscribe
About   Newsletter
Sponsored By
Hosting By
Dedicated Windows Server Hosting by SherWeb

Spend less time CD'ing around directories with the PowerShell Z shortcut

September 24, '17 Comments [18] Posted in PowerShell
Sponsored By

Everyone has a trick for moving around their computer faster. It might be a favorite shell, a series of aliases or shortcuts. I like using popd and pushd to quickly go deep into a directory structure and return exactly where I was.

Another fantastic utility is simply called "Z." There is a shell script for Z at https://github.com/rupa/z that's for *nix, and there's a PowerShell Z command (a fork of the original) at https://github.com/vincpa/z.

As you move around your machine at the command line, Z is adding the directories you usually visit to a file, then using that file to give you instant autocomplete so you can get back there FAST.

If you have Windows 10, you can install Z in seconds like this:

C:\> Install-Module z -AllowClobber

Then just add "Import-Module z" to the end of your Profile, usually at $env:USERPROFILE\Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1

Even better, Z works with pushd, cd, or just "z c:\users\scott" if you like. All those directory changes and moves will be recorded it the Z datafile that is stored in ~\.cdHistory.

What do you think? Do you have a favorite way to move around your file system at the command line?


Sponsor: Get the latest JetBrains Rider preview for .NET Core 2.0 support, Value Tracking and Call Tracking, MSTest runner, new code inspections and refactorings, and the Parallel Stacks view in debugger.

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.

facebook twitter subscribe
About   Newsletter
Sponsored By
Hosting By
Dedicated Windows Server Hosting by SherWeb

What would a cross-platform .NET UI Framework look like? Exploring Avalonia

September 21, '17 Comments [28] Posted in Open Source | WPF
Sponsored By

Many years ago before WPF was the "Windows Presentation Foundation" and introduced XAML as a UI markup language for .NET, Windows, and more, there was a project codenamed "Avalon." Avalon was WPF's codename. XAML is everywhere now, and the XAML Standard is a vocabulary specification.

Avalonia is an open source project that clearly takes its inspiration from Avalon and has an unapologetic love for XAML. Steven Kirk (GitHubber by day) and a team of nearly 50 contributors are asking what would a cross-platform .NET UI Framework look like. WPF without the W, if you will.

Avalonia (formerly known as Perspex) is a multi-platform .NET UI framework. It can run on Windows, Linux, Mac OS X, iOS and Android.

YOU can try out the latest build of Avalonia available for download here:https://ci.appveyor.com/project/AvaloniaUI/Avalonia/branch/master/artifacts and probably get the "ControlCatalog.Desktop" zip file at the bottom. It includes a complete running sample app that will let you explore the available controls.

Avalonia is cross-platform XAML ZOMG

It's important note that while Avalonia may smell like WPF, it's not WPF. It's not cross-platform WPF - it's Avalonia. Make sense? Avalonia does styles differently than WPF, and actually has a lot of subtle but significant syntax improvements.

Avalonia is a multi-platform windowing toolkit - somewhat like WPF - that is intended to be multi- platform. It supports XAML, lookless controls and a flexible styling system, and runs on Windows using Direct2D and other operating systems using Gtk & Cairo.

It's in an alpha state but there's an active community excited about it and there's even a Visual Studio Extension (VSIX) to help you get File | New Project support and create an app fast. You can check out the source for the sample apps here https://github.com/AvaloniaUI/Avalonia/tree/master/samples.

Just in the last few weeks you can see commits as they explore what a Linux-based .NET Core UI app would look like.

You can get an idea of what can be done with a framework like this by taking a look at how someone forked the MSBuildStructuredLog utility and ported it to Avalonia - making it cross-platform - in just hours. You can see a video of the port in action on Twitter. There is also a cross-platform REST client you can use to call your HTTP Web APIs at https://github.com/x2bool/restofus written with Avalonia.

The project is active but also short on documentation. I'm SURE that they'd love to hear from you on Twitter or in the issues on GitHub. Perhaps you could start contributing to open source and help Avalonia out!

What do you think?


Sponsor: Get the latest JetBrains Rider preview for .NET Core 2.0 support, Value Tracking and Call Tracking, MSTest runner, new code inspections and refactorings, and the Parallel Stacks view in debugger.

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.

facebook twitter subscribe
About   Newsletter
Sponsored By
Hosting By
Dedicated Windows Server Hosting by SherWeb

A Functional Web with ASP.NET Core and F#'s Giraffe

September 18, '17 Comments [11] Posted in DotNetCore
Sponsored By

728331198_7c1854e363_bI was watching Ody Mbegbu's YouTube Channel - it's filled with .NET Core and ASP.NET Tutorial Videos - and was checking out one in particular, "Getting Started with ASP.NET Core Giraffe." Dane Vinson pointed me to it.

There is such a great open source renaissance happening right now with new framework's and libraries popping up in the .NET Core space. I hope you check them out AND support the creators by getting involved, writing docs, filing (kind) issues, and even doing pull requests and fixing bugs or writing tests.

Ody's video was about Dustin Morris' "Giraffe" web framework. Dustin's description is "A native functional ASP.NET Core web framework for F# developers." You can check it out over at https://github.com/dustinmoris/Giraffe.

Even better, it uses the "dotnet new" templating system so you can check it out and get started in seconds.

c:> md \mygiraffeeapp & cd \mygiraffeeapp
c:\mygiraffeeapp> dotnet new -i "giraffe-template::*"
c:\mygiraffeeapp> dotnet new giraffe
The template "Giraffe Web App" was created successfully.
c:\mygiraffeeapp> dotnet run
Hosting environment: Production
Content root path: C:\mygiraffeapp
Now listening on: http://localhost:5000
Application started. Press Ctrl+C to shut down.

Boom. Now I'm checking out Giraffe's "Hello World."

Because ASP.NET Core is very modular and built on "middleware" pipelines, that means that other frameworks like Giraffe can use the bits they want and remove the bits they down. Remembering that this is F#, not C#, here you can see Giraffe adding itself to the pipeline while still using the StaticFileMiddleware.

let configureApp (app : IApplicationBuilder) =
app.UseGiraffeErrorHandler errorHandler
app.UseStaticFiles() |> ignore
app.UseGiraffe webApp

The initial readme.md for Giraffe is the docs for now, and frankly, they are excellent and easy to read. The author says:

It is not designed to be a competing web product which can be run standalone like NancyFx or Suave, but rather a lean micro framework which aims to complement ASP.NET Core where it comes short for functional developers. The fundamental idea is to build on top of the strong foundation of ASP.NET Core and re-use existing ASP.NET Core building blocks so F# developers can benefit from both worlds.

Here is a smaller Hello World. Note the use of choose and the clear and terse nature of F#:

open Giraffe.HttpHandlers
open Giraffe.Middleware

let webApp =
choose [
route "/ping" >=> text "pong"
route "/" >=> htmlFile "/pages/index.html" ]

type Startup() =
member __.Configure (app : IApplicationBuilder)
(env : IHostingEnvironment)
(loggerFactory : ILoggerFactory) =

app.UseGiraffe webApp

Is terse an insult? Absolutely not, it's a feature! Check out this single line exampe...and the fish >=> operator! Some people don't like it but I think it's clever.

let app = route "/" >=> setStatusCode 200 >=> text "Hello World"

Making more complex:

let app =
choose [
GET >=> route "/foo" >=> text "GET Foo"
POST >=> route "/foo" >=> text "POST Foo"
route "/bar" >=> text "Always Bar"
]

Or requiring certain headers:

let app =
mustAccept [ "text/plain"; "application/json" ] >=>
choose [
route "/foo" >=> text "Foo"
route "/bar" >=> json "Bar"
]

And you can continue to use Razor views as you like, passing in models written in F#

open Giraffe.Razor.HttpHandlers

let model = { WelcomeText = "Hello World" }

let app =
choose [
// Assuming there is a view called "Index.cshtml"
route "/" >=> razorHtmlView "Index" model
]

There are samples at https://github.com/dustinmoris/Giraffe/tree/master/samples you can check out as well

* Giraffe photo by Kurt Thomas Hunt, used under CC


Sponsor: A third of teams don’t version control their database. Connect your database to your version control system with SQL Source Control and find out who made changes, what they did, and why. Learn more!

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.

facebook twitter subscribe
About   Newsletter
Sponsored By
Hosting By
Dedicated Windows Server Hosting by SherWeb

The ASP.NET Interns ship their project - A basic blog template for .NET Core

September 14, '17 Comments [8] Posted in DotNetCore | Open Source
Sponsored By

The internsThe Visual Studio Tools team had some great interns this summer. Juliet Daniel, Lucas Isaza, and Uma Lakshminarayan have been working all summer and one of their projects was to make something significant with ASP.NET Core and .NET Core. They decided to write a blog template. This is interesting as none of them had written C# or .NET before. Python, C, JavaScript, but not C#. This was a good exercise for them to not only learn C#/.NET but also give the team real feedback on the entire process. The ASP.NET Community Standup had the interns on the show to give us a walkthrough of their process and what they thought of VS.

They did their work over at https://github.com/VenusInterns/BlogTemplate so I'd encourage you to star their repository...and maybe get involved! This is a great starter application to explore ASP.NET and possibly do a pull request (make sure to give them a heads up in an issue before refactoring/changing everything ;) ) and contribute.

The interns used ASP.NET Core's new Razor Pages as well. Razor Pages sits on (is just) MVC so while it might initially look unfamiliar, remember that it's all still using the ASP.NET Core "MVC" pattern under the hood.

When you install the  .NET Core SDK you'll get a bunch of standard templates so you can:

  • dotnet new console
  • dotnet new mvc
  • dotnet new console --language F#
  • etc

There are lots of 3rd party and community templates and the beginnings of a website to search them. I expect this to be more formal and move into docs.microsoft.com in time.

The interns made "dotnet new blog" where blog is the short name of their template. They haven't yet released their template into NuGet for folks to easily install "dotnet new -I blogtemplate.whatever," For now you'll need to clone their repo as if you were developing a template yourself. It's actually a decent way for you to learn how to make templates.

Try this, using the .NET Core 2.0 SDK.

C:\> git clone https://github.com/VenusInterns/BlogTemplate.git
C:\> dotnet new -i C:\BlogTemplate -o C:\myblog
C:\> cd \myblog\BlogTemplate
C:\myblog\BlogTemplate> dotnet run
C:\myblog\BlogTemplate (master) > dotnet run
Using launch settings from C:\myblog\BlogTemplate\Properties\launchSettings.json...
Hosting environment: Development
Content root path: C:\myblog\BlogTemplate
Now listening on: http://localhost:59938
Application started. Press Ctrl+C to shut down.

And here's my nice local new blog. It's got admin, login, comments, the basics.

image

At this point you're running a blog. You'll see there is a Solution in there and a project, and because it's a template rather than a packaged project, you can open it up in Visual Studio Code and start making changes. This is an important point. This is an "instance" that you've created. At this point you're on your own. You can expand it, update it, because it's yours. Perhaps that's a good idea, perhaps not. Depends on your goals, but the intern's goal was to better understand the "dotnet new" functionality while making something real.

Here's some of the features the interns used, in their words.

  • Entity Framework provides an environment that makes it easy to work with relational data. In our scenario, that data comes in the form of blog posts and comments for each post.
  • The usage of LINQ (Language Integrated Query) enables the developer to store (query) items from the blog into a variety of targets like databases, xml documents (currently in use), and in-memory objects without having to redesign how things are queried, but rather where they are stored.
  • The blog is built on Razor Pages from ASP.NET Core. Because of this, developers with some knowledge of ASP.NET Core can learn about the pros and cons of building with Razor Pages as opposed to the previously established MVC schema.
  • The template includes a user authentication feature, done by implementing the new ASP.NET Identity Library for Razor Pages. This was a simple tool to add that consisted of installing the NuGet package and creating a new project with the package and then transferring the previous project files into this new project with Identity. Although a hassle, moving the files from one project to the other was quite simple because both projects were built with Razor Pages.
  • Customizing the theme is fast and flexible with the use of Bootstrap. Simply download a Bootstrap theme.min.css file and add it to the CSS folder in your project (wwwroot > css). You can find free or paid Bootstrap themes at websites such as bootswatch.com. You can delete our default theme file, journal-bootstrap.min.css, to remove the default theming. Run your project, and you'll see that the style of your blog has changed instantly.

I wouldn't say it's perfect or even production ready, but it's a great 0.1 start for the interns and an interesting codebase to read and improve!

Here's some ideas if you want a learning exercise!

  • Make the serializers swappable. Can you change XML to JSON or Markdown?
  • Make an RSS endpoint!
  • Add Captcha/reCaptcha
  • Add social buttons and sharing
  • Add Google AMP support (or don't because AMP sucks)
  • Add Twitter card support

You can also just play with their running instance here. Be nice. https://venusblog.azurewebsites.net/ (Username: webinterns@microsoft.com, Password: Password.1)


Sponsor: A third of teams don’t version control their database. Connect your database to your version control system with SQL Source Control and find out who made changes, what they did, and why. Learn more!

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.

facebook twitter subscribe
About   Newsletter
Sponsored By
Hosting By
Dedicated Windows Server Hosting by SherWeb

Disclaimer: The opinions expressed herein are my own personal opinions and do not represent my employer's view in any way.