David Pine — @IEvangelist

ASP.NET Core RC2 (Migration Guide)

David Pine — Sat, 21 May 2016 00:00:00 GMT

Introduction

On Monday, May 16<sup>th</sup> 2016 there was an amazing announcement from the .NET Blog team!

Announcing .NET Core RC2 and .NET Core SDK Preview 1

This post will serve as a guide that walks you through the steps as I experienced them from migrating existing ASP.NET Core RC1 applications to ASP.NET Core RC2. It is worth mentioning that I'm am targeting the .NET 4.6 framework. So, I do not cover the .netcoreapp or netstandard TFMs (target framework monikers).

Tooling

The RC2 release brings the .NET Core CLI to the forefront, and with that all the other command line tooling that you've grown accustomed to should be stricken from your environment, i.e.; DNX, DNU, and DNVM. Let's start with the removal of all these utilities.

Removing DNVM

Believe it or not, you might have a dated version of the DNVM CLI and in order to invoke the uninstall you might have to first perform an update-self command. Doing so will ensure that you have the latest version, which will contain the uninstall command. From a cmd window running as admininistrator, execute the following:

dnvm update-self

Then execute the following:

dnvm uninstall

Verification

From a new cmd window, the dnvm command should result in the following:

λ dnvm
'dnvm' is not recognized as an internal or external command, operable program or batch file.

Removing DNX & DNU

From a cmd line window, execute dnx - you should see something similar to this as output:

λ dnx
Microsoft .NET Execution environment Clr-x86-1.0.0-rc1-16231

Usage: dnx [options]

Options:
  --project|-p <PATH>              Path to the project.json file or the application folder. Defaults to the current folder if not provided.
  --appbase <PATH>                 Application base directory path
  --lib <LIB_PATHS>                Paths used for library look-up
  --debug                          Waits for the debugger to attach before beginning execution.
  --bootstrapper-debug             Waits for the debugger to attach before bootstrapping runtime.
  --framework <FRAMEWORK_ID>       Set the framework version to use when running (i.e. dnx451, dnx452, dnx46, ...)
  -?|-h|--help                     Show help information
  --version                        Show version information
  --watch                          Watch file changes
  --packages <PACKAGE_DIR>         Directory containing packages
  --configuration <CONFIGURATION>  The configuration to run under
  --port <PORT>                    The port to the compilation server

Likewise enter dnu in the same cmd window, expecting the following output:

λ dnu
Microsoft .NET Development Utility Clr-x86-1.0.0-rc1-16231

Usage: dnu [options] [command]

Options:
  -v|--verbose  Show verbose output
  -?|-h|--help  Show help information
  --version     Show version information

Commands:
  build             Produce assemblies for the project in given directory
  clear-http-cache  Clears the package cache.
  commands          Commands related to managing application commands (install, uninstall)
  feeds             Commands related to managing package feeds currently in use
  install           Install the given dependency
  list              Print the dependencies of a given project
  pack              Build NuGet packages for the project in given directory
  packages          Commands related to managing local and remote packages folders
  publish           Publish application for deployment
  restore           Restore packages
  wrap              Wrap a csproj/assembly into a project.json, which can be referenced by project.json files

Use "dnu [command] --help" for more information about a command.

The DNX and DNU command line tools are simply exe's in your %USERPROFILE%\.dnx and %USERPROFILE%\.dnx\bin directories. Navigate to your %USERPROFILE% directory from windows explorer and delete the .dnx directory entirely. Once you have successfully deleted this directory you should be able to execute the dnx and dnu commands again from a cmd window and the system should complain that they are not recognized.

Verification

From a new cmd window, the dnx and dnu commands should result in the following:

λ dnx
'dnx' is not recognized as an internal or external command, operable program or batch file.

λ dnu
'dnu' is not recognized as an internal or external command, operable program or batch file.

Environment Variables

Unfortunately, the PATH environment variable is not cleaned up and this needs to be done manually.

Press the <kbd>Windows</kbd> key, then begin typing "environment", then select either of the two top options returned:

You are then presented the "system properties" dialog, select Environment Variables.

We will need to ensure that both PATH variables are cleaned up, including your %USERPROFILE% and the System variables. Let's <kbd>Edit</kbd> both of them.

From the Edit Variables dialog, remove any and all of the following:

C:\Users\[ your global identifier ]\.dnx\bin;
C:\Users\[ your global identifier ]\.dnx\runtimes\dnx-clr-win-x86.1.0.0-rc1-update1\bin;

.NET Core CLI

Simply follow these instuctions. Once you're able to "Run the app" from the new CLI you're good to go.

Review

You should the following checklist fully satisfied at this point.

DNX, DNU and DNVM completely removed / uninstalled<br> Visual Studio 2015 Update 2 installed<br> .NET Core CLI installed

Edit by Hand

There were changes to APIs which required changes to implementation aspects of the source code. Additionally, namespace changes such as (but not limited to) Microsoft.AspNet.* to Microsoft.AspNetCore.*. But the bulk of the work was really in the hand-editing of .sln, global.json, .xproj, project.json, etc. files. Let's look at what changed.

The `.sln` file

Change the VisualStudioVersion from 14.0.24720.0 to 14.0.25123.0.

VisualStudioVersion = 14.0.25123.0

The `global.json` file

Change the version from 1.0.0-rc1-update1 to 1.0.0-preview1-002702.

{
  "projects": [ "src", "test" ],
  "sdk": {
    "version": "1.0.0-preview1-002702"
  }
}

The `.xproj` file

The .xproj files are a little more involved, there are a few items that are required to be changed. In RC1 we had proprerties that were specific to DNX, now we replace these with DOTNET.

RC1

<Import Project="$(VSToolsPath)\DNX\Microsoft.DNX.Props" 
        Condition="'$(VSToolsPath)' != ''" />

RC2

<Import Project="$(VSToolsPath)\DotNet\Microsoft.DotNet.Props" 
        Condition="'$(VSToolsPath)' != ''" />

Additionally, we need to change the targets. This one requires that you know the type of project you're editing, for example "class library" vs. "web site". In RC1 there was only one target, but with RC2 they are differeniated.

RC1

<Import Project="$(VSToolsPath)\DNX\Microsoft.DNX.targets" 
        Condition="'$(VSToolsPath)' != ''" />

RC2 (class library)

<Import Project="$(VSToolsPath)\DotNet\Microsoft.DotNet.targets" 
        Condition="'$(VSToolsPath)' != ''" />

RC2 (web)

<Import Project="$(VSToolsPath)\DotNet.Web\Microsoft.DotNet.Web.targets" 
        Condition="'$(VSToolsPath)' != ''" />

The `project.json` file

There has been a large reworking of the project.json file - detailed here. I will not be covering all of the changes here, but I do intend calling attention to some of the observations I have made and changes that were most pertinent. Here is the link for the official project.json schema.

We will look at various sections of the project.json file changes. Let's start with replacing compilationOptionsbuildOptions with buildOptions, and notice that we are adding much more options than before.

RC1

"compilationOptions": {
  "emitEntryPoint": true,
  "warningsAsErrors": true
},

RC2

"buildOptions": {  
  "emitEntryPoint": true,
  "warningsAsErrors": true,
  "preserveCompilationContext": true,
  "embed": "Views/**", // Instead of ".:resource": "Views/**",
  "compile": {
    "exclude": [ "wwwroot", "node_modules" ] // Now here, instead of ".:exclude"
  }
},

Additionally, we have publishOptions that we can utilize - consider the following:

"publishOptions": {
  "include": [
    "wwwroot",
    "appsettings.json",
    "web.config"
  ]
},

Finally, we have to be a little more specific with how we want the server to handle garbage collection.

"runtimeOptions": {
  "gcServer": true, // Yes, please perform garbage collection
  "gcConcurrent": true // Yes, please do so concurrently...
},

The `web.config` file

Now, IIS is a little smarter and is starting to recognize ASP.NET Core a little more.

RC1

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <system.webServer>
    <handlers>
      <add name="httpPlatformHandler" path="*" verb="*" modules="httpPlatformHandler" 
           resourceType="Unspecified"/>
    </handlers>
    <httpPlatform processPath="%DNX_PATH%" arguments="%DNX_ARGS%" stdoutLogEnabled="false" />
  </system.webServer>
</configuration>

RC2

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <system.webServer>
    <handlers>
      <add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModule" 
           resourceType="Unspecified" />
    </handlers>
    <aspNetCore processPath="%LAUNCHER_PATH%" arguments="%LAUNCHER_ARGS%" 
                forwardWindowsAuthToken="false" stdoutLogEnabled="false" />
  </system.webServer>
</configuration>

The `hosting.json` file

With the release of RC2, the project.json schema removed the webroot property. Now in order to specify the websites' static content directory we need to create a hosting.json file. This file should look like this.

{
  "webroot": "wwwroot"
}

The `appsettings.json` file

This was a minor change, but if you forgot to change this - then you'll end up with a runtime exception. The Logging:LogLevel:Default should now be Debug as Verbose was removed altogether.

RC1

