Have you ever watched a skilled engineer pull up a terminal, issue a few keystrokes and kick off a whole series of processes in seconds? It can be downright magical, some even wizard-like. A few are hard to distinguish from cackling necromancers raising processes from the dead.

I'll let you in on a little secret, engineers who are comfortable on the command line are not wizards, they are pack rats. They accumulate techniques and store them away in a toolbox and take it everywhere they go.

That engineer can sit down at any machine and within minutes reach into their toolbox and become productive.

Let's take a look at one technique that I use. It is not my technique, like all good pack rats I borrowed it from countless others and added them to my toolbox.

The technique I use, is fairly macOS focused. It will work on macOS, Linux and WSL on Windows. You can do similar things in PowerShell, I encourage you to take a look at Michael Jolly's devtoolbox project for examples.

Let's start by creating your toolbox in a way that you can access it from any machine. Head to GitHub and create a new repository called dotfiles. This is a common name for this kind of repository, remember it. You can find all kinds of great examples by looking at other peoples dotfiles repos.

If you want to allow others to use tools from your toolbox, consider adding an MIT license and making your repo public. Be sure to add a README file. It will be useful later when you want to start documenting things for others to consume.

Once you have created the repository, let's clone it to your machine. We will do this in a special place called your home directory located in your user directory. We will also give it a special name.

cd ~
git clone git@github.com:NotMyself/dotfiles.git .dotfiles

Use git to clone the repository to a directory named .dotfiles. Notice the period in front of the directory name. This makes the directory a hidden one. Trying running these two commands to see what I mean.

ls
ls -a

The first command lists the files and directories in the current directory. Notice that the .dotfiles directory is not displayed. The second command uses the -a flag to show all files and directories.

Here is what it looks like on my machine currently.

As you can see, I have a variety of dot files for various things. Can you spot my .dotfiles directory?

Next, you will need to wire up your .dotfiles directory in a way that your terminal application will use it. By default, macOS terminal uses zsh as it's shell. So create a zsh directory in the .dotfiles directory and add a .zshrc file to it.

cd ~/.dotfiles
mkdir zsh
touch ./zsh/.zshrc

When a new shell is started in a terminal application, zsh will look for a .zshrc file in the home directory of the current user. It will then execute that file. Of course, your file is located in the .dotfiles/zsh directory.

We can fix that by creating a symbolic link between the file's current location on disk and where zsh expects it to be. To do that, create an install script in your .dotfiles directory.

echo "#\!/usr/bin/env sh" > ./install
echo "echo \"Installing..\"" >> ./install
chmod +x ./install
./install

There is a bit of magic going on here, so let's break it down. The first command creates a file named install and adds a special value as the first line. This value is called a shebang. It is used to decide how a file will be executed. In this case, the shebang checks the local system environment for the configured shell. So this install script will execute in zsh.

The next command, adds a line to the install file that will write the text "Installing..." to the terminal when the install script is executed. We will use this to verify everything is working correctly.

Text files in macOS are not typically executable. So the next command explicitly set the install text file as executable. This only needs to be done once when you create a script file.

The final command executes the install script. The output on my machine looks like this.

Finally, add the command needed to create the symbolic link to the .zshrc file to the install script. Open the install script in a text editor and add the following line.

# shell settings
ln -sv /Users/bobby/.dotfiles/zsh/.zshrc ~/.zshrc

Note that your user directory name will be different than mine. Be sure to change the bobby value to the name of your user directory. If you are not sure what that name is run echo ~ in your terminal to display the full path to your home directory.

This is a key concept in creating your toolbox. Instead of just looking up commands and running them once to set things up make a script file that does it so you do not have to look it up again.

I simply looked at my install script in my dotfiles repository to find the symlink command. See, I am not a wizard I am a pack rat.

At this point you should commit your changes to the Git repository. Now, run the install script.

./install

You may recieve an error that a file named .zshrc already exists in your home directory. In that case, make a backup of that file for later review and run the install again.

mv ~/.zshrc ~/.zshrc_backup
./install

You can now list the contents of your home directory and you should see the .zshrc file.

ls -a ~

Remember though, this is a symbolic link to the file in our .dotfiles repository. Which basically makes it our entry point to setup our shell any way we want.

Now, let's make it do something interesting. Open the ~/.dotfiles/zsh/.zshrc file in a text editor and add the following.

for DOTFILE in `find /Users/bobby/.dotfiles/system`
do
  [ -f $DOTFILE ] && source $DOTFILE
done

This script will execute each of the files located in the system directory in our .dotfiles directory. Making them available to the current shell.

