Interning and Go

Interning, a term originally introduced by Lisp is the process of storing only one copy of a value in memory and sharing a unique reference to it instead of allocating multiple copies and wasting memory. For instance the Go compiler already performs interning of string constants at compile time, so instead of allocating multiple identical strings it will allocate a single instance of the string and share a reference to it, as demonstrated in the snippet below. (Go Playground here)

package main

import (
	"fmt"
	"reflect"
	"unsafe"
)

const greet1 = "hello world"
const greet2 = "hello world"

func main() {
	a := greet1
	p := (*reflect.StringHeader)(unsafe.Pointer(&a))
	fmt.Println("a address:", *&p.Data)

	b := greet2
	p2 := (*reflect.StringHeader)(unsafe.Pointer(&b))
	fmt.Println("b address:", *&p2.Data)
}

$ go run main.go

a address: 4310983661
b address: 4310983661

Before Go 1.23, interning runtime values has only been available via third-party packages. However, as of Go 1.23 interning is now included in the standard library via the new unique package.

The unique Package in Go 1.23

Interning (or ‘canonicalizing values’) can now be performed using the unique package via its Handle type that acts as a globally unique identity for any provided (comparable) value, meaning two handles compare equal exactly if the two values used to create the handles would have also compared equal.

type Handle[T comparable] struct {}
func (h Handle[T]) Value() T {}
func Make[T comparable](value T) Handle[T] {}

Internally the Handle type is backed by a concurrent-safe map (well, an adaptive radix tree to be precise due to its need to shrink and grow the tree more efficiently than a map) which acts as a read-through cache, storing unique values when not detected in the cache and returning a Handle[T] which is designed to be passed around as values/fields instead of the underlying value, saving you additional allocations and also resulting in cheaper comparisons as you’ll only incur a reference comparison as opposed to a value comparison.

Couldn’t you achieve the same behaviour with a map of unique values?

Sure, the same interning behaviour could be achieved using a custom map to reduce duplicate allocations, however handling garbage collecting efficiently isn’t possible. The unique package has a notion of “weak references” that means the garbage collector can clean up in a single cycle made possible by access to runtime internals, something a custom rolled solution wouldn’t be able to perform.

How to use the unique package

Let’s take a look at an trivial example, inspired by the net/netip package which actually uses the unique package for efficient handling of IPv6 zone names.

package main

import (
	"unique"
)

type addrDetail struct {
	isV6   bool
	zoneV6 string
}

func main() {
	h1 := unique.Make(addrDetail{isV6: true, zoneV6: "2001:0db8:0001:0000:0000:0ab9:C0A8:0102"})

	// this addrDetail won't be allocated as it already exists in the underlying map
	h2 := unique.Make(addrDetail{isV6: true, zoneV6: "2001:0db8:0001:0000:0000:0ab9:C0A8:0102"})

	if h1 == h2 {
		println("addresses are equal")
	}
	
	// Value() returns a copy of the underlying value (ie, different memory address)
	println(h1.Value().zoneV6) 
}

Handle Comparison Performance

Earlier I mentioned that along with a reduction of unnecessary allocations via deduplication of values, the unique package can also reduce the cost of object comparisons, which can be especially evident when dealing with comparing large strings, structs with string fields or arrays, where the comparison can be reduced to a simple pointer comparison. Let’s take a look.

Below we have a benchmark that repeats a comma-separated string of IPv6 zones and then performs a string comparison on the two identical copies, one benchmark without wrapping the string in a Handle type, the other with.

package main

import (
	"strings"
	"testing"
	"unique"
)

func BenchmarkStringCompareSmall(b *testing.B)  { benchStringComparison(b, 10) }
func BenchmarkStringCompareMedium(b *testing.B) { benchStringComparison(b, 100) }
func BenchmarkStringCompareLarge(b *testing.B)  { benchStringComparison(b, 1000000) }

func BenchmarkCanonicalisingSmall(b *testing.B)  { benchCanonicalising(b, 10) }
func BenchmarkCanonicalisingMedium(b *testing.B) { benchCanonicalising(b, 100) }
func BenchmarkCanonicalisingLarge(b *testing.B)  { benchCanonicalising(b, 1000000) }

func benchStringComparison(b *testing.B, count int) {
	s1 := strings.Repeat("2001:0db8:0001:0000:0000:0ab9:C0A8:0102,", count)
	s2 := strings.Repeat("2001:0db8:0001:0000:0000:0ab9:C0A8:0102,", count)
	b.ResetTimer()
	for n := 0; n < b.N; n++ {
		if s1 != s2 {
			b.Fatal()
		}
	}
	b.ReportAllocs()
}

func benchCanonicalising(b *testing.B, count int) {
	s1 := unique.Make(strings.Repeat("2001:0db8:0001:0000:0000:0ab9:C0A8:0102,", count))
	s2 := unique.Make(strings.Repeat("2001:0db8:0001:0000:0000:0ab9:C0A8:0102,", count))
	b.ResetTimer()
	for n := 0; n < b.N; n++ {
		if s1 != s2 {
			b.Fatal()
		}
	}
	b.ReportAllocs()
}

Benchmark Results

Let’s run the benchmark and check out the results:

$ go test -run='^$' -bench=.

goos: darwin
goarch: arm64
pkg: go-experiment
cpu: Apple M1
BenchmarkStringCompareSmall-8     	116581837	        9.392 ns/op	      0 B/op	      0 allocs/op
BenchmarkStringCompareMedium-8    	14944300	       80.15 ns/op	      0 B/op	      0 allocs/op
BenchmarkStringCompareLarge-8     	903	               1296028 ns/op	      0 B/op	      0 allocs/op

BenchmarkCanonicalisingSmall-8    	1000000000	        0.3132 ns/op	      0 B/op	      0 allocs/op
BenchmarkCanonicalisingMedium-8   	1000000000	        0.3140 ns/op	      0 B/op	      0 allocs/op
BenchmarkCanonicalisingLarge-8    	1000000000	        0.3128 ns/op	      0 B/op	      0 allocs/op

PASS
ok  	go-experiment	5.596s

Running the benchmarks we can see that regardless of the size of the string, the nanoseconds per operation (ns/op) duration is consistently low regardless of whether performing the comparison over a string 10 copies long or 1,000,000, whereas the non-canonicalised version grows relative to the size of the string.

Conclusion

Hopefully, this post has given you enough of an understanding of what the unique package is and the problems it aims to solve. It’s another great package that’s now included as part of Go’s already solid standard library and hopefully in the future if you run into the potential use cases as those discussed above then this post will give you enough of an understanding to reach for interning.

The Problem

Prior to Go 1.20, out of the box options for understanding the reason for a context’s cancellation were limited to two exported errors from the context package, context.DeadlineExceeded or context.Canceled. Though rather simplistic, below is a typical way these errors are commonly checked:

func main() {
    // Pass a context with a timeout to tell a blocking function that it
    // should abandon its work after the timeout elapses.
    timeoutDuration := 3 * time.Second
    ctx, cancel := context.WithTimeout(context.Background(), timeoutDuration)
    defer cancel()

    // block until context is timed out
    <-ctx.Done()

    switch ctx.Err() {
        case context.DeadlineExceeded:
            fmt.Println("context timeout exceeded")
        case context.Canceled:
            fmt.Println("context cancelled by force")
    }
   
   // output:
   // context timeout exceeded
}

For a lot of cases this solution is sufficient, however there are occasions where you wish to provide more “context” as to why the context was canceled, in the form of custom error so developers can introspect it via the errors.Is/As functions to determine, for instance, whether the error is retryable or not.

Similarly when a context is explicitly cancelled by invoking the context.CancelFunc() function (assigned to the cancel variable in the above demonstration) there’s no way to communicate whether this was due to an error or not.

This is the problem the following two accepted proposals aim to address with the addition of a new WithCause API to Go’s context package available in Go 1.20. First by adding context.WithCancelCause and a follow-on proposal to add WithDeadlineCause and WithTimeoutCause to the context package.

Let’s take a look.

Providing context to your context cancellation

Explicit cancellation via WithCancelCause

As demonstrated below, using this new WithCancelCause API available in Go 1.20 allows us to pass a custom error type when cancelling the context. This is then stored on the context for retrieval:

package main

import (
    "context"
    "errors"
    "fmt"
)

var ErrTemporarilyUnavailable = fmt.Errorf("service temporarily unavailable")

func main() {
    ctx, cancel := context.WithCancelCause(context.Background())

    // operation failed, let's notify the caller by cancelling the context
    cancel(ErrTemporarilyUnavailable)

    switch ctx.Err() {
    case context.Canceled:
        fmt.Println("context cancelled by force")
    }

    // get the cause of cancellation, in this case the ErrTemporarilyUnavailable error
    err := context.Cause(ctx)

    if errors.Is(err, ErrTemporarilyUnavailable) {
        fmt.Printf("cancallation reason: %s", err)
    }
    
    // cancallation reason: service temporarily unavailable
}

As an API author we’re now able to provide our consumers with more information as to why the context was canceled, for instance, communicating whether the operation is safe to retry or not.

Timed cancellation with WithDeadlineCause and WithTimeoutCause

In addition to forced cancellation demonstrated above, Go 1.20 will also include the same capabilities with the timed cancellations via WithDeadlineCause and WithTimeoutCause. The main difference being that the timed cause functions, WithDeadlineCause and WithTimeoutCause require you to specify the cause of the cancellation when creating the context, as opposed to when invoking the CancelFunc returned. Let’s take a look:

...

var ErrFailure = fmt.Errorf("request took too long")

func main() {
    timeout := time.Duration(2 * time.Second)
    ctx, _ := context.WithTimeoutCause(context.Background(), timeout, ErrFailure)

    // wait for the context to timeout
    <-ctx.Done()

    switch ctx.Err() {
    case context.DeadlineExceeded:
        fmt.Printf("operation could not complete: %s", context.Cause(ctx))
    }
        
    // operation could not complete: request took too long 
}

And as you’d expect, given the similarities between WithDeadline and WithTimeout the same rules apply to the WithDeadlineCause in that it takes the cancellation cause when creating the context:

...

var ErrFailure = fmt.Errorf("request took too long")

func main() {
    timeout := time.Now().Add(time.Duration(2 * time.Second))
    ctx, _ := context.WithDeadlineCause(context.Background(), timeout, ErrFailure)

    // wait for the context to timeout
    <-ctx.Done()

    switch ctx.Err() {
    case context.DeadlineExceeded:
        fmt.Printf("operation could not complete: %s", context.Cause(ctx))
    }
        
    // operation could not complete: request took too long 
}

Wrapping up

Hopefully you found this post enlightening and the trivial examples adequately demonstrated the challenges the new WithCause changes to the context package coming in Go 1.20 aim to solve. If you have the time I’d highly recommend looking over the original issue that led to this proposal and change, and of course the discussions around the proposal itself.

See you next time!

What is the Structured Logging Proposal?

From a high level (see the proposal itself for a more in-depth look) the proposal aims to address the current gap that exists in Go’s standard library by adding structured logging with levels, residing in a new package with the import path log/slog.

First, what is Structured Logging?

Logs have traditionally been aimed at being human readable. These days it’s common to want to index them to enable better filtering and searching. This can be performed by formatting the log output in a way that makes them machine-readable. This process is called structured logging.

For example, if you’ve used Go’s existing log package then the following code would output a log that looks like the output below:

log.Printf("processed %d items in %s", 23, time.Since(time.Now()))

// Not structured, boo :(
2022/11/10 02:53:02 processed 23 items in 83ns

Its lack of structure makes parsing the output difficult and potentially costly. A better, structured alternative would be the following which adds keys and associated values to the output making parsing it programmatically far easier and more reliable.

// Structured!
time=2022/11/10 02:53:02 msg="processed item" size=23 duration=83ns level=info

Now the logs have a structure associated with them, it’s much easier to encode them as other data formats such as JSON:

{"time":"2022-11-13T03:38:37.737821Z","level":"INFO","msg":"processed items","size":23,"duration":83}

Providing a general interface for logging in Go

A wide variety of structured logging packages exist within the Go ecosystem (Logrus, Zap and Zerolog to name a few), however this diverse API landscape can make supporting logging in a provider agnostic way challenging, often requiring abstractions to avoid coupling your implementation to any given logging package. This proposal would help alleviate this pain by providing a common interface in the standard library that service owners of package authors alike could depend on.

That’s enough talk for now, let’s take a look at the proposed package in a bit more depth.

Logging via the slog package

A Bare Bones Example

Following on from the items processed logging theme above (which is common through examples in the proposal) the slog proposal aims to introduce the following API. We’ll focus on the setup at first and dive into the log writing part later.

package main

import (
     "os"
     "time"

     "golang.org/x/exp/slog"
)

func main() {
    logger := slog.New(slog.NewTextHandler(os.Stdout))
    logger.Info("processed items",
        "size", 23,
        "duration", time.Since(time.Now()))
}

// time=2022-11-10T03:56:11.768Z level=INFO msg="processed items" size=23 duration=42ns

As demonstrated, upon creating a new instance of the slog logger you can pass a type of Handler; an interface whose responsibility is to handle log records produced by a Logger struct type (returned when calling slog.New(...)). The Handler interface is a key piece of the extensibility enabled by the slog package and one we’ll touch towards the end of this post.

In this instance we’ve used the TextHandler for writing the log output as structured text, but a JSONHandler also exists for formatting your structured logs to JSON.

...

logger := slog.New(slog.NewJSONHandler(os.Stdout))
logger.Info("processed items",
    "size", 23,
    "duration", time.Since(time.Now()))
    
// {"time":"2022-11-13T04:08:19.805393Z","level":"INFO","msg":"processed items","size":23,"duration":84}

At this point it’s also valuable to highlight that you can set the logger as the default logger via the SetDefault method call. This will do two things, set the logger as the default when using the slog package. For instance, both of these would output the same log statements:

...

func main() {
    logger := slog.New(&LogrusHandler{
        logger: logrus.StandardLogger(),
    })
    slog.SetDefault(logger)

    logger.Error("something went wrong", net.ErrClosed,
        "status", http.StatusInternalServerError)
    slog.Error("something went wrong", net.ErrClosed,
        "status", http.StatusInternalServerError)
}

// {"err":"use of closed network connection","level":"error","msg":"something went wrong","status":500,"time":"2022-11-24T22:31:06Z"}

Secondly, using slog.SetDefault() will also set the logger as the default logger for the log package. So function calls such as the following will log the expected output:

...
func main() {
    logger := slog.New(&LogrusHandler{
        logger: logrus.StandardLogger(),
    })
    slog.SetDefault(logger)

    log.Print("something went wrong")
    log.Fatalln("something went wrong")
}

//{"level":"info","msg":"something went wrong","time":"2022-11-24T22:33:57Z"}
// {"level":"info","msg":"something went wrong","time":"2022-11-24T22:33:57Z"}
// exit status 1

Logging

Logging via the slog package can be performed in one of two ways, either via the loosely typed API seen above (designed for brevity at the sacrifice of additional allocations), or via a strongly typed but more performance focused alternative seen below, both approaches output the log in the same format.

...

// designed for brevity at the sacrifice of additional allocations
logger.Info("processed items",
    "size", 23,
    "duration", time.Since(time.Now()),

// designed for performance
logger.LogAttrs(slog.InfoLevel, "processed items",
    slog.Int("size", 23),
    slog.Duration("duration", time.Since(time.Now())),

Storing and fetching via context.Context

The slog logger also provides an API to enable you to store and fetch the logger via a context. Note that on the below example, FromContext will actually return a default logger if none exists within the context.

...

func main() {
    logger := slog.New(slog.NewJSONHandler(os.Stdout))

    ctx := context.Background()
    
    // save logger to context.Context
    ctx = slog.NewContext(ctx, logger)
    
    // retrieve logger from context after propagating it throughout your API,
    // If no logger exists then a default logger is returned
    logger = slog.FromContext(ctx)
    logger.Info("processed items",
        "size", 23,
        "duration", time.Since(time.Now()),
    )
}

Whilst propagating objects via a context is somewhat of a contentious point amongst Go developers (and one questioned and discussed on the initial proposal), scoping a logger to a request is a common pattern when logging and as one user commented, advocated within the OTEL (OpenTelemetry) specification, so personally I don’t have an issue with it in this case.

It becomes especially powerful when using the With function (see docs) to attach request level attributes to the returned logger before propagating it further down the call stack like so:

func main() {
    logger := slog.New(slog.NewJSONHandler(os.Stdout))
    http.HandleFunc("/hello", func(w http.ResponseWriter, r *http.Request) {
        // subsequent log entries within this context will contain these fields
        l := logger.
            With("path", r.URL.Path).
            With("user-agent", r.UserAgent())

        // propagate the logger with the above fields via the request context
        ctx := slog.NewContext(r.Context(), l)

        handleRequest(w, r.WithContext(ctx))
    })

    http.ListenAndServe(":8080", nil)
}

func handleRequest(w http.ResponseWriter, r *http.Request) {
    l := slog.FromContext(r.Context())

    l.Info("handling request",
    "status", http.StatusOK)
    
    w.Write([]byte("Hello World"))
}

The above example prints the following log output, allowing you to attach the necessary fields to all log lines. This could include a request/trace ID or any other vital request level information.

{
    "time":"2022-11-16T00:48:43.169545Z",
    "level":"INFO",
    "msg":"handling request",
    "path":"/hello",
    "user-agent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/107.0.0.0 Safari/537.36",
    "status":200
}

Log Handler

At the beginning of this post we looked at how the logger takes an initial dependency on a slog.Handler, for instance when creating a new TextHandler. Let’s spend some time looking at what a handler is and how it provides extensibility to the slog logger.

The Handler is an interface with four methods:

type Handler interface {
    Enabled(Level) bool
    Handle(r Record) error
    WithAttrs(attrs []Attr) Handler
    WithGroup(name string) Handler
}

Other than the Enabled(Level) method (which is used to report whether the logger supports the expected log level), the to most interesting method is Handle(Record), which gets invoked every time a log entry is written to the logger and receives an instance of Record as an argument, which provides all the relevant information of the particular log entry.

By implementing this interface we can create a logger that performs tasks such as batching log entries to send over HTTP, or create an adapter to integrate an existing logger package with slog, so we can make our application or package logging library agnostic.

Building a Logrus adapter for the slog logger

Let’s take a look at what that might look like as we create a slog handler that integrates with Logrus, a popular open source logging library. It’s not production ready but hopefully it gives you an idea of what a custom handler implementation would look like:

type LogrusHandler struct {
    logger logrus.Logger
}

func (h *LogrusHandler) Enabled(_ slog.Level) bool {
    // support all logging levels
    return true
}

func (h *LogrusHandler) Handle(rec slog.Record) error {
    fields := make(map[string]interface{}, rec.NumAttrs())

    rec.Attrs(func(a slog.Attr) {
        fields[a.Key] = a.Value.Any()
    })

    entry := h.logger.WithFields(fields)

    switch rec.Level {
        case slog.DebugLevel:
            entry.Debug(rec.Message)
        case slog.InfoLevel.Level():
            entry.Info(rec.Message)
        case slog.WarnLevel:
            entry.Warn(rec.Message)
        case slog.ErrorLevel:
            entry.Error(rec.Message)
    }

    return nil
}

func (h *LogrusHandler) WithAttrs(attrs []slog.Attr) slog.Handler {
    // not implemented for brevity
    return h
}

func (h *LogrusHandler) WithGroup(name string) slog.Handler {
    // not implemented for brevity
    return h
}

And to use the slog handler we can do something like the following:

package main

import (
    "net"
    "net/http"
    "os"

    "github.com/sirupsen/logrus"
    "golang.org/x/exp/slog"
)

func init() {
    // set up logrus
    logrus.SetFormatter(&logrus.JSONFormatter{})
    logrus.SetOutput(os.Stdout)
    logrus.SetLevel(logrus.DebugLevel)
}

func main() {
    // integrate Logrus with the slog logger
    logger := slog.New(&LogrusHandler{
        logger: logrus.StandardLogger(),
    })

    // start logging via the slog API
    slog.Error("something went wrong", net.ErrClosed,
        "status", http.StatusInternalServerError)
}

Now, whenever we log via the slog logger, our log records will still be handled via Logrus but we’ll no longer need to depend on the Logrus API in our library and we’ll see the following output:

{"err":"use of closed network connection","level":"error","msg":"something went wrong","status":500,"time":"2022-11-19T00:07:51Z"}

Conclusion

Hopefully this post has given you some insight into the slog package proposal, its goals and its potentially. Personally I’m hoping the proposal gets accepted as it’d be great to have structured logging as a first-class citizen in the standard library, but only time will tell.

If you’re interested in learning more then be sure to take a look at the proposal over here and the further discussions here.

Handling errors as part of your HTTP API’s middleware enables the following benefits:

• Centralised location for handling errors
• Reduce boilerplate ‘error to response’ mappings in your request handlers or controller actions
• Helps protect yourself from inadvertently revealing errors to API consumers

A Trivial Example

Let’s take a look at how we can use the Gin Error Handling Middleware package to utilise a more centralised approach to error handling.

First add the package to your application:

go get github.com/JosephWoodward/gin-errorhandling

Let’s take a look at a bare-bones example where we register a custom NotFoundError, mapping it to a 404 (http.StatusNotFound) error.

...

var (
    NotFoundError = fmt.Errorf("resource could not be found")
)

func main() {
    r := gin.Default()

    // Register middleware and specify your errors to handle
    r.Use(
        ErrorHandler(
            Map(NotFoundError).ToStatusCode(http.StatusNotFound),
        ))

    r.GET("/test", func(c *gin.Context) {
        // Return our typed error via Gin's Error function
        c.Error(NotFoundError)
    })

    r.Run()
}

Now when you make an HTTP request to /test you should see the following response:

HTTP/1.1 404 Not Found
Date: Wed, 16 Feb 2022 04:08:50 GMT
Content-Length: 0
Connection: close

Going further

So far we’ve seen how we can use the Gin error handling middleware to translate a custom error into a specific status code. If we still want control over the response body returned to the consumer (we want to return a custom error to the caller for instance) then we can use the ToResponse function which allows us to pass a function literal which passes the gin.Context as an argument:

...

var (
    NotFoundError = fmt.Errorf("resource could not be found")
)

func main() {
    r := gin.Default()
    r.Use(
        ErrorHandler(
            Map(NotFoundError).ToResponse(func(c *gin.Context, err error) {
                c.Status(http.StatusNotFound)
                c.Writer.Write([]byte(err.Error())),
            }),
        ))

    r.GET("/ping", func(c *gin.Context) {
        c.Error(NotFoundError)
    })

    r.Run()
}

In this case the caller receives the following HTTP response to their request to /ping

HTTP/1.1 404 Not Found
Date: Wed, 16 Feb 2022 04:21:37 GMT
Content-Length: 27
Content-Type: text/plain; charset=utf-8
Connection: close

resource could not be found

On Closing

Hopefully this post has adequately demonstrated the advantages of error handling via Gin middleware with Gin Error Handling Middleware. Whilst still in its infancy hopefully the library will prove helpful.

Toxiproxy is a TCP Proxy built by Shopify and written in Go designed for simulating a wide range of network conditions.

Built specifically to work in testing, continuous integration and development environments, Toxiproxy’s strength comes from the fact that it provides a dynamic API that allows you to easily add, remove and configure the type of network conditions you want to test against on the fly.

Toxiproxy comes in two parts:

1. A TCP Proxy written in Go, this acts as a server for proxying TCP traffic between the host machine and the upstream service you wish to simulate network conditions against.
2. A client used for communicating with the Toxiproxy server over HTTP. There are a wide range of Toxiproxy clients available from .NET, Ruby and PHP to Rust, Elixir and Haskell.

Let’s get started

Starting the Toxiproxy server

Before we can begin we need to download and run the Toxiproxy server. You can either run the server in a Docker container (really helpful for automated tests) or directly via an executable.

Head over to the Toxiproxy installation section to find your preferred approach.

Once running you should see the following output in your terminal:

$ INFO[0000] API HTTP server starting                      host=localhost port=8474 version=git

With the Toxiproxy server now running, let’s take a look at writing our first test.

Writing our first tests using Toxiproxy

In this example I’m going to use the TestMain(m *testing.M) function for setup and tearing down Toxiproxy.

Looking at the setup code below you’ll see I first connect to the Toxiproxy server (in our case running on port 8474 as per the above terminal output), then add my first proxy. A proxy is a service you wish to control network conditions for such as PostgreSQL, a Redis cache or an HTTP API.

When creating the client you’ll notice we inform Toxiproxy to listen on localhost:5050. This instructs Toxiproxy to listen on the aforementioned address and proxy any network traffic from port :5050 to whatever is listening on port :8080 (in this case a simple web service)

package main

import (
	toxiproxy "github.com/Shopify/toxiproxy/v2/client"
	"os"
	"testing"
)

var client *toxiproxy.Client

func TestMain(m *testing.M) {
    upstreamService := "localhost:8080"
    listen := "localhost:5050"

    // Connect to the proxy server and create a proxy which we'll configure in individual test methods.
    client = toxiproxy.NewClient("localhost:8474")
    proxy, err := client.CreateProxy("upstream_api", listen, upstreamService)
    if err != nil {
        panic(err)
    }

    // Clean up the proxy once all tests have run
    defer proxy.Delete()

    os.Exit(m.Run())
}

Next we’ll add our test method to simulate latency on the upstream request (Toxiproxy enables you introduce latency on either the upstream or downstream network traffic). We do this by adding what Toxiproxy calls a “Toxic”.

What’s a Toxic?

A Toxic is a network condition such as latency, bandwidth limitation, connection reset etc. There are a number of toxics available out of the box but you can even create your own if desired.

func TestSlowConnection(t *testing.T) {

    // Arrange

    // Use the client to get our proxy configured on test setup
    proxy, err := client.Proxy("upstream_api")
    if err != nil {
        t.Fatalf("fetching proxy 'upstream_api': %v", err)
    }

    // Add a 'toxic' to introduce 3 seconds latency into the upstream request 
    proxy.AddToxic("latency", "latency", "upstream", 1.0, toxiproxy.Attributes{
        "latency": 3000,
    })

    // Delete the proxy after use for test isolation
    defer proxy.RemoveToxic("latency")

    // Act
    start := time.Now()

    // Make our request to our dependant service
    resp, err := http.Get("http://" + proxy.Listen)

    // Assert tab
    if time.Since(start) < 3000*time.Millisecond {
        t.Fatalf("request completed sooner than expected")
    }

    if resp.StatusCode != http.StatusOK {
        t.Fatalf("wanted 200, got %v", resp.StatusCode)
    }
}

As you’ll see from the test code above, first we get the proxy (named upstream_api) we wish to introduce network issues into then we add the latency toxi that introduces latency of 3000 millisecods. We then defer the removal of the toxic to ensure it doesn’t affect subsequent tests using that proxy, then finish up by asserting that our request took the expected length of time to respond.

Wrapping up

Hopefully the above example has provided you with a good introduction to Toxiproxy and how you can use it to create automated tests that verify expected behaviour of services under various network conditions.

In this post I want to go further by demonstrating how you can use this same approach to integration test your Polly policies and how they integrate with the HttpClient.

Note: If you haven’t read my previous post then I would recommend doing so as this post leans a lot on content discussed in it.

Integration testing your Polly policies with HttpClient

One of the more common approaches to configuring your Polly policies with an HttpClient is via the Microsoft.Extensions.Http.Polly package.

This package builds onto of the IHttpClientBuilder interface allowing you to chain Polly policies with the AddPolicyHandler extension method, like so:

The .AddPolicyHandler method takes an async Polly Policy and creates an HttpMessageHandler that gets added to the HttpClient message handler pipeline:

Integration testing a Polly Retry Policy

Using this same approach we can create our HttpClientInterception configuration, but this time use the WithInterceptionCallback(Action<HttpRequestMessage> action) method, which gets executed after every matched request, to perform operations like count the number of retries made (this will include the initial request):

Conclusion

Hopefully this and the previous post have demonstrated just how versatile the HttpClientInterception can be, from stubbing simple requests from dependencies to integration testing Polly policies as I’ve demonstrated above.

This chapter got me thinking a lot about my preference for testing units of behaviour as opposed to implementation details, and as someone that works with a lot of services that communicate via HTTP there’s one particular library that’s helped me time and time again, so much so that I feel deserves its own post.

Introducing HttpClient Interception

From a high level, HttpClient Interception is a .NET Standard library, written in C# that’s designed to intercept server-side HTTP dependencies.

Prior to learning about it the two patterns I most frequently used in order to stub responses from an upstream API were either to create a custom HttpMessageHandler (which would return desired responses/assertions on a given input), or create an interface over an HttpClient. Both approaches tend to be painful (the former being difficult to mock due to lack of an interface and the latter somewhat the same).

HttpClient Interception, the brainchild of Martin Costello, aims to alleviate these pains making Black Box testing code that depends on one or more external HTTP APIs much less intrusive.

Let’s take a look

HttpClient Interception offers a convenient builder pattern over returning a desired response for a given input. Let’s take a look at what a simple test would look like this:

In this example we create an instance of HttpRequestInterceptionBuilder then specify the request we wish to match against and the response we’d like to return. We then register the builder against our HttpClientInterceptionOptions type and use it to create an instance of an HttpClient.

Now any requests that match our builder’s parameters will return the response defined (a 500 response code) without the request leaving the HttpClient.

Missing Registrations

At this point it’s worth calling out the ThrowOnMissingRegistration property.

Setting ThrowOnMissingRegistration to true ensures no request leaves an HttpClient created or modified by HttpClient Interception. This is helpful for ensuring you have visibility over unmatched requests, otherwise leaving ThrowOnMissingRegistration as false could mean your request gets handled by the real upstream service, causing a false positive or having a negative impact on your test without you being aware of it.

Though naturally it all depends on your use case so in some instances this may actually be a desired behaviour so consideration is required.

Matching multiple requests

If you want to stub the response to more than one HTTP request you can register multiple builders like so:

Here I’ve registered two separate endpoints on the same HttpClientInterceptorOptions object which is then used to create our HttpClient. Now requests to any of the two registered endpoints will result in either a Not Found response (404) or an Internal Server Error (500) response.

Creating an HttpMessageHandler

Not all libraries will enable you to use a custom HttpClient, some may only offer you the ability to add a new HttpMessageHandler, thankfully HttpClient Interception can also create an HttpMessageHandler that can be passed to the HttpClient.

For example:

Using HttpClientInterception with ASP.NET Core and IHttpClientFactory.

Now we’ve seen what HttpClient Interception can offer, let’s take a look at how we could use it to test an ASP.NET Core application depends on an upstream API. This example is taken straight from the Sample application within the HttpClient Interception repository.

Imagine we have an application that makes a remote call to GitHub’s API via Refit. This is what the controller action might look like:

To test this we can utilise HttpClient Interception to stub the response from GitHub’s API with the following fixture (based on the common WebApplicationFactory approach documented here).

Notice that when overriding ConfigureWebHost we’re taking advantage of the IHttpMessageHandlerBuilderFilter interface to add an additional HttpMessageHandler (created by HttpClient Interception) to any HttpClient created via the IHttpClientFactory API.

It’s worth noting that you can also register the HttpMessageHandler using the ConfigurePrimaryHttpMessageHandler (see the docs here) method that lives on the IHttpClientBuilder interface.

Now we can easily control the responses from the GitHub API from within our tests, without having to mock any internal implementation details of our application.

On Closing

Hopefully this post has demonstrated just how helpful and versatile HttpClient Interception can be and how it can create maintainable tests that don’t break the moment you change an implementation detail. I’d highly recommend you check it our as this post only scratches the surface of what it can do.

I’d like to close this post with a quote from Kent Beck:

“I get paid for code that works, not for tests, so my philosophy is to test as little as possible to reach a given level of confidence.”

The sun is shining and you’re walking through a wood when you happen upon quiet, desolate road. As you walk along the road you encounter an rather peculiar placed fence running from one side of the road to the other. “This fence has no use” you mutter under your breath as you remove it.

Removing the fence could very well be the correct thing to do, nonetheless you have fallen victim to the principle of Chesterton’s Fence. Before removing something we should first seek to understand the reasoning and rationale for why it was there in the first place:

“In the matter of reforming things, as distinct from deforming them, there is one plain and simple principle; a principle which will probably be called a paradox. There exists in such a case a certain institution or law; let us say, for the sake of simplicity, a fence or gate erected across a road. The more modern type of reformer goes gaily up to it and says, “I don’t see the use of this; let us clear it away.” To which the more intelligent type of reformer will do well to answer: “If you don’t see the use of it, I certainly won’t let you clear it away. Go away and think. Then, when you can come back and tell me that you do see the use of it, I may allow you to destroy it.”

As software developers we love writing code. Coupled with our tendency to want to prove ourselves we are often quick to identify code that we hastily deem as “bad” or “wrong”, especially when diving into an old codebase.

What we sometimes forget is that software isn’t designed and built in a bubble, it’s a bi-product of a series of complex interactions of events and factors.

Instead of jumping to conclusions we should first seek to control our impulse to simplify the things around us and be more cognizant of possible context or history by trying to understand why the ‘fence is positioned across the road’ in the first place. This is especially true for code that looks unusual or out of place. You may actually discover that the unusual approach has a valid reason for why it’s designed the way it is.

Similarly, the Systems Thinking, the Local Rationality Principle when summarised states:

“People do things that make sense to them given their goals, understanding of the situation and focus of attention at that time. Work needs to be understood from the local perspectives of those doing the work”

By going the extra mile you can gain a much deeper understanding of why the code or system you’re working on is build the way it is, what lead the developer to do something a particular way or what conditions they were under that led them choose a particular approach, because learning is not just about understanding new things, but also understanding design decisions and the trade-offs made of existing things.

Since C# 7 and the introduction of the ValueTuple type (freeing up some GC cycles) and tuple deconstruction, things seem to have changed and I’ve noticed more and more libraries and developers utilising them, myself included.

With that in mind I’d like to highlight a couple of creative use cases I’ve seen people using that I’d never considered before:

Tuple constructors

I first learned about this pattern at a recent Jon Skeet talk I attended at the .NET South West meet up I co-organise. Jon was demoing some new C# 8 language features and stopped to talk about how he’d adopted this particular pattern.

Given the following constructor we can make this a little shorter without losing much readability using tuples:

When we look at the lowered version of the code using a tool such as SharpLab, we can see that the Tupled version is lowered to exactly the same syntax as the version before which means there’s no cost in using such a pattern.

Tuple Methods

As you might expect, you can also use the same approach for methods. Again this incurs no additional cost:

Tuple / Deconstructor loops

Another pattern I stumbled upon is using tuples within a loop. For instance given the following dictionary of people, due to KeyValuePair now featuring a Deconstruct method, we can unpack the contents in a few ways.

Traditionally we’d have done this:

With the cost efficiently of the ValueTuple type we can start to get creative:

At this point we can go one further by adding a Deconstruct method in our Person class, allowing us to deconstruct the properties into a tuple:

Benchmarking the above patterns

For peace of mind, let’s benchmark the aforementioned patterns with BenchmarkDotNet to see what impact it has:

|                Method |     Mean |   Error |  StdDev |  Gen 0 | Gen 1 | Gen 2 | Allocated |
|---------------------- |---------:|--------:|--------:|-------:|------:|------:|----------:|
|                  List | 142.9 ns | 2.92 ns | 6.17 ns | 0.0439 |     - |     - |     184 B |
| DeconstructionToTuple | 138.8 ns | 2.21 ns | 2.07 ns | 0.0439 |     - |     - |     184 B |

As you can see they’re pretty much equal in terms of cost, with the added benefit of a more expressive syntax.

Conclusion

Hopefully the patterns highlighted above are as new to you as they were to me, and sparked some more interest in the utility of the ValueTuple type, especially when used in conjunction with KeyValuePair and/or the Deconstruct method. I can only assume we’ll start to see more patterns like this emerge in time as Record types make their way into C#.

What is Simmy and why you should use it?

Simmy is a fault-injection library that integrates with Polly, the popular .NET transient-fault-handling library. Its name comes from the Simian Army toolset, a suite of tools created by engineers at Netflix who recognised that designing a fault tolerant architecture wasn’t enough - you have to exercise it, normalising failure to ensure your system can handle it when it inevitably happens.

This idea isn’t new. Experts in the resiliency engineering field such as Dr. Richard Cook have published multiple papers around this topic whilst studying high-risk sectors (such as traffic control and health care). He summarises failure quite nicely in his Working at the Center of the Cyclone talk when he said:

“You build things differently when you expect them to fail. Failure is normal, the failed state is the normal state”.

Dr. Richard Cook (amongst others in the resiliency engineering industry) propose that in a complex system, failure is the normal state and it’s humans that build mechanisms (either sociologically, organisationally or technically) to ensure systems continue to operate. Without human intervention, failure will happen.

Dr. Richard Cook’s paper How Complex Systems Fail goes further by saying:

“The high consequences of failure lead over time to the construction of multiple layers of defence against failure. These defences include obvious technical components (e.g. backup systems, ‘safety’ features of equipment) and human components (e.g. training, knowledge) but also a variety of organisational, institutional, and regulatory defences (e.g. policies and procedures, certification, work rules, team training). The effect of these measures is to provide a series of shields that normally divert operations away from accidents.”

This shift in perspective is one of the tenants of Chaos Engineering and why Netflix built the Simian Army - to regularly introduce failure in a safe, controlled manner to force their engineers to consider and handle those failures as part of regular, everyday work. So when those failures do happen, they won’t even notice.

With that in mind let’s take a look at how we can use Simmy to regularly test our transient fault-handling mechanisms such as timeouts, circuit breakers and graceful degradations.

Simmy in Action

If you’re familiar with Polly then Simmy won’t take long to pick up as Simmy’s fault injection behaviours are Polly policies, so everything fits together nicely and instantly feels familiar.

Let’s take a look at Simmy’s current failure modes.

Simmy’s Failure Modes

At the time of writing Simmy offers the following types of failure injection policies:

Fault Policy

A fault policy can inject exceptions, or substitute results. This gives you the ability to control the type of result that can be returned.

For instance, the following example causes the chaos policy to throw SocketException with a probability of 5% when enabled.

var fault = new SocketException(errorCode: 10013);

var policy = MonkeyPolicy.InjectFault(
	fault, 
	injectionRate: 0.05, 
	enabled: () => isEnabled()  
	);

Latency Policy

Like Netflix’s Latency Monkey, a latency policy enables you to inject latency into executions such as remote calls before the calls are made.

var policy = MonkeyPolicy.InjectLatency(
	latency: TimeSpan.FromSeconds(5),
	injectionRate: 0.1,
	enabled: () => isEnabled()
	);

Behaviour Policy

Simmy’s Behaviour Policy enables you to invoke any custom behaviour within your system (such as restarting a VM, or executing a custom call or script) before a call is placed.

For instance:

var policy = MonkeyPolicy.InjectBehaviour(
	behaviour: () => KillDockerContainer(), 
	injectionRate: 0.05,
	enabled: () => isEnabled()
	);

A trivial example

Once we’ve defined our chaos policy we can use the standard Polly APIs to wrap our existing Polly policies.

var latencyPolicy = MonkeyPolicy.InjectLatency(
	latency: TimeSpan.FromSeconds(5),
	injectionRate: 0.5,
	enabled: () => isEnabled()
	);

...

PolicyWrap policies = Policy.WrapAsync(timeoutPolicy, latencyPolicy);

In the example above we introduce 5 seconds latency in 50% of our calls, which depending our timeout policy will force timeouts within our application making us more aware of how our application will handle timeouts.

By registering the Simmy policy as the inner most policy means it’ll be invoked just before the outbound call.

Using Polly registries

When implementing Simmy’s chaos policies you can use the aforementioned WrapAsync method but you’ll probably want to implement them with as little change to your existing policy code as possible, this is why I’d recommend using Polly’s PolicyRegistry type. This way you can configure your policies then easily wrap them with your Simmy policies:

// Startup.cs

var policyRegistry = services.AddPolicyRegistry();
policyRegistry["LatencyPolicy"] = GetGetLatencyPolicy();

...

if (env.IsDevelopment())
{
    // Wrap every policy in the policy registry in Simmy chaos injectors.
    var registry = app.ApplicationServices.GetRequiredService<IPolicyRegistry<string>>();
    registry?.AddChaosInjectors();
}

Testing failure modes within integration or end-to-end style tests

Prior to learning about Simmy I used to test Polly policies via unit tests, in a lot of cases this is fine - however when you want to test them these policies part of an integration or end-to-end style test to understand how your application handles slow running requests or times outs things can get a little trickier as it can be hard to replicate these things under an automated test condition.

Using Simmy’s Chaos policies we’re now able to invoke those behaviours from the outside which is where Simmy really shines.

Taking it further

Regularly and reliably testing some of the fault-tolerance patterns in a real world environment (such as staging, or dare I say it - Production!) can be challenging. If you’re on a platform such as Kubernetes then introducing failure into your system can trivial as there are plenty of tools that can do this for you. For anyone else this can be a challenge. Simmy has opened the door to make this so much easier, so much so that at one point we had it enabled in our staging environment to introduce a healthy amount of failure into our application.

As Adrian Cockcroft said in his Managing Failure Modes in Microservice Architectures talk:

“If we change the name from chaos engineering to continuous resilience, will you let us do it all the time in production?”

Wrapping it up

Hopefully this post has demonstrated the value in Simmy. Chaos Engineering is a really interesting area and it’s great to see tools like this appearing to support running experiments in your .NET applications. Hopefully over the next coming years we’ll start to see more tooling emerge, enabling us to introduce failure scenarios into our applications as part of regular work.

What is the global.json file?

For those that might not be familiar the global.json file, here’s an excerpt from the docs:

The global.json file allows you to define which .NET Core SDK version is used when you run .NET Core CLI commands. Selecting the .NET Core SDK is independent from specifying the runtime your project targets. The .NET Core SDK version indicates which versions of the .NET Core CLI tools are used. In general, you want to use the latest version of the tools, so no global.json file is needed.

You can read more about it here, so let’s continue.

Upon stumbling on a project with a global.json file I’d go through the manual process of locating the correct version of the SDK to download then installing it. After a number of times doing this, as most developers would, I decided to remove the friction by creating a .NET Core global tool to automate this process.

The result is the .NET Core Install Global SDK global tool. You can also find it on NuGet here.

Note: Before I continue, a huge thanks to Stuart Lang who was running into the same frustrations, noticed I’d started this tool and contributed a tonne towards it.

.NET Core Install SDK Global Tool

If you want to give it a try you can install the global tool on your machine by running the following command (assuming you’ve got .NET Core installed).

$ dotnet tool install -g installsdkglobaltool

Once installed the global tool has the following features:

Install .NET Core SDK based on global.json file

If you navigate to a folder with a global.json file in it and run the following command:

$ dotnet install-sdk

The global tool will check the contents of the global.json file and download then start the installation of the defined version of the .NET Core SDK.

Install the latest preview of the .NET Core SDK

It’s always fun playing with the latest preview releases of the .NET Core SDK so to save you time finding the latest version you can simply run:

$ dotnet install-sdk --latest-preview

This will download and start the installation of the latest preview version of the .NET Core SDK.

Is this suitable for build/CI environments?

No, certainly not at this moment in time. This global tool has been built with a consumer focus so does not install the SDK in a headless fashion. Instead it launches the install and still gives you the same control you’re used to (such as choosing install location).

If you’re interested in what the whole experience looks like then check out the video below:

Until next time!

As our APIs evolve it’s imperative that we don’t unintentionally break any of these public contracts as this would cause headaches for consumers of our service.

What we need is visibility of intentional or unintentional changes to this contract, this is where approval testing has helped.

What is approval testing?

Approval testing is a method of testing that not many are familiar with. If I were to hypothesise why this is, I’d say it’s because of it narrow application, especially when contrasted to other more common forms of forms of testing.

Assertion testing

We’re all familiar with assertion based testing - you order your test in an arrange, act, assert flow where you first ‘arrange’ the test, then execute the action (act) then ‘assert’ the output.

For instance:

// Arrange
var child1 = 13;
var child2 = 22;

// Act
var age = calculateAge(13, 22);

// Assert
age.ShouldBe(35);

Approval testing

Approval testing follows the same pattern but with one difference; instead of asserting the expected return value given your set of input parameters, you ‘approve’ the output instead.

This slight shift changes your perspective on what a failing test means. In other words, with Approval Testing the failed test doesn’t prove something has broken but instead flags that the given output differs from the previous approved output and needs approving.

Actions speak louder than words so let’s take a look at how we can apply this method of testing to our Open API documents in order to gain visibility of changes to the contract.

Test Setup

In this example I’ll use a simple .NET Core based API that has Swagger setup with Swagger UI. The test will use the Microsoft.AspNetCore.Mvc.Testing package for running our API in-memory. If you’re not familiar with testing this way then be sure to check out the docs if you wanted to try this yourself.

First let’s take a look at our application:

Our ASP.NET Core Application

// ProductController.cs 

[Route("api/[controller]")]
[ApiController]
public class ProductController : ControllerBase
{
    [HttpGet]
    public ActionResult<IEnumerable<ProductViewModel>> Get()
    {
        return new List<ProductViewModel>
        {
            new ProductViewModel {Id = 1, Name = "Product 1"},
            new ProductViewModel {Id = 2, Name = "Product 1"},
            new ProductViewModel {Id = 3, Name = "Product 1"}
        };
    }
}

// Program.cs

public class Program
{
    public static void Main(string[] args)
    {
        CreateWebHostBuilder(args).Build().Run();
    }
    
    public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
        WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>();
}

// ProductViewModel.cs

public class ProductViewModel
{
    public string Name { get; set; }

    public int Id { get; set; }

    public string Description { get; set; }
}

// Startup.cs

public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        ...

        services.AddSwaggerGen(c =>
        {
            c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
        });
        
    }

    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        ...
        
        app.UseSwagger();
        app.UseSwaggerUI(c =>
        {
            c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
        });
    }
}

If we were to launch our API and go to /swagger/v1/swagger.json we should see a json document that includes information about the resources our API exposes.

Now we have a working API, let’s look at our test setup.

Our Test Setup

As mentioned above, our test will use the Microsoft.AspNetCore.Mvc.Testing package for running our API in-memory. Why do we need to run it in-memory? Hold that thought and read on.

We’ll use a simple xunit fixture class that uses WebApplicationFactory<T> to run our API in memory.

// ApiFixture.cs

public class ApiFixture
{
    private readonly WebApplicationFactory<Startup> _fixture;

    public ApiFixture()
    {
        _fixture = new WebApplicationFactory<Startup>();
    }

    public HttpClient Create()
    {
        return _fixture.CreateClient();
    }
}

Now we’ve got our API and infrastructure setup, this is where the magic happens. Below is a simple test that will perform the following:

1. Run our ASP.NET Core API in memory and allow the tests to call it via an HttpClient.
2. Make a GET request to the Open API document (Swagger docs) and parse the content into a string.
3. Call .ShouldMatchApproved() on the string content.

What is ShouldMatchApproved()? Read on…

// OpenApiDocumentTests.cs

public class OpenApiDocumentTests : IClassFixture<ApiFixture>
{
    private readonly ApiFixture _apiFixture;

    public OpenApiDocumentTests(ApiFixture apiFixture)
    {
        _apiFixture = apiFixture;
    }
    
    [Fact]
    public async Task DocumentHasChanged()
    {
        // Arrange
        var client = _apiFixture.Create();

        // Act
        var request = await  client.GetAsync("/swagger/v1/swagger.json");
        var content = await request.Content.ReadAsStringAsync();
        
        // Assert
        content.ShouldMatchApproved();
    }
}

Shouldly and .ShouldMatchApproved()

Shouldly is an open-source assertion testing framework that I frequently use (and as a result, contribute to) that simplifies test assertions.

One assertion method Shouldly provides that sets it apart from others is the .ShouldMatchApproved() extension which hangs off of .NET’s string type. This extension method enables us to easily apply approval based testing to any string. There are other libraries such as ApprovalTests.Net that support more complex use cases, but for this example Shouldly will suffice.

How does .ShouldMatchApproved() work?

Upon executing your test .ShouldMatchApproved() performs the following steps:

1. First it checks to see if an approved text file lives in the expected location on disk.

2. If the aforementioned file exists Shouldly will diff the contents of the file (containing the expected) against the input (the actual) of the test.

3. If ShouldMatchApproved detects a difference between the expected and actual values then it will scan common directories for a supported diff tool (such as Beyond Compare, Win Merge etc, or even VS Code).

4. If it finds a supported difftool it will automatically launch it, prompting you to approve the diffs and save the approved copy to the location described in Step 1.

5. Once approved and saved you can rerun the test and it will pass.

Any changes to your API from this point on will result in a test pass, providing no difference is detected between your test case and the approval file stored locally. If a change is detected then the above process starts again.

One of the powerful aspects of this method of testing is that the approval file is committed to source control, meaning those diffs to the contract are visible to anyone reviewing your changes, whilst also keeping a history of changes to the public contract.

Demo

Along side the source code to the demonstration in this post and the below video, I’ve published quick demonstration on YouTube which you can take a look at. The video starts by first creating our approved document, I then go on to make a change to a model exposed via the Open API document, approve that change then rerun the test again.

It all started a couple of days ago when I found myself browsing through Microsoft’s Logging Abstractions library source code. For those that aren’t familiar with this library the aim of it (as the name suggests) is to provide a set of abstractons over the top of common APIs that have emerged around logging over time (take ILogger for instance).

As I was reading the source code I noticed the library contains an implementation of the common ILogger inferface called NullLogger. “Great!” I thought, “I really don’t like mocking and now I don’t need to mock ILogger anymore!”

Initially I thought this was old news and I’d somehow missed the memo, so I swiftly moved on. But given the number of likes and retweets a tweet of the discovery I made received I thought it would be valuable to write a short post as a nod of its existence for anyone who hasn’t seen it yet.

Logger.Instance

As you can see the implementation of the class is very straight forward, it does nothing at all…

    public class NullLogger : ILogger
    {
        public static NullLogger Instance { get; } = new NullLogger();

        private NullLogger()
        {
        }

        public IDisposable BeginScope<TState>(TState state)
        {
            return NullScope.Instance;
        }

        public bool IsEnabled(LogLevel logLevel)
        {
            return false;
        }

        public void Log<TState>(LogLevel logLevel, EventId eventId, TState state, Exception exception, Func<TState, Exception, string> formatter)
        {
        }
    }

However it does mean that if the project I’m working on depends on this this library (which most on .NET Core will be doing) I can start to use instances of NullLogger instead of mocking ILogger.

It doesn’t stop at ILogger either, there are also implementation of ILogger<T> in there (unsurprisingly called NullLogger<T>) and NullLoggerFactory.

Great, thanks Microsoft!

What is Subcutaneous Testing?

I first learnt about Subcutaneous testing from Matt Davies and Rob Moore’s excellent Microtesting - How We Set Fire To The Testing Pyramid While Ensuring Confidence talk at NDC Sydney. The talk introduces its viewers to various testing techniques and libraries you can use to ensure speed and confidence in your testing strategy whilst avoiding the crippling test brittleness that often ensues.

The term subcutaneous means “situated or applied under the skin”, which translated to an application would mean just under the UI layer.

Why would you want to test under the UI later?

As Martin Fowler highlights in his post on Subcutaneous testing, such a means of testing is especially useful when trying to perform functional tests where you want to exercise end-to-end behaviour whilst avoiding some of the difficulties associated with testing via the UI itself.

Martin goes on to say (emphasis is my own, which we’ll touch on later):

Subcutaneous testing can avoid difficulties with hard-to-test presentation technologies and usually is much faster than testing through the UI. The big danger is that, unless you are a firm follower of keeping all useful logic out of your UI, subcutaneous testing will leave important behaviour out of its test.

Let’s take a look at an example…

Subcutaneous testing an ASP.NET Core application

In previous non-core versions of ASP.NET MVC I used to use a tool called FluentMvcTesting, however with the advent of .NET Core I was keen to see what options were available to create subcutaneous tests whilst leaning on some of the primitives that exist in bootstrapping one’s application.

This investigation ultimately lead me to the solution we’ll discuss shortly via the new .AddControllersAsServices() extension method that can be called via the IMvcBuilder interface.

It’s always nice to understand what these APIs are doing so let’s take a moment to look under the covers of the AddControllersAsServices method:

public static IMvcBuilder AddControllersAsServices(this IMvcBuilder builder)
{
    var feature = new ControllerFeature();
    builder.PartManager.PopulateFeature(feature);
    foreach (Type type in feature.Controllers.Select(c => c.AsType()))
    {
        builder.Services.TryAddTransient(type, type);
    }
    
    builder.Services.Replace(
        ServiceDescriptor.Transient<IControllerActivator, ServiceBasedControllerActivator>());
    
    return builder;
}

Looking at the source code it appears that the AddControllersAsServices() method populates the ControllerFeature.Controllers collection with a list of controllers via the ControllerFeatureProvider (which is indirectly invoked via the PopulateFeature call). The ControllerFeatureProvider then loops through all the “parts” (classes within your solution) looking for classes that are controllers. It does this, among a few other things such as checking to see if the type is public, by looking for anything ending in with the strong “Controller”.

Once the controllers in your application are added to the collection within the ControllerFeature.Controllers collection, they’re then registered as transient services within .NET Core’s IOC container (IServiceCollection).

What does this mean for us and Subcutaneous testing? Ultimately this means we can resolve our chosen controller from the IOC container and in doing so it will resolve any dependencies also registered in the controller, such as services, repositories etc.

Putting it together

First we’ll need to call the AddControllersAsServices() extension method as part of the AddMvc method chains in Startup.cs:

// Startup.cs
public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        ...
        services.AddMvc().AddNewtonsoftJson().AddControllersAsServices();
    }
}

Alternatively if you’ve no reason to resolve controllers directly from your IOC container other than for testing you might prefer to configure it as part of your test infrastructure. A common pattern to do this is to move the MVC builder related method calls into a virtual method so we can override it and call the base method like so:

// Startup.cs
public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        ...
        ConfigureMvcBuilder(services);
    }

    public virtual IMvcBuilder ConfigureMvcBuilder(IServiceCollection services)
    => services.AddMvc().AddNewtonsoftJson();
    }

Now all that’s left to do is create a derived version of Startup.cs which we’ll call TestStartup then call AddControllersAsServices() after setting up MVC.

// TestStartup.cs
public class TestStartup : Startup
{
    public TestStartup(IConfiguration configuration) : base(configuration)
    {
    }

    public override IMvcBuilder ConfigureMvcBuilder(IServiceCollection serviceCollection)
    {
        var services = base.ConfigureMvcBuilder(serviceCollection);
        return services.AddControllersAsServices();
    }
}

We can now start to resolve controllers from the container using the .Host.Services.GetService<T>() method. Putting it in a simple test fixture would look like this:

// SubcutaneousTestFixture.cs
public class SubcutaneousTestFixture
{
    private TestServer _server;

    public T ResolveController<T>() where T : Controller
        => _server.Host.Services.GetService<T>();

    public SubcutaneousTestFixture Run<T>() where T : Startup
    {
        var webHostBuilder = WebHost.CreateDefaultBuilder();
        webHostBuilder.UseStartup<T>();
        webHostBuilder.UseContentRoot(Directory.GetCurrentDirectory());

        _server = new TestServer(webHostBuilder);

        return this;
    }
}

Which can be invoked like so within our test:

// NewsDeletionTests.cs
public class NewsDeletionTests : IClassFixture<SubcutaneousTestFixture>
{
    private readonly SubcutaneousTestFixture _fixture;

    public NewsDeletionTests(SubcutaneousTestFixture fixture)
    {
        _fixture = fixture.Run<TestStartup>();
    }

    ...
}

Now if we want to test our controller actions (using a trivial example here) we now do so without having to go through too much effort associated with end to end testing such as using Selenium:

//DeleteNewsController.cs
[HttpPost]
public async Task<IActionResult> Delete(DeleteNews.Command command)
{
    try
    {
        await _mediator.Send(command);
    }
    catch (ValidationException e)
    {
        return View(new ManageNewsViewModel
        {
            Errors = e.Errors.ToList()
        });
    }

    return RedirectToRoute(RouteNames.NewsManage);
}

// DeleteNewsTests.cs
[Fact]
public void UserIsRedirectedAfterSuccessfulDeletion()
{
    // Arrange
    var controller = _fixture.ResolveController<DeleteNewsController>();

    // Act
    var result = (RedirectToActionResult) controller.Delete(new DeleteNews.Command { Id = 1 });
    
    // Assert
    result.ControllerName.ShouldBe(nameof(NewsController));
    result.ActionName.ShouldBe(nameof(NewsController.Index));
}

[Fact]
public void ErrorsAreReturnedToUser()
{
    // Arrange
    var controller = _fixture.ResolveController<DeleteNewsController>();

    // Act
    var result = (ViewResult) controller.Delete(new DeleteNews.Command { Id = 1 });
    var viewModel = result.Model as DeleteNewsViewModel;

    // Assert
    viewModel?.Errors.Count.ShouldBe(3);
}

At this point we’ve managed to successfully exercise end-to-end behaviour in our application whilst avoiding the difficulties often associated with with hard-to-test UI technologies. At the same time we’ve successfully avoided mocking out dependencies so our tests won’t start breaking when we modify the implementation details.

There are no silver bullets

Testing is an imperfect size and there’s rarely a one size fits all solution. As Fred Brooks put it, “there are no silver bullets”, and this approach is no exception - it has its limitations which, depending on how you architect your application, could affect its viability. Let’s see what they are:

• No HTTP Requests
  As you may have noticed, there’s no HTTP request, which means anything regarding HttpContext

• Request filters No HTTP request also means any global filters you may have will not be invoked.

• ModelState is not set
  As we’re not generating an HTTP request, you’ll notice ModelState validation is not set and would require mocking. To some this may or may not be a problem. Personally as someone that’s a fan of MediatR or Magneto coupled with FluentValidation, my validation gets pushed down into my domain layer. Doing this also means I don’t have to lean on validating my input models using yucky attributes.

Conclusion

Hopefully this post has given you a brief insight as to what Subcutaneous Testing is, the trade offs one has to make and an approach you could potentially use to test your applications in a similar a manner. There are a few approaches out there, but on occasion there are times where I wish to test a behaviour inside of my controller so this can do the trick.

Ultimately Subcutaneous Testing will enable you to test large parts of your application but will still leave you lacking the confidence you’d require in order to push code into production, this is where you could fill in the gaps with tests that exercise the UI.

This post aims to take a look at what those five seemingly innocent words really mean, and hopefully by the end of this post you’ll possibly reconsider using it in future, or at the very least be a little more conscious about its use.

Making assumptions in a world of variability

Often when you hear the aforementioned phrase used it’s usually in the context of making an assertion or justification for the most suitable framework, language or service to be used in a given project. The problem with this is it makes too many assumptions. It’s rare anyone truly knows the full scope and nature of a project upfront until it’s done. You may have read the ten page project specification, or know the domain well, but ask yourself this - how many times have you been working on a project only to have the scope or specification changed underneath you. No one can predict the future, so why use a language that implies unquestionable certainty.

Ultimately building software is about making the right trade offs given the various different constraints and conditions (risks, costs, time to name a few), there are no “right” or “wrong” solutions, just ones that make the appropriate trade offs, this also applies to our tooling.

I’ll leave you with this great tweet from John Allspaw:

"The right tool for the job!" said someone whose assumptions, past experience, motivations, and definition of "job" aren‘t explicit.

— John Allspaw (@allspaw) March 18, 2015

Skipping tests is usually a good practice to get into, but I use the word “usually” here because as with all things in software there sometimes certain constraints or parameters that may well justify doing so. In my case I needed to skip a certain test if I was running on AppVeyor in Linux.

Having done a bit of digging I found two options that would work:

Option 1 - Using the #if preprocessor directive

Depending on your scenario it might be possible to simple use an #if preprocessor directive to include the test. If you’re wishing to exclude a test based on the operating system the test were running on then this may be a solution.

My scenario also involved checking the presence of environmental variables, which I’d rather do through code. This led me to the next approach which I felt was more suitable.

Preferred Option - Leveraging existing XUnit functionality

XUnit already has the ability to skip a test by providing a reason for skipping the test in question via the Skip property that exists within the Fact attribute:

So all we have to do is extend the FactAttribute class and set that property:

Now instead of using the traditional [Fact] attribute, we can use our new IgnoreOnAppVeyorLinuxFact attribute:

Building the new DDD South West website

Since getting involved with organising the DDD South West event last year, one thing that was unanimous around the team of organisers was how we needed a new website. The previous website was a free SharePoint hosted solution that had a number of problems (slow, design could be improved, lots of manual processes, speaker submissions by sending word documents etc), so after last year’s conference I started working on the new DDD South West website, and with the 2018 conference approaching it was a bit of a panic to get it finished in time.

Luckily it was all sorted by the time we opened for speaker submissions (with a bit of JIT development). Surprisingly considering there are very few tests everything has worked without any problems, and what’s more is it’s all open source!

Here’s a screenshot of the before and after, hopefully you’ll agree it’s a large improvement!

Before:

After:

Feel free to check the new website out over at https://dddsouthwest.com, it’s built with all of the usual stuff:

• .NET Core (MVC with MediatR)
• PostgreSQL
• Identity Server 4
• Docker
• Hosted on Linux behind nginx

Migrating my blog from .NET Core 1.x to 2.x.

I’ve been meaning to do this for a while now, and migrating a blog to a major version number when you know there’s lots of breaking changes isn’t something you charge at with gusto. Suffice to say it was painful and I ran into some weird issue where I quickly realised it was easier to just create a new project and start copying things over than to figure out what was going wrong.

I managed to get the website back up and running but still had a lot to fix on the login/admin side of things which uses OAuth and Google sign-in. So whilst the website was functional the admin area (and thus my ability to post) was not. Couple with the finishing the DDD South West website it all took a bit of time.

Anyway, it’s all working now so that’s a relief and I’ve got a few posts lined up.

.NET Oxford Talk - ASP.NET Core 2.0 Razor Deep Dive

A couple of weeks ago I had the pleasure of being invited to the .NET Oxford user group to talk about all of the new features in Razor for ASP.NET Core 2.0. It’s a talk I’ve given a few times before but this time around I was keen to update it with a bit more focus on the newer features in 2.0, such as the ITagHelperComponent interface and Razor Pages.

As a .NET meet up organiser myself, I always enjoy the opportunity to visit other .NET focused meet ups as it’s always interesting to see how they operate, and to meet other .NET developers in the wider UK community. It’s also a great chance to borrow ideas to potentially incorporate into .NET South West.

The talk

Overall I was really happy with the way the talk went (though I do wonder if I harped on about how great Rider is a little too much) with a good number of questions throughout and afterwards. Each talk I give I always try and focus on one habit I’ve noticed I’ve picked up, or wish to improve on when presenting, whether it be talking slower, less or more energy etc. On this occasion it was spend less time looking at the screen behind me and more time focused on, and looking at the audience. Whilst the session wasn’t recorded I was quite conscious of it throughout and feel I did much better than previous sessions.

Closing

All in all it’s been a crazy couple of months and now everything is settling down I’m looking forward to getting back into regularly blogging.

Oh, and on one last note - I’ve been selected to speak at DDD Wales (their first one!) which I’m really looking forward to.

GlobalExceptionHandler.NET in a nutshell
GlobalExceptionHandler.NET hands off ASP.NET Core’s .UseExceptionHandler() endpoint and enables developers to configure HTTP responses (including the status codes) per exception type.

For instance, the following configuration:

app.UseExceptionHandler().WithConventions(x => {
  x.ContentType = "application/json";
  x.ForException<RecordNotFoundException>().ReturnStatusCode(HttpStatusCode.NotFound)
      .UsingMessageFormatter((ex, context) => JsonSerializer(new {
          Message = ex.Message
      }));
});

app.Map("/error", x => x.Run(y => throw new RecordNotFoundException("Record not be found")));

Will result in the following output if a RecordNotFoundException is thrown.

HTTP/1.1 404 Not Found
Date: Sat, 25 Nov 2017 01:47:51 GMT
Content-Type: application/json
Server: Kestrel
Cache-Control: no-cache
Pragma: no-cache
Transfer-Encoding: chunked
Expires: -1
{
  "Message": "Record not be found"
}

Improvements in Version 2

Whilst the initial version of GlobalExceptionHandler.NET was a good start, there were a few features and internal details that I was keen to flesh out and improve, so Version 2 was a pretty big overhaul. Let’s take a look at what’s changed in version 2.

It now extends the UseExceptionHandler() API

The first version of GlobalExceptionHandler.NET had its own implementation of UseExceptionHandler which would catch any exceptions thrown further down the ASP.NET Core middleware stack, there was no real motivation for creating a separate implementation other than I didn’t realise how extensible the UseExceptionHandler API was.

As soon as I realised I could offload some of work to ASP.NET Core I was keen to do so.

Now invoked with WithConventions

Now I was using the UseExceptionHandler() endpoint, I was keen to have a more meaningful fluent approach to integrating with ASP.NET Core, so I ultimately went with a WithConventions() approach as the name felt a lot more natural.

Supports polymorphic types

One problem the previous version of GlobalExceptionHandler.NET had was it couldn’t distinguish between exceptions of the same type. Version 2 will now look down the inheritance tree for the first matching type. To give an example.

Given the following exception type:

public class ExceptionA : BaseException {}

// startup.cs

app.UseExceptionHandler().WithConventions(x => {
  x.ContentType = "application/json";
  x.ForException<BaseException>().ReturnStatusCode(HttpStatusCode.BadRequest)
      .UsingMessageFormatter((e, c) => JsonSerializer(new {
          Message = "Base Exception response"
      }));
});

app.Map("/error", x => x.Run(y => throw new ExceptionA()));

HTTP/1.1 400 Bad Request
Date: Sat, 25 Nov 2017 01:47:51 GMT
Content-Type: application/json
Server: Kestrel
Cache-Control: no-cache
Pragma: no-cache
Transfer-Encoding: chunked
Expires: -1
{
  "Message": "Base Exception response"
}

As the above example will hopefully illustrate, as there is no configured response to ExceptionA GlobalExceptionHandler.NET goes to the next type in the inheritance tree to see if a formatter is specified for that type.

Content Negotiation

GlobalExceptionHandler.NET verion 2 now supports content negotiation via the optional GlobalExceptionHandler.ContentNegotiation.Mvc package.

Once included you no longer need to specify the content type or response serialisation type:

//Startup.cs

public void ConfigureServices(IServiceCollection services)
{
    services.AddMvcCore().AddXmlSerializerFormatters();
}

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    app.UseExceptionHandler().WithConventions(x =>
    {
        x.ForException<RecordNotFoundException>().ReturnStatusCode(HttpStatusCode.NotFound)
            .UsingMessageFormatter(e => new ErrorResponse
            {
                Message = e.Message
            });
    });

    app.Map("/error", x => x.Run(y => throw new RecordNotFoundException("Record could not be found")));
}

Note how we had to include the AddMvcCore service, this is because ASP.NET Core MVC is required in order to take care of content negotiation which is a real shame as it would have been great to enable it without a dependency being required on MVC.

Now when an exception is thrown and the consumer has provided the Accept header:

GET /api/demo HTTP/1.1
Host: localhost:5000
Accept: text/xml

The response will be formatted according to the Accept header value:

HTTP/1.1 404 Not Found
Date: Tue, 05 Dec 2017 08:49:07 GMT
Content-Type: text/xml; charset=utf-8
Server: Kestrel
Cache-Control: no-cache
Pragma: no-cache
Transfer-Encoding: chunked
Expires: -1

<ErrorResponse 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <Message>Record could not be found</Message>
</ErrorResponse>

Wrapping up

Hopefully this has given you a good idea of what you’ll find in version 2 of the GlobalExceptionHandler.NET library. Moving forward there are a few further improvements I’d like to make around organising configuration on a domain by domain basis. And as always, the code is up on GitHub so feel free to take a look.

What is the Serverless framework and what problem does it aim to solve?

Serverless, which I’ll refer to as the Serverless framework to avoid confusion, is a cloud provider agnostic toolkit designed to aid operations around building, managing and deploying serverless components, whether full-blown serverless architectures or disparate functions (or FaaS).

To give a more concrete example, Serverless framework aims to provide developers with an interface that abstracts away the vendor’s cloud specific APIs and configuration whilst simultaneously providing you with additional tooling to be able to test and deploy functions with ease, perfect for rapid feedback or being able to integrate into your CI/CD pipelines.

Let’s take a look.

Getting started with .NET Core and the Serverless Framework

First of all we’re going to need to install the Serverless framework:

$ npm install serverless -g

Next let’s see what Serverless framework templates are currently available:

$ serverless create --help

Note: In addition to the serverless command line argument, sls is a nice short hand equivalent, producing the same results:

$ sls create --help

Template for the service. Available templates:
"aws-nodejs",
"aws-python",
"aws-python3",
"aws-groovy-gradle",
"aws-java-maven",
"aws-java-gradle",
"aws-scala-sbt",
"aws-csharp",
"aws-fsharp",
"azure-nodejs",
"openwhisk-nodejs",
"openwhisk-python",
"openwhisk-swift",
"google-nodejs"

To create our .NET Core template we use the --template command:

$ serverless create --template aws-csharp --name demo

Let’s take a moment to look at the files created by the Serverless framework and go through the more note worthy ones:

$ ls -la
.
..
.gitignore
Handler.cs
aws-csharp.csproj
build.cmd
build.sh
global.json
serverless.yml

Handler.cs
Opening Handler.cs reveals it’s the function that will be invoked in response to an event such as notifications, S3 updates and so forth.

//Handler.cs

[assembly:LambdaSerializer(typeof(Amazon.Lambda.Serialization.Json.JsonSerializer))]
namespace AwsDotnetCsharp
{
    public class Handler
    {
       public Response Hello(Request request)
       {
           return new Response("Go Serverless v1.0! Your function executed successfully!", request);
       }
    }
    ...
}

serverless.yml
This is where the magic happens. The serverless.yml file is your schema which defines the configuration of your Lambda(s) (or Azure functions) and how they interact with your wider architecture. Once configured Serverless framework generates a Cloud Formation template off of the back of this which AWS uses to provision the appropriate infrastructure.

global.json
Open global.json and you’ll notice it’s pinned to version 1.0.4 of the .NET Core framework, this is because as of the time of writing this .NET Core 2.0 isn’t supported, though Amazon have promised support is on its way.

{
  "sdk": {
    "version": "1.0.4"
  }
}

Now, let’s go ahead and create our Lambda.

Creating our .NET Core Lambda

For the purpose of this demonstration we’re going to create a Lambda that’s reachable via HTTP. In order to do this we’re going to need to stand up an API Gateway in front of it. Normally doing this would require logging into the AWS Console and manually configuring an API Gateway, so it’s a perfect example to demonstrate how Serverless framework can take care of all of a lot of heavy lifting.

Let’s head over to our serverless.yml file and scroll down to the following section:

# serverless.yml
functions:
  hello:
    handler: CsharpHandlers::AwsDotnetCsharp.Handler::Hello

#    The following are a few example events you can configure
#    NOTE: Please make sure to change your handler code to work with those events
#    Check the event documentation for details
#    events:
#      - http:
#          path: users/create
#          method: get
#      - s3: ${env:BUCKET}
#      - schedule: rate(10 minutes)
#      - sns: greeter-topic
#      - stream: arn:aws:dynamodb:region:XXXXXX:table/foo/stream/1970-01-01T00:00:00.000
#      - alexaSkill
#      - iot:
#          sql: "SELECT * FROM 'some_topic'"
#      - cloudwatchEvent:
#          event:
#            source:
#              - "aws.ec2"
#            detail-type:
#              - "EC2 Instance State-change Notification"
#            detail:
#              state:
#                - pending
#      - cloudwatchLog: '/aws/lambda/hello'
#      - cognitoUserPool:
#          pool: MyUserPool
#          trigger: PreSignUp

#    Define function environment variables here
#    environment:
#      variable2: value2
...

This part of the serverless.yml file describes the various events that our Lambda should respond to. As we’re going to be using API Gateway as our method of invocation we can remove a large portion of this for clarity, then uncomment the event and its properties pertaining to http:

functions:
  hello:
    handler: CsharpHandlers::AwsDotnetCsharp.Handler::Hello

#    The following are a few example events you can configure
#    NOTE: Please make sure to change your handler code to work with those events
#    Check the event documentation for details
   events:
     - http:
         path: users/create
         method: get

#    Define function environment variables here
#    environment:
#      variable2: value2
...

Creating our .NET Core C# Lambda

Because we’re using HTTP as our method of invocation we need to add the Amazon.Lambda.APIGatewayEvents NuGet package to our Lambda and reference the correct request and return types, we can do that using the following .NET Core CLI command:

$ dotnet add package Amazon.Lambda.APIGatewayEvents

Now let’s open our Handler.cs file and update our Lambda to return the correct response type:

public APIGatewayProxyResponse Hello(APIGatewayProxyRequest request, ILambdaContext context)
{
    // Log entries show up in CloudWatch
    context.Logger.LogLine("Example log entry\n");

    var response = new APIGatewayProxyResponse
    {
        StatusCode = (int)HttpStatusCode.OK,
        Body = "{ \"Message\": \"Hello World\" }",
        Headers = new Dictionary<string, string> {{ "Content-Type", "application/json" }}
    };

    return response;
}

Now we’re set. Let’s move on to deploying our Lambda.

Registering an account on AWS Lambda

If you’re reading this then I assume you already have an account with AWS, if not you’re going to need to head over to their registration page and sign up.

Setting AWS credentials in Serverless framework

In order to enable the Serverless framework to create Lambdas and accommodating infrastructure around our Lambdas we’re going to need to set up our AWS credentials. The Serverless framework documentation does a good job of explaining how to do this, but for those that know how to generate keys in AWS you can set your credentials via the following command:

serverless config credentials --provider aws --key <Your Key> --secret <Your Secret>

Build and deploy our .NET Core Lambda

Now we’re good to go!

Let’s verify our setup by deploying our Lambda, this will give us an opportunity to see just how rapid the feedback cycle can be when using Serverless framework.

At this point if we weren’t using the Serverless framework we’d have to manually package our Lambda up into a .zip file in a certain structure then manually log into AWS to upload our zip and create an infrastructure (in this instance API Gateway in front of our Lambda). But as we’re using the Serverless framework it’ll take care of all of the heavy lifting.

First let’s build our .NET Core Lambda:

$ sh build.sh

or if you’re on Windows:

$ build.cmd

Next we’ll deploy it.

Deploying Lambdas using the Serverless framework is performed using the deploy argument. In this instance we’ll set the output to be verbose using the -v flag so we can see what Serverless framework is doing:

$ serverless deploy -v

Once completed you should see output similar to the following:

$ serverless deploy -v

Serverless: Packaging service...
Serverless: Uploading CloudFormation file to S3...
Serverless: Uploading artifacts...
Serverless: Validating template...
Serverless: Updating Stack...
Serverless: Checking Stack update progress...
CloudFormation - UPDATE_IN_PROGRESS - 
...
CloudFormation - UPDATE_COMPLETE - AWS::CloudFormation::Stack - demo-dev
Serverless: Stack update finished...
Service Information
service: demo
stage: dev
region: us-east-1
api keys:
  None
endpoints:
  GET - https://b2353kdlcc.execute-api.us-east-1.amazonaws.com/dev/users/create
functions:
  hello: demo-dev-hello

Stack Outputs
HelloLambdaFunctionQualifiedArn: arn:aws:lambda:us-east-1:082958828786:function:demo-dev-hello:2
ServiceEndpoint: https://b2353kdlcc.execute-api.us-east-1.amazonaws.com/dev
ServerlessDeploymentBucketName: demo-dev-serverlessdeploymentbucket-1o4sd9lppvgfv

Now if we were to log into our AWS account and navigate to the the Cloud Formation page in the region us-east-1 (see the console output) we’d see that Serverless framework has taken care of all of the heavy lifting in spinning our stack up.

Let’s navigate to the endpoint address returned in the console output which is where our Lambda can be reached.

If all went as expected we should be greeted with a successful response, awesome!

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 28
Connection: keep-alive
Date: Wed, 08 Nov 2017 02:51:33 GMT
x-amzn-RequestId: bb076390-c42f-11e7-89fc-6fcb7a11f609
X-Amzn-Trace-Id: sampled=0;root=1-5a027135-bc15ce531d1ef45e3eed7a9b
X-Cache: Miss from cloudfront
Via: 1.1 3943e81340bd903a74d536bc9599c3f3.cloudfront.net (CloudFront)
X-Amz-Cf-Id: ZDHCvVSR1DAPVUfrL8bU_IuWk3aMoAotdRKBjUIor16VcBPkIiNjNw==

{
  "Message": "Hello World"
}

In addition to invoking our Lambda manually via an HTTP request, we could also invoke it using the following Serverless framework command, where the -l flag will return any log output:

$ serverless invoke -f hello -l

{
    "statusCode": 200,
    "headers": {
        "Content-Type": "application/json"
    },
    "body": "{ \"Message\": \"Hello World\" }",
    "isBase64Encoded": false
}
--------------------------------------------------------------------
START RequestId: bbcbf6a3-c430-11e7-a2e3-132defc123e3 Version: $LATEST
Example log entry

END RequestId: bbcbf6a3-c430-11e7-a2e3-132defc123e3
REPORT RequestId: bbcbf6a3-c430-11e7-a2e3-132defc123e3	Duration: 17.02 ms	Billed Duration: 100 ms 	Memory Size: 1024 MB	Max Memory Used: 34 MB

Making modifications to our Lambda

At this point if we to make any further code changes we’d have to re-run the build script (build.sh or build.cmd depending on your platform) followed by the Serverless framework deploy function command:

$ serverless deploy function -f hello

However if we needed to modify the serverless.yml file then we’d have to deploy our infrastructure changes via the deploy command:

$ serverless deploy -v

The difference being the former is far faster as it will only deploy the source code where as the later will tear down your Cloud Formation stack and stand it back up again reflecting the changes made in your serverless.yml configuration.

Command recap

So, let’s recap on the more important commands we’ve used:

Create our Lambda:

$ serverless create --template aws-csharp --name demo

Deploy our infrastructure and code (you must have built your Lambda before hand using one of the build scripts)

$ serverless deploy -v

Or just deploy the changes to our hello function (again, we need to have built our Lambda as above)

$ serverless deploy function -f hello

At this point we can invoke our Lambda, where -l is whether we want to include log output.

$ serverless invoke -f hello -l

If our commands were written in Python or Node then you could optionally use the invoke local command, however this isn’t available for .NET Core.

$ serverless invoke local -f hello

Once finished with our demo function we can clean up after ourselves using the remove command:

$ serverless remove

Adding more Lambdas

Before we wrapping up, imagine we wanted to add more Lambdas to our project, to do this we can simply add another function name to the functions section of serverless.yml configuration file:

From this:

functions:
  hello:
    handler: CsharpHandlers::AwsDotnetCsharp.Handler::Hello
    events:
     - http:
         path: users/create
         method: get

To this:

functions:
  hello:
    handler: CsharpHandlers::AwsDotnetCsharp.Handler::Hello
    events:
     - http:
         path: users/create
         method: get
  world:
    handler: CsharpHandlers::AwsDotnetCsharp.Handler2::World
    events:
     - http:
         path: users/
         method: get

At this point all we’d need to do is create a new Handler class (for the sake of this demonstration I called it Handler2.cs) and make sure we set the handler property in our serverless.yml configuration appropriately, we’d also need to ensure we set our new Handler2 function name to World as to match the handler address in our serverless configuration.

As the additional function will require its own set of infrastructure we would need to run the build script and then use the following command to regenerate our stack:

$ serverless deploy -v

Once deployed we’re able to navigate to our second function as we do our first.

We can also deploy our functions independent of one another by supplying the appropriate function name when executing the deploy function command:

$ serverless deploy function -f world

Conclusion

Hopefully this post has given you an idea as to how the Serverless framework can help you develop and manage your functions, whether using Azure, AWS, Google or any of the other providers supported.

If you’re interested in learning more about the Serverless framework then I’d highly recommend checking out their documentation (which is plentiful and very well documented).

REST Client for Visual Studio Code

After installing REST Client the first thing I noticed was how elegant it is. Simply create a new tab, paste in your raw HTTP request (ensuring the tab’s Language Mode is set to either HTTP or Plaintext, more on this later) and in no time at all you’ll see a “Send Request” button appear above your HTTP request allowing you to execute the request as is, no further modifications are required to tell REST Client how to parse or format.

Features

To give you a firm grasp of why you should consider adding REST Client to your tool chain, here are a few of the features that particularly stood out to me, organised in an easily consumable list format, because we all like lists:

No BS request building

The easiest form of an HTTP request you can send is to paste in a normal HTTP GET URL like so:

https://example.com/comments/1

Note: You can either paste your requests into a Plaintext window where you’ll need to highlight the request and press the Send Request keyboard shortcut (Ctrl+Alt+R for Windows, or Cmd+Alt+R for macOS) or set the tab’s Language Mode to HTTP where a “Send Request” will appear above the HTTP request.

If you want more control over your request then a raw HTTP request will do:

POST https://example.com/comments HTTP/1.1
content-type: application/json

{
    "name": "sample",
    "time": "Wed, 21 Oct 2015 18:27:50 GMT"
}

Once loaded you’ll see the response appear in a separate pane. A nice detail that I really liked is the ability to hover my cursor over the request timer and get a breakdown of duration details, including times surrounding Socket, DNS, TCP, First Byte and Download.

Saving requests as collections for later use is a simple plain text .http file

Following the theme of low friction elegance, it’s nice that saving requests for later use (or if you want to check them into your component’s source control) are saved as simple plain text documents with an .http file extension.

Break down of requests

One of the gripes I had with Postman was requests separated by tabs. If you had a number of requests you were working with they’d quickly get lost amongst the number of tabs I tend to have open.

REST Client doesn’t suffer the same fate as requests can be grouped in your documents and separated by comments, where three or more hash characters (#) are treated as delimiters between requests by REST Client.

Environments and Variables

REST Client has a concept of Environments and Variables, meaning if you work with different environments (ie QA, Staging and Production), you can easily switch between environments configured in the REST Client settings (see below), changing the set of variables configured without having to modify the requests.

Environments

"rest-client.environmentVariables": {
    "local": {
        "host": "localhost",
        "token": "test token"
    },
    "production": {
        "host": "example.com",
        "token": "product token"
    }
}

Variables

Variables on the other hand allow you to simply define variables in your document and reference them throughout.

@host = localhost:5000
@token = Bearer e975b15aa477ee440417ea069e8ef728a22933f0

GET https://{{host}}/api/comments/1 HTTP/1.1
Authorization: {{token}}

It’s not Electron

I have nothing against Electron, but it’s known to be a big of a resource hog, so much so that I rarely leave Postman open between sessions, where as I’ve always got VS Code (one Electron process is enough) open meaning it’s far easier to dip into to test a few requests.

Conclusion

This post is just a brief overview of some of the features in REST Client, if you’re open to trying an alternative to your current HTTP Request generation tool then I’d highly recommend you check it out, you can read more about it on the REST Client GitHub page.

For anyone that uses a command-dispatcher library such as MediatR, Magneto or Brighter (to name a few), you’ll know that the pattern encourages you to push your domain logic down into a domain library via a handler, encapsulating your app or API’s behaviours such as retrieving an event, like so:

public async Task<IActionResult> Get(int id)
{
    var result = await _mediator.Send(new EventDetail.Query(id));
    return Ok(result);
}

Continuing with the event theme above, within your handler, or in the pipeline before it you’ll take care of all of your validation, throwing an exception if the argument is invalid (in this case, an ArgumentException).

Now when it comes to handling that exception you’re left having to explicitly catch it from each action method:

public async Task<string> Get(int id)
{
    try {
        var result = await _mediator.Send(new EventDetail.Query(id));
        return Ok(result);
    } catch (ArgumentException){
        return BadRequest();
    }
}

Whilst this is perfectly acceptable, I’m always looking at ways I can reduce boiler plate code, and what happens if an exception is thrown somewhere else in the HTTP pipeline This is why I created Global Exception Handler for ASP.NET Core.

What is Global Exception Handler?

Available via NuGet or GitHub, Global Exception Handler lets you configure an exception handling convention within your Startup.cs file, which will catch any of the exceptions specified, outputting the appropriate error response and status code.

Not just for Web API or MVC

Whilst it’s possible to use Global Exception Handler with Web API or MVC, it’s actually framework agnostic meaning as long as it runs, or can run on the ASP.NET Core pipeline (such as BotWin or Nancy) then it should work.

Let’s take a look at how we can use it alongside Web API (though the configuration will be the same regardless of framework).

How do I use Global Exception Handler for an ASP.NET Core Web API project?

To configure Global Exception Handler, you call it via the the UseWebApiGlobalExceptionHandler extension method in your Configure method, specifying the exception(s) you wish to handle and the resulting status code. In this instance a ArgumentException should translate to a 400 (Bad Request) status code:

public class Startup
{
    public void Configure(IApplicationBuilder app, IHostingEnvironment env)
    {
        app.UseWebApiGlobalExceptionHandler(x =>
        {
            x.ForException<ArgumentException>().ReturnStatusCode(HttpStatusCode.BadRequest);
        });

        app.UseMvc();
    }
}

Now when our MediatR pipeline throws an ArgumentException we no longer need to explicitly catch and handle it in every controller action:

public async Task<IActionResult> Get(int id)
{
    // This throws a ArgumentException
    var result = await _mediator.Send(new EventDetail.Query(id));
    ...
}

Instead our global exception handler will catch the exception and handle it according to our convention, resulting in the following JSON output:

{
    "error": {
        "status": 400,
        "message": "Invalid arguments supplied"
    }
}

This saves us in the following three scenarios: - You no longer have to explicitly catch exceptions per method - Those times you forgot to add exception handling will be caught - Enables you to catch any exceptions further up the HTTP pipeline and propagate to a configured result

Not happy with the error format?

If you’re not happy with the default error format then it can be changed in one of two places.

First you can set a global error format via the MessageFormatter method:

Global formatter

public class Startup
{
    public void Configure(IApplicationBuilder app, IHostingEnvironment env)
    {
        app.UseWebApiGlobalExceptionHandler(x =>
        {
            x.ForException<ArgumentException>().ReturnStatusCode(HttpStatusCode.BadRequest);
            x.MessageFormatter(exception => JsonConvert.SerializeObject(new {
                error = new {
                    message = "Something went wrong",
                    statusCode = exception.HttpStatusCode
                }
            }));
        });

        app.UseMvc();
    }
}

Exception specific formatter

Alternatively you can specify a custom message per exception caught, which will override the global one demoed above:

app.UseWebApiGlobalExceptionHandler(x =>
{
    x.ContentType = "text/xml";
    x.ForException<ArgumentException>().ReturnStatusCode(HttpStatusCode.BadRequest).UsingMessageFormatter(
        exception => JsonConvert.SerializeObject(new
        {
            error = new
            {
                message = "Oops, something went wrong"
            }
        }));
    x.MessageFormatter(exception => "This formatter will be overridden when an ArgumentException is thrown");
});

Resulting in the following 400 response:

{
    "error": {
        "message": "Oops, something went wrong"
    }
}

Content type

By default Global Exception Handler is set to output application/json content type, however this can be overridden for those that may prefer to use XML or an alternative format. This can be done via the the ContentType property:

app.UseWebApiGlobalExceptionHandler(x =>
{
    x.ContentType = "text/xml";
    x.ForException<ArgumentException>().ReturnStatusCode(HttpStatusCode.BadRequest)
    x.MessageFormatter(exception => {
        // serialise your XML in here
    });
});

Moving forward

Having used this for a little while now, one suggestion was to implement problem+json as the default content type, standardising the default output which I’m seriously considering. I’m also in the process of building ASP.NET Core MVC compatibility so exceptions can result in views being rendered or requests being redirect to routes (such as a 404 page not found view).

For more information feel free to check out the GitHub page or try it out via Nuget.

Yet Windows has always come up short on delivering a powerful grep experience for searching via a command line, this is where a tool like ripgrep can help you.

Having first heard about ripgrep after a conversation on Twitter, I was made aware of the fact that most people are actively using it without knowing it as ripgrep is what powers Visual Studio Code’s search functionality! (see here)

As someone that’s a heavy user of grep in my day-to-day work flow the first thing that blew me away with ripgrep was its blazing fast speed. Having read its benchmarks that it so proudly displays on its GitHub page, at first I was septical - but ripgrep flies on large recursive searches like no other grepping tool I’ve used.

Let’s take a look.

A bit about ripgrep

Written in Rust, ripgrep is a tool that combines the usability of The Silver Searcher (a super fast ack clone) with the raw performance of GNU. In addition, ripgrep also has first class support for Windows, Mac and Linux (available on their GitHub page), so for anyone who regularly works across multiple platforms and is looking to normalise their tool chain then it’s well worth a look.

Some of ripgrep’s features that sold it to me are: - It’s crazily fast at searching large directories - Ripgrep won’t search files already ignored by your .gitignore file (this can easily be overridden when needed). - Ignores binary or hidden files by default - Easy to search specific file types (making it great for searching for functions or references in code files) - Highlights matches in colour - Full unicode support - First class Windows, Mac and Linux support

Let’s take a look at how we can install ripgrep.

Installation

Mac

If you’re on a Mac using Homebrew then installation is as easy as:

$ brew install ripgrep

Windows

• Download the ripgrep executable from their releases page on GitHub
• Put the executable in a familiar location (c:/tools for instance)
• Add the aforementioned tools path to your PATH environment

Alternatively if you’re using Chocolately then installation is as simple as:

$ choco install ripgrep

Linux

$ yum-config-manager --add-repo=https://copr.fedorainfracloud.org/coprs/carlwgeorge/ripgrep/repo/epel-7/carlwgeorge-ripgrep-epel-7.repo

$ yum install ripgrep

See the ripgrep GitHub page for more installation options.

Usage

Next, let’s take a look at some of the use cases for ripgrep in our day-to-day scenarios.

Recursively search contents of files in current directory, while respecting all .gitignore files, ignore hidden files and directories and skip binary files:

$ rg hello

Search the contents of .html and .css files only for the word foobar using the Type flag (t).

$ rg -thtml -tcss foobar

Or return everything but css files using the Type Not flag (T):

$ rg -Tjs foobar

Returns a list of all .css files

$ rg -g *.css --files

More examples

ripgrep has a whole host of other searching options so I’d highly recommend checking out their GitHub page where they reference more examples.

Conclusion

Hopefully this post has given you a taste of how awesome ripgrep is and encouraged you to at least install it and give it a spin. If you’re someone that spends a lot of time on the command line for day to day navigation then having a powerful grepping tool at your disposal and getting into the habit of using it whenever you need to locate a file really does help your work flow.

Now, go forth an grep with insane speed!

What is GraphQL?

GraphQL is a query language (hence QL in the name) created and open-sourced by Facebook that allows you to query an HTTP (or other protocols for that matter) based API. Let me demonstrate with a simple example:

Say you’re consuming a REST API on the following resource identifier:

GET service.com/user/1

The response returns on this URI is the following JSON object is:

{
    "Id": 1,
    "FirstName": "Richard",
    "Surname": "Hendricks",
    "Gender": "Male",
    "Age": 31,
    "Occupation": "Pied Piper CEO",
    "RoleId": 5,
    ...
}

Now as a mobile app developer calling this service you’re aware of the constraints on bandwidth users face when connected to a mobile network, so returning the whole JSON blob when you’re only interested in their FirstName and Surname properties is wasteful, this is called over-fetching data, GraphQL solves this by letting you as a consumer dictate your data needs, as opposed to having it forced upon you by the service.

This problem is a fundamental requirement that REST doesn’t solve (in fairness to REST, it never set out to solve this problem, however as the internet has changed it’s a problem that does exist).

This is where GraphQL comes in.

Using GraphQL we’re given control as consumers to dictate what our data requirements are, so instead of calling the aforementioned URI, instead we POST a query to a GraphQL endpoint (often /graphql) in the following shape:

{
    Id,
    FirstName,
    Surname
}

Our Web API powered GraphQL server fulfills the request, returning the following response:

{
    "Id": 1,
    "FirstName": "Richard",
    "Surname": "Hendrix"
}

This also applies to under-fetching which can best be described as when you have to make multiple calls to join data (following the above example, retrieving the RoleId only to then call another endpoint to get the Role information). In GraphQL’s case, we could represent that with the following query, which would save us an additional HTTP request:

{
    Id,
    FirstName,
    Surname,
    Role {
        RoleName
    }
}

The GraphQL query language includes a whole host of other functionality including static type checking, query functions and the like so I would recommend checking it out when you can (or stay tuned for a later post I’m in the process of writing where I demonstrate how to set it up in .NET Core).

So what is GraphiQL?

Now you know what GraphQL is, GraphiQL (pronounced ‘graphical’) is a web-based JavaScript powered editor that allows you to query a GraphQL endpoint, taking full advantage of the static type checking and intellisense promised by GraphQL. You can consider it the Swagger of the GraphQL world.

In fact, I’d suggest you taking a moment to go try a live exampe of GraphiQL here and see how GraphQL’s static type system and help you discover data that’s available to you via the documentation and intellisense. GitHub also allow you to query your GitHub activity via their example GraphiQL endpoint too.

Introducing GraphiQL.NET

Traditionally if you wanted to set this up you’d need to configure a whole host of node modules and JavaScript files to enable you to do this, however given .NET Core’s powerful middleware/pipeline approach creating a GraphiQL middleware seemed like the obvious way to enable a GraphiQL endpoint.

Now you no longer need to worry about taking a dependency on Node or NPM in your ASP.NET Core solution and can instead add GraphiQL support via a simple middleware calls using GraphiQL.NET (before continuing I feel it’s worth mentioning all of the code is up on GitHub.

Setting up GraphiQL in ASP.NET Core

You can install GraphiQL.NET by copying and pasting the following command into your Package Manager Console within Visual Studio (Tools > NuGet Package Manager > Package Manager Console).

Install-Package graphiql

Alternatively you can install it using the .NET Core CLI using the following command:

dotnet add package graphiql

From there all you need to do is call the UseGraphiQl(); extension method within the Configure method within Startup.cs, ensuring you do it before your AddMvc(); registration.

public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
{
    app.UseGraphiQl();

    app.UseMvc();
}

Now when you navigate to /graphql you should be greeted with the same familiar GraphiQL screen but without the hassle of having to add node or any NPM packages to your project as a dependency - nice!

The library is still version 1 so if you run into any issues then please do feel free to report them!

What problem does the ITagHelperComponent solve?

Pre .NET Core 2.0, if you’re using a library that comes bundled with some static assets such as JavaScript or CSS, you’ll know that in order to use the library you have to manually add script and/or link tags (including a reference to the files in your wwwroot folder), to your views. This is far from ideal as not only does it force users to jump through additional hoops, but it also runs the risk of introducing breaking changes when a user decides to remove the library and forgets to remove the JavaScript references, or if you update the library version but forget to change the appropriate JavaScript reference.

This is where the ITagHelperComponent comes in; it allows you to inject content into the header or footer of your application’s web page. Essentially, it’s dependency injection for your JavaScript or CSS assets! All that’s required of the user is they register the dependency with their IoC Container of choice within their Startup.cs file.

Enough talk, let’s take a look at how it works. Hopefully a demonstration will clear things up.

Injecting JavaScript or CSS assets into the head or body tags

Imagine we have some JavaScript we’d like to include on each page, this could be from either:

• A JavaScript and/or CSS library we’d like to use (Bootstrap, Pure etc)
• Some database driven JavaScript code or value that needs to be included in the head of your page
• A JavaScript file that’s bundled with a library that our users need to include before the closing </body> tag.

In our case, we’ll keep it simple - we need to include some database drive JavaScript in our page in the form of some Google Analytics JavaScript.

Creating our JavaScript tag helper component

Looking at the contract of the ITagHelperComponent interface you’ll see it’s a simple one:

public interface ITagHelperComponent{
    int Order { get; }
    void Init(TagHelperContext context);
    Task ProcessAsync(TagHelperContext context, TagHelperOutput output);
}

We could implement the interface ourselves, or we could lean on the existing TagHelperComponent base class and override only the properties and methods we require. We’ll do the later.

Let’s start by creating our implementation which we’ll call CustomerAnalyticsTagHelper:

// CustomerAnalyticsTagHelper.cs

CustomerAnalyticsTagHelper : TagHelperComponent {}

For this example the only method we’re concerned about is the ProcessAsync one, though we will touch on the Order property later.

Let’s go ahead and implement it:

// CustomerAnalyticsTagHelper.cs

public class CustomerAnalyticsTagHelper : TagHelperComponent
{
    private readonly ICustomerAnalytics _analytics;

    public CustomerAnalyticsTagHelper(ICustomerAnalytics analytics)
    {
        _analytics = analytics;
    }

    public override Task ProcessAsync(TagHelperContext context, TagHelperOutput output)
    {
        if (string.Equals(context.TagName, "body", StringComparison.Ordinal))
        {
            string analyticsSnippet = @"
            <script>
                (function (i, s, o, g, r, a, m) {
                    i['GoogleAnalyticsObject'] = r; i[r] = i[r] || function () {
                        (i[r].q = i[r].q || []).push(arguments)
                    }, i[r].l = 1 * new Date(); a = s.createElement(o),
                        m = s.getElementsByTagName(o)[0]; a.async = 1; a.src = g; m.parentNode.insertBefore(a, m)
                })(window, document, 'script', '//www.google-analytics.com/analytics.js', 'ga');
                ga('create', '" + _analytics.CustomerUaCode + @"', 'auto')
                ga('send', 'pageview');
            </script>";
            
            output.PostContent.AppendHtmlLine(analyticsSnippet);
        }

        return Task.CompletedTask;
    }
}

As you can see, the TagHelperContext argument gives us context around the tag we’re inspecting, in this case we want to look for the body HTML element. If we wanted to drop JavaScript or CSS into the <head></head> tags then we’d inspect tag name of “head” instead.

The TagHelperOutput argument gives us access to a host of properties around where we can place content, these include:

• PreElement
• PreContent
• Content
• PostContent
• PostElement
• IsContentModified
• Attributes

In this instance we’re going to append our JavaScript after the content located within the <body> tag, placing it just before the closing </body> tag.

Dependency Injection in our tag helper

With dependency injection being baked into the ASP.NET Core framework, we’re able to inject dependencies into our tag helper - in this case I’m injecting our database driven consumer UA (User Analytics) code.

Registering our tag helper with our IoC container

Now all that’s left to do is register our tag helper with our IoC container of choice. In this instance I’m using the build in ASP.NET Core one from the Microsoft.Extensions.DependencyInjection package.

// Startup.cs

public void ConfigureServices(IServiceCollection services)
{
    services.AddSingleton<ICustomerAnalytics, CustomerAnalytics>(); // Data source containing UA code
    services.AddSingleton<ITagHelperComponent, CustomerAnalyticsTagHelper>(); // Our tag helper
    ...
}

Now firing up our tag helper we can see our JavaScript has now been injected in our HTML page without us needing to touch any of our .cshtml Razor files!

...
<body>
    ...
    <script>
        (function (i, s, o, g, r, a, m) {
            i['GoogleAnalyticsObject'] = r; i[r] = i[r] || function () {
                (i[r].q = i[r].q || []).push(arguments)
            }, i[r].l = 1 * new Date(); a = s.createElement(o),
                m = s.getElementsByTagName(o)[0]; a.async = 1; a.src = g; m.parentNode.insertBefore(a, m)
        })(window, document, 'script', '//www.google-analytics.com/analytics.js', 'ga');
        ga('create', 'UA-123456789', 'auto')
        ga('send', 'pageview');
    </script>
</body>
</html>

Ordering our output

If we needed to include more than one script or script file in our output, we can lean on the Order property we saw earlier, overriding this allows us to specify the order of our output. Let’s see how we can do this:

// JsLoggingTagHelper.cs

public class JsLoggingTagHelper : TagHelperComponent
{
    public override int Order => 1;

    public override Task ProcessAsync(TagHelperContext context, TagHelperOutput output)
    {
        if (string.Equals(context.TagName, "body", StringComparison.Ordinal))
        {
            const string script = @"<script src=""/jslogger.js""></script>";
            output.PostContent.AppendHtmlLine(script);
        }

        return Task.CompletedTask;
    }
}

// CustomerAnalyticsTagHelper.cs

public class CustomerAnalyticsTagHelper : TagHelperComponent
{
    ...
    public override int Order => 2; // Set our AnalyticsTagHelper to appear after our logger
    ...
}

// Startup.cs

public void ConfigureServices(IServiceCollection services)
{
    services.AddSingleton<ICustomerAnalytics, CustomerAnalytics>();
    services.AddSingleton<ITagHelperComponent, CustomerAnalyticsTagHelper>();
    services.AddSingleton<ITagHelperComponent, JsLoggingTagHelper>();
    ...   
}

When we we launch our application we should see the following HTML output:

<script src="/jslogger.js"></script>
<script>
    (function (i, s, o, g, r, a, m) {
        i['GoogleAnalyticsObject'] = r; i[r] = i[r] || function () {
            (i[r].q = i[r].q || []).push(arguments)
        }, i[r].l = 1 * new Date(); a = s.createElement(o),
            m = s.getElementsByTagName(o)[0]; a.async = 1; a.src = g; m.parentNode.insertBefore(a, m)
    })(window, document, 'script', '//www.google-analytics.com/analytics.js', 'ga');
    ga('create', 'UA-123456789', 'auto')
    ga('send', 'pageview');
</script>
</body>
</html>

Conclusion

Hopefully this post has highlighted how powerful the recent changes to tag helpers are and how using the ITagHelperComponent interface allows us to inject content into our HTML without having to touch any files. This means as a library author we can ease integration for our users by simply asking them to register a type with their IoC container and we can take care of the rest!

With this in mind, only recently did I spend the time and effort to investigate how easy it was to create and manage a project solution via the CLI, including creating the solution structure, referencing projects along the way and adding them to .NET’s .sln file.

It turns out it’s incredibly easy and has instantly become my preferred way of managing solutions. Hopefully by the end of this post you’ll arrive at the same conclusion too.

Benefits of using the CLI for solution management

So what are the benefits of using the CLI for solution management? Let’s have a look:

• Something that has always been a fiddly endevour of UI interactions is now so much simpler via the CLI - what’s more, you don’t need to open your editor of choice if you want to create references or update a NuGet package.

• Using the CLI for creating projects and solutions is particularly helpful if (like me) you work across multiple operating systems and want to normalise your tool chain.

• Loading an IDE just to update a NuGet package seems unnecessary

Let’s begin!

Creating our solution

So let’s take a look at how we can create the following project structure using the .NET Core CLI.

piedpiper
└── src
    ├── piedpiper.domain
    ├── piedpiper.sln
    ├── piedpiper.tests
    └── piedpiper.website

First we’ll create our solution (.sln) file, I’ve always preferred to create the solution file in the top level source folder but the choice is yours (just bear in mind to specify the right path in the commands used throughout the rest of this post).

# /src/

$ dotnet new sln -n piedpiper

This will create a new sln file called piedpiper.sln.

Next we use the output parameter on the dotnet new <projecttype> command to create a project in a particular folder:

# /src/

$ dotnet new mvc -o piedpiper.website

This will create an ASP.NET Core MVC application in the piedpiper.website folder in the same directory. If we were to look at our folder structure thus far it looks like this:

# /src/

$ ls -la

piedpiper.sln
piedpiper.website

Next we can do the same for our domain and test projects:

# /src/

$ dotnet new classlib -o piedpiper.domain
$ dotnet new xunit -o piedpiper.tests

Adding our projects to our solution

At this point we’ve got a solution file that has no projects referenced, we can verify this by calling the list command like so:

# /src/

$ dotnet sln list

No projects found in the solution.

Next we’ll add our projects to our solution file. Once upon a time doing this involved opening Visual Studio then adding a reference to each project manually. Thankfully this can also be done via the .NET Core CLI.

Now start to add each project with the following command, we do this by referencing the .csproj file:

# /src/

$ dotnet sln add piedpiper.website/piedpiper.website.csproj
$ dotnet sln add piedpiper.domain/piedpiper.domain.csproj
$ dotnet sln add piedpiper.tests/piedpiper.tests.csproj

Note: If you’re using a Linux/Unix based shell you can do this in a single command using a globbing pattern!

# /src/

$ dotnet sln add **/*.csproj

Project `piedpiper.domain/piedpiper.domain.csproj` added to the solution.
Project `piedpiper.tests/piedpiper.tests.csproj` added to the solution.
Project `piedpiper.website/piedpiper.website.csproj` added to the solution.

Now when we call list on our solution file we should get the following output:

# /src/

$ dotnet sln list

Project reference(s)
--------------------
piedpiper.domain/piedpiper.domain.csproj
piedpiper.tests/piedpiper.tests.csproj
piedpiper.website/piedpiper.website.csproj

So far so good!

Adding a project reference to a project

Next up we want to start adding project references to our project, linking our domain library to our website and test library via the dotnet add reference command:

# /src/

$ dotnet add piedpiper.tests reference piedpiper.domain/piedpiper.domain.csproj

Reference `..\piedpiper.domain\piedpiper.domain.csproj` added to the project.

Now if you were to view the contents of your test project we’d see our domain library has now been referenced:

# /src/piedpiper.tests/

$ cat piedpiper.tests/piedpiper.tests.csproj 

<Project Sdk="Microsoft.NET.Sdk">

  ...

  <ItemGroup>
    <ProjectReference Include="..\piedpiper.domain\piedpiper.domain.csproj" />
  </ItemGroup>

</Project>

Next we’ll do the same for our website project, so let’s go to our website folder and run the same command:

# /src/

$ dotnet add piedpiper.website reference piedpiper.domain/piedpiper.domain.csproj

# /src/

$ cat piedpiper.website/piedpiper.website.csproj 

<Project Sdk="Microsoft.NET.Sdk">

  ...

<ItemGroup>
    <ProjectReference Include="..\piedpiper.domain\piedpiper.domain.csproj" />
  </ItemGroup>

</Project>

At this point we’re done!

If we navigate back to our root source folder and run the build command we should see everything build successfully:

$ cd ../

# /src/

$ dotnet build

icrosoft (R) Build Engine version 15.3.388.41745 for .NET Core
Copyright (C) Microsoft Corporation. All rights reserved.

    piedpiper.domain -> /Users/josephwoodward/Desktop/demo/src/piedpiper.domain/bin/Debug/netstandard2.0/piedpiper.domain.dll
    piedpiper.tests -> /Users/josephwoodward/Desktop/demo/src/piedpiper.tests/bin/Debug/netcoreapp2.0/piedpiper.tests.dll
    piedpiper.website -> /Users/josephwoodward/Desktop/demo/src/piedpiper.website/bin/Debug/netcoreapp2.0/piedpiper.website.dll

Build succeeded.

    0 Warning(s)
    0 Error(s)

Time Elapsed 00:00:08.08

Adding a NuGet package to a project or updating it

Before wrapping up, let’s say we wanted to add a NuGet package to one of our projects, we can do this using the add package command.

First navigate to the project you want to add a NuGet package to:

# /src/

$ cd pipedpiper.tests/

$ dotnet add package shouldly

info : Adding PackageReference for package 'shouldly'
...
log  : Installing Shouldly 2.8.3.

Optionally we could specify a version we’d like to install using the version argument:

$ dotnet add package shouldly -v 2.8.2

Updating a NuGet package

Updating a NuGet package to the latest version is just as easy, simply use the same command without the version argument:

dotnet add package shouldly

Conclusion

If you’ve managed to get this far then well done, hopefully by now you’ve realised how easy creating and managing a solution is using the new .NET Core command line interface.

One of the great powers of using the CLI is you can now turn creating the same project structure into a handy bash script which you could alias and reuse!

#!/bin/bash

echo "Enter project name, followed by [ENTER]:"
read projname

echo "Creating solution for $projname"

dotnet new sln -n $projname

dotnet new mvc -o $projname.website
dotnet new classlib -o $projname.domain
dotnet new xunit -o $projname.tests

echo "Adding projects to solution"
dotnet sln add **/*.csproj

echo "Referencing projects"
dotnet add $projname.website reference $projname.domain/$projname.domain.csproj
dotnet add $projname.tests reference $projname.domain/$projname.domain.csproj

Happy coding!

Running a user group isn’t a sail in the park, but it’s not hard or particularly time consuming either. Hopefully this post will provide some valuable information and reassurance to those looking to create and foster a local .NET focused community of people wishing to learn, share, expand their knowledge and meet local developers with similar passions and interests.

1. You can do it

The the very first question that can play through your mind is whether you’re capable of starting and running such a meet up. If you’re having any self-doubts about whether you’re knowledgeable enough to run a user group, or whether you have the confidence to organise it - don’t.

Running a user group is an incredibly rewarding experience that starts off small and grows, as it grows you grow with it. Everyone that attends user groups are there to learn, that also applies to the organiser(s) too. So don’t let any hesitations or self-doubts get in your way.

2. Gauging the interest in a .NET user group

One of the first hurdles you face when starting a user group is trying to gauge the level of interest that exists in your local area.

I’ve found a great way to gauge interest is to simply create a meet up group on the popular user group organising site meetup.com informing people that you’re interested in seeing what the level of interest is like. You can create an event with no date and set the title to “To be announced” then leaving it active for a few months. Meetup.com notifies people with similar interests of the new user group and over time you start to get people joining the group waiting for the first meet to be announced. In the meantime your meet up page has a forum where you can start conversations with some of the new members where you can look for assistance or ask if anyone knows of a suitable venue.

This time is a great opportunity to get to know local developers before the meet up.

3. Having an online presence

When it comes to organising a meet up, websites like meetup.com make the whole process a breeze. The service isn’t free (starting at $9.99 - see more here) but personally I would say it’s worth it in terms of how much effort it saves you. MeetUp provides services such as:

• Posting and announcing meet ups to members
• Sending out regular emails to your user group
• Increases meet up visibility to local developers on the platform
• Semi-brandable pages (though this could be better)
• Ability to link to add sponsors within your meet up page

If you are on a budget then there are free alternatives such as the free tier of EventBrite which you can link to from a website you could set up.

4. Many hands make light work

Starting a meet up requires a lot of work, once the meet up is running the number of hours required to keep it ticking along dramatically reduces. That said, there are times where you may have personal commitments that make it difficult to focus on the meet up - so why not look to see if anyone else is interested in helping?

If you don’t have any close friends or work colleagues that are interested in helping you can mention you’re looking for help on your meet up page discussed previously. There’s also nothing to stop you from talking to members once the meet up is under way to see if anyone is interested in helping out. If you do have people interested in helping then why not create a Slack channel for your group where you can stay organised.

5. The Venue

Next up is the venue, this is often the most challenging part as most venues will require payment for a room. All is not lost though as there are a few options available to you:

• Look for sponsorship to cover the cost of the venue - some companies (such as recruitment companies) are often open to ideas of sponsoring meet ups in one way or another for publicity. Naturally this all depends on your stance around having recruitment companies at your meet up.

• Approach software companies to see if they are interested in hosting the event. Often you’ll find software companies are geared up for hosting meet ups and happy to do so in exchange for interacting with the community (and potentially saving them recruitment costs).

• Small pubs - I know of a few meet up organisers who host at pubs in a back room as the venue are often aware that a few people stay behind to have a few drinks so it works in their favour too.

Ultimately you want to ensure is you have consistency, so talk to the venue to and make it clear that you’re looking for a long-term solution.

6. Speakers

Once you’ve got your venue sorted the next task you face ( and this will be a regular one) is sourcing speakers. Luckily this finding speakers is often reasonably simple and once your meet up becomes established you’ll start to find you have speakers approaching you with interest in giving a talk. I would also recommend looking at other near by meet ups for past speakers and making contact with them via Twitter. Networking at conferences is also a great way of finding potential speakers too.

In addition to the aforementioned suggestions, Microsoft also have a handy Microsoft Evangelists (UK only) for finding Evangelists nearby that are often more than happy to travel to your user group to give a talk.

Finally, encourage attendees of your meet up to give talks. You’re trying to foster a community, so try to drive engagement and ownership by opening up space for short 15 minute lightning talks.

7. Sponsorship / Competitions and Prizes

Once your user group is off the ground I would recommend reaching out to software companies to see if they provide sponsorship for meet ups in the shape of prize licences or extended trials - for instance, JetBrains are well known for their awesome community support programme which I’d highly recommend taking a look at.

Some companies require your meet up to be a certain size, some are more flexible on what they can provide, often being happy to ship swag such as stickers and t-shirts instead which can be given away as prizes during your meet up (though if you’re accepting swag from abroad then do be sure to clarify import tax so you don’t get stung).

Swag and prizes aren’t essential for a meet up, but it’s something worth considering to spice things up a bit.

Go for it

Hopefully this post has given you some ideas if you are considering setting up a meet up. Organising a meet up and running it is an extremely satisfying responsibility and it’s great seeing a community of developers coming together to share knowledge and learn from one another. So what are you waiting for, go for it!

Arrival

Living just two hours’ drive from Reading I decided to drive up early in the morning with fellow Just Eater Stuart Lang who was also giving a talk. After arriving and grabbing our speaker polo shirts we headed to the speaker room to say hello to the other speakers - some of whom I know from previous conferences and through organising DDD South West.

Speakers’ Room

I always enjoying spending time in the speakers’ room. As a relative newcomer to speaking I find it’s a great opportunity to get some tips from more experienced speakers as well as geek out about programming. In addition, I still had some preparation to do so it’s a quiet room where I can refine and tweak my talk slides.

Talk 1 - Goodbye REST; Hello GraphQL by Sandeep Singh

Even though I had preparation to take care of for my post-lunch talk, I was determined to attend Sandeep Singh’s talk on GraphQL as it’s a technology I’ve heard lots about via podcasts and have been interested to learn more. In addition, working at Just Eat where we have a lot of distributed services that are extremely chatty over HTTP - I was interested to see if and where GraphQL could help.

Having met Sandeep Singh for the first time at DDD South West he’s clearly a knowledgeable guy so I was expecting great thing, and he delivered. The talk was very informative and by the end of the talk Sandeep had demonstrated the power of GraphQL (along with well-balanced considerations that need to be made) and answered the majority of questions I had forming in my notes as the talk progressed. It’s definitely sparked my interest in the GraphQL and I’m keen to start playing with it.

My talk - Building a better Web API architecture using CQRS

Having submitted two talks to DDD Reading (this and my Razor Deep Dive I delivered at DDD South West), the one that received the most votes was this talk, a topic and architectural style I’ve been extremely interested in for a number of years now (long before MediatR was a thing!).

Having spoken at DDD Reading before, this year my talk was held in a rather intimidating room called Chicago that seats up to 90 with a stage overlooking the attendees. All in all I was happy with the way the talk went, however I did burn through my slides far faster than I did during practice, luckily though the attendees had plenty of questions so I had plenty of opportunity to answer and expand on them with the remaining time. I’ll chalk this down to experience and learn from it.

I must say that one of my concerns whilst preparing the talk was the split opinions around what CQRS really is, and how it differs to Bertrand Meyer’s formulation of CQS (coincidentally, there was a healthy debate around the definition moments before my talk in the speakers’ room between two speakers well-versed in the area!).

Talk 3 - Async in C# - The Good, the Bad and the Ugly by Stuart Lang

Having worked with Stuart for a year now and known him for slightly longer, it’s clear that his knowledge on async/await is spot on and certainly far deeper than any other developer I’ve met. Having seen a slightly alternative version of his Stuart’s talk delivered internally at Just Eat I was familiar with the narrative, however I was keen to attend to this talk because C#’s async language construct is deep area and one I’m interested in.

Overall the talk went really well with a nice break in the middle allowing for time for questions before moving on (something I may have to try in my talk moving forward).

Conclusion

Overall DDD 12 was an awesome day, I’d love to have attended more talks and spend more time speaking with people but keen to deliver my talk to the best of my ability I had work to be done. None the less after my talk was over it was great catching up with familiar faces and meeting new people (easily one of my favourite parts of a conference as I’m a bit of a chatterbox!).

I’ll close this post with a massive thanks to the event organisers (having helped organise DDD South West this year I have full appreciation for the hard work and time that goes into organising such an event), and also the sponsors - without them the conference would not have been possible.

Until next year!

This post is just a short summary of the highs and lows of organising the conference and the day itself.

Organising the conference

This year I was honoured to be part of the organisation team for DDD South West, and I loved every minute of it. Myself and the other organisers (there were 5 of us in total, some of whom have been organising the conference for well over 5 or 6 years!) would hold regular meetings via Skype, breaking down responsibilities such as sponsorship, catering, speaker related tasks and finance. Initially these meetings were about a month apart, but as the conference drew closer and the pressure started to set in, we would meet weekly.

During the organising of DDD Southwest I’ve gained a true appreciation for the amount of effort conference organisers (especially those that run non-profit events in their spare time, such as those I’ve had the pleasure of working with) put in to organising an event for the community.

On the day everything went as expected with no hiccups, though as I was speaking on the day I was definitely a lot more stressed than I would have been otherwise. After the event we all headed over to the Just Eat offices for an after party, which I’ll cover shortly.

For more information on the day, there are two fantastic write ups by Craig Phillips and Dan Clarke that I’d highly recommend reading.

ASP.NET Core Razor Deep Dive talk

Whilst organising DDD South west 7, I figured why not pile the stress on and submit a few sessions. Last year I caught the speaking bug and this year I was keen to continue to pursue it, so I submitted 3 sessions each on very different subjects and was quite surprised to see the ASP.NET Core Razor Deep Dive was selected. It’s not the sexiest topic to talk about, but non-the-less it was a great opportunity to share some experience and give people information they can take away and directly apply in real life (something I always try to do when putting together a talk).

The talk itself was focused on the new Razor changes and features introduced in ASP.NET Core, why and where you’d use them. The topics included:

• Razor as a view engine and it’s syntax
• Tag helpers and how powerful they are
• Create your own tag helpers for some really interesting use cases - this part was especially great as I could see a lot of people in the audience had the “light bulb” moment. This brings me great joy as I know there’s something they were able to take away from the talk.
• Why Partial Views and Child Actions are limiting
• View Components and how you can use them to create more modular, reusable views
• And finished off with the changes people can expect to see in Razor when ASP.NET Core 2.0 is released (ITagHelperComponents and Razor Pages)

Overall I was really happy with the talk and the turnout. The feedback I received was great, with lots of mentions of the word “engaging” (which as a relatively new speaker still trying to find his own style, is always positive to hear).

DDD South West 7 after party

Once all was done and dusted and the conference drew to a close, a large majority of us took a 5 minute stroll over to the Just Eat offices for an after party where free pizza and beer was on offer for the attendees (Thanks Just Eat!).

After a long day of ensuring the event was staying on track coupled with the stresses of talking, it was great to be able to unwind and enjoy spending time mingling with the various attendees and sponsors, all of whom made the event possible.

Bring on DDD South West 8!

Hopefully by the end of this post you’ll have a firm understanding of the new feature and how it differs in comparison to the Tuple type introduced in .NET 4.

A quick look at tuple types as a language feature

Prior to C# 7, .NET’s tuples were an awkward somewhat retrofitted approach to what’s a powerful language feature. As a result you don’t see them being used as much as they are in other language like Python or to some extend Go (which doesn’t support Tuples, but has many features they provide such as multiple return values) - with this in mind it behoves me to briefly explain what Tuples are and why you’d use them for those that may not have touched them before.

So what are Tuples and where you would use them?

The tuples type’s main strengths lie in allowing you to group types into a closely related data structure (much like creating a class to represent more than one value), this means they’re particularly useful in cases such as returning more than one value from a method, for instance:

public class ValidationResult {
    public string Message { get; set; }
    public bool IsValid { get; set; }
}

var result = ValidateX(x);
if (!result.IsValid)
{
    Logger.Log(Error, result.Message);
}

Whilst there’s nothing wrong with this example, sometimes we don’t want to have to create a type to represent a set of data - we want types to work for us, not against us; this is where the tuple type’s utility is.

In fact, in a languages such as Go (which allow multiple return types from a function) we see such a pattern used extensively throughout their standard library.

bytes, err := ioutil.ReadFile("file.json")
if err != nil {
    log.Fatal(err)
}

Multiple return types can also stop you from needing to use the convoluted TryParse method pattern with out parameters.

Now we’ve got that covered and we’re all on the same page, let’s continue.

In the beginning there was System.Tuple

Verbosity
Back in .NET 4 we saw the appearance of the System.Tuple<T> class which introduced a verbose and somewhat awkward API:

var person = new Tuple<string, int>("John Smith", 43);
Console.WriteLine($"Name: {person.Item1}, Age {person.Item2}");
// Output: Name: John Smith, Age: 43

Alternatively there’s a static factory method that cleared things up a bit:

var person = Tuple.Create("John Smith", 43);

But there was still room for improvement such as:

No named elements
One of the weaknesses of the System.Tuple type is that you have to refer to your elements as Item1, Item2 etc instead of by their ‘named’ version (allowing you to unpack a tuple and reference the properties directly) like you can in Python:

name, age = person_tuple
print name

Garbage collection pressure
In addition the System.Tuple type is a reference type, meaning you pay the penalty of a heap allocation, thus increasing pressure on the garbage collector.

public class Tuple<T1> : IStructuralEquatable, IStructuralComparable, IComparable

Nonetheless the System.Tuple type scratched an itch and solved a problem, especially if you owned the API.

C# 7 Tuples to the rescue

With the introduction of the System.ValueTuple type in C# 7, a lot of these problems have been solved (it’s worth mentioning that if you want to use or play with the new Tuple type you’re going to need to download the following NuGet package.

Now in C# 7 you can do such things as:

Tuple literals

// This is awesome and really clears things up; we can even directly reference the named value!

var person = (Name: "John Smith", Age: 43);
Console.WriteLine(person.Name); // John Smith

Tuple (multiple) return types

(string, int) GetPerson()
{
    var name = "John Smith";
    var age = 32;
    return (name, age);
}

var person = GetPerson();
Console.WriteLine(person.Item1); // John Smith

Even named Tuple return types!

(string Name, int Age) GetPerson()
{
    var name = "John Smith";
    var age = 32;
    return (name, age);
}

var person = GetPerson();
Console.WriteLine(person.Name); // John Smith

If that wasn’t enough you can also deconstruct types:

public class Person
{
    public string Name => "John Smith";
    public int Age => 43;

    public void Deconstruct(out string name, out int age)
    {
        name = Name;
        age = Age;
    }
}

...

var person = new Person();
var (name, age) = person;

Console.WriteLine(name); // John Smith

As you can see the System.ValueTuple greatly improves on the older version, allowing you to write far more declarative and succinct code.

It’s a value type, baby!
In addition (if the name hadn’t given it away!) C# 7’s Tuple type is now a value type, meaning there’s no heap allocation and one less de-allocation to worry about when compacting the GC heap. This means the ValueTuple can be used in the more performance critical code.

Now going back to our original example where we created a type to represent the return value of our validation method, we can delete that type (because deleting code is always a great feeling) and clean things up a bit:

var (message, isValid) = ValidateX(x);
if (!isvalid)
{
    Logger.Log(Log.Error, message);
}

Much better! We’ve now got the same code without the need to create a separate type just to represent our return value.

C# 7 Tuple’s limitations

So far we’ve looked at what makes the ValueTuple special, but in order to know the full story we should look at what limitations exist so we can make an educated descision on when and where to use them.

Let’s take the same person tuple and serialise it to a JSON object. With our named elements we should expect to see an object that resembles our tuple.

var person = (Name: "John", Last: "Smith");
var result = JsonConvert.SerializeObject(person);

Console.WriteLine(result);
// {"Item1":"John","Item2":"Smith"}

Wait, what? where have our keys gone?

To understand what’s going on here we need to take a look at how ValueTuples work.

How the C# 7 ValueTuple type works

Let’s take our GetPerson method example that returns a named tuple and check out the de-compiled source. No need to install a de-compiler for this, a really handy website called tryroslyn.azurewebsites.net will do everything we need.

// Our code
using System;
public class C {
    public void M() {
        var person = GetPerson();
        Console.WriteLine(person.Name + " is " + person.Age);
    }
    
    (string Name, int Age) GetPerson()
    {
        var name = "John Smith";
        var age = 32;
        return (name, age);
    }
}

You’ll see that when de-compiled, the GetPerson method is simply syntactic sugar for the following:

// Our code de-compiled
public class C
{
    public void M()
    {
        ValueTuple<string, int> person = this.GetPerson();
        Console.WriteLine(person.Item1 + " is " + person.Item2);
    }
    [return: TupleElementNames(new string[] {
        "Name",
        "Age"
    })]
    private ValueTuple<string, int> GetPerson()
    {
        string item = "John Smith";
        int item2 = 32;
        return new ValueTuple<string, int>(item, item2);
    }
}

If you take a moment to look over the de-compiled source you’ll see two areas of particular interest to us:

First of all, our Console.WriteLine() method call to our named elements have gone and been replaced with Item1 and Item2. What’s happened to our named elements? Looking further down the code you’ll see they’ve actually been pulled out and added via the TupleElementNames attribute.

...
[return: TupleElementNames(new string[] {
    "Name",
    "Age"
})]
...

This is because the ValueTuple type’s named elements are erased at runtime, meaning there’s no runtime representation of them. In fact, if we were to view the IL (within the TryRoslyn website switch the Decompiled dropdown to IL), you’ll see any mention of our named elements have completely vanished!

IL_0000: nop // Do nothing (No operation)
IL_0001: ldarg.0 // Load argument 0 onto the stack
IL_0002: call instance valuetype [System.ValueTuple]System.ValueTuple`2<string, int32> C::GetPerson() // Call method indicated on the stack with arguments
IL_0007: stloc.0 // Pop a value from stack into local variable 0
IL_0008: ldloc.0 // Load local variable 0 onto stack
IL_0009: ldfld !0 valuetype [System.ValueTuple]System.ValueTuple`2<string, int32>::Item1 // Push the value of field of object (or value type) obj, onto the stack
IL_000e: ldstr " is " // Push a string object for the literal string
IL_0013: ldloc.0 // Load local variable 0 onto stack
IL_0014: ldfld !1 valuetype [System.ValueTuple]System.ValueTuple`2<string, int32>::Item2 // Push the value of field of object (or value type) obj, onto the stack
IL_0019: box [mscorlib]System.Int32 // Convert a boxable value to its boxed form
IL_001e: call string [mscorlib]System.String::Concat(object, object, object) // Call method indicated on the stack with arguments
IL_0023: call void [mscorlib]System.Console::WriteLine(string) // Call method indicated on the stack with arguments
IL_0028: nop  // Do nothing (No operation)
IL_0029: ret  // Return from method, possibly with a value

So what does that mean to us as developers?

No reflection on named elements

The absence of named elements in the compiled source means that it’s not possible to use reflection to get those name elements via reflection, which limits ValueTuple’s utility.

This is because under the bonnet the compiler is erasing the named elements and reverting to the Item1 and Item2 properties, meaning our serialiser doesn’t have access to the properties.

I would highly recommend reading Marc Gravell’s Exploring tuples as a library author post where he discusses a similar hurdle when trying to use tuples within Dapper.

No dynamic access to named elements

This also means when casting your tuple to a dynamic object results in the loss of the named elements. This can be witnessed by running the following example:

var person = (Name: "John", Last: "Smith");
var dynamicPerson = (dynamic)person;
Console.WriteLine(dynamicPerson.Name);

Results in the following error RuntimeBinder exception:

Unhandled Exception: Microsoft.CSharp.RuntimeBinder.RuntimeBinderException: 'System.ValueTuple<string,string>' does not contain a definition for 'Name'
   at CallSite.Target(Closure , CallSite , Object )
   at CallSite.Target(Closure , CallSite , Object )
   at TupleDemo.Program.Main(String[] args) in /Users/josephwoodward/Dev/TupleDemo/Program.cs:line 16

Thanks to Daniel Crabtree’s post for highlighting this!

No using named Tuples in Razor views either (unless they’re declared in your view)

Naturally the name erasure in C# 7 tuples also means that you cannot use the names in your view from your view models. For instance:

public class ExampleViewModel {

    public (string Name, int Age) Person => ("John Smith", 30);

}

public class HomeController : Controller
{
    ...
    public IActionResult About()
    {
        var model = new ExampleViewModel();

        return View(model);
    }
}

// About.cshtml
@model TupleDemo3.Models.ExampleViewModel

<h1>Hello @Model.Person.Name</h1>

Results in the following error:

'ValueTuple<string, int>' does not contain a definition for 'Name' and no extension method 'Name' accepting a first argument of type 'ValueTuple<string, int>' could be found (are you missing a using directive or an assembly reference?)

Though switching the print statement to @Model.Person.Item1 outputs the result you’d expect.

Conclusion

That’s enough about Tuples for now. Some of the examples used in this post aren’t approaches you’d use in real life, but hopefully go to demonstrate some of the limitations of the new type and where you can and can’t use C# 7’s new ValueTuple type.

Setting up and configuring a Selenium Grid has never been an simple process, but thanks to Docker it’s suddenly got a whole lot easier. In addition, you’re now able to run your own Selenium Grid locally and greatly speed up your tests’ execution. If that isn’t enough then another benefit is because the tests execute inside of a Docker container, you’ll no longer be blocked by your browser navigating the website you’re testing!

Let’s take a look at how this can be done.

Note: For the impatient, I’ve put together a working example of the following post in a GitHub repository you can clone and run.

Selenium Grid Docker Compose file

For those that haven’t touched Docker Compose (or Docker for that matter), a Docker Compose file is a Yaml based configuration document (often named docker-compose.yml) that allows you to configure your applications’ Docker environment.

Without Docker Compose you’d need to manually run your individual Dockerfile files specifying their network connections and configuration parameters along the way. With Docker Compose you can configure everything in a single file and start your environment with a simple docker-compose up command.

Below is the Selenium Grid Docker Compose configuration you can copy and paste:

# docker-compose.yml

version: '2'
services:
    selenium_hub:
        image: selenium/hub:3.0.1-aluminum
        container_name: selenium_hub
        privileged: true
        ports:
            - 4444:4444
        environment:
            - GRID_TIMEOUT=120000
            - GRID_BROWSER_TIMEOUT=120000
        networks:
            - selenium_grid_internal

    nodechrome1:
        image: selenium/node-chrome-debug:3.0.1-aluminum
        privileged: true
        depends_on:
            - selenium_hub
        ports:
            - 5900
        environment:
            - no_proxy=localhost
            - TZ=Europe/London
            - HUB_PORT_4444_TCP_ADDR=selenium_hub
            - HUB_PORT_4444_TCP_PORT=4444
        networks:
            - selenium_grid_internal

    nodechrome2:
        image: selenium/node-chrome-debug:3.0.1-aluminum
        privileged: true
        depends_on:
            - selenium_hub
        ports:
            - 5900
        environment:
            - no_proxy=localhost
            - TZ=Europe/London
            - HUB_PORT_4444_TCP_ADDR=selenium_hub
            - HUB_PORT_4444_TCP_PORT=4444
        networks:
            - selenium_grid_internal

networks:
    selenium_grid_internal:

In the above Docker Compose file we’ve defined our Selenium Hub (selenium_hub) service, exposing it on port 4444 and attaching it to a custom network named selenium_grid_internal (which you’ll see all of our nodes are on).

selenium_hub:
    image: selenium/hub:3.0.1-aluminum
    container_name: selenium_hub
    privileged: true
    ports:
        - 4444:4444
    environment:
        - GRID_TIMEOUT=120000
        - GRID_BROWSER_TIMEOUT=120000
    networks:
        - selenium_grid_internal

All that’s remaining at this point is to add our individual nodes. In this instance I’ve added two Chrome based nodes, named nodechrome1 and nodechrome2:

nodechrome1:
    image: selenium/node-chrome-debug:3.0.1-aluminum
    privileged: true
    depends_on:
        - selenium_hub
    ports:
        - 5900
    environment:
        - no_proxy=localhost
        - TZ=Europe/London
        - HUB_PORT_4444_TCP_ADDR=selenium_hub
        - HUB_PORT_4444_TCP_PORT=4444
    networks:
        - selenium_grid_internal

nodechrome2:
    image: selenium/node-chrome-debug:3.0.1-aluminum
    ...

Note: If you wanted to add Firefox to the mix then you can replace the image: value with the following Docker image:

nodefirefox1:
    image: selenium/node-firefox-debug:3.0.1-aluminum
    ...

Now if we run docker-compose up you’ll see our Selenium Grid environment will spring into action.

To verify everything is working correctly we can navigate to http://0.0.0.0:4444 in our browser where we should be greeted with the following page:

Connecting Selenium Grid from .NET Core

At the time of writing this post the official Selenium NuGet package does not support .NET Standard, however there’s a pending pull request which adds support (the pull request has been on hold for a while as the Selenium team wanted to wait for the tooling to stabilise). In the mean time the developer that added support released it as a separate NuGet package which can be downloaded here.

Alternatively just create the following .csproj file and run the dotnet restore CLI command.

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>netcoreapp1.0</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="15.0.0-preview-20170123-02" />
    <PackageReference Include="xunit" Version="2.2.0-beta5-build3474" />
    <PackageReference Include="xunit.runner.visualstudio" Version="2.2.0-beta5-build1225" />
    <PackageReference Include="CoreCompat.Selenium.WebDriver" Version="3.2.0-beta003" />
  </ItemGroup>

</Project>

Next we’ll create the following base class that will create a remote connection to our Selenium Grid:

public abstract class BaseTest
{
    private IWebDriver _driver;

    public IWebDriver GetDriver()
    {
        var capability = DesiredCapabilities.Chrome();
        if (_driver == null){
            _driver = new RemoteWebDriver(new Uri("http://0.0.0.0:4444/wd/hub/"), capability, TimeSpan.FromSeconds(600));
        }

        return _driver;
    }
}

After that we’ll create a very simple (and trivial) test that checks for the existence of an ID on google.co.uk.

public class UnitTest1 : BaseTest 
{

    [Fact]
    public void TestForId()
    {
        using (var driver = GetDriver())
        {
            driver.Navigate().GoToUrl("http://www.google.co.uk");
            var element = driver.FindElement(By.Id("lst-ib"));
            Assert.True(element != null);
        }
    }

    ...

}

Now if we run our test (either via the dotnet test CLI command or from your editor or choice) we should see our Docker terminal console showing our Selenium Grid container jump into action as it starts executing the test one one of the registered Selenium Grid nodes.

At the moment we’re only executing the one test so you’ll only see one node running the test, but as you start to add more tests across multiple classes the Selenium Grid hub will start to distribute those tests across its cluster of nodes, dramatically increasing your test execution time.

If you’d like to give this a try then I’ve added all of the source code and Docker Compose file in a GitHub repository that you can clone and run.

The drawbacks

Before closing there are a few drawbacks to this method of running tests, especially if you’re planning on doing it locally (instead of setting a grid up on a Virtual Machine via Docker).

Debugging is made harder
If you’re planning on using Selenium Grid locally then you’ll lose the visibility of what’s happening in the browser as the tests are running within a Docker container. This means that in order to see the state of the web page on a failing test you’ll need to switch to local execution using the Chrome / FireFox or Internet Explorer driver.

Reaching localhost from within a container
In this example we’re executing the tests against an external domain (google.co.uk) that our container can resolve. However if you’re planning on running tests against a local development environment then there will be some additional Docker configuration required to allow the container to access the Docker host’s IP address.

Conclusion

Hopefully this post has broadened your options around Selenium based testing and demonstrated how pervasive Docker is becoming. I’m confident that the more Docker (and other container technology for that matter) matures, the more we’ll see said technology being used for such use cases as we’ve witnessed in this post.

After a bit of digging I quickly realised there weren’t any places that summarised all of the options available, so I thought I’d summarise it all in a post.

Enough talk, let’s begin.

Don’t set an IP

The first approach is to not specify any IP address (this means removing the .NET Core CLI template convention of using the .UseUrls() method. Without it the web host will listen on localhost:5000 by default.

Whilst this approach is far from ideal, it is an option so deserves a place here.

Hard-coded approach via .UseUrls()

As I alluded to earlier, the default approach that .NET Core’s CLI uses is to hard-code the IP address in your application’s program.cs file via the UseUrls(...) extension method that’s available on the IWebHostBuilder interface.

If you take a look at the UseUrls extension method’s signature you’ll see the argument is an unbounded string array allowing you to specify more than one IP address that the web host will listen on (which may be preferable to you depending on your development machine, network configuration or preference as specifying more than one host address can save people running into issues between localhost vs 0.0.0.0 vs 127.0.0.1).

public static IWebHostBuilder UseUrls(this IWebHostBuilder hostBuilder, params string[] urls);

Adding multiple IP addresses can either be done by comma-separated strings, or a single string separated by a semi-colon; both result in the same configuration.

var host = new WebHostBuilder()
    .UseConfiguration(config)
    .UseKestrel()
    .UseUrls("http://0.0.0.0:5000", "http://localhost:5000")
    ///.UseUrls("http://0.0.0.0:5000;http://localhost:5000") also works
    .UseContentRoot(Directory.GetCurrentDirectory())
    .UseIISIntegration()
    .UseStartup<Startup>()
    .Build();

If you’d rather not explicitly list every IP address to listen on you can use a wildcard instead resulting in the web host binding to all IPv4 and IPv6 IPs addresses on port 5000:

.UseUrls("http://*:5000")

A bit about wildcards: The wildcard is not special in any way, in fact anything not recognised as an IP will be bound to all IPv4 or IPv6 addresses, so http://@£$%^&*:5000 is considered the same as "http://*:5000" and vice versa.

Whilst this hard-coded approach makes it easy to get your application up and running, the very fact that it’s hard-coded does make it difficult to configure externally via automation such as a continuous integration/deployment pipeline.

Note: It’s worth mentioning that setting a binding IP address directly on the WebHost as we are in this approach always takes preference over any of the other approaches listed in this post, but we’ll go into this later.

Environment variables

You can also specify the IP your application listens on via an environment variable. To do this first you’ll need to download the Microsoft.Extensions.Configuration package from NuGet then call the AddEnvironmentVariables() extension method on your ConfigurationBuilder object like so:

public static void Main(string[] args)
{
    var config = new ConfigurationBuilder()
        .AddEnvironmentVariables()
        .Build();

    var host = new WebHostBuilder()
        .UseKestrel()
        .UseContentRoot(Directory.GetCurrentDirectory())
        .UseConfiguration(config)
        .UseStartup<Startup>()
        .Build();

    host.Run();
}

Now if you were to set the following environment variable and run your application it will listen to the IP address specified:

ASPNETCORE_URLS=https://*:5123

Command line argument

The another option available is to supply the host name and port via a command line argument when your application’s initially executed (notice how you can use one or more addresses as we did above).

dotnet run --urls "http://*:5000;http://*:6000"

or

dotnet YourApp.dll --urls "http://*:5000;http://*:6000"

Before you can use command line arguments, you’re going to need the Microsoft.Extensions.Configuration.CommandLine package and update your Program.cs bootstrap configuration accordingly:

public static void Main(string[] args)
{
    var config = new ConfigurationBuilder()
        .AddCommandLine(args)
        .Build();

    var host = new WebHostBuilder()
        .UseKestrel()
        .UseContentRoot(Directory.GetCurrentDirectory())
        .UseConfiguration(config)
        .UseStartup<Startup>()
        .Build();

    host.Run();
}

Notice how I’ve removed the .ForUrls() method; this prevents .ForUrls() overwriting the IP address provided via command line.

hosting.json approach

Another popular approach to specifying your host and port address is to read the IP address from a .json file during the application boot up. Whilst you can name your configuration anything, the common approach appears to be hosting.json, with the contents of your file containing the IP address you want your application to listen on:

{
  "urls": "http://*:5000"
}

In order to use this approach you’re first going to need to include the Microsoft.Extensions.Configuration.Json package, allowing you to load configurations via .json documents.

public static void Main(string[] args)
{
    var config = new ConfigurationBuilder()
        .SetBasePath(Directory.GetCurrentDirectory())
        .AddJsonFile("hosting.json", optional: true)
        .Build();

    var host = new WebHostBuilder()
        .UseKestrel()
        .UseContentRoot(Directory.GetCurrentDirectory())
        .UseConfiguration(config)
        .UseStartup<Startup>()
        .Build();

    host.Run();
}

Now when you run the dotnet run or dotnet YourApp.dll command you’ll noticed the output will reflect the address specified within your hosting.json document.

Just a reminder that before publishing your application be sure to include your hosting file in your publishing options (in either your project.json or your .csproj file:

// project.json

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

// YourApp.csproj

<ItemGroup>
  <Content Update="wwwroot;Views;appsettings.json;web.config;hosting.json">
  <CopyToPublishDirectory>PreserveNewest</CopyToPublishDirectory>
  </Content>
</ItemGroup>

Out of all of the approaches available this has to be my most preferred option. It’s simple enough to overwrite or modify within your test/release pipeline whilst removing hurdles co-workers may need to jump through when wanting to download your source code and run the application (as opposed to the command line approach).

Order of preference

When it comes down to the order the IP addresses are loaded, I would recommend you check out the documentation here, especially this snippet:

You can override any of these environment variable values by specifying configuration (using UseConfiguration) or by setting the value explicitly (using UseUrls for instance). The host will use whichever option sets the value last. For this reason, UseIISIntegration must appear after UseUrls, because it replaces the URL with one dynamically provided by IIS. If you want to programmatically set the default URL to one value, but allow it to be overridden with configuration, you could configure the host as follows:

var config = new ConfigurationBuilder()
   .AddCommandLine(args)
   .Build();

var host = new WebHostBuilder()
   .UseUrls("http://*:1000") // default URL
   .UseConfiguration(config) // override from command line
   .UseKestrel()
   .Build();

Conclusion

Hopefully this post helped you gain a better understanding of the many options available to you when configuring what IP address you want your application to listen on, writing it has certainly helped me cement them in my mind!

As someone that’s never written a Visual Studio Code extension before it was a bit of an abmitious first extension, but enjoyable none the less.

Today I released the first version of the IL Viewer (0.0.1) to the Visual Studio Code Marketplace so it’s available to download and try via the link below:

Download IL Viewer for Visual Studio Code

Download C# IL Viewer for Visual Studio Code or install it directly within Visual Studio Code by launching Quick Open (CMD+P for Mac or CTRL+P for Windows) and pasting in the follow command and press enter.

ext install vscodeilviewer

The source code is all up on GitHub so feel free to take a look, but be warned - it’s a little messy right now as it was hacked together to get it working.

For those interested in how it works, continue reading.

How does it work?

Visual Studio Code and HTTP Service

At its heart, Visual Studio Code is a glorified text editor. C# support is added via the hard work of the OmniSharp developers, which itself is backed by Roslyn. This means that in order to add any IL inspection capabilities I needed to either hook into OmniSharp or build my own external service that gets bundled within the extension. In the end I decided to go with the later.

When Visual Studio Code loads and detects the language is C# and the existence of a project.json file, it starts an external HTTP serivce (using Web API) which is bundled within the extension.

Moving forward I intend to switch this out for a console application communicating over stdin and stdout. This should speed up the overall responsiveness of the extension whilst reducing the resources required, but more importantly reduce the start up time of the IL viewer.

Inspecting the Intermediate Language

Initially I planned on making the Visual Studio Code IL Viewer extract the desired file’s IL directly from its project’s built DLL, however after a little experimentation this proved not to ideal as it required the solution to be built in order to view the IL, and built again for any inspections after changes, no matter how minor. It would also be blocking the user from doing any work whilst the project was building.

In the end I settled on an approach that builds just the .cs file you wish to inspect into an in memory assembly then extracts the IL and displays it to the user.

Including external dependencies

One problem with compiling just the source code in memory is that it doesn’t include any external dependencies. As you’d expect, as soon as Roslyn encounters a reference for an external binary you get a compilation error. Luckily Roslyn has the ability to automatically include external dependencies via Roslyn’s workspace API.

public static Compilation LoadWorkspace(string filePath)
{
    var projectWorkspace = new ProjectJsonWorkspace(filePath);

    var project = projectWorkspace.CurrentSolution.Projects.FirstOrDefault();
    var compilation = project.GetCompilationAsync().Result;

    return compilation;
}

After that the rest was relativly straight forward, I grab the syntax tree from the compilation unit of the project the load in any additional dependencies before using Mono’s Cecil library to extract the IL (as Cecil supports .NET Standard it does not require the Mono runtime).

Once I have the IL I return the contents as a HTTP response then display it to the user in Visual Studio Code’s split pane window.

Below is a simplified diagram of how it’s all tied together:

As I mentioned above, the source code is all available on GitHub so feel free to take a look. Contributions are also very welcome!

I find these types of post really helpful at tracking progress and ensuring I stay on a positive projection as a software developer/engineer - a hobby that I’m lucky enough to have as a career.

Review of 2016

Last year was an amazing year for a couple of reasons, some planned and some not so. So, without further ado let’s look at last year’s personal targets and goals to see how I’ve done.

Goal 1: Speak at more conferences and meet-ups

I’m inclined to say I’ve smashed this. At the time of writing last year’s post (February 2016) my speaking activities included relatively small user groups and meet ups. Since that post I’ve spoken at a few more meet ups but also at some rather large conferences which has been amazing.

The talks include:

• Why software engineering is a great career choice
  TechSpark Graduates Conference 2016 - 1st December 2016

• Going cross-platform with ASP.NET Core
  BrisTech 2016 - 3rd November 2016

• Going cross-platform with ASP.NET Core
  Tech Exeter Conference - 8th October 2016

• Building rich client-side applications using Angular 2
  DDD 11 (Reading) - 3rd September 2016

• .NET Rocks Podcast - Angular 2 CLI (Command Line Interface)
  24th August 2016

• Angular 2
  BristolJS - May 25th, 2016

• Angular 2
  Taunton Developers’ Meetup - June 9th, 2016

It’s a really great feeling reflecting on my very first talk (a lightening talk on TypeScript) and how nervous I was in comparison to now. Don’t get me wrong, the nerves are still there, but as many will know - you’re just able to cope with them better.

.All in all I’m extremely satisfied at how far I’ve progressed in this area and how much my confidence speaking in public has grown. This is certainly something I wish to continue to do in 2017.

Goal 2: Start an Exeter based .NET User Group

At the time of setting this goal I was working in Exeter where there were no .NET focused user group, something that surprised me given the number of .NET specific jobs in the city.

To cut a long story short, I’d started an Exeter .NET user group and was in the process of organising the first meet up when I got a job opportunity at Just Eat in Bristol and ended up taking over the Bristol based .NET South West user group as the organiser was stepping down and closing the rather large, well established group down. Having been to a couple of the meet ups at the user group it was a shame to see it end, and given the fact I was now working in Bristol I decided to step forward to take over along with a couple of the other members.

Since then we (me and the the other organisers) have been really active in keeping .NET South West alive and well, organising a range of speakers on variety of .NET related topics.

Goal 3: Continue contributing to the .NET OSS ecosystem

This year I’ve create a number of small open-source libraries, and projects (Angular 2 piano sight reading game the one that’s received the most attention). However whilst I’ve been contributing on and off to other libraries, I don’t feel my contributions have been at a level that I’m happy with, so this will be a goal for 2017.

Bonus Goal - F

Making a start learning F# was one of my bonus goals that I was hoping to achieve during 2016, however other than making a few changes to a couple of lines of F#, this is a no-go.

In all honesty, I’m still on the bench as to whether I want to learn F# - my only motivation being to learn a functional language (growing knowledge and thinking in a different paradigm); where as there are other languages I’m interested in learning that aren’t necessarily tied to the .NET eco-system.

Other notable events and achievements in 2016

In addition to the aforementioned goals and achievements in 2016, there have also been others.

• New job as a .NET software engineer at Just Eat in Bristol - a seriously awesome company that has a lot of really talented developers and interesting problems to work on.
• Co-organiser of DDD South West conference
• Heavy investment of time in learning .NET Core and Docker
• Became co-organiser of the .NET South West user group

Goals for 2017

With a review of 2016 out of the way let’s take a quick look at plans for 2017.

Goal 1: Continue to grow as a speaker, speaking at larger events

I’ve really loved speaking at meet ups and conferences, it’s a truly rewarding experience both on a personal development and professional development level. There’s very little more satisfying in life than pushing yourself outside of your comfort zone. So in 2017 I’m really keen to continue to pursue this by talking at larger conferences and events.

Goal 2: More focus on contributing to open-source projects

Whilst I’m satisfied with my contributions to the open-source world, with personal projects and contributions to other projects, it’s definitely an area I would like to continue to pursue. So in 2017 I’m aiming I’m looking for other larger projects I invest in and contribute to on a long term basis.

Goal 3: Learn another language

Where as I previously set myself a 2016 goal of Learn F#, this time around I’m going to keep my options open. I’ve recently been learning a little Go, but also really interested in Rust, so this year I’m going to simply set a goal to learn a new language. As it stands, it looks like it’s between Go and Rust, with F# still being a possibility.

Conclusion

Overall it’s been a great year, I’m really keen to keep the pace up on public speaking as it’s far too easy to rest on one’s laurels, so here’s to 2017 and the challenges it brings!

Before we continue, let me take a moment to explain what Roslyn is for those that may not fully understand what it is.

What is Roslyn?

Roslyn is an open-source C# and VB compiler as a service platform.

The key words to take away with you here are “compiler as a service”; let me explain.

Traditionally compilers have been a black box of secrets that are hard to extend or harness, especially for any tooling or code analysis purposes. Take ReSharper for instance; Resharper has a lot of code analysis running under the bonnet that allows it to offer refactoring advice. In order for the ReSharper team to provide this they had to build their own analysis tools that would manually parse your solution’s C# inline with the .NET runtime - the .NET platform provided no assistance with this, essentially meaning they had to duplicate a lot of the work the compiler was doing.

This has since changed with the introduction of Roslyn. For the past couple of years Microsoft have been rewriting the C# compiler in C# (I know, it’s like a compiler Inception right?) and opening it up via a whole host of APIs that are easy to prod, poke and interrogate. This opening up of the C# compiler has resulted in a whole array of code analysis tooling such as better StyleCop integration and debugging tools like OzCode and the like. What’s more, you can also harness Roslyn for other purposes such as tests that fail as soon as common code smells are introduced into a project.

Let’s start

So now we all know what Roslyn is, let’s take a look at how we can use it to compile a project in memory. In this post we will be taking some C# code written in plain text, turning it into a syntax tree that the compiler can understand then using Roslyn to compile it, resulting in a streaming in-memory assembly.

Create our project

In this instance I’m using .NET Core on a Mac but this will also work on Windows, so let’s begin by creating a new console application by using the .NET Core CLI.

dotnet new -t console

Now, add the following dependencies to your project.json file:

"dependencies": {
    "Microsoft.CodeAnalysis.CSharp.Workspaces": "1.3.2",
    "Mono.Cecil": "0.10.0-beta1-v2",
    "System.ValueTuple": "4.3.0-preview1-24530-04"
},

For those interested, here is a copy of the project.json file in its entirety:

{
  "version": "1.0.0-*",
  "buildOptions": {
    "debugType": "portable",
    "emitEntryPoint": true
  },
  "dependencies": {
    "Microsoft.CodeAnalysis.CSharp.Workspaces": "1.3.2",
    "Mono.Cecil": "0.10.0-beta1-v2",
    "System.ValueTuple": "4.3.0-preview1-24530-04"
  },
  "frameworks": {
    "netcoreapp1.1": {
      "dependencies": {
        "Microsoft.NETCore.App": {
          "type": "platform",
          "version": "1.0.1"
        }
      },
      "imports": "portable-net45+win8+wp8+wpa81"
    }
  }
}

Once we’ve restored our project using the dotnet restore command, the next step is to write a simple class to represent our source code. This code could be read from a web form, a database or a file on disk. In this instance I’m hard-coding it into the application itself for simplicity.

public class Program {

    public static void Main(string[] args)
    {

        var code = @"
        using System;
        public class ExampleClass {
            
            private readonly string _message;

            public ExampleClass()
            {
                _message = ""Hello World"";
            }

            public string getMessage()
            {
                return _message;
            }

        }";

        CreateAssemblyDefinition(code);
    }

    public static void CreateAssemblyDefinition(string code)
    {
        var sourceLanguage = new CSharpLanguage();
        SyntaxTree syntaxTree = sourceLanguage.ParseText(code, SourceCodeKind.Regular);

        ...
    }

}

Getting stuck into Roslyn

Now we’ve got the base of our project sorted, let’s dive into some of the Roslyn API.

First we’re going to want to create an interface we’ll use to define the language we want to use. In this instance it’ll be C#, but Roslyn also supports VB.

public interface ILanguageService
{
    SyntaxTree ParseText(string code, SourceCodeKind kind);

    Compilation CreateLibraryCompilation(string assemblyName, bool enableOptimisations);
}

Next we’re going to need to parse our plain text C#, so we’ll begin by working on the implementation of the ParseText method.

public class CSharpLanguage : ILanguageService
{
    private static readonly LanguageVersion MaxLanguageVersion = Enum
        .GetValues(typeof(LanguageVersion))
        .Cast<LanguageVersion>()
        .Max();

    public SyntaxTree ParseText(string sourceCode, SourceCodeKind kind) {
        var options = new CSharpParseOptions(kind: kind, languageVersion: MaxLanguageVersion);

        // Return a syntax tree of our source code
        return CSharpSyntaxTree.ParseText(sourceCode, options);
    }

    public Compilation CreateLibraryCompilation(string assemblyName, bool enableOptimisations) {
        throw new NotImplementedException();
    }
}

As you’ll see the implementation is rather straight forward and simply involved us setting a few parse options such as the language features we expect to see being parsed (marked via the languageVersion parameter) along with the SourceCodeKind enum.

Looking further into Roslyn’s SyntaxTree

At this point I feel it’s worth mentioning that if you’re interested in learning more about Roslyn then I would recommend spending a bit of time looking into Roslyn’s Syntax Tree API. Josh Varty’s posts on this subject are a great resource I would recommend.

I would also recommend taking a look at LINQ Pad, which amongst other great features, has the ability to show you a syntax tree generated by Roslyn your code. For instance, here is a generated syntax tree of our ExampleClass code we’re using in this post:

Now our C# has been parsed and turned into a data structure the C# compiler can understand, let’s look at using Roslyn to compile it.

Compiling our Syntax Tree

Continuing with the CreateAssemblyDefinition method, let’s compile our syntax tree:

public static void CreateAssemblyDefinition(string code)
{
    var sourceLanguage = new CSharpLanguage();
    SyntaxTree syntaxTree = sourceLanguage.ParseText(code, SourceCodeKind.Regular);

    Compilation compilation = sourceLanguage
      .CreateLibraryCompilation(assemblyName: "InMemoryAssembly", enableOptimisations: false)
      .AddReferences(_references)
      .AddSyntaxTrees(syntaxTree);

    ...
}

At this point we’re going to want to fill in the implementation of our CreateLibraryCompilation method within our CSharpLanguage class. We’ll start this by passing the appropriate arguments into an instance of CSharpCompilationOptions. This includes:

• outputKind - We’re outputting a (dll) Dynamically Linked Library
• optimizationLevel - Whether we want our C# output to be optimised
• allowUnsafe - Whether we want the our C# code to allow the use of unsafe code or not

public class CSharpLanguage : ILanguageService
{
    private readonly IReadOnlyCollection<MetadataReference> _references = new[] {
          MetadataReference.CreateFromFile(typeof(Binder).GetTypeInfo().Assembly.Location),
          MetadataReference.CreateFromFile(typeof(ValueTuple<>).GetTypeInfo().Assembly.Location)
      };

    ...

    public Compilation CreateLibraryCompilation(string assemblyName, bool enableOptimisations) {
      var options = new CSharpCompilationOptions(
          OutputKind.DynamicallyLinkedLibrary,
          optimizationLevel: enableOptimisations ? OptimizationLevel.Release : OptimizationLevel.Debug,
          allowUnsafe: true);

      return CSharpCompilation.Create(assemblyName, options: options, references: _references);
  }
}

Now we’ve specified our compiler options, we invoke the Create factory method where we also need to specify the assembly name we want our in-memory assembly to be called (InMemoryAssembly in our case, passed in when calling our CreateLibraryCompilation method), along with additional references required to compile our source code. In this instance, as we’re targeting C# 7, we need to supply the compilation unit with the ValueTuple structs implementation. If we were targeting an older version of C# then this would not be required.

All that’s left to do now is to call Roslyn’s emit(Stream stream) method that takes a Stream input parameter and we’re sorted!

public static void CreateAssemblyDefinition(string code)
{
    ...

    Compilation compilation = sourceLanguage
        .CreateLibraryCompilation(assemblyName: "InMemoryAssembly", enableOptimisations: false)
        .AddReferences(_references)
        .AddSyntaxTrees(syntaxTree);

    var stream = new MemoryStream();
    var emitResult = compilation.Emit(stream);
    
    if (emitResult.Success){
        stream.Seek(0, SeekOrigin.Begin);
        AssemblyDefinition assembly = AssemblyDefinition.ReadAssembly(stream);
    }
}

From here I’m then able to pass my AssemblyDefinition to a method that extracts the IL and I’m good to go!

Conclusion

Whilst this post is quite narrow in its focus (I can’t imagine everyone is looking to compile C# in memory!), hopefully it’s served as a primer in spiking your interest in Roslyn and what it’s capable of doing. Roslyn is a truly powerful platform that I wish more languages offered. As mentioned before there are some great resources available go into much more depth. I would especially recommend Josh Varty’s posts on the subject.

Spinning up instances of your application can lead to a lot of additional work when it comes to running your tests within any type of continuous deployment or delivery pipeline. This has certainly become easier with the introduction of the cloud, but still requires a reasonable investment of time and effort to setup, as well slowing down your deployment/delivery pipeline.

An alternative approach to running your integration or end-to-end tests is to utilise in-memory testing. This is where your application is spun up in memory via an in-memory server and has the tests run against it. An additional benefit to running your tests this way is you’re no longer testing any of your host OS’s network stack either (which in most cases will be configured differently to your production server’s stack anyway).

TestServer package

Thankfully in-memory testing can be performed easily in ASP.NET Core thanks to the Microsoft.AspNetCore.TestHost NuGet package.

Let’s take a moment to look at the TestServer API exposed by the TestHost library:

public class TestServer : IServer, IDisposable
{
    public TestServer(IWebHostBuilder builder);

    public Uri BaseAddress { get; set; }
    public IWebHost Host { get; }

    public HttpClient CreateClient();
    public HttpMessageHandler CreateHandler();
    
    public RequestBuilder CreateRequest(string path);
    public WebSocketClient CreateWebSocketClient();
    public void Dispose();
}

As you’ll see, the API has all the necessary endpoints we’ll need to spin our application up in memory.

For those that are regular readers of my blog, you’ll remember we used the same TestServer package to run integration tests on middleware back in July. This time we’ll be using it to run our Web API application in memory and run our tests against it. We’ll then assert that the response received is expected.

Enough talk, let’s get started.

Running Web API in memory

Setting up Web API

In this instance I’m going to be using ASP.NET Core Web API. In my case I’ve created a small Web API project using the ASP.NET Core yoman project template. You’ll also note that I’ve stripped a few things out of the application for the sake of making the post as easier to follow. Here are the few files that really matter:

Startup.cs (nothing out of the ordinary here)

public class Startup
{
    public Startup(IHostingEnvironment env)
    {
        var builder = new ConfigurationBuilder()
            .SetBasePath(env.ContentRootPath)
            .AddJsonFile("appsettings.json", optional: true, reloadOnChange: true)
            .AddJsonFile($"appsettings.{env.EnvironmentName}.json", optional: true)
            .AddEnvironmentVariables();
        Configuration = builder.Build();
    }

    public IConfigurationRoot Configuration { get; }

    // This method gets called by the runtime. Use this method to add services to the container.
    public void ConfigureServices(IServiceCollection services)
    {
        // Add framework services.
        services.AddMvc();
    }

    // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
    public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
    {
        loggerFactory.AddConsole(Configuration.GetSection("Logging"));
        loggerFactory.AddDebug();

        app.UseMvc();
    }
}

ValuesController.cs

[Route("api/[controller]")]
public class ValuesController : Controller
{
    [HttpGet]
    public string Get()
    {
        return "Hello World!";
    }
}

All we’ve got here is a simple WebAPI application that returns a single Hello World! value from ValueController when you fire a GET request to /api/values/.

Running Web API in memory

At this point I’ve created a test project alongside my Web API one and added the Microsoft.AspNetCore.TestHost package to my test project’s package.json file.

package.json

...
"dependencies": {
    "dotnet-test-xunit": "2.2.0-preview2-build1029",
    "xunit": "2.2.0-beta2-build3300",
    "Microsoft.AspNetCore.TestHost": "1.0.0",
    "TestWebAPIApplication":{
        "target":"project"
    }
},
...

Next, we’ll create our first test class, and bootstrap our WebAPI project. Pay particular attention to our web application’s Startup.cs that’s being passed into the WebHostBuilder’s UseStartup<T> method. You’ll notice this is exactly the same way we bootstrap our application within Program.cs (the bootstrap file we use when deploying our application).

public class ExampleTestClass
{
    private IWebHostBuilder CreateWebHostBuilder(){
        var config = new ConfigurationBuilder().Build();
        
        var host = new WebHostBuilder()
            .UseConfiguration(config)
            .UseStartup<Startup>();

        return host;
    }

    ...
}

Writing our test

At this point we’re ready to write our test, so let’s create a new instance of TestServer which takes and instance of IWebHostBuilder.

public TestServer(IWebHostBuilder builder);

As you can see from the following trivial example, we’re simply capturing the response from the controller invoked when calling /api/values, which is our case is the ValuesController.

[Fact]
public async Task PassingTest()
{
    var webHostBuilder = CreateWebHostBuilder();
    var server = new TestServer(webHostBuilder);

    using(var client = server.CreateClient()){
        var requestMessage = new HttpRequestMessage(new HttpMethod("GET"), "/api/values/");
        var responseMessage = await client.SendAsync(requestMessage);

        var content = await responseMessage.Content.ReadAsStringAsync();

        Assert.Equal(content, "Hello World!");
    }
}

Now, when we call Assert.Equals on our test we should see the test has passed.

Running test UnitTest.Class1.PassingTest...
Test passed 

Conclusion

Hopefully this post has given you enough insight into how you can run your application in memory for purposes such as integration or feature testing. Naturally there’s a lot more you could do to simplify and speed up the tests by limiting the number of times TestServer is created.

I won’t go into too much detail as how the blog is built as it’s nothing anyone wouldn’t have seen before, but as someone that likes to read about people’s experiencing building things, I thought I’d break down how it’s built and what I learned whilst doing it.

Here’s an overview of some of the technology I’ve used:

• .NET Core / ASP.NET Core MVC
• MediatR
• Azure SQL
• Dapper
• Redis
• Google Authentication
• Docker
• Nginx
• Ubuntu

.NET Core / ASP.NET Core MVC

Having been following the development of .NET Core, I thought I’d wait until things stabilised before I started migrating. Unfortunately I didn’t wait long enough and had to go through the the pain many developers experiences with breaking changes.

I also ran into various issues such as waiting for libraries to migrate to .NET Standard, and other problems such as RSS feed generation for which no .NET Standard libraries exist, primarily because System.ServiceModel.Syndication is not .NET Core compatible just yet. None of these are deal breakers, with work arounds out there, but none-the-less tripped me up along the way. That said, whilst running into these issues I did keep reminding myself that this is what happens when you start building with frameworks and libraries still in beta - so no hard feelings.

In fact, I’ve been extremely impressed with the direction and features in ASP.NET Core and look forward to building more with it moving forward.

MediatR

I’ve never been a fan of the typical N-teir approach to building an application primarily because it encourages you to split your application into various horizontal slices (generally UI, Business Logic and Data Access), which often leads of a ridged design filled with lots of very large mixed concerns. Instead I prefer breaking my application up into vertical slices based on features, such as Blog, Pages, Admin etc.

MediatR helps me do this and at the same time allows you to model your application’s commands and queries, turning a HTTP request into a pipeline to which you handle and return a response. This has an added effect of keeping your controllers nice and skinny as the only responsibility of the Controller is to pass the request into MediatR’s pipeline.

Below is a simplified example of what a controller looks like, forming the request then delegating it to the appropriate handler:

// Admin Controller
public class BlogAdminController {

    private readonly IMediator _mediator;

    public BlogAdminController(IMediator mediator)
    {
        _mediator = mediator;
    }

    [Route("/admin/blog/edit/{id:int}")]
    public IActionResult Edit(BlogPostEdit.Query query)
    {
        BlogPostEdit.Response model = _mediator.Send(query);

        return View(model);
    }
}

public class BlogPostEdit
{
    public class Query : IRequest<Response>
    {
        public int Id { get; set; }
    }

    public class BlogPostEditRequestHandler : IRequestHandler<Query, Response>
    {
        private readonly IBlogAdminStorage _storage;

        public BlogPostEditRequestHandler(IBlogAdminStorage storage)
        {
            _storage = storage;
        }

        public Response Handle(Query request)
        {
            var blogPost = _storage.GetBlogPost(request.Id);
            if (blogPost == null)
                throw new RecordNotFoundException(string.Format("Blog post Id {0} not found", request.Id.ToString()));

            return new Response
            {
                BlogPostEditModel = blogPost
            };
        }
    }

    public class Response
    {
        public BlogPostEditModel BlogPostEditModel { get; set; }
    }
}

A powerful feature of MediatR’s pipelining approach is you can start to use the decorator pattern to handle cross-cutting concerns like caching, logging and even validation.

If you’re interested in reading more about MediatR then I’d highly recommend Jimmy Bogard’s video on favouring slices rather than layers, where he covers MediatR and its architectural benefits.

Google Authentication

I wanted to keep login simple, and not have to worry about storing passwords. With this in mind I decided to go with Google Authentication for logging in, which I cover in my Social authentication via Google in ASP.NET Core MVC post.

Docker, Ubuntu and Redis

Having read loads on Docker but never having played with it, migrating my blog to .NET Core seemed like a perfect opportunity to get stuck into Docker to see what all the fuss was about.

Having been using Docker for a couple of months now I’m completely sold on how it changes the deployment and development landscape.

This isn’t the right post to go into too much detail about Docker, but no doubt you’re aware of roughly what it does by now and if you’re considering taking it for a spin to see what it can do for you then I would highly recommend it.

Docker’s made configuring my application to run on Ubuntu with Redis and Nginx an absolute breeze. No longer do I have to spin up individual services and packing website up and deploy it. Now I simply have to publish an image to a repository, pull it down to my host and run docker-compose up.

Don’t get me wrong, Docker’s certainly not the golden bullet that some say it is, but it’s definitely going to make your life easier in most cases.

Open-sourcing the blog

I redeveloped the blog in mind of open-sourcing it, so once I’ve finished tidying it up I’ll put it up on my GitHub account so you can download it and give it a try for yourself. It’s no Orchard CMS, but it’ll do the job for me - and potentially you.

No longer do you need to simultaneously waste time and slow down your local development machine by installing various services like Redis, Postgres and other dependencies. You can simply download a Docker image and boot up your development environment. Then, once you’re finished with it tear it down again.

In fact, a lot of the Docker images for such services are maintained by the development teams and companies themselves.

I’d never fully appreciated this dream until recently when I partook in the quarterly three day hackathon at work, where time was valuable and we didn’t waste time downloading and installing the required JDK just to get Elastic Search installed.

In fact, I was so impressed with Docker and Elastic Search that it compelled me to write this post.

So without further ado, let’s get started.

What is Elastic Search?

Elasticsearch is a search server based on Lucene. It provides a distributed, multitenant-capable full-text search engine with a RESTful web interface and schema-free JSON documents.

Now that that’s out of the way, let’s get going. First thing’s first, you’re going to need Docker

Installing Docker

If the title didn’t give it away, we’re going to be setting up Elastic Search up locally using Docker, so if you don’t have Docker installed then you’re going to need to head over to the Docker download page and download/install it.

Setting up Elastic Search

Next we’re going to need to find the Elastic Search Docker image.

To do this we’re going to head over to Docker Hub and seach for Elastic Search (here’s a direct link for the lazy or those pressed for time).

What is Docker Hub? For new to Docker, Docker Hub is a repository of popular Docker images, many of which are officially owned and supported by the owners of the software.

Pulling and running the Elastic Search Docker image

To run the Elastic Search Docker image we’re first going to need to pull it down to our local machine. To do this open your command prompt or terminal (any directory is fine as nothing is downloaded to the current directory) and execute the following Docker command:

docker pull elasticsearch

Running Elastic Search

Next we want to run our Elastic Search image, do to that we need to type the following command into our terminal:

docker run -d -p 9200:9200 -p 9300:9300 elasticsearch

Let’s breakdown the command:

• First we’re telling Docker we want to run an image in a container via the ‘run‘ command.

• The -d argument will run the container in detached mode. This means it will run as a separate background process, as opposed to short-lived process that will run and immediately terminate once it has finished executing.

• Moving on, the -p arguments tell the container to open and bind our local machine’s port 9200 and 9300 to port 9200 and 9300 in the Docker container.

• Then at the end we specify the Docker image we wish to start running - in this case, the Elastic Search image.

Note: At this point, if you’re new to Docker then it’s worth knowing that our container’s storage will be deleted when we tear down our Docker container. If you wish to persist the data then we have to use the -v flag to map the Docker’s drive volume to our local disk, as opposed to the default location which is the Docker’s container.

If we want to map the volume to our local disk then we’d need to run the following command instead of the one mentioned above:

docker run -d -v "$HOME/Documents/elasticsearchconf/":/usr/share/elasticsearch/data -p 9200:9200 -p 9300:9300 elasticsearch

This will map our $HOME/Documents/elasticsearchconf folder to the container’s /usr/share/elasticsearch/data directory.

Checking our Elastic Search container is up and running

If the above command worked successfully then we should see the Elastic Search container up and running, we can check this by executing the following command that lists all running containers:

docker ps

To verify Elastic Search is running, you should also be able to navigate to http://localhost:9200 and see output similar to this:

{
  "name" : "f0t5zUn",
  "cluster_name" : "elasticsearch",
  "cluster_uuid" : "3loHHcMnR_ekDxE1Yc1hpQ",
  "version" : {
    "number" : "5.0.0",
    "build_hash" : "253032b",
    "build_date" : "2016-10-26T05:11:34.737Z",
    "build_snapshot" : false,
    "lucene_version" : "6.2.0"
  },
  "tagline" : "You Know, for Search"
}

Container isn’t running?

If for some reason you container isn’t running, then you can run the following command to see all containers, whether running or not.

docker ps -a

Then once you’ve identified the container you just tried to run (hint: it should be at the top) then run the following command, including the first 3 or 4 characters from the Container Id column:

docker logs 0403

This will print out the containers logs, giving you a bit of information as to what could have gone wrong.

Connecting to Elastic Search

Now that our Docker container is up and running, let’s get our hands dirty with Elastic Search via their RESTful API.

Indexing data

Let’s begin by indexing some data in Elastic Search. We can do this by posting the following product it to our desired index (where product is our index name, and television is our type):

// HTTP POST:
http://localhost:9200/product/television

Message Body:
{"Name": "Samsung Flatscreen Television", "Price": "£899"}

If successful, you should get the following response from Elastic Search:

{
    "_index":"product",
    "_type":"television",
    "_id":"AVhIJ4ACuKcehcHggtFP",
    "_version":1,
    "result":"created",
    "_shards":{
        "total":2,
        "successful":1,
        "failed":0
    },
    "created":true
}

Searching for data

Now we’ve got some data in our index, let’s perform a simple search for it.

Performing the following GET request should return the following data:

// HTTP GET:
http://localhost:9200/_search?q=samsung

The response should look something like this:

{
    "took":16,
    "timed_out":false,
    "_shards":{
        "total":15,
        "successful":15,
        "failed":0
    },
    "hits":{
        "total":1,
        "max_score":0.2876821,
        "hits":[{
                "_index":"product",
                "_type":"television",
                "_id":"AVhIJ4ACuKcehcHggtFP",
                "_score":0.2876821,
                "_source": {
                    "Name": "Samsung Flatscreen Television","Price": "£899"
                }
            }]
        }
}

One of the powerful features of Elastic Search is its  full-text search capabilities, enabling you to perform some truely impressive search queries against your indexed data.

For more on the search options available to you I would recommend you check out this resource.

Deleting Indexed data

To delete indexed data you can perform a delete request, passing the object ID, like so:

// HTTP Delete
http://localhost:9200/product/television/AVhIJ4ACuKcehcHggtFP

Moving Forward

So far we’ve been using Elastic Search’s API query our Elastic Search index. If you’d prefer something more visual that will aid you in your exploration and discovery of the Elastic Search structured query syntax then I’d highly recommend you check out ElasticSearch-Head; a web frontend for your Elastic Search cluster. 

To get started with ElasticSearch-Head you simply clone the repository to your local drive, open the _index.html_ file and point it at your http://localhost:9200 endpoint.

If you have experience issues connecting your web client to your Dockerised Elastic Search cluster then it could be because of CORS permissions. Instead of fiddling around with configurations I simply installed and enabled this Chrome plugin to get around it.

Now you can use the web UI to view the search tab to discover more of Elastic Search’s complex structured query syntax.

During the talk I discussed the future of the .NET platform and Microsoft’s cross-platform commitment, the performance benefits, differences between .NET and .NET Core including ASP.NET differences, then proceeded to demonstrate the new .NET command line interface and building an ASP.NET Core application using .NET Core.

To put the proof in the pudding so to speak, to demonstrate that .NET Core really is cross platform, I did all of this on a Macbook Pro.

My talk topic? Building Rich client-side applications using Angular 2.

As a regular speaker at meet ups and the occasional podcast, this year I’ve been keen to step it up and move into the conference space. Speaking is something that I love doing, and DDD 11 was a great opportunity that I didn’t want to miss.

Having spotted a tweet that DDD were accepting talk proposals a number of weeks ago, I quickly submitted a few talks I had up my sleeve - with Building rich client-side apps using Angular 2 being the talk that received enough votes to get me a speaking slot - yay!

My talk was one of the last talks of the day so I had to contend with a room full of sleepy heads, tired after a long day of networking and programming related sessions (myself included). With this in mind I decided it would be best to step up the energy levels with a hope of keeping people more engaged.

Overall I think the talk went well (though in hindsight I could have slowed down a little bit!) and received what I felt was a good reception, and it was great to have people in the audience (some of whom are speakers themselves) approach me afterwards saying they enjoyed the talk.

As Steve was demonstrating all of these amazing APIs (including  server side rendering of Angular 2/Reacts applications, Angular 2 validation that was integrated with .NET Core MVC’s validation) the question that was at the end of everyone’s tongue was “How’s he doing this?!”.

When the opportunity finally arose, Steve demonstrated what I think it one of the coolest parts of the talk - the JavaScriptServices middleware - the topic of this blog post.

Before continuing, if you develop single page apps in either Angular, React or Knockout then I’d highly recommend you check out the talk, which can also be found here.

What is JavaScriptServices?

JavaScriptServices is a .NET Core middleware library that plugs into the .NET Core pipeline which uses Node to execute JavaScript (naturally this also includes Node modules) at runtime. This means that in order to use JavaScriptServices you have to have Node installed the host machine.

How does it work and what application does it have? Let’s dive in and take a look!

Setting up JavaScriptServices

Before we continue, it’s worth mentioning that it looks like the package is currently going through a rename (from NodeServices to JavaScriptServices) - so you’ll notice the API and NuGet package is referenced NodeServices, yet I’m referring to JavaScriptServices throughout. Now that that’s out of the way, let’s continue!

First of all, as mentioned above, JavaScriptServices relies on Node being installed on the host machine, so if you don’t have Node installed then head over to NodeJs.org to download and install it. If you’ve already got Node installed then you’re good to continue.

As I alluded to earlier, setting up the JavaScriptServices middleware is as easy as setting up any other piece of middleware in the in the new .NET Core framework. Simply include the JavaScriptServices NuGet package in your solution:

Install-Package Microsoft.AspNetCore.NodeServices -Pre

Then reference it in your Startup.cs file’s ConfigureServices method:

public void ConfigureServices(IServiceCollection services)
{
    services.AddNodeServices();
}

Now we have the following interface at our disposal for calling Node modules:

public interface INodeServices : IDisposable
{
    Task<T> InvokeAsync<T>(string moduleName, params object[] args);
    Task<T> InvokeAsync<T>(CancellationToken cancellationToken, string moduleName, params object[] args);

    Task<T> InvokeExportAsync<T>(string moduleName, string exportedFunctionName, params object[] args);
    Task<T> InvokeExportAsync<T>(CancellationToken cancellationToken, string moduleName, string exportedFunctionName, params object[] args);
}

Basic Usage

Now we’ve got JavaScriptServices setup, let’s look at getting started with a simple use case and run through how we can execute some trivial JavaScript in our application and capture the output.

First we’ll begin by creating a simple JavaScript file that contains the a Node module that returns a greeting message:

// greeter.js
module.exports = function (callback, firstName, surname) {

    var greet = function (firstName, surname) {
        return "Hello " + firstName + " " + surname;
    }

    callback(null, greet(firstName, surname));
}

Next, we inject an instance of INodeServices into our controller and invoke our Node module by calling InvokeAsync<T> where T is our module’s return type (a string in this instance).

public DemoController {

    private readonly INodeServices _nodeServices;

    public DemoController(INodeServices nodeServices)
    {
        _nodeServices = nodeServices;
    }

    public async Task<IActionResult> Index()
    {
        string greetingMessage = await _nodeServices.InvokeAsync<string>("./scripts/js/greeter", "Joseph", "Woodward");

        ...
    }

}

Whilst this is a simple example, hopefully it’s demonstrated how easy it and given you an idea as to how powerful this can potentiall be. Now let’s go one further.

Taking it one step further - transpiling ES6/ES2015 to ES5, including source mapping files

Whilst front end task runners such as Grunt and Gulp have their place, what if we were writing ES6 code and didn’t want to have to go through the hassle of setting up a task runner just to transpile our ES2015 JavaScript?

What if we could transpile our Javascript at runtime in our ASP.NET Core application? Wouldn’t that be cool? Well, we can do just this with JavaScriptServices!

First we need to include a few Babel packages to transpile our ES6 code down to ES5. So let’s go ahead and create a packages.json in the root of our solution and install the listed packages by executing _npm install _at the same level as our newly created packages.json file.

{
    "name": "nodeservicesexamples",
    "version": "0.0.0",
    "dependencies": {
        "babel-core": "^6.7.4",
        "babel-preset-es2015": "^6.6.0"
    }
}

Now all we need to register the NodeServices service in the ConfigureServices method of our Startup.cs class:

public void ConfigureServices(IServiceCollection services)
{
    ...
    services.AddNodeServices();
    ...
}

After this we want to create our Node module that will invoke the Babel transpiler - this will also include the source mapping files.

// /node/transpilation.js

var fs = require('fs');
var babelCore = require('babel-core');

module.exports = function(cb, physicalPath, requestPath) {
    var originalContents = fs.readFileSync(physicalPath);
    var result = babelCore.transform(originalContents, {
        presets: ['es2015'],
        sourceMaps: 'inline',
        sourceFileName: '/sourcemapped' + requestPath
    });

    cb(null, result.code);
}

Now comes the interesting part. On every request we want to check to see if the HTTP request being made is for a .js extension. If it is, then we want to pass its contents to our JavaScriptServices instance to transpile it to ES6/2015 JavaScript, then finish off by writing the output to the output response.

At this point I think it’s only fair to say that if you were doing this in production then you’d probably want some form of caching of output. This would prevent the same files being transpiled on every request - but hopefully the follow example is enough to give you an idea as to what it would look like:

public void Configure(IApplicationBuilder app, IHostingEnvironment env, INodeServices nodeServices)
{
    ...

    // Dynamically transpile any .js files under the '/js/' directory
    app.Use(next => async context => {
        var requestPath = context.Request.Path.Value;
        if (requestPath.StartsWith("/js/") && requestPath.EndsWith(".js")) {
            var fileInfo = env.WebRootFileProvider.GetFileInfo(requestPath);
            if (fileInfo.Exists) {
                var transpiled = await nodeServices.InvokeAsync<string>("./node/transpilation.js", fileInfo.PhysicalPath, requestPath);
                await context.Response.WriteAsync(transpiled);
                return;
            }
        }

        await next.Invoke(context);
    });

    ...
}

Here, all we’re doing is checking the ending path of every request to see if the file exists within the /js/ folder and ends with .js. Any matches are then checked to see if the file exists on disk, then is passed to the transpilation.js module we created earlier. The transpilation module will then run the contents of the file through Babel and return the output to JavaScriptServices, which then proceeds to write to our application’s response object before invoking the next handler in our HTTP pipeline.

Now that’s all set up, let’s go ahead and give it a whirl. If we create a simple ES2016 Javascript class in a wwwroot/js/ folder and reference it within our view in a script tag.

// wwwroot/js/example.js

class Greeter {
    getMessage(name){
        return "Hello " + name + "!";
    }
}

var greeter = new Greeter();
console.log(greeter.getMessage("World"));

Now, when we load our application and navigate to our example.js file via your browser’s devtools you should see it’s been transpiled to ES2015!

Conclusion

Hopefully this post has giving you enough of an understanding of the JavaScriptServices package to demonstrate how powerful the library really is. With the abundance of Node modules available there’s all sorts of functionality you can build into your application, or application’s build process. Have fun!

So if you’ve been looking at Angular 2 recently then be sure to check out show 1339 and leave any feedback you may have.

If you’ve ever re-written a website and had to ensure old, expired URLs didn’t result in 404 errors and lost traffic then you’ll know what a pain this can be when dealing with a large number of expired URLs. Thankfully using .NET Core’s new middleware approach, this task becomes far easier - so much so that I’ve wrapped it into a library I intend to publish to NuGet:

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    ...
    app.UseRequestRedirect(r => r.ForPath("/32/old-path.html").RedirectTo("/32/new-path").Permanently());
    app.UseRequestRedirect(r => r.ForPath("/33/old-path.html").RedirectTo("/33/new-path").Temporarily());
    app.UseRequestRedirect(r => r.ForPath("/34/old-path.html").RedirectTo(DeferredQueryDbForPath).Temporarily());
    ...
}

private string DeferredQueryDbForPath(string oldPath){
    /* Query database for new path only if old path is hit */
    return newPath;
}

Whilst working on this middleware I was keen to add some integration tests for a more complete range of tests. After a bit of digging I noticed that doing so was actually really simple, thanks to the _TestServe_r class available as part of the Microsoft.AspNetCore.TestHost package.

What is Test Server?

TestServer is a lightweight and configurable host server, designed solely for testing purposes. Its ability to create and serve test requests without the need for a real web host is it’s true value, making it perfect for testing middleware libraries (amongst other things!) that take a request, act upon it and eventually return a response. In the case of the aforementioned middleware, our response we’ll be testing will be a status code informing the browser that the page has moved along with the destination the page is located at.

TestServer Usage

As mentioned above, you’ll find the TestServer class within the Microsoft.AspNetCore.TestHost package, so first of all you’ll need to add it to your test project either by using the following NuGet command:

Install-Package Microsoft.AspNetCore.TestHost

Or by updating your project.json file directly:

"dependencies": {
    ...
    "Microsoft.AspNetCore.TestHost": "1.0.0",
    ...
},

Once the NuGet package has downloaded we’re ready start creating our tests.

After creating our test class the first thing we need to do is configure an instance of WebHostBuilder, ensuring we add our configured middleware to the pipeline. Once configured we create our instance of TestServer which then bootstraps our test server based on the supplied WebHostBuilder configurations.

[Fact]
public async void Should_Redirect_Permanently()
{
    // Arrange
    var builder = new WebHostBuilder()
        .Configure(app => {
            app.UseRequestRedirect(r => r.ForPath("/old/").RedirectTo("/new/").Permanently());
        }
    );

    var server = new TestServer(builder);

    // Act
    ...
}

Next we need to manually create a new HTTP Request, passing the parameters required to exercise our middleware. In this instance, using the redirect middleware, all I need to do is create a new GET request to the path outlined in my arrange code snippet above. Once created we simply pass our newly created HttpRequestMessage to our configured instance of TestServer.

// Act
var requestMessage = new HttpRequestMessage(new HttpMethod("GET"), "/old/");
var responseMessage = await server.CreateClient().SendAsync(requestMessage);

// Assert
...

Now all that’s left is to assert our test using the response we received from our TestServer.SendAsync() method call. In the example below I’m using assertion library Shouldly to assert that the correct status code is emitted and the correct path (/new/) is returned in the header.

// Assert
responseMessage.StatusCode.ShouldBe(HttpStatusCode.MovedPermanently);
responseMessage.Headers.Location.ToString().ShouldBe("/new/");

The complete test will look like this:

public class IntegrationTests
{
    [Fact]
    public async void Should_Redirect_Permanently()
    {
        // Arrange
        var builder = new WebHostBuilder()
            .Configure(app => {
                app.UseRequestRedirect(r => r.ForPath("/old/").RedirectTo("/new/").Permanently());
            }
        );

        var server = new TestServer(builder);

        // Act
        var requestMessage = new HttpRequestMessage(new HttpMethod("GET"), "/old/");
        var responseMessage = await server.CreateClient().SendAsync(requestMessage);

        // Assert
        responseMessage.StatusCode.ShouldBe(HttpStatusCode.MovedPermanently);
        responseMessage.Headers.Location.ToString().ShouldBe("/new/");
    }
}

Conclusion

In this post we looked at how simple it is to test our middleware using the TestServer instance. Whilst the above example is quite trivial, hopefully it provides you with enough of an understanding as to how you can start writing integration or functional tests for your middleware.

Recently I’ve been doing a lot of ASP.NET Core MVC and in one project I’ve been working on I have an admin login area. My first instinct was to create the login section as an Area within the main application project.

Creating a login area in the same application would work, but other than sharing an /admin/ path it really was a completely separate application. It has different concerns, a completely different UI (in this instance it’s an Angular 2 application talking to a back-end API). For these reasons, creating the admin section as an MVC Area just felt wrong - so I began to look at what Kestrel could offer in terms of proxying requests to another application. This way I could keep my user facing website as one project and the administration area as another, allowing them to grow independent of one another.

Whilst proxying requests is possible in IIS, I was keen to use Kestrel as I’d like the option of hosting the application across various platforms, so I was keen to see what Kestrel had to offer.

Enter the ASP.NET Core Proxy Middleware!

After a little digging it came to no surprise that there was some middleware that made proxying requests a breeze. The middleware approach to ASP.NET Core MVC lends itself to such a task and setup was so simple that I felt it merited a blog post.

After installing the Microsoft.AspNetCore.Proxy NuGet package via the “Install-Package Microsoft.AspNetCore.Proxy“ command, all I had to do was hook the proxy middleware up to my pipeline using the _MapWhen_ method within my application’s Startup class:

// Startup.cs
public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    ...

    app.MapWhen(IsAdminPath, builder => builder.RunProxy(new ProxyOptions
    {
        Scheme = "http",
        Host = "localhost",
        Port = "8081"
    }));

    ...

}

private static bool IsAdminPath(HttpContext httpContext)
{
    return httpContext.Request.Path.Value.StartsWith(@"/admin/", StringComparison.OrdinalIgnoreCase);
}

As you can see, all I’m doing is passing a method that checks the path begins with /admin/.

Once setup, all you need to do is set your second application (in this instance it’s my admin application) to the configured port. You can do this within the Program class via the _UseUrls_ extension method:

// Program.cs
public class Program
{
    public static void Main(string[] args)
    {
        var host = new WebHostBuilder()
            .UseKestrel()
            .UseContentRoot(Directory.GetCurrentDirectory())
            .UseUrls("http://localhost:8081")
            .UseIISIntegration()
            .UseStartup<Startup>()
            .Build();

        host.Run();
    }
}

Now, if you start up your application and navigate to /admin/ (or whatever path you’ve specified) the request should be proxied to your secondary application!

Happy coding!

Recently however, I was introduced to a rather interesting but delightful looking typeface called Fira Mono that’s been designed by Mozilla specifically for their Firefox OS.

At first I didn’t think much of the font, but the more I saw him using it the more it grew on me. Eventually I decided to download it and give it a try. And having been using it now for a number of days I’ve no intention of switching back to Droid Sans.

Fira Mono in Visual Studio Code:

Fira Mono in Visual Studio:

Would you like ligatures with that?

If you’re a developer that likes your programming fonts with ligatures then there is a version available that includes ligatures called Fira Code.

Downloading Fira Mono

The font itself is open-source so if you’re interesting it giving it a try then download it via Font Squirrel here, then once extracted to your fonts directory load up Visual Studio (or restart so Visual Studio can load the font) and to go Tools > Options > Environment > Fonts and Colors and select it from the Font dropdown.

Having experimented with various font sizes (In Visual Studio only), font size 9 appears to work really well with Fira Mono.

As mentioned above, if you’d like the ligatures then head over here to download them.

1: Expand/Shrink Selection (CTRL + ALT + Right to expand, CTRL + ALT + Left to shrink)
This shortcut enables you to expand a selection by scope, meaning pressing CTRL + ALT + Right to expand your selection will start by highlighting the code your cursor is over, then the line then function scope, class and namespace. Check out the following gif to see an example. Be sure to watch the selected area!

Expand/Shrink Selection:

2: Increase selection by word (CTRL + Shift + Right to expand, CTRL + Shift + Left to shrink)

A few of you will probably notice that this shortcut isn’t really a ReSharper shortcut - and you’d be right. But none the less, once harnessed, increase/decrease selection by word is extremely powerful when it comes to renaming variables, methods, classes etc. and will serve you well if mastered.

Where am I going with this?

Whilst the aforementioned shortcuts are excellent tools to add to your shortcut toolbox, one thing I always wished they would do was the expand selection by camel case, allowing me to highlight words with more precision and save me the additional key presses when it comes to highlighting the latter part of a variable in order to rename it. For instance, instead of highlighting the whole word in one go (say, the word ProductService, for example), it would first highlight the word Product, followed by Service after the second key press.

Having wanted to do this for sometime now, I was pleasantly surprised when I stumbled across a ReSharper setting to enable just this. This setting can be enabled by going to ReSharper > Options > Environment > Editor > Editor Behaviour and selecting the Use CamelHumps checkbox.

The problem I’ve found when enabling this is the setting overwrites the default behaviour of CTRL  + ALT + Left / Right. Whilst this may be fine for some, I would rather the ability to choose when to highlight by word and when to highlight by camel case. Luckily you can do just this via the _ReSharperHumpPrev and _ReSharper_HumpNext_ commands that are available for binding in Visual Studio.

To do this do the following:

1. Open the Visual Studio Options window from Tools > Options
2. Expand Environment and scroll down to Keyboard
3. Map the two commands _ReSharper_HumpNext_ and _ReSharper_HumpPrev_ to the key mappings you wish (E.g. ALT+Right Arrow and ALT+Left Arrow) by selecting the command from the list and entering the key mapping in the Press shortcut keys text box, then click Assign.

Now, with UseCamelHumps enabled and my shortcut keys customised, I can choose between the default selection by string, or extend selection by camel case - giving me even more code-editing precision!

Initially, I started looking at the SimpleAuthentication library - but quickly realised ASP.NET Core already provided support for third party authentication providers via the Microsoft.AspNet.Authentication library.

Having implemented cookie based authentication I thought I’d take a moment to demonstrate how easy it is with ASP.NET’s new middleware functionality.

Let’s get started.

Sign up for Google Auth Service

Before we start, we’re going to need to register our application with the Google Developer’s Console and create a Client Id and Client Secret (which we’ll use later on in this demonstration).

1. To do this go to Google’s developer console and click “Create Project”. Enter your project name (in this instance it’s called BlogAuth) then click Create.
2. Next we need to enable authentication with Google’s social API (Google+). Within the Overview page click the Google+ API link located under Social API and click Enable once the Google+ page has loaded.
3. At this point you should see a message informing you that we need to create our credentials. To do this click the Credentials link on the left hand side, or the Go to Credentials button.
4. Go across to the OAuth Consent Screen and enter a name of the application you’re setting up. This name is visible to the user when authenticating. Once done, click Save.
5. At this point we need to create our ClientId and ClientSecret, so go across to the Credentials tab and click Create Credentials and select OAuth client ID from the dropdown then select Web Application.
6. Now we need to enter our app details. Enter an app name (used for recognising the app within Google Developer Console) and enter your domain into the Authorized JavaScript origins. If you’re developing locally then enter your localhost address into this field including port number.
7. Next enter the return path into the Authorized redirect URIs field. This is a callback path that Google will use to set the authorisation cookie. In this instance we’ll want to enter http://:/signin-google (where domain and port are the values you entered in step 6).
8. Once done click Create.
9. You should now be greeted with a screen displaying your Client ID and Client Secret. Take a note of these as we’ll need them shortly.

Once you’ve stored your Client ID and Secret somewhere you’re safe to close the Google Developer Console window.

Authentication middleware setup

With our Client ID and Client Secret in hand, our next step is to set up authentication within our application. Before we start, we first need to to import the Microsoft.AspNet.Authentication package (Microsoft.AspNetCore.Authorization if you’re using RC2 or later) into our solution via NuGet using the following command:

// RC1
install Microsoft.AspNet.Authentication

// RC2
install Microsoft.AspNetCore.Authorization

Once installed it’s time to hook it up to ASP.NET Core’s pipeline within your solution’s Startup.cs file.

First we need to register our authentication scheme with ASP.NET. within the ConfigureServices method:

public IServiceProvider ConfigureServices(IServiceCollection services)
{
    ...

    // Add authentication middleware and inform .NET Core MVC what scheme we'll be using
    services.AddAuthentication(options => options.SignInScheme = CookieAuthenticationDefaults.AuthenticationScheme);

    ...
}

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{

    ...
    // Adds a cookie-based authentication middleware to application
    app.UseCookieAuthentication(new CookieAuthenticationOptions
    {
        LoginPath = "/account/login",
        AuthenticationScheme = "Cookies",
        AutomaticAuthenticate = true,
        AutomaticChallenge = true
    });

    // Plugin Google Authentication configuration options
    app.UseGoogleAuthentication(new GoogleOptions
    {
        ClientId = "your_client_id",
        ClientSecret = "your_client_secret",
        Scope = { "email", "openid" }
    });

    ...

}

In terms of configuring our ASP.NET Core MVC application to use Google for authentication - we’re done! (yes, it’s that easy, thanks to .NET Core MVC’s middleware approach). 

All that’s left to do now is to plumb in our UI and controllers.

Setting up our controller

First, let’s go ahead and create the controller that we’ll use to authenticate our users. We’ll call this controller AccountController:

public class AccountController : Controller
{
    [HttpGet]
    public IActionResult Login()
    {
        return View();
    }

    public IActionResult External(string provider)
    {
        var authProperties = new AuthenticationProperties
        {
            // Specify where to return the user after successful authentication with Google
            RedirectUri = "/account/secure"
        };

        return new ChallengeResult(provider, authProperties);
    }

    [Authorize]
    public IActionResult Secure()
    {
        // Yay, we're secured! Any unauthenticated access to this action will be redirected to the login screen
        return View();
    }

    public async Task<IActionResult> LogOut()
    {
        await HttpContext.Authentication.SignOutAsync("Cookies");

        return RedirectToAction("Index", "Homepage");
    }
}

Now we’ve created our AccountController that we’ll use to authenticate users, we also need to create our views for the Login and Secure controller actions. Please be aware that these are rather basic and are simply as a means to demonstrate the process of logging in via Google authentication.

// Login.cshtml

<h2>Login</h2>
<a href="/account/external?provider=Google">Sign in with Google</a>

// Secure.cshtml

<h2>Secured!</h2>
This page can only be accessed by authenticated users.

Now, if we fire up our application and head to the /login/ page and click _Sign in with Google_ we should be taken to the Google account authentication screen. Once we click Continue  we should be automatically redirected back to our /secure/ page as expected!

This post serves as a review of how powerful the Razor tag engine is, but also a warning of potential pitfalls you may encounter as your codebase grows.

The power of ASP.NET Core MVC’s tag engine

For those of you that haven’t been keeping up to date with the changes in ASP.NET Core MVC, one of the new features included within Razor are Tag Helpers. At their essence, tag helpers allow you to replace Razor’s jarring syntax with a more natural HTML-like syntax. If we take moment to compare a new tag helper to the equivalent Razor function you’ll see the difference (remember, you can still use the HTML helpers, Tag helpers do not replace them and will happily work side by side in the same view).

// Before - HTML Helpers
@Html.ActionLink("Click me", "MyController", "MyAction", { @class="my-css-classname", data_my_attr="my-attribute"}) 

// After - Tag Helpers
<a asp-controller="MyController" asp-action="MyAction" class="my-css-classname" my-attr="my-attribute">Click me</a>

Whilst both of these will output the same HTML, it’s clear to see how much more natural the tag helper syntax looks and feels. Infact, with data prefix being optional when using data attributes in HTML, you could mistake the tag helper for HTML (more on this later).

Building your own tag helpers

It goes without saying that we’re able to create our own tag helpers, and this is where they get extremely powerful. Let’s start by creating a tag helper from start to finish. The follow example is a trivial example, but if you stick stick with me hopefully you’ll see why I chose this example as we near the end. So let’s begin by creating a tag helper that automatically adds a link-juice preserving rel=“nofollow” attribute to links outbound links:

public class NoFollowTagHelper : TagHelper
{
    // Public properties becomes available on our custom tag as an attribute.
    public string Href { get; set; }

    public override void Process(TagHelperContext context, TagHelperOutput output)
    {
        output.TagName = "a"; // Specify our tag output name
        output.TagMode = TagMode.StartTagAndEndTag; // The type of tag we wish to create

        output.Attributes["href"] = Href;
        if (!output.Attributes["href"].Value.ToString().Contains("josephwoodward.co.uk"))
        {
            output.Attributes["rel"] = "nofollow";
        }

        base.Process(context, output);
    }
}

Before continuing, it’s worth noting that our derived class (NoFollowTagHelper) is what will become our custom tag helper name; Razor will add hyphens between the uppercase character and then lowercase the string. It will also remove the word TagHelper from the class name if it exists.

Before we can use our tag helper we need to tell Razor where to find it.

Loading our tag helper

To load our tag helper we need to add it to our _ViewImports.cshtml file. The _ViewImport’s sole purpose is to reference our assemblies relating to the views to save us littering our views with references to assemblies. Using the _ViewImport we can do this in one place, much like we used to specify custom HTLM Helpers in the Web.config in previous versions of ASP.NET MVC.

// _ViewImports.cshtml
@using TagHelperDemo
@using TagHelperDemo.Models
@using TagHelperDemo.ViewModels.Account
@using TagHelperDemo.ViewModels.Manage
@using Microsoft.AspNet.Identity
@addTagHelper "*, Microsoft.AspNet.Mvc.TagHelpers"
@addTagHelper "*, TagHelperDemo" // Reference our assembly containing our tag helper here.

The asterisk will load all tag helpers within the TagHelperDemo assembly. If you wish to only load a single tag helper you can specify it like so:

// _ViewImports.cshtml
...
@addTagHelper "ImageLoaderTagHelper, TagHelperDemo"

Using our tag helper

Now that we’ve created our tag helper and referenced it, any references to elements will be transformed into no follow anchor links if the href is going to an external domain:

// Our custom tag helper
<no-follow href="http://outboundlink.com">Thanks for visiting</no-follow>
<no-follow href="/about">About</no-follow>

<!-- The transformed output -->
<a href="http://outboundlink.com" rel="nofollow">Thanks for visiting</a>
<a href="/about">About</a>

But wait! There’s more!

Ok, so creating custom no-follow tags isn’t ideal and is quite silly when we can just type normal HTML, so let’s go one step further. With the new tag helper syntax you can actually transform normal HTML tags too! Let’s demonstrate this awesomeness by modifiyng our nofollow tag helper:

[HtmlTargetElement("a", Attributes = "href")]
public class NoFollowTagHelper : TagHelper
{
    public override void Process(TagHelperContext context, TagHelperOutput output)
    {
        var href = output.Attributes["href"];
        if (!href.Value.ToString().Contains("josephwoodward.co.uk"))
        {
            output.Attributes["rel"] = "nofollow";
        }

        base.Process(context, output);
    }
}

As you’ll see, we’ve removed some redundant code and added the HtmlTargetElement attribute. This attribute is what allows us to target existing HTML elements and add additional functionality. Now, if we look at our Razor code ALL of our anchors have been processed by our NoFollowTagHelper class and only those with outbound links have been transformed:

<!-- Before -->
<a href="http://outboundlink.com">Thanks for visiting</a>
<a href="/about">About</a>

<!-- After -->
<a href="http://outboundlink.com" rel="nofollow">Thanks for visiting</a>
<a href="/about">About</a>

We’ve retrospectively changed the output of our HTML without needing to go through our codebase! For those that have worked on large applications and needed to create some kind of consistency between views, you’ll hopefully understand how powerful this can be and the potential use cases for it. In fact, this is exactly how ASP.NET uses the tilde (~/) to locate the path an img src path - see for yourself here.

Moving on

So far we’ve spent the duration of this blog post talking about how powerful ASP.NET Core MVC’s Tag Helpers, but with all great powers comes great responsibility - so let’s take a moment to look at the downsides of tag helpers and ways we can prevent potential pitfalls as we use them.

The Responsibility

They look just like HTML

When the ASP.NET team first revealed tag helpers to the world there were mixed reactions over the syntax. The powers of Tag Helpers were clear, but some people feel the blurring of lines between HTML and Razor breaks separation of concerns between HTML and Razor. Take the following comments taken from Scott Hanselman’s ASP.NET 5 (vNext) Work in Progress - Exploring TagHelpers post demonstrate the feelings of some:

What are the design goals for this feature? I see less razor syntax, but just exchanged for more non-standard html-like markup. I’m still fond of the T4MVC style of referencing controller actions.

This seems very tough to get on-board with. My biggest concern is how do we easily discern between which more obscure attributes are “TagHelper” related vs which ones are part of the HTML spec? When my company hires new devs, I can’t rely on the fact that they would realize that “action” is a “server-side” attribute, but then things like “media” and “type” are HTML … not to mention how hard it would be to tell the difference if I’m trying to maintain code where folks have mixed server-side/html attributes.

This lack of distinction between HTML and Razor quickly becomes apparent when you open a view file in a text editor that doesn’t support the syntax highlighting of Tag Helpers that Visual Studio does. Can you spot what’s HTML and what’s a tag helper the following screenshot?

The solution

Luckily there is a solution to help people discern between HTML and Razor, and that’s to force prefixes using the @tagHelperPrefix declaration.

By adding the @tagHelperPrefix declaration to the top of your view file you’re able to force prefixes on all of the tags within that current view:

// Index.cshtml
@tagHelperPrefix "helper:"

...

<div>
    <helper:a asp-controller="MyController" asp-action="MyAction" class="my-css-classname" my-attr="my-attribute">Click me</helper:a>
</div>

With a tagHelperPrefix declaration specified in a page, any tag helper that isn’t prefixed with the specified prefix will be completely ignored by the Razor engine (note: You also have to prefix the closing tag). If the tag is an enclosing tag that wraps some content, then the body of the tag helper will be emitted:

// Index.cshtml - specify helper prefix
@tagHelperPrefix "helper:"

...

<div>
    // Haven't specified helper: prefix
    <asp-controller="MyController" asp-action="MyAction" class="my-css-classname" my-attr="my-attribute">Click me</a>
</div>

<!-- Output without prefix: -->
<div>
    Click me
</div>

One problem that may arise from this solution is you may forget to add the prefix declaration to your view file. To combat this you can add the prefix declaration to the _ViewImport.cshtml file (which we talked about earlier). As all views automatically inherit from _ViewImport, our prefix rule will cascade down through the rest of our views. As you’d expect, this change will force all tag helpers to require your prefix - even the native .NET MVC tags including any anchors or image HTML tags that feature a tilde:

Unexpected HTML behaviour

Earlier in this article, the second version of NoFollowTagHelper demonstrated how we can harness the power of Tag Helpers to transform any HTML element. Whilst the ability to perform such transformations is a extremely powerful, we’re effectively taking HTML, a simple markup language with very little native functionality, and giving it this new power. 

Let me try and explain.

If you were to copy and paste a page of HTML into a .html file and look at it, you’d be confident that there’s no magic going on with the markup - effectively what you see is what you get. Now rename that HTML page to .cshtml and put it in an ASP.NET Core MVC application with a number of tag helpers that don’t require a prefix and you’ll no longer have that same confidence. This lack of confidence can create uncertainty in what was once static HTML. It’s the same problem you have when performing DOM manipulations using JavaScript, which is why I prefer to prefix selectors targeted by JavaScript with a ‘js’, making it clear to the reader that it’s being touched by JavaScript (as opposed to selecting DOM elements by classes used styling purposes).

To demonstrate this with an example, what does the following HTML element do?

<img src="/profile.jpg" alt="Profile Picture" />

In any other context it would be a simple profile picture from the root of your application. Considering the lack of classes or Id attributes you’d be fairly confident there’s no JavaScript targeting it too.

With Tag Helpers added to the equation this HTML isn’t what you expect. When rendered it actually becomes the following:

<img src="http://cdn.com/profile.mobile.jpg" alt="Profile Picture" />

Ultimately, the best way to avoid this unpredictable behaviour is to ensure you use prefixes, or at least be ensure your team are clear as to what tag helpers or are not active.

On closing

Hopefully this post has been valuable in highlighting the good, the bad and the potentially ugly consequences of Tag Helpers in your codebase. They’re an extremely powerful addition to the .NET framework, but as with all things - there is potential to shoot yourself in the foot.

What is fiddler?

Fiddler is a super powerful, free web debugging proxy tool created by the guys and girls at Telerik. Once launched, Fiddler will capture all incoming and outgoing traffic from your machine, allowing you to analyse traffic, manipulate HTTP (and HTTPS!) requests and perform a whole host of traffic based operations. It’s a fantastic tool for debugging and if you don’t have it I’d highly recommend you take a look at it. Did I say it’s 100% free too?

Capturing ASP.NET / IIS Traffic

By default, Fiddler is configured to register itself as the system proxy for Microsoft Windows Internet Services (WinInet) - the HTTP layer used by IE (and other browsers), Microsoft Office, and many other products. Whilst this default configuration is suitable for the majority of your debugging, if you wish to capture traffic from IIS (which bypasses WinInet), we’ll need to re-route our IIS traffic through Fiddler by modifying our application’s Web.config.

Step 1: Update your Web.config

To do this, simply open your Web.config and add the following snippet of code after the element.

<system.net>
    <defaultProxy enabled="true">
        <proxy proxyaddress="http://127.0.0.1:8888" bypassonlocal="False"/>
    </defaultProxy>
</system.net>

Step 2: Configure Fiddler to use the same port

Now that we’ve routed our IIS traffic through port 8888, we have to configure Fiddler to listen to the same port. To do this simple open Fiddler, go to _Tools > Fiddler Options_ > Connections then change the port listed within the “Fiddler listens on port” setting to 8888.

Now if you fire up your application you’ll start to see your requests stacking up in Fiddler ready for your inspection.

Happy debugging!

Let’s begin!

Step 1: Download the NuGet command line tool

First, you’ll need to download the NuGet command line tool. You can do this by going here and downloading the latest version (beneath the Windows x86 Commandlineheading).

Step 2: Add the NuGet executable to your PATH system variables

Now we’ve downloaded the NuGet executable we want to add it to our PATH system variables. At this point, you could simply reference the executable directly - but before long you’ll be wanting to contribute more of your libraries and adding it to your PATH system variables will save you more work in the long run.

If you already know how to add PATH variables then jump to Step 3, if not then read on.

Adding the nuget command to your PATH system variables

First, move the NuGet.exe you downloaded to a suitable location (I store mine in C:/NuGet/). Now, right-click My Computer (This PC if you’re on Windows 10). Click “Advanced System Settings” then click the “Environment Variables” button located within the Advanced tab. From here double-click the PATH variable in the top panel and create a new entry by adding the path to the directory that contains your NuGet.exe file (in this instance it’s C:/NuGet/).

Now, if all’s done right you should be able to open a Command Prompt window, type “nuget” and you’ll be greeted with a list of NuGet commands.

Step 3: Create a Package.nuspec configuration file

In short, a .nuspec file is an XML-based configuration file that describes our NuGet package and its contents. For further reading on the role of the .nuspec file see the nuspec reference on nuget.org.

To create a .nuspec package manifest file, let’s go to the root of our project we wish to publish (that’s where I prefer to keep my .nuspec file as it can be added to source control) and open a Command Prompt window (Tip: Typing “cmd” in the folder path of your explorer window will automatically open a Command Prompt window pointing to the directory).

Now type “_nuget_ spec” into your Command Prompt window. If all goes well you should be greeted with a message saying “Created ‘Package.nuspec’ successfully”. If so, you should now see a Package.nuspec file your project folder.

Let’s take a moment to look inside of our newly created Package.nuspec file. It should look a little like below:

<?xml version="1.0"?>
<package>
  <metadata>
    <id>Package</id>
    <version>1.0.0</version>
    <authors>Joseph</authors>
    <owners>Joseph</owners>
    <licenseUrl>http://LICENSE_URL_HERE_OR_DELETE_THIS_LINE</licenseUrl>
    <projectUrl>http://PROJECT_URL_HERE_OR_DELETE_THIS_LINE</projectUrl>
    <iconUrl>http://ICON_URL_HERE_OR_DELETE_THIS_LINE</iconUrl>
    <requireLicenseAcceptance>false</requireLicenseAcceptance>
    <description>Package description</description>
    <releaseNotes>Summary of changes made in this release of the package.</releaseNotes>
    <copyright>Copyright 2016</copyright>
    <tags>Tag1 Tag2</tags>
    <dependencies>
      <dependency id="SampleDependency" version="1.0" />
    </dependencies>
  </metadata>
</package>

As you can see, all of the parameters are pretty self-explanatory (see the docs here if you have any uncertainties on what the configuration does). The only one you may have a question about is the dependencies node - this is simply a list of the dependencies and their version that your NuGet package may have (See here for more info).

Now we’ve generated our NuGet configuration file, let’s take a moment to fill it in.

Once you’re done, your manifest file should look a little like below. The next step is to reference the files to be packaged. In the following example, you’ll see that I’ve referenced the Release .dll file (take a look at the documentation here for more file options). If you haven’t noticed, I’ve also removed the node as my package doesn’t have any additional dependencies.

<?xml version="1.0"?>
<package >
  <metadata>
    <id>Slugity</id>
    <version>1.0.2</version>
	<title>Slugity</title>
    <authors>Joseph Woodward</authors>
    <owners>Joseph Woodward</owners>
    <licenseUrl>https://raw.githubusercontent.com/JosephWoodward/SlugityDotNet/master/LICENSE</licenseUrl>
    <projectUrl>https://github.com/JosephWoodward/SlugityDotNet</projectUrl>
    <iconUrl>https://raw.githubusercontent.com/JosephWoodward/SlugityDotNet/release/assets/logo_128x128.png</iconUrl>
    <requireLicenseAcceptance>false</requireLicenseAcceptance>
    <description>Slugity is a simple, configuration based class library that's designed to create search engine friendly URL slugs</description>
	<language>en-US</language>
    <releaseNotes>Initial release of Slugity.</releaseNotes>
    <copyright>Copyright 2016</copyright>
    <tags>Slug, slug creator, slug generator, url, url creator</tags>
  </metadata>
  <files>
    <file src="bin\Release\Slugity.dll" target="lib\NET40" />
  </files>
</package>

Step 4: Creating your NuGet package

Once your Package.nuspec file has been filled in, let’s create our NuGet package! To do this simply run the following command, replacing the path to the .csproj file with your own.

nuget pack Slugity/Slugity.csproj -Prop Configuration=Release -Verbosity detailed

If you have the time, take a moment to look over the various pack command options in the NuGet documentation.

Once the above command has been run, if all has gone well then you should see a _YourPackageName._nupkg file appear in your project directory. This is our NuGet package that we can now submit to nuget.org!

Step 5: Submitting your NuGet package to nuget.org

We’re almost there! Now all we need to do is head over to nuget.org and submit our package. If you’re not already registered at nuget.org then you’ll need to do so (see the “Register / Sign in” link at the top right of the homepage). Next, go to your Account page and click “Upload a package”. Now all you need to do is upload your .nupkg package and verify the package details that nuget.org will use for your package listing!

Congratulations on submitting your first NuGet package!

I hope this guide has been helpful to you, and as always, if you have any questions then leave them in the comments!

I find learning on the job interesting for a few reasons. First of all, you spend a good portion of time at your computer programming. This very fact means you have plenty of opportunities to improve your knowledge and understanding of the language or framework you’re using. However, you also have to balance this opportunity with the fact that you’re working and have things to do and deadlines to meet. These external pressures mean you have to be smart about how you learn.

One of the strengths of a good developer is their ability to learn on the fly, and we should always be looking for opportunities to learn.

With this in mind. This post is a collection what I’ve found to be effective ways of learning on the job, whilst not letting it get in the way of your work.

REPLs, Fiddlers and online editors are your friends

REPLs are a great tool for learning. Within my browser’s bookmark toolbar I have a whole host of online REPLs or Fiddlers for different languages. Languages such as C#, TypeScript and JavaScript.

If I’m researching a problem or happen to come across some code that I’m struggling to understand, I’ll often take a moment to launch the appropriate REPL or Fiddler and experiment with the output to make sure I fully understand what the code is doing. These can be an invaluable tool for testing that base library function you’ve not never used before, test the output of the algorithm you’ve found or learn what your transpiled TypeScript code will look like. In fact, some online tools such as .NET Fiddle also have the ability to decompile code all the way to the IL/MSIL level - enabling you to gain an even greater understanding of what your code is doing.

Here are a few of the online tools I would recommend:

• .NET Fiddle (suitable for C#, F# and even VB.NET!)
• TypeScript Playground
• JS Fiddle or Plunker

This aptly brings me onto my next tip.

Don’t just copy and paste that code

Above I talked about REPLs and online Fiddlers. Use them! We’ve all copied and pasted some code on Stack Overflow to get something working. Take a moment to figure out exactly WHY the code is working and what your code is doing. Copying and pasting code that you don’t understand is both dangerous and a wasted opportunity to learn something new. If you’re too busy then bookmark it, or better yet - some of the editors listed above such as .NET Fiddle allow you to save snippets of code for later.

Write it down in a notepad

This tip I’ve found particularly effective and goes beyond learning whilst on the job, but I’ll expound on this in a moment.

If you stumble across one of those bits of information that you think “Wow, I didn’t know that. I should remember that!”, take a moment and write it down on a notepad. The process of writing it down helps your new found knowledge to your long-term memory. Another tip for further improving your long-term memory is to revisit some of your notes a couple of hours, or days later. Repetition is another proven way to improve the retention of such information.

Having a notebook on you is also useful when reading books. If you happen to read a sentence of paragraph whilst reading a book, take a moment to write it down in your own words in your notebook. I guarantee you’ll be able to recall the information later that day far clearer than you would have had you continued reading.

Share it with a co-worker or summarise it in a quick tweet

If you’ve just solved a problem or stumbled across a valuable piece of information then share it with your nearest co-worker. The very fact that you’re talking about it or explaining the concept will help engrain it into your long-term memory. You also have the added benefit of sharing information knowledge with others.

If no-one’s around then you could always talk it through with your rubber duck, or summarise your new knowledge in a quick tweet.

Stack Overflow

Stack Overflow is another great tool for learning on the job. If you’re a registered user then you should take full advantage of the ability to favourite answers or questions. Doing so enables you to review them in more detail at a time more suitable.

Pocket and other alternatives

Bookmark sites like Pocket are another powerful tool when it comes to learning on the job and go a step beyond bookmarking.

Whilst struggling with that problem, if you happened to have come across an interesting article but didn’t have the time to read it in its entirety then why not add it to your personal Pocket list and fill in the knowledge gap at a later date whilst you’re waiting for the bus. Many of the apps like Pocket include the ability to automatically sync bookmarks with your smartphone for offline viewing making it perfect for commuting.

I hope people find these tips valuable. I’m always interested in hearing other recommendations for learning on the job so if there’s anything I’ve not mentioned then please feel free to add it to the comments!

Introducing Slugity - The highly configurable C# slug generator

Whilst creating Slugity, my main focus was configure-ability. People, myself included, have opinions on how a URL should be formatted. Some people like the camel-case URLs that frameworks such as ASP.NET MVC encourage, other dogmatically favour lowercase slugs. Some people still like to strip stop-words from their slugs in order to shorten the overall URL length whilst retaining keyword density within their slugs. Having jumped from pattern to pattern across a variety of projects myself, I was keen to develop Slugity to cater to these needs.

Having been working on Slugity for a number of days now, below are the configuration end-points included in its first release:

• Customisable slug text case (CamelCase, LowerCase, Ignore)
• String Separator
• Slug’s maximum length
• Optional replacement characters
• Stop Words

Slugity setup and configuring

Given the fact that slugs aren’t the most complicated strings to get right, setting up Slugity is a breeze. It comes with a default configuration that should be suitable for the majority of its users, myself includes - but it’s simple enough to configure if the default settings don’t meet your requirements.

Using default configuration options:

var slugity = new Slugity();
string slug = slugity.GenerateSlug("A <span style="font-weight: bold">customisable</a> slug generation library");

Console.Log(slug); 
//Output: a-customisable-slug-generation-library

Configuring Slugity:

If Slugity’s default configuration doesn’t meet your requirements then configuration is easy:

var configuration = new SlugityConfig
{
    TextCase = TextCase.LowerCase,
    StringSeparator = '_',
    MaxLength = 60
};

configuration.ReplacementCharacters.Add("eat", "munch on");

var slugity = new Slugity(configuration);
string slug = slugity.GenerateSlug("I like to eat lettuce");

Console.Log(slug);
//Output: i_like_to_munch_on_lettuce

Moving forward I’d like to add the ability to replace the various formatting classes that are responsible for the various formatting and cleaning of the slug.

The code is currently up on GitHub and can be viewed here. I’m in the process of finishing off the last bits and pieces and then getting it added to NuGet, so stay tuned.

Update

The library has recently been added to NuGet and can be downloaded here, or via the following NuGet command:

Install-Package Slugity

Debugging code can be both hard and time-consuming. Thankfully, the guys over at OzCode have been working hard to battle the debugging time sink-hole by developing OzCode, a magically intelligent debugging extension for Visual Studio.

Remembering back to when I first installed OzCode (when it was in its beta stage!), it took all of a few minutes to see that the OzCode team were onto a winner. I clearly remember entering into debug mode by pressing F5 and watching my Visual Studio code window light up with a host of new debugging tools. Tools that I’ve been crying out for in Visual Studio (or other editors for that matter!) for a long time. In fact, OzCode has changed the way I debug altogether.

What does OzCode cost, and is it worth it?

Before continuing, let’s go over the price. OzCode is a paid for Visual Studio extension, coming in at an extremely reasonable $79 (£55) for a personal licence. Is it worth the money? Definitely.

I’m always happy to pay for good software and OzCode is no exception. Suffice it to say, it doesn’t take long to realise the value it provides and how quickly it pays for itself in the time it saves you. Don’t believe me? Go try the free 30-day trial and see for yourself. I purchased it as soon as it was out of public beta as it was clear it was worth the money.

It’s also worth mentioning that OzCode do provide open-source licences and to Microsoft MVPs.

So without further ado, let’s take a deeper look at OzCode and some of the features that make it one of the first extensions I install when setting up a new development machine, and why I think you’ll love it.

Magic Glance

OzCode’s magic glance feature is by far the biggest change to how you’ll debug your code, and probably the first thing you’ll notice when entering into debug mode. Normally, when you’re trying to find out the value of a variable or property within Visual Studio you need to hover over the variable(s) you’d like to inspect. This is less than perfect as the more variables you have to inspect then the more time it’ll take you hovering over them to keep track of what’s changing. This is what OzCode’s Magic Glance feature steps in.

With OzCode installed and Magic Glance at your disposal, you’re treated to a helpful display of variable/parameter values without the requirement to hover over them. This also helps you build a better mental model and holistic view of the data you’re debugging.

Reveal

Collections (or any derivative of an array) receive an even larger dosage of OzCode love with the Reveal feature. If you’ve ever had to view specific properties within a collection then you’ll know it’s not the most pleasant experience.

OzCode simplifies the process of reviewing data in a collection by providing you with the ability to mark properties within a collection as favourites (via a toggleable star icon) which make them instantly visible above the variable.

Search

Linked closely to the aforementioned Reveal function, Search adds the additional benefit of being able to search a collection for a particular value. To do this simply inspect the collection and enter the value you’re searching for. OzCode will then filter the results that match your input. By default OzCode will perform a shallow search on your collection (I’d imagine this is for performance purposes) - however, if your object graph is deeper then you can easily drill down even deeper.

Investigate

If you’ve ever had to split a complex expression up in order to see the values whilst debugging then OzCode’s Investigate feature will be music to your ears. When reaching a complex (or simple) if statement, OzCode adds visual aids to the expressions to indicate whether they’re true of false.

Quick Attach to a process

OzCode’s Quick Attach to a process feature is easily one of my most used features - and I’ll explain why in a second. Depending on your project type, you either have to enter debugging mode by pressing F5, or by manually attaching your build to a process. With OzCode, they’ve greatly simplified this process, and as a keyboard shortcut junkie - they’ve also provided shortcuts to make it even faster.

Using shortcuts to attach to a process via quickly became my de facto way of entering debugging mode, and it saves me a tonne of time. Friends and colleagues are often impressed at how quickly I’m able to enter debugging mode, to which I explain that it’s all thanks OzCode. Debugging is now a single keypress away and I love it! (as opposed to multiple clicks, or waiting for Visual Studio to launch my application in a new browser window)

Loads more features

These are just a few of my favourite features that easily make OzCode worth the money.

If you want to see a full list of features then I’d recommend taking a look over OzCode’s features page.

Features include:

• Predict the Future
• Live Coding
• Conditional Breakpoints
• When Set… Break
• Exceptions Trails
• Predicting Exceptions
• Trace
• Foresee
• Compare
• Custom Expressions
• Quick Actions
• Show All Instances

Future of OzCode

The future of OzCode is looking bright. With code analysis tools now being able to leverage Roslyn platform I can’t wait to see what wizardry the OzCode guys come up with next. For a sneak peek at some of the great features on the horizon I would definitely recommend this recent OzCode webinar. If you’ve only got a few minutes then I would highly recommend you take that time to check out the 28-minute mark at the LINQ visualisation.

Any questions about this review or OzCode itself then feel free to ask!

The Ajax response object pattern is an incredibly simple pattern to implement, but goes a long way to help promote a consistent API to handling most Ajax responses, and hopefully by the end of this post you’ll be able to see the value in implementing such an approach.

Before we dig into what the Ajax response object pattern is and how to implement it, let’s take a moment to look at the problem it aims to solve.

The common way to handle Ajax responses

Typically you’ll see a variation of the following approach to handling an asynchronous javascript response (the important part here is the handling of the response rather than how we created it), and whilst the code may vary slightly (the example used is a trivial implementation) hopefully it will give you an idea as to what we’re trying to do.

// The back end
public class ProfileController : Controller
{

    ...

    [HttpGet]
    public ActionResult GetProfile(int profileId)
    {
        var userProfile = this.profileService.GetUserProfile(profileId);

        return View(new ProfileViewModel(userProfile));
    }
}

// The Javascript / JQuery
$.ajax({
    type: "GET",
    url: "/Profile/LoadProfile/" + $('#userProfileId').val(),
    dataType: "html",
    success: function (data, textStatus, jqXHR) {
        $('#profileContainer').html(data);
    },
    error: function (jqXHR, textStatus, errorThrown) {
        // Correctly handle error
    }
});

As you can see from the above code all we’re doing is creating our asynchronous javascript request to our back end to retrieve a profile based on the profile id provided. The DOM is then updated and the response loaded via the call to JQuery’s html() method.

What’s wrong with this approach?

Nothing. There’s nothing wrong with this approach and it’s in fact, a perfectly acceptable way to perform and handle ajax requests/responses - however, there is room for improvement. To see what can be improved ask yourself the following questions:

1. What does our code tell us about the state of the ajax response?
   Judging by our code, we can tell that our HTTP request to our _LoadProfile_ controller action was successful as our success method is being invoked - however what does this REALLY tell us about the state of our response? How to do we know that our payload is in fact a user profile. After all, our success method (or our status code of 200 Ok) simply tells us that the server successfully responded to our HTTP request - it doesn’t tell us that our domain validation conditions within our service were met.

2. Is it easy to reason with?
   When programming we should always aim to write code succinct and clear. Code that leaves no room for ambiguity and removes any guesswork. Does the above solution do this?

3. How could we pass additional context to our Javascript?
   As we’re returning an HTML response to be rendered to the user, what happens if we wanted to pass additional context to the Javascript such as a notification of an error, or some data we wish to display to the user via a modal dialog?

4. Are we promoting any kind of consistency?
   What happens if our next Ajax response returns a Json object? That will need to be handled in a completely different way. If we have multiple developers working on a project then they’ll each probably implement ajax responses in various ways.

A better approach - let’s model our Ajax response

Object-orientated programming is all about modelling. Wikipedia says it best: 

Object-oriented programming (OOP) is a programming language model organized around objects rather than “actions” and data rather than logic.

To us mere mortals (as opposed to computers), modelling behaviour/data makes it easier for us to grasp and reason with - this premise is what helped make the Object-orientated programming paradigm popular in the early to mid-1990s. Looking back over our previous example, are we really modelling our response?

When we start passing values around (such as HTML in the previous example), we’re missing out on the benefits gained from creating a model around our expected behaviour. So, instead of simply returning a plain HTML response or a JSON object containing just our data, let’s try and model our HTTP response and see what benefits it will bring us. This is where the Ajax response object pattern can help.

The Ajax response object pattern

Implementation of the Ajax response object pattern simple. To resolve the concerns and questions raised above, we simply need to model our Ajax response, allowing to us to add additional context to our asynchronous HTTP response which we can then reason with within our Javascript.

The following example is the object I tend to favour when applying the Ajax response object pattern - but your implementation may vary depending on what you’re doing.

public class AjaxResponse
{
    public bool Success { get; set; }

    public string ErrorMessage { get; set; }

    public string RedirectUrl { get; set; }

    public object ResponseData { get; set; }

    public static AjaxResponse CreateSuccessfulResult(object responseData)
    {
        return new AjaxResponse
        {
            Success = true,
            ResponseData = responseData
        };
    }
}

We can then use the AjaxResponse object to model our HTTP response to something like the following:

[HttpGet]
public JsonResult GetProfile(int profileId)
{
    var response = new AjaxResponse();

    try
    {
        var userProfile = this.profileService.GetUserProfile(profileId);

        response.Success = true;
        response.ResponseData = RenderPartialViewToString("Profile", new ProfileViewModel(userProfile));
    }
    catch (RecordNotFoundException exception)
    {
        response.Success = false;
        response.ErrorMessage = exception.Message;
    }

    return Json(response, JsonRequestBehavior.AllowGet);
}

Earlier we were rendering the view and returning just the HTML payload in the response, now we need to render the view to a string and pass to the ResponseData property. This way we can make use of the additional properties such as whether the response the user is expecting was successful, if not then we can supply and error message. Because our ResponseData property is an object base type, we can use it to store any type, including Json.

Below is an implementation of the _RenderPartialViewToString_ method I often create in a base controller when writing ASP.NET MVC applications.

public class BaseController : Controller
{
    protected string RenderPartialViewToString(string viewName, object model)
    {
        if (string.IsNullOrEmpty(viewName))
        {
            viewName = this.ControllerContext.RouteData.GetRequiredString("action");
        }

        this.ViewData.Model = model;
        using (var stringWriter = new StringWriter())
        {
            ViewEngineResult partialView = ViewEngines.Engines.FindPartialView(this.ControllerContext, viewName);
            ViewContext viewContext = new ViewContext(this.ControllerContext, partialView.View, this.ViewData, this.TempData, (TextWriter)stringWriter);
            partialView.View.Render(viewContext, (TextWriter)stringWriter);
            return stringWriter.GetStringBuilder().ToString();
        }
    }
}

Now that we’ve modelled our response we have the ability to provide the response consumer far more context, this context enables us to better reason with our server response. In the cases where we may need to perform any kind of front end action based on the outcome of the response, we can easily do.

// The Javascript / JQuery
$.ajax({
    type: "GET",
    url: "/Profile/LoadProfile/" + $('#userProfileId').val(),
    dataType: "json"
    success: function (data, textStatus, jqXHR) {
        if (ajaxResponse.Success === true) {
            $('#profileContainer').html(ajaxResponse.ResponseData);
        } else {
            Dialog.showDialog(ajaxResponse.ErrorMessage);
        }
    },
    error: function (jqXHR, textStatus, errorThrown) {
        ...
    }
});

Additionally, if the approach is used throughout a team then you’re promoting a consistent API that you can build around. This makes the development of general error handlers far easier. What’s more, if you’re using TypeScript in your codebase then you can continue to leverage the benefits by casting your response to a TypeScript implementation of the ajaxResponse class and gain all the intelli-sense and tooling support goodness that comes with TypeScript.

// TypeScript implementation
export interface IAjaxResponse {
    Success: boolean;
    ErrorMessage: string;
    RedirectUrl: string;
    ResponseData: any;
}

That’s all for now. Thoughts and comments welcome!

Azure’s search platform has been on my radar for a while now, and having recently listened to an MS Dev Show interview with one of the developers behind Azure Search I was keen to give it a go.

This article serves as a high level overview as to how to get up and running with Azure Search service on your website or blog with a relatively simple implementation that could use some fleshing out. Before we begin it’s also worth mentioning that Azure’s Search service has some really powerful search capabilities that are beyond the scope of this article so I’d highly recommend checking out the documentation.

Azure Search Pricing Structure

Before we begin, let us take a moment to look at the Azure Search pricing:

One of the great things about Azure Search is it has a free tier that’s more than suitable for relatively low to medium traffic websites. What’s odd though is after the free tier there’s a sudden climb in price and specifications for the next model up - which I assume is because whilst it’s been available for a year, it’s still relatively new, so hopefully we’ll see more options become available moving forward but only time will tell; but as it stands the free tier is more than what I will need so let us continue!

Setting up Azure Search - Step 1: Creating our search service

Before we begin we’ve got to create our Azure Search service within Azure’s administration portal.

Note: If you’ve got the time then the Azure Search service documentation goes through this step in greater detail, so if you get stuck then feel free to refer to it here.

Enter in your service name (in this instance I used the name “jwblog”), select you subscription, resource group, location and select the free pricing tier.

Setting up Azure Search - Step 2: Configuring our service

Now that we’ve created our free search service, next we have to configure it. To do this click the Add Index button within the top Azure Search menu.

Add an index (see image above)

Once we’ve created our account next we need to decide which content we’re going to make searchable and reflect that within our search indexes. What Azure Search will then do is index that content, allowing it to be searched. We can do this either programatically via the Azure Search API, or via the Portal. Personally I’d rather do it up front in the Portal, but there’s nothing to stop you doing it in the code, but for now lets do it via the Azure Portal. In the instance of this post, we’d want to index our blog post title and blog post content as this is what we want the user to be able to search.

Setting retrievable content  (see image above)

When configuring our Azure Search profile we can specify what content we want to mark as retrievable, in this instance as I plan on only showing the post title on the search result page so I will mark the post title as retrievable content. As the search result page will also need to link to the actual blog post I will also mark the blog post id as retrievable.

Now we’ve set up and profile and configured it let’s get on with some coding!

Setting up Azure Search - Step 3: Implementing our search - the interface

Because it’s always a good idea to program to an interface rather than implementation, and because we may want to index other content moving forward we’ll create a simple search provider interface, avoiding the use of any Azure Search specific references.

public interface ISearchProvider<T> where T : class
{
    IEnumerable<TResult> SearchDocuments<TResult>(string searchText, string filter, Func<T, TResult> mapping);

    void AddToIndex(T document);
}

If you take a moment to look at the SearchDocuments method signature:

IEnumerable<TResult> SearchDocuments<TResult>(string searchText, string filter, Func<T, TResult> mapper);

You’ll see that we take a Func of type T and return a TResult - this will allow us to map our search index class (which we’ll create next) to a data transfer object - but more on this later. You’re also able to provide search filters to provide your website with richer searching capabilities.

Next we want to create our blog post search index class that will contain all of the properties required to index our content. As we’re creating a generic interface to our search provider we’re going to extend Azure Search’s AzureSearchIndex class. This allows us to create a BlogPostIndex class, but also gives us the scope to easily index other content such as pages (in which case we’d call it a BlogPageIndex).

What’s important to note is that the below BlogPostSearchIndex class is that our properties are the same name and type as the columns we configured earlier within Step 2 and that we’ve passed the index name to the base constructor.

// BlogPostSearchIndex.cs

[SerializePropertyNamesAsCamelCase]
public class BlogPostSearchIndex
{
    public BlogPostSearchIndex(int postId, string postTitle, string postBody)
    {
        // Document index needs to be a unique string
        IndexId = "blogpost" + postId.ToString();
        PostId = postId;
        PostTitle = postTitle;
        PostBody = postBody;
    }

    // Properties must remain public as they'll be used for automatic data binding
    public string IndexId { get; set; }

    public int PostId { get; set; }

    public string PostTitle { get; set; }

    public string PostBody { get; set; }

    public override string ToString()
    {
        return $"IndexId: {IndexId}\tPostId: {PostId}\tPostTitle: {PostTitle}\tPostBody: {PostBody}";
    }
}

Now that we’ve created the interface to our search provider we’ll go ahead and work on the implementation.

Setting up Azure Search - Step 5: Implementing our search - the implementation

At this point we’re now ready to start working on the implementation to our search functionality, so we’ll create an AzureSearchProvider class that extends our ISearchProvider interface and start fleshing out our search.

Before we begin it’s worth being aware that Azure’s search service does provide RESTful API that you can consume to manage and indexes, however as you’ll see below I’ve opted to do it via their SDK.

// AzureSearchProvider.cs

public class AzureSearchProvider<T> : ISearchProvider<T> where T : class
{
    private readonly SearchServiceClient _searchServiceClient;
    private const string Index = "blogpost";

    public AzureSearchProvider(SearchServiceClient searchServiceClient)
    {
        _searchServiceClient = searchServiceClient;
    }

    public IEnumerable<TResult> SearchDocuments<TResult>(string searchText, string filter, Func<T, TResult> mapper)
    {
        SearchIndexClient indexClient = _searchServiceClient.Indexes.GetClient(Index);

        var sp = new SearchParameters();
        if (!string.IsNullOrEmpty(filter)) sp.Filter = filter;

        DocumentSearchResponse<T> response = indexClient.Documents.Search<T>(searchText, sp);
        return response.Select(result => mapper(result.Document)).ToList();
    }

    public void AddToIndex(T document)
    {
        if (document == null)
            throw new ArgumentNullException(nameof(document));

        SearchIndexClient indexClient = _searchServiceClient.Indexes.GetClient(Index);

        try
        {
            // No need to create an UpdateIndex method as we use MergeOrUpload action type here.
            IndexBatch<T> batch = IndexBatch.Create(IndexAction.Create(IndexActionType.MergeOrUpload, document));
            indexClient.Documents.Index(batch);
        }
        catch (IndexBatchException e)
        {
            Console.WriteLine("Failed to Index some of the documents: {0}",
                string.Join(", ", e.IndexResponse.Results.Where(r => !r.Succeeded).Select(r => r.Key)));
        }
    }
}

The last part of our implementation is to set our configure out search provider with our IoC container of choice to ensure that our _AzureSearchProvider.cs_ class and its dependencies (Azure’s _SearchServiceClient_ class) can be resolved. Azure’s _SearchServiceClient.cs_ constructor requires our credentials and search service name as arguments so we’ll configure them there too.

In this instance I’m using StructureMap, so if you’re not using StructureMap then you’ll need to configure your IOC configuration accordingly.

public class DomainRegistry : Registry
{
    public DomainRegistry()
    {
        ...

        this.For<SearchServiceClient>().Use(() => new SearchServiceClient("jwblog", new SearchCredentials("your search administration key")));
        this.For(typeof(ISearchProvider<>)).Use(typeof(AzureSearchProvider<>));

        ...
    }
}

At this point all we need to do is add our administration key which we can get from the Azure Portal under the Keys setting within the search service blade we used to configure our search service.

Setting up Azure Search - Step 6: Indexing our content

Now that all of the hard work is out of the way and our search service is configured, we need to index our content. Currently our Azure Search service is an empty container with no content to index, so in the context of a blog we need to ensure that when we add or edit a blog post the search document stored within Azure Search is either added or updated. To do this we need to go to our blog’s controller action that’s responsible for creating a blog post and index our content.

Below is a rough example as to how it would look, I’m a huge fan of a library called Mediatr for delegating my requests but below should be enough to give you an idea as to how we’d implement indexing our content. We would also need to ensure we did the same thing for updating our blog posts as we’d want to ensure our search indexes are up to date with any modified content.

public class BlogPostController : Controller
{
    private readonly ISearchProvider<BlogPostSearchIndex> _searchProvider;

    public BlogPostController(ISearchProvider<BlogPostSearchIndex> searchProvider)
    {
        this._searchProvider = searchProvider;
    }

    [HttpPost]
    public ActionResult Create(BlogPostAddModel model)
    {
        ...

        // Add your blog post to the database and use the Id as an index Id

        this._searchProvider.AddToIndex(new BlogPostSearchIndex(indexId, model.Id, model.Title, model.BlogPost));

        ...
    }

    [HttpPost]
    public ActionResult Update(BlogPostEditModel model)
    {
        ...
        // As we're using Azure Search's MergeOrUpload index action we can simply call AddToIndex() when updating
        this._searchProvider.AddToIndex(new BlogPostSearchIndex(indexId, model.Id, model.Title, model.BlogPost));

        ...
    }

}

Now that we’re indexing our content we’ll move onto querying it.

Setting up Azure Search - Step 7: Querying our indexes

As Azure’s Search service is built on top of Lucene’s query parser (Lucene is well known open-source search library) we have a variety of ways we can query our content, including:

• Field-scoped queries
• Fuzzy search
• Proximity search
• Term boosting
• Regular expression search
• Wildcard search
• Syntax fundamentals
• Boolean operators
• Query size limitations

To query our search index all we need to do is call our generic SearchDocuments method and map our search index object to a view model/DTO like so:

private IEnumerable<BlogPostSearchResult> QuerySearchDocuments(string keyword)
{
    IEnumerable<BlogPostSearchResult> result = _searchProvider.SearchDocuments(keyword, string.Empty, document => new BlogPostSearchResult
    {
        Id = document.PostId,
        Title = document.PostTitle
    });

    return result;
}

At this point you have one of two options, you can either retrieve the indexed text (providing you marked it as retrievable earlier in step 2) and display that in your search result, or you can return your ID and query your database for the relevant post based on that blog post ID. Naturally this does introduce what is an unnecessary database call so consider your options. Personally as my linkes include a filename, I prefer to treat the posts in my database as the source of truth and prefer to check the posts exist and are published so I’m happy to incur that extra database call.

public IEnumerable<BlogPostItem> Handle(BlogPostSearchResultRequest message)
{
    if (string.IsNullOrEmpty(message.Keyword) || string.IsNullOrWhiteSpace(message.Keyword))
        throw new ArgumentNullException(nameof(message.Keyword));

    List<int> postIds = QuerySearchDocuments(message.Keyword).Select(x => x.Id).ToList();

    // Get blog posts from database based on IDs
    return GetBlogPosts(postIds);
}

Setting up Azure Search - Wrapping it up

Now we’re querying our indexes and retrieving the associated blog posts from the database all we have left to do is output our list of blog posts to the user.

I’m hoping you’ve found this general overview useful. As mentioned at the beginning of the post this is a high level overview and implementation of what’s a powerful search service. At this point I would highly recommend you take the next step and look at how you can start to tweak your search results via means such as scoring profiles and some of the features provided by Lucene.

Happy coding!

I feel formally setting yourself yearly goals is a great way to focus a set of specific, well thought out targets as opposed to spending the year moving from one subject to another with no real aim. So without further ado, here are my personal targets for 2016.

Goal 1: Speak at more conferences and meet-ups

Those of you that know me will know that when I start talking about programming and software development it’s hard to shut me up. Software and web development is a subject I’ve been hugely passionate about from a young age and since starting this blog I’ve found sharing knowledge and documenting progress a great way to learn, memorise get involved in the community. This desire to talk about software has ultimately led me to start speaking at local meet-ups (including a lunchtime lightning talk at DDD South West) which I’ve really enjoyed. This year I’d like to continue to pursue this by speaking at larger events and meet-ups that are further afield. I already plan on submitting a few talks to this year’s DDD South West event so we’ll see if they get accepted.

Goal 2: Start an Exeter based .NET User Group

Living in a rather quiet and rural part of United Kingdom has its pros and cons and whilst Somerset is a great place to live, it suffers from a lack of meet-ups, specifically .NET ones - this is something I’m hoping to rectify by starting up a .NET user group.

Whilst I don’t live in Exeter, it’s the closest place where I feel there will be enough interest for setting up a .NET specific user group, so I’m currently in the process of looking for a location on the outskirts of the city to make it easier for commuters living in some of the nearby towns and cities.

Goal 3: Continue contributing to the .NET OSS ecosystem

One of last year’s goals was to contribute to more open-source libraries, and whilst I felt I made good progress in achieving this goal I’m keen to continue working in this area. Not only do I want to continue to contribute to existing projects but I’m also keen to help others get involved in contributing to projects. It’s a really rewarding activity that can really help develop your skill set as a software developer, with this in mind I’ve been thinking of a few satellite sites that will help people get started.

I’m also thinking about a few talks that talk about how someone can get started and the lessons you can learn by contributing to open-source software.

In addition to the above, I’m also keen on contributing some of my own libraries to the .NET open-source ecosystem. More often than not I’ve found myself creating a few classes to encapsulate certain behaviour or abstract a third party API, yet I’ve never turned it into its own library. This year I’m keen to take that extra step and turn it into a fully fledged library that can be downloaded via NuGet.

Bonus Goal: F

Having been watching the F# community closely for some time now I’m really interested in what it has to offer, so this year I’m considering jumping in and committing myself to learning it and becoming proficient in it. I’ve got a few side projects I plan on working on that I feel will be a great place to use F# so we’ll see how that goes.

Conclusion

This concludes my personal targets for 2016. Whilst it’s not an exclusive list of what I will be focusing on, it’s certainly a list that I wish to feel I’ve made some progress on by the end of the year. I shall see how it goes and keep people updated.

Before I go into the details on the application, feel free to try it give it a try here.

The application

After playing with Angular 2 for a few evenings and liking what I was seeing, I decided I wanted to build something more real life than a throw-away To-Do list. Don’t get me wrong, there’s nothing wrong with building to-do lists, they’re a great way to get to grips with a framework, but nothing beats a real world project - with this in mind I decided to cross a side project off of my “apps to build” list and build a piano note trainer (source code available on GitHub).

As someone who is currently learning to play the piano and isn’t a great sight reader, I’ve been keen to develop a note trainer that records your progress over time to give you indicators as to just how well your sight reading is progressing.

So far the application is going well and I’m extremely impressed with Angular 2’s component based approach (heavily inspired by React if I’m not mistaken - but more on that in a moment). At the time of writing the application will generate random notes and draw them to the HTML 5 canvas whilst monitoring the user’s input to see if they press the appropriate key on the CSS based piano (credit to Taufik Nurrohman for the paino, it looks great and has saved me a tonne of time!). If the user presses the correct key then the application informs them of the correct key press and then moves onto another key. If the user fails to press the correct key then the application lets the user know and waits for them to try again.

As I continue to build the piano note trainer I’m finding Angular 2 feel more and more intuitive, and whilst Angular 2 is structurally different to Angular 1, it still feels quite similar in many ways - bar no controllers and the dreaded scope object.

Angular 2’s component based approach feels really nice, because we’ve learned over time that composition over inheritance the best way to build software

One of my main gripes with Angular 1 is the $scope object that was passed throughout an application and all too easily became a dumping ground of functions and data. This often inadvertently resulted in controllers taking on dependencies and quickly becoming tightly coupled to one another. Alternatively, the component based approach in Angular 2 naturally encourages encapsulated building blocks that contain the behaviour, HTML and CSS specific to the component and its role - the component can then expose a strict surface to its consuming components. This component based model follows the all too important _“composition over inheritance”_ approach and allows you to build your application out of a bunch of easily testable units.

For instance, if you were to take the following screenshot of the application in its current state and break it down into the various components it looks like this:

Overall I’ve been really happy with Angular 2 so far and can’t wait to see what tooling we start to see appear for it now that it’s using TypeScript. I can’t help but feel 2016 is going to be a big year for Angular.

The source code for the application is available on my GitHub profile and once finished I plan on submitting it to builtwithangular2.com. I’m hoping to have a live link once the application has reached a point that I’m happy with it to be used (I’ve still got to add sharp and flat notes which are causing some issues). In the mean time, feel free to give it a try via my GitHub profile.

These days the answer to the majority of a developer’s day to day questions are just a few clicks away and often rank quite highly on Google for the search term(s) making them even easier to find. And whilst the majority of us developers use it more than a few times a day I’m always quietly surprised when I see a developer browsing Stack Overflow looking for, or at, a solution to a problem they’re having yet they don’t have an account (its fairly easy to spot when someone doesn’t have an account from a distance as advertisements are visible between the answers).

When you ask someone who regularly uses Stack Overflow why they don’t have an account the response you usually get is ”I usually find the answer to my question so have no need to ask”, or ”I don’t plan on answering questions” - which are all perfectly valid reasons. But as developers when have we ever had an issue, fixed it and then remembered the solution to the problem the next time we ran into the same issue - days, weeks, months of ever years later? I feel I would be fairly safe in saying we’ve all had problems or questions we’ve needed to look for on more than one occasion. This is where Stack Overflow can be a huge help (not to mention you’ll be giving back to the community).

Leaving yourself upvote breadcrumbs to your technical issues

Next time you’re on Stack Overflow I would encourage you to take a moment to create an account, even if you don’t wish to fill out your profile - and the next time you find an answer to the problem you’re facing - simply upvote it. It takes a split second to do but that split second can save you minutes or potentially hours over your programming career. I can’t remember the number of times I’ve had an technical issue, gone searching for a solution on Stack Overflow and noticed I’d upvoted an answer a few months or years earlier.

Ultimately isn’t that one of the things we enjoy doing as developers? Look for ways to make difficult things simple? Next time make it easier to see signals through the noise by upvoting the solutions to your problems.

The book wasn’t referring directly to whether you’re just a consumer or things, or a creator of others - but more subtley teased a thought into the readers’ mind about the way they approached something. What, as a human or a developer, can I do in this instance to make something more useful to myself and others. With this slight shift of mindset you start to see new opportunities arising that you may have not seen before.

With this change of mindset I found myself asking why I wasn’t a member of Stack Overflow. As I searched and browsed Stack Overflow day by day I was in a pure consumer mode. I wasn’t giving anything back or making anything better as I took what others had spent time writing, without giving anything of value in return. When you ask someone who regularly visits Stack Overflow for answers to their questions why they don’t have an account you’ll regularly get responses such as “I don’t have time”, or “I don’t plan on answering questions” - which, whether you agree with them or not, are all perfectly valid reasons.

The problem with tracking code and single page applications

Traditionally, as your user navigates a normal website each page raises the Google Analytics pageview event (highlighted below).

<script>
  (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
  (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
  m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
  })(window,document,'script','//www.google-analytics.com/analytics.js','ga');

  ga('create', 'UA-xxxxxxxx-x', 'auto');
  ga('send', 'pageview'); // Pageview event
</script>

However within the single page application space things are slightly different. Once your initial page has loaded, all subsequent pages or views are rendered within the application without the need for a page refresh or page load - this means no further pageview events will be raised. This would result in very inaccurate visitor data as Google Analytics would capture the initial page load, and then ignore the duration of their session.

The solution

Having had to deal with this very same issue (though I needed to raise multiple custom events when certain functionality was used) just recently the solution I eventually settled with was a simple one.

First of all we want to break our Analytics code into two, allowing our Google Analytics tracking code to be registered (notice how I’ve removed the pageview event - we will call this later).

This code should be added into your main index.html page or your base Layout/template page.

...
</head>
<body>
<script>
  (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
  (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
  m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
  })(window,document,'script','//www.google-analytics.com/analytics.js','ga');

  ga('create', 'UA-xxxxxxxx-x', 'auto');
 // Pageview event removed so we can call it once the view has loaded.
</script>
<div class="wrapper">
...

Next we’re going to create a Google Analytics service (well call it GoogleAnalyticsService.js) that will be responsible for encapsulating our Analytics behaviour and used to manually raise our pageview event (and other events for that matter!) once the page has loaded. We can then inject our service into the appropriate Angular controllers and invoke the functions that will raise our Google Analytics events.

Take a moment to look at the Google Analytics page tracking documentation to see that we’re passing in a page path (excluding the domain - ie: /checkout/) to uniquely identify the page within our Analytics reports.

(function (angular, window) {

    "use strict";

    var ngModule = angular.module("ourAppModule");

    ngModule.factory("googleAnalyticsService", [
        "$window", function ($window) {

            var ga = $window.ga;

            var _pageView = function(page) {			
                ga("send" "pageview", {
                    page: page
                });
            };

            return {
                pageView: _pageView,
            };
        }
    ]);

})(window.angular);

Now that we’ve created our GoogleAnalyticsService we can simply inject it into our application’s controllers and invoke the pageView() function which in turn raises the Google Analytics pageview event.

Single page application version:

If your Angular application is a single page application then we can go one further and automatically call the pageview function once our view has loaded by adding the event to Angular’s $viewContentLoaded event listener, like so:

(function (angular, window) {

    "use strict";

    var ngModule = angular.module("ourAppModule");

    ngModule.factory("googleAnalyticsService", [
        "$window", function ($window) {

            var ga = $window.ga; //Google Analytics

            var _pageView = function(page) {			
                ga("send" "pageview", {
                    page: page
                });
            };

            var _viewChangePageView = function(scope, page) {
                if (scope){
                    scope.$on('$viewContentLoaded', function(event) {
                        _pageView(page)
                    });
                }
            };

            return {
                pageView: _pageView,
                viewChangePageView: _viewChangePageView // used for SPA
            };
        }
    ]);

})(window.angular);

From here all we need to do is invoke our method from our application’s controllers:

(function(angular, window) {

    'use strict';

    var app = angular.module('ourAppModule');
    app.controller('CheckoutController', ['$location', 'googleAnalyticsService', function($location, googleAnalyticsService) {
		...

		googleAnalyticsService.pageView($location.path());

		...
	}]);

})(window.angular);

Now when our user’s visit our application we should start seeing our visitors browsing data flooding into our Google Analytics account. You can verify this by setting Google Analytics into debug mode and using your browser’s console to see the events being raised. To do this simply replace the script source from analytics.js to analytics_debug.js.

<script>
  (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
  (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
  m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
  })(window,document,'script','//www.google-analytics.com/analytics_debug.js','ga'); //debug mode

  ga('create', 'UA-xxxxxxxx-x', 'auto');
</script>

Once we’ve verified that our events are being raised then switch your analytics path back to analytics.js and you’re good to go!

2015 has been a fantastic year for me for many reasons. Looking back at the targets I set myself for 2015 I’m happy with my progress, and whilst I’ve only met two of the four goals I set myself, I’m not going to be too hard on myself as I feel I’ve made up for it in other areas (which I’ll go through in a moment) to make up for the two targets missed.

Last year’s goals

Before setting my goals for 2016, let me take a moment to review last year’s targets and achievements:

Goal #1: Get dangerous with Javascript

During 2015 I’ve spent a great deal of time working on my Javascript knowledge, this includes:

• A Javascript based shooting game (written in TypeScript, but for those that are familiar with TypeScript will know that it’s essentially Javascript decorated with types)
• I’ve also spent a great deal of time really getting to grips with some of the fundamental design patterns commonly used in libraries such as the IIFE, Module Reveal pattern and so forth.
• In addition to the above, I’ve also had the opportunity to write a lot of Javascript in my previous job, and have recently started working in a web services based role that involves a lot of Javascript via Angular.
• Whilst learning Javascript I’ve also become a huge fan of TypeScript - so much so that I’ve given various workshops and talks at local user groups on the subject (more on this later though).

Whilst I wouldn’t consider myself ‘dangerous’ with Javascript, I feel I’ve reached a level where I’m confident in my ability and comfortable writing it. This is a goal I will continue to pursue in 2016.

Goal #2: Contribute to more open source projects

Shortly after committing to this goal I stumbled upon an awesome C# assertion framework called Shoudly via a tweet by its owner Jake Ginnivan (@JakeGinnivan). Jake was very welcoming of first time contributors and helped a great deal with any Git related issues encountered as I stumbled my way through getting to grips with both the Shoudly codebase and contributing to it.

Today I still enjoy contributing to Shoudly and have been honoured to be added as a core contributor to the project. Jake’s been paving the way with some truly inspiring work (including DNX support!) on the library and I look forward to continuing to contribute to it this year.

As a slight aside - if anyone is interested, as I was this time last year, in getting involved in contributing to an open source library then we’re an extremely friendly bunch always looking for new contributors. I’d be happy to help you make your first contribution to Shouldly.

Goal #3: Increase the frequency of my blog posts

As many developers will know, blogging isn’t easy. It takes time, effort and a log of research to write blog posts that are of any real value to people and whilst I’ve remaind consistent with my blogging throughout the year, the frequency of my posts isn’t at a level that I am happy with. This is something I’m looking to rectify in 2016.

Bonus Goal: Achieve over 8,000 points on Stack Overflow

When writing about this goal last year, I felt aiming to achieve over 8,000 points on StackOverflow was a little ambitious - especially considering the scope of the other (what I considered to be more important) goals, so suffice to say I fell short of the 8,000 points mark.

Other noticable achievements in 2015

In addition to the above goals, 2015 was also an exciting year for me for the following reasons:

.NET Rocks Interview

When writing my 2015 goals, if you’d told me I’d be appearing on .NET Rocks by the end of the year I’d have told you to stop pulling my leg. But on December 10th my interview discussing Visual Studio shortcuts and productivity boosts was published. You can read more about the episode here.

I started talking regularly at local meet ups

Whilst I’ve been attending local meet ups for a little while now, I’ve also started talking at them too. Originally it started with a TypeScript talk at a local gathering, then moved to the same talk but in a lighting talk format at DDD South West, to a TypeScript workshop and a further talk on JavaScripts IFFE pattern. This is certainly something I wish to continue doing in 2016.

Overall I’ve been very satisfied with 2015; the highlight(s) of the year have got to go to being made a core contributor to Shoudly, alongside being featured on .NET Rocks. I hope everyone else has had a great year and I wish everyone the best for 2016!

Stay tuned for my goals for 2016!

With the release of C# 6 this problem and instances like can be easily avoided with the introduction of the nameof expression.

C#6 nameof expression

The nameof expression is a simple solution to the problem, see the follow snippets from the MSDN docs for an example of how the nameof expression can be is used:

void f(string s) {
    if (s == null) throw new ArgumentNullException(nameof(s));
}

Using the nameof expression in Razor becomes especially helpful:

<%= Html.ActionLink("Sign up", @typeof(UserController), @nameof(UserController.SignUp)) %>

What’s happening under the hood?

As it’s always a good idea to understand how things are interpreted when compiled, let’s take a look and see exactly what happens to the following code sample:

public class Class1
{
    public void Output(string myString)
    {
        if (myString == null)
        {
            throw new ArgumentNullException(nameof(myString));
        }
    }
}

When we use a tool like JetBrain’s free decompiler DotPeek to take a look at the decompiled source you can see that the property passed into the nameof expression has now been evaluated at compile time and converted into a string literal representation of the parameter:

public class Class1
{
	public void Output(string myString)
	{
		bool flag = myString == null;
		if (flag)
		{
			throw new ArgumentNullException("myString");
		}
	}
}

The result is the exact equivalent of what you’d normally do without the nameof expression - except this time you have the added benefit of compile time safety, rather than having to rely on magic strings (something that’s extremely helpful when using refactoring tools to rename classes, properties or methods).

With this in mind, that means if we were to take the following with and without _nameof_ examples and view the IL code generated then they should be exactly the same:

// With nameof expression:
string myString = "Hello World";
throw new ArgumentNullException(nameof(myString));

// Without nameof expression:
string myString = "Hello World";
throw new ArgumentNullException("myString");

IL code generated when using the nameof expression:

IL_0000:  nop
IL_0001:  ldstr      "Hello World"
IL_0006:  stloc.0
IL_0007:  ldstr      "myString"
IL_000c:  newobj     instance void [mscorlib]System.ArgumentNullException::.ctor(string)
IL_0011:  throw

IL code generated when not using the nameof expression:

IL_0000:  nop
IL_0001:  ldstr      "Hello World"
IL_0006:  stloc.0
IL_0007:  ldstr      "myString"
IL_000c:  newobj     instance void [mscorlib]System.ArgumentNullException::.ctor(string)
IL_0011:  throw

We can see that the output is identical.

If that isn’t proof enough that you should favour using the nameof expression over magic strings then I don’t know what is!

Update:
If you’re keen to go even further into the nameof expression then @ErikSchierboom has written an extremely indepth look at what’s happening under the bonnet in his C# 6 under the hood: nameof operator article that I’d highly recommend reading.

Last week I had the pleasure of speaking with both Carl Franklin and Richard Campbell as part of a .NET Rocks episode talking about areas of a subject I have a great interest in - mastering your toolset. In this particular show we spent most of the time covering the most important shortcuts you can learn to increase your productivity but also touched on some of the finer details about the what, where and why you should spend time dedicated to turning these shortcuts into habits and ultimately muscle memory; to the point where you perform them instinctively.

If you’ve read my 9 ways I improved my productivity in Visual Studio 2013 blog post then some of the shortcuts and features will be familiar to you, however we discuss some that aren’t on the list that I’d highly recommend checking out.

The show is published on the 10th of December and can be downloaded via the .NET Rocks website or most Podcast aggregators.

Update

You can now download my talk with Carl and Richard via the .NET Rocks website.

I’m overwhelmed with the amount of positive feedback I’ve had from the show via Twitter, emails and the sheer number of comments it has received on the .NET Rocks Show website. Going into the show I had my concerns listeners may not find it an interesting subject from the outset, but to the contrary it seems like it resonates with a lot of developers which is fantastic to see!

After a week of programming on my new Surface Pro 3 I decided to put together a rather lengthy post detailing my thoughts and experiences of using the device as a development machine, and whilst the I was, and still am extremely happy with the Surface Pro 3, one aspect that I felt was really lagging was the keyboard - my main criticism being that the keys were too close together and the trackpad wasn’t accurate enough, and slightly on the small side for my liking. It seems that these criticisms weren’t just ones shared by me, but by many others - but with the release of the Surface Pro 4 and the backwards compatible Surface Pro 4 Type Cover it’s clear that Microsoft have been listening to the feedback as the 4’s Type Cover goes a long way in correcting these niggles.

In addition to improvements over the existing Type Cover Microsoft released a version that includes a fingerprint scanner - however it doesn’t look like it’s going to be released in the UK any time soon so being the impatient person I am, I went ahead and ordered myself a standard Type Cover.

The keyboard

The biggest improvement between the Surface Pro 3 keyboard and the 4 is the keyboard size. The keyboard itself has increased further to the edges of the Type Cover with the additional room allowing for much needed gaps between the keys. As someone with rather fat fingers this gap between the keys has gone a long way to increasing my typing accuracy, and thus speed - something extremely important for someone who does  a lot of programming on the Surface Pro 3.

I addition to the aforementioned key spacing, the keys feel a lot more solid than the previous keyboard - it’s minor but it definitely lends to the typing experience on the new keyboard.

Other improvements that have been made to the keyboard are:

• The FN (function) key now features a small light so you know whether your function keys are active or not.
• The keyboard now features a dedicated print screen button and insert key.

The Trackpad

The next major improvement the Surface Pro 4 Type Cover has undergone in comparison to predecessor is the track pad. Not only is the track pad larger (Microsoft say 40% larger) but it’s also made of glass - resulting in it being far smoother and FAR MORE responsive. Whilst the Surface Pro 3’s track pad was enough to get the job done, I would never have said it was pleasurable to use. It always felt like hard work - however these recent changes have resulted in a much better experience.

Overall, if you’re an owner of a Surface Pro 3 and you want to give your device a brand new lease of life then I’d highly recommend upgrading to the Surface Pro 4 Type Cover.

Before I continue if there are any podcasts that any readers of my blog would recommend then I’m always keen to be introduced to new ones, so please feel free to comment!

.NET Rocks!

Website URL: http://www.dotnetrocks.com
Release Frequency: 3 times a week (Tuesday, Wednesday and Thursday)
Average Episode Duration: 60 minutes

.NET Rocks! is easily the staple of my podcasts. With over 1159 episodes in their show archive hosts Carl Franklink and Richard Campbell do a fantastic job of delivering a great, high-production value podcast that features a broad range of .NET (and on occasion not do .NET) focused podcasts. Carl and Richard travel around creating their podcasts, presenting opporunities to interview some really high profile members of the .NET community. .NET Rocks especially deserves my number 1 spot for the sheer number of episodes they’ve released over the years and the regularity of their releases.

MS Dev Show

Website URL: http://msdevshow.com
Release Frequency: Once a week
Average Episode Duration: 60 minutes

MS Dev Show is a recent addition to my long list of favourite development related podcasts but has certainly left a good impression. Since first learning about MS Dev Show just a few weeks ago I’ve already made a good start on burning my way through their archive.

Hanselminutes

Website URL: http://hanselminutes.com
Release Frequency: Once a week
Average Episode Duration: 30 - 40 minutes

Along with the aforemention podcasts, I would also highly recommend Scott Hanselman’s Hanselminutes podcast. Having been listening to Hanselminutes long before I got into the .NET world, I’ve always been a great admirer of Scott Hanselman’s ability effortlessly communicate concepts, ideas and thoughts in a clear manner - if he has the ability to slow down time to find the perfect word or sentence that expresses what he’s trying to communicate. Whilst not all episodes are development related, they’re always insightful and interesting.

Developer On Fire

Website: http://developeronfire.com
Release Frequency: Twice a week
Average Episode Duration: 30 - 60 minutes

Developer On Fire is a recent addition to my podcast list (when I say recent, I mean ⁶⁄₈ months) but has quickly become one of my favourites due to presentation format and the topics discussed. Where as a lot of the podcasts listed are more technology focused (where a guest comes on to discuss a particular topic), Developer On Fire does something a little different and talks about the guests more personal relation with the software industry, encouraging them to share experiences and tips with a real focus on delivering value.

The host, Dave Rael presents the show really well and does a great job of keeping the guests talking, teasing interesting stories, tips and recommendations out of them throughout - often ending with a great question where he asks for two or three book recommendations for the listeners - books that on occasion I’ve actually gone and purchased as a direct result of the recommendation. 

Eat, Sleep, Code

Website URL: http://developer.telerik.com/community/eat-sleep-code/​
Release Frequency: Twice a month
Average Episode Duration: 30 - 40 minutes

Eat Sleep Code is a podcast created by the guys and girls over at Telerik and is certainly worth adding to your podcast aggregator of choice. Each episode spans between 30 to 40 minutes and is a healthy mix of programming related subjects ranging from .NET to Javascript and mobile development.

Herding Code

Website URL: http://herdingcode.com
Release Frequency: Once a month, sometimes longer
Average Episode Duration: 20 - 30 minutes

Herding Code is another get .NET focused podcast that regularly features a variety of subjects ranging from software architecture to mobile phones and javascript libraries. Whilst I would definitely recommend adding it to your podcast aggregator of choice be aware that the eposide release cycle is rather inconsistent.

Software Engineering Radio

Website URL: http://www.se-radio.net
Release Frequency: 2 or 3 times a month
Average Episode Duration: 60 minutes

Whilst not specifically .NET focused (more Java) but often featuring more advanced subjects that apply to general application development, Software Engineering Radio deserves a mention for its sheer technical depth of discussions.

Javascript Jabber

Website URL: https://devchat.tv/js-jabber
Release Frequency: Once a week
Average Episode Duration: 1 hour

Whilst Javascript Jabber is not a .NET focused podcast, with way the .NET and application development landscape is changing most of us .NET (specifically ASP.NET) developers are no doubt familiar with Javascript or will become increasingly familiar with it over the next few years - especially with tooling changes we’re seeing in ASP.NET MVC 6. For this reason I feel Javascript Jabber deserves a place on the list. Javascript Jabber regularly features a variety of guests, most often Ruby related, however the hosts do a great job of keeping it Javascript focused. Personally I’ve found Javascript Jabber a great way to keep upto date with the never ending emergence of Javascript libraries.

That’s it for now. I’m always on the lookout for new podcasts to ease my commute so feel free to mention any I’ve missed in the comments below and I’ll be sure to add them to the list!

Having been playing around with Roslyn for a couple of days now I thought I’d share a cool snippet of code I put together to demonstrate how easy it is to parse C# code using the power of just a few Roslyn NuGet packages.

In this using Roslyn to analyse an existing codebase and flag any classes that are guilty of the ’Too many parameters’ code smell.

First, let’s load the solution:

First of all we’re going to need to load our solution…

public static class WorkspaceSolution
{
    public static IEnumerable<Document> LoadSolution(string solutionDir)
    {
        var solutionFilePath = Path.GetFullPath(solutionDir);

        MSBuildWorkspace workspace = MSBuildWorkspace.Create();
        Solution solution = workspace.OpenSolutionAsync(solutionFilePath).Result;

        var documents = new List<Document>();
        foreach (var projectId in solution.ProjectIds)
        {
            var project = solution.GetProject(projectId);
            foreach (var documentId in project.DocumentIds)
            {
                Document document = solution.GetDocument(documentId);
                if (document.SupportsSyntaxTree) documents.Add(document);
            }
        }

        return documents;
    }
}

As you can see from the above snippet this is actually quite simple thanks to the Microsoft.CodeAnalysis.MSBuild package, more specifically the MSBuildWorkspace class. This allows us to scan our solution and create a collection of any documents within it.

Analysing the documents (aka. class files)

Now we’ve got a list of all of the documents within our solution we can begin to iterate through them, parsing the syntax tree until we come to the method parameters (though performing the same analysis on constructors is equally as easy - but for the sake of this demonstration we’ll look at methods).

At this point we can check to see if the number of parameters exceeds our threshold.

List<MethodDeclarationSyntax> methods = documents.SelectMany(x => x.GetSyntaxRootAsync().Result.DescendantNodes().OfType<MethodDeclarationSyntax>()).ToList();

var smellyClasses = new Dictionary<string, int>();
int paramThreshold = 5;
foreach (MethodDeclarationSyntax methodDeclarationSyntax in methods)
{
    ParameterListSyntax parameterList = methodDeclarationSyntax.ParameterList;
    if (parameterList.Parameters.Count >= 5)
    {
        smellyClasses.Add(methodDeclarationSyntax.Identifier.SyntaxTree.FilePath, parameterList.Parameters.Count);
    }
}

Let’s put it to use

If you’re still not sold on how powerful this can be, let’s move this into a unit test that can easily be included as a base suite of unit tests - allowing us to easily enforce rules on our development teams.

[TestCase(5)]
public void Methods_ShouldNotHaveTooManyParams(int totalParams)
{
    List<MethodDeclarationSyntax> methods = this.documents.SelectMany(x => x.GetSyntaxRootAsync().Result.DescendantNodes().OfType<MethodDeclarationSyntax>()).ToList();
    foreach (MethodDeclarationSyntax methodDeclarationSyntax in methods)
    {
        ParameterListSyntax parameterList = methodDeclarationSyntax.ParameterList;

        // Assert
        parameterList.Parameters.Count.ShouldBeLessThanOrEqualTo(totalParams, "File Location: " + methodDeclarationSyntax.Identifier.SyntaxTree.FilePath);
    }
}

As you’ll see in the code snippet below we then use Shouldly unit testing framework and its awesome error messages to inform us of the class that’s currently violating our code smell rule!

If you’re interested in having a play with this then you can find the code up on GitHub here. I’d also recommend checking out this post if you’re interested in learning more about Roslyn and how it works. Another great resource that gave me the idea for using Roslyn to create tests is this strathweb.com blog post by @filip_woj.

Recently I was writing some Javascript for a responsive HTML5 front end that I was working on and needed to find out what CSS media breakpoint the browser was currently in. Naturally my initial reaction was to use Javascript to detect the browser width and go from there; however doing it this way immediately felt dirty as it would result in a duplication of breakpoint values throughout the application - something I was keen to avoid.

After a bit of head-scratching the solution I ended up with was to target the device specific show/hide classes that most CSS framework provide.

In the following primitive example I’m using the Unsemantic CSS grid framework, but almost all CSS frameworks provide similar classes - though even if you’re not using a framework there’s nothing to stop you from creating your own.

HTML:

<a href="#" id="clickMeButton">Click Me</a>

<!-- These can go just before the </body> tag -->
<div class="show-on-desktop"></div>
<div class="show-on-mobile"></div>

CSS:

.show-on-desktop { display: none;}
.show-on-mobile { display: none; }

/* Mobile */
@media (max-width: 300px) { 
    .show-on-mobile { display: block; }
}

/* Desktop */
@media (min-width: 301px) {    
    .show-on-desktop { display: block; }
}

Javascript:

$(function(){

   $('#clickMeButton').on('click', function(){
       if($('.show-on-desktop').is(':visible')){
           alert('desktop');
       } else if ($('.show-on-mobile').is(':visible')){
           alert('mobile'); 
       }
	}); 

});

You can check out this JSFiddle to see a working example of the above code - if you resize the browser and click the button you’ll notice the alert message will change from “Desktop” to “Mobile”.

Whilst looking at similar solutions I found this StackOverflow answer which goes one further and turns the same approach into a Bootstrap plugin for easier use - awesome!

When I first decided to start a development blog I wasn’t sure as to how much time I’d be able to dedicate to it and was concerned that, like many blogs online, my post frequency would start out string but begin to dwindle over time until it was never touched again.

With this uncertainty in mind, I didn’t want to spend too much time putting together a blog so I bought a domain and setup WordPress on my Linux VPS with a simple, only slightly customised template with the intention to see how I got on.

Fast forward just over a year now and I’m still blogging with reasonable frequency and feel I have gotten to a point where I feel it’s safe to say that I won’t be stopping any time soon. The rewards of blogging about programming related subjects have become clear to me and I’ve learned a great deal from investigating a subject enough to confidently write a blog post; and with this in mind I decided it was time to commit to spending some time and effort in updating my upgrading my blog to aid reader retention and act a platform for me to continually develop and evolve over time.

About the new blog

Whilst I was perfectly happy with WordPress as a blogging platform (I have reservations about the language used to create it but that’s another story!), I was keen to develop a solution in ASP.NET, and whilst conscious that I did not want to reinvent the wheel, I built myself a simple administration area that I can use to create and maintain posts. I’ve also been looking at other design patterns and techniques over the past few months and creating a blog seemed the perfect way to put some of them to practice and live with them a while to see their worth.

For those interested in what I used under the hood, below is the technology stack and why I chose to use them:

ASP.NET MVC

Being an ASP.NET developer MVC was an obvious choice. It’s a great, extensible framework that I love the more and more I use. I was tempted to dive into using ASP.NET MVC vNext but I decided to wait a bit until I cross that bridge, but it’s certainly something I entend on doing.

Dapper ORM

Initially I started out using Entity Framework, but given the simplicity of the blog and desire for speed, decided to give StackOverflow’s Dapper ORM a try. It’s a mega lightweight ORM created and used internally by StackOverflow who built it with speed in mind. I’ve really enjoyed using it and will no doubt be using it couldn’t recommend it enough when simplicity and speed are what you’re after. As an example of what Dapper does, among many of the other benefits, Dapper allows you to easily hydrate POCO objects like so:

public class Dog
{
    public int? Age { get; set; }
    public Guid Id { get; set; }
    public string Name { get; set; }
    public float? Weight { get; set; }

    public int IgnoredProperty { get { return 1; } }
}            

var guid = Guid.NewGuid();
var dog = connection.Query<Dog>("select Age = @Age, Id = @Id", new { Age = (int?)null, Id = guid });

dog.Count()
    .IsEqualTo(1);

dog.First().Age
    .IsNull();

dog.First().Id
    .IsEqualTo(guid);

Dapper also allows you to map a single row to multiple objects and allows you to process multiple result grids in a single query.

MediatR

This was an interesting choice and proved a real eye-opener to me.

I’ve always found software architecture an interesting subject and one that I’ve always gravitated towards, and being a frequent reader of Jimmy Bogard’s blog (creator of AutoMapper, and technical architect at Headsprings in Austin,Texas), I found his Putting your controllers on a diet blog posts particularly interesting as they introduced me to Command - Query Separation (CQS), and an alternative approach to the typical n-tier architecture that any enterprise developer will be familiar with - and Mediatr is a 

Being a separate subject in itself that deserves its own blog post, CQS is the process of breaking a solution down into simple, isolated Command or Queries; in this instance, using Jimmy Bogard’s MediatR library. When you do this you realise that the service layer becomes redundant and your code can becomes far more succinct and expressive.

Azure

I’ve been playing around with Azure for sometime now and decided to use it as my hosting provider. Using a shared instance that costs just a few pounds a month, Azure has done a great job in removing many of the issues you can have when setting up a website.

As a software developer, the main benefit you get from setting yourself yearly goals like this is it forces you to look at your existing strengths and weaknesses (we all have weaknesses, we just need to be honest about them) and areas that you feel can be improved. This means that throughout the year as you work towards improving these areas that are lacking, you’re focused on exactly were you need to spend time to improve to ensure that year on year you’re going in the right direction and that in 3 years time when you look back at yourself 3 years ago, you’ll see that you have improved and haven’t stagnated.

I always feel it’s important to set yourself only a few goals, 3 or 4 at the most. Setting yourself anything more can start to become unrealistic and can often result in you not spending enough time on each goal, or spreading your time to thin, resulting in no noticeable improvement over the year.

So here are my goals for 2015:

Goal 1: Get dangerous with Javascript

Whilst I’ve always been comfortable writing JQuery, and to a lesser form Javascript; I’ve always felt that my knowledge in the area was patchy. I can get by with it, but I feel there is room for improvement.

As I consider myself a polyglot programmer I feel being dangerous with Javascript will be another string to my bow as a software developer for the following reasons:

• Whether you love or hate Javascript, there’s one thing for sure and that is that it’s here to stay.
• Javascript is a great transferable skill to have. You may move from one language to another (say C# to Java, or .NET to Play Framework or Ruby), but providing you’re still working on a web stack then your Javascript skill remain.
• I strongly believe that having strong front end skills is a great way to separate yourself from other developers.

So this year my main goal is to improve really develop my Javascript knowledge and skills.

Goal 2: Contribute to more open source projects

Having always been a great supporter of the open source software movement (not to mention a consumer of open source software too!) this year I’m keen to find some projects to get involved in. I’m also keen to get working on developing and open sourcing some more projects.

Whilst I have contributed to open source projects in the past, I don’t feel I’ve added as much value as I could do. Generally a lot of my contributes have been documentation and UI related issues, which, whilst important - don’t give you the added valuable feedback and learning you gain when committing code and having other developers review your code.

As well as contributing to existing open source projects, I’m also keen to start a few of my own. Whilst I do have one or two projects currently on my GitHub account that have users, I’m keen to write some more as I find writing a plugin or a piece of software that other’s find useful is a rewarding experience.

(Since writing this post I’m already on my way to acheving this goal which you can read about here).

Goal 3: Increase the frequency of my blog posts

Another of my goals this year is to increase the frequency of my blog posts.

Having only started blogging this year I’ve found it an incredibly rewarding and valuable experience. It’s great getting feedback from other people and writing blog posts about programming topics really does help drill the subject matter into your brain.

When starting out blogging I felt no one would take much interested in some of the subjects I wanted to discuss - especially when you take into consideration the plethora of other great resources/developer blogs online. Yet I’ve been pleasantly surprised by the attention some of the posts has received. So this year I’m going to try and improve on the frequency of my blog posts.

I’d really like to achieve a blog post a week but whether I can get my thoughts out on paper that quickly is another story.

Bonus Goal: Achieve over 8,000 points on Stack Overflow

Over the past few months I’ve become quite active on Stack Overflow. I particularly enjoy answering questions relating to StructureMap. At the time of writing I have 2,266 points to my name - with an aim of making it to 8,000 by the end of the year. This, I feel is going to be a challenging figure to reach, but one that is achievable.

I’ve found that Stack Overflow is another great resource to learn from. Especially when answering questions that you have no solid knowledge of as they force you to research the subject enough to construct a solution to the user’s problem.

Conclusion

So, there we have it; my 3 (4 including the bonus) goals to aim for this year. I’ve tried not to have too many as I don’t want to spread my time to thin, and I feel each goal requires enough work to make achieving it a challenge, yet providing me with enough value that by the end of the year I’m a better developer than I am at the start.

I wouldn't normally create a blog post about a mug, but as a programmer I thought this programmer's "Cup of type T" was clever enough to merit sharing it with my readers.

I originally spotted it at a zazzle.co.uk, but having read less than enthusiastic reviews about the store and the quality of their service offered I decided to look elsewhere. Ultimately I ended up getting it printed myself via vistaprint.co.uk for about the same price.

Recently I’ve been reading a lot about IoC patterns and best practices, and being a subscriber to PluralSight.com I stumbled across a fantastic course by Matt Honeycutt titled “Build Your Own Application Framework with ASP.NET MVC 5”. The video course presented a whole array of work that can be done to increase productivity within ASP.NET MVC, and one part of the course that particularly stuck out was the use of start-up tasks.

As an aside, I would highly recommend checking out Matt Honeycutt’s course if you’ve got an active subscription. For those who do not have a PluralSight subscription then PluralSight offer a free trial so you can sign up and watch the course for free. It’s 3 hours 25 minutes in length and packed full of tips for modifications, functionality and extensions that can make you more productive in ASP.NET MVC.

The problem

As an ASP.NET MVC application grows so does the use of the application event methods accessible from Global.asax.cs such as Application_Start, Application_BeginRequest, Application_EndRequest and so on. After a while these methods can become unmanageable and messy as more and more functionality is tied into the application events.

Let me demonstrate with an example. Take this simple Application_start method:

protected void Application_Start()
{
     IContainer container = StructureMapCoreSetup.Initialise();
     container.Configure(c => c.IncludeRegistry<DefaultRegistry>());

     StructureMapResolver = new StructureMapDependencyResolver(container);
     DependencyResolver.SetResolver(StructureMapResolver);

     ViewEngines.Engines.Clear();
     ViewEngines.Engines.Add(new RazorViewEngine());

     AreaRegistration.RegisterAllAreas();

     FilterConfig.RegisterGlobalFilters(GlobalFilters.Filters);
     RouteConfig.RegisterRoutes(RouteTable.Routes);
     BundleConfig.RegisterBundles(BundleTable.Bundles);
}

If you look closely you’ll see that this method is responsible for the following actions:

1. Setup our IoC container (in this case it’s StructureMap)
2. Register it with ASP.NET MVC’s dependency resolver
3. Clear existing view engines and explicitly add Razor
4. Register all areas of the application
5. Register any global filters
6. Register the application routes
7. Finally register the application’s Javascript and CSS bundles

Even with these reasonably tidy 7 steps, you can see how the method has the potential to become quite convoluted.

The solution

One such way to keep these application event methods in shape and prevent your global.asax.cs class becoming a god object  is to harness the power of your IoC container and break the functionality down into modular tasks. These tasks can then by loaded by your IoC container and executed at the correct stage of the life-cycle of a page request. Let’s take a look at how we can do this.

First we’re going to use a simple implementation of the command pattern to define our task execution interfaces:

public interface IExecutable
{
    void Execute();
}

Now we’ve created our role interface we also need to create an interface for the various stages of the application’s life-cycle that we wish to fire off tasks during.

public interface IRunAtStartup : IExecutable
{
}

public interface IRunOnEachRequest : IExecutable
{
}

public interface IRunAtEndOfEachRequest : IExecutable
{
}

From here we can begin to categorise our methods into nice, well organised classes based off of the interface they implement.

For instance, I often move all of the basic framework set-up tasks into their own FrameworkTasks.cs  class like so:

public class FrameworkSetupTask : IRunAtStartup
{
    public void Execute()
    {
        AreaRegistration.RegisterAllAreas();

        ViewEngines.Engines.Clear();
        ViewEngines.Engines.Add(new RazorViewEngine());

        FilterConfig.RegisterGlobalFilters(GlobalFilters.Filters);
        RouteConfig.RegisterRoutes(RouteTable.Routes);
        BundleConfig.RegisterBundles(BundleTable.Bundles);
    }
}

In addition to this if my project has various AutoMapper profiles then I’ll move them into their own start-up task class that’s fire off when the application is run:

public class AutoMapperProfiles : IRunAtStartup
{
    public void Execute()
    {
        Mapper.AddProfile(new CoreAutoMapperProfile());
        Mapper.AddProfile(new CartAutoMapperProfile());
        Mapper.AddProfile(new ProductAutoMapperProfile());
    }
}

Setting up your IoC container to execute the tasks

Now we’ve abstracted our various application life-cycle tasks we can use our IoC container to load and execute the tasks based on their interface type.

In the following example you’ll notice that I’m using StructureMap as my IoC container. You may also notice that I’m favouring the nested container per HTTP request approach - this is a personal choice of mine so it’s possible that your setup may vary. Other than this difference there shouldn’t be much to change in the following examples.

The Task Runner method
The task runner is the method responsible for loading and executing the tasks accordingly. You’ll notice the argument to the TaskRunner method is a nullable container. This is so I can pass a (nested) container as an argument (see Application_Start as an example), otherwise the TaskRunner method will use an existing instance of the nested container that’s set up within my StructureMapDependencyResolver  class.

public class MvcApplication : HttpApplication
{
    public static StructureMapDependencyResolver StructureMapResolver { get; set; }

    protected void Application_Start
    {
        ...

        StructureMapResolver = new StructureMapDependencyResolver(container);

        var serviceLocatorProvider = new ServiceLocatorProvider(() => StructureMapResolver);
        container.Configure(cfg => cfg.For<ServiceLocatorProvider>().Use(serviceLocatorProvider));

        DependencyResolver.SetResolver(StructureMapResolver);

        TaskRunner<IRunAtStartup>(container.GetNestedContainer());
    }

    protected void Application_BeginRequest(object sender, EventArgs e)
    {
        StructureMapResolver.CreateNestedContainer();

        TaskRunner<IRunOnEachRequest>();
    }

    protected void Application_EndRequest(object sender, EventArgs e)
    {
        TaskRunner<IRunAtEndOfEachRequest>();
    }

    private static void TaskRunner<T>(IContainer container = null)
    {
        if (container == null)
        {
            container = StructureMapResolver.CurrentNestedContainer;
        }

        foreach (var taskInstance in container.GetAllInstances<T>())
        {
            var task = taskInstance as IExecutable;
            if (task != null)
            {
                task.Execute();
            }
        }
    }
}

As you can see our HttpApplication events are far cleaner now than they were before and will continue to remain manageable as the project grows and further functionality is added that requires hooking up to the HttpApplication events.

Conclusion

As demonstrated, creating event tasks is straight forward and can easily be set up with any IoC container. If you’re using StructureMap and instead opting to use an IoC Container such Ninject or Unity then it should be easy enough to create a similar TaskRunner  method.

You’ll notice that for this example I’ve set up event tasks for the main HTTP events (Application_Start , Application_BeginRequest and Application_EndRequest) but this pattern can easily be applied to some of the other HttpApplication events such as Application_Error.

I’ve used this approach in various ASP.NET MVC projects with great success. The only drawback I’ve been aware of is the fact that you lose the ability to instantly see what occurs during your application events as they’ve now been moved into their own classes, though I feel this is a minor setback for the tidiness of the approach.

As mentioned earlier in my post, I would definitely recommend checking out the PluralSight course if you can.

Test automation, much like writing unit tests, requires an initial upfront investment in writing the actual tests - but once created, these tests become increasingly valuable as your project grows and ages. However, unlike unit tests there is an even greater investment required in creating the initial framework with which to build your automation tests upon. This important step requires a good deal of thought and planning to ensure the tests you write are as efficient and maintainable as possible.

Is this additional investment I talk of worth it in the long run? I certain think so and many others that have experience with test automation would also agree.

Luckily there’s a great talk by John Sonmez from SimpleProgrammer.com that takes you through how to create a Test Automation framework that I acts as a great foundation to write succinct, yet maintainable automation tests efficiently.

As it stands, ASP.NET MVC’s default behavior when outputting property names (using @Html.LabelFor() for example) is to output the property name as is. For instance, below highlights how the property name would appear if being output via a LabelFor() HTML helper.

public class ExampleViewModel
{ 
    public string Surname { get; set; } //Output: "Surname"

    public string FirstName { get; set; } //Output: "FirstName"

    public string age { get; set; } //Output: "age"
}

Whilst the output of the Surname property is fine, given that it’s a single word; you’ll notice that the output of the FirstName property is less than desirable and should instead be displayed as two separate words if it is to be read correctly.

If you wish to update the way the FirstName property is displayed within a view then the common solution is to use the ASP.NET’s Display annotation like so:

public class ExampleViewModel
{ 
    [Display(Name = "Surname")]
    public string Surname { get; set; } //Output: "Surname"

    [Display(Name = "First Name")]
    public string FirstName { get; set; } //Output: "First Name"

    [Display(Name = "Age")]
    public string age { get; set; } //Output: "Age"
}

Why I’m not a huge fan of Display annotations

Whilst this solution will work, I’m not a huge fan of it as I generally try avoid muddying my objects with annotations if I can; especially annotations that are view specific such as the Display annotation.

Whilst I appreciate this is a view model, containing data that is destined for the view, I would argue that a view model’s purpose is to represent only the data - rather than how it is displayed or formatted within the UI. That’s what HTML is for, marking up our data. If we were to output the view model above via a Restful API or web service then our display annotations suddenly become irrelevant.

Another issue with the overuse of data annotations is they can really start to get messy. Take the following model for instance.

public class LoginModel
{
    [Display(Name = "Account User Name")]
    [Required(ErrorMessage = "Please fill in your user name.")]
    [MaxLen(30)]
    public string AccountUserName { get; set; }

    [Display(Name = "Account Password")]
    [Required(ErrorMessage = "Please fill in your password.")]
    [MaxLen(30)]
    public string AccountPassword { get; set; }
}

Instead I tend to favor a conventional or configuration approach to such a problem - and thankfully, due to ASP.NET MVC’s extensibility, we can create our own conventional approach to displaying property names without the need to pollute our view model or data transfer objects with UI specific Display annotations.

Harnessing the power of the ModelMetaDataProvider

In order to apply our conventional approach to display properties within ASP.NET MVC we first need to look at where the display data is coming from when using an extension method such as the  @Html.LabelFor() extension used in our example above.

If we dig into the LabelFor extension (I use ReSharper which has a built in .NET de-compiler) you’ll see the LabelFor accesses the display property via an implementation of ModelMetadataProvider:

internal static MvcHtmlString LabelFor<TModel, TValue>(this HtmlHelper<TModel> html, Expression<Func<TModel, TValue>> expression, string labelText, IDictionary<string, object> htmlAttributes, ModelMetadataProvider metadataProvider)
{
     return LabelExtensions.LabelHelper((HtmlHelper) html, ModelMetadata.FromLambdaExpression<TModel, TValue>(expression, html.ViewData, metadataProvider), ExpressionHelper.GetExpressionText((LambdaExpression) expression), labelText, htmlAttributes);
}

After a little further digging you’ll find that the ModelMetadataProvider is a base class of DataAnnotationsModelMetadataProvider. If you take a moment to take a look at the DataAnnotationsModelMetadataProvider class and its implementation you’ll clearly see how ASP.NET MVC is accessing the Display attributes value and then returning an instance of ModelMetadata, which eventually ends up within the view helper and gets output in the view.

With this in mind, all we have to do in order to create our own conventional approach is create our own ModelMetadataProvider instance that overrides the current behavior and then register it with ASP.NET MVC.

Creating our own convention based ModelMetadataProvider

In my implementation, whilst I favor conventions over Display attributes, there may be instances where I will want to use a Display attribute, so I’m going to create a new class that extends ASP.NET MVC’s existing DataAnnotationsModelMetadataProvider implementation.

After a little work this is what I ended up with:

public class ConventionalModelMetadataProvider : DataAnnotationsModelMetadataProvider
{
    protected override ModelMetadata CreateMetadata(IEnumerable<Attribute> attributes, Type containerType, Func<object> modelAccessor, Type modelType, string propertyName)
    {
        ModelMetadata modelMetadata = base.CreateMetadata(attributes, containerType, modelAccessor, modelType, propertyName);

        if (modelMetadata.DisplayName == null)
        {
            modelMetadata.DisplayName = modelMetadata.PropertyName.SplitWords();
        }

        return modelMetadata;
    }
}

As you can see, all I’m doing here is calling the base (DataAnnotationsModelMetadataProvider) class’ implementation of the CreateMetadata method and updating the DisplayName  property if it’s not set. This means that if the DataAnnotationsModelMetadataProvider class we’re extending does not find a Display data annotation on the property then it will return null. Then in our implementation we’re simply getting the property name from the ModelMetadata  class and using an extension method I created (see below) to split the property name into words based on its upper-case letters, turning a string like “AddressLine1” into “Address Line 1”.

public static class StringExtensions
{
    public static string SplitWords(this string value)
    {
        return value != null ? Regex.Replace(value, "([a-z](?=[A-Z0-9])|[A-Z](?=[A-Z][a-z]))", "$1 ").Trim() : null;
    }
}

Registering our custom ModelMetadataProvider with ASP.NET MVC

Now all we have to do in order to use our conventional based approach to displaying property names is register our custom ModelMetadataProvider with ASP.NET MVC. This can be done by setting the Metadata provider within our website’s Global.asax.cs class, like so:

public class MvcApplication : System.Web.HttpApplication
{
    protected void Application_Start()
    {
        ...

        ModelMetadataProviders.Current = new ConventionalModelMetadataProvider();

        ...
    }
}

Once this is done you’ll now be able to remove your Display annotations and have property names output as they are, but split by their uppercase letter, whilst still allowing you to override our conventional behavior using a Display attribute if you need to.

Taking the ModelMetadataProvider further

Custom ModelMetadataProviders are a great way to harness the power of ASP.NET MVC model metadata functionality and opens up an array of possibilities. For instance, you can easily see how you could extend our solution above to query a database for field names, allowing us to have database driven properties - this same direction can be used for multilingual sites!

I hope you’ve found this guide blog post helpful and if you have any questions then please feel free to ask them in the comments section below.

After scratching my head trying to figure out what could have gone wrong, and trying multiple solutions following a bit of Google-fu (such as restarting Visual Studio, rebuilding my solution, running Visual Studio in administration mode and even restarting my computer) - I will still no closer to getting my unit tests running.

Eventually I managed to figure out what the problem was after I remembered that ReSharper had a cache that could be cleared from within ReSharper’s options (Resharper > Options > Environment > General > Clear Cache), and after clearing ReSharper’s cache and restarting Visual Studio I was able to run my unit tests once again without any hiccups.

It turns out that something must have happened that caused a corruption within ReSharper’s cache resulting in it ignoring my unit tests.

Whilst I know this blog post is trivial, I know I’ll most likely run into this issue again and feel I best document it just in case anyone else is experiencing similar issues.

As with all IDEs I’ve used I’ve always been fond of trying to get the best from them in order to improve my productivity, so as soon as I started using Visual Studio I immediately started researching features and functions to aid my day-to-day development, and over time I’ve built up a repertoire of common shortcuts that help me spend more time writing software and less time navigating the Visual Studio functions and menus.

I’ve always believed that one of the best ways to improve your productivity is to optimise your workflow. To do this I like to pay attention to the tasks I regularly perform when programming and see what can change about these behaviors to speed them up. For instance, I noticed I was creating classes a lot, so I got into the habit of using Resharper’s create class shortcut (ALT + Insert). This minor adjustment to my workflow dramatically reduced the time it took me to create a new class, whilst helping me stay in the zone by not having to break my concentration by taking my hands off of the keyboard and reaching for my mouse.

Optimising workflow is all about rewiring our habits and training our muscle memory so you get to a point where you’re pressing shortcuts and performing tasks without needing to consciously stop and try to remember the necessary shortcut. This takes time, but only a few days of constant use.

With this in mind I’ve decided to highlight some of the shortcuts and functions that helped me the most in improving my productivity in Visual Studio 2013.

Visual Studio Productivity Tip 1: Get ReSharper

Without wanting to sound like an Jetbrains’ salesman, I honestly believe the best thing I did to improve my productivity within Visual Studio is to start using Resharper. The folks over at JetBrains have done a fantastic job of implementing some real time-saving features into Visual Studio via their plugin. They offer a 30 day free trial so at the very least give it a try and you’ll see what I mean.

If you don’t believe me then watch the below video:

Visual Studio Productivity Tip 2: Learn to abuse Peek Definition

Peek Definition is a fantastic feature that really helped speed up my development. It particularly comes in handy if you’re working on a method that calls/references another class or method that you need to browse at or modify. Before Peek Definition was introduced in Visual Studio 2013 I would have to rely on Resharper’s CTRL + F12 shortcut that would take me to the implementation of the method or class – resulting in the whole class being loaded in another pane and breaking my flow.

With the introduction of Peek Definition into my workflow I’m now able to quickly open up the method/class using the ALT + F12 shortcut (I’ve changed it to ALT + Q for quicker single hand access) and analyse or make modifications to it without needing to leave the class I’m in. This helps keep me in the zone and focusing on what I’m doing.

Additional tip: Use the Esc key to close the peek definition window – this way your hands don’t have to leave the keyboard.

Visual Studio Productivity Tip 3: Switch between code tabs using CTRL + TAB

Another really useful feature is the ability to quickly switch between all open tabs within Visual Studio using the CTRL + TAB shortcut. Pressing this will open a popup window with all active (open) files that you can quickly navigate to using the up and down keys on the keyboard and then release to load the selected file.

What’s especially powerful about this feature is the fact that it automatically selects the last file you opened, meaning you can quickly press CTRL + TAB to go back to your previous file . This is particularly useful if I’m working between two classes such as an interface and an implementation of the interface.

Visual Studio Productivity Tip 4: Enable Enhanced Scroll Bar

I was using Visual Studio 2013 for about a year before I learnt of the new enhanced scroll bar feature, and after enabling it I quickly realised how much of a benefit using it over the traditional scroll bar would bring.

Not only does the enhanced scroll bar help you navigate your way around a class, but it also highlights any code changes you’ve made, along with errors, bookmarks and even your caret position.

You can enable the advanced scroll bar by right clicking the scroll bar within your code editor and selecting “Toolbar Options”. You can also access it via Tools > Options > Text Editor > All Languages > Scroll Bars.

Within the scoll bar’s options you have an array of choices allowing you to specify exactly what you’d like to see highlighted on the scroll bar. As I like to keep my code window as large as possible I opted for the narrower scroll bar that whilst still providing all of the normal feedback, doesn’t take up as much room as the medium or wide scroll bar.

Visual Studio Productivity Tip 5: GoToFile shortcut (using ReSharper)

As mentioned in tip 1, if you’ve got ReSharper installed then you’ve already got access to some fantastic time-saving shortcuts at your disposal that really go a long way at helping you improve your productivity when programming. One such shortcut that will dramatically improved my productivity was the use of Resharper’s GoToFile shortcut (CTRL + SHIFT + T).

The GoToFile shortcut is probably one of Resharper’s most powerful sortcuts that allows you to quickly locate anytype of file within your solution, including views, CSS files and Javascript files. What’re more is Resharper’s GoToFile dialog has the ability to pattern match all sorts of strings. For instance, if you wish to locate a class named “LoginRepository.cs” you only need type “lr” and Resharper will display a list of all files matching your query.

Visual Studio Productivity Tip 6: GoToDefinition shortcut (F12)

Another time saving shortcut that really helped me speed up my code navigation and saves  me from taking my hands off of the keyboard is the GoToDefinition shortcut (F12).

When your keyboard cursor is over a class definition, simply press F12 to quickly open the highlighted class. The same also applies for interfaces. Whilst this may seem like a simple shortcut, when using it becomes a habit you’ll realise how much time you’ve wasted navigating to a class via the mouse.

Visual Studio Productivity Tip 7: GoToFileMember shortcut (using Resharper)

Without wanting to make this post too Resharper focused, another great shortcut at the disposal of Resharper users is the GoToFileMember shortcut (ALT + ).

Using the GoToFileMember shortcut I’m able to quickly navigate to a property or a method in a few key strokes.

Simply press ALT + \ and you’re promptly greeted with a list of all of the classes methods and properties. In addition to this you can also quickly find the property or method you’re looking for via the GoToFileMember dialog’s search field.

Visual Studio Productivity Tip 8: Quickly create a constructor

I learned about this feature later on in my Visual Studio experiences, but it quickly became my staple way of creating constructors.

Next time you need to create a class constructor, instead of typing the entire constructor out type “ctor” and then hit the tab key immediately afterwards. This will instantly add a constructor to your class for you.

Visual Studio Productivity Tip 9: Quickly create properties

In addition to creating constructors as highlighted in the above tip, Visual Studio has a similar feature for properties.

Next time you need to create a new property simple type “prop” followed by hitting the tab key to quickly create a property. Typing the type and the pressing tab again will then automatically take you to the next definition along the declaration. You can also press Shift + Tab to go back to the previous definition.

Conclusion

So there you have it; quintessential tips that helped me to improve my productivity in Visual Studio 2013. Visual Studio is a feature packed IDE that can save you a lot of work. This is only the beginning of my journey to improve my productivity in Visual Studio.

If any of these features are new to you then the worst thing to do at this point is to try out the tips mentioned and leave it at that. Improving your productivity in a tool like Visual Studio doesn’t happen overnight and takes repetition to build these shortcuts into your muscle memory. But once they are well practiced you’ll really notice a difference in your workflow.

Don’t stop there. It’s always important to stop and take an honest look at your workflow and ask yourself “What tasks to I constantly repeat, and what an be done to reduce the time it takes to perform said tasks? Is there a shortcut or Visual Studio extension that I could learn or use to speed up the time it takes me to perform such an action? Generally I find the answer is yes!.

With the Surface Pro’s third iteration, all of the niggles I had with them were gone so I finally decided to jump in.

In order to fund the Surface Pro 3 I decided to part with my existing portable development machine - my Macbook Pro Retina that I was running Windows 8.1 on via Bootcamp.

Over the past few years my Macbook Pro has proven to be a great development laptop so making the choice to switch to a Surface Pro 3 wasn’t an easy choice to make, and despite receiving glowing reviews I couldn’t find any reviews or comments from a software developer’s perspective on how it performs as a development machine. So having lived with the Surface Pro 3 for a week or so now I decided to highlight what I feel the pros and cons of the Surface Pro 3 are from a software developer’s perspective, and how it performs as a portable development machine.

If you’re reading this and unaware as to the hardware specifications/features of the Surface Pro 3 then you’ll probably find more suitable information somewhere else. This post presume you already know the stats of the Surface Pro 3 and are keen to find out how it performs as a development machine.

Programming using the Surface Pro 3 keyboard and trackpad

My first concern when committing to the Surface Pro 3 was the keyboard. As any software developer will know, the keyboard is his main tool so it’s important that it’s responsive and comfortable to type on for long periods of time. Being a bit of a shortcut addict it was also important for me that the keyboard not be too small as to force my hands into weird positions when pressing some of the shortcuts I’ve grown to rely on.

Thankfully I was pleasantly surprised. Naturally it took me a short while to feel comfortable touch typing on the keyboard, especially when programming and requiring the use of certain special characters, but before long I was programming away without and concerns. Only occasionally hitting the wrong key - but that will work itself out in due time.

The keyboard is just the right size to feel familiar to the faster typers out there and provides a good level of feedback with a satisfying “click” as you press each key.

As for the track pad, I wouldn’t go as far as saying it’s terrible - but it’s certainly not the best trackpad I’ve used. It’s perfectly fine for navigating around Visual Studio or IntelliJ IDEA but it can feel a little unresponsive at times.

UPDATE: Since writing this post I’ve upgraded my Surface Pro 3 with the Surface Pro 4 Type Cover - something I would highly recommend as a lot of the issues mentioned regarding the keyboard and the trackpad have been resolved.

Typing on your lap (or lapability as Microsoft call it)

One of the criticisms of the Surface Pro 2 was the difficultly in typing on your lap. Because the keyboard clips into place by a strong magnet and the screen’s kick stand only had 3 points at which it could be moved to, it made typing very difficult due to the limited angles.

Thankfully this has been sorted in the Surface Pro 3. With the kick stand being adjustable to any level, you can lower or raise the screen to any level that suits you. What’s more is the keyboard has an additional magnet in it that allows the keyboard to be docked at a slight angle to further aid the positioning of the keyboard to a suitable level based on how or where you’re sitting.

In fact, as I write this I’m laying in bed with the keyboard comfortably on my lap with no movements or fear of the keyboard become disconnected from the display screen.

One of my fears before purchasing the Surface Pro 3 was the strength of the keyboard magnet. I was concerned that if, for some reason, I were to knock the screen that the magnet wouldn’t be strong enough to keep the display from disconnecting and falling over, possibly onto the floor. Thankfully I quickly realised this should not be a concern as the magnet is incredibly strong and holds the keyboard and display firmly together. On the contrary it actually requires quite some force in order to separate the screen from the keyboard.

Is the Surface Pro 3 screen too small for software/web development?

Before committing to selling my Macbook Pro Retina to fund my Surface Pro 3 purchase, I did have concerns about whether the screen would be large enough for programming on. The Surface Pro 2’s screen was a little too small for my taste, but Microsoft have increased the size of the screen for the Surface Pro 3, providing me with more than enough screen real-estate to write code without the need for constantly scrolling across or up and down the page.

Running Visual Studio on the Surface Pro 3

Hardware wise, the Surface Pro 3 model I decided to go for was the i5, 8gb of memory and 256GB SDD drive, which was actually a downgrade from the i7 Macbook Pro Retina I was using before - but the additional portability of the Surface Pro 3 made the sacrifice one I was happy to make.

The majority of my development time on the Surface Pro 3 has been some rather large Visual Studio 2014 projects, followed by some Android programming in IntelliJ IDEA. During my time programming I’ve yet to experience any slow compile times. Visual Studio is a power-house of an IDE and loves to gobble up memory, but this doesn’t appear to hamper the Surface Pro 3. All in all, I’ve not noticed any performance difference between the Macbook Pro Retina and the Surface Pro 3 when programming and compiling applications.

Below is a screenshot of the system resources with Visual Studio 2013 and SQL Server running; as you can see there’s more than enough memory and CPU remaining to ensure build times are fast and the system remains responsive.

Additional ports

As someone who does a lot of Android development I was a bit disappointed to see that the Surface Pro 3 only features one USB port. As someone who prefers to test his Android apps against a real phone rather than the Android emulator it’s a slight annoyance that there isn’t a t least one more port available. This would save me from having to lug a USB adapter around with me.

Conclusion

Ultimately I’m extremely happy with my purchase of the Surface Pro 3 and I don’t have any regrets about selling my Macbook Pro Retina to pay for it. The Surface Pro 3 is a fantastic device that I find myself using more and more, both as a laptop and a tablet.

The fact that the Surface Pro 3 is more portable than my Macbook Pro means that I take it everywhere with me, allowing me to have a sneaky coding session when I have a bit of spare time.

Edit: If you’re considering purchasing the Surface Pro 3 as a development laptop then I highly recommend you listen to Scott Hanselman’s latest Hanselminutes podcast ‘Selecting the Ultimate Developer Laptop with Damian Edwards‘ where he and Damian Edwards openly talk about how they find the Surface Pro 3 a great development laptop.

Over time I would start to notice patterns occurring. For instance when developing web based applications following a typical n-tier application structure I’ve noticed it becomes very easy to label everything at the service/business logic level a ‘service’. With this in mind I started to do a little googling for naming ideas and found this little gem of a question on every developer’s favourite site that highlights a whole range of different naming ideas and conventions that might help describe that class you’re creating perfectly.

These are:

• Coordinator
• Builder
• Writer
• Reader
• Handler
• Container
• Protocol
• Target
• Converter
• Controller
• View
• Factory
• Entity
• Bucket
• Attribute
• Type
• Helper
• Collection
• Info
• Provider
• Processor
• Element
• Manager
• Node
• Option
• Factory
• Context
• Designer
• Editor

[Serializable]
public class UserProfileSessionData
{
    public int UserId { get; set; }

    public string EmailAddress { get; set; }

    public string FullName { get; set; }
}

public class ExampleLoginController : Controller {

    [HttpPost]
    public ActionResult Login(LoginModel model)
    {
        if (ModelState.IsValid)
        {
            var profileData = new UserProfileSessionData {
                UserId = model.UserId,
                EmailAddress = model.EmailAddress,
                FullName = model.FullName
            }

            this.Session["UserProfile"] = profileData;
        }
    }
}

And then retrieving session data like this:

public class ExampleDetailController : Controller
{   ...
    public ActionResult ViewProfile()
    {
        ...
        var sessionData = (UserProfileSessionData) this.Session["UserProfile"];
        ...
    }
    ...
}

What’s the problem with doing it this way?

Whilst this solution works, there’s improvements that can be made. Take a look at the code for a moment and try and think of what problems doing the above could lead to as the project started to mature.

First of all, what happens if we want to modify the what information gets stored in the session? Or even worse, we want to switch from session based storage to database storage? Ultimately we’d have to spend a great deal of time going through any controller that references the session and make changes.

Ultimately, what we’re doing by accessing the Session object directly from within the controller is breaking the D (dependency inversion) of the SOLID principles - a set of five principles of object-orientated programming and design aimed at encouraging the creation of extensible, flexible and testable software; something all developers should strive to do.

What is the Dependency Inversion principle?

Once of the most memorable definitions of dependency inversion that I’ve heard and which has stuck with me is:

“Program to an interface, not an implementation”

In the context of the code sample above, by directly programming against the Session object (an implementation) we’re creating a dependency within our controller. We can avoid doing this by using an interface type to abstract and encapsulate the session’s implementation details - allowing us to programming against some kind of simplified interface. Doing this leads to a loosely coupled controller that’s not directly depending on the existence of the Session object, but instead depends a type that implements our IUserInformation type.

This powerful thing about this is the controller does not need to be concerned about the implementation details, meaning we could easily switch the implementation to read the data from a database instead of a session object - and we wouldn’t have to touch anything in the controller.

This also makes the controller far more testable as we can easily mock the session’s abstraction.

Ok, I’m following so far. So how do we ‘invert’ our controller’s dependencies?

There are multiple types of dependency injection but the most common pattern for this type of challenge is constructor injection using an Inversion of Control Container.

In this example I’m going to use StructureMap as my IoC container of choice as it’s one I’m most comfortable with and prefer using in my day-to-day life.

The first step is to include the Nuget package for both StructureMap and StructureMap.Web. Now we’ve got the StructureMap packages we need to hook Structuremap into ASP.NET’ MVC’s dependency resolver by creating a new class (In this instance I called it StructureMapDependencyResolver.cs) and implementing the IDependencyResolver from the System.Web.Mvc package like so:

public class StructureMapDependencyResolver : IDependencyResolver
{
    private readonly IContainer _container;

    public StructureMapDependencyResolver(IContainer container)
    {
        _container = container;
    }

    public object GetService(Type serviceType)
    {
        if (serviceType.IsAbstract || serviceType.IsInterface)
        {
            return _container.TryGetInstance(serviceType);
        }
        return _container.GetInstance(serviceType);
    }

    public IEnumerable<object> GetServices(Type serviceType)
    {
        return _container.GetAllInstances<object>().Where(s => s.GetType() == serviceType);
    }
}

Once this is done simply add our DependencyResolver to the Application_Start method within Global.asax.cs, like so:

public class MvcApplication : HttpApplication
{
    protected void Application_Start()
    {
        ...
        ObjectFactory.Initialize(x => x.AddRegistry<WebsiteRegistry>());
    	DependencyResolver.SetResolver(new StructureMapDependencyResolver(ObjectFactory.Container));
        ...
    }
}

Now that StructureMap is hooked up to our ASP.NET MVC application, all that’s left to do is define our dependencies by creating our WebsiteRegistry.cs class that extends StructureMap.Configuration.DSL.Registry.cs, like so:

public class WebsiteRegistry : Registry
{
    public WebsiteRegistry()
    {
        this.For<IUserInformation>().HybridHttpOrThreadLocalScoped().Use(() => GetUserInformationFromSession());
    }

    public static IUserInformation GetUserInformationFromSession()
    {
        HttpSessionStateBase session = new HttpSessionStateWrapper(HttpContext.Current.Session);

        // Check to see if the session already exists, if it does then cast it to IUserInformation
        if (session["UserSessionData"] != null)
        {
            return session["UserSessionData"] as IUserInformation;
        }

        // Otherwise create a new instance of UserInformation.cs
        session["UserSessionData"] = new UserInformation();
        return session["UserSessionData"] as IUserInformation;
    }
}

Once we’ve added our Registry we need to define how our instance of IUserInformation is constructed. In this case we want to deserialize our session object and cast it to an instance of IUserInformation.

We can now refactor our ExampleLoginController.cs file to move the dependencies outside of the controller and program against the IUserInformation interface.

public class ExampleDetailController : Controller {

    private readonly IUserInformation userInformation;

    public void ExampleLoginController(IUserInformation userInformation) {
        this.userInformation = userInformation;
    }

    [HttpPost]
    public ActionResult ViewProfile()
    {
        ...
        string emailAddress = this.userInformation.EmailAddress;
        ...
    }
}

After spending about an hour trying to figure out why my route wasn’t working I decided to pull out the Google-fu to look debugging ASP.NET MVC routes, which is when I came across a golden nuget package written by Phil Haack called RouteDebugger.

Setup was simple, and after downloading the RouteDebugger Nuget package via Visual Studio’s awesome Nuget Package Manager tool and enabling it within the Web.config configuration file by adding the following it was up and running.

<add key="RouteDebugger:Enabled" value="true" />

Now when you fire up your application you’re greeted with a useful debugging pane located at the bottom of your page (see below) showing you exactly what route your current page URL matches and which ones they don’t. In my instance this proved extremely valuable as I was able to very quickly identify that my route was being matched to a far more vague route before it was being hit.

<div class="panel">
         <div class=panel-inner">
             <h2 class="panel-title">Panel Title</h2>
             <div class="panel-content">
                 /* Can I pass content to be rendered in here here? */
             </div>
         </div>
     </div>
</div>

As my side project progressed and grew, I found myself making more and more modifications to these HTML components so I started to look how I can encapsulate the component for greater flexibility and extensibility as my project progressed.

The solution I ended up with was creating a HTML extension modelled off of the way the the Html.BeginForm() extension works, by writing directly to the view’s context and then returning an instance of IDisposable, with the call to disposing of the context writing the closing HTML statements of my component to the view context - essentially wrapping the contents passed into the HTML extension in my HTML component.

Below is an example of what the code looks like:

namespace System.Web.Mvc
{
    public static class HtmlHelperExtensions
    {
        public static HtmlPanelComponent PanelComponent(this HtmlHelper html, string title)
        {
            html.ViewContext.Writer.Write(
            "<div class=\"panel\">" +
            "<div class=\"panel-inner\">" +
            "<h2 class=\"panel-title\">" + title + "</h2>" +
            "<div class=\"panel-content\">"
            );

            return new HtmlPanelComponent(html.ViewContext);
        }
    }

    public class HtmlPanelComponent : IDisposable
    {
        private readonly ViewContext _viewContext;
        public HtmlPanelComponent(ViewContext viewContext)
        {
            _viewContext = viewContext;
        }
        public void Dispose()
        {
            _viewContext.Writer.Write(
            "</div>" +
            "</div>" +
            "</div>"
            );
        }
    }
}

Using this new HTML extension I’m now able to reuse my HTML component and fill the panel’s content in with whatever I please, like so:

@using (Html.PanelComponent("Panel Title"))
{
    <p>Welcome back, please select from the following options</p>
    <a href="#">Profile</a>
    <a href="#">My Defails</a>
}

If you’re short on time then I’d recommend fast forwarding to the 20 minute mark where Anders runs through using Generics and Lambda Expressions (instead of waiting for ECMAScript 6) in TypeScript.

As explained in previous blog posts, I’m a huge fan of StructureMap and use it as my IoC container of choice when writing .NET applications. With the release of StructureMap 3, I was happy to see there have been some rather large updates to it. However, when I tried to update an application from version 2 to StructureMap 3 I quickly ran into some configuration issues as a result of the API changes, and with StructureMap 3 being as new as it is there’s little documentation at the moment. Eventually I managed to figure out where missing classes have been moved to so I thought I’d document it here to help anyone who experienced similar head scratching questions.

Q1: HttpContext related scoping has moved

Updating my .NET MVC application that uses HttpContext I quickly became aware that HybridHttpOrThreadLocalScoped had vanished, but I noticed this has now been moved into a separate StructureMap.Web Nuget package that can be found here. It can also be found within Visual Studio’s package manager by simply searching for “StructureMap.Web”. Added this package to my solution quickly resolved the HttpContext related issues I ran into.

Jeremy Miller did mention this on his blog, however I seemed to have skimmed over little detail as I rushed to update like an excited kid at Christmas.

Q2: SetAllProperties(), where are you?

SetAllProperties has now been moved into a class called Policies and can be accessed like so: this.Policies.SetAllProperties();

All of the source code is up on Github for those interested.

“Your project file uses a different version of the TypeScript compiler and tools than is currently installed on this machine. No compiler was found at C:\Program Files (x86)\Microsoft SDKs\TypeScript\0.9\tsc.exe. You may be able to fix this problem by changing the element in your project file. ”

Scratching my head I wondered where I needed to go to reference the new Type Script 1.0 compiler that had installed along with Visual Studio 2013 Update 2 Release Candidate. After having a quick look around the project options such as the TypeScript Build panel within project properties I was still stumped.

It turns out that you specify the TypeScript version number within the project’s .csproj file itself. Simple right click the project that requires TypeScript compilation, click “Unload Project” and then right click the unloaded project again and click “Edit  .csprok” to view the project’s project configuration. From here you should see a TypeScript version property that you need to update to your desired version (in my case 1.0).

Once you’ve updated this, simple reload the project and you’re good to go!

Today I was setting up a project in Code Igniter that connected to a Microsoft SQL Server database (in my case it was a local instance of SQL Server 2008 Express) and I kept experiencing an incredibly unhelpful blank white screen.

Now I’ve worked with PHP for about 8 years professionally but never spent a huge amount of time with Code Igniter so it was all a little new to me. However, having previously worked with a few other MVC frameworks it didn’t take long for me to find my way around and become familiar with it. After performing a few checks and double checks to make sure I wasn’t doing anything silly I still hadn’t come any closer to figuring out why Code Igniter was throwing me a blank white page.

I started to dig down into the way Code Igniter was connecting to the SQL Server database via its MS SQL Server driver and it suddenly hit me - I’d fallen victim to the “we don’t like seeing errors so let’s suppress them by using the @ operator” school of thought.

That’s right, Code Igniter’s MS SQL Server driver was suppressing a simple error that would have helped me solve the problem within minutes. Interestingly I’m not the only one who appears to have fallen victim to this either.

Why suppressing warnings and errors is bad

One common reason some might advocate suppressing errors is that showing errors to users is not only messy and unprofessional, but also poses a potential security risk as often errors or warnings can contain important configuration information such as database names and sometimes even usernames or password. This is a perfectly valid concern; HOWEVER, errors are thrown for a reason. Something somewhere is going wrong and it’s important that errors are handled correctly. Ignoring errors is not handling them.

One way to correctly handle such errors is to wrap the cause of the potential error in a try catch statement and output any occurring exceptions to a log file. Doing this not only prevents users from seeing the error but also provides us with a way to track if an error is being thrown in the first place, something that can become increasingly important as an application or website grows in size and traffic as the suppression of errors can start to affect performance.

And, as my story above highlighted, you’re no longer hiding an important error from someone who might be using your code.

Since it’s launch in August 2008 Stack Overflow spread like wildfire throughout the development community, quickly establishing itself as the place to go to find programming and development related issues answered. No longer did we need to trawl through the noise of forum posts looking for solutions to questions or fixes for bugs, all we needed to do was type our question into Google with a suffix of “ + stackoverflow” to find exactly what we were looking for.

Whilst skeptical of claims that Stack Overflow has saved companies billions of dollars in developer productivity, once thing for sure is that whether or not the total figure is billions, Stack Overflow has certainly saved a lot of companies a lot of money in the 5 years it’s been alive.

Currently sitting above sites such as NetFlix, BBC and Flickr in the Alexa Top 100 the most visited websites (position 58 at time of writing), Stack Overflow receives roughly 1.7 million visits a day. With such high traffic numbers and a huge fan of system architecture I was really interested to know a bit more about what was going on under the hood of Stack Overflow. We all know that it’s powered by Microsoft’s fantastic .NET MVC framework, but what about the structure, the database access, the servers and all of the other juicy bits that get us developers salivating?! Thankfully StackOverflow software engineer Marco Cecconi, gave a talk at the Developer Conference 2013 on this very subject.

At just over 46 minutes long I highly recommend you check out the talk if like me, you love to know about systems and software architecture.

Bravo Microsoft, I loved this advert. It was incredibly moving and highlighted how important software and technology is to the world - something that is so easily forgotten, helped by the fact it’s so silently prevalent; until we experience a power cut or broadband outage and suddenly realise how much it enriches our lives.

If you’re new to AutoMapper and have been following a lot of the tutorials online then you your mappings might look a little something like this:

public class BlogService : IBlogService
{
    ...

    public BlogPostDto GetPost(int id)
    {
        BlogPost blogPost = this.blogRepository.GetPost(id);
        if (blogPost == null)
        {
            throw new EntityNotFoundException("blogPost");
        }

        return Mapper.Map<BlogPost, BlogPostDto>(blogPost);
    }

    ...
}

Whilst doing it this way will work, if we want to stick to Uncle Bob’s SOLID princples and promote abstraction and code testability then we really want to do it a different way, as not to couple AutoMapper’s static Mapper.Map class to, in this instance, our BlogService class.

This is where AutoMappers IMappingEngine interface comes in handy.

IMappingEngine Interface

By using the IMapperEngine interface we’re able to “program to an interface and not implementation” (more on the importance of that here) by using our IoC container of choice to inject the IMappingEngine interface into our object. In this case it’s a Blog service object.

If you take a moment to look at what methods the IMappingEngine interface provides us you’ll see it provides us access to all of the mapping methods we need (specifically the Mapper.Map method used above). Great! Now all we need to do is inject our the MappingEngine and we’re good to go.

Injecting IMappingEngine using an IoC Container

In this instance I’m using StructureMap for my IoC container needs as I’m comfortable with it, but any IoC container will do.

To start with we need to map AutoMapper’s Mapper.Engine to the IMapperEngine interface within our custom Structuremap registry (I’ve included the full namespace to the registry below to make it easier for those trying to follow).

public class WebsiteRegistry : StructureMap.Configuration.DSL.Registry
{
    public WebsiteRegistry()
    {
        this.For().Use();

        Mapper.AddProfile(new AutoMapperMappingProfiles());
        this.For().Use(() => Mapper.Engine);
    }
}

Then all we have to do is register our new registry with StructureMap and call _StructureMapCoreSetup.Configure()_ in our application’s composition root. As this is an ASP.NET MVC application the composition root is the Global.asax.cs

public static class StructureMapCoreSetup
{
    public static void Configure()
    {
        ObjectFactory.Initialize(x =>
        {
            x.AddRegistry();
        });
    }
}

Now that our instance of IMappingEngine is configured with our dependency injection container we’re able to inject AutoMapper whenever we need it, turning our first example below.

public class BlogService : IBlogService
{

    private readonly IMappingEngine mappingEngine;
    private readonly IBlogRepository blogRepository;

    public BlogService(IMappingEngine mappingEngine, IBlogRepository blogRepository)
    {
        this.mappingEngine = mappingEngine;
        this.blogRepository = blogRepository;
    }

    ...

    public BlogPostDto GetPost(int id)
    {
        BlogPost blogPost = this.blogRepository.GetPost(id);
        if (blogPost == null)
        {
            throw new EntityNotFoundException("blogPost");
        }

        return this.mappingEngine.Map<BlogPost, BlogPostDto>(blogPost);
    }

    ...
}

Now that we’re injecting the MappingEngine we’re easily able to mock it when writing tests, and can continue to program happy in the knowledge we’ve abstracted the AutoMappers mapping functionality and are programming to an interface rather than implementation.

See below for a simple test case using a mocked IMappingEngine instance:

[Test]
public void Get_Post_By_Id_Test()
{
    var blogPost = new BlogPost();
    var blogPostDto = new BlogPostDto();

    /* Setup */
    var mappingEngine = new Mock();
    mappingEngine.Setup(x => x.Map<BlogPost, BlogPostDto>(blogPost)).Returns(blogPostDto);

    this._blogRepository.Setup(x => x.GetPost(It.IsAny())).Returns(blogPost);

    /* Test */
    this._blogService = new BlogService(this._blogRepository.Object, mappingEngine.Object);
    BlogPostDto blogPostResult = this._blogService.GetPost(5);

    /* Assert */
    Assert.NotNull(blogPostResult);
    Assert.IsInstanceOf(blogPostResult);
}

Taking AutoMapper Further

If we wanted to further abstract AutoMapper from our web application then we could use the Facade Pattern to encapsulate the IMappingEngine and inject that instead. This means that if a time came where we wanted to completely replace AutoMapper with another object mapping engine, or even write our own then we wouldn’t need to violate the Liskov Substitution Principle. I will save this for another post though.

First of all I had to find a suitable cropping plugging and after a bit of googling I stumbled upon the a JQuery based image cropping script called JCrop that did everything I needed. It had a nice clean API, was regularly updated and worked well in multiple browsers.

All of the image processing is performed in PHP, but now that I’m doing more and more C# lately I’ll probably write a C# version too.

In total it took me an evening to write and works pretty well. You can drag across your chosen image to set the crop or you can specify the width and/or height of the crop and image quality of the cropped image.

I’ve also added it to Github so if anyone would like to use/fork it then feel free to do so.

Creating virtual directories is pretty straight forward when developing against IIS, however this particular project is using IIS Express I wasn’t too sure how easy this was to do, or whether it was even possible. However, it seems that it’s actually very straight forward to set up.

Creating a virtual directory in IIS Express

To create a Virtual Directory in IIS Express simple navigate to the IIS Express’ config directory located in _C:\Users<User>\Documents\IISExpress\config_ and open the applicationhost.config file.

The applicationhost.config file holds all configuration data for your Visual Studio projects that require IIS Express. As you browse through the file you’ll notice a sites section that contains your application(s) IIS Express configuration in the following format:

<site name="MvcApplication" id="1">
    <application path="/" applicationPool="Clr4IntegratedAppPool">
    <virtualDirectory path="/" physicalPath="c:\users\<User>\documents\visual studio 2012\Projects\MvcApplication\MvcApplication" />
     </application>
     <bindings>
         <binding protocol="http" bindingInformation="*:1239:localhost" />
     </bindings>
</site>

Once you’ve found this creating a virtual directory is very straight forward. Simply add an additional line like below:

<site name="MvcApplication" id="1">
    <application path="/" applicationPool="Clr4IntegratedAppPool">
    <virtualDirectory path="/" physicalPath="c:\users\<User>\documents\visual studio 2012\Projects\MvcApplication\MvcApplication" />
     </application>

     <application path="/Uploads" applicationPool="Clr4IntegratedAppPool">
         <virtualDirectory path="/" physicalPath="C:\temp\YourVirtualDirectoryPath" />
     </application>

     <bindings>
         <binding protocol="http" bindingInformation="*:1239:localhost" />
     </bindings>
</site>

Once done load your project up and your virtual directory (in my case the /Uploads directory) will be accessible from within your project as if it were in the same directory.