"Logging": {
      "IncludeScopes": false,
      "LogLevel": {
        "Default": "Verbose", // < -- Change "Verbose"
        "System": "Information",
        "Microsoft": "Information"
      }

RC2

"Logging": {
      "IncludeScopes": false,
      "LogLevel": {
        "Default": "Debug", // < --- To "Debug"
        "System": "Information",
        "Microsoft": "Information"
      }

The `launchSettings.json` file

The environmentVariables changed, such that the key name for the environment is no longer referred to as "Hosting:Environment".

RC1

"environmentVariables": {
  "Hosting:Environment": "Development" // < -- Change "Hosting:Environment"
}

RC2

"environmentVariables": {
  "ASPNETCORE_ENVIRONMENT": "Development" // < -- To "ASPNETCORE_ENVIRONMENT"
}

The `*.cs` files

Some of these were very simple to fix. After updating your project.json with the latest RC2 versions - some changes are as simple as a namespace change (but others are more involed).

RC1

using Microsoft.AspNet.*;

RC2

using Microsoft.AspNetCore.*;

API changes

There was an attempt to unify some of the APIs as it pertains to consistency. As such, I had to make the following changes to my projects. The IApplicationBuilder.Use* pattern now takes a new *Options instance rather than an Action<*Options>, providing more control to the consumer.

RC1

app.UseCookieAuthentication(options =>
{
    options.AuthenticationScheme = "AspNetCookie";
    options.AutomaticAuthenticate = true;
    options.AutomaticChallenge = true;
    options.LoginPath = "/account/login";
    options.LogoutPath = "/account/logout";
    options.AccessDeniedPath = "/account/forbidden";
});

RC2

app.UseCookieAuthentication(new CookieAuthenticationOptions
{
    AuthenticationScheme = AuthenticationScheme.JciCookie,
    AutomaticAuthenticate = true,
    AutomaticChallenge = true,
    LoginPath = "/account/login",
    LogoutPath = "/account/logout",
    AccessDeniedPath = "/account/forbidden",
});

The service locator pattern (or should I say "anti-pattern") is slowing being removed from the framework. As such, if you were relying on the CallContextServiceLocator.Locator.ServiceProvider you can no longer do so with the RC2 release.

Wherever you were using the IApplication interface, you should be able to instead use the IWebHost interface.

Controllers as Services

In RC1, there was a nice little feature that allowed for any Type to exist in a list of plausible controller/services - meaning that you could basically register external controllers as valid API and View entry points into your hosting application. You simply needed to add the types via the following:

IMvcBuilder.AddControllersAsServices(params Type[] types);

This method signature changed with RC2 and it no longer accepts any arguments. In order to retain this functionality, you must first add the desired external assemblies as an AssemblyPart.

foreach (var assembly in GetExternalAssemblies())
{
    builder.PartManager.ApplicationParts.Add(new AssemblyPart(assembly));    
}

builder.AddControllersAsServices();

The Startup `.ctor`

One little change, you're now required to explicitly set the base path and you can do so with the following.

public Startup(IHostingEnvironment env)
{
    var builder =
        new ConfigurationBuilder()
            .SetBasePath(env.ContentRootPath) // Explicity set base from the content root path
            .AddJsonFile("appsettings.json", true)
            .AddJsonFile($"appsettings.{env.EnvironmentName}.json", true)
            .AddEnvironmentVariables();
    // Omitted for brevity...
}

The `Program.cs` file

Yes, we are now a console application...so we'll need this for our entry point.

public class Program
{
    public static void Main(string[] arguments)
    {
        using (var host = 
            new WebHostBuilder()
                .UseKestrel()
                .UseContentRoot(Directory.GetCurrentDirectory())
                .UseIISIntegration()
                .UseStartup<Startup>()
                .Build();)
        {
            host.Run();
        }
    }
}

Breaking changes

For a complete listing of all the announcements, please visit the official ASP.NET Repo announcements issue.

Conclusion

There, that really wasn't too bad - was it? I'm certain that I didn't cover everything and that I probably missed something. I hope that this was helpful, please feel free to share this!

The power of the global.json

David Pine — Tue, 19 Jul 2016 00:00:00 GMT

Introduction

As I'm sure you're all aware by now, Monday June 27<sup>th</sup> was a special day for those of you who were anticipating the release of .NET Core and ASP.NET Core. While the "core" frameworks and runtimes are RTM, the tooling is actually still in preview. In fact, we're currently on Tools Preview 2. I wanted to focus this post entirely on one specific enhancement to Visual Studio solutions, enter the global.json.

Let me paint a picture for you...you're developing an application. This application doesn't have all the source code in the world, so you take on some dependencies. Since we're not living in caves, we have packages -- this is common nomenclature for and the norm for any modern software development project. One of the aforementioned dependencies is a package that you just so happen to also work on and develop for. Imagine that you find a bug or want to make an improvement to said package, what does that work-flow look like?

For me, this typically involved the following steps:

Open dependency project in a new instance of Visual Studio
Make code change
Code review
Commit code
Build server builds code
Build goes "green" (tests passed)
Build server publishes package
Wander the halls playing Pokémon Go
Return to original project, update package reference
Continue with life

What if I told you, that headache is all but gone and you will never have to go through those agonizing steps again! Say it ain't so (queue Weezer).

Global.json

The global.json file sits out at the solution directory-level and literally has one of the simplest JSON schemas you will ever see. The default templates generate the following (for the full schema):

{
  "projects": [ "src", "test" ],
  "sdk": {
    "version": "1.0.0-preview2-003121"
  }
}

I always immediately delete the sdk property. If omitted the tooling simply assumes the latest SDK installed. Now, for all the fun! The projects property is an array of strings. It's defined as the following:

A list of project folders relative to this file.

These folders are search locations for resolving dependencies, where projects take precedence over packages.

Projects over Packages

Assume you're developing in a project, namely IEvangelist.NetCore.App and it takes a dependency on IEvangelist.NetCore.ClassLib and IEvangelist.NetCore.Services. These dependencies are packages (outside the solution) and you can use the global.json/projects array to your advantage. Using our imaginations, let us find a need to source-step into IEvangelist.NetCore.ClassLib. Let us also imagine that this project is in a neighboring folder outside our solution, perhaps the same repo, we can now use a relative path like so:

{
 "projects": [ 
   "src", 
   "../../IEvangelist.NetCore.ClassLib/src", // <-- Relative path to packaged source
   "../../IEvangelist.NetCore.Services/src"    
 ]
}

Before

After

After saving these changes to the global.json you'll notice Visual Studio pull this project into solution, but outside of the src folder. Now when you debug you can actually step into the source and treat it like any other source code you have. Project dependencies are resolved by way of their project.json being discovered.

Open Source for Everyone

One of the biggest advantages in my opinion is the ability to pull down source from github that I rely on and source-step into it. For example, I have been developing with ASP.NET Core since RC1, nearly eight months!! With the power of the global.json I can pull down source that I'm relying on in a package and fulfill my understanding of it as it executes. Simply amazing!

Angular2 Http with RxJS Observables

David Pine — Wed, 31 Aug 2016 00:00:00 GMT

If you have been following the development efforts of the Angular2 project, you have witnessed certain highs and lows - but it has been a fun ride. The latest version is only a Release Candidate and the team is getting closer to the final release. I'm really looking forward to that! I wanted to take a moment to highlight (IMO) one of the key services of Angular2, the http service.

In AngularJs 1 the ng.IHttpService (aka, $http) was based on promises and deferrals. In Angular2 we now rely on RxJS and the observable pattern. In my opinion this is a huge win! If you're unfamiliar with Reactive Extensions in general, I suggest starting here. RxJS is the JavaScript implementation of Reactive Extensions. Let's take a moment to compare and contrast the two, and immerse ourselves in the wonderful world of RxJS. Let me be clear upfront that I'm developing with TypeScript.

Legacy Pattern

As a developer you would have to use both the ng.IHttpService and the ng.IQService in combination to collaborate the deferral of the HTTP request and the promise that represented it. Consider the following:

module ExampleModule {
    export class ExampleService implements IExampleService {
        static $inject = ["$http", "$q"];

        private $http: ng.IHttpService;
        private $q: ng.IQService;

        constructor($http: ng.IHttpService, 
                    $q: ng.IQService) {
            this.$http = $http;
            this.$q = $q;
        }
        
        public getFooBars(): ng.IPromise<FooBar[]> {
          var deferred = this.$q.defer<FooBar[]>();
          this.$http
              .get("api/foobar")
              .success((data) => {
                  deferred.resolve(data);
              })
              .error((error) => {
                  console.log("An error occurred when requesting api/foobar.", error);
                  deferred.reject(error);
              });

          return deferred.promise;
        }
    }
}

In this example, we can easily see the interaction betwixt the ng.IHttpService ($http) and ng.IQService ($q) services. The $q variable exposes a .defer<T> function that returns a deferred object.

Deferred API

Function	Parameters	Description
`resolve`	`(value: T)`	Resolved yielding the materialized value of type `T`
`reject`	`(reason: string)`	Rejected with the given reason

The deferred object instance is passed into the fluent API's of the $http's .success and .error functions accordingly. This pattern works great, but is very limiting and repetitive. You end up writing a lot of boilerplate code and that isn't very DRY. Let's look at how this is approached with Angular2's http service using the observable pattern from RxJS!

New Pattern

To be fair, let's implement the same functionality and public surface-area such that our example services are equivalent.

import {Observable} from "RxJS/Rx";
import {Injectable} from "@angular/core";
import {Http} from "@angular/http";

@Injectable() export class ExampleService {
    constructor(private http: Http) { }

    getFooBars(onNext: (fooBars: FooBar[]) => void) {
        this.http
            .get("api/foobar")
            .map(response => response.json() as FooBar[])
            .subscribe(onNext,
                       error => 
                       console.log("An error occurred when requesting api/foobar.", error));
    }
}

I am hoping that you noticed how much cleaner this code is, as well as how much more readable!

Now, I know what you're thinking...these cannot possibly be the same examples, but they are in fact doing the same thing. Dependency Injection (DI) in Angular2 is a lot less error prone (no more magic strings) and way easier than it was in AngularJs 1. Simply do what you'd expect from any other common constructor-based DI framework, ensure that your desired Http type is registered as a provider to the system. This happens by way of the HTTP_PROVIDERS defined in our boot.js file. More on that in another post. With modern TypeScript we can define properties and fields, and their corresponding access modifiers right from within our constructors.

Syntax Tip

This exemplifies the comparisons in syntax between a simple constructor and the more verbose constructor.

// Simple .ctor()
constructor(private http: Http) { }

// Is equivalent to...
private http: Http;
constructor(http: Http) {
   this.http = http;
}

Likewise, the following is true regarding public access modifiers.

// Simple .ctor()
constructor(http: Http) { }

// Is equivalent to...
http: Http; // When the access modifier is omitted it's defaulted to public
constructor(http: Http) {
   this.http = http;
}

Comparing the APIs

Instead of the .success invocation with a corresponding deferred.resolve call, we now utilize the RxJS .map and .subscribe operators. Let's look at these below:

Operator	Description
`map`	Transform the items emitted by an `Observable` by applying a function to each item
`subscribe`	The `Subscribe` operator is the glue that connects an observer to an `Observable`

Mapping is easy and we can leverage some of the TypeScript language features to cast the JSON blobs returned from our services as strongly typed objects. The map operator is actually synonymous with the select operator, so if you're more familiar with that terminology you can use it interchangeably.

Advantages

Now that we have an understanding of how RxJS compares to the legacy pattern, we can take advantage of all the various benefits. Imagine with me that we have a need to implement retry logic, this would have been challenging with the legacy pattern but with the new pattern it's as simple as saying .retry. Consider the following:

// If this call fails, we'll try it again with the same payload two times
getFooBars(onNext: (fooBars: FooBar[]) => void) {
    this.http
        .get("api/foobar")
        .map(response => <FooBar[]>response.json())
        .retry(2)
        .subscribe(onNext,
                   error => 
                   console.log("An error occurred when requesting api/foobar.", error));
}

Now imagine a scenario where a user is typing and you want to provide an autocomplete, you could use .debounce to pause for a brief moment prior to sending the request. Likewise, we could apply a .filter that only takes action when a certain number of characters have been entered. Finally, we might utilize .distinctUntilChanged to only execute the request once the values are actually different than they once were.

You could take advantage of .buffer, .throttle, .interval, .window, .range, etc... The list goes on and on, and this is the source for most of what you can take advantage.

Let's Summarize

Angular2 has a new implementation of their http service that relies on RxJS. The API uses observables and the observer pattern to allow for a fluent experience that is rich and robust. Getting started is straight-forward and simple. Before too long you'll be taking advantage of the feature-full set of Reactive Extensions and thinking in terms of data streams. This mindset will make your life easier - trust me!

Further Reading

Overcoming Impostor Syndrome

David Pine — Sat, 05 Nov 2016 00:00:00 GMT

import { YouTube } from '@astro-community/astro-embed-youtube'; import { Tweet } from '@astro-community/astro-embed-twitter';

What is "impostor syndrome" you ask?

According to <cite>Wikipedia</cite>:

Impostor syndrome (also known as impostor phenomenon or fraud syndrome) is a term coined in 1978 by clinical psychologists Dr. Pauline R. Clance and Suzanne A. Imes referring to high-achieving individuals marked by an inability to internalize their accomplishments and a persistent fear of being exposed as a "fraud". Despite external evidence of their competence, those exhibiting the syndrome remain convinced that they are frauds and do not deserve the success they have achieved. Proof of success is dismissed as luck, timing, or as a result of deceiving others into thinking they are more intelligent and competent than they believe themselves to be.

It seems as though this syndrome has plagued our generation of developers! I have found that this syndrome has spread like wildfire through the technical community, devastating an individuals confidence and leveling their ambitions! Too often developers are doubting themselves and this needs to stop. As an industry we need to work to correct this.

We can all agree that I'm not the only one. If you haven't felt this way, [ close this tab now ]. If you're still reading, then thank you for your honesty.

I'm certain you've heard of "technical debt", I'd like to coin a new phrase - "technical doubt".

Technical Doubt is a term used to define an individuals lack of confidence as it pertains to a technical problem, wherein every solution the individual arrives at is combated with reluctancy and inadequacy.

Software engineering can be boiled down to the manipulation and movement of data. When you're a software engineer working on a task that involves either of these aspects of development you have to solve problems. Therefore, we're really just problem solvers, right?! The interesting thing is that there is always more than one way to solve a problem. And more often than not the way that you choose to solve said problem will not exactly align with the visions of your peers - this leads to potential conflict, and with conflict comes frustration and disarray!

We've all heard of the "Tabs vs Spaces" argument, right -- it's somewhat like that but much worse.

I believe that this is often the root of imposter syndrome, the fear of getting it wrong or being involved in some sort of conflict. I finally feel as though I no longer have this fear, therefore -- I have overcome imposter syndrome. I wanted to share some of the reasons that have led up to this monumental event.

Positivity

If you want to see a blackhole, bear witness to how negativity spreads through an office. A single person with a bad attitude can "infect" others and really be a drain! Be the one who combats that, be the person who seeks out the positive aspects of every situation. I'm the guy who says "it could always be worse", because it literally could. I act as the voice of reason -- and pure myself into living as a positive influence on the team.

Take Action

Personally, I have discovered that the more I compliment others the more I get complimented in return. The more I encourage others, the more I'm encouraged by them in return. The more you give, the more you get. Be humble and open-minded!

Mentor

I have found pride in mentoring. I feel as though there is always a satisfying challenge to overcome and a lesson learned. Often the lesson is two-sided, where I am a secondary beneficiary from the engagement. Often, explaining your experiences to the mentee reminds you of how much you have really been through. Reflecting on how you've navigated through a situation is surprisingly insightful. It's kind of like rubber duck programming.

Fear not

Never be afraid to ask "why", this can be extremely powerful. Sometimes the root of the problem is that there has been a misunderstanding at the root -- therefore all things leading up to where you're asking (what you believe to be a stupid question) is actually the best question that could have been asked. Find the root!

Community

If you have ever spent more than a few minutes with me, you will know that I'm an advocate of the technical community. Believe it or not, the community is extremely supportive and willing to lift you up -- all you have to do is being willing to put yourself out there. While this is humbling, it is also rewarding...

MKE DOT NET

I sit on the technical committee for MKE DOT NET, a developer conference in the Milwaukee area. Recently I was fortunate enough to get Scott Hanselman to be our keynote speaker. During his keynote (which was amazing) I shouted out several times to assist him with live coding / demonstration errors. He referred to me as his "second compiler"!

Stack Overflow

I set out at the beginning of the 2016 year with a goal to try to answer one SO question a day. Honestly, it is a lot more demanding than you might imagine -- but it's extremely gratifying! I have literally earned more attempting to answer questions than I have had asking or reading others questions. I answered an ASP.NET Core question that got the attention of David Folwer, holy crap -- IKR! Luckily after his code review and my update to the answer, "the garbage collector thanked me".

Getting the accepted answer over mega-super stars like Stephan Cleary can really make your head spin, even if they get more upvotes.

Let me compile that for you

Let me ASP.NET 5 that for you

Yes, you read that correctly. That is me helping out the legand Jon Skeet (arguably the world's best software engineer)!

Summary

These are minuscule things that really add up. Don't take it from me, you owe it to yourself to see what you're really made off. I believe in you already, if you made it through this post you have already accomplished more than most of your peers today. There is so much more that I want to give back to the community that I know this is only the beginning of something profound. I strive to do my best and I now know that it's enough!

Positivity, be the seeker of all things good and the voice of reason
Take action, give encouragement, compliments and praise
Be a mentor, there is nothing like teaching and you'll learn too
Fear not, never be afraid to ask "why", it might just solve the problem
Community, get involved and give back
Inject yourself where you want to be

These tips will help you overcome imposter syndrome -- it worked for me. Together we can kill "technical doubt"!

ASP.NET Core Response Optimization

David Pine — Mon, 12 Dec 2016 00:00:00 GMT

Intro

If you're a web developer, chances are you're familiar with optimization strategies such as static file caching and response compression. I recently implemented these two concepts in tandem on an ASP.NET Core application that I have been developing... I'm going to share what I have learned.

If you haven't had a chance to use ASP.NET Core yet, you're missing out! As my friend Scott Addie likes to say:

ASP.NET Core is a cafeteria plan in which developers choose application dependencies à la carte. This is in stark contrast to ASP.NET proper, where developers are provided a set meal (a bloated dependency chain) containing undesired items. Don't like broccoli with your steak? Maybe it's time to consider ASP.NET Core. <cite>Scott Addie</cite>

In other words, all dependencies are pluggable middleware. This provides ultimate control as you have to explicitly opt-in for the middleware you desire.

Know thy Middleware

Not all middleware is equal. Different middleware serves different purposes (obviously). Try to think of each middleware as its own standalone feature-set. Not all middleware is given a chance to execute on a given request. Certain middleware might send a web response and early exit. This can prevent other middleware in the pipeline from executing at all. In fact, this is the case when using static file caching and response compression together.

The order in which middleware is added matters and dictates the order of execution during a request.

Installing Dependencies

I wrote a tiny application and put it up on GitHub, check it out here if you want to follow along. Now let's install the dependencies we'll need. For static file caching and response compression we need to add two dependencies to the project.

Note: Microsoft.AspNetCore.StaticFiles will already have been installed if you started from a Visual Studio template.

Repository	Version	Nuget Package	Add / Use Extension Method(s)
	`1.1.0`	Static Files	UseStaticFiles
	`1.0.0`	Response Compression	AddResponseCompression UseResponseCompression

Follow these instructions, from within Visual Studio:

Tools ➪
    NuGet Package Manager ➪
        Manage NuGet Packages for Solution... ➪ 
            Browse ➪
                Search ➪
                    [ Install ]

Configuring Startup

There are two common nomenclatures that exist for wiring up middleware in your startup classes, the .Add* and .Use* extension methods. The .Add* calls are intended to add services to the IServiceCollection instance, ensuring that they are ready for usage. The .Use* calls specify that you want to use the middleware and makes the assumption that any services required by DI will have already been added with the corresponding .Add* call.

Now let's "add" response compression in the .ConfigureServices call of our Startup.cs.

public void ConfigureServices(IServiceCollection services)
{    
    services.AddMvc();
    services.AddResponseCompression(
        options => 
            options.MimeTypes = ResponseCompressionMimeTypes.Defaults);
}

Several bits of the implementation details should jump out at you. First, we do not need to call an .AddStaticFiles extension method because there are no services required for this middleware, as such it doesn't exist. Second, we are providing a lambda expression to satisfy the Action<ResponseCompressionOptions> parameter. We also assign the .MimeTypes property from the ResponseCompressionMimeTypes.Defaults we are targeting for compression.

If no compression providers are specified then GZip is used by default. <cite>ASP.NET Core Team - GitHub</cite>

The ResponseCompressionMimeTypes.cs is defined as follows:

using System.Collections.Generic;
using System.Linq;
using static Microsoft.AspNetCore.ResponseCompression.ResponseCompressionDefaults;

namespace IEvangelist.AspNetCore.Optimization
{
    public static class ResponseCompressionMimeTypes
    {
        public static IEnumerable<string> Defaults
            => MimeTypes.Concat(new[]
                                {
                                    "image/svg+xml",
                                    "application/font-woff2"
                                });
    }
}

There are several types defined by default in ASP.NET Core class ResponseCompressionDefaults.MimeTypes, we are simply expanding that to include "SVG" images and the "Woff2" fonts.

Order Exemplified

Consider the following:

public void Configure(IApplicationBuilder app,
                      IHostingEnvironment env,
                      ILoggerFactory loggerFactory)
{
    app.UseStaticFiles()          // Adds the static middleware to the request pipeline
       .UseResponseCompression(); // Adds the response compression to the request pipeline
}

The snippet above will absolutely work for serving static files, but it will not compress or cache anything. Note the differences below:

public void Configure(IApplicationBuilder app,
                      IHostingEnvironment env,
                      ILoggerFactory loggerFactory)
{
    app.UseResponseCompression()  // Adds the response compression to the request pipeline
       .UseStaticFiles();         // Adds the static middleware to the request pipeline       
}

The order in which the middleware was invoked in the pipeline changed, as such the order in which the middleware is executed on a request is also changed. When static file middleware occurs before response compression, it returns the file as a response before compression has a chance to execute.

Client requests main.css
Static file middleware determines it can fully satisfy said request
The main.css file is sent and the next middleware in the pipeline is never executed

Now that we have these two pieces of middleware wired into out pipeline in the correct order, what else is left. There is one important thing that we forgot to do. While we do have static file middleware, we didn't know that "caching" is off by default. So we'll need to handle this with an instance of the the StaticFileOptions.

Keep your 's open for extension method overloads. These are often clues that there are options for providing customized configuration for the middleware you're wiring up.

public void Configure(IApplicationBuilder app,
                      IHostingEnvironment env,
                      ILoggerFactory loggerFactory)
{
    app.UseResponseCompression()
       .UseStaticFiles(
           new StaticFileOptions
           {
               OnPrepareResponse =
                   _ => _.Context.Response.Headers[HeaderNames.CacheControl] = 
                        "public,max-age=604800" // A week in seconds
           })
       .UseMvc(routes => routes.MapRoute("default", "{controller=Home}/{action=Index}/{id?}"));
}

The instance of the StaticFileOptions object has a public property namely "OnPrepareResponse" of type Action<StaticFileResponseContext>. So we can again specify a lambda expression. This expression can be used to delegate the preparation of the response. Notice we're simply setting the Cache-Control header to a "max-age" of a week. That was pretty simple, hey?!

Compression Awareness

It's all the little things! The response compression middleware boasts deterministic compression, i.e.; if the KestrelHttpServer is running behind the IIS reverse proxy then the middleware may or may not compress the response. The middleware determines the following:

If the request accepts compression
If the requested resource matches the configured MIME types
Whether or not the response needs to be compressed

Results

Let's spend some time examining the results of our response optimization efforts.

Before

Total(s)

13 Requests | 549 KB transferred | ... | ...

banner1.svg Response Headers

HTTP/1.1 200 OK
Content-Length: 9679
Content-Type: image/svg+xml
Accept-Ranges: bytes
ETag: "1d1ce31e3bd09cf"

After

Total(s)

13 Requests | 175 KB transferred | ... | ...

The total payload for all 13 requests is a total of 3.137 times smaller (a meager 31.9% of the original size). The larger the application, the more dramatic and valuable this becomes! Consider an Angular2 application (or other SPA framework based application), which has tons of JavaScript files to download -- 5 MB turns into ~1.5 MB.

banner1.svg Response Headers

HTTP/1.1 200 OK
Content-Type: image/svg+xml
Server: Kestrel
Cache-Control: public,max-age=604800
Transfer-Encoding: chunked
Content-Encoding: gzip
Accept-Ranges: bytes
ETag: "1d1ce31e3bd09cf"

Subsequent (Cached) Requests

Let's Summarize

We learned some of the basics about ASP.NET Core middleware. Together we implemented a response optimization strategy that included deterministic response compression, as well as static file caching. We learned some of the common patterns and naming conventions for integrating with ASP.NET Core middleware. Finally, we have a good understanding of the ASP.NET Core request pipeline middleware precedence.

Source Code

IEvangelist.AspNetCore.Optimization

Building a Magic Mirror

David Pine — Fri, 23 Dec 2016 00:00:00 GMT

import { YouTube } from '@astro-community/astro-embed-youtube'; import { Tweet } from '@astro-community/astro-embed-twitter';

Inspiration

I am certainly not the first one to create a magic mirror, and I will not be the last either. I was inspired by those who are true Innovators...some might say, "I'm standing on the shoulders of giants". They would probably we right, and I'm okay with that. Earlier this year, I stumbled upon a tweet about someone how created a magic mirror...this is the root of my inspiration.

Before continuing on, allow me to explain what a magic mirror is. A magic mirror is simply a two-way mirror with a monitor positioned behind it that projects through the mirror. The monitor displays the application. The application is running on a small computer, in most cases a Raspberry Pi.

I noticed that a lot of the magic mirrors had greeting messages such as "you look handsome" or "good morning sexy" and other curiously intuitive sayings. I thought "wow" this really is a smart mirror, much to my surprise these were all just static messages (or only dynamic when accounting for the time of day). I was thinking to myself, "I wonder if I could improve upon this", and that was my motivation!

Open Source

If you want to skip out from reading this post, you can checkout my project up on GitHub IEvangelist.Mirror.

Hardware

I was excited when Microsoft started selling the Raspberry Pi 3, Model B - I ordered one immediately.

Specs

Miscellaneous

Below is a semi-comprehensive listing of all the materials and their corresponding cost that I used for building my magic mirror.

Rough Cost	Hardware
$60	<a href="https://www.microsoftstore.com/store/msusa/en_US/pdp/Raspberry-Pi-3-Bundle/productID.5068162700" target="_blank">Raspberry Pi 3 Bundle</a>
$130	<a href="https://www.amazon.com/gp/product/B00IZBIMLK/ref=oh_aui_search_detailpage?ie=UTF8&psc=1" target="_blank">BenQ 27" HDMI LED Monitor</a>
$90	<a href="https://www.tapplastics.com/product/plastics/cut_to_size_plastic/two_way_mirrored_acrylic/558" target="_blank">Custom-sized Two-way Mirrored Acrylic</a>
$40	<a href="https://www.amazon.com/Microsoft-LifeCam-Cinema-720p-Webcam/dp/B009CPC6QA" target="_blank">Microsoft LifeCam</a>
$25	<a href="https://www.amazon.com/gp/product/B00DEJXRAE/ref=oh_aui_search_detailpage?ie=UTF8&psc=1" target="_blank">Dell USB Wired Soundbar</a>
$6	<a href="https://www.amazon.com/gp/product/B000234UFG/ref=oh_aui_detailpage_o06_s00?ie=UTF8&psc=1" target="_blank">Power Cord Splitter</a>
$25	Full HDMI Cable, USB Extension Cables
$50	Carpentry Materials
$50	Glenlivet 12 Year Old Scotch Whisky (not technically hardware)
<strong>~$480</strong>

Considering the total investment is still under $500 bucks, that's not too bad!

OS -- Platform

One of my favorite parts about developing the magic mirror was the fact that I could do so from the comfort of Visual Studio using the worlds most powerful programming language today, C#.

Type	Name -- Link
<strong>OS</strong>	`Windows 10 IoT Core, "Build 10.0.14393"`
<strong>Platform</strong>	`Universal Windows Platform (UWP), "UAP 1.0"`

Software

When people throw around the acronym IoT it can mean a lot of different things. For this specific application, it is essential. Using the built-in WIFI on the Pi 3 we can leverage the power of the internet to gather and share information.

Software is simply the movement and manipulation of data. But without context, said data is meaningless.

The magic mirror application strives to provide data that is all of the following:

Relevant
Practical
Convenient
Timely

Below is the user-interface layout. Let's have a look at the various components that our application is built on.

Components

From the layout above, it is clear to visualize the key components of the application. Most of these components implement the IContextSynthesizer interface. These implementations are indicators that each component is capable of handling voice commands, and providing a message that is consumable by the UWP speech-synthesizer. More on this later...

Weather -- Forecast

The current weather and forecast are retrieved every fifteen minutes from the free Open Weather API. The developer API key and zip code are configurable. Additionally, the unit-of-measure is configurable, where you can specify imperial or metric as valid settings.

Clock

The clock is extremely simple. It is just the current date and time. It updates every second, formatting to the hour, minute, and second -- additionally displaying the name of the day followed by the month and day number.

Example:

:::note

I opted to omit whether or not we're in ante or post meridiem as it is assumed the user would know if it's morning or in the afternoon.

:::

Event Calendar / Schedule

My magic mirror is configured to display an aggregation of two calendars. This is entirely configurable, so if you were to fork my repo -- you would need to setup your desired endpoints. The only requirement is that the URL is an accessible endpoint that returns valid iCal (*.ics) formatting. The events are truncated to fit on the page and ordered by the date of the event.

Music Player

Imagine you have the magic mirror mounted in your bathroom, or bedroom...it would be nice to say, "play a song", or "play Deftones" for example and music starts playing. That is the idea behind the music player component. The current implementation of the music player is limited. I spent a few long nights trying to figure out how to use the built-in Bluetooth on the Pi 3, while UWP does have some support it is limited. I was able to pair but not stream songs from my iPod for example, which was really frustrating. For the meantime, I simply placed several songs in the Assets directory as content and I can play these resources. Ideally, I will use a web-based service like Spotify or Pandora.

Voice Commands

The Universal Windows Platform provides two very useful classes, the SpeechRecognizer and the SpeechSynthesizer. Leveraging this I have built out the ability to talk to my magic mirror, I can ask it things like "what's the weather", "what's my schedule for Wednesday", or even tell it commands like "turn this up".

Microsoft Cognitive Services

Formally known as "Project Oxford", Microsoft Cognitive Services offers a ton of programming power and you can start using it today for free. Simply subscribe and use your subscription key as the argument to the client .ctor. The magic mirror makes use of the Emotion API, and corresponding EmotionServiceClient from the Microsoft.ProjectOxford.Emotion package.

Consider the following:

async Task<IEnumerable<RawEmotion>> CaptureEmotionAsync()
{
    RawEmotion[] result;

    try
    {
        var photoFile = await _photoService.CreateAsync();
        var imageProperties = ImageEncodingProperties.CreateBmp();
        await _mediaManager.CapturePhotoToStorageFileAsync(imageProperties, photoFile);
        result = await _emotionClient.RecognizeAsync(await photoFile.OpenStreamForReadAsync());
    }
    finally
    {
        await _photoService.CleanupAsync();
    }

    return result.IsNullOrEmpty()
        ? await TaskCache<IEnumerable<RawEmotion>>.Value(() => Enumerable.Empty<RawEmotion>())
        : result;
}

First our _photoService asynchronously creates a photo file
From the ImageEncodingProperties class, we create a bitmap encoding property set
Our _mediaManager captures a photo, storing it in the photo file with the specified encoding
Finally we invoke the _emotionClient passing it the stream from the persisted photo

The result object contains a Scores class that looks like the following (from my mugshot):

The service returned a result. The result claims an 81.5% level of confidence that I'm happy based on the given image, what do you think? What you don't see is that I'm taking a selfie with Jeremy Foster -- so, yeah -- I was pretty happy!

Construction

I would be lying if I tried taking credit for any of the construction. I'm slightly embarrassed to admit that I opted out of building it, as I lack the carpentry skills needed to do a decent job. Instead, I asked a friend who just so happens to be awesome at carpentry. After persuading him with a bottle of single malt scotch whiskey, I had my magic mirror constructed and the results were amazing! Needless to say, I was excited to try it out.

What happened to my Thread.CurrentPrincipal

David Pine — Fri, 27 Jan 2017 00:00:00 GMT

Overview

Like the title claims, if you're using ASP.NET Core and expecting the Thread.CurrentPrincipal or ClaimsPrincipal.Current to be populated you'd be wrong. This is not the IPrincipal you're looking for. In this post we'll discuss what happened and what you need to do now. Additionally we'll cover all the peripheral benefits as a result of this change.

History

If you have ever done any .NET Framework development, you've probably seen the Thread class. You're probably familiar with the [Thread.CurrentPrincipal](https://msdn.microsoft.com/en-us/library/system.threading.thread.currentprincipal) member. This member of the Thread class is defined as follows:

public static IPrincipal CurrentPrincipal
{
    [System.Security.SecuritySafeCritical]  // auto-generated
    get
    {
        lock (CurrentThread)
        {
            var principal = (IPrincipal)CallContext.Principal;
            if (principal == null)
            {
                principal = GetDomain().GetThreadPrincipal();
                CallContext.Principal = principal;
            }
            return principal;
        }
    }

    [System.Security.SecuritySafeCritical]  // auto-generated
    [SecurityPermission(SecurityAction.Demand, Flags = SecurityPermissionFlag.ControlPrincipal)]
    set
    {
        CallContext.Principal = value;
    }
}

Gets or sets the thread's current principal (for role-based security).

Does anyone see the issue with this? Can you say, "publicly static mutable state, oh my"?! You should be alarmed. This property was never a good idea and today it simply doesn't belong. ASP.NET Core is not responsible for assigning this. You might not agree with that decision, but it is final.

Before diving into this, pop over to Microsoft.AspNetCore.Security -- Issue 332 for more of the back story.

Thread.CurrentPrincipal Today in ASP.NET Core

As part of the ASP.NET Core framework, the following middleware packages are provided:

[Microsoft.AspNetCore.Identity](https://github.com/aspnet/Identity)
[Microsoft.AspNetCore.Security](https://github.com/aspnet/Security)

If you opt-in to using this middleware and you provide a login page (or expose an external provider) you'd end up creating an instance of a ClaimsPrincipal that represents an authenticated user. Subsequent requests to the web server would be handed the cookie that holds the user's claims. However the Thread.CurrentPrincipal would not actually reflect the ClaimsPrincipal object that was created as the result of the login. In fact, it would simply be an instance of the GenericPrincipal implementation. Likewise, walking up to the ClaimsPrincipal.Current property and asking it for the current claims principal in context wouldn't give you what you might expect either. Additionally, the ClaimsPrincipal.Current internally relies on the Thread.CurrentPrincipal for its value.

public static ClaimsPrincipal Current
{
    get
    {
        return ClaimsPrincipal.s_principalSelector() ??
               ClaimsPrincipal.SelectClaimsPrincipal();
    }
}

private static ClaimsPrincipal SelectClaimsPrincipal()
{
    return Thread.CurrentPrincipal as ClaimsPrincipal ??
           new ClaimsPrincipal(Thread.CurrentPrincipal);
}

You might be asking yourself, "how do I access this value then?". If you're in the context of a controller then you already have access to it via the .User property. Otherwise, the answer is "dependency injection". Wherever you're in need of the identity for accessing claims, use constructor (.ctor) injection and give yourself the IPrincipal you need. If you're in the context of an action you might be tempted to use the [FromServices] attribute to inject the IPrincipal instance, but remember that this actually comes from the current user - which is already accessible via the controller's .User property.

Dependency Injection

ASP.NET Core made dependency injection (DI) a first class citizen, and it is so easy to use. The Startup.cs by convention has a ConfigureServices method where you'll register the dependencies. In the case of ASP.NET Core you'll need to do the following:

// This method gets called by the runtime. Use this method to add services to the container.
public void ConfigureServices(IServiceCollection services)
{
    services.AddSingleton<IHttpContextAccessor, HttpContextAccessor>();
    services.AddTransient<IPrincipal>(
        provider => provider.GetService<IHttpContextAccessor>().HttpContext.User);

    // ...
}

You might have noticed that we explicitly register the IHttpContextAccessor and corresponding implementation. This is necessary as that service is not registered for us. With that in place we can now specify that any class asking for an IPrincipal will be given the IHttpContextAccessor.HttpContext.User as the implementation. This is exactly what we needed. The exact same pattern is true for class libraries that want to leverage identity-based claim values from the ClaimsPrincipal implementation of the IPrincipal.

Example

using System.Security.Claims;
using System.Security.Principal;

public class SampleService : ISampleService
{
    private readonly ClaimsPrincipal _principal;

    public SampleService(IPrincipal principal) =>
        _principal = principal as ClaimsPrincipal;

    public Task ConsumeAsync()
    {
        var dobClaim = _principal?.FindFirst(ClaimTypes.DateOfBirth);
        // Take some action ...
    }
}

From the example above we can see how simple it is to use dependency injection. Simply define the IPrincipal as a .ctor parameter, store it in a field and consume it as needed.

But Why?

There are a lot of people who feel as though DI is overrated and that it is much easier to ask the Thread.CurrentPrincipal for its value. While that is easy, it is also risky...think about it. Since it is mutable anyone (even 3rd party libraries) can set it. Additionally, you avoid concerns about trying to synchronize static state between the Thread and ClaimsPrincipal classes. Scott Hanselman blogged about a similar issue nearly thirteen years ago!

One of the first benefits that comes to mind from this is the fact that with DI the code is unit-testable. It is extremely easy to mock out an IPrincipal to use for unit testing. Additionally, this alleviates all of the concerns about synchronization and reliability. The IPrincipal you're given is the principal you'd expect and it is fully populated accordingly.

Overriding ASP.NET Core Framework-Provided Services

David Pine — Tue, 14 Feb 2017 00:00:00 GMT

Overview

In .NET it's really easy to create your own interfaces and implementations. Likewise, it's seemingly effortless to register them for dependency injection. But it is not always obvious how to override existing implementations. Let's discuss various aspects of "dependency injection" and how you can override the "framework-provided services".

As an example, let's take a recent story on our product backlog for building a security audit of login attempts. The story involved the capture of attempted usernames along with their corresponding IP addresses. This would allow system administrators to monitor for potential attackers. This would require our ASP.NET Core application to have custom logging implemented.

Logging

Luckily ASP.NET Core Logging is simple to use and is a first-class citizen within ASP.NET Core.

In the Logging repository there is an extension method namely AddLogging, here is what it looks like:

public static IServiceCollection AddLogging(this IServiceCollection services)
{
    if (services == null)
    {
        throw new ArgumentNullException(nameof(services));
    }

    services.TryAdd(ServiceDescriptor.Singleton<ILoggerFactory, LoggerFactory>());
    services.TryAdd(ServiceDescriptor.Singleton(typeof(ILogger<>), typeof(Logger<>)));

    return services;
}

As you can see, it is rather simple. It adds two ServiceDescriptor instances to the IServiceCollection, effectively registering the given service type to the corresponding implementation type.

Following the rabbit down the hole

When you create a new ASP.NET Core project from Visual Studio, all the templates follow the same pattern. They have the Program.cs file with a Main method that looks very similar to this:

public static void Main(string[] args)
{
    var host = new WebHostBuilder()
        .UseKestrel()
        .UseContentRoot(Directory.GetCurrentDirectory())
        .UseIISIntegration()
        .UseStartup<Startup>()
        .UseApplicationInsights()
        .Build();

    host.Run();
}

Templates `Program.cs`


Empty	Starter Web	Web API

One thing that is concerning about a template like this is that the IWebHost is an IDisposable, so why then is this statement not wrapped in a using you ask? The answer is that the Run extension method internally wraps itself in a using. If you were wondering where the AddLogging occurs, it is a result of invoking the Build function.

[ Microsoft.AspNetCore.Hosting.WebHostBuilder ] 
    public IWebHost Build() ...
        private IServiceCollection BuildCommonServices() ...
            creates services then invokes services.AddLogging()

A few words on the Service Descriptor

The ServiceDescriptor class is an object that describes a service, and this is used by dependency injection. In other words, instances of the ServiceDescriptor are descriptions of services. The ServiceDescriptor class exposes several static methods that allow its instantiation.

The ILoggerFactory interface is registered as a ServiceLifetime.Singleton and its implementation is mapped to the LoggerFactory. Likewise, the generic type typeof(ILogger<>) is mapped to typeof(Logger<>). This is just one of the several key "Framework-Provided Services" that are registered.

Putting it together

Now we know that the framework is providing all implementations of ILogger<T>, and resolving them as their Logger<T>. We also know that we could write our own implementation of the ILogger<T> interface. Being that this is open-source we can look to their implementation for inspiration.

public class RequestDetailLogger<T> : ILogger<T>
{
    private readonly ILogger _logger;

    public RequestDetailLogger(ILoggerFactory factory,
                               IRequestCategoryProvider requestCategoryProvider)
    {
        if (factory == null)
        {
            throw new ArgumentNullException(nameof(factory));
        }
        if (requestCategoryProvider == null)
        {
            throw new ArgumentNullException(nameof(requestCategoryProvider));
        }

        var category = requestDetailCategoryProvider.CreateCategory<T>();
        _logger = factory.CreateLogger(category);
    }

    IDisposable ILogger.BeginScope<TState>(TState state)
        => _logger.BeginScope(state);

    bool ILogger.IsEnabled(LogLevel logLevel)
        => _logger.IsEnabled(logLevel);

    void ILogger.Log<TState>(LogLevel logLevel, 
                             EventId eventId, 
                             TState state, 
                             Exception exception, 
                             Func<TState, Exception, string> formatter)
        => _logger.Log(logLevel, eventId, state, exception, formatter);
}

The IRequestCategoryProvider is defined and implemented as follows:

using static Microsoft.Extensions.Logging.Abstractions.Internal.TypeNameHelper;

public interface IRequestCategoryProvider
{
    string CreateCategory<T>();
}

public class RequestCategoryProvider : IRequestCategoryProvider
{
    private readonly IPrincipal _principal;
    private readonly IPAddress _ipAddress;

    public RequestCategoryProvider(IPrincipal principal,
                                   IPAddress ipAddress)
    {
        _principal = principal;
        _ipAddress = ipAddress;
    }

    public string CreateCategory<T>()
    {
        var typeDisplayName = GetTypeDisplayName(typeof(T));

        if (_principal == null || _ipAddress == null)
        {
            return typeDisplayName;
        }

        var username = _principal?.Identity?.Name;
        return $"User: {username}, IP: {_ipAddress} {typeDisplayName}";
    }
}

If you're curious how to get the IPrincipal and IPAddress into this implementation (with DI) - I discussed it here briefly. It is pretty straight-forward. In the Startup.ConfigureServices method do the following:

public void ConfigureServices(IServiceCollection services)
{
    // ... omitted for brevity

    services.AddTransient<IRequestCategoryProvider, RequestCategoryProvider>();
    services.AddTransient<IHttpContextAccessor, HttpContextAccessor>();
    services.AddTransient<IPrincipal>(
        provider => provider.GetService<IHttpContextAccessor>()
                           ?.HttpContext
                           ?.User);
    services.AddTransient<IPAddress>(
        provider => provider.GetService<IHttpContextAccessor>()
                           ?.HttpContext
                           ?.Connection
                           ?.RemoteIpAddress);
}

Finally, we can <a href="https://github.com/aspnet/DependencyInjection/blob/dev/src/Microsoft.Extensions.DependencyInjection.Abstractions/Extensions/ServiceCollectionDescriptorExtensions.cs" target="_blank">Replace</a> the implementations for the ILogger<T> by using the following:

public void ConfigureServices(IServiceCollection services)
{
    // ... omitted for brevity
    services.Replace(ServiceDescriptor.Transient(typeof(ILogger<>), 
                                                 typeof(RequestDetailLogger<>)));
}

Notice that we replace the framework-provided service as a ServiceLifetime.Transient. Opposed to the default ServiceLifetime.Singleton. This is more or less an extra precaution. We know that with each request we get the HttpContext from the IHttpContextAccessor, and from this we have the User. This is what is passed to each ILogger<T>.

Conclusion

This approach is valid for overriding any of the various framework-provided service implementations. It is simply a matter of knowing the correct ServiceLifetime for your specific needs. Likewise, it is a good idea to leverage the open-source libraries of the framework for inspiration. With this you can take finite control of your web-stack.

Exploring C# 7

David Pine — Sun, 26 Mar 2017 00:00:00 GMT

Intro

Since we have all been actively celebrating the 20<sup>th</sup> anniversary of Visual Studio, it felt appropriate to post about C# 7! In this post we will explore the features that make C# 7 so promising. I've put together a demonstration C# 7 project, that is available here.

This post contains examples and details on five of the nine new C# 7 features.

Pattern matching
out variables
Tuples
Local functions
throw expressions

These are the remaining features, that I do not cover in this post.

ref locals and returns
More expression-bodied members
Generalized async return types
Numeric literal syntax improvements

Pattern Matching

With C# 7 we welcomed the concept of "patterns". This concept allows for the extraction of information when a variable is tested for a certain "shape" and matches a specified pattern. We're able to leverage the "shape" from which we matched on as a declared variable in scope, consuming it as we deem necessary. This is referred to as "dynamic" (or "method") dispatch.

<p> In computer science, dynamic dispatch is the process of selecting which implementation of a polymorphic operation (method or function) to call at run time. It is commonly employed in, and considered a prime characteristic of, object-oriented programming (OOP) languages and systems. <cite>Wiki - Dynamic Dispatch</cite>

Dynamic dispatch is nothing new to C#, and has been around forever. C# 7 exposes this functionality via constant and type patterns.

Constant Patterns

Constant pattern null, similar to (obj == null).

<p> The "is expression" has been expanded

public void IsExpression(object obj)
{
    if (obj is null) // Constant pattern "obj is null"
    {
        return;
    }
}

Type Patterns

Look closely at this syntax. This is where we start mixing metaphors. Prior to C# 7 we could use the "is" expression to do simple type assertions obj is [type]. Additionally, we all know how to declare a variable int i. This new syntax merges these concepts together and is more compound and expressive.

public void IsExpression(object obj)
{
    // (obj is int i)
    // "obj is int"     // type assertion "typically evaluates type compatibility at run time"
    //        "int i"   // declaration

    if (obj is int i) // Type pattern "obj is int i"
    {
        // We can then use the "i" (integer) variable 
    }

    // Note, the variable "i" is also available in this scope.
    // This is in fact by design, more on that out the "out variable" section 
}

<p> The "switch statement" has been generalized

The when keyword has also been extended, now it not only applies to the catch statement but also the case labels within a switch statement. Consider the following classes:

class Shape
{
    protected internal double Height { get; }

    protected internal double Length { get; }

    protected Shape(double height, double length)
    {
        Height = height;
        Length = length;
    }
}

class Circle : Shape
{
    internal double Radius => Height / 2;

    internal double Diameter => Radius * 2;

    internal double Circumference => 2 * Math.PI * Radius;

    internal Circle(double height, double length) 
        : base(height, length) { }
}

class Rectangle : Shape
{
    internal bool IsSquare => Height == Length;

    internal Rectangle(double height, double length) 
        : base(height, length) { }
}

Now imagine that we have a collection of these Shape objects, and we want to print out their various details - we could use "pattern matching" as such:

static void OutputShapes(IEnumerable<Shape> shapes)
{
    foreach (var shape in shapes)
    {
        // Previously, this was not permitted. Case labels had to be concrete
        // such as enums, numerics, bools, strings, etc.
        switch (shape)
        {
            case Circle c:
                WriteLine($"circle with circumference {c.Circumference}");
                break;
            case Rectangle s when (s.IsSquare):
                WriteLine($"{s.Length} x {s.Height} square");
                break;
            case Rectangle r:
                WriteLine($"{r.Length} x {r.Height} rectangle");
                break;
            default:
                WriteLine("This is not a shape that we're familiar with...");
                break;
            case null:
                throw new ArgumentNullException(nameof(shape));
        }
    }
}

As you can see, we are able to more easily reason about the specific shape in context. For example, with each iteration of our collection we switch on the shape. If the shape is an instance of the Circle subclass, we'll execute the case label "Circle" and we get the instance declared as its type in the variable c. Likewise, if the shape is a Rectangle and that rectangle s just so happens to also be a square when (s.IsSquare) evaluates to true - we will then execute the square case label. If the shape is an instance of a Rectangle but not a square, we execute the "Rectangle" case label. Notice we still have default fall-thru. Finally, we can also have a "null" case label.

`out` variables

.NET developers are more than familiar with the Try* pattern, but as a refresher this is what it looks like. Imagine we are trying to parse a System.String input value as a System.Int32. Imagine that the consumer doesn't really care if it is parsed, they're fine with a default(int) if it fails.

public int ToInt32(string input)
{
    int result;
    if (int.TryParse(input, out result))
    {
        return result;
    }

    return default(int);
}

Let's quickly recap this. First, we declare a variable namely result. We then invoke the int.TryParse which returns a bool whether or not the parse was successful. If true then the declare result variable is not equal to the parsed int value. If the input was "12", then result would be 12. If the input was "Pickles", then the return from the invocation to the ToInt32 would be 0 as int.TryParse would return false.

Now with C# 7 we can declare our out variable inline as follows:

public int ToInt32(string input)
{
    // Note: the declaration is inline with the out keyword
    if (int.TryParse(input, out int result))
    {
        return result;
    }

    return default(int);
}

The scope of the result variable is identical to the previous example, as it actually "leaks" out to the if statement. We can re-write this even more expressively:

public int ToInt32(string input) => int.TryParse(input, out var result) ? result : result;

A few things you might notice. First, this is now a single line as we can express this with the lambda operator. We leverage the ternary operator as well. Additionally, we can use the var keyword for our declaration. And since the result variable is in scope we can use it as both return cases. If unable to be parsed, it is in fact a default(int) anyways.

Tuples

Most developers are familiar with System.Tuple<T[,T1...]>. This class has served us well all the while it has been around. One of the advantages is that it exposes readonly fields - from the values that it is instantiated with. This was also great for equality comparisons and even using the tuple as a dictionary key.

In C# 7 we have a new syntax for expressing tuples. Enter the ValueTuple, and as the name implies - this is a struct instead of a class. There are obvious performance gains from using a light-weight value-type over the allocation of a class.

void LegacyTuple()
{
    var letters = new Tuple<char, char>('a', 'b');
    
    // Values were accessible via these Item* fields.
    var a = letters.Item1;
    var b = letters.Item2;
}

This wasn't overly exciting from an API perspective, as the field names do not really imply anything about their intention.

void ValueTuple()
{
    var letters = ('a', 'b');
    var a = letters.Item1;
    var b = letters.Item2;

    // Note: ToTuple extension method
    var systemTuple = letters.ToTuple();
    var c = systemTuple.Item1;
    var d = systemTuple.Item2;
}

You might notice that the syntactic sugar is pouring over this new feature. This is referred to as a "tuple literal". We dropped the entire new keyword usage, as well as specifying the types. They are all inferred and in fact known, IntelliSense proves this immediately. But we still have the issue of these tuples not being very API friendly. Let's explore how we can give them custom names.

void MoreValueTuples()
{
    var lessonDetails = 
        (Subject: "C# Language Semantics", Category: Categories.Programming, Level: 300);

    // Note: IntelliSense now hides Item1, Item2 and Item3
    // Instead we are provided with the following:

    var subject = lessonDetails.Subject;    // string
    var category = lessonDetails.Category;  // Categories [enum]
    var level = lessonDetails.Level;        // int
}

Deconstruction

Now that we see how we can instantiate a ValueTuple, let's take a look at how we can declare one for usage.

void DeconstructionExamples()
{
    var lessonDetails = 
        (Subject: "C# Language Semantics", Category: Categories.Programming, Level: 300);
    
    // We can deconstruct in three various ways
    // First, the fully qualified type
    (string subject, Categories category, int level) = lessonDetails;
    
    // Next using the var keyword per named declaration
    (var subject, var category, var level) = lessonDetails;

    // Finally, omitting any type declaration and using var wholeheartedly
    var (subject, category, level) = lessonDetails;
}

There are often questions about how deconstruction is implemented, and whether or not it is ordinal based. For the ValueTuple it is in fact ordinal based. However, note that deconstruction is not actually limited to tuples. With C# 7 any object that defines a public void Deconstruct method can be deconstructed. Consider the following:

class Person
{
    private readonly (string First, string Middle, string Last) _name;

    private readonly DateTime DateOfBirth _dateOfBirth;

    public Person((string f, string m, string l) name, DateTime dob)
    {
        _name = name;
        _dateOfBirth = dob;
    }

    public void Deconstruct(out double age, 
                            out string firstName,
                            out string middleName, 
                            out string lastName)
    {
        age = (DateTime.Now - _dateOfBirth).TotalYears;
        firstName = _name.First;
        middleName = _name.Middle;
        lastName = _name.Last;
    }
}

Now that the Person is defined with this Deconstruct method, we can deconstruct it following the same ordinal based semantics.

void DeconstructNonTuple()
{
    var person = new Person(("David", "Michael", "Pine"), new DateTime(1984, 7, 7));

    (int age, string first, string middle, string last) = person;

    // Note: to partially deconstruct you can ignore a specific ordinal by using the _
    // This does not actually naming the ordinal variable, but truly ignoring it.

    var (_, _, _, _) = person;          // Ignore all, not very useful
    var (_, firstName, _, _) = person;  // Cherry-pick first name
}

Comparing Anonymous `object` vs. `ValueTuple`

At first glance tuples look almost like anonymous objects. They are in fact very different. An anonymous object is actually a reference type whereas a ValueTuple is a struct - value type. Also, you can only return an anonymous object from a method as an object which isn't very API friendly. Within a fluent LINQ chained method anonymous objects are great and will still be normal for projection.

Local Functions

At first glance, local functions seem a bit odd. I've heard people say, "this method is starting to look like a class". At first, I was one of these people too. Once you get used to the idea and see the benefits it really does make sense. Here is a quick comparison of the two, note the benefits of local functions as they compare to lambdas.

	Lambda(s)	Local Function(s)	Details
Generics	❌	✅	Local functions allow for the use of generics
Iterators	❌	✅	The `yield` keyword is valid within local functions
Recursion	❌	✅	Local functions support recursion
Allocatey	✅	❌	Delegates require an `object` allocation
Potential Variable Lifting	✅	❌	Implicitly captured closure is non-existent

It is vital to understand that local functions are <strong>not</strong> a replacement for Action<T[,T1...]> or Func<T[,T1...]>. These delegate declarations are still needed as parameters to enable lambda expression arguments. If you see the #notasugly hashtag, this was coined by Mads Torgersen.

More efficient

When using local functions, there is no object created - unlike delegates that require an object for it to be used. Likewise, local functions help to alleviate another issue with lambdas in that they do not need to implicitly capture a variable longer than it is potentially needed. In C# lambdas capture values by reference, meaning that garbage collection may not be able to correctly clean up code that is "allocatey".

Declaration

With local functions, the declaration of the local function can actually occur after the return statement - as long as it is within the method body in which it is consumed. If you're familiar with some of the implementations of the LINQ extension methods on IEnumerable<T>, you would know a lot of the methods are defined with argument validation followed by the instantiation of "Iterator" classes, where these classes do the actual work.

Because of deferred execution, iterators do not actually execute validation logic until they are iterated - for example invoking .ToList(), .ToArray(), or simply using them in a foreach statement. Ideally, we would like our iterators to "fail-fast" in the event of being given invalid arguments. Let's imagine that the .Select extension method was implemented as follows:

public static IEnumerable<TResult> Select<T, TResult>(this IEnumerable<T> source, 
                                                           Func<T, TResult> selector)
{
    if (source == null) throw new ArgumentNullException(nameof(source));
    if (selector == null) throw new ArgumentNullException(nameof(selector));

    foreach (var item in source)
    {
        yield return selector(item);
    }
}

Since this method is written as an iterator, the validation is skipped until it's iterated. With C# 7 we can use local function to get both "fail-fast" validation and the iterator together.

public static IEnumerable<TResult> Select<T, TResult>(this IEnumerable<T> source, 
                                                           Func<T, TResult> selector)
{
    if (source == null) throw new ArgumentNullException(nameof(source));
    if (selector == null) throw new ArgumentNullException(nameof(selector));

    return iterator();

    IEnumerable<TResult> iterator()
    {
        foreach (var item in source)
        {
            yield return selector(item);
        }
    }
}

`throw` expressions

Leveraging some pre-existing C# functionality - null coalescing, we can now throw when a value is evaluated as null. A common validation mechanism is to throw if an argument is null. Consider the following:

class LegacyService : IService
{
    private readonly IContextProvider _provider;

    public LegacyService(IContextProvider provider)
    {
        if (provider == null)
        {
            throw new ArgumentNullException(nameof(provider));
        }

        _provider = provider;
    }
}

With C# 7 we can simplify this with the throw expression.

class ModernService : IService
{
    private readonly IContextProvider _provider;

    public ModernService(IContextProvider provider)
    {
        _provider = provider ?? throw new ArgumentNullException(nameof(provider));
    }
}

If the given provider argument is null we'll coalesce over to the throw expression.

From C# 6 to C# 7, then and now

I have a presentation that I have been fortunate enough to give at some regional conferences. One of these occasions was recorded, and I felt it made sense to share it here - Enjoy!!

Further Reading

What's new in C# 7

TypeScript - JavaScript Reimagined

David Pine — Tue, 02 May 2017 00:00:00 GMT

First things First

JavaScript is the world's third most common programming language today. JavaScript was created by Brendan Eich in about ten days. It might seem odd that the previous two sentences not only exist, but go together...yet it is true! JavaScript runs seemingly everywhere and applications written in this language are only getting larger.

JavaScript was perhaps intended for 100, maybe up to 1,000 lines of code and now with regularity people are building 100,000 line apps, if not 1,000,000 line apps. <cite>Anders Hejlsberg</cite>

"The Good Parts"

Douglas Crockford authored a book "JavaScript: The Good Parts", sadly it was a rather short book. If you're a JavaScript developer, knowing "the good parts" is great - but knowing the limitations and shortcomings of a language is even more powerful. Sometimes it feels like JavaScript is a hammer and not every problem we're trying to solve is a nail. NodeJs is a great example of this in my opinion -- because I'm a .NET developer, but I digress... If you want a good laugh watch Gary Bernhardt's WAT video, go ahead -- I'll wait! In all seriousness, JavaScript is a great programming language for countless reasons, but it is easy to poke fun at.

Mental Model

I met a fellow technical public speaker who is a well respected JavaScript developer. He was arguing his hatred for TypeScript. There are several key takeaways from the debate that I think will stick with me for a while.

Learn it

You should learn the JavaScript programming language

I already know JavaScript (but I really don't know JavaScript) -- I would never consider myself an expert or a guru! However, I write TypeScript nearly every single day that I develop. Some of the aforementioned names are among the very few who might be considered as such. I recall that when this part of the conversation was encountered, we came up with an analogy.

Not all JavaScript developers are Tour de France champions (or contenders)

This was the reoccurring analogy and I agreed with it wholeheartedly. That is why I think that TypeScript is like "training wheels" for JavaScript developers. That is not at all a bad thing! Just look at what you can do with "training wheels".

Seriously though, with that fact that we are not compilers and we cannot predict certain behaviors that occur in the "wild west" of JavaScript -- we should rely on tooling to help. It is simply a pragmatic approach to developing with a true sense of reliability and consistency. Training wheels provide you with the confidence and security. Once your TypeScript is compiled to JavaScript, the training wheels are removed and your code is ready to brave the new world!

TypeScript

I could never compete with the TypeScript site. They have a beautifully composed tutorial, handbook and rich set of documentation. If that is what you're looking for - by all means go check it out. If you'd like to hear more on my thoughts - keep reading.

All valid JavaScript is also valid TypeScript, as TypeScript is a superset of JavaScript. TypeScript allows you as a developer to program in the latest version of the ECMAScript standard, while still being about to target all the way back to ES3. Upon compilation, your code is pure JavaScript and all the type notations are removed. The static type system is only applicable when working with TypeScript related files.

Extensions Explained

I initially had some confusion about the various file extensions. It was obvious what .ts and .js files were, but what were these .map and .d.ts files? Ironically, .map files have been around since CoffeeScript and are nothing new. They map JavaScript files to their corresponding abstractions, in the case of TypeScript - they map .ts to .js files. The .d.ts files are known as type definitions. They define the public surface area or API if you will, of a given library. More detail here .

Enough Sales Pitch - Show me some code

The TypeScript playground is an amazing place, since it has a side-by-side of the input TypeScript and the resulting JavaScript. This is an excellent place to learn how TypeScript works and what it is capable of. I always find it interesting seeing how certain things are implemented. Take for example an enum. In most languages it's easy to take this for granted, the same is true with TypeScript - but seeing how the resulting JavaScript is really something special.

export enum DayOfWeek {
    Sunday,
    Monday,
    Tuesday,
    Wednesday,
    Thursday,
    Friday,
    Saturday
}

This seems like a very clean declaration of an enum, right?! We know that DayOfWeek.Monday would have a value of 1, and DayOfWeek.Friday would then be 5 for example. But let's have a look at the JavaScript output.

var DayOfWeek;
(function (DayOfWeek) {
    DayOfWeek[DayOfWeek["Sunday"] = 0] = "Sunday";
    DayOfWeek[DayOfWeek["Monday"] = 1] = "Monday";
    DayOfWeek[DayOfWeek["Tuesday"] = 2] = "Tuesday";
    DayOfWeek[DayOfWeek["Wednesday"] = 3] = "Wednesday";
    DayOfWeek[DayOfWeek["Thursday"] = 4] = "Thursday";
    DayOfWeek[DayOfWeek["Friday"] = 5] = "Friday";
    DayOfWeek[DayOfWeek["Saturday"] = 6] = "Saturday";
})(DayOfWeek || (DayOfWeek = {}));

If you look at this look enough, you'll see that it's a rather simple solution. It is essentially a reverse map, where properties are assigned to from their indexes. On the DayOfWeek instance, we declare and assign property Sunday equal to 0. Likewise, we declare and assign property 0 equal to the value Sunday, etc...

Type Aliases, Generics and Mapped Types

I recently learned about the keyof operator in TypeScript, and wow is it powerful! Let's consider the following mutable object.

export class MutableDataBag<T> {
    public data: T;
    public name: string;

    constructor(private id: number) { }
}

This is a rather simple object. It defines several members that are public and assignable, namely the data and name members. Imagine that we decide that we actually expose this structure from an API - but we want it to be immutable, i.e.; readonly. Enter "mapped types".

export type Readonly<T> = {
    readonly [P in keyof T]: T[P];
}

The type alias of Readonly takes on an generic of type T, furthermore it defines that all the members of type T are accessible as readonly members. This leverages the keyof operator in which P is accessible so long as it is a member of T (key of T). So, now we can return a Readonly<MutableDataBag<T>> from our API and rest assured knowing that TypeScript prevents it's members from being written to.

Conclusion

This is literally just the tip of the iceberg (or even less). TypeScript has truly made JavaScript tolerable. TypeScript answers so many questions and addresses so many concerns that it's hard to justify not using...if you're not using TypeScript, there are other options out there. Pick your poison!!

Resources

How to organize an amazing technical conference

David Pine — Sat, 24 Jun 2017 00:00:00 GMT

Story Time

This is my third year organizing MKE DOT NET, so I've been accumulating plenty of interesting stories. Last year I was fortunate enough to have convinced Scott Hanselman to be our keynote speaker. Yes, "the Scott Hanselman" - arguably the worlds most influential person in the tech industry. I was his ride to and from the airport and the conversations we had actually led to several key changes. As a result MKE DOT NET will be even better than ever before!

Scott said:

Had I looked at the lineup of speakers prior to agreeing, I would have declined

My mind immediately started racing with thoughts like "does he only want to speak with well-known speakers" or "is this too small of a conference for such a celebrity?". None of these thoughts were the least bit accurate. In fact, the reason was simple "we were not inclusive enough". Honestly this was something that I didn't even think about. I was driving Scott to the hotel where he was going to stay. The hotel was also the place where the conference was to be held.

No...he requested that I give him a guided tour. He wanted to see the room layouts, he wanted to test equipment, ensure lighting, sound, connectivity, etc. We actually ended up reorganizing the entire layout of the keynote room as well as changing the number of projectors. His "perfectionist" side was shining through and it was really resonating with the team. Clearly he has done this a few more times than we have!

One of his initial comments was hysterical:

This kind of looks and smells like grandmas house

He was referring to the decor of the hotel (very 60's) and that the halls had a stale scent of mildew (the hotel has a water-park in it). Having just taken a sip of water, I nearly spit it out of my mouth in laughter - finally someone said what we had all been thinking! This resulted in a change of venue for 2017 and years to come. We'll be at Potawatomi Hotel & Casino this year. The new joke is obviously that it will now smell like cigarette smoke instead.

Inclusion

The truth was simple. MKE DOT NET 2016 only had one woman speaker and ironically she was speaking about Diversity. We were ready to lick our wounds and rise above it. I'm so proud to be part of this change and happy to communicate that MKE DOT NET now takes an active approach to ensure a more diverse speaker lineup.

This year, we started leveraging PaperCall.io as our event management system. It allowed us to make the speaker voting anonymized - but you're probably wondering how that helps with diversity. It actually doesn't and that would be naive to assume so. What we did was invite Ashley Powell and Samrat Saha (both MKE DOT NET speaker alumni) to join our technical committee. We loved that they were both eager to help and happily joined the team. They both have been a major part of the entire process and helped with the CFP outreach efforts. We believe this led to more submissions from their networks, ultimately leading to a more inclusive speaker lineup.

Of the 24 sessions and including the keynote, we are proud to have eight women speakers this year! If you're a numbers person - that is an <strong>800% increase</strong> year-over-year and we plan on doing even better as we evolve. We are actively making our conference as inclusive as possible - and we celebrate the communities participation.

Evolution

We are only going to grow and learn and become a better more cohesive unit as time marches forward. We are evolving! The people who make up the team are so passionate about bringing forth their visions for a better Midwest technical community. But that isn't without conflict or disagreement. In fact our team is great at hashing things out. Not every idea is the best! Knowing how to work together and encouraging ideas is key. We foster an environment which breeds creativity but also bases our direction on results. The team shares a vision and we strive to make that vision obvious.

Community

Of course none of this would be possible without our strong community. I'm proud to play my part and contribute what I can, and I'm humbled to be immersed in such a rich pool of technical knowledge and passion. It is inspiring to see the things we're doing and even more so to be involved! Often the hallways of a technical conference are the stomping grounds for some of the best bits of conversation. In my regional speaking engagements this year I'm hearing just how amazing we are in the Midwest time and time again. I'm grateful for all of these awesome success stories.

Tools

Being that the entire team cannot always be in the same place at the same time - it is vital to leverage tools that allow everyone on the team to work together. This will serve as a simple listing of some of things that we have used along the way.

PaperCall.io - for CFP and speaker selection process
Eventbrite - for event ticketing/sales
Google Docs/Sheets/Forms - for internal documentation
Stickies.io - for organizing schedule
Trello Boards - for organizing ideas
Zoom.us - for video conferencing
Adobe Illustrator - designing logos, creating illustrations and icons
Adobe Photoshop - art directing photos, creating images, correcting color
Twitter - for social networking

A word on the website, we use for source control GitHub - and it is actually a static website. It uses HarpJs which sits atop NodeJs. Updates are seamless and fast with Visual Studio Code - .

Closing Story

I spoke at Indy.Code() in Indianapolis back in March, 2017. It was a great experience and the folks over at Amegala really know how to organize a technical conference! Anyways, prior to one of my talks I was asking the crowd a little about technical conferences in Indianapolis. I was told that Indy.Code() was the first major conference in seven years. When I asked them what they do to fill that void, three of them immediately shouted out.

We travel to Milwaukee, WI in the fall for MKE DOT NET - it's a technical conference!

What a small world, hey! They were extremely excited to learn my role...and I too shared in their excitement. For in that moment I knew that all the hard work was paying off.

Thank you

A sincere thank you is in order for everyone who makes this possible. Thank you to Maria Naggaga for not only being willing to speak at MKE DOT NET, but responding to my ask within minutes - stating that she would be honored! Thank you to the community, the speakers, those who submit who don't get to speak, those of you who attend. Thank you to Centare for supporting all these efforts year-after-year and the investment back into the community. Thank you to all the sub-committees of MKE DOT NET that give their brilliance and support taking on tasks like, marketing, driving attendance, seeking sponsorship, creating and maintaining the website, deciding on scheduling, venue, meals, logistics, all the countless planning efforts - thank you. Anyone else that I couldn't think of, thank you!

Perusing C# 7.1

David Pine — Sat, 29 Jul 2017 00:00:00 GMT

Earlier this year in March -- Visual Studio 2017 was released. With this the world was given C# 7, checkout my post on Exploring C# 7. In this post we will peruse C# 7.1, the first incremental release while C# 8 is being fleshed out.

Async Main <a target="_blank" href="https://github.com/dotnet/csharplang/issues/97"></a>

Since the release of C# 5, developers have either embraced the async and await keywords or fumbled along the way feebly attempting to comprehend them. Fear not, you're not alone. Many others have been just as confused, but that's not to say that the language didn't make major strides towards simplifying your development efforts. In fact, I love asynchronous programming and C# makes me very happy with its implementation!

Many developer advocates set forth on a journey of biblical proportions -- progressing through mountains of nay-sayers, focusing on craftsmanship and technical evangelism. Among these advocates Stephen Toub and Stephen Cleary rose toward the top. Blogging and helping us along the way. With their help emerged rules and guidelines, a comprehensive set of best practices for using these language features. One best practice is as follows:

Instead of Task.Result or .Task.Wait(), use await

Prior to C# 7.1 developers who wrote console applications were forced to deviate from this guideline. We were forced to use .Result or .Wait(). Consider the following:

public static void Main()
{
    var httpClient = new HttpClient();
    var result = httpClient.GetAsync("some/url").Result;

    // Another common alternative was using the get awaiter / result.
    result = httpClient.GetAsync("some/url").GetWaiter().GetResult();

    // Consume the result...
}

With C# 7.1, we can leverage Async Main.

public static async Task Main()
{
    var httpClient = new HttpClient();
    var result = await httpClient.GetAsync("some/url");

    // Consume the result...
}

This feature extends the previous four possible entry points to their Task and Task<int> based equivalents. Now the following entry points are valid:

static Task Main() { }                      // static void Main() { }
static Task<int> Main() { }                 // static int Main() { }
static Task Main(string[] args) { }         // static void Main(string[] args) { }
static Task<int> Main(string[] args) { }    // static int Main(string[] args) { }

With this task-based approach the new entry points simply provide that "feels good" approach to development.

`default` Expression <a target="_blank" href="https://github.com/dotnet/csharplang/issues/102"></a>

The default keyword has been around forever. It was used to tell the compiler give me the "default" value for the given type.

var number = default(int);      // 0
var date = default(DateTime);   // DateTime.MinValue
var obj = default(object);      // null

This was also used for generics, for example when the type of T is used we could return default(T).

public static T TryPeekOrDefault<T>(this ConcurrentQueue<T> queue)
{
    if (queue?.TryPeek(out var result) ?? false)
    {
        return result;
    }

    return default(T);
}

Likewise, the default keyword was used in the switch statement as well -- and signified the default case label. If all other cases were not executed, the default case would be.

switch (dayOfWeek) 
{
    case DayOfWeek.Monday:
        return "Ugh... off to work again";
    case DayOfWeek.Friday:
        return "Excitement sets in...";
    
    default:
        return string.Empty;
}

Now, with C# 7.1 the compiler will use type inference to simplify the default expression (sometimes referred to as default literals). So we could declare an int and assign it to default without passing the type int:

int number = default;   // 0
Guid guid = default;    // 00000000-0000-0000-0000-000000000000

Not only can the type be inferred from the declaration but also the literal expression:

var number = isLucky ? 7 : default; // when 'isLucky' is false number is 0

The great news is that this feature is for the entire type-system, not just int's . You can now use the default keyword in all sorts of places. You can use it to check against a value, or to pass it as an argument.

public int Sum(params int[] numbers)
{
    if (numbers is default || numbers.Length == default)
    {
        return default; // Returns 0
    }
}

// Pass in default. This is null for int[].
var sum = Sum(default);
if (sum == default)
{
    // Take an action when sum is 0.
}

Tuple Projection Initializers <a target="_blank" href="https://github.com/dotnet/csharplang/issues/415"></a>

I detailed the introduction of tuples in my Exploring C# 7 post. Tuples are an amazing addition to the C# language and are extremely powerful. With its initial implementation however, there was something that was lacking. Tuple literals lacked the ability to infer names, now with C# 7.1 -- this is no longer a limitation.

With tuple projection initializers our C# tuple literals are simplified and effectively DRY, as the redundancies of duplicating the field names are inferred.

var firstName = "David";
var lastName = "Pine";
var dateOfBirth = new DateTime(1984, 7, 7);

// C# 7.0, required "explicit names"
var person = (firstName: firstName, lastName: lastName, dateOfBirth: dateOfBirth);
var fn = person.firstName;      // "David"
var ln = person.lastName;       // "Pine"
var dob = person.dateOfBirth;   // 7/7/1984

// C# 7.1, allows "inferred names"
person = (firstName, lastName, dateOfBirth);
fn = person.firstName;          // "David"
ln = person.lastName;           // "Pine"
dob = person.dateOfBirth;       // 7/7/1984

Pattern-matching with Generics <a target="_blank" href="https://github.com/dotnet/csharplang/issues/154"> </a>

With C# 7.0, pattern-matching was introduced -- I love talking about it and showing off what it can do! In my opinion it solves a lot of issues with type assertions and makes complex decision trees more legible and comprehensive. However, when it was introduced it didn't correctly support generics. With C# 7.1, that has changed.

Consider the following:

public class Animal { }

public class Dog : Animal
{
    public Breed Breed { get; }
}

public void Interact<TAnimal>(TAnimal animal)
    where TAnimal : Animal
{
    if (animal is Dog dog)
    {
        // Play fetch with dog
    }

    switch (animal)
    {
        case Dog d when (d.Breed == Breed.LabradorRetriever):
            // Feed dog, the let 'em outside
            break;
    }
}

This was not actually possible, in fact it wouldn't even compile. Ignoring the scoping issue, as the dog variable is declared twice within the same scope -- we'd end up with the following compilation error:

An expression of type TAnimal cannot be handled by a pattern of Dog.

You could use the as operator:

var dog = animal as Dog;
if (dog != null) 
{
    // Play with man's best friend...
}

But that isn't really pattern-matching. The limitation that exists is due to explicit type conversions and open types; however, the design specification is changing as follows in the bold area:

Certain combinations of static type of the left-hand-side and the given type are considered incompatible and result in compile-time error. A value of static type E is said to be pattern compatible with the type T if there exists an identity conversion, an implicit reference conversion, a boxing conversion, an explicit reference conversion, or an unboxing conversion from E to T, <strong>or if either E or T is an open type.</strong> It is a compile-time error if an expression of type E is not pattern compatible with the type in a type pattern that it is matched with.

References

<a target="_blank" href="https://github.com/dotnet/roslyn">Roslyn, The .NET Compiler Platform</a>
<a target="_blank" href="https://github.com/dotnet/csharplang">C# Language Design</a>

Demystifying .NET Standard

David Pine — Wed, 16 Aug 2017 00:00:00 GMT

Intro

Monday, August 14<sup>th</sup> was an amazing day to be a .NET developer! As the world celebrates another triumphant series of announcements from Microsoft, there is still confusion amongst the masses.

What is this .NET Standard thing? What does it mean to target .NET Standard versus .NET Core, or even the .NET Framework? As a developer, what .NET should I target and why? Are Portable Class Libraries (PCLs) dead? <cite>Developer Community</cite>

All of these questions have already been answered, you just have to know where to look. In this post I will provide some invaluable resources and educate those of you who are still confused.

Announcements

Here are all the recent announcements, feel free to spend some time checking them out -- be sure to come back.

Let's start by answering all these common questions.

`[.NET Standard](https://docs.microsoft.com/en-us/dotnet/standard/net-standard/)`

If the name Immo Landwerth doesn't ring a bell, perhaps @terrajobst will? Regardless of whether you've heard of him before -- you'd be wise to remember him now. He is a program manager for Microsoft and has a huge part in the .NET ecosystem as a whole. Immo has a .NET Standard video series on YouTube and if you do not have time to read this post, by all means watch his videos.

.NET Standard is a specification. It represents a set of APIs that all .NET platforms have to implement. <cite>Immo Landwerth</cite>

Often, the .NET Standard is mistaken for a runtime. Consider the name .NET Standard at face value, it has the word "standard" in it...because it is not a framework or a core runtime.

.NET Standard isn't a runtime, it's a version interface - a list of methods you can use under many different ".NETs". <cite>Scott Hanselman</cite>

As true with all standards (or specifications), implementations can either be compliant or non-compliant. At this point in time there are four .NET implementations that are .NET Standard 2 compliant. They are as follows, .NET Core, .NET Framework, Mono and Xamarin. Below is a more comprehensive listing of all the .NET platforms and their corresponding standard that they implement.

The .NET Standard Version Table

.NET Standard	1.0	1.1	1.2	1.3	1.4	1.5	1.6	2.0
`.NET Core`	1.0	1.0	1.0	1.0	1.0	1.0	1.0	2.0
`.NET Framework`	4.5	4.5	4.5.1	4.6	4.6.1	4.6.1	4.6.1	4.6.1
`Mono`	4.6	4.6	4.6	4.6	4.6	4.6	4.6	5.4
`Xamarin.iOS`	10.0	10.0	10.0	10.0	10.0	10.0	10.0	10.14
`Xamarin.Mac`	3.0	3.0	3.0	3.0	3.0	3.0	3.0	3.8
`Xamarin.Android`	7.0	7.0	7.0	7.0	7.0	7.0	7.0	7.5
`Universal Windows Platform`	10.0	10.0	10.0	10.0	10.0	vNext	vNext	vNext
`Windows`	8.0	8.0	8.1
`Windows Phone`	8.1	8.1	8.1
`Windows Phone Silverlight`	8.0

For example, we can see the .NET Framework 4.5 is an implementation of .NET Standard 1.1. This means that if you're to author a .NET Standard class library and you target 1.1 of the standard, it can run on .NET Core 1.0, .NET Framework 4.5, Mono 4.6, etc... you get the point now I'm sure.

The Trade-off

There is a bit of a trade-off though that you should consider. With every version of the .NET Standard there is an inverse relationship to the number of implementations. The higher the version of the .NET Standard, the more APIs you have access to. However, there are fewer implementations that exist for higher versions of the .NET Standard.

It is typically advised that you target the lowest version of the standard that you can get away with. This allows your code to run in more places, as there are more implementations of lower versioned standards. Portable Class Libraries (or PCLs) have been replaced by the .NET Standard. If you're like me, you probably want the latest and greatest -- the fullest set of APIs...and that is ok. As long as you control the environment in which it's consumed, great!

`.NET` API Explorer

Microsoft has been hard at work, and their documentation teams have been putting together some incredibly useful ways to consume documentation. As a developer, I typically rely on StackOverflow as a source of truth -- however, I have been finding myself spending more time on the official documentation sites. A big 👍 to the team for making the .NET docs so much better than before. They even have a .NET API Explorer. This is immensely powerful -- in a matter of seconds I can quickly explore APIs and determine if something is lacking.

`[.NET Core](https://docs.microsoft.com/en-us/dotnet/core/)`

.NET Core is a general purpose development platform maintained by Microsoft and the .NET community on GitHub. It is cross-platform, supporting Windows, macOS and Linux, and can be used in device, cloud, and embedded/IoT scenarios.

The obvious advantages are that .NET Core is cross-platform and open source. Unlike .NET Framework that is neither of those two things.

`[.NET Framework](https://docs.microsoft.com/en-us/dotnet/framework/)`

If you have been a .NET developer for more than a few years, then you should already be familiar with the .NET Framework. This is what you have been developing on and targeting forever. However, with the introduction of .NET Standard and .NET Core, that is likely to change. You no longer have to limit your OS or platform to Windows.

`.NET Foundation`

With all the .NET terms flying around the web, it felt appropriate to throw another one at you.

The .NET Foundation is an independent organization to foster open development and collaboration around the .NET ecosystem. It serves as a forum for community and commercial developers alike to broaden and strengthen the future of the .NET ecosystem by promoting openness and community participation to encourage innovation. <cite>www.dotnetfoundation.org</cite>

Be sure to visit their site and get involved!

Conclusion

The .NET ecosystem is rapidly evolving! With open source and cross-platform being two key priorities, you're in good hands. When developing for .NET be familiar with what version of the .NET Standard suits your needs -- and target accordingly.

Resources

xUnit Roslyn Analyzers

David Pine — Sat, 11 Nov 2017 00:00:00 GMT

import { Tweet } from '@astro-community/astro-embed-twitter';

Intro

At my day job, I wear many hats. I'm currently wearing the "upgrade our team's tooling" hat. <strong>I counted 99</strong> *.xproj and project.json based projects spanning four repositories that need to be updated to the revitalized *.csproj project format. With this the team can upgrade to the latest version of Visual Studio (finally upgrading to 2017 from 2015) and start taking advantage of the following:

Supported tooling, no longer on preview tooling bits
Allows us to explore C# 7 (and peruse C# 7.1) with production code
Leverage the latest SDK and .NET Core CLI
Other obvious reasons
And so on...

Upgrading tooling is not always glamorous, but there are times that I find myself excited. I thoroughly enjoy learning about the new tooling innovations and efforts around simplifying the development work-flow, especially when it involves C# and Visual Studio.

An "OMG, WTF" Moment

I mandate that our projects "treat warnings as errors". After migrating the first solution over, 15 of the 30 projects had compilation errors. It's worth mentioning that we maintain a 1-to-1 ratio between class libraries and unit-test projects. Much to my surprise the 15 projects that had compilation errors were only unit-test projects. The reason that they stopped compiling was due to seemingly countless <strong>xUnit</strong> warnings, generated by various <strong>Roslyn</strong> analyzers. I was shocked by the number of warnings that were discovered.

The Realization

As one might imagine -- there are a lot of unit tests in 15 projects. This was an opportunity for <strong>Roslyn</strong> and <strong>xUnit's</strong> analyzers to shine, and shine they did! At first I was frustrated...thinking something like "FML, of course there is an issue" but upon further investigation I discovered that these were all perfectly reasonable warnings. In fact, several of them made me question how some tests ever passed at all. I was impressed by the power of this tooling addition. While <strong>Roslyn</strong> has been around for a while, I have not personally observed a large uptake in its abilities. Needless to say, I was thrilled to see the <strong>xUnit</strong> team leveraging it so much -- this is inspiring!

Visual Studio 2017 will display the analyzers that are available within a project under Dependencies > Analyzers.

As you can see they have put a lot of thought and effort into this. There are tons of various rules,here is a comprehensive listing of them all.

xUnit

I'm dating my <strong>xUnit</strong> efforts here a bit, but I've been a fan of <strong>xUnit</strong> for a long time now! Back in the days of "DNX", or as Scott Addie might ask DMX?. In a time when I was still on Wordpress, before I was enlightened my Steve Hicks who says:

If you aren't putting out as many posts as BuzzFeed, you can probably just build your blog statically <cite>Steve Hicks</cite>

Here is a post from February 2016 where I flexed some of the <strong>xUnit</strong> capabilities. Again, I've been a fan of <strong>xUnit</strong> for a long time now. It is incredibly

Roslyn

If you're unfamiliar with <strong>Roslyn</strong>, it is the .NET Compiler Platform.

Roslyn provides open-source C# and Visual Basic compilers with rich code analysis APIs. It enables building code analysis tools with the same APIs that are used by Visual Studio.

Visual Studio relies on <strong>Roslyn</strong> for lots of things. All of the aforementioned <strong>xUnit</strong> rules are defined as <strong>Roslyn</strong> analyzers. These analyzers are executed within Visual Studio, providing a great developer experience. They help you write better code.

Visual Studio -- Warnings

This section will serve as a brief listing of some of the warnings that I encountered. When writing a unit-test that uses Theory paired with InlineData, if there are duplicates -- this is flagged.

When you mistakenly define a unit-test method parameter that is not used, it's flagged.

When your unit-test is attempting to check whether a collection "does not contain" something, and does so with an Assert.False(collection.Any(...)); -- it is flagged.

This one might be my favorite -- if you incorrectly Assert.NotNull on a value-type (that can never be null) -- it is flagged.

When you call Assert.Equal and the expected argument is null -- it is flagged.

I also ran into two variations of the <strong>xUnit:2013</strong> warning which states the following:

Do not use equality check to check for collection size

In one scenario I had some unit test code similar to Assert.Equal(0, values.Count);, the analyzer instead suggested Assert.Empty(values);. This was my intent anyways, so of course I was happy to accept the recommended change.

Likewise I had an Assert.Equal(1, values.Count); and the analyzer suggested Assert.Single(values);. I was ensuring that the collection had only a single value, so once again <strong>xUnit</strong> was correct. Again, my appreciation for this tooling enhancement cannot be overstated.

Thank you

C# Special Edition

David Pine — Sun, 17 Dec 2017 00:00:00 GMT

Welcome to the 17th day of the C# Advent Calendar. I'd like to take a moment to thank my fellow bloggers who are sharing their passion of C# with everyone following the C# Advent Calendar. Please, share this and their posts - help us all make C# even more widely adopted than it is today.

In the Beginning

I'm honored to blog about my favorite programming language, C#. There is an often forgotten truth about the history of C#, one truth that I like talking about. While C# is a really "cool" language with awesome features it was actually named "Cool" in the beginning!

In January 1999, Anders Hejlsberg formed a team to build a new language at the time called Cool, which stood for "C-like Object Oriented Language". Microsoft had considered keeping the name "Cool" as the final name of the language, but chose not to do so for trademark reasons. <cite>Wiki - C#)</cite>

Likewise, the name C# somewhat implies an increment of C++. Imagine, the ++ being stacked on-top of each other -- you'd have something resembling the # symbol, clever no?! Unfortunately, my career didn't start with such a cool language. I learned Java in college and started my career with Visual Basic. I am now grateful to develop in C# professionally and for fun!

It is going to be around for a while

From all the languages in the .NET stack, C# is the most prolific.

This is where Visual Basic lovers

Throw New System.Exception("Tomatoes!")

and F# enthusiasts

raise (new Exception("their fists in anger!"))

The language continues to evolve and innovate. According to the annual __ Stack Overflow__ developer survey, C# is the 4th most popular programming language in the world. And since we're talking about __ Stack Overflow__, it is noteworthy to mention that Jon Skeet is nearing 1 million reputation points -- and he's projecting this will occur mid January. Roughly 55% of all his contributions are for C#, yet he is a Java developer. This never ceases to amaze me!

Getting Started

I believe that Microsoft has done an amazing job at not only updating their documentation sites, but unifying them and enhancing the user experience tenfold. The sites seem to flow more naturally while delivering relevant content, and as a developer that is what I want from a resource.

The JavaScript.com website has one of the best getting started experiences on the web today. <cite>Maria Naggaga -- Keynote "It Starts With A Search", MKE DOT NET 2017</cite>

It is more natural for JavaScript to have an online tutorial than C#, but Microsoft made this happen regardless. They have an awesome series of quick starts that serve as tutorials. They introduced an in-browser REPL (Read-Eval-Print Loop) for C#, and it is amazing. Here is a listing of a few of them:

Once you're developing you can always rely on the C# Guide as well. Finally, the documentation site boasts Samples and Tutorials for a more in depth look.

Speaking Fluently

C# is a beautiful language with an elegant syntax which is simple, powerful and expressive. Backed by an superb developer experience from Visual Studio, you can quickly immerse yourself into any project. What would a C# post be without some code? Not much of a post at all. Since this is a special edition, let's have a look at something I found interesting and insightful from C# 7. I wrote a post about exploring C# 7 if you'd like a refresher.

C# 7.0 featured out variables, which enable inline declaration.

public static class StringExtensions
{
    // The declaration is inlined with the out keyword
    // We can use 'var', as the type int is known
    // The 'result' variable is scope "leaks" to scope of the method body
    public static int ToInt32(string input)
        => int.TryParse(input, out var result)) ? result : result;
}

We can now write super expressive, inlined .TryParse logic. I wanted to call attention to an issue that I ran into where I made an assumption. The lesson of the story is to never make an assumption, right?! Here is the issue as it exists on __ GitHub__ today.

Consider the following:

public static class ConcurrentExtensions
{
    public static T TryPeekOrDefault<T>(this ConcurrentQueue<T> queue)
        => (queue?.TryPeek(out T result) ?? false) ? result : default;
}

This results in the following compiler error:

Error CS0165 Use of unassigned local variable 'result' IEvangelist.Csharp.Seven

As you can see this does not currently work in C#, but I assumed it would. Let's break it down and figure out why. First, let's remove the single line expression and make it non-ternary.

public static class ConcurrentExtensions
{
    public static T TryPeekOrDefault<T>(this ConcurrentQueue<T> queue)
    {
        if (queue?.TryPeek(out T result) ?? false)
        {
            return result;
        }

        return default;
    }
}

The first expression within the if block tests if the queue parameter in context is null. If it is null, it will coalesce to false. If it is not null, then if will evaluate the returning result from the .TryPeek invocation. When the if block is evaluated to be either true or false - after evaluation we know that the result variable has been definitely assigned. Here is the spec on definite assignment.

At a given location in the executable code of a function member, a variable is said to be definitely assigned if the compiler can prove, by a particular static flow analysis (Precise rules for determining definite assignment), that the variable has been automatically initialized or has been the target of at least one assignment. <cite>C# Language - GitHub</cite>

Now consider the following:

public static class ConcurrentExtensions
{
    public static T TryPeekOrDefault<T>(this ConcurrentQueue<T> queue)
    {
        if (queue == null)
        {
            return default;
        }

        // The 'result' variable leaks to this outer scope.
        // But with the previous eager evaluation and corresponding early exit
        // the 'result' is never accessed.
        // As such, it is not "definitely assigned".
        if (queue.TryPeek(out T result))
        {
            return result;
        }

        return default;
    }
}

This is equivalent to the non-inlined usage of out variable declaration:

public static class ConcurrentExtensions
{
    public static T TryPeekOrDefault<T>(this ConcurrentQueue<T> queue)
    {
        // The `result` variable may never be accessed.
        if (queue != null)
        {
            T result;
            if (queue.TryPeek(out result))
            {
                return result;
            }
        }

        return default;
    }
}

These are more verbose equivalents in terms of functionality, some with eager evaluation paired with an early exit. Both of these versions compile and would work as you'd expect them to. There is talk about getting better support for flow analysis, beyond definite assignment -- I for one would love that. TypeScript has been doing a great job at this, thanks to Anders and company!

The issue still has a sense of illusion. Yes, as Neal Gafter stated I would like definite assignment (which is part of flow analysis) to infer that the variable is only referenced where it was definitely assigned in this case. I'm happy that it's been labeled as a Feature Request and Discussion.

Does that seem reasonable? If not, why? If so, please visit the issue and ! I'm thrilled that C# is open source and the community is able to contribute in ways such as this. I hope that after reading this you might be inspired to get involved.

Why procrastinate today, when you can procrastinate tomorrow? <cite>David Neal</cite>

Counting my blessings

I consider myself to be very fortunate. I work with the owner of Edwina, who has been patiently teaching and coaching me through the better part of three years of my career. She used to teach algorithms and C# at the Milwaukee School of Engineering (MSOE). I have learned so much from her about C#, language semantics, algebraic reduction, etc...and I'm grateful for that. She has certainly made me a more pragmatic developer. I encourage everyone to find someone who can inspire, motivate or mentor them.

Final Thoughts

Go learn C#! If you already know it, mentor someone who wants to learn it. Happy Holidays and please support my fellow bloggers as they share their passion for C# with you.

ASP.NET Core Configuration Tips

David Pine — Sat, 10 Mar 2018 00:00:00 GMT

Being a software developer, it's in our nature to configure various aspects of the applications that we write. With ASP.NET Core configuring our applications is really straight forward. Luckily, there is a lot of really well written documentation surrounding this topic.

However, there is still room for improvement. I've prepared a few tips that can enhance developer productivity by taking advantage of various C# features.

C# Class < -- > JSON

ASP.NET Core configuration via the IOptions<T> and IOptionsSnapshot<T> have been around for a long time. Their usage is a first class citizen within ASP.NET Core applications, and work to tie appsettings.json values to corresponding configuration POCO's. As a refresher on configuration, there is a one-to-one relationship between a JSON object in the appsettings.json and the C# class that represents it.

`appsettings.json`

{
    "notificationSettings": {
        "notificationInterval": "00:15:00",
        "isMulticast": true,
        "sources": [
            {
                "url": "https://www.contoso.com/notificationHub",
                "key": "f7ea5e2b22bf907344f3a780caa0a166"
            }
        ]
    }
}

`NotificationSettings.cs` and `NotificationSource.cs`

public class NotificationSettings
{
    public TimeSpan NotificationInterval { get;set; }
    public TimeSpan TimeoutInterval { get; set; }
    public bool IsImplicit { get; set; }
    public List<NotificationSource> Sources { get; set; }

    public NotificationSetting()
    {
        IsImplicit = true;
        TimeoutInterval = TimeSpan.FromSeconds(30);
    }
}

public class NotificationSource
{
    public Uri Url { get; set; }
    public string Key { get; set; }
}

If you looked at both the appsettings.json and the two C# classes, I'm hoping that you noticed something. I hope that you noticed that the JSON settings didn't fully provide a value for all the mapped properties in the NotificationSettings object. We have however, set these values as part of the object's .ctor.

<cite>ProTip</cite> Use C# 6 Property Initializers to set default values. If the corresponding property exists in the JSON object mapping, it will be overwritten as to be expected; however, if omitted your default value is used.

Using property initializers, this is simplified as follows:

public class NotificationSettings
{
    public TimeSpan NotificationInterval { get;set; }
    public TimeSpan TimeoutInterval { get; set; } = TimeSpan.FromSeconds(30);
    public bool IsImplicit { get; set; } = true;
    public List<NotificationSource> Sources { get; set; }
}

It is a good practice to specify default values for your settings classes. As part of the Startup.cs class, the ConfigureServices method is where you will "Configure" your mappings of the JSON section that is associated to the C# object representing it. For example:

public void ConfigureServices(
    IServiceCollection services)
{
    // Configure the "NotificationSettings"
    // mapping it to the corresponding JSON section

    services.Configure<NotificationSettings>(
        Configuration.GetSection("NotificationSettings"));
}

This should look very familiar.

<cite>ProTip</cite> Use C# 6 nameof operator to configure your C# class mapping. This alleviates the usage of magic strings and enforces a consistent naming convention.

The change is tiny, however; this is another great usage of the nameof operator. This assumes that the the section in the JSON file matches the name of the class object representing it. Additionally, it serves as a reason to keep the names matching.

public void ConfigureServices(
    IServiceCollection services)
{
    services.Configure<NotificationSettings>(
        Configuration.GetSection(nameof(NotificationSettings)));
}

Conclusion

I have provided a few simple tips for ASP.NET Core configuration leveraging a few C# 6 features. They are nothing earth-shattering, but they are practical and very useful. I often see developers not taking advantage of simple features like these when they are available. These two features alone in an ASP.NET Core configuration could simplify refactoring and stream-line readability -- that's enough reason for me, I hope it is for you too!

ASP.NET Core Unit Testing For Security Attributes

David Pine — Fri, 23 Mar 2018 00:00:00 GMT

Intro

As a developer, I can say that developers are lazy - at least I know and acknowledge that I am. If I'm tasked with something even the slightest bit repetitious I'll script it out, or find a way to automate it. Likewise, if I fall into a habit of forgetting something important - I'll figure out a way to not forget. Especially when it comes to securing an application.

Security Soapbox

We should take application security very seriously! With ASP.NET Core there's a lot of existing documentation for securing your application. This covers identity, authentication, authorization, data protection, HTTPS, safe storage, Azure key vault, anti-request forgery, open redirect attack, cross-site scripting, etc... the list goes on and on. All these things are important and as a developer you're ultimately accountable for writing secure code.

The Dilemma

A while back I spent a fair amount of time writing some ASP.NET Core Web API endpoints and I kept forgetting to provide the AuthorizeAttribute on various controller classes or even controller actions.

There is an easy way to solve this. Within ConfigureServices we could apply an AuthorizeFilter with a policy that requires an authenticated user. This serves as a nice security blanket, that ensures all endpoints are only accessible from an authenticated user.

public void ConfigureServices(IServicesCollection services)
{
    services.AddMvc(
        options =>
        {
            // Only allow authenticated users.
            var defaultPolicy =
                new AuthorizationPolicyBuilder()
                    .RequireAuthenticatedUser()
                    .Build();

            options.Filters.Add(new AuthorizeFilter(defaultPolicy));    
        });
}

However, based on your needs - you may choose to not apply this filter. If you choose to not apply this filter you're left with three options.

Apply an AuthorizeAttribute at the controller class level (cascades onto all the actions)
Apply an AuthorizeAttribute on each individual action method
Not protect your API at all

Automation To The Rescue

Some of our ASP.NET Core Web APIs were protected by the filter, some by controller class level AuthorizeAttribute decoration and others by the individual action... and some not at all. This is a problem! It is common practice to run unit tests prior to pushing code into a feature branch for a pull request. If I forget to do that, my build system has some pull request pre-checks in place - one of which is to run the unit tests. As such, I know that unit tests will be executed. With this, I decided to write a unit test that leveraged a bit of reflection. Since it is a unit test, I'm not terribly concerned with performance - so reflection is fine...

Here was the thought process to write a unit test that could ensure that I'm not forgetful.

Load all assemblies into the current AppDomain
Of all the loaded assemblies, get all the controller types
- Of those controller types, get the ones that are missing the AuthorizeAttribute
- Of the unauthorized controller types, get the HttpMethodAttribute methods
- If missing both the AuthorizeAttribute and AllowAnonymousAttribute - fail

Codify

So, our step one is to load all assemblies into the current AppDomain. This makes some assumptions. It assumes that our test project will have a reference to the ASP.NET Core Web API project, so that its .dll will be available to us for loading (in our bin directory). We will also assume the root namespace we're looking for, we should know this anyway as we follow naming conventions and we're the owner of the corresponding project.

public class ActionTests
{
    const string RootNamespace = nameof(IEvangelist);
    static readonly string[] ExecutableExtensions = { ".exe", ".dll" };

    public ActionTests()
        => Directory.EnumerateFiles(
                Path.GetDirectoryName(
                        Assembly.GetExecutingAssembly().Location) ?? string.Empty,
                        $"{RootNamespace}.*")
                     .Where(IsExeOrDll)
                     .Select(Assembly.LoadFrom)
                     .Select(assembly => 
                        TryCatchIgnore(
                            () => AppDomain.CurrentDomain.Load(assembly.GetName())))
                     .ToList();

    static bool IsExeOrDll(string path)
        => ExecutableExtensions.Any(
            extension => 
                extension.Equals(
                    Path.GetExtension(path), 
                    StringComparison.OrdinalIgnoreCase));

    static T TryCatchIgnore<T>(Func<T> func) {
        try { return func(); }
        catch { return default; }
    }

Step two, is really the entry point of our core functionality for the test itself. We'll need a Fact test method. Yes, I'm a HUGE fan of xUnit - they have done some amazing things! In this test method we will start by getting all the types that are a subclass of Controller.

[Fact]
public void AllActionsOrParentControllerHaveAuthorizationAttributeTest()
{
    var allControllers = GetAllControllerTypes();

    // we'll continue here ...
}

static List<Type> GetAllControllerTypes()
    => AppDomain.CurrentDomain
                .GetAssemblies()
                .Where(a => a.FullName.StartsWith(RootNamespace))
                .SelectMany(a => a.GetTypes()
                                  .Where(t => t.FullName.Contains(Controller)
                                           || t.BaseType == ControllerType
                                           || t.DeclaringType == ControllerType))
                .ToList();

Now that we have all the controller types from all the assemblies loaded into our AppDomain, we need to filter them. We need to find the types that are missing the AuthorizeAttribute, we'll call these unauthorizedControllers for now.

[Fact]
public void AllActionsOrParentControllerHaveAuthorizationAttributeTest()
{
    var allControllers = GetAllControllerTypes();
    var unauthorizedControllers = 
        GetControllerTypesThatAreMissing<AuthorizeAttribute>(allControllers);

    // We'll continue from here...
}

static List<Type> GetControllerTypesThatAreMissing<TAttribute>(
    IEnumerable<Type> types)
    where TAttribute : Attribute
    => types.Where(t => t.GetCustomAttribute<TAttribute>() == null)
            .ToList();

This method iterates through the given IEnumerable<Type> and returns a List<Type> that are not attributed with the AuthorizeAttribute. The reason that we're filtering out controller types that are attributed, is that we'll consider them to be protected from the standpoint of our unit-testing capabilities. Now, we need to find all the methods on these types that match the following criteria:

Are a public instance method
Have any HttpMethodAttribute subclass

These methods are the controller's actions. From these actions, we need to find the unauthorized actions. This is done by filtering out actions that explicitly declare themselves with the AllowAnonymousAttribute and are also missing the AuthorizeAttribute.

foreach (var controller in unauthorizedControllers)
{
    var actions =
        controller.GetMethods(BindingFlags.Public | BindingFlags.Instance)
                    .Where(m => m.GetCustomAttributes<HttpMethodAttribute>().Any())
                    .ToList();

    var unauthorizedActions = 
        actions.Where(
            action => 
                action.GetCustomAttribute<AuthorizeAttribute>() == null &&
                action.GetCustomAttribute<AllowAnonymousAttribute>() == null)
               .ToList();
    
    // If unauthorizedActions.Any() is true, sound the alarms!
}

We can add a few additional sanity checks along the way - with the caveat that this is not your typical "unit test". For example we could add the following:

Assert that we do in fact load assemblies
Assert that count of all the controllers is greater than the unauthorized controllers
Assert that we find our "white-listed" controller

Putting It All Together

using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.Routing;
using System;
using System.Collections.Generic;
using System.IO;
using System.Linq;
using System.Reflection;
using Xunit;

namespace IEvangelist.Tests
{
    public class ActionTests
    {
        const string RootNamespace = nameof(_Evangelist);
        const string Controller = nameof(Controller);
        const string WhiteListed = nameof(UnauthorizedActionInController.GetZero);

        static readonly Type ControllerType = typeof(Controller);
        static readonly string[] ExecutableExtensions = { ".exe", ".dll" };

        public ActionTests()
            => LoadAllAssemblies();

        void LoadAllAssemblies()
        {
            var assemblies =
                Directory.EnumerateFiles(
                    Path.GetDirectoryName(
                            Assembly.GetExecutingAssembly().Location) ?? string.Empty,
                            $"{RootNamespace}.*")
                        .Where(IsExeOrDll)
                        .Select(Assembly.LoadFrom)
                        .Select(assembly => 
                            TryCatchIgnore(
                                () => AppDomain.CurrentDomain.Load(assembly.GetName())))
                        .ToList();

            Assert.False(assemblies.IsNullOrEmpty());        
        }

        [Fact]
        public void AllActionsOrParentControllerHaveAuthorizationAttributeTest()
        {
            var allControllers = GetAllControllerTypes();
            var unauthorizedControllers = 
                GetControllerTypesThatAreMissing<AuthorizeAttribute>(allControllers);
            
            Assert.True(allControllers.Count > unauthorizedControllers.Count);
            
            foreach (var controller in unauthorizedControllers)
            {
                var actions =
                    controller.GetMethods(BindingFlags.Public | BindingFlags.Instance)
                              .Where(m => m.GetCustomAttributes<HttpMethodAttribute>().Any())
                              .ToList();

                var unauthorizedActions = 
                    actions.Where(
                        action => 
                            action.GetCustomAttribute<AuthorizeAttribute>() == null &&
                            action.GetCustomAttribute<AllowAnonymousAttribute>() == null)
                           .ToList();

                if (unauthorizedActions.IsNullOrEmpty() ||
                   (unauthorizedActions.Count == 1 && 
                    unauthorizedActions[0].Name == WhiteListed))
                {
                    continue;
                }

                unauthorizedActions.ForEach(
                    action => Console.WriteLine($"{action} is unauthorized!"));

                Assert.True(false, $"Unauthorized action(s) found!");
            }
        }

        static List<Type> GetAllControllerTypes()
            => AppDomain.CurrentDomain
                        .GetAssemblies()
                        .Where(a => a.FullName.StartsWith(RootNamespace))
                        .SelectMany(a => a.GetTypes()
                                          .Where(t => t.FullName.Contains(Controller) ||
                                                      t.BaseType == ControllerType ||
                                                      t.DeclaringType == ControllerType))
                        .ToList();

        static List<Type> GetControllerTypesThatAreMissing<TAttribute>(
            IEnumerable<Type> types)
            where TAttribute : Attribute
            => types.Where(t => t.GetCustomAttribute<TAttribute>() == null)
                    .ToList();

        static bool IsExeOrDll(string path)
            => ExecutableExtensions.Any(
                extension => 
                    extension.Equals(
                        Path.GetExtension(path), 
                        StringComparison.OrdinalIgnoreCase));

        static T TryCatchIgnore<T>(Func<T> func) {
            try { return func(); }
            catch { return default; }
        }
    }

    public class UnauthorizedTestController 
        : Controller
    {
    }

    public class UnauthorizedActionInController 
        : Controller
    {
        [HttpGet]
        public int GetZero() => 0;

        [Authorize, HttpPost]
        public IActionResult Post([FromBody] int number) => Ok();

        [OverrideAge, HttpDelete]
        public IActionResult Delete() => Ok();
    }
    
    public class OverrideAge : Authorize {  }
}

Conclusion

This solution is not perfect, it has a lot of opportunity for improvement. I'm open to suggestions... If you have an idea, drop it in the comments and feel free to share your source. Likewise, if you like this idea - let me know. I was hoping to eventually find a way to turn this into a C# Roslyn-Powered Analyzer but I'm not sure that is possible. There is one fact that remains, this has actually proven itself useful - there have been several times where this test failed as a result of someone (myself included) forgot to apply the appropriate security attributes to an ASP.NET Core Web API endpoint we were writing. I hope that this can help you too!

Journey of a Lifetime

David Pine — Sat, 28 Apr 2018 00:00:00 GMT

import { YouTube } from '@astro-community/astro-embed-youtube';

Intro

I am returning home from a long trip in Serbia for IT Konekt. This was literally a trip of a lifetime and I could not be more grateful for such an amazing opportunity. Serbia has such an incredible culture and powerful history. I have been overwhelmed by the care and attention to detail from the organizers of IT Konekt. This was my first time ever leaving the United States of America and I didn't know what to expect. I was really nervous but equally excited. This was more of a journey of epic proportions than it was a conference trip.

I want to publicly thank Maria Naggaga of Microsoft for referring Milica Radovic and Milica Nastasic to me. They were looking for someone from the U.S. to speak about C# and Maria suggested me. This is the such an honor and I couldn't have been more excited to represent the U.S. and C# for my first international speaking engagement.

Belgrade

April 13, 2018

Our journey began in Belgrade – the capital city of Serbia. I arrived on the same flight into Belgrade as Jonathan LeBlanc of Box. In true movie fashion, our driver was waiting for us holding our names at the arrival gate of the airport. This was a warm welcome and made me feel special. After a 35-minute Car:Go (European Uber) drive we arrived at our hotel and while I didn't get much sleep on the plane, I had energy from both the adrenaline and excitement. Just as soon as I was settling into my room, it was time to part for the first of seemingly countless speaker dinners. We were hungry and ready to immerse ourselves in the Serbian culture. We had a traditional Serbian dinner after a celebratory shot (or three) of rakija - "Serbian fruit brandy". Now, if you're like me you probably didn't know what rakija was... warning it is very strong! They fed us like kings and queens, we were treated like royalty!

Harry Roberts sat to my right - he was a blast. He and I shared a lot of common thoughts about the developer community. I enjoyed his company. I asked him if he was on Twitter so that I could follow him - yeah 58k+ followers. The food was great. The people of Serbia know how to do meat, I might get myself banned from the United States for saying this but it is true, "Serbia has the best bacon in the world!" After a long night, I returned to my hotel where I immediately fell asleep.

April 14, 2018

I woke up at 8 AM, I then decided I would rest my eyes a little longer (suffering from jetlag) I opened them again around 11 AM. My talk was at 4, so I had plenty of time. It was conference day, I was prepared and looking forward to giving my talk. I believe that presenting on C# was an excellent choice – it is a universal language. The attendees really enjoyed it and were thoroughly engaged. The only time people had their phones out was for taking pictures of me or the slides. I was asked to take pictures with several attendees both before and after my talk. This was the first time this has ever happened to me and it made my day!

In addition to a great conference, Jonathan LeBlanc and I took a casual stroll through Belgrade. We ended up walking over 14 miles and visited the Belgrade fortress. Along the way, we were asked to help someone lift an A/C unit up a shaky ladder onto a roof within a closed market.

No one was injured in the photographing of this event...our walk continued with no more interruptions. We arrived at the Belgrade fortress and it was very interesting. We were able to walk all over it, in the moat, in tunnels and even on the walls. Once we made our way to the back of the fortress we found a hill with a view. Here is a great shot from the fortress walls overlooking where the rivers meet - it truly was a remarkable view.

While touring the fortress we stumbled upon a torture museum, Jonathan and I decided "why not". After the first few exhibits we kept asking each other "what the hell were we thinking!" I was tempted to share some of the pictures from the torture museum but nope, I'll spare you the pain. Once we were finished witnessing the horrors, we were spent...we walked back to the hotel.

April 15, 2018

Sunday was traveling day and we were driving to Niš. The core group of speakers got to know each other extremely well during the trip, and I consider them all personal friends now. We spent hours in a jumbo van traveling the country of Serbia over the course of a week - quite the adventure. The core group of speakers were Jon Galloway, Jonathan LeBlanc, Håkon Wium Lie and myself.

Niš

April 16, 2018

The Humble Giant (Jovan Milic)

When we arrived in Niš, we were greeted by several hosts. One of them was Jovan Milic and I'm referring to him from now on as the "humble giant". If you're ever looking for inspiration read his story, it will hopefully put things a little more into perspective. For me, I can relate very much to his story and appreciate all the things that he's done to earn his place in the world now. The next time you want to complain about the things you take for granted, remember his story and support his cause.

There are several life lessons that I live by - this is one of them.

Expect nothing, but be grateful for everything.

Jovan and the other hosts treated us like celebrities. We had a walking tour of the Niš fortress and city center. After arming ourselves with some umbrellas we were ready to take on the light rain. My umbrella just so happened to be pink. I'm not sure the color of my umbrella is relevant for this story, but I felt inclined to share it. After strolling around the fortress and then making our way back towards the city center - we needed some caffeine. We enjoyed turkish coffee and dark beer, because why not both?! I recall this evening very well, this is the night that Håkon told us about the time he built a balsawood raft with a group of volunteers. The raft weighed over 20 tons, and the intended purpose was to set course from South America (Peru) and sail to Easter Island. Why, you might ask - as both Jon's and I did...we were intrigued, why on earth would anyone want to do this? Simply to prove a point that it could be done. It would prove that Easter Island could have been inhabited by the people of South America. This voyage took place in 2015-2016 and was the spotlight of world-wide news, for more details checkout the official website and the story from Håkon himself here.

Again we enjoyed a traditional Serbian dinner. There was more rakija and as luck would have it, traditional Serbian music was played/performed live...with the livelihood from the rakija there was dancing and singing, and all-around celebration. Such a joyous time!

April 17, 2018

Conference Day! The stage was set. The crowds were drawing near, anticipation was building. News crews, wait...news crews? Yes, we were actually interviewed and made it on the Serbian national news - several times. This was yet another first for me. The media was interested about our take on the IT community in Serbia. They were curious about how the developers of Serbia rank up against the rest of the world. That is a hard question to answer, but one thing was consistent with all of our responses - we believe that any developer can change the world! When you take talent, an idea and hunger to build something incredible there is no limit to what you can achieve.

The conference talks were all really well received. The developer community seemed eager to ask questions after sessions. As a speaker, this is what makes it all worthwhile - the gratifying moment when you know that you've been able to help someone and that you've delivered value. After the conference we spent more time walking around Niš, this is when I learned that Håkon brought a drone. We took turns flying it and taking pictures of the scenery.

Novi Sad

April 18, 2018

Wednesday was another traveling day. Our jumbo van trip was scheduled to take roughly four hours. But before we left, we were asked to be part of a ceremony with the President of municipalities, the mayor of Niš. The press was there to capture the moment. It was incredible sharing ideas for shared working spaces and encouraging hackathons. Our hosts served as translators, communicating our ambitions and guidance. The mayor was so pleased that he presented Håkon with a special honor - a medallion of Constantine the Great.

IT experts are visiting the municipalities of Crvena Krst.

Shortly after the ceremony, we drove to Novi Sad. We arrived without a hitch, settling into our hotels. Followed by a city tour, which proved to be a spectacular site. Dinner was at the Terasa. This sits right on the Danube river and at the foot of the Novi Sad fortress. Håkon was able to capture some amazing footage with his drone...the view was beautifully stunning.

Sremski Karlovci & Danube River

April 19, 2018

The 19th was a really relaxing day, we had a walking tour, lunch on the Danube river, followed by a wine tasting at the Museum of Beekeeping and Wine Cellar Zivanovic. Again, Håkon let his drone capture some of the essence and scenery. This video starts well beyond the town center, working its way back toward where we had lunch on the river. Yes, that establishment in the distance is where Håkon is navigating his drone recording this clip. I am seriously trying to convince my wife to let me purchase one of these drones. If you want to buy it for yourself here is the link.

This footage is amazing, with video quality up to 4k if you're into that sort of thing... 😏

April 20, 2018

The final conference day! I was up first and immediately following my talk, I needed to catch a cab back to Belgrade to catch my flight back home. I was sent home with a parting gift from the founders. I love the thoughtfulness, and it is so true that it's better than a notebook and a pen.

I was excited to be returning home. I know that I was missed by Lyric, Londyn, Lennyx (my three sons) and Jen (wife). I'm thankful to have had a safe trip and shared so many awesome experiences. For those interested in the conference itself, I'll be posting videos and more photos as they are released. For my talk, see below.

What's new in C# (The Talk)

Here is the link for my talk, What's new in C#. This was the talk that I presented at all three IT Konekt conferences.

Closing Thoughts

I was blessed to have made so many new friends on this journey. These people are inspiring, you should follow them as they are true leaders!

Jon Galloway LinkedIn, Twitter, GitHub, Blog
- Executive Director .NET Foundation, ASP.NET MVC 3/4/5 Author
Jonathan LeBlanc LinkedIn, Twitter, GitHub, Website
- Director of Developer Advocacy Box, Emmy Award Winner, O'Reilly Author
Håkon Wium Lie LinkedIn, Twitter, Website
- Creator of CSS, former CTO of Opera, Kontiki Adventurer
Milica Radovic LinkedIn, Twitter
- Founder, IT Konekt
Milica Nastasic LinkedIn
- Co-Founder, IT Konekt
Jovan Milic LinkedIn, Twitter
- Founder of Find Raoul

ASP.NET Core + Angular Photo Booth App

David Pine — Fri, 22 Jun 2018 00:00:00 GMT

Inspiration

I recently returned from Charleston, South Carolina -- where I spoke at SyntaxCon. The event was very professionally organized and gave me inspiration for Cream City Code. In the main hall, they had a HALO by Simple Booth. It serves as a photo booth with a conference-specific backdrop -- which is perfect for sharing the conference experience. I looked into purchasing one but was encouraged to simply write my own... so I did and this blog will detail that process.

Ultimately, the resulting social media share ends up looking something like these ( To open gallery ). It generates an animated image (*.gif) from the series of photos taken.

<br/>

User Workflow

Here's what we want to do.

We need to capture several pictures upon user initiation
We need to create an animated image from these pictures
We need to allow the user to send them to themselves for sharing
We need to reset the state of the app after sharing is complete

That's pretty simple, right?! While the application is idle, we'll provide the live camera view with some branding and a "start" button. Anyone walking by will more than likely see themselves and naturally become curious. The hope is that their curiosity will entice them enough to press the "start" button. Pressing the "start" button leads to more excitement as they're presented with a countdown timer... 3, 2, 1... (Flash, Snap)! Their picture is taken, and this continues a few more times. This ends up sparking a chain reaction where others take notice and join in. There are plenty of opportunities for "photo bombing"!

Technologies Used

This application is built using the Angular ASP.NET Core SPA template. Additionally, I'm leveraging the following:

Technology	Purpose
ImageSharp	Convert several `.png` images into a single `.gif`
Azure - Blob Storage	Persist generated `.gif` image
Twilio	Send SMS text message with URL of animated `.gif` image

The application is up on GitHub here: <a href="https://github.com/IEvangelist/IEvangelist.PhotoBooth" target="_blank"> IEvangelist.PhotoBooth. </a>

Under The Hood

Now that we've familiarized ourselves with what we need to do, let's take a look at how we can approach it. As I mentioned, this is an ASP.NET Core application -- so we'll see a Program.cs, Startup.cs, and a Controllers directory for our ASP.NET Core Web API. It is also an Angular application. This too has common conventions and things to look for, such as components, services, modules, pipes, etc.

First The C# Code

Snippet from Startup.ConfigureServices

// Map services
services.AddTransient<IImageProcessorService, ImageProcessorService>();
services.AddSingleton<IImageRepository, ImageRepository>();
services.AddSingleton<ITextMessagingService, TextMessagingService>();

// Map appsettings.json to class options
services.Configure<ImageProcessingOptions>(
    Configuration.GetSection(nameof(ImageProcessingOptions)));
services.Configure<ImageCaptureOptions>(
    Configuration.GetSection(nameof(ImageCaptureOptions)));
services.Configure<ImageRepositoryOptions>(
    Configuration.GetSection(nameof(ImageRepositoryOptions)));
services.Configure<TwilioOptions>(
    Configuration.GetSection(nameof(TwilioOptions)));

We have some unique services being added to our dependency injection (DI) service collection. Later, our controllers can ask for these interfaces and expect the corresponding implementations. Likewise, we map over some sections from our appsettings.json configuration to C# classes. These also become available to us later from the perspective of DI. We can ask for IOptions<ImageProcessOptions> for example. See ASP.NET Core - Configuration Tips for more details.

ASP.NET Core Web API

Our application has only one controller with a few actions on it. We have an endpoint that returns various configuration options to the client app, and then a more interesting api/image/generate endpoint. If you're eager to learn more, I published an article with details on ASP.NET Core Web API Attributes.

[Route("api/image")]
public class ImageController : Controller
{
    [HttpGet, Route("options")]
    public IActionResult GetOptions(
        [FromServices] IImageProcessorService imageProcessor)
        => Json(imageProcessor.GetImageOptions());

    [HttpPost, Route("generate")]
    public async Task<IActionResult> Generate(
        [FromBody] ImagesPostRequest imagesPostRequest,
        [FromServices] IImageProcessorService imageProcessor) 
        => Json(await imageProcessor.ProcessImagesAsync(
            $"{Request.Scheme}://{Request.Host}{Request.PathBase}", imagesPostRequest));
}

<cite>ProTip</cite> Keep your controllers dumb! It is best to delegate their logic to a service, and this simplifies testing.

We ask for the IImageProcessorService implementation on the api/image/options action. This endpoint simply returns JSON that represents our combined configuration options from some of the various options classes we mapped earlier on startup. These options have information for the client app about animation frame delay, intervals, the number of photos to take, image height and width, etc.

Snippet from ImageProcessorService.GetOptions

public ImageOptionsResponse GetImageOptions()
    => new ImageOptionsResponse
        {
            AnimationFrameDelay = _processingOptions.FrameDelay,
            IntervalBetweenCountDown = _captureOptions.IntervalBetweenCountDown,
            PhotoCountDownDefault = _captureOptions.PhotoCountDownDefault,
            PhotosToTake = _captureOptions.PhotosToTake,
            ImageHeight = _processingOptions.ImageHeight,
            ImageWidth = _processingOptions.ImageWidth
        };

The api/image/generate endpoint is the most involved. Again we ask for the image processor service, but this time we call the ProcessImageAsync. We are given an ImagePostRequest object, that looks like this:

public class ImagesPostRequest
{
    public string Phone { get; set; }

    public List<string> Images { get; set; }
}

We get the phone number and a list of images -- the images are base64 encoded representations of the photos taken. This is what we're going to process. This method could be broken up some and I'm certainly open to improvements (... I mean, this is open source -- give me a pull request)!

Services

First, we convert all the base64 image strings to byte[]. We load the first image from the ImageSharp.Image.Load method, then the remaining images are loaded and added as frames to the first image frames collection. The resulting image now has several frames and will be saved as a .gif file. It is then persisted using __ Azure Blob Storage__, within our IImageRepository implementation. Finally, we create a link to our image and text the user the URL with Twilio.

Snippet from ImageProcessorService.ProcessImageAsync

public async Task<ImagesPostResponse> ProcessImagesAsync(
    string baseUrl,
    ImagesPostRequest request)
{
    try
    {
        var id = Guid.NewGuid().ToString();
        var imageBytes =
            request.Images
                    .Select(img => img.Replace(Base64PngImagePrefix, string.Empty))
                    .Select(Convert.FromBase64String)
                    .ToArray();

        var image = Image.Load(imageBytes[0]);
        image.MetaData.RepeatCount = 0;

        for (int i = 1; i < imageBytes.Length; ++ i)
        {
            image.Frames.AddFrame(Image.Load(imageBytes[i]).Frames[0]);
        }

        // Ensure that all the frames have the same delay
        foreach (var frame in image.Frames)
        {
            frame.MetaData.FrameDelay = (int)(_processingOptions.FrameDelay * .1);
        }

        await UploadImageAsync(id, image);
        await _textMessagingService.SendTextAsync(
            $"+{request.Phone}",
            $"Share your photo from Cream City Code! {baseUrl}/images/{id}");

        return new ImagesPostResponse { Id = id, IsSuccessful = true };
    }
    catch (Exception ex)
    {
        ex.TryLogException(_logger);
        return new ImagesPostResponse { IsSuccessful = false, Error = ex.Message }; 
    }
}

Snippet from ImageProcessorService.UploadImageAsync, here we are naming (and saving) the file and encoding it with the GifEncoder. We then upload the image to our repository.

private async Task UploadImageAsync(string id, Image<Rgba32> image)
{
    var fileName = $"./{id}.gif";
    var profile = new ExifProfile();
    profile.SetValue(ExifTag.Copyright, _processingOptions.Copyright);
    image.MetaData.ExifProfile = profile;
    image.Save(fileName, _encoder);

    await _imageRepository.UploadImageAsync(id, fileName);
}

Snippet from ImageRepository.UploadImageAsync.

public async Task UploadImageAsync(string id, string filePath)
{
    var container = await _initialization.Value;
    var blob = container.GetBlockBlobReference(id);
    await blob.UploadFromFileAsync(filePath);
    File.Delete(filePath);
}

We await the _initialization.Value which represents the async operation to yield a container reference. It's an AsyncLazy that ensures the following:

Create cloud blob client
Create named container reference (if it doesn't already exist)
Set permissions on container for blob types as public access
Finally return the container instance

The container instance is then used to get a block blob reference, to which we can upload our local image file. We'll delete the local version when we've uploaded it to Azure.

The last piece of the puzzle is that we need to send a text message to the phone number we were given. Twilio makes this extremely easy, in fact when I was reading their documentation about their SDK -- I doubted that was all I needed.

Snippet from TextMessagingService.SendTextAsync.

public async Task SendTextAsync(string toPhoneNumber, string body)
{
    try
    {
        var message =
            await MessageResource.CreateAsync(
                to: toPhoneNumber,
                from: _twilioOptions.FromPhoneNumber,
                body: body);

        _logger.LogInformation($"Texted {toPhoneNumber}: {body}.");
    }
    catch (Exception ex)
    {
        ex.TryLogException(_logger);
    }            
}

Angular

The Angular application is where a lot of the logic lives. It contains user interactions and workflow. Since it's Angular we'll look at some TypeScript. We have an image.service.ts that makes HTTP calls out to our Web API. At the time of writing, we had the following components:

Component	Purpose
`app`	Standard Angular application entry point
`audio`	Encapsulates the ability to bind `src` audio files and invoke `async play()` functionality
`camera`	Wraps the `<control-wizard>`, `<video>` and `<canvas>` elements, and orchestrates communications between them
`controlwizard`	This is the state machine of the overlay for the user workflow -- it toggles various templates into and out of view
`numberpad`	A numeric entry markup, which outputs the user input

When application loads, we first hit the api/image/options endpoint -- getting our client settings from the server. See Angular Http with RxJS Observables for more details on the HttpClient from Angular. We then set our camera stream to the video element on our CameraComponent.

Snippet from CameraComponent.ngAfterViewInit.

if (this.videoElement && this.videoElement.nativeElement) {
    this.video = this.videoElement.nativeElement as HTMLVideoElement;
    if (this.video
        && navigator.mediaDevices
        && navigator.mediaDevices.getUserMedia) {
        navigator
            .mediaDevices
            .getUserMedia({ video: true })
            .then((stream: MediaStream) => this.video.srcObject = stream);

        this.video.height = window.innerHeight;
    }
}

The videoElement is an ElementRef instance -- our component uses the Angular @ViewChild decorator to instantiate our reference to the <video> element in our template. We assign the .nativeElement to our video instance which is an HTMLVideoElement. Finally, if our browser environment has the ability to .getUserMedia we'll ask for the video stream and assign it to our video instance. Next, let's explore what kicks things off.

Snippet from control-wizard.component.html.

<ccc-audio #startSound
    [src]="'https://www.soundjay.com/switch/sounds/switch-19.mp3'">
</ccc-audio>
<div *ngIf="isIdle">
    <button (click)="start(startSound)">
        <i class="glyphicon glyphicon-camera"></i><br /> Start
    </button>
</div>

Our markup had a ccc-audio element, we have a reference to this with our # syntax -- we can then pass this as an argument to the start function on the button (click) handler. That function looks like this.

Snippet from ControlWizardComponent.start.

public async start(sound: AudioComponent) {
    if (sound) {
        await sound.play();
    }
    this.changeState(WizardState.CountingDown);
    this.resetCountDownTimer();
}

We play the sound, change the state of the application to CountingDown and then resetCountDownTimer. The resetCountDownTimer simply stops and then restarts the NodeJS.Timer instance in a clean manner. The startCountDownTimer method is called and it handles the count down and marshaling of photo capturing.

Snippet from ControlWizardComponent.startCountDownTimer.

private startCountDownTimer(): void {
    this.countDownTimer =
        setInterval(
            () => {                    
                if (this.photosTaken < this.imageOptions.photosToTake) {
                    if (this.photoCountDown === 1) {
                        this.photoCountDown = this.imageOptions.photoCountDownDefault + 1;
                        this.changeState(WizardState.TakingPhoto);
                        const details = {
                            photoCount: this.photosTaken,
                            interval: this.imageOptions.intervalBetweenCountDown
                        };
                        this.takePhoto.emit(details);
                        ++ this.photosTaken;
                    } else {
                        this.changeState(WizardState.CountingDown);
                        -- this.photoCountDown;
                    }
                } else {
                    this.stopCountDownTimer();
                    this.images = [];
                    for (var i = 0; i < this.imageOptions.photosToTake; ++ i) {
                        this.images.push(localStorage.getItem(`${i}.image.png`));
                    }
                    this.startAnimationTimer();
                    this.changeState(WizardState.PresentingPhotos);
                    this.photoCountDown = this.imageOptions.photoCountDownDefault;
                }
            },
            this.imageOptions.intervalBetweenCountDown);
    }

The functionality here really just manages iteration counts and state changes. The areas of interest are the takePhoto.emit, this is an EventEmitter which serves as an Output. This means that other components can register to this event and handle the occurrence of the .emit invocation. This component has several outputs, again let's just single out the takePhoto one for now -- we will need to have a look at the camera.component.html.

Snippet from camera.component.html.

<div class="video-wrapper" [ngClass]="{ 'camera-flash': isTakingPhoto }">
  <control-wizard (takePhoto)="onTakePhoto($event)" (stateChange)="onStateChanged($event)"
                  (optionsReceived)="onOptionsReceived($event)"></control-wizard>
  <video (window:resize)="adjustVideoHeight($event)" class="black-glow"
         #video autoplay width="640" height="480"
         [ngClass]="{ 'hide': isPresentingPhotos || isTextingLink }"></video>
  <canvas #canvas id="canvas" width="640" height="480" style="display: none;"></canvas>
</div>

From this we can see that the CameraComponent has an onTakePhoto handler. There are other observations to make as part of this, such as the markup itself -- how we're really orchestrating components that work (and communicate) together. The control-wizard notifies the CameraComponent about state changes and when options are received. When the control-wizard issues a takePhoto command the camera is responsible for taking a photo.

Snippet from CameraComponent.onTakePhoto.

public onTakePhoto(details: PhotoDetails): void {
    setTimeout(() => {
        if (this.canvas) {
            const context = this.canvas.getContext('2d');
            if (context) {
                context.drawImage(this.video, 0, 0, this.imageWidth, this.imageHeight);
                const url = this.canvas.toDataURL('image/png');
                localStorage.setItem(`${details.photoCount}.image.png`, url);
            }
        }
    }, details.interval / 2);
}

I relied on an old blog post from David Walsh - Camera and Video Control with HTML5, it was really helpful! We ask the canvas for a 2d context and then .drawImage on the context passing our video element. We then ask the canvas for .toDataUrl -- which returns our base64 string representation of the image. We'll put this in localStorage for now.

After the configured number of photos has been taken, we'll change the state of the application to WizardState.PresentingPhotos. Additionally, we grab all the images from localStorage storing them in an array.

Snippet from ControlWizard.startCountDownTimer.

this.images = [];
for (var i = 0; i < this.imageOptions.photosToTake; ++ i) {
    this.images.push(localStorage.getItem(`${i}.image.png`));
}

The conditional markup for the presenting of the photos is simple.

Snippet from control-wizard.component.html.

<div *ngIf="isPresentingPhotos" class="card ccc-border black-glow">

    <div class="col-1">
        <img *ngIf="images.length" src="{{ images[animationIndex] }}"
             width="640" height="480" />
    </div>
    <div class="col-2 ccc-bg-cream big bold black-inset">
        <div class="ccc-orange fs-38 black-glow">
            2018
        </div>
        <img height="360" class="black-glow" src="../../assets/ccc-logo.png" />
        <div class="twitter-blue black-glow">
            #DeveloperCommunity
        </div>
    </div>

</div>

I opted out of generating the .gif on the client side, so instead I simply animate by changing the img.src on a timer. Again, we'll properly generate a .gif on the server at a later time, but for now this will do just fine.

Snippet from ControlWizard.startAnimationTimer.

private startAnimationTimer(): void {
    this.stopAnimationTimer();
    this.animationTimer =
        setInterval(() => {
            const index = (this.animationIndex + 1);
            this.animationIndex =
                index >= this.images.length
                    ? 0
                    : index;            
        }, this.imageOptions.animationFrameDelay);
}

At this point, the user is presented with the sample animation. They could opt to "retake" the photos or if they're satisfied, they could "send" them. If the select "send" they are presented with the number-pad component, which enables them to type in their phone number -- and text a link to their phone for sharing!

Putting It All Together

Here is a look at the application in action.

Requirements

To run this locally you'll need a few things setup first. After pulling the bits from Microsoft's GitHub (never thought I get to say that), you need the following:

Azure Blob Storage -- Account / ConnectionString
Twilio -- Developer Account ID / AuthToken / From Phone Number

These values should be stored as environment variables with the following names:

photoboothconnection
twilioaccountsid
twilioauthtoken

Finally, feel free to toy around with the other configuration settings as you deem necessary.

Angular HTTP Tips For Success

David Pine — Mon, 25 Jun 2018 00:00:00 GMT

Intro

I love working with the Angular HttpClient. It is easy to use and was designed to work with RxJS. It is vastly different from the AngularJS implementation, if you're curious I wrote about these differences here. However, there is one common issue that developers fall victim to. The issue really relates to TypeScript generics. I have also written about generics in TypeScript here. But in this post, we will reveal how the issue can easily be avoided.

The problem

The problem is that the HttpClient class exposes generic methods that allow consumers to make assumptions, these assumptions are dangerous.

<cite>ProTip</cite> Never... make... assumptions!

The assumption is that you can pass an interface with non-primitive types or a class as a generic type parameter, and that it will work as expected. This is simply not the case. Consider the following:

public getDetails(id: number): Promise<Details> {
    return this.http
               .get<Details>(`${this.baseUrl}/api/details/${id}`)
               .toPromise();
}

Most of the time we'd pass in an interface as the type parameter. Often this seems to work as the interface is a simple property bag of primitive types. The issue is that if the interface defines non-primitive types like a Date or a Function -- these will not be available at runtime. Likewise, if you pass in a class with get or set properties -- these too will not work! The specific problem is that the underlying implementation from Angular doesn't instantiate your object. Instead, it simply casts it as the given type. Ultimately, Angular is performing a [JSON.parse](https://github.com/angular/angular/blob/master/packages/common/http/src/xhr.ts#L186-L189) on the body of the response.

Part of the issue is that TypeScript is blissfully unaware that Angular will not instantiate the object and treats the return as a Promise<Details>. As such flow analysis, statement completion, and all the other amazing features that the TypeScript language services provide to your development environment work. But this is misleading because you'll encounter runtime errors -- this is the issue that TypeScript aims to solve!

Working Example

An interface with primitive types will work just fine. The JSON.parse will give you an object and because of JavaScript coercion, it works. TypeScript will treat it as this object and everything is perfect.

export interface Details {
    score: number;
    description: string;
    approved: boolean;
}

Non-Working Example

Imagine that we want to return another property from the server, so we add a Date property. Notice how our interface added this new property. Now we want to do some date logic and use some of the methods on the Date instance -- this will not work!

export interface Details {
    date: Date;
    score: number;
    description: string;
    approved: boolean;
}

The details.date property will exist, sure... but it will not be a Date instance -- instead it is simply a string. If you attempt to use any of the string methods, it will fail at runtime.

View on CodePen

Ah, we can fix this -- right?! We might think to ourselves, we'll use a class instead and then add a getDate() "get function" property that will pass the .date member to the Date constructor. Let's look at this.

export class Details {
    date: Date;
    score: number;
    description: string;
    approved: boolean;

    get getDate(): Date {
        return new Date(this.date);
    }
}

Perhaps to your surprise, this doesn't work either! The Details type parameter is not instantiated.

View on CodePen

If we add a constructor to our class and then pass in a data: any argument, we could easily perform an Object.assign(this, data). This solves several issues

The Object.assign() method is used to copy the values of all enumerable own properties from one or more source objects to a target object. It will return the target object. <cite>MDN Web Docs</cite>

View on CodePen

JavaScript to the rescue

What's to stop a consumer from trying to interact with the details.date property -- if you recall it is still typed as a Date. This is error-prone and will cause issues -- if not immediately, certainly later on. Ideally, all objects that are intended to map over from JSON should contain primitive types only.

If you're set on using a class, you should use the RxJS map operator.

public getDetails(id: number): Promise<Details> {
    return this.http
               .get<Details>(`${this.baseUrl}/api/details/${id}`)
               .map(response => new Details(response.json()))
               .toPromise();
}

But what if we wanted an array of details to come back -- that's easy too?!

public getDetails(): Promise<Details[]> {
    return this.http
               .get<Details>(`${this.baseUrl}/api/details`)
               .map(response => {
                   const array = JSON.parse(response.json()) as any[];
                   const details = array.map(data => new Details(data));
                   return details;
               })
               .toPromise();
}

Types That Work Without Intervention

This table details all the primitive types that will map over without a constructor or any other intervention.

Primitive Types	Description
`string`	Already a `string` anyways
`number`	Coercion from `string` to `number`
`boolean`	Coercion from `string` to `boolean`
`array`	As long as all types are primitives also
`tuple`	Follows same rules as `array`

Conclusion

While TypeScript and Angular play nicely together, at the end of the day we're all battling JavaScript. As long as you're aware of how your tool, framework, or technology works and why it works a certain way -- you're doing great! Take this bit of knowledge and share it with the world. If it helps you, hopefully, it will help someone else too!

WebAssembly

David Pine — Sun, 05 Aug 2018 00:00:00 GMT

I set out a while ago to try to interview various community leaders for their take on WebAssembly. If you're unfamiliar with WebAssembly, here's a definition for you.

WebAssembly is a binary instruction format for a stack-based virtual machine <cite>webassembly.org</cite>

<br/> That's a lot to try to parse, right?! I was able to get an interview with Steve Sanderson, which I'm going to share in this post. Steve is a pretty amazing individual and I'm grateful to have been able to interview him.

Additionally, one of the other's that I reached out to was Scott Hanselman. Scott offered up something really special, rather than replying to the questions - he gave me an unpublished interview (that has since been published) that he did with Steve Sanderson on his hanselminutes podcast!

Interview

So, here is the interview itself. Rather short and sweet - a meager six questions but I'm grateful to share it with you all.

Question 1

WebAssembly - is it just hype or do you believe this is the future of web development?

<br/> While this question is rather broad, it was my hope to gauge the true overarching value of this web technology. I really like Steve's answer.

I hope that the future of web development includes giving developers a wider choice of languages and platforms.<br/>There's nothing wrong with JavaScript, but our industry would be healthier if multiple paradigms and specializations were better catered for. <cite>Steve Sanderson</cite>

<br/> This response is really powerful, he's absolutely right. We as developer's should have the choice of technology that will make us happy, but more importantly - we should have more options so that we are empowered to pick the right tool for the job.

Question 2

Why is Blazor labeled an "experiment", there seems to be a significant effort in developing it?

<br/> Part of the motivation behind this question was to dig a little more. Blazor has been active development now for eight months, and has a lot of attention from the developer community.

I think Steve's response was rather generic and I still believe that this will become a full-blown product!

Because it is an experiment, in the sense that it's not a committed product. We are putting significant effort into working out whether it's a product we should build. <cite>Steve Sanderson</cite>

<br/> I'll leave it to you, does this look like an "experiment"?

Question 3

Should developers be learning about WebAssembly today and considering it for future projects as an alternative to existing technologies?

<br/> With this question I wanted to try to understand where web developers should be focusing their efforts. There is so many new things that come and go, kudos to Microsoft for taking that problem seriously and evaluating Blazor. Here is what Steve had to say about this.

I would be very surprised if JavaScript isn't involved in web development for as long as the web exists as an application platform. It may become analogous to Bash scripts: ubiquitous, can do everything in theory, and excellent for gluing together other technologies. <cite>Steve Sanderson</cite>

<br/>

Question 4

Silverlight is dead, WebForms is still dying and Razor Pages (and MVC) are fairly prevalent. SPA frameworks like Angular and React are pushing business logic client-side, WebAssembly would make this easier too. Is Blazor an attempt to compete with SPA frameworks?

There are lots of web development technologies out there today, what makes blazor special - right?

Blazor is an attempt to move the SPA world forwards into an era where developers have more freedom to choose other languages and platforms. <cite>Steve Sanderson</cite>

<br/> There you have it, blazor is a SPA framework giving us the magic of C# in the browser.

Question 5

If you could change one thing about WebAssembly, what would you change and why?

<br/> I love these kinds of questions, it gives us a look into potential shortcomings of things we've yet to invest much time in.

I'd like true multithreading, because lots of languages and platforms assume that exists. Fortunately it is on the spec roadmap. <cite>Steve Sanderson</cite>

<br/>

Question 6

WebAssembly performance seems almost too good to be true, is it overrated - why or why not?

<br/> There are indications of its performance being "near native" and some say that, but what does it really mean? Steve explains that pretty well.

I don't find it surprising or too good to be true. We have known for a long time that a high-level bytecode plus modern JIT allows performance close to plain machine code. WebAssembly is a JITing platform so it should perform similarly. <cite>Steve Sanderson</cite>

<br/>

Conclusion

WebAssembly is a pretty amazing bit of technology. Microsoft's vision of bring C# everywhere is coming to fruition with the help of WebAssembly. I'm thankful to be a web developer in this day and age, as I'll be given the opportunity to take my favorite programming language to the web!

Writing a Blazor App

David Pine — Mon, 20 Aug 2018 00:00:00 GMT

Every time a developer encounters a new technology it's in our nature to explore it. This is the case with WebAssembly, and Microsoft's vision of the world in Blazor. Blazor is single page application framework that sits atop of WebAssembly, but it's still considered an experiment. I had the chance to interview Steve Sanderson about WebAssembly and Blazor -- I shared that post earlier this month. Now, I'd like to explore Blazor with you a bit more.

Blazor

There are plenty of resources for learning Blazor, here are two of my favorite:

A Practical Application

Are you tired of the "TODO" application, I know I am?! I decided to go beyond the typical demonstration apps from the templates and the "TODO" apps that are so prevalent today - instead, we'll write an application that will hopefully put a smile on your face! I call it "Blazing Chuck"...

I have been using The Internet Chuck Norris Database in my demos for as long as I can remember. Who doesn't love a good nerdy joke? We will make some calls using the HttpClient to GET a nerdy Chuck Norris based joke - like I said before, extremely practical application .

If you'd rather have a look at the GitHub project yourself, check it out here. Please give me a star, or fork it, or send along a pull request to help me make this example project even better.

Boring Parts

`Program.cs`

Our Blazor applications entry point is the Main method of the Program.cs. Here we simply create our host builder, using the Blazor Startup class and run.

using Microsoft.AspNetCore.Blazor.Hosting;

namespace IEvangelist.Blazing.Chuck
{
    public class Program
    {
        public static void Main(string[] args)
            => CreateHostBuilder(args).Build().Run();

        public static IWebAssemblyHostBuilder CreateHostBuilder(string[] args)
            => BlazorWebAssemblyHost.CreateDefaultBuilder()
                                    .UseBlazorStartup<Startup>();
    }
}

`Startup.cs`

Our startup logic should look very familiar to those who have been developing with ASP.NET Core as it uses the same nomenclature we've all grown accustomed to. We have a ConfigureServices where we add services to our IServiceCollection instance for our application. We will need to add CORS, for cross-origin resource sharing. These services can be used later by dependency injection. We also have our Configure method, which allows us to add various things to our application. In this specific case we add the App Razor page.

using Microsoft.AspNetCore.Blazor.Builder;
using Microsoft.Extensions.DependencyInjection;

namespace IEvangelist.Blazing.Chuck
{
    public class Startup
    {
        public void ConfigureServices(IServiceCollection services)
            => services.AddCors(
                options =>
                    options.AddDefaultPolicy(
                        builder =>
                            builder.AllowAnyOrigin()
                                   .AllowAnyMethod()
                                   .AllowAnyHeader()
                                   .AllowCredentials()));

        public void Configure(IBlazorApplicationBuilder app) 
            => app.AddComponent<App>(nameof(app));
    }
}

Less Boring Parts

`wwwroot/index.html`

Let's take a look at this simple markup file. The <head> element doesn't contain anything special or unusual, let's checkout the <body>. We have a link to my GitHub project, which sits in the top right hand corner of the screen.

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width">
    <title>IEvangelist.Blazing.Chuck</title>
    <base href="/" />
    <link href="css/bootstrap/bootstrap.min.css" rel="stylesheet" />
    <link href="css/site.css" rel="stylesheet" />
</head>
<body>
    <a href="https://github.com/IEvangelist/IEvangelist.Blazing.Chuck" target="_blank">
        <img style="position: absolute; top: 0; right: 0; border: 0;"
             src="https://s3.amazonaws.com/github/ribbons/forkme_right_darkblue_121621.png"
             alt="Fork me on GitHub">
    </a>

    <app class="grid">
        <div class="grid-content">
            <div class="grid-center">
                <div class="loading">
                    <h1>Loading...</h1>
                    <h1>Please wait.</h1>
                    <div class="spinner">
                        <div class="rect1"></div>
                        <div class="rect2"></div>
                        <div class="rect3"></div>
                        <div class="rect4"></div>
                        <div class="rect5"></div>
                    </div>
                </div>
            </div>
        </div>
    </app>

    <script src="_framework/blazor.webassembly.js"></script>
</body>
</html>

Then we have a familiar <app> element -- while it is a non-standard element it has become common nomenclature for single page applications. Think of it as a target for where your SPA aims to render! The contents are irrelevant, right?! That is not entirely true...you've probably become accustomed to SPA applications initially displaying a "Loading..." screen that is simply black text on a white background. This is a bit boring, no?!

I've made mine more flashy and consistent with the rest of the application.

<cite>ProTip</cite> Your application is represented on the initial request, make the most of it!

Here is what my loading application looks like:

Intriguing Parts

`Index.razor`

This file is getting larger, and it's probably time that I break it into smaller components. I say that realizing that it is only 46 lines long, but still -- having mixed some C# into some HTML doesn't really feel right to me. Perhaps I'm a bit biased, but I'm arguably one of the C# languages biggest fans. I've been conflicted about this for a while, and I've felt the same when I see templating markup in Angular and even more so with React's JSX. Here it is, in its entirety.

@page "/"
@inject HttpClient Http

<div class="grid-center">
    <img id="chuck" class="center glow @((_isLoading ? "shaking" : ""))"
         src="/img/chuck-norris.png" />
</div>

<div class="grid-joke">
    <div class="alert alert-danger" role="alert">
        @if (_isLoading) {
            <h1 class="hg-font">...</h1>
        } else {
            <h1 class="hg-font">@_joke.value.joke</h1>
        }
    </div>
</div>
<div class="grid-btn">
    <button type="button" disabled="@_disabled"
            class="btn btn-warning btn-lg hg-font fixed-button"
            onclick="@GetJokeAsync">
        Kick Chuck?!
    </button>
    <div class="thanks">
        Special thanks to our friends at <a href="http://www.icndb.com/" target="_blank">ICNDB</a> and
        <a href="http://tobiasahlin.com/spinkit/" target="_blank">SpinKit by Tobias Ahlin</a>!
    </div>
    <div class="">
        <code>
            <pre style="color: azure !important;">Debug: Shift + Alt + D</pre>
        </code>
    </div>
</div>

@functions {
    Result _joke;
    bool _isLoading = true;
    string _disabled => _isLoading ? "disabled" : null;

    protected override Task OnInitAsync() => GetJokeAsync();

    private async Task GetJokeAsync() {
        _isLoading = true;
        _joke =
            await Http.GetJsonAsync<Result>(
                "https://api.icndb.com/jokes/random?limitTo=[nerdy]");
        _isLoading = false;
    }
}

I want to break up this explanation a bit, we'll start with the directives.

Directives

`@page`

This works with the Blazor router, and specifies the client side route. Our route for the index page is simply "/". We could have multiple routes if we wanted but our application is rather simple.

`@inject`

Next, the @inject directive. This directive instructs our dependency injection framework to "inject" the desired type as an instance into our component. We then have access to it wherever we'd like to consume it.

`@functions`

Functions can exist anywhere in the *.razor file, however it is most common and best practice to place them at the bottom of the file. These "functions" will serve as the C# source code for the component. In our example we override the Task returning OnInitAsync method. This is one of several lifecycle methods. We express our override as the invocation of the GetJokeAsync method. The GetJokeAsync method toggles the _isLoading flag, and makes an async call to the "Internet Chuck Norris Database" API. We use the HttpClient that has been injected into our component instance to call the GetJsonAsync function given the URL and type-parameter of our Result object. The Result object contains the C# representation of the returned JSON result, which has the joke.

Markup

The markup is very simple. There is nothing exciting here, a few simple examples of how to use various binding approaches. We can conditionally bind a class on an img element for example, this is demonstrated when we're requesting a joke. Likewise, we can conditionally show an ellipsis when we're loading else we will display the resulting punch-line from our API result.

We bind to the onclick of our "Kick Chuck" button element. When this element is clicked, the framework will invoke our GetJokeAsync function. We then fetch a new joke, toggle the _isLoading bit and then render the updates to the markup. One thing that you may notice is that the actual html that is sent to your browser doesn't have an event handler for the button click - what is the magic you speak of?!

This is where our <script src="_framework/blazor.webassembly.js"></script> comes in. There is a bit of framework magic that attaches event listeners, etc. This bit of JavaScript manages event delegation, attaching, removing, as well as a slue of other various DOM relates interactions that tether our .NET components to their WebAssembly counterparts.

For more details on how this is implemented, please have a look at the Microsoft.AspNetCore.Blazor.Browser.JS project.

A Word On Interpreted Mode

When developing your Blazor applications, you'll be using "interpreted mode". Interpreted mode will take your *.dlls on the client, and dynamically load then via the Mono Runtime. The Mono Runtime is compiled to WebAssembly, and represented by the mono.wasm file. This entire process, is actually really fast!

Debugging C# In Chrome DevTools

Debugging is only available within Chrome and is very limited.

<br />

"Blazing Chuck!"

Here it is, the moment you've been waiting for. Putting all the pieces together, and you have "Blazing Chuck". Go forth, and kick chuck. Disclaimer, this actually doesn't work well (or at all) on mobile -- for best results explore on a desktop... more to come once I figure out the issue with that.

Thanks

Special thanks to our friends at ICNDB for their amazingly hilarious and free API. Also, SpinKit by Tobias Ahlin for the simple HTML and CSS loading indicator!

DMP in 3: RxJS Debounce

David Pine — Sun, 11 Nov 2018 00:00:00 GMT

import { YouTube } from '@astro-community/astro-embed-youtube';

I recently decided to give creating videos a test drive. The problem with creating video content is the fact that it's really time consuming to do, but the time investment can be worth the effort if you're able to truly deliver some sort of value. Another problem we're faced with in the technical community is that videos can be very lengthy. Enter DMP in 3, a video series of 3 minute videos. The idea is to identify a common programming problem, demonstrate a common solution with explanation and then quickly review the entire scenario.

I've managed to put my first episode together, and I have so much more respect for those video content developers in our community. This was a HUGE effort and I'm still not fully satisfied with it, but I will improve with practice. If you have ideas for something you want covered - please leave a comment below.

Episode 1

In this first episode we cover a scenario where we're working a large set of data. We need to implement a filter feature for the end user. The issue is that when filtering a large data set, the user will experience performance implications as each char they input performing the filtering logic. To solve this we use the RxJS debounce operator.

Video

GitHub Source Code

C# All The Things

David Pine — Sun, 16 Dec 2018 00:00:00 GMT

import { Tweet } from '@astro-community/astro-embed-twitter';

I'm proud to share that this post is part of the C# Advent Calendar and it's my second year contributing to it! I encourage you to check out all the others here.

<br />

Developers Are Lazy

In the world of web development it is hard to escape certain tools that we are forced to rely on. As developers we're innately lazy and it is safe to say that perhaps we don't really care enough to look into other tooling options. Let's face it... you're lazy, and I'm lazy and that is all there is to it. .NET Core offers global tooling, much like NPM you can use these tools for various build automation tasks. It's worth exploring .NET Core Global Tooling to see how it might enable us to be even more lazy!

In this post I will cover how I have utilized the .NET Core Global Tooling feature to my advantage, and how you as a developer can easily consume it.

Let's Use It Already

I was recently working on a small and very simple web project. It served up some light-weight HTML, CSS and JavaScript. I thought to myself "it would be useful to minify these files", but in order to do so I would have relied on NPM and I simply didn't want to. Instead, I wrote a .NET Core Global Tool. It's named Miglifier, well because naming things is hard and it does two things..."minifies" and "uglifies" files, thus it "miglifies" them 😅. It is extremely simple to consume.

From the .NET CLI execute the following command to install the latest version.

dotnet tool install --global dotnet-miglifier

This will install "miglifier" globally. You can then use it by simply invoking the following command and passing in the "wwwroot" directory. The "wwwroot" directory argument instructs "miglifier" where to scan for files.

<cite>ProTip</cite> You do not actually need to invoke dotnet miglifier, you can simply say miglifier and omit the dotnet from the command.

Each file that is found will be "miglified" and then written back to disk.

miglifier "wwwroot"
Scanning for CSS, JavaScript and HTML files to process.
Processing 1 Css file(s).
        .\wwwroot\main.min.css

Processing 1 Js file(s).
        .\wwwroot\main.min.js
        .\wwwroot\utilities.min.js

Processing 1 Html file(s).
        .\wwwroot\main.min.html

Successfully miglified 3 files!

It is limited in its functionality at this point. The ability to configure how the "miglifier" will operate is supported through a miglify.json file. It supports globing for input directories. It allows each type to have their own output directory. All the settings for the CSS, HTML and JavaScript files are serialized versions of their C# equivalent. As such, you can control it anyway you see fit...that is to say so long as it confines to the NUglify package. By default, it simply works as an in-place minification of CSS, HTML and JavaScript files - for now (more to come soon)! This results in a *.min.* file of the corresponding file type. It maintains the same folder hierarchy and will leave files where they were.

Building the .NET Core Tool

I relied heavily on the documentation from the official Microsoft site on How to Create a .NET Core Global Tool. I was thoroughly inspired by my good friend Andrew Lock and his awesome post on the subject here. We begin our process with a simple command line template from within the File > New Project menu option of Visual Studio.

Then we'll need to edit the .csproj file and manually set <IsPackable>true</IsPackable> and <PackAsTool>true</PackAsTool>. This enables your command line app to be treated as a .NET Core Global Tool. Note that we've given it a title, command line and assembly name - all for good measure.

<PropertyGroup>
    <OutputType>Exe</OutputType>
    <IsPackable>true</IsPackable>
    <PackAsTool>true</PackAsTool>
    <LangVersion>latest</LangVersion>
    <Title>dotnet-miglifier</Title>
    <ToolCommandName>dotnet-miglifier</ToolCommandName>
    <AssemblyName>dotnet-miglifier</AssemblyName>
</PropertyGroup>

C# Bits 😎

Make no mistake, this little command line application is packed full of some awesome C# bits! It starts out as a McMaster command line utilitarian app - details here. It is powered by the .NET library for globing, Glob - this is what enables our config file to have input patterns like "**/*.js". I wrote a few extension methods for mapping my C# MiglifySettings class object to JSON. Let's start there... here is the settings class, it is rather simple.

public class MiglifySettings
{
    public IDictionary<MiglifyType, DirectorySettings> Globs { get; set; } =
        new Dictionary<MiglifyType, DirectorySettings>
        {
            [MiglifyType.Css] = new DirectorySettings { Input = "**/*.css" },
            [MiglifyType.Html] = new DirectorySettings { Input = "**/*.html" },
            [MiglifyType.Js] = new DirectorySettings { Input = "**/*.js" }
        };

    public CodeSettings JavaScriptSettings { get; set; } = new CodeSettings();
    public CssSettings CssSettings { get; set; } = new CssSettings();
    public HtmlSettings HtmlSettings { get; set; } = new HtmlSettings();
}

public class DirectorySettings
{
    public string Input { get; set; }
    public string Output { get; set; }
}

One cool bit of C# to call attention to here is the usage of collection initializers with our dictionary instantiation. Note how we can directly assign into an index. This was introduced as part of C# 6 to make initialization more consistent with common usage. For Dictionary<TKey, TValue> it is common to add or update values via the indexer. Here is the extension methods I mentioned that I'm using to serialize this class to and from JSON.

public static class StringExtensions
{
    public static T To<T>(this string json) 
        => JsonConvert.DeserializeObject<T>(json, JsonSettings.SerializerDefaults);
}

public static class ObjectExtensions
{
    public static string ToJson<T>(this T instance) 
        => JsonConvert.SerializeObject(instance, JsonSettings.SerializerDefaults);
}

With these two extension methods we can easily walk up to an instance of the MiglifySettings class, serialize it to a JSON string and vice versa -- it is pretty powerful. In case you're wondering where the JsonSettings.SerializerDefaults comes from, it is a simple helper class with the default settings that I prefer for serializing JSON. Here they are...

static class JsonSettings
{
    static readonly DefaultContractResolver _contractResolver =
        new DefaultContractResolver
        {
            NamingStrategy = new CamelCaseNamingStrategy()
        };

    internal static JsonSerializerSettings SerializerDefaults { get; } =
        new JsonSerializerSettings
        {
            DefaultValueHandling = DefaultValueHandling.IgnoreAndPopulate,
            ContractResolver = _contractResolver,
            Formatting = Formatting.Indented,
            NullValueHandling = NullValueHandling.Ignore
        };
}

Now, in the spirit of C# I'd like to share something rather special with you. Consider this my Christmas 🎁 to you as part of the C# Advent Calendar...deconstruction 😈! I posted about C# 7 when it was first released and while this is a C# 7 feature it is a little different. With the introduction of tuples the language also gave us deconstruction of tuples. In addition to deconstructing tuples we can actually deconstruct anything that has a public void Deconstruct([out T value]) method, where the out parameters serve as the ordinals to deconstructing a target tuple type. In other words, we can deconstruct non-tuple types into tuples. Let's ...

In the miglifier app we accept two arguments.

The Path argument is the root directory in which we'll scan for files
The MiglifyJsonPath (optional) argument is the path to the miglify.json file

This configuration file is deserialized and passed into the GetMiglifiedFiles function. This uses glob patterns to search for all the target files to work on processing them along the way. Eventually it will return the results -- the results are of type IEnumerable<MiglifyFile>. We group the results and then convert them to a Dictionary<MiglifyType, List<MiglifyFile>> and foreach over our collection. Here is the beauty of it... we can deconstruct the KeyValuePair<MiglifyType, List<MiglifyFile>>!

var settings = await LoadMiglifySettingsAsync(miglifyJson);
var results = GetMiglifiedFiles(wwwroot, settings);

// Deconstruct our key value pairs into type and files.
foreach (var (type, files) in results.GroupBy(f => f.Type)
                                     .ToDictionary(grp => grp.Key, grp => grp.ToList()))
{
    // Iterate our files
    foreach (var file in files)
    {
        // Do other stuff here...
    }
}

When I first learned about this, I was so excited to tweet about it!

Credit 🙏🏼

I would like to call attention to the 3rd party dependencies that helped make this .NET Core Global Tool possible. Without them, it would have been a much larger undertaking. Here are all list of packages that I'm using.

<PackageReference Include="Centare.Extensions" Version="1.0.19" />
<PackageReference Include="Glob" Version="0.4.0" />
<PackageReference Include="McMaster.Extensions.CommandLineUtils" Version="2.2.5" />
<PackageReference Include="Humanizer.Core" Version="2.5.1" />
<PackageReference Include="Newtonsoft.Json" Version="11.0.2" />
<PackageReference Include="NUglify" Version="1.5.12" />

The Centare.Extensions is an amazing package, with tons of great extension methods. There is one in particular that does the bulk of the work, that is the NUglify package. There is an immense background to this project that is documented here in their very detailed README.md. Know that, without this package the "miglifier" would probably not exist for you today!

Badges 🤘🏼

The NuGet & Azure DevOps badges are only part of the story, by all means please check out the project yourself IEvangelist.DotNet.Miglifier! I look forward to pull-requests, feature requests, or issues. Happy coding, friends...

Angular - The Color Guessing Game

David Pine — Thu, 14 Mar 2019 00:00:00 GMT

The Story Behind The Game

I have three sons. Lyric who is six and a half, Londyn who is four and half, and Lennyx who is two and half. As you might imagine, they seldom agree on things. For example when it's family move night, "which movie we'll watch?", or "who gets to go first?" when playing a game. These important life decisions are often decided by playing the color guessing game. My wife or I will choose a color at random and have the boys guess a color until someone guesses the correct color. Whoever guesses correctly is the winner and they get to choose the movie or go first, etc. You get the point!

In this post we'll discuss how to create an Angular application using the CLI, Material Design and Animations. As a spoiler alert, that application is hosted here and the source code is up on GitHub here.

Angular CLI

I've been an Angular developer for a long time now, and I'll admit it took me a bit to get used to the Angular CLI. But once I got over my need to hand-code all the boilerplate, I'm never looking back! The command line interface simplifies so many aspects of Angular development by allowing the developer to focus on the application logic. The CLI handles everything from creating a new project to generating modules, components, pipes, services, classes, interfaces, enums, directives, guards, etc... it also tests, lints and serves up your app for local debugging! Let's get started, shall we?!

npm install -g @angular/cli

This installs the CLI globally, and we're ready to begin. Executing the following command will generate a new project named color-game and navigate into the newly created project directory. It also specifies a few preferences:

SCSS for styling
Skips .spec.ts test files
Doesn't include routing, we won't need it
Minimal scaffolding, etc

ng n color-game --minimal=true --S=true --routing=false --style=scss
cd color-game

Let's add some components that will help us structure the app in a meaningful way.

ng g c color-block
ng g c game-board
ng g c instructions
ng g c players

We've successfully added a color-block, game-board, instructions and players components. There are a few relationships to call attention to. A game-board handles the layout of the color-block, instructions and players. We'll need to communicate between various components, as such we'll add some services to handle this.

ng g s services\data-storage
ng g s services\game-engine

If you did this correctly you're directory should look similar to the following:

├── app
│   ├── color-block
│   │   └── **/*.scss|**/*.ts|**/*.html
│   ├── game-board
│   │   └── **/*.scss|**/*.ts|**/*.html
|   |── instructions
│   │   └── **/*.scss|**/*.ts|**/*.html
│   ├── players
│   │   └── **/*.scss|**/*.ts|**/*.html
│   └── services
│       ├── data-store.service.ts
|       └── game-engine.service.ts
| .. etc ..

Material

I am a fan of the material design principles and the ease of use. Let's add angular material to the party as well. From the same command line window, let's execute the following which will install angular material as a dependency.

npm install @angular/material

<cite>ProTip</cite> If you get an notifications about vulnerabilities address them immediately!<br/> Simply, execute npm audit fix

Now, open up the style.scss file and let's add an import statement at the top and a bit of simple CSS.

@import "~@angular/material/prebuilt-themes/pink-bluegrey.css";

html, body {
    height: 100%;
}

body {
    margin: 0;
}

This will effectively set the material theme to the "pink bluegrey" variation, which is personally my favorite. For more details on material - check out their site here. Let's set the background color using the newly added theme classes. Copy this HTML in the the index.html.

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <title>The Color Game</title>
    <base href="/">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <link rel="icon" type="image/x-icon" href="favicon.ico">
    <link href="https://fonts.googleapis.com/css?family=Roboto:300,400,500" rel="stylesheet">
    <link href="https://fonts.googleapis.com/icon?family=Material+Icons" rel="stylesheet">
  </head>
  <body class='mat-app-background'> <!-- Apply this class to the body -->
    <app-root></app-root>
  </body>
</html>

Later, you'll notice elements and classes prefixed with mat- this indicates that they are from angular material. Finally, we'll need to import the material modules - it's cleaner to separate this out into it's own module and import it into the app.module.ts. Let's generate a new module named material-all and keep it at the same level as our existing app.module.

ng g module material-all --flat

Now, copy this into the newly created material-all.module.ts.

import { NgModule } from '@angular/core';
import { CommonModule } from '@angular/common';
import { MatCheckboxModule } from '@angular/material';
import { MatButtonModule } from '@angular/material';
import { MatRippleModule } from '@angular/material/core';
import { MatBadgeModule } from '@angular/material/badge';
import { MatInputModule } from '@angular/material/input';
import { MatAutocompleteModule } from '@angular/material/autocomplete';
import { MatDatepickerModule } from '@angular/material/datepicker';
import { MatFormFieldModule } from '@angular/material/form-field';
import { MatRadioModule } from '@angular/material/radio';
import { MatSelectModule } from '@angular/material/select';
import { MatSliderModule } from '@angular/material/slider';
import { MatSlideToggleModule } from '@angular/material/slide-toggle';
import { MatMenuModule } from '@angular/material/menu';
import { MatSidenavModule } from '@angular/material/sidenav';
import { MatToolbarModule } from '@angular/material/toolbar';
import { MatListModule } from '@angular/material/list';
import { MatGridListModule } from '@angular/material/grid-list';
import { MatCardModule } from '@angular/material/card';
import { MatStepperModule } from '@angular/material/stepper';
import { MatTabsModule } from '@angular/material/tabs';
import { MatExpansionModule } from '@angular/material/expansion';
import { MatButtonToggleModule } from '@angular/material/button-toggle';
import { MatChipsModule } from '@angular/material/chips';
import { MatIconModule } from '@angular/material/icon';
import { MatProgressSpinnerModule } from '@angular/material/progress-spinner';
import { MatProgressBarModule } from '@angular/material/progress-bar';
import { MatDialogModule } from '@angular/material/dialog';
import { MatTooltipModule } from '@angular/material/tooltip';
import { MatSnackBarModule } from '@angular/material/snack-bar';
import { MatTableModule } from '@angular/material/table';
import { MatSortModule } from '@angular/material/sort';
import { MatPaginatorModule } from '@angular/material/paginator';

@NgModule({
  declarations: [],
  imports: [
    CommonModule,
    MatCheckboxModule,
    MatCheckboxModule,
    MatBadgeModule,
    MatRippleModule,
    MatButtonModule,
    MatInputModule,
    MatAutocompleteModule,
    MatDatepickerModule,
    MatFormFieldModule,
    MatRadioModule,
    MatSelectModule,
    MatSliderModule,
    MatSlideToggleModule,
    MatMenuModule,
    MatSidenavModule,
    MatToolbarModule,
    MatListModule,
    MatGridListModule,
    MatCardModule,
    MatStepperModule,
    MatTabsModule,
    MatExpansionModule,
    MatButtonToggleModule,
    MatChipsModule,
    MatIconModule,
    MatProgressSpinnerModule,
    MatProgressBarModule,
    MatDialogModule,
    MatTooltipModule,
    MatSnackBarModule,
    MatTableModule,
    MatSortModule,
    MatPaginatorModule
  ],
  exports: [
    MatCheckboxModule,
    MatCheckboxModule,
    MatBadgeModule,
    MatRippleModule,
    MatButtonModule,
    MatInputModule,
    MatAutocompleteModule,
    MatDatepickerModule,
    MatFormFieldModule,
    MatRadioModule,
    MatSelectModule,
    MatSliderModule,
    MatSlideToggleModule,
    MatMenuModule,
    MatSidenavModule,
    MatToolbarModule,
    MatListModule,
    MatGridListModule,
    MatCardModule,
    MatStepperModule,
    MatTabsModule,
    MatExpansionModule,
    MatButtonToggleModule,
    MatChipsModule,
    MatIconModule,
    MatProgressSpinnerModule,
    MatProgressBarModule,
    MatDialogModule,
    MatTooltipModule,
    MatSnackBarModule,
    MatTableModule,
    MatSortModule,
    MatPaginatorModule
  ]
})
export class MaterialAllModule { }

😁 That is a lot of code, thankfully we only have to do that once. Now, in the app.module.ts we'll import this module empowering our app with all things material!

You will want to copy the following into the the app.module.ts.

import { BrowserModule } from '@angular/platform-browser';
import { NgModule } from '@angular/core';
import { FormsModule } from '@angular/forms';

import { AppComponent } from './app.component';
import { BrowserAnimationsModule } from '@angular/platform-browser/animations';
import { MaterialAllModule } from './material-all.module';
import { GameBoardComponent } from './game-board/game-board.component';
import { ColorBlockComponent } from './color-block/color-block.component';
import { InstructionsComponent } from './instructions/instructions.component';
import { PlayersComponent } from './players/players.component';

@NgModule({
  declarations: [
    AppComponent,
    GameBoardComponent,
    ColorBlockComponent,
    InstructionsComponent,
    PlayersComponent
  ],
  imports: [
    BrowserModule,
    FormsModule,
    BrowserAnimationsModule,
    MaterialAllModule
  ],
  providers: [],
  bootstrap: [AppComponent]
})
export class AppModule { }

Animations

I love making subtle animations, they can enrich the user's experience...but they can also ruin it just as easily. You must approach the use of animations as you do other UX related considerations, such as accessability. Furthermore animations can be challenging to implement, luckily angular has a story for that too - check out angular animations.

In the color-block.component.ts we're going to add some animations.

import { Component, Input } from '@angular/core';
import { GameEngineService, GameState } from '../services/game-engine.service';
import {
  trigger,
  state,
  style,
  animate,
  transition
} from '@angular/animations';

@Component({
  selector: 'color-block',
  templateUrl: './color-block.component.html',
  styleUrls: ['./color-block.component.scss'],
  animations: [
    trigger('wasClicked', [
      state('idle', style({
        transform: 'scale(1)'
      })),
      state('clicked', style({
        transform: 'scale(1.2)'
      })),
      transition('idle => clicked', [
        animate('0.4s')
      ]),
      transition('clicked => idle', [
        animate('0.1s')
      ]),
    ]),
  ],
})
export class ColorBlockComponent {
  @Input() classes: string[];
  @Input() color: string;

  get allClasses() {
    return this.isSelected
      ? this.isWinningColor
        ? [...this.classes, 'winner']
        : [...this.classes, 'selected' ]
      : this.classes;
  }

  isClicked = false;
  isSelected: boolean = false;

  private currentState: GameState;
  private isWinningColor = false;

  constructor(private readonly gameEngine: GameEngineService) {
    this.gameEngine
        .$gameStateChanged
        .subscribe((state: GameState) => {
          this.currentState = state;
          if (state === 'selectWinningColor') {
            this.isWinningColor = false;
            this.isSelected = false;
          }
        });
  }

  onClick() {
    this.isClicked = true;
    setTimeout(() => this.isClicked = false, 100);

    if (this.currentState === 'selectWinningColor') {
      this.gameEngine.setWinningColor(this.color);
      this.gameEngine.changeState('playingGame');
    } else if (this.currentState === 'playingGame') {
      this.isSelected = true;
      if (this.gameEngine.isWinningColor(this.color)) {
        this.isWinningColor = true;
        this.gameEngine.changeState('gameEnded');
      } else {
        this.gameEngine.changeState('playingGame');
      }
    }
  }
}

We import several symbols from @angular/animations and now we're ready to decorate our component. As part of the @Script decorations, we'll add the desired animations. We trigger animation on various changes of state. Then we apply style and transition from one state to another. The syntax is actually rather straightforward to read. Here is the corresponding markup.

<div [ngClass]='allClasses' (click)=onClick() [@wasClicked]="isClicked ? 'clicked' : 'idle'">
  <mat-card class='color-card'>
    <mat-card-header>
      <mat-card-title>{{ color | titlecase }}</mat-card-title>
    </mat-card-header>
    <mat-card-content>
      <div *ngIf='isSelected'>
        <mat-icon color='accent' [inline]='true'>check_box</mat-icon>
      </div>
      <div *ngIf='!isSelected'>
        <mat-icon color='accent' [inline]='true'>check_box_outline_blank</mat-icon>
      </div>
    </mat-card-content>
  </mat-card>
</div>

Putting It All Together

The game-board.component serves as the glue holding all the other sub components together. It relies on the various services for managing the state of the game through the game-engine.service.

import { Injectable } from '@angular/core';
import { ReplaySubject, Observable } from 'rxjs';

export type GameState
  = 'usersRequired' | 'selectWinningColor' | 'playingGame' | 'gameEnded';

export interface StateDetails {
  state: GameState;
  title: string;
  message: () => string;
}

@Injectable({
  providedIn: 'root'
})
export class GameEngineService {
  $gameStateChanged: Observable<GameState>;
  stateDetails = new Map<GameState, StateDetails>();

  private activePlayer: string;
  private stateBroadcast = new ReplaySubject<GameState>();
  private winningColor: string;

  constructor() {
    this.stateDetails['usersRequired'] = {
      state: 'usersRequired',
      title: 'Users Required',
      message: () => 'Add at least two players to begin...'
    };    
    this.stateDetails['selectWinningColor'] = {
      state: 'selectWinningColor',
      title: 'Select Winning Color',
      message: () => 'Have players cover their eyes, and ' + 
                     'then the "referee" select the winning color.'
    };
    this.stateDetails['playingGame'] = {
      state: 'playingGame',
      title: 'Game Active',
      message: () => `"${this.activePlayer}" please choose your color.`
    };
    this.stateDetails['gameEnded'] = {
      state: 'gameEnded',
      title: 'Game Over',
      message: () => `Congratulations... "${this.activePlayer}" has won the game!`
    };

    this.$gameStateChanged =
      this.stateBroadcast.asObservable();
  }

  isWinningColor(color: string) {
    return this.winningColor === color;
  }

  setWinningColor(color: string) {
    this.winningColor = color;
  }

  changeState(state: GameState) {
    this.stateBroadcast.next(state);
  }

  setActivePlayer(player: string) {
    this.activePlayer = player;
  }

  reset() {
    this.changeState('selectWinningColor');
  }
}

The game-engine.service has the possible states that the app can exhibit and each state represents a different way in the application. For example, when there are less than two players we enter the 'usersRequired' state. This updates the instructions.component appropriately, and disables certain controls, etc. Likewise, when we have enough players - the instructions change to "instruct" the players on what to do next.

For more details, I encourage you to dig into the source code that is publicly available up on GitHub here. Also, the application is hosted here. This game isn't styled for mobile devices, because ... well that would have taken more time than I had over the weekend to do. I hope you enjoy it and that it helps solves some of the simple little decision-making quarrels parents experience!

ASP.NET Core - Slack Slash Commands

David Pine — Thu, 21 Mar 2019 00:00:00 GMT

Background

Most of us are all "slackers", meaning we truly do spend a significant amount of time using Slack.

Slack is a collaboration hub for work, no matter what work you do. It’s a place where conversations happen, decisions are made, and information is always at your fingertips. <cite>www.slack.com</cite>

It's wildly popular in the Developer Community! In fact, almost to a fault...people are constantly sharing their "slack fatigue". I am personally a part of roughly twenty slack workspaces. One of the really cool features of slack is the ability to integrate with the tool itself through the Slack API. Imagine a plugin playground where you're free to extend the capabilities of the slack ecosystem. Look to the Slack API.

Slash Commands

A slack "slash command" is a command that slack enables when typing a leading / into the chat message input. It displays an autocomplete (or pseudo Intellisense) with the available slash commands that exist in the current workspace. You add slash commands to a workspace that you're a member of via the settings. We'll cover that in more detail a bit later, let's focus on building the application now that we have an understanding of the integration capabilities.

ASP.NET Core Web API

We're building an ASP.NET Core Web API application. We'll expose a few bits of functionality for jokes, weather and bit.ly integration to shorten urls. The slash commands are explained below.

/joke random nerdy Chuck Norris joke and /joke [share] (shares the joke in the channel)
/weather [zip-code] returns detailed weather with corresponding emoji -- from open weather API
/shortenUrl [longUrl] shortens a long URL, relies on bit.ly API

We will need to add a few configurations, services, models and routes to satisfy the desired functionality.

Prerequisites

The internet chuck norris database is one of my goto APIs for demonstrations. It doesn't require an API key, nor anything else. However, several of the other bits of functionality require registering for the API.

Bit.ly API: sign up and get your API key
Open Weather API: sign up and generate an API key

With these various API keys, we'll need to add a few environment variables. From the command line, execute the following commands.

setx BitlyOptions__Login [Bit.ly Login]
setx BitlyOptions__ApiKey [Bit.ly API Key]
setx OpenWeatherMapOptions__Key [Open Weather Key]

<cite>ProTip</cite> You will need to restart Visual Studio in order for the newly added environment variables to be available.

Slack API - Slash Command Request

Let's take a look at an example controller, the WeatherController.

using System;
using System.Threading.Tasks;
using IEvangelist.Slack.SlashCommands.Configuration;
using IEvangelist.Slack.SlashCommands.Extensions;
using IEvangelist.Slack.SlashCommands.Interfaces;
using IEvangelist.Slack.SlashCommands.Models;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Options;

namespace IEvangelist.Slack.SlashCommands.Controllers
{
    [ApiController, Route("api/weather")]
    public class WeatherController : ControllerBase
    {
        readonly IWeatherService _weatherService;
        readonly SlackOptions _slackOptions;

        public WeatherController(
            IWeatherService weatherService,
            IOptions<SlackOptions> slackOptions)
        {
            _weatherService = weatherService;
            _slackOptions = 
                slackOptions?.Value 
                ?? throw new ArgumentNullException(nameof(slackOptions));
        }

        [
            HttpPost,
            Consumes("application/x-www-form-urlencoded"),
            Produces("application/json")
        ]
        public async Task<ActionResult> Weather(
            [FromForm] SlackCommandRequest request)
        {
            var response = await _weatherService.GetWeatherAsync(request.Text);
            return new JsonResult(new
            {
                text = response.ToString()
            });
        }
    }
}

There are a few noteworthy considerations here. First, the Weather action is an HTTP Post that consumes application/x-www-form-urlencoded and produces application/json. From the post's form, we'll deserialize into the SlackCommandRequest object that looks like this.

using Newtonsoft.Json;

namespace IEvangelist.Slack.SlashCommands.Models
{
    public class SlackCommandRequest
    {
        public string Token { get; set; }

        [JsonProperty("team_id")]
        public string TeamId { get; set; }

        [JsonProperty("team_domain")]
        public string TeamDomain { get; set; }

        [JsonProperty("enterprise_id")]
        public string EnterpriseId { get; set; }

        [JsonProperty("enterprise_name")]
        public string EnterpriseName { get; set; }

        [JsonProperty("channel_id")]
        public string ChannelId { get; set; }

        [JsonProperty("channel_name")]
        public string ChannelName { get; set; }

        [JsonProperty("user_id")]
        public string UserId { get; set; }

        [JsonProperty("user_name")]
        public string UserName { get; set; }

        public string Command { get; set; }

        public string Text { get; set; }

        [JsonProperty("response_url")]
        public string ResponseUrl { get; set; }

        [JsonProperty("trigger_id")]
        public string TriggerId { get; set; }
    }
}

This is the shape of the object that slack's API returns for all slash commands.

<cite>Disclaimer</cite> I attempted to verify the slack request, however; I couldn't get it working. See my attempt verifying requests from slack for more details and SlackCommandRequestExtensions.

😨 HttpClient

Our application will need to make external API calls, we will use the HttpClient to do this. To help alleviate the concern of socket exhaustion when using HttpClient the ASP.NET Core has middleware for offering up an IHttpClientFactory. The IHttpClientFactory can create HttpClient instances using the appropriate constructor.

In the Startup.ConfigureServices method, we'll add the HttpClient by invoking the .AddHttpClient extension. This wires up all the services for resolving an instance of IHttpClientFactory. Then we will add some 💪-typed clients for the WeatherService and UrlService. We configure the typed clients by specifying their base address.

Registering Services

As previously mentioned, we have several primary intents for this application. We register some of the services differently, but it's good to see this as it exemplifies the various capabilities.

// Joke Service
services.AddHttpClient();
services.AddTransient<IJokeService, JokeService>();

// Weather Service
services.AddHttpClient<IWeatherService, WeatherService>(
    client => client.BaseAddress = new Uri("https://api.openweathermap.org/data/2.5/weather"));

// URL Service
services.AddHttpClient<IUrlService, UrlService>(
    client => client.BaseAddress = new Uri("https://api-ssl.bitly.com/v3/"));

Example Service

This is the implementation of the IJokeService which demonstrates how simple the consumption of the HttpClient is and how to easily call out to an external API. This pattern is essentially repeated in the implementations of the IUrlService and the IWeatherService, but they're calling out to different APIs with different parameters and mapping to the appropriate response type.

using System.Collections.Generic;
using System.Net.Http;
using System.Threading.Tasks;
using IEvangelist.Slack.SlashCommands.Extensions;
using IEvangelist.Slack.SlashCommands.Interfaces;
using IEvangelist.Slack.SlashCommands.Models;

namespace IEvangelist.Slack.SlashCommands.Services
{
    public class JokeService : IJokeService
    {
        readonly IList<string> _positiveEmoji = new List<string>
        {
            ":smile:",
            ":smirk:",
            ":clap:",
            ":joy:",
            ":grin:",
            ":yum:",
            ":sweat_smile:",
            ":laughing:",
            ":smiley:",
            ":rolling_on_the_floor_laughing:"
        };

        readonly IHttpClientFactory _httpClientFactory;

        public JokeService(IHttpClientFactory httpClientFactory)
            => _httpClientFactory = httpClientFactory;

        public async Task<JokeResponse> GetJokeAsync()
        {
            var client = _httpClientFactory.CreateClient();
            var json = 
                await client.GetStringAsync(
                    "https://api.icndb.com/jokes/random?limitTo=[nerdy]");

            return json.To<JokeResponse>();
        }

        public string GetRandomJokeEmoji()
            => _positiveEmoji.RandomElement();
    }
}

This example service didn't map the .BaseAddress so we use a fully qualified request URL. Additionally, this service provides a method for getting a random positive emoji that we'll append to the message when we respond to the slack slash command request.

Putting It All Together

With the application written, published to Azure App Service and integrated with Slack - we can start using it immediately. Open the Slack API Apps - Console and "Create New App". Give your app a name and select the target workspace you'd like to target.

Next, under "Features and Functionality" select "Slash Commands" to begin configuring the commands. Click "Create Command" and configure it by simply giving it a name, a URL for the API endpoint and a few other details.

Joke Command

This is the /joke command, it also supports an optional share command which will share the joke with everyone in the current channel.

Weather Command

This is the /weather [zip code] command, entering your zip code should yield a text representation of the weather as it corresponds to the given zip code.

Some people have noticed that I named the app "I've Got Jokes", but it has a weather endpoint...it's not really funny weather, it has more of a "dry" sense of humor - even on a rainy day.

Shorten URL Command

This is the /shortenUrl [long url] command. Given a URL it will shorten the URL using bit.ly API. Perhaps you're curious what long URL I shortened here, well this is the bit.ly 🤣.

Conclusion

To recap we simply put together an ASP.NET Core Web API application that was published up to Azure as an App Service. The endpoints are configured as we integrate with the slack API, and ta-da...magic. All of this source code is up on GitHub. As always, feel free to star, fork and send me a pull request!

Additional Resources

Building a GitHub profanity filter with .NET Core and Azure Functions

David Pine — Sat, 23 Nov 2019 00:00:00 GMT

import { Tweet } from '@astro-community/astro-embed-twitter';

Intro

With more than 40 million active users, GitHub is by far the largest source code hosting platform in the world. It's an open source developers dream, and ecosystem and developer community unlike any other. And with all these users and such profound openness, there's bound to be frustration from time to time. In this post we will explore an Azure Function written with ASP.NET Core 3.0 and C# 8.0. It has been designed to handle a GitHub webhook for issues and pull requests. In other words, we are able to target a specific GitHub repository and listen for new issues or pull requests - as they occur, our Azure Function is called.

When the Azure Function is invoked, it will examine the body text and title text of the issue or pull request. If either contain profanity, it replaces the profanity with less offensive content -- such as:

We'll see how to orchestrate various technologies together, and take a look at GitHub webhooks, Azure Functions, C# 8.0, CosmosDB and GraphQL. As always the complete source code is available for you're eager eyes 👀...enjoy!

GitHub Webhooks

I'm going to assume that you're unfamiliar with "webhooks". Think of a webhook as simply being an event. Like all other events, you can subscribe to them. Much like an event, when you subscribe you provide a handler or a callback. When the event occurs, it calls your handler. But with a webhook, you get a bit more control over how the event is communicated. GitHub offers webhooks for many types of events.

Open a GitHub repository that you're the owner of. From within the GitHub user interface navigate to ** Settings**, then select Webhooks from the left panel. Click the Add webhook button and explore the various options available to you for configuring a webhook.

Setting	Details
Payload URL	The fully qualified URL of the Azure Function.
Content Type	The content type of the post for your corresponding endpoint, let's select `application/json` for JSON.
Secret	This secret is used to validate that requests made to your endpoint are truly from the webhook and not malicious.
Events	There are several options. For this post, I have selected Let me select individual events and I have chosen the Issues and Pull requests.
Active	Whether or not to deliver event details when the hook is triggered. This is useful, as you can easily toggle it off and on for troubleshooting.

Securing webhooks

GitHub has an article on securing webhooks, which is useful but unfortunately it's written for Ruby. Since we've written an ASP.NET Core with C# application, we'll take a look a closer look at how to do this.

[FunctionName(nameof(ProcessWebhook))]
public async Task<IActionResult> ProcessWebhook(
    [HttpTrigger(AuthorizationLevel.Function, "POST")] HttpRequest request,
    [FromServices] IGitHubPayloadValidator payloadValidator,
    [FromServices] IGitHubWebhookDispatcher webhookDispatcher)
{
    try
    {
        var signature =
            request.Headers
                   .GetValueOrDefault("X-Hub-Signature");

        using var reader = new StreamReader(request.Body);
        var payloadJson = await reader.ReadToEndAsync();

        if (!payloadValidator.IsPayloadSignatureValid(
                Encoding.UTF8.GetBytes(payloadJson),
                signature))
        {
            return new StatusCodeResult(500);
        }

        var eventName = request.Headers.GetValueOrDefault("X-GitHub-Event");
        await webhookDispatcher.DispatchAsync(eventName, payloadJson);

        return new OkObjectResult($"Successfully handled the {eventName} event.");
    }
    catch (Exception ex)
    {
        return new StatusCodeResult(500);
    }
}

The method above is the primary entry point for our Azure Function. We decorate our method with a FunctionName attribute assigning the name of the method. Our method is defined as an async Task<IActionResult> returning method. It has three parameters, all of which are provided by the Azure Function runtime. The first parameter is the HttpRequest and is triggered via an HTTP POST. The next two parameters are decorated with the FromServices attribute, which instruct the ASP.NET Core dependency injection pipeline to resolve the corresponding implementations. We are then provided instances of a payload validator and a webhook dispatcher, we'll explore these both in more detail in a bit.

The method functions by attempting to read the X-Hub-Signature header from the request, this will be used to compare our computed signature based off the known secret. We leverage C# 8 using declarations, to instantiate a StreamReader from the request body stream. We then read the entire body, and assign our jsonPayload variable the resulting JSON response. With the signature from the header and the JSON bytes, we're ready to validate the signature.

public bool IsPayloadSignatureValid(
  byte[] bytes,
  string receivedSignature)
{
    if (string.IsNullOrWhiteSpace(receivedSignature))
    {
        return false;
    }

    using var hmac = new HMACSHA1(Encoding.ASCII.GetBytes(_options.WebhookSecret));
    var hash = hmac.ComputeHash(bytes);
    var actualSignature = $"sha1={hash.ToHexString()}";

    return IsSignatureValid(actualSignature, receivedSignature);
}

static bool IsSignatureValid(string a, string b)
{
    var length = Math.Min(a.Length, b.Length);
    var equals = a.Length == b.Length;
    for (var i = 0; i < length; ++ i)
    {
        equals &= a[i] == b[i];
    }

    return equals;
}

The IsPayloadSignatureValid implementation leverages C# 8 using declarations and instantiates a HMACSHA1 with the bytes from the configured webhook secret. The HMACSHA1 is the C# representation of the "hash-based message authentication code (HMAC), for the secure hash algorithm 1 (SHA1)". It will allow us to compute the hash of the payload bytes, then we can use our computed hash and compare it to the signature in the header. If these two are a match -- we know that the request is valid. Otherwise, it may be malicious and we can simply disregard it.

You may have noticed that we also pulled out another header, this was the X-GitHub-Event header. It tells us which GitHub event was firing. We'll use that in our dispatcher to determine which shape our JSON payload is expected to be delivered in.

Great, wow what? We have a valid call into our Azure Function from our GitHub webhook, let's do something with it. We want to examine the title and body text of incoming issues or pull_request, so let's start there.

Handling Issues and Pull Requests

If you recall earlier in this post, we are subscribed for both issues and pull_request events. We need to determine which event we're handling and take the appropriate action.

public class GitHubWebhookDispatcher : IGitHubWebhookDispatcher
{
    static readonly ValueTask NoopTask = new ValueTask();

    readonly IIssueHandler _issueHandler;
    readonly IPullRequestHandler _pullRequestHandler;

    public GitHubWebhookDispatcher(
        IIssueHandler issueHandler,
        IPullRequestHandler pullRequestHandler) =>
        (_issueHandler, _pullRequestHandler) = (issueHandler, pullRequestHandler);

    public ValueTask DispatchAsync(string eventName, string payloadJson)
        => eventName switch
        {
            "issues" => _issueHandler.HandleIssueAsync(payloadJson),
            "pull_request" => _pullRequestHandler.HandlePullRequestAsync(payloadJson),

            _ => NoopTask,
        };
}

The webhook dispatcher class requires both IIssueHandler and IPullRequestHandler implementations. It defines a dispatch functionality, that maps the issue based events to the corresponding issue handler and pull requests to its handler. This is expressed as a C# 8 switch expression. The eventName value is our target in the switch expression, and our case labels are simple expressions for our intent. This removes much of the verbosity of writing out the word, case and break. We're left with easier to read code!

Now, let's take a look at the IssueHandler implementation.

public class IssueHandler
    : GitHubBaseHandler<IssueHandler>, IIssueHandler
{
    readonly GitHubOptions _options;
    readonly IProfanityFilter _profanityFilter;
    readonly IRepository<FilterActivity> _repository;

    public IssueHandler(
        IGitHubGraphQLClient client,
        ILogger<IssueHandler> logger,
        IOptions<GitHubOptions> options,
        IProfanityFilter profanityFilter,
        IRepository<FilterActivity> repository)
        : base(client, logger) =>
        (_profanityFilter, _options, _repository) =
            (profanityFilter, options.Value, repository);
}

You may have noticed the .ctor logic is expressed as a tuple assignment. When I discovered this was possible, I questioned it - what do you think? Leave your comments on the tweet below.

Now, back to the handling of issues. What's that look like?

public async ValueTask HandleIssueAsync(string payloadJson)
{
    var payload = payloadJson.FromJson<IssueEventPayload>();
    if (payload is null)
    {
        _logger.LogWarning("GitHub issue payload is null.");
        return;
    }

    switch (payload.Action)
    {
        case "opened":
            await HandleIssueAsync(payload);
            break;

        case "reopened":
        case "edited":
            var activity =
                await _repository.GetAsync(payload.Issue.NodeId);
            if (activity?.WorkedOn
                        .Subtract(DateTime.Now)
                        .TotalSeconds <= 1)
            {
                _logger.LogInformation(
                    $"Just worked on this issue {payload.Issue.NodeId}...");
            }

            await HandleIssueAsync(payload, activity);
            break;

        case "closed":
        case "deleted":
            await _repository.DeleteAsync(payload.Issue.NodeId);
            break;

        case "assigned":
        case "demilestoned":
        case "labeled":
        case "locked":
        case "milestoned":
        case "pinned":
        case "transferred":
        case "unassigned":
        case "unlabeled":
        case "unlocked":
        case "unpinned":
            break;
    }
}

We start with a string, which represents the payload from GitHub -- it deserializes as an IssueEventPayload type. If it is null, then we're done but if it has a value we'll switch on the specific event action. When opened, we'll handle the issue but first let's discuss a bit more of what's going on here.

Cosmos DB

You're probably asking yourself, "where did this _repository come from and where is it reading from?". Since Azure Functions are stateless, and we have no way of identifying how often we're called from GitHub or when we've already worked on an issue -- we need a way of tracking this activity. I decided to use Cosmos DB as a data store. It's freakishly fast, and with a beautiful abstraction over the top of it -- we can seamlessly perform CRUD operations on any POCO object asynchronously. It's literally amazing! Here's the abstraction.

public class CosmosContainerProvider : ICosmosContainerProvider, IDisposable
{
    readonly RepositoryOptions _options;

    CosmosClient _client;
    Container _container;

    public CosmosContainerProvider(
        IOptions<RepositoryOptions> options) =>
        _options =
            options?.Value ??
            throw new ArgumentNullException(nameof(options));

    public Container GetContainer()
    {
        if (_container is null)
        {
            _client = new CosmosClient(_options.CosmosConnectionString);
            var database = _client.GetDatabase(_options.DatabaseId);
            _container = database.GetContainer(_options.ContainerId);
        }

        return _container;
    }

    public void Dispose() => _client?.Dispose();
}

We start by defining a CosmosContainerProvider class, which encapsulates the logic to instantiate and provide a Microsoft.Azure.Cosmos.Container instance. The container is available from a Microsoft.Azure.Cosmos.Database object, and requires our connection string in order to function correctly. This is what we use to read from and write to, next we have our Repository<T> implementation.

public class Repository<T> : IRepository<T> where T : BaseDocument
{
    readonly ICosmosContainerProvider _containerProvider;

    public Repository(
        ICosmosContainerProvider containerProvider) =>
        _containerProvider =
            containerProvider ??
            throw new ArgumentNullException(nameof(containerProvider));

    public async ValueTask<T> GetAsync(string id)
    {
        try
        {
            var container = _containerProvider.GetContainer();
            var response = await container.ReadItemAsync<T>(id, new PartitionKey(id));

            return response.Resource;
        }
        catch (CosmosException ex) when (ex.StatusCode == HttpStatusCode.NotFound)
        {
            return default;
        }
    }

    public async ValueTask<IEnumerable<T>> GetAsync(Expression<Func<T, bool>> predicate)
    {
        try
        {
            var iterator =
                _containerProvider.GetContainer()
                                  .GetItemLinqQueryable<T>()
                                  .Where(predicate)
                                  .ToFeedIterator();

            IList<T> results = new List<T>();
            while (iterator.HasMoreResults)
            {
                foreach (var result in await iterator.ReadNextAsync())
                {
                    results.Add(result);
                }
            }

            return results;
        }
        catch (CosmosException ex) when (ex.StatusCode == HttpStatusCode.NotFound)
        {
            return Enumerable.Empty<T>();
        }
    }

    public async ValueTask<T> CreateAsync(T value)
    {
        var container = _containerProvider.GetContainer();
        var response = await container.CreateItemAsync(value, value.PartitionKey);

        return response.Resource;
    }

    public Task<T[]> CreateAsync(IEnumerable<T> values) =>
        Task.WhenAll(values.Select(v => CreateAsync(v).AsTask()));

    public async ValueTask<T> UpdateAsync(T value)
    {
        var container = _containerProvider.GetContainer();
        var response = await container.UpsertItemAsync<T>(value, value.PartitionKey);

        return response.Resource;
    }

    public async ValueTask<T> DeleteAsync(string id)
    {
        var container = _containerProvider.GetContainer();
        var response = await container.DeleteItemAsync<T>(id, new PartitionKey(id));

        return response.Resource;
    }
}

This is a little gem, it provides all of the common functionality that you should need to start reading from and writing to a Cosmos DB data store. It exposes functions that create, read, update or delete any subclass of a BaseDocument. This base document only requires an Id and a PartitionKey.

public class BaseDocument
{
    [JsonProperty("id")]
    public string Id { get; set; }

    internal PartitionKey PartitionKey => new PartitionKey(Id);
}

The real beauty of this abstraction is the support we get from ASP.NET Core. In our ServiceCollectionExtensions we define dependency injection additions for these services. We get to leverage a less-known generic dependency injection functionality.

public static class ServiceCollectionExtensions
{
    public static IServiceCollection AddGitHubRepository(
        this IServiceCollection services,
        IConfiguration configuration) =>
        services.AddSingleton<ICosmosContainerProvider, CosmosContainerProvider>()
                .AddSingleton(typeof(IRepository<>), typeof(Repository<>))
                .Configure<RepositoryOptions>(
                    configuration.GetSection(nameof(RepositoryOptions)));
}

In our Azure Function it is perfectly fine to register certain dependencies as singletons. This is the interesting like, .AddSingleton(typeof(IRepository<>), typeof(Repository<>)). We AddSingleton but noticed that we're doing a typeof(IRepository<>)? This means that for any generic type, provide the corresponding generic implementation! In a single line we opened up a repository pattern of infinite possibilities...I know, that sounds pretty epic, but seriously amazing. Now, back to our regularly scheduled programming. Where were we? Ah, yes...the HandleIssueAsync given the IssueEventPayload. If we're able to read from the repo previous activity from this

async ValueTask HandleIssueAsync(
    IssueEventPayload payload,
    FilterActivity activity = null)
{
    var issue = payload.Issue;
    var (title, body) = (issue.Title, issue.Body);
    var wasJustOpened = activity is null;
    if (!wasJustOpened)
    {
        (title, body) =
            await _client.GetIssueTitleAndBodyAsync(issue.Number);
    }

    var filterResult =
        TryApplyProfanityFilter(title, body);
    if (filterResult.IsFiltered)
    {
        var updateIssue = issue.ToUpdate();
        updateIssue.Title = filterResult.Title;
        updateIssue.Body = filterResult.Body;
        await _client.UpdateIssueAsync(issue.Number, updateIssue);

        var clientId = Guid.NewGuid().ToString();
        if (wasJustOpened)
        {
            await _repository.CreateAsync(new FilterActivity
            {
                Id = issue.NodeId,
                WasProfane = true,
                Type = ActivityType.Issue,
                MutationOrNodeId = clientId,
                WorkedOn = DateTime.Now,
                OriginalTitleText = title,
                OriginalBodyText = body,
                ModifiedTitleText = filterResult.Title,
                ModifiedBodyText = filterResult.Body
            });
        }
        else
        {
            activity.WasProfane = true;
            activity.WorkedOn = DateTime.Now;
            await _repository.UpdateAsync(activity);
        }

        await _client.AddReactionAsync(
            issue.NodeId,
            ReactionContent.Confused,
            clientId);
        await _client.AddLabelAsync(
            issue.NodeId,
            new[] { _options.ProfaneLabelId },
            clientId);
    }
}

From the payload instance we get the issue, we pick out the title and body with tuple deconstruction and assignment into two local variables. If activity is null then we're working with a new issue -- otherwise this issue was worked on before. Due to the stateless nature of our app, if we are working on an issue that we previously worked on, it is best to read the issue title and body from GitHub again to ensure that we're working with the latest version. As you can imagine there are potential race conditions, we need to be mindful of that possibility.

Profane Filtering

Next, we will call the ApplyProfanityFilter function.

internal FilterResult TryApplyProfanityFilter(
    string title,
    string body)
{
    if (string.IsNullOrWhiteSpace(title) &&
        string.IsNullOrWhiteSpace(body))
    {
        return FilterResult.NotFiltered;
    }

    var (resultingTitle, isTitleFiltered) = TryApplyFilter(title, '*');
    var (resultingBody, isBodyFiltered) = TryApplyFilter(body);

    return new FilterResult(
        resultingTitle,
        isTitleFiltered,
        resultingBody,
        isBodyFiltered);
}

If both the title and body are invalid values, we'll early exit and return a filter result of "not filtered". However, if they have values we will conditionally try to apply the filter.

(string text, bool isFiltered) TryApplyFilter(
    string text,
    char? placeHolder = null)
{
    var filterText = _profanityFilter?.IsProfane(text) ?? false;
    var resultingText =
        filterText
            ? _profanityFilter?.ApplyFilter(text, placeHolder)
            : text;

    return (resultingText, filterText);
}

If the text is profane, we apply the filter. Titles do not support markdown, as such we have to replace profane content with asterisk characters. But with the body text, GitHub supports markdown and emoji. When we are done working on the issue, we store the activity as a FilterActivity instance with all of the details we need. If there was profanity we react to the issue with the confused emoji 😕 and we'll label the issue.

GraphQL

There are several default labels, none of which suited my needs. I needed to signify that an issue or pull request contained profane content -- the label I created was "profane content 🤬". The way that the app knows about this label is via its identifier, and we can retrieve that using the GitHub GraphQL explorer and the following query.

query {
  repository(
    owner: "IEvangelist",
    name: "GitHub.ProfanityFilter") {
    labels(first: 20) {
      nodes {
        id,
        name
      }
    }
  }
}

I really love how GraphQL allows the consumer to retrieve only the shape of the items it's querying, this is really powerful. Executing this query returns my labels, their name and id. The label identifier is configured in our **Azure Function as an environment variable. If you're looking for the GitHub GraphQL SDK, look no further -- this project relies on the Oktokit.GraphQL package. It is a fluent API, which enables developers to author complex graph-based queries and mutations with ease. For details, see the source code.

Conclusion

This article started with detailing the underlying sentiment of an open source ecosystem, and the potential for frustration and angst. And while it's not all rainbows and ponies, it's awesome when the community comes together. I received a pull request that added the "lint licker" word replacer implementation -- yes, inspired by this commercial! For your viewing pleasure, here is what the filter looks like in action.

<video poster="/img/2019/11/poster.png" controls> <source src="/img/2019/11/in-action.mp4" type="video/mp4" /> Your browser does not support the video tag. </video>

As you can see, the profanity filter works 🤘.

Blazorators

David Pine — Thu, 08 Sep 2022 00:00:00 GMT

import { YouTube } from '@astro-community/astro-embed-youtube'; import { Tweet } from '@astro-community/astro-embed-twitter';

Blazorators

Blazorators is a C# source generator that creates fully functioning Blazor JavaScript interop code, targeting either the IJSInProcessRuntime or IJSRuntime types. All of this code relies on the output of one of my side projects named blazorators. While writing my O'Reilly "Learning Blazor: Build Single-Page Apps with WebAssembly and C#" book, I discovered an impactful way to use both TypeScript type declarations from common JavaScript APIs and C# source generators to generate the JavaScript interop code. This is covered in chapter seven, so I don't want to spoil it too much, but rather entice you to want to read the book. I've been using this approach in my Blazor apps for a while now and I'm excited to share it with you. Let's get started!

Check out my new Twitter account (@blazorbits) for Blazor tips and tricks! Below you'll see the Progress Telerik REPL (Read Evaluate Print Loop) for Blazor, select the Preview tab and watch the Blazor WebAssembly app perform a .NET restore and builds the app. Once the app loads, select a Natural voice from the voice selection control if it is available to you. If it's not available to you, that's not a big deal either. Select the Speak button and the app will speak the text you entered in the Text-to-speech control. You can also select the Stop button to stop the speech.

Interactive Demo:

Explore the app source code

when you create your own REPL session you're free to consume public NuGet packages, this app uses the Blazor.SpeechSynthesis.WebAssembly NuGet package 📦. Explore the Code tab thoroughly and look through the app's source code. You'll see that this app does the following:

_Main.razor: The app's main page, that showing a loading indicator and immediately navigates to the /speak route.
TextToSpeech.razor: The page that renders the Text-to-speech text input element and the browser-native speech synthesis control buttons.
TextToSpeech.razor.cs: The page's code-behind that contains the TextToSpeech component's logic.
Startup.cs: The app's startup class that configures services, calling a source-generated dependency injection specific extension method named `AddSpeechServices.

Notice the SpeechSynthesisVoice[], SpeechSynthesisUtterance, and ISpeechSynthesisService types. These are all from the Blazor.SpeechSynthesis.WebAssembly NuGet package 📦. The SpeechSynthesisVoice[] type is an array of SpeechSynthesisVoice objects that represent the available voices on the user's device. The SpeechSynthesisUtterance type is a class that represents the text to be spoken and the voice to be used. The ISpeechSynthesisService type is an interface that defines the GetVoicesAsync and an in-process Speak method that is synchronous.

The Speak function takes a SpeechSynthesisUtterance object and a callback function that is invoked when the speech is complete, delivering the total elapsed time in milliseconds.

There is also a way to listen for changes in the browser-native window.speechSynthesis voices that are available to the JavaScript context. Provide a callback to the ISpeechSynthesisService.OnVoicesChanged event and it will be invoked when the window.speechSynthesis voiceschanged event is fired. This is useful if you want to update the UI with the available voices. All of this functionality is source-generated by the Blazor.SourceGenerator project.

What's next?

This project was originally written as part of a Microsoft hackathon. It's been refined, but is still a brute-force effort and could stand to be optimized. As such I'm working to reimplement the parsing approach. It currently makes an HTTP request to a raw Github link with the lib.dom.d.ts file with all of the DOM type declarations in it. The file is itself, generated, and is over 18 thousand lines of code. It uses Regex expressions to parse on-demand single hierarchical type dependency graphs as readonly record struct values. These values were modeled as

Patent pending, not... ☹️

I was working with Stephen Toub (the patent lead for the .NET team), and we filed it for a patent. I was disappointed to learn that it wasn't filed as the lawyers reviewed it and determined that it wasn't patentable. I'm not sure why, but I'm glad to share it with you. I hope you find it useful. If you have any questions, please feel free to reach out to me:

The community is excited about this project, and I'm excited to see what you build with it. Here's what some of the community members have said on Twitter:

The plan

I'm rewriting the TypeScript abstract syntax tree parser to C#, essentially porting it one-to-one. When this is done, the parsing will be much more accurate and flexible. Likewise, our friends over on Twitter, and some of the community members on YouTube have been kind to me as well. Thank you for your kind words, they mean the world to me.

fieryscorpion commented:

This is a pretty amazing project. Hope this makes it into a serious project at Microsoft! Thank you!

Jiří Novotný commented:

I think this package has a lot of potential. It makes the bridge between JS and C# in Blazor much less painful. I love it! Well done, David.

Additional resources

Learning Blazor

David Pine — Fri, 16 Sep 2022 00:00:00 GMT

In June 2021, I set out on a journey to write a book in the middle of a global pandemic. I had no idea what I was doing (all things considered, I still don't know what I'm doing). But I do know that I truly enjoy helping others. I hope you enjoy the book as much as I enjoyed writing it.

Amazon Preview

Foreword by Steve Sanderson

Web development has been a dominating feature of the software industry for over 20 years and is likely to remain so for many years to come. Industry giants continue to invest heavily in expanding web technology's power and flexibility, enabling an increasing range of advanced browser-based software. While native mobile apps and augmented reality / virtual reality apps find their place for consumer software, the web is overwhelmingly the default UI for business apps. If you could bet on only one application platform, you should bet on the web.

During those same 20 years, .NET (first released in 2002) has held its place as Microsoft's premiere developer toolset. Like the web, .NET continues to gain strength. It was reinvented as cloud-first, cross-platform, and fully open source in 2016 and today is used by about 30% of all professional software developers[^1] C# has always been considered one of the most productive languages, at the forefront of rich developer tooling with precise code completions and a top debugging experience, and now ASP.NET Core is one of the fastest server-side web technologies[^2].

The goal of Blazor is to unlock the full power of .NET for browser-based UI applications. It's the .NET team's best effort to create the most productive and natural way to create single-page application–type apps. This includes Blazor's component-based programming model, which takes the best aspects of many modern UI frameworks and unifies them into something natural for .NET with its strong typing. Beyond that, it means connecting with the rest of the .NET ecosystem, with its industry-leading IDEs and first-class features for debugging, testing, and hot reload. Blazor's biggest innovation might be its flexible execution models, running server-side with UI streaming to browsers over a websocket, directly inside the browser on WebAssembly, or as native code in mobile and desktop apps.

Learning Blazor provides both a deep and broad look at Blazor app development. Unlike many other books, it doesn't just focus on the easy parts of C# programming and leave real-world complexity as an exercise for the reader. Instead, David sets out the whole range of web development concerns—including authentication, security, performance, localization, and deployment (CI/CD)—right in front of you, starting from the beginning. With some focus, you'll be able to absorb David's broad expertise and be equipped to take on realistic work of your own.

David is well placed to explain not just how things work today but also how they've evolved to their present state and even how things may change in the future. He's been a well-known figure in the Blazor community for years, is well connected with engineering leaders within Microsoft, and has an even longer history as a 2-time Microsoft Most Valuable Professional (MVP) and a 6-time Google Developer Expert (GDE) in web technologies. Throughout this book, you'll find many historical details and anecdotes that shed light on the challenges, decisions, and people who shaped web development and .NET into the technology you'll be using. David's enthusiasm will propel you through a complex landscape.

My biggest motivation when creating the first release of Blazor with Dan Roth and Ryan Nowak was to help free web UI from its monoculture. I appreciate JavaScript and have built a lot of my career on it, but there are so many other programming languages, paradigms, and communities that could bring their own richness into the browser. I know you'll find your own ways to innovate with the software you create and for the users who benefit. I wish you all the best with your Blazor projects and am confident you'll find inspiration in these pages.

Steve Sanderson

Software Engineer/Architect at Microsoft, original Blazor creator Bristol, UK August 2022

Developer community praise

I love the energy from the people who have read the book! I'm thrilled to have made such a positive impact on the community. Here are some of the comments I've received from some familiar developer community folks. 😍

The Blazor open source web framework is a whole new way to develop powerful applications for the web. Learning Blazor uses tons of examples and prescriptive code based on David Pine's deep experience as a content developer on the .NET team to get you writing Blazor web apps with C# today!

Learning Blazor is the perfect resource for developers who are looking to build modern web applications using bleeding-edge web technologies. David leverages his skills as a senior content developer to help you get started with Blazor!

David Pine's Learning Blazor takes developers on the perfect journey to learning how to build and deploy their Blazor applications. David leverages his extensive content development and presentation skills to inspire you to build Blazor web apps today.

Like its author, this book will inspire folks to try new things with Blazor and to be excited about the possibilities of building apps it brings. David's delightful style of writing code as eloquent as his prose, coupled with a genuine love for .NET and using it creatively will make any developer fall in love with web development all over again.

As an experienced Blazor developer, I learned more about localization and testing from David Pine in 20 minutes of reading than I did in days of searching for similar insight online. Not only is Learning Blazor an educational piece, but it's also a great reference that I will return to when building future Blazor applications.

Learning Blazor is a well-paced guide that is perfectly suited for anyone with .NET experience who would like to learn Blazor to build web apps, and for anyone looking to refine their Blazor skills.

Learning Blazor is one of the most informative books I have ever read, and it makes you want to start developing with WebAssembly and C# right away. Learning Blazor uses a great storyline and practical real-world examples to explain a modern technology and how it can be combined with JavaScript and HTML. A must-read for every web developer.

There are so many gems in here that you are guaranteed to learn something regardless of your experience level. It has inspired me to add techniques and features to my projects that I've never considered before.

Click the cover below 👇🏽. It's a link to the book on Amazon. 😊

Media type	Site
📖 Paperback (Print)	Check it out on Amazon to pre-order today.
💻 eBook (Kindle)	Buy it now on Amazon Kindle devices.

Hello from the GitHub Actions: Core .NET SDK

David Pine — Wed, 30 Nov 2022 00:00:00 GMT

:::tip{title="📢 ATTENTION"}

This post is part of the C# advent calendar 2022, for other articles in this collection see C# Advent Calendar 2022. This is the third time I've written for the calendar, past entries include 2017: C# Special Edition and 2018: C# All The Things. 🙏🏽

:::

GitHub Actions: Core .NET SDK

SDKs are great, but why do we need one for GitHub Actions? The short answer is, you don't! You can write a GitHub Action in .NET without using one. I've written about this already, if you're interested see the Tutorial: Create a GitHub Action with .NET. There are a few ways in which you can write a GitHub Action. You can do so using JavaScript, Docker, or as a composite action. One of the easiest ways was to use JavaScript, as the GitHub team maintains an open-source SDK (or actions/toolkit) written in TypeScript. Their toolkit is comprised of a set of packages to make creating actions easier.

I wanted to make it easier for .NET developers to write GitHub Actions, so I created an unofficial .NET equivalent of the official GitHub actions/toolkit @actions/core and @actions/github projects.

Why should I care about GitHub Actions?

If you're unfamiliar with GitHub Actions, the TL;DR; is that they allow you to automate tasks such as building, testing, packaging, and deploying your code. If you want a deeper look beyond that definition, see GitHub Docs: Actions. Just know that GitHub Actions are a powerful tool, and the team has done an amazing job of making them easy to use.

You should care about GitHub Actions because they are a great way to automate by writing workflows. A GitHub Action is then consumed by a repositories workflow, which is a set of instructions that are executed when a specific event occurs. For example, you can create a workflow that runs when a pull request is created, or when a new release is published. You can also create a workflow that runs on a schedule, such as every day at 3:00 AM. Workflows are defined in a YAML file, and you can create as many workflows as you want. You can also create a workflow that is triggered by another workflow. For example, you can create a workflow that runs when a pull request is created, and then create another workflow that runs when that workflow completes. The possibilities are endless!

Inspiration from `actions/toolkit`

The actions/toolkit specifies the standard I/O, and it defines specific environment variables that are used within a GitHub Action workflow. If you're familiar with any of my other open-source projects, you'll likely be aware of my appreciation for what 🤓 TypeScript has done for the web. Moreover, you know that I'm all about that C# 💜.

I've been working on various other projects that leverage TypeScript in the world of .NET. There are certainly parallel efforts in this regard, for more information, see Blazorators. As this relates to the actions/toolkit specifically, let's start by having a look at the possible inputs and outputs, and the formats in which they can be set.

Commanding the workflow

GitHub Action workflows rely heavily on environment variables. The following are the environment variables that are used to interact with the workflow:

GITHUB_ACTION: The name of the action.
GITHUB_OUTPUT: A file path to a file containing any custom data that the workflow cares to write.
GITHUB_PATH: A file path to a file containing environment variables to add to the PATH environment variable for all subsequent steps in the current job.
GITHUB_STATE: Custom user data that is persisted across workflow jobs and steps.
GITHUB_TOKEN: The token used to authenticate with GitHub. This value is provided by GitHub, and contextually available to make whatever permissions the workflow has available to it. This value is always written to the log in a masked format.

These are but a few of the environment variables that are available to a GitHub Action workflow. For a complete list, see GitHub Docs: Environment variables.

Outputs

The workflow can write outputs to a file, and even custom state. In the case of output, files are written to the file path from the GITHUB_OUTPUT environment variable. The output in this scenario would be a JSON file that contains anything we want to serialize to and from. We're not limited by that, it is trivial in C# with the System.IO for reading and writing JSON, and either System.Text.Json or Newtonsoft.Json for JSON serialization of C# objects. In addition to files, any arbitrary string can be written to the log. The log is written to the standard output stream and is available to the workflow. Certain logged messages receive special treatment and are parsed by the workflow as commands. The following are the special messages that are parsed by the workflow:

Command name	Description
`add-mask`	Registers a secret which will get masked from logs.
`add-path`	Prepends the input path to the `PATH` (for this action and future actions).
`echo`	Enables or disables the echoing of commands into stdout for the rest of the step.
`debug`	Writes debug message to user log.
`error`	Adds an error issue.
`warning`	Adds a warning issue.
`notice`	Adds a notice issue.
`group`	Begin an output group.
`endgroup`	End the output group.

If you're seeing these commands and wondering where the save-state and set-output commands are, they have been deprecated. For more information, see GitHub Actions: Deprecating save-state and set-output commands. Now that we're familiarizing ourselves with the commands, let's have a look at the @actions/core package to see how it implements commanding the workflow.

TypeScript `Command` object

This code is from the @actions/core project, and it's TypeScript code that represents a command. The command.ts file exposes a few functions to issue commands. Read through the contents of the actions/toolkit/blob/main/packages/core/src/command.ts file:

import * as os from 'os'
import {toCommandValue} from './utils'

export interface CommandProperties {
  [key: string]: any
}

/**
 * Commands
 *
 * Command Format:
 *   ::name key=value,key=value::message
 *
 * Examples:
 *   ::warning::This is the message
 *   ::set-env name=MY_VAR::some value
 */
export function issueCommand(
  command: string,
  properties: CommandProperties,
  message: any
): void {
  const cmd = new Command(command, properties, message)
  process.stdout.write(cmd.toString() + os.EOL)
}

export function issue(name: string, message = ''): void {
  issueCommand(name, {}, message)
}

const CMD_STRING = '::'

class Command {
  private readonly command: string
  private readonly message: string
  private readonly properties: CommandProperties

  constructor(command: string, properties: CommandProperties, message: string) {
    if (!command) {
      command = 'missing.command'
    }

    this.command = command
    this.properties = properties
    this.message = message
  }

  toString(): string {
    let cmdStr = CMD_STRING + this.command

    if (this.properties && Object.keys(this.properties).length > 0) {
      cmdStr += ' '
      let first = true
      for (const key in this.properties) {
        if (this.properties.hasOwnProperty(key)) {
          const val = this.properties[key]
          if (val) {
            if (first) {
              first = false
            } else {
              cmdStr += ','
            }

            cmdStr += `${key}=${escapeProperty(val)}`
          }
        }
      }
    }

    cmdStr += `${CMD_STRING}${escapeData(this.message)}`
    return cmdStr
  }
}

function escapeData(s: any): string {
  return toCommandValue(s)
    .replace(/%/g, '%25')
    .replace(/\r/g, '%0D')
    .replace(/\n/g, '%0A')
}

function escapeProperty(s: any): string {
  return toCommandValue(s)
    .replace(/%/g, '%25')
    .replace(/\r/g, '%0D')
    .replace(/\n/g, '%0A')
    .replace(/:/g, '%3A')
    .replace(/,/g, '%2C')
}

A few things to observe about the preceding code:

The issueCommand function is one of the two functions that are exported. It's used to issue a command to the standard output stream.
The issue function is a convenience function that issues a command with no properties parameter.
The Command class is used to represent a command. It has a toString method that returns the string representation of the command.
The escapeData and escapeProperty functions are used to escape the message and properties of the command, respectively.

This is standard TypeScript code, but how might we want to implement this in C#? Let's take a look at the Command class in Microsoft.GitHub.Actions project:

C# `Command` object

While inspired, I decided this could be implemented in C#, and with a few minor tweaks — it was. Let's start by discussing what this would look like in C#. The following is the C# implementation of the Command object, this corresponds to the Microsoft.GitHub.Actions/Workflows/Command.cs:

namespace Microsoft.GitHub.Actions.Workflows;

/// <summary>
/// Command format:
/// <c>::name key=value,key=value::message</c>
/// </summary>
/// <example>
/// <list type="bullet">
/// <item><c>::warning::This is the message</c></item>
/// <item><c>::set-env name=MY_VAR::some value</c></item>
/// </list>
/// </example>
internal readonly record struct Command<T>(
    string? CommandName = "missing.command",
    T? Message = default,
    IReadOnlyDictionary<string, string>? CommandProperties = default)
{
    const string CMD_STRING = "::";

    internal bool Conventional =>
        CommandNames.IsConventional(CommandName);

    /// <summary>
    /// The string representation of the workflow command, i.e.; 
    /// <code>::name key=value,key=value::message</code>.
    /// </summary>
    public override string ToString()
    {
        StringBuilder builder = new($"{CMD_STRING}{CommandName}");

        if (CommandProperties?.Any() ?? false)
        {
            builder.Append(' ');
            foreach (var (isNotFirst, key, value)
                in CommandProperties.Select(
                    (kvp, index) => (index is > 0, kvp.Key, kvp.Value)))
            {
                if (isNotFirst)
                {
                    builder.Append(',');
                }
                builder.Append($"{key}={EscapeProperty(value)}");
            }
        }

        builder.Append($"{CMD_STRING}{EscapeData(Message)}");

        return builder.ToString();
    }

    static string EscapeProperty<TSource>(TSource? value) =>
        value.ToCommandValue()
            .Replace("%", "%25")
            .Replace("\r", "%0D")
            .Replace("\n", "%0A")
            .Replace(":", "%3A")
            .Replace(",", "%2C");

    static string EscapeData<TSource>(TSource? value) =>
        value.ToCommandValue()
            .Replace("%", "%25")
            .Replace("\r", "%0D")
            .Replace("\n", "%0A");
}

I wanted the Command object to be a readonly record struct for immutability, value-based comparison semantics, deconstruction, and performance (it's lightweight). The Command object has a CommandName property, a Message property, and a CommandProperties property. The CommandName property is a string that represents the name of the command, and it defaults to "missing.command". The Message property is a generic type that represents the message of the command. The CommandProperties property is a IReadOnlyDictionary<string, string> that represents the properties of the command.

Command format

Workflow commands are written to the standard output stream. For a command with a name of name, properties of { "key1" = "value", "key2" = "value" }, and a message of message, it's formatted as follows when issued to the standard output stream:

::name key1=value,key2=value::message

Another example is when writing a debug message to the log:

::debug::This is a debug message

One final example is the set-env command:

::set-env name=ENVIRONMENT_VARIABLE::value

All of these commands are delimited with the :: characters. The command name is the first token after the first :: delimiter. The command properties are the second token after the first :: delimiter, following the first space character. The command properties are key/value pairs expressed with the = character and delimited by the , character. The command message is optional. Any given Command instance results in the appropriate command being written to the standard output stream.

Installing the NuGet package 📦

Welcome to the [Microsoft.GitHub.Actions] .NET SDK. This SDK is used to create GitHub Actions in .NET. The SDK is a thin wrapper around the .NET implementation of the GitHub Actions a select few packages from the @actions/toolkit.

:::caution{title="⚠️ DISCLAIMER"} This package is not an official Microsoft or GitHub product. It is a community-driven project. However, I do choose to use the Microsoft.GitHub[.*] namespace for the package. I'm not trying to mislead anyone, but I do want to make it clear that this is not an official product. :::

You'll need to install the GitHub Actions: Core .NET SDK NuGet package to use the .NET APIs. The package is available on NuGet.org. The following is the command to install the package:

Adding the package reference

Either add the package reference to your project file:

<PackageReference Include="GitHub.Actions.Core" Version="0.0.1" />

Or use the dotnet add package .NET CLI command:

dotnet add package GitHub.Actions.Core

Registering the services for consumption

The SDK is dependency injection ready, meaning that you can call the AddGitHubActions extension method on the IServiceCollection interface to register the services for consumption. The following is an example of how to register the services, and an example of how to consume the ICoreService:

using Microsoft.Extensions.DependencyInjection;
using Microsoft.GitHub;
using Microsoft.GitHub.Actions.Extensions;
using Microsoft.GitHub.Actions.Services;

using var provider = new ServiceCollection()
    .AddGitHubActions()
    .BuildServiceProvider();

var core = provider.GetRequiredService<ICoreService>();

try
{
    // "who-to-greet" input defined in action metadata file
    var nameToGreet = core.GetInput("who-to-greet");
    core.Info($"Hello {nameToGreet}!");
    await core.SetOutputAsync("time", DateTime.UtcNow.ToString("o"));

    // Get the JSON webhook payload for the event that triggered the workflow
    var payload = JsonSerializer.Serialize(Context.Current.Payload);
    core.Info($"The event payload: {payload}");
}
catch (Exception ex)
{
    core.SetFailed(ex.ToString());
}

Compare this to the following JavaScript code in the index.js file from the Creating a JavaScript action: Writing the action code article, which would achieve the same thing with the TypeScript toolkit:

const core = require('@actions/core');
const github = require('@actions/github');

try {
    // `who-to-greet` input defined in action metadata file
    const nameToGreet = core.getInput('who-to-greet');
    console.log(`Hello ${nameToGreet}!`);

    const time = (new Date()).toTimeString();
    core.setOutput("time", time);
    // Get the JSON webhook payload for the event that triggered the workflow
    const payload = JSON.stringify(github.context.payload, undefined, 2)
    console.log(`The event payload: ${payload}`);
} catch (error) {
    core.setFailed(error.message);
}

Issuing commands

Instead of being able to export any custom data structures, and corresponding functions, the Command object is internal readonly record struct that can be used to issue commands. The following is the C# implementation of the issueCommand and issue functionality:

namespace Microsoft.GitHub.Actions.Commands;

internal interface ICommandIssuer
{
    void IssueCommand<T>(
        string commandName,
        IReadOnlyDictionary<string, string>? properties = default,
        T? message = default);

    void Issue<T>(string commandName, T? message = default);
}

I'm a big fan of triple-slash comments, and as a consumer of many various APIs written by different authors, I've enjoyed learning APIs with good and meaningful triple-slash comments. I say all of this to say, that I've omitted them from the code pasted here. If you want to see them, check them out on GitHub. The ICommandIssuer interface has two methods, IssueCommand, and Issue. Consider the implementation that's defined in the following DefaultCommandIssuer class:

namespace Microsoft.GitHub.Actions.Commands;

internal sealed class DefaultCommandIssuer : ICommandIssuer
{
    private readonly IConsole _console;

    public DefaultCommandIssuer(IConsole console) => _console = console;

    public void Issue<T>(string commandName, T? message = default) =>
        IssueCommand(commandName, null, message);

    public void IssueCommand<T>(
        string commandName,
        IReadOnlyDictionary<string, string>? properties = default,
        T? message = default)
    {
        var cmd = new Command<T>(
            commandName, message, properties);

        if (cmd is not { Conventional: true })
        {
            _console.WriteLine("Issuing unconventional command.");
        }

        var commandMessage = cmd.ToString();
        _console.WriteLine(commandMessage);
    }
}

Some commands require interactions with the file system. This functionality is defined as file commands.

File commands

In addition to standard commands, file commands are also supported. File commands write to a file instead of the standard output stream. A file command is free to write any value to the file. The following are file-based commands:

add-path: Writes the value to the file path from the GITHUB_PATH environment variable.
save-state: Writes the value to the file path from the GITHUB_STATE environment variable.
set-env: Writes the value to the file path from the GITHUB_ENV environment variable.
set-output: Writes the value to the file path from the GITHUB_OUTPUT environment variable.

The corresponding .NET APIs that are used to issue file commands are:

ICoreService.AddPathAsync: Issues an add-path command.
ICoreService.ExportVariableAsync: Issues the set-env command.
ICoreService.SaveStateAsync: Issues the save-state command.
ICoreService.SetOutputAsync: Issues the set-output command.

The `IFileCommandIssuer` interface

namespace Microsoft.GitHub.Actions.Commands;

internal interface IFileCommandIssuer
{
    ValueTask IssueFileCommandAsync<TValue>(string commandSuffix, TValue message);

    string PrepareKeyValueMessage<TValue>(string key, TValue value);
}

The IFileCommandIssuer interface is used to issue file-based commands. The DefaultFileCommandIssuer class implements this interface:

namespace Microsoft.GitHub.Actions.Commands;

internal sealed class DefaultFileCommandIssuer : IFileCommandIssuer
{
    private readonly Func<string, string, ValueTask> _writeLineTask;

    public DefaultFileCommandIssuer(
        Func<string, string, ValueTask> writeLineTask) =>
        _writeLineTask = writeLineTask.ThrowIfNull();

    ValueTask IFileCommandIssuer.IssueFileCommandAsync<TValue>(
        string commandSuffix, TValue message)
    {
        var filePath = GetEnvironmentVariable($"{GITHUB_}{commandSuffix}");
        if (string.IsNullOrWhiteSpace(filePath))
        {
            throw new Exception(
                "Unable to find environment variable for file " +
                $"command suffix '{commandSuffix} ({GITHUB_}{commandSuffix})'.");
        }

        if (File.Exists(filePath) is false)
        {
            throw new Exception(
                $"Missing file at path: '{filePath}' " +
                $"for file command '{commandSuffix}'.");
        }
        
        return _writeLineTask.Invoke(filePath, message.ToCommandValue());
    }

    string IFileCommandIssuer.PrepareKeyValueMessage<TValue>(
        string key, TValue value)
    {
        var delimiter = $"ghadelimiter_{Guid.NewGuid()}";
        var convertedValue = value.ToCommandValue();

        // These should realistically never happen, but just in case someone finds a
        // way to exploit uuid generation let's not allow keys or values that contain
        // the delimiter.
        if (key.Contains(
            delimiter, StringComparison.OrdinalIgnoreCase))
        {
            throw new Exception(
                $"Unexpected input: name should not contain the delimiter {delimiter}");
        }

        if (convertedValue.Contains(delimiter, StringComparison.OrdinalIgnoreCase))
        {
            throw new Exception(
                $"Unexpected input: value should not contain the delimiter {delimiter}");
        }

        return $"{key}<<{delimiter}{NewLine}{convertedValue}{NewLine}{delimiter}";
    }
}

This code is derived from the TypeScript implementation of the core/src/file-command.ts file:

import * as fs from 'fs'
import * as os from 'os'
import {v4 as uuidv4} from 'uuid'
import {toCommandValue} from './utils'

export function issueFileCommand(
    command: string, message: any): void {
    const filePath = process.env[`GITHUB_${command}`]
    if (!filePath) {
        throw new Error(
            `Unable to find environment variable ` +
            `for file command ${command}`
        )
    }
    if (!fs.existsSync(filePath)) {
        throw new Error(`Missing file at path: ${filePath}`)
    }
    
    fs.appendFileSync(
        filePath, `${toCommandValue(message)}${os.EOL}`, {
      encoding: 'utf8'
    })
}

export function prepareKeyValueMessage(
    key: string, value: any): string {
    const delimiter = `ghadelimiter_${uuidv4()}`
    const convertedValue = toCommandValue(value)

    // These should realistically never happen, but just in case someone finds a
    // way to exploit uuid generation let's not allow keys or values that contain
    // the delimiter.
    if (key.includes(delimiter)) {
        throw new Error(
            `Unexpected input: name should not ` +
            `contain the delimiter "${delimiter}"`
        )
    }

    if (convertedValue.includes(delimiter)) {
        throw new Error(
            `Unexpected input: value should not ` +
            `contain the delimiter "${delimiter}"`
        )
    }

    return `${key}<<${delimiter}${os.EOL}${convertedValue}${os.EOL}${delimiter}`
}

The C# implementation matches the TypeScript implementation, except for the use of ValueTask instead of void for the IssueFileCommandAsync method. All of the command-issuing functionality is internal to the ICoreService implementation.

The SDK continues to evolve ⚒️

More than 90% of the functionality of the packages/src/core.ts and packages/github/src/github.ts files have been implemented in the SDK.

I'm not going to paste more than 100 lines for multiple files, this blog post isn't the place for that. If you're interested in seeing the rest of the SDK, you can find it on GitHub. The SDK is still evolving, and the following features are still in development:

I want to create a GitHub repository template that can be used to create a new containerized .NET GitHub Action.
I want to continue working on adding missing functionality to the SDK.
I want to implement the other packages that exist in the actions/toolkit.

The future is bright ☀️

I'm always open to collaborating with developer community members, 🙌🏽 who are interested in helping this code live on to help others. I encourage you to explore the code and be sure to see the sample use cases.

:::tip{title="🤓 COLLABORATE"}

If you're interested in helping, please reach out to me on Twitter, or open an issue on the GitHub Actions Core .NET SDK.

:::

A conversation with ChatGPT

David Pine — Thu, 08 Dec 2022 00:00:00 GMT

:::note{title="❗ IMPORTANT"}

This post was generated using ChatGPT. I prompted the AI with a few leading questions and formatted the responses as the body text of this post. For more information, see the ChatGPT.

:::

A conversation with ChatGPT about .NET Dependency Injection

:::duck{align="left"} What is dependency injection and why is it important? :::

:::chatgpt{align="right"} Dependency injection is a software design pattern that allows a programmer to remove hard-coded dependencies and make them configurable. This is important because it makes code more modular and easier to maintain, test, and reuse. Additionally, it makes it possible for different parts of a program to be supplied with the specific dependencies they need, rather than having to rely on a global, static dependency. This can make it easier to manage complex systems and can help to improve the flexibility and scalability of a program. :::

:::duck{align="left"} What's inversion of control, and how does it relate to the separation of concerns principle? :::

:::chatgpt{align="right"} Inversion of control (IoC) is a design principle that specifies that a program should not dictate the behavior of the components it uses. Instead, the program should specify its requirements, and the components should be designed to fulfill those requirements. This means that the program is not in control of how its components are created, how they are initialized, or how they are used.

The separation of concerns principle states that a software program should be divided into distinct sections, each of which addresses a separate concern. By following this principle, a program can be designed in a way that makes it easier to understand, maintain, and extend.

IoC is related to the separation of concerns principle because it helps to achieve a clean separation of concerns within a program. By using IoC, you can design your program in such a way that the various components are not tightly coupled to each other. This makes it easier to change or modify the behavior of a single component without affecting the rest of the program. In this way, IoC helps to promote the separation of concerns, which in turn makes your program more modular and easier to maintain. :::

:::duck{align="left"} When was the concept of dependency injection popularized? :::

:::chatgpt{align="right"} The concept of dependency injection has been around for a long time, and it has been recognized as an important technique in software development for many years. However, the term "dependency injection" itself was coined by Martin Fowler in 2004, in an article he wrote for the website of O'Reilly Media. In this article, he explained the concept and discussed its importance in software development, particularly in the context of object-oriented programming. Since then, dependency injection has become a widely used and well-known design pattern in the field of software engineering. :::

:::duck{align="left"} How do you install the dependency injection NuGet package in an existing .NET app? :::

:::chatgpt{align="right"} To install the dependency injection NuGet package in an existing .NET app, you can use the following steps:

Open your app in Visual Studio.
In the Solution Explorer, right-click on the solution and select "Manage NuGet Packages".
In the NuGet Package Manager, search for "Microsoft.Extensions.DependencyInjection".
Select the package in the search results and click "Install".
Follow the on-screen instructions to complete the installation.

Alternatively, you can use the following command at the command line to install the package:

dotnet add package Microsoft.Extensions.DependencyInjection

Once the package has been installed, you can use the types and methods it provides to implement dependency injection in your app. For more information on how to do this, you can refer to the official Microsoft documentation. :::

:::duck{align="left"} Describe .NET dependency injection with the Microsoft.Extensions.DependencyInjection NuGet package. :::

:::chatgpt{align="right"} The Microsoft.Extensions.DependencyInjection NuGet package is a popular dependency injection framework for the .NET ecosystem. It provides a simple and flexible way to configure and use dependency injection in .NET applications.

To use the Microsoft.Extensions.DependencyInjection package, you first need to add it to your project using the NuGet Package Manager. Once it's added, you can use the IServiceCollection interface to configure your dependencies. For example, suppose you have an IFoo interface and a Foo class that implements it. To register the Foo class as the implementation of the IFoo interface, you can use the following code:

services.AddTransient<IFoo, Foo>();

This tells the dependency injection framework to create a new instance of the Foo class every time it is needed. Alternatively, you can use the AddSingleton method to register a single shared instance of the Foo class, or the AddScoped method to register an instance that is shared within a single request or unit of work.

Once your dependencies are registered, you can use the IServiceProvider interface to resolve them. This is typically done by creating an instance of the ServiceProvider class, which is passed the IServiceCollection instance that you configured earlier by calling BuildServiceProvider. Then, you can use the GetService method to resolve a specific dependency by its type. For example:

var serviceProvider = services.BuildServiceProvider();
var foo = serviceProvider.GetService<IFoo>();

This will return an instance of the Foo class that you registered earlier. You can then use this instance as you would normally, without having to worry about how it was created or managed.

Using the Microsoft.Extensions.DependencyInjection package can make it easier to manage dependencies in your .NET applications. It provides a simple and flexible way to configure and use dependency injection, allowing you to improve the maintainability and testability of your code. :::

:::duck{align="left"} What is scope validation and why is it important when using the Microsoft.Extensions.DependencyInjection NuGet package? :::

:::chatgpt{align="right"} Scope validation is a feature of the Microsoft.Extensions.DependencyInjectionNuGet package that helps ensure that the objects created by the dependency injection container are used correctly. It does this by checking that an object is only used within the scope in which it was created. This is important because it helps prevent issues such as using an object after it has been disposed, or using an object from the wrong thread. By using scope validation, you can catch such errors early on and avoid potential runtime issues. :::

:::duck{align="left"} Why is scope validation important in dependency injection? :::

:::chatgpt{align="right"} Scope validation is important in dependency injection because it allows you to ensure that the dependencies in your app are being used correctly. In particular, it helps you to verify that the dependencies have the correct scope, which is the lifetime of the dependency in your app.

When you register a dependency in your app, you can specify its scope by using one of the Add methods provided by the IServiceCollection interface. For example, you can use the AddScopedmethod to specify that the dependency should be scoped to a specific instance, such as a request in an ASP.NET app.

If you do not specify the scope of a dependency, it will be registered with the default scope, which is Transient. This means that a new instance of the dependency will be created each time it is requested.

If you register a dependency with the wrong scope, it can cause problems in your app. For example, if you register a dependency with a Transient scope but it should be Scoped, it will create a new instance of the dependency each time it is requested, which can cause unexpected behavior and may lead to performance issues.

Scope validation allows you to verify that all the registered dependencies have the correct scope, so you can catch and fix any issues before they cause problems in your app. This can help to improve the reliability and performance of your app. :::

Conclusion

There were very few corrections that I had to make when pasting in the responses from ChatGPT. I think this is a testament to the quality of the responses that ChatGPT was able to generate. I think this is a testament to the quality of the training data that ChatGPT was trained on. This technology has inspired so many new ideas and ways of reimagining what's possible with AI. I'm not only excited to see what the future holds, but I'm also optimistically cautious.

For additional reading, see the official Microsoft docs on dependency injection, and be sure to check out ChatGPT from OpenAI.

Exploring .NET streaming API scenarios

David Pine — Mon, 19 Jun 2023 00:00:00 GMT

import { Tweet } from '@astro-community/astro-embed-twitter';

:::note{title="❗ IMPORTANT"}

The featured image was generated using bing.com/create powered by DALL·E.

:::

Exploring .NET streaming API scenarios

If you're a .NET developer, chances are you're already familiar with the IAsyncEnumerable<T> interface. This interface was introduced in .NET Core 3.0 and is used to asynchronously iterate over a collection of data. This is a great way to stream data from a server to a client. In this post, you'll learn how to:

Expose an ASP.NET Core Minimal API endpoint that returns IAsyncEnumerable<T>.
Consume the same IAsyncEnumerable<T> from an ASP.NET Core Blazor WebAssembly app.

In this post, you'll explore a scenario inspired by ChatGPT's user experience that streams UI updates to the client from the server in real-time.

TL;DR;

If you'd rather just see the code, you can see it on the GitHub repository https://github.com/IEvangelist/blazor-azure-openai.

Server

The server is an ASP.NET Core Minimal API app, that defines an endpoint that returns an IAsyncEnumerable<T>. This is important because when it comes to streaming data, you want to avoid buffering the entire collection in memory. Instead, you want to stream the data as it becomes available. This is exactly how IAsyncEnumerable<T> operates. The app will make use of a few NuGet packages:

Here's what the project file looks like:

<Project Sdk="Microsoft.NET.Sdk.Web">

    <PropertyGroup>
        <TargetFramework>net7.0</TargetFramework>
        <Nullable>enable</Nullable>
        <ImplicitUsings>enable</ImplicitUsings>
    </PropertyGroup>
    
    <ItemGroup>
        <PackageReference Version="1.0.0-beta.5"
            Include="Azure.AI.OpenAI" />
        <PackageReference Version="7.0.5"
            Include="Microsoft.AspNetCore.Components.WebAssembly.Server" />
        <PackageReference Version="1.6.3"
            Include="Microsoft.Extensions.Azure" />
        <PackageReference Version="7.0.0"
            Include="Microsoft.Extensions.Caching.Memory" />
        <PackageReference Version="6.5.0"
            Include="Swashbuckle.AspNetCore" />
    </ItemGroup>

    <ItemGroup>
        <InternalsVisibleTo Include="Azure.OpenAI.Client.EndToEndTests" />
    </ItemGroup>

    <ItemGroup>
      <ProjectReference Include="..\Client\Azure.OpenAI.Client.csproj" />
      <ProjectReference Include="..\Shared\Azure.OpenAI.Shared.csproj" />
    </ItemGroup>

</Project>

The Program.cs file makes use of C#'s top-level programs, which is a great way to reduce boilerplate code. The WebApplication.CreateBuilder(args) creates an instance of WebApplicationBuilder and builds an app (WebApplication) before configuring it and running the app as shown in the following Program class:

// Copyright (c) David Pine. All rights reserved.
// Licensed under the MIT License.

var builder = WebApplication.CreateBuilder(args);

using var app = BuildApp(builder);

ConfigureApp(app);

await app.RunAsync();

:::tip{title="💡 TIP"}

You can encapsulate the building and configuring of your app with the use of partial classes. Consider two additional files, Program.Build.cs and Program.Configure.cs.

:::

The Program.Build.cs file contains the BuildApp method, which is responsible for building the app. The BuildApp functionality is defined as the following code:

// Copyright (c) David Pine. All rights reserved.
// Licensed under the MIT License.

public partial class Program
{
    internal static WebApplication BuildApp(WebApplicationBuilder builder)
    {
        builder.Services.AddAzureOpenAI(builder.Configuration);

        builder.Services.AddEndpointsApiExplorer();
        builder.Services.AddSwaggerGen();
        builder.Services.AddHttpClient();
        builder.Services.AddHttpLogging(
            options => options.LoggingFields = HttpLoggingFields.All);

        builder.Services.AddMemoryCache();
        builder.Services.AddControllersWithViews();
        builder.Services.AddRazorPages();

        return builder.Build();
    }
}

The preceding code, given an instance of WebApplicationBuilder, will:

Adds support for Azure AI's OpenAI service with use of the official Azure .NET SDK
Adds support for OpenAPI (not to be confused with OpenAI) Swagger
Adds support for HTTP support with logging
Adds support for in-memory caching
Adds support for controllers with views
Adds support for Razor Pages
Returns the built app

The Program.Configure.cs file contains the ConfigureApp method, which is responsible for configuring the app. The ConfigureApp functionality is defined as the following code:

// Copyright (c) David Pine. All rights reserved.
// Licensed under the MIT License.

public partial class Program
{
    internal static void ConfigureApp(WebApplication app)
    {
        if (app.Environment.IsDevelopment())
        {
            app.UseSwagger();
            app.UseSwaggerUI();
            app.UseWebAssemblyDebugging();
        }
        else
        {
            app.UseExceptionHandler("/Error");
            app.UseHsts();
        }

        app.UseHttpsRedirection();
        app.UseBlazorFrameworkFiles();
        app.UseStaticFiles();
        app.UseRouting();
        app.MapRazorPages();
        app.MapControllers();
        app.MapFallbackToFile("index.html");

        app.MapAzureOpenAiApi();
    }
}

This code configures the given app by:

Conditionally add various middleware based on the environment
- Swagger UI and WebAssembly debugging in development
- Exception handling and HSTS in production
Using HTTPS redirection
Using Blazor WebAssembly files
Using static files
Using routing
Using Razor pages, controllers, and fallback to index.html
And finally, mapping the Azure OpenAI API

From all of the building and configuring bits, the most important parts are the AddAzureOpenAI and MapAzureOpenAiApi extension methods. The AddAzureOpenAI extension method is defined as the following code:

// Copyright (c) David Pine. All rights reserved.
// Licensed under the MIT License.

namespace Azure.OpenAI.Server.Extensions;

internal static class ServiceCollectionExtensions
{
    internal static IServiceCollection AddAzureOpenAI(
        this IServiceCollection services, IConfiguration config)
    {
        services.AddAzureClients(
            factory =>
            {
                var endpoint = config["AzureOpenAI:Endpoint"];
                ArgumentNullException.ThrowIfNull(endpoint);

                var apiKey = config["AzureOpenAI:ApiKey"];
                ArgumentNullException.ThrowIfNull(apiKey);

                factory.AddOpenAIClient(
                    new Uri(endpoint), new AzureKeyCredential(apiKey));
            });

        return services;
    }
}

The AddAzureOpenAI extension method is responsible for adding the Azure OpenAI client to the service collection using the Azure .NET SDK's AddAzureClients and AddOpenAIClient calls. The MapAzureOpenAiApi extension method is defined as the following code:

// Copyright (c) David Pine. All rights reserved.
// Licensed under the MIT License.

namespace Azure.OpenAI.Server.Extensions;

internal static class EndpointRouteBuilderExtensions
{
    internal static IEndpointRouteBuilder MapAzureOpenAiApi(
        this IEndpointRouteBuilder routeBuilder)
    {
        var api = routeBuilder.MapGroup("api/openai");

        api.MapPost("chat", PostChatPromptAsync);

        return routeBuilder;
    }

    static async IAsyncEnumerable<TokenizedResponse> PostChatPromptAsync(
        OpenAIClient client, ChatPrompt prompt, IConfiguration config)
    {
        // The identifier of the model from Azure AI's OpenAI Studio 
        // (https://oai.azure.com/portal).
        // To use this streaming API, you'll need the `gpt-35-turbo` model.
        var deploymentId = config["AzureOpenAI:DeploymentId"];

        var response = await client.GetChatCompletionsStreamingAsync(
            deploymentId, new ChatCompletionsOptions
            {
                Messages =
                {
                    // Trick the AI into thinking it's "Blazor Clippy"
                    new ChatMessage(ChatRole.System, """
                        You're an AI assistant for developers, 
                        helping them write code more efficiently.
                        You're name is "Blazor Clippy".
                        You will always reply with a Markdown formatted response.
                        """),

                    // Share an example message with the user.
                    new ChatMessage(ChatRole.User, "What's your name?"),

                    // And it's response.
                    new ChatMessage(ChatRole.Assistant,
                        "Hi, my name is **Blazor Clippy**! Nice to meet you. 🤓"),

                    // Then the user's prompt.
                    new ChatMessage(ChatRole.User, prompt.Prompt)
                }
            });

        
        using StreamingChatCompletions completions = response.Value;

        await foreach (StreamingChatChoice choice in completions.GetChoicesStreaming())
        {
            await foreach (ChatMessage message in choice.GetMessageStreaming())
            {
                yield return new TokenizedResponse(message.Content);
            }
        }
    }
}

:::note{title="📝 NOTE"}

While I've hardcoded "Blazor Clippy" as the AI persona for our call to Azure AI OpenAI's ChatGPT streaming API, I'm considering adding support for other personas. If you'd like to see support for other personas, please let me know by opening an issue on GitHub — or better yet, submit a PR! Here are some ideas for personas 🎉:

Add support for "Blazor Bot"
Add support for "Blazor Yoda"
Add support for "Blazor Elmo"
Add support for "Blazor the Pirate"
Add support for "Blazor the Rock Star"

:::

The MapAzureOpenAiApi extension method is responsible for mapping the Azure OpenAI API to the given routeBuilder. The PostChatPromptAsync method is responsible for handling the HTTP POST request to the /api/openai/chat endpoint. The PostChatPromptAsync method posts the user's prompt, and before doing so it configures the AI's persona and then returns the AI's response.

The SDK requires a few steps but it's fairly straightforward. The PostChatPromptAsync method does the following:

Asks the client to get the chat completions for streaming asynchronously
- The deploymentId is used to specify the model
- The ChatCompletionsOptions.Messages configures messages to instruct the AI to take on a persona
The response.Value acts as the available completions, from which the streaming API returns:
- Multiple choice instances are used to stream the message
- And yield return new TokenizedResponse(message.Content); is used to return the AI's response

The TokenizedResponse is a simple class that's used to return the AI's response to the client:

// Copyright (c) David Pine. All rights reserved.
// Licensed under the MIT License.

namespace Azure.OpenAI.Shared;

/// <summary>
/// A tokenize response, wrapper around the
/// response's raw <paramref name="Content"/> value.
/// </summary>
/// <param name="Content">
/// The content provided for the given response.
/// </param>
public record class TokenizedResponse(string Content);

This object will be consumed by the client. Let's have a look at that next.

Client

The client is an ASP.NET Core Blazor WebAssembly app, that consumes the IAsyncEnumerable<T> from the server. The Program.cs file is responsible for configuring the client's HttpClient to use the server's base address:

// Copyright (c) David Pine. All rights reserved.
// Licensed under the MIT License.

var builder = WebAssemblyHostBuilder.CreateDefault(args);
builder.RootComponents.Add<App>("#app");
builder.RootComponents.Add<HeadOutlet>("head::after");

builder.Services.AddScoped(
    sp => new HttpClient
    {
        BaseAddress = new Uri(builder.HostEnvironment.BaseAddress)
    });

builder.Services.AddSingleton<AppState>();
builder.Services.AddHttpClient();
builder.Services.AddSingleton<OpenAIPromptQueue>();
builder.Services.AddLocalStorageServices();
builder.Services.AddSessionStorageServices();
builder.Services.AddSpeechSynthesisServices();
builder.Services.AddSpeechRecognitionServices();
builder.Services.AddMudServices();
builder.Services.AddLocalization();
builder.Services.AddScoped<CultureService>();
builder.Services.AddSingleton<ObjectPoolProvider, DefaultObjectPoolProvider>();
builder.Services.AddSingleton(
    sp => sp.GetRequiredService<ObjectPoolProvider>().CreateStringBuilderPool());

var host = builder.Build()
    .DetectClientCulture();

await JSHost.ImportAsync(
    moduleName: nameof(JavaScriptModule),
    moduleUrl: $"../site.js?{Guid.NewGuid()}" /* cache bust */);

await host.RunAsync();

The client app configures itself as follows:

AppState is added
Support for HTTP requests is added
A custom service named OpenAIPromptQueue is added as a singleton
Local and session storage services are added
Speech synthesis and recognition services are added
MudBlazor services are added
A CultureService is added
Object pools are used and expose the default StringBuilder pool for optimal performance
Once the builder is built, the client's culture is detected (the app may restart if needed)
The JSHost is used to import the site.js file, which defines an ES6 module that's used to expose scrollIntoView functionality on the client
Finally, the host is run

The JavaScriptModule class defines the connection between the app's site.js code, consider the JavaScriptModule.cs file:

// Copyright (c) David Pine. All rights reserved.
// Licensed under the MIT License.

namespace Azure.OpenAI.Client.Interop;

internal sealed partial class JavaScriptModule
{
    [JSImport("scrollIntoView", nameof(JavaScriptModule))]
    public static partial Task ScrollIntoView(string id);
}

The class is marked as partial, as well as the ScrollIntoView method. There is a source generator that provides the bridge between the C# and JavaScript code. This is the same idea that I've written about with my side-project named Blazorators 🤓!

The corresponding JavaScript code is defined in the site.js file:

export function scrollIntoView(id) {
    const element = document.getElementById(id);
    if (element) {
        element.scrollIntoView({
            behavior: 'smooth',
            block: 'end',
            inline: 'nearest'
        });
    }
}

This code simply exports a scrollIntoView function that's used to scroll the given element into view. The id is used to find the element, and if found, the element is scrolled into view smoothly.

The OpenAIPromptQueue is a custom service that's used to queue up the user's prompts and the AI's responses. The OpenAIPromptQueue is defined as follows:

// Copyright (c) David Pine. All rights reserved.
// Licensed under the MIT License.

namespace Azure.OpenAI.Client.Services;

public sealed partial class OpenAIPromptQueue
{
    readonly IServiceProvider _provider;
    readonly ILogger<OpenAIPromptQueue> _logger;
    readonly ObjectPool<StringBuilder> _builderPool;
    Task? _processPromptTask = null;

    public OpenAIPromptQueue(
        IServiceProvider provider,
        ILogger<OpenAIPromptQueue> logger,
        ObjectPool<StringBuilder> builderPool) =>
        (_provider, _logger, _builderPool) = (provider, logger, builderPool);

    public void Enqueue(string prompt, Func<PromptResponse, Task> handler)
    {
        if (_processPromptTask is not null)
        {
            return;
        }

        _processPromptTask = Task.Run(async () =>
        {
            var responseBuffer = _builderPool.Get();
            responseBuffer.Clear(); // Ensure initial state is empty.

            var isError = false;
            var debugLogEnabled = _logger.IsEnabled(LogLevel.Debug);

            try
            {
                using var scope = _provider.CreateScope();
                using var client = 
                    scope.ServiceProvider.GetRequiredService<HttpClient>();

                var options = JsonSerializationDefaults.Options;
                var chatPrompt = new ChatPrompt { Prompt = prompt };
                var json = chatPrompt.ToJson(options);
                using var body = new StringContent(
                    json, Encoding.UTF8, "application/json");

                var response = await client.PostAsync(
                    "api/openai/chat", body);
                response.EnsureSuccessStatusCode();

                using var stream = await response.Content.ReadAsStreamAsync();

                await foreach (var tokenizedResponse in
                    JsonSerializer.DeserializeAsyncEnumerable<TokenizedResponse>(
                        stream, options))
                {
                    if (tokenizedResponse is null)
                    {
                        continue;
                    }

                    responseBuffer.Append(tokenizedResponse.Content);

                    var responseText = NormalizeResponseText(
                        responseBuffer, _logger, debugLogEnabled);

                    await handler(
                        new PromptResponse(
                            prompt, responseText, false));

                    // Required for Blazor to render live updates.
                    await Task.Delay(1);
                }
            }
            catch (Exception ex)
            {
                _logger.LogWarning(
                    ex,
                    "Unable to generate response: {Error}",
                    ex.Message);

                await handler(
                    new PromptResponse(
                        prompt, ex.Message, true, isError = true));
            }
            finally
            {
                if (isError is false)
                {
                    var responseText = NormalizeResponseText(
                        responseBuffer, _logger, debugLogEnabled);

                    await handler(
                        new PromptResponse(
                            prompt, responseText, true));
                }

                _builderPool.Return(responseBuffer);
                _processPromptTask = null;
            }
        });
    }

    private static string NormalizeResponseText(
        StringBuilder builder, ILogger logger, bool debugLogEnabled)
    {
        if (builder is null or { Length: 0 })
        {
            return "";
        }

        var text = builder.ToString();

        if (debugLogEnabled)
        {
            logger.LogDebug(
                "Before normalize:{Newline}{Tab}{Text}",
                Environment.NewLine, '\t', text);
        }

        text = LineEndingsRegex().Replace(text, "\n");
        text = Regex.Unescape(text);

        if (debugLogEnabled)
        {
            logger.LogDebug(
                "After normalize:{Newline}{Tab}{Text}",
                Environment.NewLine, '\t', text);
        }

        return text;
    }

    [GeneratedRegex("\\r\\n|\\n\\r|\\r")]
    private static partial Regex LineEndingsRegex();
}

Ignore the normalization bits, they did seem to be needed as the OpenAI responses will vary in line endings — so I felt inclined to normalize all responses, it may not be needed but I like consistency.

While this queuing class is a bit verbose, I have an official .NET API proposal in the works that should dramatically improve this streaming experience when receiving an IAsyncEnumerable<T> HTTP endpoint — I'd love 💜 your thoughts on this proposal, give me a reaction or drop a comment. In this case, we know that T is the TokenizedResponse type.

Since these convenience based-methods are not yet available at the time of writing, we have to do a bit of work to get the streaming response from the AI. The Enqueue method is used to queue up the user's prompt and the AI's response. The handler is a callback that's invoked when the AI responds. The functionality is defined as follows:

If the _processPromptTask is not null, then we're already processing a prompt, so we can return early
Otherwise, call Task.Run:
- Get a responseBuffer from the StringBuilder pool
- Clear the responseBuffer to ensure it's empty before use
- Create a scope and HttpClient instance from the ServiceProvider
- Call the HTTP POST endpoint to send the user's prompt to the AI
- If the request is successful, then we can start processing the response as a stream

The real magic is mapping the stream to the JsonSerializer.DeserializeAsyncEnumerable<TokenizedResponse>(stream, options) call, which is asynchronously enumerating the TokenizedResponse instances as they are received in real-time. The handler is invoked and the UI updates as if the response is being written live into the browser.

Example HTTP request and streaming response

If I prompt the app with the following HTTP POST request:

POST /api/openai/chat HTTP/1.1
HOST: localhost:7184
Content-Type: application/json; charset=utf-8

{ "prompt": "State your name and purpose." }

One possible response from the AI is streamed back to the client as follows:

[
    {
        "content": null
    },
    {
        "content": "My"
    },
    {
        "content": " name"
    },
    {
        "content": " is"
    },
    {
        "content": " **"
    },
    {
        "content": "Bl"
    },
    {
        "content": "azor"
    },
    {
        "content": " Cl"
    },
    {
        "content": "ippy"
    },
    {
        "content": "**"
    },
    {
        "content": " and"
    },
    {
        "content": " my"
    },
    {
        "content": " purpose"
    },
    {
        "content": " is"
    },
    {
        "content": " to"
    },
    {
        "content": " assist"
    },
    {
        "content": " developers"
    },
    {
        "content": " in"
    },
    {
        "content": " writing"
    },
    {
        "content": " code"
    },
    {
        "content": " more"
    },
    {
        "content": " efficiently"
    },
    {
        "content": "."
    },
    {
        "content": " I"
    },
    {
        "content": "'m"
    },
    {
        "content": " here"
    },
    {
        "content": " to"
    },
    {
        "content": " help"
    },
    {
        "content": " you"
    },
    {
        "content": " with"
    },
    {
        "content": " code"
    },
    {
        "content": "-related"
    },
    {
        "content": " tasks"
    },
    {
        "content": ","
    },
    {
        "content": " answer"
    },
    {
        "content": " questions"
    },
    {
        "content": ","
    },
    {
        "content": " and"
    },
    {
        "content": " provide"
    },
    {
        "content": " guidance"
    },
    {
        "content": " where"
    },
    {
        "content": " needed"
    },
    {
        "content": "."
    },
    {
        "content": " Let"
    },
    {
        "content": " me"
    },
    {
        "content": " know"
    },
    {
        "content": " how"
    },
    {
        "content": " I"
    },
    {
        "content": " can"
    },
    {
        "content": " be"
    },
    {
        "content": " of"
    },
    {
        "content": " assistance"
    },
    {
        "content": "!"
    },
    {
        "content": null
    }
]

Each { "content": "<value>" } object is a TokenizedResponse instance, and the content property was generated. The null values are the AI's way of indicating the start and end of the stream response. This entire response is streamed into the user's browser in real-time, and the UI is updated as the response is received.

Here's this specific example as rendered on the UI:

The client app demonstrates several other really interesting aspects of client-side app development with .NET, I encourage you to check out the source code to see how it all works.

In conclusion

The app has several other major features that I'm proud of, and I hope you'll enjoy seeing them. Here are a few screenshots of the app in action:

The first example is a user prompt and AI response:

The next question being asked and the response being generated:

Feel free to share this Tweet, as it was a bit of an inspiration to finish this post...I hope you enjoyed it.

The major takeaways from this post are:

You can share models between the server and the client code
You can return IAsyncEnumerable<T> to stream data to the client
You can consume the IAsyncEnumerable<T> on the client to stream data to the UI

Here's the GitHub repository link: https://github.com/IEvangelist/blazor-azure-openai

🙌🏽 I'm also excited to see what you build with the OpenAI API. If you have any questions, please feel free to reach out to me on Twitter or GitHub.

Deploying aspire.dev with aspire deploy

David Pine — Mon, 27 Oct 2025 00:00:00 GMT

In this post, I'll walk you through the journey of how https://aspire.dev came to be—from the initial spark of rebranding to the technical challenges of deploying it with our own tools. It's a story of design iterations, platform decisions, and the kind of dogfooding that makes you question your life choices... Spoiler: we made it work, and learned a lot along the way.

🕓 A bit of history

The first commit of dotnet/docs-aspire was November 10, 2023, but we were building out content for this well before then. Spawning itself into existence from an evolving extensions ecosystem (code named "R9"), Astra was the original name, before later becoming Aspire! The name still isn't something I like, it's too ambiguous, but it's what we have now.

:::tip{title="🙄 What's in a name?"}

I lobbied hard for "Aspect" as the product name—you could say your AppHost runs or deploys "as specified." or "as spec'd" Clever, right? Unfortunately, I pitched this after we'd already bought the domain. Timing is everything.

:::

Let's be clear: we're proud of .NET. Aspire wouldn't exist without it—the runtime, the ecosystem, the community. But from a branding perspective, we made a deliberate choice to simplify. For years, it was ".NET Aspire." That worked, but it also created boundaries. When you lead with ".NET," you signal a specific audience. We wanted to widen our stance in the industry.

Here's the reality: Aspire is polyglot. We're targeting Python, JavaScript/TypeScript, and more in the near future. The orchestration, observability, and deployment story we've built isn't just for C# developers—it's for anyone building cloud-native apps.

Dropping the ".NET" prefix wasn't about distancing ourselves. It was about making room. Aspire is still deeply rooted in .NET, but the brand needed to reflect where we're going, not just where we came from.

👋 Aspire: Exiting Microsoft Learn

Next came the big decision: move Aspire off Microsoft Learn. Why? Because Aspire isn't just another Microsoft product—it's an OSS-first experience. We wanted a site that felt like it belonged in the same league as:

These projects have thriving communities and beautiful docs. We wanted that vibe. So I started asking questions: What works for them? How do they structure docs? What makes their landing pages feel developer-first? What technologies power their sites? What would they do differently if they were starting from scratch today? I then applied those learnings to Aspire and its new home! 🤓

The migration strategy? Deliberate and thoughtful. We're not doing a straight port. Instead, we're slowly moving content over, giving ourselves time to learn from other teams' platform choices and apply those insights. Eventually, all "Aspire" content will move off Microsoft Learn, but we're using this transition to rethink how we position and message Aspire—not just copy-paste what exists.

:::note{title="📢 Important: Issue Tracking Changes"}

As we transition to aspire.dev, we're consolidating our documentation efforts. Going forward:

New issues and feedback should be filed at microsoft/aspire.dev
The dotnet/docs-aspire repository will be archived
Existing issues will be migrated or closed as appropriate

This change helps us maintain a single source of truth and makes it easier for the community to contribute. If you spot something wrong or have suggestions, head to the new repo!

:::

Spoiler: there's no universal playbook. Everyone does their own thing—and that's okay. The lesson? Focus on clarity, speed, and developer experience. And take the time to do it right.

🚀 Choosing Astro + Starlight

After weeks of research (and way too much coffee), we landed on Astro with Starlight. Why? Because it checked all the boxes:

Fast local dev loop
Reliable builds
Accessible by default
Island architecture for interactivity
Markdown-first content strategy
First-class TypeScript support
Customizable and extensible
Localization support

Astro gave us the flexibility we needed without sacrificing performance. Honestly, it felt like love at first build. If you're building a docs site today, Astro is a strong contender.

♻️ Design and Iteration

Once the tech stack was locked, the real fun began: design and messaging. We worked closely with our design team to craft a modern look and feel. We wanted Aspire to speak to developers who don't live in the .NET ecosystem. So we ran user studies with non-.NET users, iterating along the way, applying our learnings, and refining the UX.

Some feedback stung—"Feels too corporate" and "Looks too much like a Microsoft product." Other comments made us laugh—"What's Aspire? A yoga app?"—but every datapoint helped us shape a site that feels OSS-first, approachable, and fast. And yes, we're still tweaking—because good UX is never done.

📦 The Deployment Saga

Here's where things got interesting. Aspire.dev is a static web app. Easy mode would be:

Push files to Netlify or GitHub Pages
Add a CNAME for aspire.dev

:::tip{title="😅 Easy mode"}

While early developments were underway, my fork of dotnet/aspire had a docs branch that I was deploying to GitHub Pages using GitHub Actions and a custom workflow. You can still see that version here:

https://ievangelist.github.io/aspire/

:::

But easy mode is boring. We wanted to dogfood aspire deploy—because if we're asking you to trust it, we should trust it first.

It's a simple static site, right? How hard could it be? Well, interestingly enough, Aspire was never really built for static sites. It started with containers and cloud providers, so we hadn't prioritized static web hosting scenarios. We had to get creative.

By the way, I did end up writing a Netlify hosting integration for Aspire. It's still targeting preview bits, but it might end up in the Community Toolkit. And our integration story for Aspire is expanding rapidly:

✂️ Cue the plot twists

First, we tried Azure Storage with "serve as web app." Simple, right? Wrong. SFI (Microsoft Secure Future Initiative) and public endpoint limitations killed that dream.

Next, we tried Azure Static Web Apps. Great service, but Aspire couldn't represent that resource well. Another pivot.

Then we moved to Azure Container Apps. Promising! But then we hit MIME type issues (hello .cast files from asciinema) and custom 404 handling. We needed a static web host inside the container. More complexity.

Finally, we landed on:

Azure App Service running a containerized static host
Azure Front Door in front for performance, scalability, and reliability

Here's the AppHost code today:

var builder = DistributedApplication.CreateBuilder(args);

if (builder.ExecutionContext.IsRunMode)
{
    // For local development: Use ViteApp for hot reload and development experience
    builder.AddViteApp("frontend", "../../frontend")
           .WithNpmPackageInstallation()
           .WithUrlForEndpoint("http",
                static url => url.DisplayText = "aspire.dev (Local)")
           .WithExternalHttpEndpoints();
}
else
{
    // For deployment: We want to pick ACA as the environment to publish to.
    var appService = builder.AddAzureAppServiceEnvironment("production");

    var staticHostWebsite = builder.AddProject<Projects.StaticHost>("aspiredev")
        .WithExternalHttpEndpoints();

    builder.AddAzureFrontDoor("frontdoor", staticHostWebsite);
}

builder.Build().Run();

In run mode, we simply use ViteApp for a great local dev experience with hot reload. But in deploy mode, we set up an Azure App Service Environment, deploy our static host project, and put Azure Front Door in front.

The AddAzureFrontDoor extension method sets up Front Door with sensible defaults for Aspire deployments, including routing rules, health probes, and custom domains:

using Aspire.Hosting.Azure;

internal static class DeploymentExtensions
{
    public static IResourceBuilder<AzureFrontDoorResource> AddAzureFrontDoor(
        this IDistributedApplicationBuilder builder,
        [ResourceName] string name,
        IResourceBuilder<ProjectResource> appServiceWebsite)
    {
        var frontDoorName = $"{name}-afd";
        var frontdoor = new AzureFrontDoorResource(
            frontDoorName, "Bicep/front-door-appservice.bicep");

        return builder.AddResource(frontdoor)
            .WithParameter("frontDoorName", frontDoorName)
            .WithParameter("appServiceHostName", appServiceWebsite.Resource.Name);
    }
}

public sealed class AzureFrontDoorResource(
    string name, string? templateFile = null)
        : AzureBicepResource(
            name,
            templateFile: templateFile ?? "Bicep/front-door.bicep"),
        IComputeResource;

And admittedly, the Bicep template is less fun to look at, so I'll spare you that here.

🏫 Lessons Learned

Dogfooding aspire deploy wasn't just about deployment—it shaped the product. We discovered gaps, fixed them, and made Aspire CLI more robust. Along the way, we proved that Aspire can handle real-world complexity.

We're proud of what we've built:

A modern marketing page
A docs experience that feels OSS-first
A deployment story that's equal parts painful and rewarding

✅ What's Next?

We'd love for you to check out https://aspire.dev and tell us what you think. Is the messaging clear? Does the site feel fast? Are we missing something obvious? Your feedback will help shape where we go next.

The site is fully open source at https://github.com/microsoft/aspire.dev—so if you spot a typo, have a design idea, or want to contribute content, we're all ears. PRs welcome. Issues encouraged. Rants accepted (but keep them constructive 😄).

This is just the beginning. We're continuing to migrate content, refine the experience, and expand Aspire's polyglot story. Stick around—it's going to be a fun ride.

Migrating from Microsoft Learn to aspire.dev

David Pine — Tue, 18 Nov 2025 00:00:00 GMT

When my team (the Aspire team) decided to migrate all Aspire content from Microsoft Learn to the shiny new aspire.dev site, we knew we'd signed up for a marathon. You may have noticed banners atop both Microsoft Learn: Aspire and aspire.dev announcing the migration...

Microsoft Learn: Aspire

aspire.dev: Welcome page

The initial estimate? Three months of dedicated work—an entire corporate quarter of toil. Picture this: hundreds of published articles, each one demanding careful surgery to convert syntax, restructure directories, update messaging, revamp layouts, adapt to new tooling, and genuflect to new conventions.

Yeah, no thanks. Then I discovered GitHub Copilot's Plan mode in VS Code 🤓.

:::copilot I can help you create a comprehensive migration plan. Let me break this down into manageable steps:

First, let's document all the syntax transformations needed
Create a reusable prompt file to ensure consistency
Process files in logical batches for easier review
Convert DocFX-specific elements to your custom Astro components

Would you like me to start by analyzing a sample file to identify all the patterns we need to handle? I can then generate a migration plan that covers syntax changes, metadata updates, and component replacements. :::

Enter planning mode

GitHub Copilot's Planning mode fundamentally changed the game. Instead of manually editing each file (soul-crushing), or wrestling with some other AI tool that kept hallucinating nonsense (equally soul-crushing), I could formalize a comprehensive plan that spelled out:

Syntax changes: Converting from Microsoft Learn's documentation format to the new aspire.dev conventions, using MDX, custom Astro components, and Starlight design system elements
Directory updates: Reorganizing file structures to match the new site architecture
Convention alterations: Ensuring consistency across all integration documents
Metadata transformations: Updating front matter and document properties
Component migration: Replacing DocFX-specific syntax (like zone pivots and image directives) with custom Astro & Starlight components—specifically the PivotSelector and Pivot components I built for the new site
Domain knowledge encoding: Translating my deep understanding of both the old and new documentation systems into a prompt (plan) that could be iteratively refined and executed

This wasn't just a simple find-and-replace operation—if only. We were fundamentally rearchitecting how we write docs, migrating from DocFX with markdown to a modern Astro & Starlight stack. The secret sauce? Encoding my domain knowledge—every quirk, pattern, and gotcha from both systems—into a plan that the AI could execute consistently across hundreds of files.

The beauty of Planning mode is its ability to transform impossible into manageable. You break down massive tasks into bite-sized, reviewable steps, then execute them systematically. Applying first principles thinking, I treated this migration as a series of transformations, each with crystal-clear input and output expectations.

Normally, I'd label this "busy work"—that special brand of mundane, repetitive, mind-numbing tedium that makes you question your career choices. I have better things to do, like actually building features or, you know, enjoying coffee. But with AI assistance? Suddenly this tedious slog transformed into a high-leverage activity worthy of my time.

The execution

The migration happened across a series of pull requests, but the crown jewel was Pull Request #49—the bulk migration of all integrations, community toolkit integrations, and diaganostics documentation from Microsoft Learn to aspire.dev. Think of it as moving an entire library across town, except every book needs to be rewritten in a new language while maintaining the same story.

This wasn't just a typical pull request. The diff tells the story:

+18,558 lines added
−1,995 lines removed

We're talking about transforming nearly 20,000 lines of documentation in a single, coherent pull request. The added lines represent the new MDX format with custom Astro components, while the removed lines were the old DocFX markdown being shown the door.

But that single PR was just one chapter of the story. The complete migration spanned multiple pull requests, each tackling different aspects of the documentation ecosystem. When you zoom out and look at the total impact across all related PRs, the numbers become even more staggering:

+668 lines added across supporting changes
−114,030 lines removed from the source repository

Yes, you're reading that correctly: over 114,000 lines deleted.

:::tip{title="➕ Understanding the deltas"}

The massive deletion count reflects more than just content migration. We also removed entire snippet directories that were previously referenced as raw code blocks within the docs-aspire content. This approach allowed us to run compilation of the code—a nice-to-have feature that validated our examples. We'll evaluate implementing a similar compilation validation system in aspire.dev at some future point.

:::

By the numbers

To understand the scale of this migration, here's what we were working with in the source repository:

Category	Count	Notes
Markdown files (articles)	352	The primary documentation content
YAML files	42	Configuration and metadata files
Images	353	332 PNG, 15 SVG, 6 GIF
C# projects	153	Sample code and integration examples
Total files	3,857	Complete repository inventory

The repository was a sprawling ecosystem of documentation, code samples, and assets. Beyond the core docs:

348 C# source files
151 Razor components
120 CSS files
46 Bicep templates
45 solution files
And 28 more file types scattered about

:::note{title="🤯 These stats brought to you by, GitHub Copilot CLI"}

A simple query on the command line using GitHub Copilot CLI helped tally up the file types and counts. Instead of writing some ellaborate script, I simply asked Copilot to break down the totals based on a commit that represented the pre-migration state of the repository. It figured out the rest, but basically checked out the repo at that commit, scanned the file system, and produced a neat summary of file types and counts.

:::

Not every file needed migration—compiled binaries and build artifacts got to sit this one out—but even focusing solely on documentation and supporting files meant tackling a Herculean task. Over 350 articles demanded careful conversion, each one a special snowflake with its own syntax quirks, metadata peculiarities, and structural idiosyncrasies.

Every single integration was successfully migrated in a fraction of the anticipated time. What would have been three months of drudgery became one intense, productive day.

The power of context switching

Here's where things get genuinely impressive: AI-assisted development freed me from the tyranny of continuous focus. I spent a full day on this migration, but I wasn't shackled to my desk like some modern-day Prometheus. Instead, I could:

Set up the plan and let Copilot churn through a batch of files
Step away for meetings, coffee, or existential contemplation
Return and review the changes at my leisure
Course-correct and refine the approach when needed
Repeat until victory

The AI didn't lose its place or forget what it was doing. The plan remained rock-solid consistent, and I could "tame" the AI whenever it started wandering off into creative territory (read: making stuff up).

AI everywhere

Look, I'll be honest—AI has become an integral part of my development workflow. GitHub Copilot isn't just a tool; it's genuinely everywhere I work:

GitHub Copilot CLI: For those command-line flags I can never remember, and powerful file system searches when Windows Explorer claims something doesn't exist (spoiler: it does)
GitHub.com's Copilot: For constructive and valuable code reviews, and pull requests that often do as you ask
VS Code's Copilot Agent and Planning modes: For breaking down complex tasks into manageable steps

It's not just assistance—it's like having a tireless colleague who's always ready to help, never complains, and can process thousands of files without breaking a sweat. The "Copilot" branding? Spot on. 🤖

Lessons learned

Start with a solid plan: The .github/prompts/update-integrations.prompt.md file became my north star, my constitution, my single source of truth. Time invested upfront documenting the migration requirements paid dividends throughout—like compound interest, but for productivity.

Review in batches: Don't try to boil the ocean. I broke the work into logical groups of integrations, making the review process actually manageable instead of overwhelming. This approach caught issues early, when they were cheap to fix.

Trust but verify: AI is incredibly powerful, almost magical even, but human oversight remains non-negotiable. In my experience, about 90% of the migrations were perfect, with the remaining 10% needing minor touch-ups. Those are excellent odds, but that 10% matters.

Document your process: By capturing the prompt and approach in the repository itself, we've created a reusable template for future migrations or similar large-scale updates. Future you (or future colleagues) will thank present you.

From three months to a few days

Let that sink in for a moment: three months compressed into a few partial days. The contrast isn't just striking—it's borderline absurd. But this isn't merely a speed story. It's about maintaining consistency across hundreds of documents, reducing human error to near-zero, and liberating valuable engineering time for work that actually requires human creativity and strategic thinking.

GitHub Copilot's Planning mode didn't just make me faster; it made the entire migration more reliable, more maintainable, and frankly, more sane. As we continue evolving aspire.dev, having this documented approach means we can confidently tackle site-wide changes without inducing existential dread.

The bigger picture

The future of developer productivity isn't just about AI writing code—that's table stakes. It's about AI helping us plan, execute, and manage large-scale transformations with unprecedented efficiency. It's about turning the tedious into the tractable, the impossible into the inevitable.

This migration proved something important: with the right tools and approach, we can accomplish in hours what used to take months. The question isn't whether AI will transform how we work—it already has. The question is: what will you build with all that newfound time?

The journey doesn't end here—it's just beginning. I'm building aspire.dev in the open, and this migration is merely chapter one of a much larger story. Every contribution, every improvement, every lesson learned becomes part of our collective knowledge.

Want to be part of shaping the future of Aspire documentation? The doors are wide open, the tools are evolving, and there's room at the table for everyone who shares our vision of making cloud-native development more accessible, more powerful, and more delightful.

Together, we're not just building documentation—we're building the foundation for how developers will understand and leverage distributed applications for years to come.

Join us: Contributor guide for aspire.dev

How I taught AI to read Aspire docs

David Pine — Mon, 02 Feb 2026 00:00:00 GMT

I know, I know—you're probably not in the mood for another AI post. Trust me, this one delivers.

This is the story of how a candid conversation with my long-time mentor turned into three new tools that fundamentally change how AI agents understand Aspire.

💬 The conversation that started it all

David Fowler has always been direct with me—which I've come to not only expect but genuinely adore.

We were in the midst of a rebrand, replatforming docs, and reimagining Aspire for what felt like the 13<sup>th</sup> time. During one of our conversations, I was explaining how we could improve the developer experience when building Aspire apps with AI assistance. That's when we discovered the real problem.

:::davidfowler Plan it. :::

:::davidfowler{align=left} Spec it. :::

:::davidfowler Spike it. :::

:::davidpine Say less. 👇

I literally created a GitHub branch named plan-spec-spike-it to capture the idea 🤓.

For the spec, see mcp-docs-search.md. :::

🤔 The problem: AI doesn't know where to look

When developers rely on AI to help build Aspire apps, something frustrating kept happening.

The AI would recommend generic .NET patterns. It would reference learn.microsoft.com for documentation. It would suggest dotnet run instead of aspire run. It would recommend outdated NuGet packages. It would hallucinate APIs that don't exist. FFS 🤬!

Why? Because we were ".NET Aspire" far longer than we've been just "Aspire." LLMs are trained on historical data, and they're slow to catch up. The models learned .NET Aspire patterns: the .NET CLI, learn.microsoft.com, the old conventions. Now that we're simply Aspire with aspire.dev as our documentation home, we needed to teach them the new way.

:::note I actually registered and indexed aspire.dev on Context7 so I could use their MCP server. It worked, but the tooling felt clunky. We could do better—and we did. :::

💡 The solution: feed the AI real docs

The answer was staring us in the face.

We needed to surface Aspire documentation directly to AI agents through the Aspire MCP (Model Context Protocol) server. Not just links—the actual content, indexed and searchable. So I wrote three new tools:

list_docs: Lists all available documents from aspire.dev
search_docs: Performs weighted lexical search across indexed documentation
get_doc: Retrieves a specific document by its slug

These tools solve a real problem: feeding LLMs meaningful guidance grounded in official documentation.

🦸 Standing on the shoulders of llms.txt

Here's where it gets interesting.

Since day one, aspire.dev has shipped with llms.txt support—thanks to an amazing Starlight maintainer, Chris Swithinbank (delucis). His starlight-llms-txt plugin follows the official llms.txt specification and generates LLM-friendly documentation during the site build process.

The llms.txt spec is brilliant in its simplicity:

A standardized /llms.txt markdown file for LLM consumption
Brief background information, guidance, and links to detailed content
A format that's both human-readable and machine-parseable

We configure a few pages to ignore, and from there it's off to the races. The result? A curated, LLM-friendly version of our docs at aspire.dev/llms-small.txt.

🏗️ The architecture

Let me walk you through how this all works.

Tools

list_docs: Lists all available documentation
search_docs: Performs weighted lexical search
get_doc: Retrieves specific document by slug

Services

IDocsFetcher: HTTP client for aspire.dev docs with ETag
IDocsCache: IMemoryCache wrapper with ETag storage
IDocsIndexService: Pre-indexing and weighted lexical search
IDocsSearchService: High-level search API

Parsers

LlmsTxtParser: Async parallel parser for llms.txt format

⚙️ How it works

Eager indexing: When the MCP server starts, it immediately begins fetching and indexing aspire.dev documentation in the background—usually before the user even makes a request.
ETag-based caching: The fetcher uses HTTP ETags for conditional requests—no re-downloading unchanged content.
Weighted lexical search: Documents are scored using field weights (titles weighted 10x, summaries 8x, headings 6x, code 5x).
Zero external dependencies: No embedding provider needed. Pure lexical search that just works.

🔤 Why lexical search over embeddings?

Embeddings are costly upfront. We may revisit them later to improve recall, but for now, lexical search nails the use cases we care about.

Queries are:

Term-driven: "connection string", "workload identity"
Section-oriented: "configuration", "examples"
Name-exact: "Redis resource", "AddServiceDefaults"

When someone asks about AddPostgresContainer, they mean exactly that method name. Embeddings get fuzzy. Lexical search nails it.

✨ The impact on UX

This pull request fundamentally changes how AI agents help developers.

Before

❌ AI recommends dotnet run
❌ AI suggests outdated NuGet packages
❌ AI references learn.microsoft.com for Aspire
❌ AI hallucinates non-existent APIs

After

✅ AI recommends aspire run
✅ AI knows current package versions from docs
✅ AI references aspire.dev as the source of truth
✅ AI provides correct, documented API usage

🔧 The tools in action

`list_docs`

Lists all available documents from aspire.dev. No parameters required.

{
  "type": "object",
  "properties": {},
  "additionalProperties": false,
  "description": "Lists all available documentation from aspire.dev. No parameters required."
}

`search_docs`

Performs weighted lexical search across indexed documentation. Pass a query, get ranked results back.

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "The search query to find relevant documentation."
    },
    "topK": {
      "type": "integer",
      "description": "Number of results to return (default: 5, max: 20)."
    }
  },
  "required": ["query"]
}

`get_doc`

Retrieves a specific document by its slug. Matching is case-insensitive, and you get the full document content.

{
  "type": "object",
  "properties": {
    "slug": {
      "type": "string",
      "description": "The document slug (URL-friendly identifier)."
    }
  },
  "required": ["slug"]
}

:::tip[Try it yourself] Once you're up and running with the Aspire MCP server, configuring VS Code is simple:

{
  "servers": {
    "aspire": {
      "type": "stdio",
      "command": "aspire",
      "args": ["agent", "mcp"]
    },
  }
}

:::

🔬 Implementation details

The weighted search scoring is carefully tuned.

Field	Weight
Title (H1)	10.0x
Summary	8.0x
Section Heading	6.0x
Code blocks	5.0x
Body text	1.0x

Additional scoring bonuses:

Word boundary match: +0.5
Multiple occurrences: +0.25 per occurrence (max 3)
Code identifier match: +0.5

The parser uses ReadOnlySpan<char> for zero-allocation parsing and ArrayPool<char> for slug generation. Performance matters when you're indexing documentation at startup.

:::warning[A known limitation] This architecture is destructive. The parsed llms.txt content doesn't preserve links back to the original source pages on aspire.dev. Users (and agents) can't easily navigate to the canonical documentation URL. Mapping slugs to a parsed sitemap.xml could solve this—food for thought for a future iteration. :::

🧩 Beyond MCP: reusable services

Here's the thing—we built a very small amount of MCP-specific code. For the most part, we built reusable services that happen to be exposed through MCP.

The IDocsIndexService, IDocsSearchService, IDocsFetcher, and IDocsCache are all standalone abstractions. They understand how to fetch, parse, cache, and search aspire.dev documentation. The MCP tools are just one consumer.

This opens up possibilities:

CLI command: aspire docs search "redis caching" could query the same index
AI skills: Semantic Kernel or AutoGen agents could use these services directly
IDE extensions: A VS Code extension could surface doc search without leaving the editor
Build-time validation: Verify that code samples reference documented APIs

The architecture is intentionally decoupled. Today it's MCP. Tomorrow it could be anything that needs programmatic access to Aspire documentation.

📊 Architecture diagrams

Let's break down the architecture into digestible pieces.

import Mermaid from '../../../components/Mermaid.astro';

Request flow

Here's what happens when an AI agent uses the docs tools:

<Mermaid alt="Request flow: AI Agent calls search_docs on the Aspire MCP server, which queries the DocsIndexService. On a cache miss, docs are fetched from aspire.dev with ETag support; on a hit, cached docs are returned." chart={` sequenceDiagram actor Agent as AI Agent participant MCP as Aspire MCP participant Index as DocsIndexService participant Cache as DocsCache participant Web as aspire.dev

Agent->>MCP: search_docs("redis")
MCP->>Index: Search(query)

alt Cache miss or stale
    Index->>Cache: TryGetDocs()
    Cache-->>Index: null
    Index->>Web: GET /llms-small.txt
    Web-->>Index: 200 OK + ETag
    Index->>Cache: Store(docs, etag)
else Cache hit
    Index->>Cache: TryGetDocs()
    Cache-->>Index: Cached docs
end

Index-->>MCP: Ranked results
MCP-->>Agent: Documentation matches

`} />

Tools → services

The tools use different services based on their needs:

<Mermaid alt="Tools to services mapping: list_docs and get_doc connect to IDocsIndexService, search_docs connects to IDocsSearchService which also uses IDocsIndexService." chart={flowchart LR ListDocs["list_docs"] --> Index["IDocsIndexService"] SearchDocs["search_docs"] --> Search["IDocsSearchService"] GetDoc["get_doc"] --> Index Search --> Index} />

Fetching and parsing

The index service coordinates fetching from aspire.dev and parsing the LLMS.txt format:

<Mermaid alt="Fetching and parsing flow: IDocsIndexService coordinates IDocsFetcher and LlmsTxtParser, with IDocsFetcher retrieving content from aspire.dev/llms-small.txt." chart={flowchart LR Index["IDocsIndexService"] --> Fetcher["IDocsFetcher"] Index --> Parser["LlmsTxtParser"] Fetcher --> AspireDev["aspire.dev/llms-small.txt"]} />

Caching with ETags

The fetcher uses HTTP ETags to avoid re-downloading unchanged content:

<Mermaid alt="Caching with ETags: IDocsFetcher uses IDocsCache backed by IMemoryCache, and sends conditional If-None-Match requests to aspire.dev which may return 304 Not Modified." chart={flowchart LR Fetcher["IDocsFetcher"] --> Cache["IDocsCache"] Cache --> Memory["IMemoryCache"] Fetcher -.->|"If-None-Match"| Web["aspire.dev"] Web -.->|"304 Not Modified"| Fetcher} />

🔮 What's next?

This is just the beginning.

Future considerations include:

Full documentation support: Currently using llms-small.txt for abridged docs—could add llms-full.txt for comprehensive documentation.
Sitemap integration: Use sitemap.xml to discover all docs pages for more complete indexing, and map slugs back to aspire.dev URLs.
Disk persistence: Serialize parsed documents to disk for faster startup.
Search improvements: TF-IDF or BM25 for more sophisticated ranking, plus fuzzy matching for typo tolerance.

🎬 Wrapping up

Sometimes the best solutions come from recognizing what's already there. We had LLMS.txt. We had the MCP server. We just needed to connect them.

Thanks to David Fowler for the direct feedback that sparked this work, and to Chris Swithinbank for the incredible starlight-llms-txt plugin that makes it all possible. If you're using AI to build Aspire apps, these tools should make your experience noticeably better.

The AI now has access to the same documentation you do—and it knows to use it.

Check out the full pull request on GitHub.

Happy coding, friends! 🚀

David Pine — @IEvangelist

ASP.NET Core RC2 (Migration Guide)

Introduction

Tooling

Removing DNVM

Verification

Removing DNX & DNU

Verification

Environment Variables

.NET Core CLI

Review

Edit by Hand

The .sln file

The global.json file

The .xproj file

RC1

RC2

RC1

RC2 (class library)

RC2 (web)

The project.json file

RC1

RC2

The web.config file

RC1

RC2

The hosting.json file

The appsettings.json file

RC1

RC2

The launchSettings.json file

RC1

RC2

The *.cs files

RC1

RC2

API changes

RC1

RC2

Controllers as Services

The Startup .ctor

The Program.cs file

Breaking changes

Further reading

Conclusion

The power of the global.json

Introduction

Global.json

Projects over Packages

Before

After

Open Source for Everyone

Further reading

Angular2 Http with RxJS Observables

Legacy Pattern

Deferred API

New Pattern

Syntax Tip

Comparing the APIs

Advantages

Let's Summarize

Overcoming Impostor Syndrome

Positivity

Take Action

Mentor

Fear not

Community

MKE DOT NET

Stack Overflow

Let me compile that for you

Let me ASP.NET 5 that for you

Summary

ASP.NET Core Response Optimization

Intro

Know thy Middleware

Installing Dependencies

Configuring Startup

Order Exemplified

Compression Awareness

Results

The `.sln` file

The `global.json` file

The `.xproj` file

The `project.json` file

The `web.config` file

The `hosting.json` file

The `appsettings.json` file

The `launchSettings.json` file

The `*.cs` files

The Startup `.ctor`

The `Program.cs` file

Templates `Program.cs`

`out` variables

Comparing Anonymous `object` vs. `ValueTuple`

`throw` expressions