I typically setup a series of files in the system folder: .alias, .env, .function, .path, and .prompt.

• .alias - contains a set of command aliases to commands that already exist on my machine.
• .env - contains commands to add additional functionality into my terminal environment.
• .function - contains a set of functions that are useful in my terminal environment.
• .path - updates the $PATH to include any other binary sources on my machine.
• .prompt - contains the configuration needed to setup my fancy shell prompt.

Aliases can be very useful for common commands containing elaborate flags and values that you use regularly. Let's set up a few so you can see how easy it is. First, we need to set up the .alias file.

cd ~/.dotfiles
mkdir system
touch system/.function

Then add the following code to the .alias file.

alias l="ls -la"       # List in long format, include dotfiles
alias ld="ls -ld */"   # List in long format, only directories
alias ..="cd .."
alias ...="cd ../.."
alias ....="cd ../../.."

These aliases are ones that I use for navigating around the file system. As you can see they are simply shortcuts for other commands.

Functions on the other hand allow you to do more complex tasks with a single command. Let's set you up with one of my favorite functions. Typically when I create a new directory using the mkdir command the very next thing I do is change directories into the one I just created.

Let's create a function that does this in one command instead of two. First, you need to create the .function file.

cd ~/.dotfiles
touch system/.function

Next, add the following code to the .function file using a text editor.

# Create a new directory and enter it
function mk() {
  mkdir -p "$@" && cd "$@"
}

Now when you wish to create a directory and enter it you can execute the command mk foo.

Commit these changes to your dotfiles repository.

And with that your toolbox is setup. Start collecting the tools that make you look like a wizard. You can take a look at my dotfiles repository for ideas. Or, search GitHub for others.

In a previous life, I was a heavy user of Visual Studio on Windows. But for the last few years I have been working exclusively on Mac OSX and using VSCode as my primary editor.

One feature of the full Visual Studio that I miss is integrating with a Symbol Server for debugging code that does not belong to me.

If you are not familiar with how a debugger works (at least in .NET), debugging information is stored in a symbol file separate from the executable that is being built by a compiler. All modern version of Microsoft compilers store that information in  a program database file, or .pdb.

You might recognize those files from building a debug version of your applications. But did you know that Microsoft also produces symbol files for the .NET Core framework libraries as well?

And they make those symbols available via a Symbol Server. A symbol server enables debuggers to automatically retrieve the correct symbol files for a given library.

Micorsoft also makes their source code available via a Source Server. This allows a client to retrieve the exact version of the source code that were used to build an assembly.

Combining a Symbol and Source Server it is possible to debug right into any library you are using just like you do with your own code.

In full Visual Studio there is a deeply nested configration setting that you enable to make all this work. It is a bit more involved to get working in VSCode, let me outline the steps for you.

First, install the dotnet cli global tool for symbols.

dotnet tool install -g \
    --add-source https://api.nuget.org/v3/index.json \
    dotnet-symbol

This will add everything that is needed to fetch symbols from the primary NuGet source. This happens to be where we get all of the .NET libraries from.

We can use this tool now by issuing the command dotnet symbol from our terminals.

Next, we need to pull the symbols for the meta package we are using to build the application.

dotnet symbol --symbols \
  --output /tmp/symbols \
  /usr/local/share/dotnet/shared/Microsoft.AspNetCore.App/3.1.2/*

This will use the symbol tool to download the pdb symbol  files to a temporary directory for all the dlls found in the AspNetCore meta package version 3.1.2 that is located on my local machine.

Once downloaded, we can copy them into the meta package directory.

sudo cp /tmp/symbols/* \
  /usr/local/share/dotnet/shared/Microsoft.AspNetCore.App/3.1.2

Now that the symbols are in the right place, the debugger can use them to fetch source code and debug into the .NET Core framework. These steps only need to be completed once per .NET Core SDK you have installed. Any application you build from here out on that SDK will have the symbols available to it.

But if we jump into VSCode and attempt to debug an application, we will start seeing messages like this in the Debug Console.

Loaded '/src/sample/src/server/bin/Debug/netcoreapp3.1/Microsoft.IdentityModel.Protocols.dll'.
Skipped loading symbols.
Module is optimized and the debugger option 'Just My Code' is enabled.

This message is telling us that the debugger skipped loading external symbols because the "Just My Code" debugger option is enabled.

This is a feature of the debugger that allows us to focus our debugging session only on code that we have written. And that is probably the normal state we want to use.

But we can easily tell the debugger that we want to debug all the code we have symbols for by setting a flag in the launch.json file.

{
   "version": "0.2.0",
   "configurations": [
        {
            "name": ".NET Core Launch (web)",
            "type": "coreclr",
            "request": "launch",
            "preLaunchTask": "build",
            "program": "${workspaceFolder}/src/server/bin/Debug/netcoreapp3.1/server.dll",
            "args": [],
            "cwd": "${workspaceFolder}/src/server",
            "stopAtEntry": false,
            "justMyCode": false,
            "env": {
                "ASPNETCORE_ENVIRONMENT": "Development"
            }
        }
    ]
}

In this example, we have added the justMyCode property to the .NET Core Launch configuration and set it's value to false.

And just like that, we are debugging the .NET Core framework libraires on our local machine.

On August 5th of 2019, Daniel Roth announced on the aspnetcore repository that Microsoft.AspNetCore.SpaServices and Microsoft.AspNetCore.NodeServices were being made obsolete in the coming .NET Core 3 release.

As you can see from the annourncement issue, there has been quite a bit of commentary from folks who have been relying on these services for various workflows.

I have been using the DevelopmentServer middleware quite heavily in my Bivrost project for debugging purposes. The way it worked in .NET Core 2 is the middeware would shell out and start a webpack development server and proxy requests from the aspnetcore application to the SPA application.

This functionalty went away. So I had to figure out another way to setup my development workflow.

Workaround for Webpack Based Frontend Apps

This workaround is taken directly from this application that I work on in my spare time. I have removed all use of the SpaServices provided development server. Instead, I configure webpack to proxy requests to aspnetcore and setup vscode to launch both processes.

Startup.cs

The startup configuration is here only to serve up the built webpack based SPA application for production purposes. The location of this path is configurable in the appsettings.json and is specific to your application.

public class Startup
  {
    public void ConfigureServices(IServiceCollection services)
    {
      //configures the root of the built spa files
      services.AddSpaStaticFiles(configuration =>
      {
          configuration.RootPath = Configuration["Client"];
      });
    }

    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
      //tells the application to serve them up for production use
      app.UseStaticFiles();
      app.UseSpaStaticFiles();
    }
  }

vue.config.js || webpack.config.js

This configuration can go in your vue.config.js or webpack.config.js. It will proxy all http requests to the provided url (including websockets/signalr). This is a fairly standard thing to do in the frontend world.

module.exports = {
  devServer: {
    proxy: 'http://localhost:5000/'
  }
};

.vscode/launch.json

The vscode launch.json tells the editor how to launch your application for debugging. This setup creates 2 configurations a Client for starting the webpack based app using NPM and a Server for starting the backend using dotnet cli. Then I use a compound configuration that joins the two together. Simply select the compound configuration in vscode and click run.

Note: The Client configuration does not attempt to connect a debugger, it just starts the app via NPM. I prefer to debug client-side code in my browser.

{
  "version": "0.2.0",
  "compounds": [
    {
      "name": "Bivrost",
      "configurations": ["Server", "Client"]
    }
  ],
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Client",
      "runtimeExecutable": "npm",
      "runtimeArgs": [
        "run-script",
        "serve"
      ],
      "noDebug":true,
      "cwd": "${workspaceFolder}/src/client",
      "skipFiles": [
        "<node_internals>/**"
      ]
    },
    {
      "name": "Server",
      "type": "coreclr",
      "request": "launch",
      "preLaunchTask": "build",
      // If you have changed target frameworks, make sure to update the program path.
      "program": "${workspaceFolder}/src/server/bin/Debug/netcoreapp3.1/server.dll",
      "args": [],
      "cwd": "${workspaceFolder}/src/server",
      "stopAtEntry": false,
      "env": {
          "ASPNETCORE_ENVIRONMENT": "Development",
      }
    }
  ]
}

When the application is running in debug, your screen will look similar to this:

Note: There are two debug consoles one for the Client app and one for the Server app. You also have a drop-down menu in the debug controls at the top to select either process as well. You do have to stop them both.

In this stream, we cover an overview of the Bivrost frontend, how websockets are managed using Vuex plugins and end with some conversion work using Vuetify.

Stream Channel: https://notmyself.livecoders.dev/
Repository: https://github.com/notmyself/bivrost

Vuex is a state management plugin for Vue.js. It allows you to centrally store all data needed for a Vue application and manage mutations (changes) to that data.

Out of the box it works really well for working with data from an API. But when working with realtime data being pushed to the client over websockets, there isn't a good way to represent that flow in a clean way.

Here is an example. Say we have a Vue application that needs to connect to a SignalR hub to recieve chat messages and display them realtime.

• Where should you put the SignalR client construction logic?
• Where should you put the logic to start the SignalR client connection?
• How do you dispatch SignalR messages into the Vuex store?

This post will cover each of these topics and the concepts outlined here can be used with any websockets library you want.

Setting Up a Chat Store

First, let's setup a Vuex store for handling our realtime chat data. I typically set up Vuex modules for each specific domain my apps need to know about. A simple chat module looks like this.

const state = {
  chatMessages: [],
  limit: 5
};

const getters = {
  displayMessages: state => state.chatMessages
};

const actions = {
  addMessage({ commit }, message) {
    commit('ADD_MESSAGE', message);
  },
  deleteMessage({ commit }, message) {
    commit('DELETE_MESSAGE', message);
  }
};

const mutations = {
  ADD_MESSAGE(state, message) {
    while (state.chatMessages.length >= state.limit) {
      state.chatMessages.shift();
    }
    state.chatMessages.push(message);
  },
  DELETE_MESSAGE(state, message) {
    state.chatMessages = state.chatMessages.filter(m => m.id !== message.id);
  }
};

export default {
  namespaced: true,
  state,
  getters,
  actions,
  mutations
};

This chat module will maintain an array of chat messages for display. The array is limted to five messsages. When a new message is added, the oldest messages is popped off the stack.

Note: I am explicitly using namespaces in the module definition. Here is how you call a namespaced module using the Vuex store.

store.dispatch('chat/addMessage', message);

This call will execute the addMessage action passing it the message object.

Using this module in your Vuex store is pretty simple.

import Vue from 'vue';
import Vuex from 'vuex';

import chat from './modules/chat';

Vue.use(Vuex);

export default new Vuex.Store({
  modules: {
    chat
  }
});

Import the chat module then pass it along to the Vuex store constructor.

Finally, instruct Vue to use the store in main.js.

import Vue from 'vue';
import store from './store';
import App from './App.vue';

Vue.config.productionTip = false;

new Vue({
  store,
  render: h => h(App)
}).$mount('#app');

Note that the Vue instance has no knowledge of how the store is setup, it simply uses it as configured.

We now have a store that is capible of handling our chat message state and making that state available to any Vue component that wants to consume it.

Setting Up a Websocket Plugin

Vuex has a nice plugin model that allows you to add functionality by hooking into a stores mutations. For each websocket connection we can create a plugin that manages the interaction between socket messages we care about and the store.

Here is the basic shell of the plugin we will be building over the next few sections.

export default function createWebSocketPlugin() {
  return store => {
  
  };
}

The module simply exports a function that returns a function with a single parameter: the store itself. To wire it up to the Vuex store, import the plugin and hand it off to the Vuex store constructor plugins array.

import Vue from 'vue';
import Vuex from 'vuex';

import chat from './modules/chat';
import chatSocket from './plugins/chat';

Vue.use(Vuex);

export default new Vuex.Store({
  modules: {
    chat
  },
  plugins: [chatSocket()]
});

Now that the plugin is wired in, we can update it to create a websocket connection.

import { HubConnectionBuilder } from '@aspnet/signalr';

const client = new HubConnectionBuilder()
  .configureLogging(process.env.VUE_APP_SIGNALR_LOG_LEVEL)
  .withUrl(process.env.VUE_APP_SIGNALR_HUB_URL)
  .build();


export default function createWebSocketPlugin() {
  return store => {
      //subscribe to events
    client.start();
  };
}

Here we have imported a websocket library called SignalR. It is a popular way of communicating with .NET server applications, but any websocket library will do.

Then we create a client and start the connection after we have subscribed to any events. The plugin how has access to both a websocket client and the Vuex store.

Subscribing to Connection Events

Our client side Vue application need a way to monitor the connection state of the websocket to ensure it does not try to use a closed connection. Let's subscribe to our first event by handling the connection status of the websocket.

First, update the chat vuex module to keep track of the connection state as well as actions and mutations for updating it.

const state = {
  connected: false,
  error: null,
  chatMessages: [],
  limit: 5
};

const getters = {
  displayMessages: state => state.chatMessages
};

const actions = {
  addMessage({ commit }, message) {
    commit('ADD_MESSAGE', message);
  },
  deleteMessage({ commit }, message) {
    commit('DELETE_MESSAGE', message);
  },
  connectionOpened({ commit }) {
    commit('SET_CONNECTION', true);
  },
  connectionClosed({ commit }) {
    commit('SET_CONNECTION', false);
  },
  connectionError({ commit }, error) {
    commit('SET_ERROR', error);
  }
};

const mutations = {
  ADD_MESSAGE(state, message) {
    while (state.chatMessages.length >= state.limit) {
      state.chatMessages.shift();
    }
    state.chatMessages.push(message);
  },
  DELETE_MESSAGE(state, message) {
    state.chatMessages = state.chatMessages.filter(m => m.id !== message.id);
  },
  SET_CONNECTION(state, message) {
    state.connected = message;
  },
  SET_ERROR(state, error) {
    state.error = error;
  }
};

export default {
  namespaced: true,
  state,
  getters,
  actions,
  mutations
};

We have added a flag to indicate connection status and an error to the state. By default the connection is not available and there is no error state. We have added actions for opening and closing the connection as well as populating the error.

Now we update the plugin to subscribe to connection events and push them to the store.

import { HubConnectionBuilder } from '@aspnet/signalr';

const client = new HubConnectionBuilder()
  .configureLogging(process.env.VUE_APP_SIGNALR_LOG_LEVEL)
  .withUrl(process.env.VUE_APP_SIGNALR_HUB_URL)
  .withAutomaticReconnect()
  .build();

export default function createWebSocketPlugin() {
  return store => {
    client.on('stateChanged', (oldState, newState) => {
      if (oldState !== newState && newState !== 'Connected')
        store.dispatch('chat/connectionClosed');
      else store.dispatch('chat/connectionOpened');
    });

    client
      .start()
      .then(() => {
        store.dispatch('chat/connectionOpened');
      })
      .catch(err => {
        store.dispatch('chat/connectionError', err);
      });
  };
}

Here we are subscribing to the stateChanged event. If the state is anything other than "Connected" we dispatch a closed action to the store otherwise the opened action.

We also handle the start promise states calling the appropriate actions.

Subscribing to Chat Events

The websocket server I am connecting to will raise receiveChatMessage events for each chat message sent to the server. We can easily subscribe to this event in our plugin.

client.on('receiveChatMessage', message => {
  store.dispatch('chat/addMessage', message);
});

The event handler dispatches the addMessage action passing along the received message.

Subscribing to Mutations

Our plugin is successfully managing it's own connection state and pushing messages into the Vuex store. But the application will need to send chat messages as well.

To accomplish that the plugin needs to subscribe to mutations and handle the ones it cares out.

store.subscribe((mutation, state) => {
  if (state.chat.connected && mutation.type === 'chat/SEND_MESSAGE')
    client.invoke('SendMessage', null, message);
});

Here we subscribe to all mutations. Then check the websocket connection state and mutation type before sending the message to the server.

Wrapping Up

This post has described the technique that I have used in my Twitch streaming application Bivrost. If you would like to see how all of this is wired up in an acual application check out the src/client/src/store directory.

In this stream we do some hacking on Bivrost my Vue.js/ASP.NET Core Twitch bot and overlay system. We learn some good techniques on Vuex.

Stream Channel: https://notmyself.livecoders.dev/
Project: https://github.com/NotMyself/bivrost/projects/1
Repository: https://github.com/NotMyself/bivrost

The reports of my death are greatly exaggerated. Join me for a catch-up session. We will discuss some upcoming events, what's new at Auth0 and a project I have been working on called Bivrost.

Photo by Rueben McChristian on Unsplash

In this stream, we cover updating a Vue.js application to use an external identity provider to authenticate using OpenID Connect and OAuth 2.

Stream Channel: https://notmyself.livecoders.dev/
Project: https://github.com/NotMyself/securing-vue/projects/1
Repository: https://github.com/NotMyself/securing-vue
Completed: https://github.com/NotMyself/securing-vue/tree/complete

Photo by Yanny Mishchuk on Unsplash

Twitch.tv's API does not offer a way to fetch scheduled events. In this stream, we take a stab at writing a screen-scraper to fetch event information for a given stream team.

Stream Channel: https://notmyself.livecoders.dev/

Photo by Korey Moore on Unsplash

In this popup stream, I show how you can verify a jwt token for any framework you want to use by hand.

Stream Channel: https://notmyself.livecoders.dev/
Twitter: https://twitter.com/NotMyself

Photo by Danielle Calicdan on Unsplash

Having set up the basic application structure in the previous session, in this session we will cover setting up continuous deployment on Zeit Now. Now bot will detect commits to the source control repository and trigger a build producing a deployable version of the application.

Stream Channel: https://notmyself.livecoders.dev/
Github Repository: https://github.com/NotMyself/zeitcore
Twitter: https://twitter.com/NotMyself

Photo by Taylor Young on Unsplash