Miroslav Popovic

ASP.NET Core 3.0 Workshop

Fri, 26 Jul 2019 00:00:00 GMT

UPDATE (September 29th): The workshop sample and materials have been updated to the final version of .NET Core 3.0. All the missing pieces are implemented.

Workshop content

Session #0 - Prepare your environment by installing and configuring prerequisites
Session #1 - An introduction to .NET Core and ASP.NET Core in form of presentations
Session #2 - Working with .NET Core CLI tools and Visual Studio 2019, analyzing project templates
Session #3 - Choosing a domain to develop and creating user stories for it
Session #4 - REST API introduction, creating Web API project, introduction to Postman and configuring git
Session #5 - Creating domain models, EF Core context and migrations
Session #6 - Creating view models and controllers, validation, error handling, using Postman
Session #7 - Securing API with JWT token based auth
Session #8 - Creating unit and integration tests, adding Swagger support
Session #9 - Versioning APIs, usage limiting, monitoring and creating health checks
Session #10 - Introduction to Blazor and creating client-side Blazor client
Session #99 - Resources and further reading

Introduction

For quite some time, I was thinking about creating a workshop for ASP.NET Core. After some talks I had with members of EESTEC student organization and the management of Seavus, the idea started to shape up. My plan was to build something that could be reused for various events - for community organized events, inside the company, for conferences, and of course to be usable for others too.

After almost two months of sleeping less, preparing samples, writing instructions and having a first live workshop with students in duration of 10 days, there's finally something to share. The current version of workshop, with sample project and instructions, is available on GitHub. I was heavily influenced by .NET Foundation's presentations and workshops and I even took some of the materials from there - parts of presentation, presentation template and the cover image for the workshop. Why not, my user group and myself are members of .NET Foundation organization. You could be too! :)

So, what is this workshop about? Other than ASP.NET Core 3.0 of course. Well, at the end, I have decided to go with Web API route. After the introduction to .NET Core 3.0 and ASP.NET Core and looking through the available templates, together with attendees, a domain is chosen and implemented as REST Web API. That API is then improved and finally consumed by frontend SPA application. To continue at the bleeding edge, we are not using JavaScript SPA frameworks like Aurelia (the best one out there ;)), React, Vue or Angular, but a completely new thing called Blazor!

The workshop itself is split into 10 parts (for now). Each part has it's own document with instructions. There is a prerequisites document that you can use to prepare your environment. If you want to present it to others, there's a speaker notes document to remind you what should you go through during each part.

Note that both ASP.NET Core 3.0 and client-side Blazor are at the moment in preview phase. .NET Core 3.0 will launch in September during .NET Conf and client-side Blazor sometime next year. The workshop is updated to Preview 7, which came out a few days ago and has a go-live license. There are some things in workshop that could not be achieved with the current version. I still consider the workshop a work in progress, until the final versions of .NET Core 3.0 and client-side Blazor are out and the workshop updated.

You are welcome to use the workshop as you see fit. You can follow it by yourself, using the provided instructions. Or you could present the workshop to your friends, community or company. You could also create a derived version of workshop from it - in which case I would be grateful for an attribution :). I hope it will be useful.

I'm also interested in presenting the workshop as well as giving regular talks, so if you have something in mind, like a community event, conference, etc., let me know.

Live workshop

At the end, here are some pictures from the live workshop we had in Banja Luka. Thanks EESTEC, Seavus, BLbit, Bit Alliance and ETFBL for the help in organizing the event! And of course, thanks to all attendees, you were great!

2018 in review

Fri, 08 Feb 2019 00:00:00 GMT

This is (a bit late) review of the activities I had in 2018., mostly for archival purpose, since I tend to forget things.

Seavus

I started to work for Seavus in September 2017., so 2018. was my first full year there. Some time was necessary to adopt to the new way of working. Before Seavus, I was doing remote / freelance work. Switching to regular working hours, with no overtime and staying up late took a while. As always, there are pros and cons. The biggest pro in my opinion is with social aspect. Seavus managed to attract a huge number of great people (900+ of employees at the moment) and I consider that as its greatest strength. Most of the cons that I have are related to the difference between the work I had before. None of them are really big, and things are improving along the way.

Seavus Banja Luka office started growing nicely. Btw we are hiring :). At the end of 2018. I was offered a promotion to Technical Lead with additional assignments - basically to be a face of Seavus in Bosnia and Herzegovina. We'll see how that goes :).

Conferences and other community events

Continuing from 2017., the last year was also pretty busy regarding community events. Here are the talks I had:

January 25th, BLbit meetup - Introduction to ASP.NET Core 2.0 talk
February 6th, Seavus CodeTalks, Novi Sad - Building production-ready APIs with ASP.NET Core 2.0
February 7th, MSDEV Serbia meetup, Belgrade - Introduction to ASP.NET Core 2.0 and Building production-ready APIs with ASP.NET Core 2.0 talks
April 19th, NetWork conference, Neum - Docker and ASP.NET Core talk
April 27th, WinDays conference, Porec - Building production-ready APIs with ASP.NET Core 2.1 talk
May 12th, Weblica conference, Cakovec - Building production-ready APIs with ASP.NET Core talk
May 17th, Seavus CodeTalks, Kragujevac - Docker and ASP.NET Core 2.1 talk
September 1st, KulenDayz conference, Osijek - Docker and ASP.NET Core talk
September 14th, MSCommunity conference, Sarajevo - Visual Studio productivity talk
September 22nd, CrisCon conference, Krizevci - Docker and ASP.NET Core talk
October 25th, Sinergija conference, Belgrade - Building production-ready APIs with ASP.NET Core 2.x talk
November 1st, DotNet Amsterdam meetup, Amsterdam - Building production-ready APIs with ASP.NET Core 2.2 talk
November 3rd, SQLSaturday event, Banja Luka - Building production-ready APIs with ASP.NET Core 2.2 talk
November 13th, Seavus CodeTalks, Belgrade - Be productive with Visual Studio talk
November 15th, Seavus CodeTalks, Banja Luka - Be productive with Visual Studio talk
December 6th, Advanced Technology Days conference, Zagreb - Migration from ASP.NET MVC to ASP.NET Core 2.x talk

The DotNet Amsterdam meetup was recorded. You can check it out on YouTube.

Now that I see all of it in a list, it's a lot :). Not sure if I'll be able to keep that pace in 2019.

BLbit user group

BLbit continues to be most active MSCommunity user group in Bosnia and Herzegovina by the number of meetups. One of highlights of the last year was a participation in global .NET Conf event - with a conference watch party and an additional meetup. We had swags too! :)

Last year we have also started to use Meetup platform and became members of .NET Foundation. Recently, we have also created a Twitter account and we are still on Eventbrite too.

We also got a new sponsor - Seavus, in addition to MSCommunity and institutions providing us with the place to held our meetups - ICBL, BLC, Qlab and Smart Office.

Hopefully, we will able to keep going strong this year too.

Plans for 2019

Granted, there will be more responsibilities in Seavus, with the promotion, but I don't plan to neglect the community engagement. Might tune down a bit with the number of community events, but will try to be more active with my blog (yeah, not the first time I planned that) and open-source contributions.

ASP.NET Core Identity and Aurelia

Sat, 14 Jul 2018 00:00:00 GMT

This blog post is a response to a StackOverflow question. Andreas wanted to know how to add ASP.NET Core Identity to an existing Aurelia project. The answer is of course: it depends.

If it's really an existing application but without any authentication support or even without database access, then adding authentication and Identity might prove a bit difficult if you are not familiar enough with ASP.NET Core. At least it was like that before ASP.NET Core 2.1 which brought us Identity UI library and Identity Scaffolding features, among other things.

Identity UI library is implemented as a Razor Class Library, another new feature in 2.1 which enables Razor views and pages to be embedded into class libraries. This was a perfect fit for Identity, so when you create a new ASP.NET Core 2.1 project with Identity enabled, you won't get any Account or Manage views, nor their models. Everything is embedded into the new Microsoft.AspNetCore.Identity.UI assembly/NuGet package.

Identity Scaffolding is a new feature that can be used from within Visual Studio or from .NET Core CLI. It's basically a code generator that will generate overrides for any (or all) Identity Razor views, partials or necessary scripts. Talking Dotnet has a good overview of Identity UI Scaffold.

So, this could be the answer to the question? Well, not quite. It will work only on ASP.NET Core 2.1 and above. If the project was created using Aurelia CLI, it would be on ASP.NET Core 2.0. In that case, you first need to upgrade to ASP.NET 2.1.

All of this is for an existing project, but if you are creating a new one, things might be a bit easier.

Creating a new ASP.NET Core project with Aurelia and Identity enabled

ASP.NET Core 2.1 also has a new SPA project templates that are more in line with community usage of client-side frameworks. I.e. the new template for React is using Create React App and the new template for Angular is using Angular CLI. However, there is no template for Aurelia. Neils Morf has a solution for this in his blog post. He basically creates a new project using the Angular template and then modifies few things to run Aurelia instead. Note that you won't need to install the new SPA templates since they come with ASP.NET Core 2.1 (his blog post was written prior to 2.1 release). After that, Identity Scaffold could be used to add Identity to it.

Another approach would be to create a new ASP.NET Core 2.1 project with Identity enabled and then add Aurelia to it. This is what we will do here.

Now create a new Aurelia app in another folder using Aurelia CLI. We don't want the CLI to overwrite files in our ASP.NET Core project. We'll copy and modify files we need manually. Make sure you select TypeScript (that's what OP was using) and ASP.NET Core in options.

> npm install aurelia-cli -g
> au new

Copy the following folders from the generated Aurelia app to the previously generated ASP.NET Core app:

aurelia_project
src

And the following files:

index.ejs
package.json
package-scripts.js
tsconfig.json
tslint.json
webpack.config.js
webpack.netcore.config.js

After these files are copied, we can run npm install to install all the required npm packages.

Before we start modifying files, we need to figure out what we are trying to achieve. There are (at least) three ways we can add authentication, depending on how far we want to go down the rabbit hole:

Use the default implementation of Identity and protect access to Aurelia app.
Reimplement the whole ASP.NET Core Identity UI in Aurelia.
Have something in between, like have login only implemented in Aurelia and the rest (registration, forgot password, management, etc.) implemented in MVC.

We will go with option #1, as that is the easiest route. We'll leave the default Identity implementation intact (login, register, forget password) and serve Aurelia app from the main route (/Home/Index). [Authorize] attribute will be added to HomeController in order to force the user to log in before accessing Aurelia app.

Note that this option will be viable only if we host the Aurelia app within the same ASP.NET Core app. If we had a separate project for it and a separate URL for hosting the client-side Aurelia app, we would probably go with option #2 or #3.

Option #2 is not easy to implement since Identity has a lot of different functionality. That could be a good topic for another blog post. For simple apps, option #1 works pretty well.

Let's start modifying files. First, we'll replace Views/Home/Index.cshtml content in ASP.NET Core app with a content from Views/Shared/_Layout.cshtml of Aurelia app and then define the body and scripts. The end result will be this:

@{
    Layout = null;
    ViewData["Title"] = "Home page";
}
<html>
<head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>@ViewData["Title"] - Aurelia</title>

    <link rel="stylesheet" href="~/dist/vendor.css" asp-append-version="true" />
</head>
<body>
    <div aurelia-app="main">Loading...</div>

    <environment names="Development">
        <script type="text/javascript" src="~/dist/vendor.bundle.js" asp-append-version="true"></script>
        <script type="text/javascript" src="~/dist/app.bundle.js" asp-append-version="true"></script>
    </environment>
    <environment names="Production">
        <script type="text/javascript" asp-src-include="~/dist/common.*.bundle.js" asp-append-version="true"></script>
    </environment>
    <environment names="Staging, Production">
        <script type="text/javascript" asp-src-include="~/dist/vendor.*.bundle.js" asp-append-version="true"></script>
        <script type="text/javascript" asp-src-include="~/dist/app.*.bundle.js" asp-append-version="true"></script>
    </environment>
</body>
</html>

Next thing - Startup class. In there we need to add two things, to enable Webpack dev middleware, which is a part of JavaScriptServices and to add SPA fallback route. Both of those changes are inside Configure method, so this is how it will look like after:

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
        app.UseDatabaseErrorPage();

        // This is added
        app.UseWebpackDevMiddleware(new WebpackDevMiddlewareOptions
        {
            HotModuleReplacement = true,
            ConfigFile = "webpack.netcore.config.js",
            HotModuleReplacementClientOptions = new Dictionary<string, string> { {"reload", "true"} }
        });
    }
    else
    {
        app.UseExceptionHandler("/Home/Error");
        app.UseHsts();
    }

    app.UseHttpsRedirection();
    app.UseStaticFiles();
    app.UseCookiePolicy();

    app.UseAuthentication();

    app.UseMvc(routes =>
    {
        routes.MapRoute(
            name: "default",
            template: "{controller=Home}/{action=Index}/{id?}");

        // This is added
        routes.MapSpaFallbackRoute(
            name: "spa-fallback",
            defaults: new {controller = "Home", action = "Index"});
    });
}

If we try to build the project now, we'll get TypeScript (tsc) errors, since it seems to be too eager to include all .js files it finds into compilation. To prevent it, wwwroot and ./*.js exclusions need to be added into tsconfig.json file:

"exclude": [
    "node_modules",
    "aurelia_project",
    "wwwroot",
    "./*.js"
]

Great, we can run the application now and get the output from Aurelia, but no authentication has been involved. Let's add [Authorize] attribute to HomeController's Index method.

public class HomeController : Controller
{
    [Authorize]
    public IActionResult Index()
    {
        return View();
    }

    // other methods ...
}

If we run the application now and browse https://localhost:[port]/, we will be automatically redirected to login page. After login (and probably the initial registration), we will be redirected back to the home page which hosts our Aurelia app.

We can also try building Aurelia app from the command line with au build. It should work as expected. In fact, there's one more feature we missed when copying from the Aurelia app generated with au new. Project file also contained an additional target for publishing the Webpack Aurelia output:

<Target Name="PublishRunWebpack" AfterTargets="ComputeFilesToPublish">
    <!-- As part of publishing, ensure the JS resources are freshly built in production mode -->
    <Exec Command="npm install" />
    <Exec Command="au build --env prod" />
    <!-- Include the newly-built files in the publish output -->
    <ItemGroup>
        <DistFiles Include="wwwroot\dist\**" />
        <ResolvedFileToPublish Include="@(DistFiles->'%(FullPath)')" Exclude="@(ResolvedFileToPublish)">
        <RelativePath>%(DistFiles.Identity)</RelativePath>
        <CopyToPublishDirectory>PreserveNewest</CopyToPublishDirectory>
        </ResolvedFileToPublish>
    </ItemGroup>
</Target>

With this change, dotnet publish operation now also creates an output from Aurelia app.

That's it, we have a client-side Aurelia app used in combination with server-side ASP.NET Core app with authentication and ASP.NET Core Identity enabled. By default, a cookie-based authentication is configured. If we need to make an API calls from Aurelia app to ASP.NET Core, we would also need to send cookies with each fetch request from the client - assuming that authorization is required for all API calls on the server side (and you do require it, don't you?). Usually, cookie-based authentication is not the best choice for API calls. Token-based authentication should be used instead.

Bonus: Authorizing API calls from Aurelia app with JWT tokens

The plan is to leave the current cookie-based authentication enabled for use in Identity (and potentially other MVC based pages) and to add JWT token based authentication too. Shawn Wildermuth has a good post about enabling dual mode authentication.

The following code should be added to Startup.ConfigureServices method, just before the services.AddMvc()... line:

services.AddAuthentication()
    .AddCookie(cfg => cfg.SlidingExpiration = true)
    .AddJwtBearer(cfg =>
    {
        cfg.SaveToken = true;

        cfg.TokenValidationParameters = new TokenValidationParameters()
        {
            ValidIssuer = Configuration["Tokens:Issuer"],
            ValidAudience = Configuration["Tokens:Issuer"],
            IssuerSigningKey = new SymmetricSecurityKey(Encoding.UTF8.GetBytes(Configuration["Tokens:Key"]))
        };
    });

This code depends on a presence of several configuration options, so we need to add those to appsettings.json or another configuration source. Make sure these options are overridden and that strong key is used for production.

"Tokens": {
    "Key": "2b0c0b6d-28ee-430b-b644-aaf99a195161",
    "Issuer": "https://miroslavpopovic.com"
}

Now that we have added JWT authentication, we need to have a mechanism of sharing the token and other data with the client side app. One easy approach might be to generate new JWT token each time user access the home page and send it to the browser together with the HTML that hosts Aurelia app. It avoids the extra call to the server to retrieve user data (including the token), but be aware that it might not be the best choice from the security standpoint - make sure you are on HTTPS!

This class will contain the data that will be passed on to the client:

public class ConfigViewModel
{
    public string UserName { get; set; }
    public string Token { get; set; }
}

Let's add GenerateToken method to HomeController:

// A better approach would be to have this in a separate class
// Note that this is just a sample implementation!
private static string GenerateToken(string name, bool isAdmin, string issuer, string key)
{
    var claims = new List<Claim>
    {
        new Claim(JwtRegisteredClaimNames.Sub, name),
        new Claim(JwtRegisteredClaimNames.Jti, Guid.NewGuid().ToString())
    };
    if (isAdmin) claims.Add(new Claim(ClaimTypes.Role, "admin"));

    var securityKey = new SymmetricSecurityKey(Encoding.UTF8.GetBytes(key));
    var creds = new SigningCredentials(securityKey, SecurityAlgorithms.HmacSha256);

    var token = new JwtSecurityToken(
        issuer,
        issuer,
        claims,
        expires: DateTime.Now.AddDays(1),
        signingCredentials: creds);

    return new JwtSecurityTokenHandler().WriteToken(token);
}

We'll inject IConfiguration into HttpController constructor and modify the Index method to call token generator and give necessary data to the view:

[Authorize]
public IActionResult Index()
{
    var token = GenerateToken(
        User.Identity.Name,
        User.IsInRole("admin"),
        _configuration["Tokens:Issuer"],
        _configuration["Tokens:Key"]);

    return View(new ConfigViewModel {UserName = User.Identity.Name, Token = token});
}

The Index view also needs to be changed. @model ConfigViewModel needs to be added to the top and <div> that acts as a container for Aurelia app needs to accept data-* parameters:

<div aurelia-app="main" data-username="@Model.UserName" data-token="@Model.Token">Loading...</div>

In Aurelia app, we'll modify main.ts to register the instance of serverConfig:

aurelia.container.registerInstance(
    'serverConfig',
    Object.assign({}, (aurelia.host as HTMLElement).dataset));

app.ts or any other components can now inject serverConfig and use it for binding, API calls, etc.:

import { inject } from 'aurelia-framework';

@inject('serverConfig')
export class App {
    message = 'Hello World!';
    serverConfig;

    constructor(serverConfig) {
        this.serverConfig = serverConfig;
    }
}

app.html content:

<template>
    <h1>${message}</h1>
    <h2>Welcome ${serverConfig.username}</h2>
    <p>Your JWT token for API calls is: ${serverConfig.token}</p>
</template>

Finally, we'll add DataController that will require JWT authorization for calls:

using System;
using Microsoft.AspNetCore.Authentication.JwtBearer;
using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;

namespace AspNetCoreAurelia.Controllers
{
    [ApiController]
    [Authorize(AuthenticationSchemes = JwtBearerDefaults.AuthenticationScheme)]
    public class DataController : Controller
    {
        [HttpGet("/api/data")]
        public IActionResult Index()
        {
            return Ok(new {data = new Random().Next(1, 100)});
        }
    }
}

To call the API we'll use aurelia-fetch-client plugin which needs to be installed first:

> npm install aurelia-fetch-client

Again, app.ts will be modified with a new loadData() method that's using aurelia-fetch-client:

import { inject } from 'aurelia-framework';
import { HttpClient } from 'aurelia-fetch-client';

@inject('serverConfig', HttpClient)
export class App {
    data;
    message = 'Hello World!';
    http;
    serverConfig;

    constructor(serverConfig, http) {
        this.serverConfig = serverConfig;
        this.http = http;

        http.configure(config => {
            config
                .useStandardConfiguration()
                .withBaseUrl('/api/')
                .withDefaults({
                    headers: {
                        'Accept': 'application/json',
                        'Authorization': 'Bearer ' + serverConfig.token
                    }
                });
        });
    }

    loadData() {
        this.http.fetch('data')
            .then(response => response.json())
            .then(result => {
                this.data = result.data;
            });
    }
}

app.html will be modified too to have a button that triggers the call to loadData() method and displays the result of the API call:

<template>
    <h1>${message}</h1>
    <h2>Welcome ${serverConfig.username}</h2>
    <p>Your JWT token for API calls is: ${serverConfig.token}</p>

    <button class="btn btn-default" click.trigger="loadData()">Load Data</button>

    <div if.bind="data">
        Random data from server is: ${data}
    </div>
</template>

Here's the final result in all its glory:

The finished sample code can be found on GitHub.

Summary

So, that's it. We talked about how to add ASP.NET Core Identity to the existing project with ASP.NET Core and Aurelia. After that, we have considered options for creating a new ASP.NET Core and Aurelia project that has Identity implemented from the start and choose to implement the easiest one.

Unfortunately, we don't have a template that would cover this - to generate an ASP.NET Core app with Identity and Aurelia, but it's not that hard to do it now when we have Aurelia CLI at our disposal and also Identity scaffolding. It will be even easier when Aurelia CLI updates the ASP.NET Core output to 2.1. Hopefully, it will happen soon and you can always jump in to help, it's open source after all :).

Finally, I will leave you with a thought. Do consider whether you really want to have Aurelia (or any other client-side framework) in the same project as your backend. Microservices are a buzzword today, and with a good reason. Serving static client-side code and serving backend API from the same server may affect the performance. When you have them separately it's easier to scale them appropriately. The client-side code could be served from CDN optimized for static files and with aggressive caching involved. Backend code could then be scaled up easily to accommodate higher request count and not to be bogged down by static files. There are a PowerPoint presentation and sample code that you might find interesting on my GitHub repository with a microservice-like organization. It has ASP.NET Core backend, Postgres database, HAProxy balancer and Aurelia frontend in separate Docker containers.

Again, the code from this post can be found on GitHub.

Using Elasticsearch with ASP.NET Core and Docker

Thu, 12 Jul 2018 00:00:00 GMT

Recently, I got an assignment for my employer's internal project to investigate Elasticsearch and its usage from within ASP.NET Core 2.1 app. I had no prior knowledge of Elasticsearch, but I had some experience with Solr and earlier with NHibernate Search which also used Lucene under the cover. This post is a summary of my research.

So, what exactly is Elasticsearch?

Elasticsearch is a distributed, RESTful search and analytics engine. It's based on Lucene and provides a JSON based REST API on top of it, among other things. It also has a rich ecosystem of tools and a number of official and unofficial client libraries. There are two official .NET clients, a low-level Elasticsearch.Net which is just an unopinionated wrapper around REST API and a high-level NEST library built on top of Elasticsearch.Net which provides strongly typed, fluent query DSL.

Elasticsearch installation

Almost all of my development work is done on Windows and for it, we have several installation options, including a simple .zip file package, an .msi installation package and of course docker images.

If you are going with .zip or .msi package, you'll also need to install Java 8 SDK or later. Once unpacked or installed, you can run Elasticsearch from the command line or install it as a Windows service. Since I don't have Java SDK installed but have Docker, I'm going with Docker image option.

Elastic, the company behind the Elasticsearch, is hosting their own Docker registry. To pull the latest Elasticsearch image (version 6.3.0 at the moment of writing) from the registry, you need to execute this command:

> docker pull docker.elastic.co/elasticsearch/elasticsearch:6.3.0

Kibana is also interesting for playing around with Elasticsearch. It's a web GUI that lets you visualize Elasticsearch data and navigate through the whole Elastic Stack. To pull its image, execute this command:

> docker pull docker.elastic.co/kibana/kibana:6.3.0

Now that we have both Elasticsearch and Kibana downloaded, we can run them under the same network. First, let's create a Docker network:

> docker network create esnetwork --driver=bridge

With the network set up, run both Elasticsearch and Kibana containers:

> docker run -p 9200:9200 -p 9300:9300 -e "discovery.type=single-node" --name elasticsearch -d --network esnetwork docker.elastic.co/elasticsearch/elasticsearch:6.3.0
> docker run -p 5601:5601 --name kibana -d --network esnetwork docker.elastic.co/kibana/kibana:6.3.0

We also need to map a volume to avoid the data being reset each time we restart the container, which further complicates the command. Instead of that, we can use docker-compose. Let's create docker-compose.yml file with the following content:

version: '2'
services:
    elasticsearch:
        image: docker.elastic.co/elasticsearch/elasticsearch:6.3.0
        ports:
            - "9200:9200"
            - "9300:9300"
        volumes:
            - esdata:/usr/share/elasticsearch/data
        networks:
            - esnetwork
    kibana:
        image: docker.elastic.co/kibana/kibana:6.3.0
        ports:
            - "5601:5601"
        networks:
            - esnetwork
        depends_on:
            - elasticsearch
volumes:
    esdata:
        driver: local
networks:
    esnetwork:
        driver: bridge

So, in short, we create two services elasticsearch and kibana and connect them via bridge network. kibana depends on elasticsearch in order to prevent it from being started first. If elasticsearch container start fails, kibana will fail too. We are also using the default ports for both.

To run everything, we can just do:

> docker-compose up

Now both Elasticsearch and Kibana are started. Browse http://localhost:5601/ to be greeted with Kibana dashboard.

That's everything we need for running Elasticsearch in dev environment. Installation on production environment shouldn't be too hard either as there are packages for various Linux distros. Also, there are Elasticsearch SaaS offerings from all major cloud vendors and from Elastic itself.

Sample project creation

To see how Elasticsearch works with ASP.NET Core, we'll create a new blog project, using Mads Kristensen's MiniBlog.Core template. MiniBlog is a simple blogging engine built on ASP.NET Core 2.0.

If you don't want to follow the step-by-step creation of the new project and adding functionality to it, there's a complete sample on GitHub.

On the command line, install the template:

> dotnet new --install MadsKristensen.AspNetCore.Miniblog

Then create the project and add the NEST NuGet package:

> dotnet new miniblog --name MiniBlogElasticsearch
> dotnet add package NEST

Open the project with Visual Studio Code or with Visual Studio 2017:

> code .

If you start the debugging now or do dotnet run from the command line, you should get the following welcome post in your browser:

You can log in (using Sign in link at the bottom of the page) and create new posts - we will need several in order to test how search is working. Use demo for both username and password.

Configuring Elasticsearch client

NEST NuGet package is already installed in the previous step. NEST is a high level .NET client for Elasticsearch which provides a way to call Elasticsearch REST APIs via strongly-typed, easy to use, query DSL. There's a good Getting started document on Elastic search documentation which can bring you up to speed.

For connecting to Elasticsearch API, we will use ElasticClient which needs to be configured first. The documentation states that ElasticClient is thread safe and hence it's possible to use a singleton instance of it per application (or per index). In order to be good ASP.NET Core citizens, let's initialize everything we need for Elasticsearch in Startup class' ConfigureServices method. Of course, we'll follow the best practices and add extension method for it:

// In Startup class
public void ConfigureServices(IServiceCollection services)
{
    // ...
    services.AddElasticsearch(Configuration);
}

And here's the basic extension method implementation:

public static class ElasticsearchExtensions
{
    public static void AddElasticsearch(
        this IServiceCollection services, IConfiguration configuration)
    {
        var url = configuration["elasticsearch:url"];
        var defaultIndex = configuration["elasticsearch:index"];

        var settings = new ConnectionSettings(new Uri(url))
            .DefaultIndex(defaultIndex)
            .DefaultMappingFor<Post>(m => m
                .Ignore(p => p.IsPublished)
                .PropertyName(p => p.ID, "id")
            )
            .DefaultMappingFor<Comment>(m => m
                .Ignore(c => c.Email)
                .Ignore(c => c.IsAdmin)
                .PropertyName(c => c.ID, "id")
            );

        var client = new ElasticClient(settings);

        services.AddSingleton<IElasticClient>(client);
    }
}

The method expects that there is an elasticsearch section in the configuration, so we need to add it to appsettings.json (or other configuration source):

{
    "elasticsearch": {
        "index": "miniblog",
        "url": "http://localhost:9200/"
    }
}

index should point to the default index in Elasticsearch and url to the actual address of our Elasticsearch instance. Note that the organization within Elasticsearch is a bit different than within relational database server. When I first looked into it, I thought that index is an equivalent of a single database and type an equivalent of a database table. However, it's not really like that. Types are now obsolete from version 6.0.0 and will be completely removed in version 7.0.0. Indices should contain a single type only. Fortunately, we only have one type that needs to be indexed and searched - a blog Post. Comment type is nested and indexed under Post.

From the docs: Indices created in Elasticsearch 6.0.0 or later may only contain a single mapping type. Indices created in 5.x with multiple mapping types will continue to function as before in Elasticsearch 6.x. Mapping types will be completely removed in Elasticsearch 7.0.0.

OK, back to AddElasticsearch extension method. It also creates default mappings for our types. We are choosing not to index Post.IsPublished, Comment.Email (GDPR everyone?) and Comment.IsAdmin properties. Plus, we want to have better names for ID properties in index - id instead of iD.

Once ConnectionSettings are defined, we create a new instance of ElasticClient using those settings and register it as a singleton under .NET Core dependency injection container.

Indexing blog posts

Great, we can now use IElasticClient when we need to communicate with Elasticsearch instance. Let's use it to add posts to the index whenever they are saved.

Open Services/FileBlogService.cs in your editor and locate SavePost(Post post) method. MiniBlog saves all the blog posts as separate XML files under wwwroot/Posts folder and SavePost method does the actual saving. We'll modify it by adding some code at the beginning and at the end of the method:

// Inject IElasticClient to the constructor

public async Task SavePost(Post post)
{
    string filePath = GetFilePath(post);
    post.LastModified = DateTime.UtcNow;

    // Add this line:
    bool postExists = File.Exists(filePath);

    // ... rest of the method functionality

    // Add these lines at the end:
    if (postExists)
        await _elasticClient.UpdateAsync<Post>(post, u => u.Doc(post));
    else
        await _elasticClient.IndexDocumentAsync(post);
}

In order to index the blog Post we check if the post already exists. If it does, we assume it's already a part of the index, so we do UpdateAsync. Elasticsearch will identify the post by id. If it doesn't already exist, it will call IndexDocumentAsync.

Blog Posts can also be deleted. We need to modify DeletePost(Post post) method too:

public async Task DeletePost(Post post)
{
    string filePath = GetFilePath(post);

    if (File.Exists(filePath))
        File.Delete(filePath);

    await _elasticClient.DeleteAsync<Post>(post);

    if (_cache.Contains(post))
        _cache.Remove(post);
}

It's possible that index sometimes gets out of sync with actual posts - like when we are adding posts without starting Elasticsearch first, or if we have created posts before implementing the indexing changes above. To cover these cases, we'll create a simple reindex operation (NOT for production use). We can have it under the new SearchController:

public class SearchController : Controller
{
    private readonly IBlogService _blogService;
    private readonly IElasticClient _elasticClient;
    private readonly IOptionsSnapshot<BlogSettings> _settings;

    public SearchController(IBlogService blogService, IElasticClient elasticClient, IOptionsSnapshot<BlogSettings> settings)
    {
        _blogService = blogService;
        _elasticClient = elasticClient;
        _settings = settings;
    }

    [Authorize]
    [Route("/search/reindex")]
    public async Task<IActionResult> ReIndex()
    {
        await _elasticClient.DeleteByQueryAsync<Post>(q => q.MatchAll());

        var allPosts = (await _blogService.GetPosts(int.MaxValue)).ToArray();

        foreach (var post in allPosts)
        {
            await _elasticClient.IndexDocumentAsync(post);
        }

        return Ok($"{allPosts.Length} post(s) reindexed");
    }
}

The implementation is pretty naïve (like I said, NOT for production use). It deletes all posts from the index using match_all operator of Elasticsearch and then recreates the index by adding all posts to the index one by one. There's a better way to do this for production - Reindex API but our implementation is good enough for a simple demo.

When we navigate to http://localhost:[our-port]/search/reindex in the browser, it will trigger reindexing and display the number of indexed posts.

That's it! Our Elasticsearch index now has data we can use. Let's try to see it in Kibana. Navigate to http://localhost:5601/app/kibana#/dev_tools/console and enter the following in the console:

GET miniblog/_search
{
    "query": { "match_all": {} }
}

It will use the match_all operator to return everything in our miniblog index. Depending on the number of posts you have added you might have a different total number:

Implementing search operation

Excellent! We have data indexed but we're not using it for anything from the application itself. Let's add search operation next. Add the following to our SearchController:

[Route("/search")]
public async Task<IActionResult> Find(string query, int page = 1, int pageSize = 5)
{
    var response = await _elasticClient.SearchAsync<Post>(
        s => s.Query(q => q.QueryString(d => d.Query(query)))
            .From((page - 1) * pageSize)
            .Size(pageSize));

    ViewData["Title"] = _settings.Value.Name + " - Search Results";
    ViewData["Description"] = _settings.Value.Description;

    if (!response.IsValid)
    {
        // We could handle errors here by checking response.OriginalException or response.ServerError properties
        return View("Results", new Post[] { });
    }

    if (page > 1)
        ViewData["prev"] = GetSearchUrl(query, page - 1, pageSize);
    if (response.IsValid && response.Total > page * pageSize)
        ViewData["next"] = GetSearchUrl(query, page + 1, pageSize);

    return View("Results", response.Documents);
}

private static string GetSearchUrl(string query, int page, int pageSize)
{
    return $"/search?query={Uri.EscapeDataString(query ?? "")}&page={page}&pagesize={pageSize}/";
}

It's pretty simple. QueryString full text query is used for searching for the string passed in from the browser. QueryString searches in all fields by default and that's what we need. A pagination is also implemented with page and pageSize parameters, used as arguments for From and Size methods of NEST fluent DSL.

Tip: Errors are not handled. By default, NEST doesn't throw exceptions, neither for search nor for indexing operations. We can change that when configuring the client. When exceptions aren't thrown, you can check the response object. response.IsValid will be false in case of any error and response.ServerErrors or response.OriginalException would contain actual errors or exceptions. We could for instance check which error happens and send it to the view to display it to the user.

The backend is implemented. We now need to add a search form to our pages. We'll add it below the header in _Layout.cshtml:

<header class="siteheader">
    <div class="container">
        <p itemprop="name"><a href="~/">@settings.Value.Name</a></p>
        By <span itemprop="author">@settings.Value.Owner</span>
    </div>
    <!-- Insert search form here: -->
    <form class="container" asp-action="Find" asp-controller="Search" method="get">
        <input type="search" name="query" placeholder="Search..." value="@ViewContext.HttpContext.Request.Query["query"]" />
    </form>
</header>

When user enters a value in search input and hits Enter, it will trigger the search operation and redirect the browser to search results. As a last thing, let's add Views/Search/Results.cshtml Razor view:

@model IEnumerable<Post>
<div class="container search-results">
    <h1>Search results</h1>

    @if (!Model.Any())
    {
        <p>Nothing found for: <em>@ViewContext.HttpContext.Request.Query["query"]</em></p>
    }

    @foreach (var post in Model)
    {
        <article class="post">
            <header>
                <h2><a asp-controller="Blog" asp-action="Post" asp-route-slug="@post.Slug">@post.Title</a></h2>
                <time datetime="@post.PubDate.ToString("s")" itemprop="datePublished">Published @post.PubDate.ToString("MMM d, yyyy")</time>
                @if (User.Identity.IsAuthenticated)
                {
                    <a asp-controller="Blog" asp-action="edit" asp-route-id="@post.ID" title="Edit the post">Edit post</a>
                }
            </header>
            <p>@post.Excerpt</p>
        </article>
    }

    <nav class="pagination" aria-label="Pagination">
        @if (ViewData["prev"] != null)
        {
            <a rel="prev" href="@ViewData["prev"]" title="Previous results">&laquo; Previous</a>
        }
        @if (ViewData["next"] != null)
        {
            <a rel="next" href="@ViewData["next"]" title="Next results">Next &raquo;</a>
        }
        <br /><br />

        @section Head {
            @if (ViewData["prev"] != null)
            {
                <link rel="prev" href="@ViewData["prev"]" />
            }
            @if (ViewData["next"] != null)
            {
                <link rel="next" href="@ViewData["next"]" />
            }
        }
    </nav>
</div>

Search page displays a list of Posts found by Elasticsearch in response to the given query.

If we search for something on our site, this is what we will get:

Pagination will work too if you have more than 5 results.

Summary

This is just a tip of the iceberg. Elasticsearch has a vast number of features that you can use. The sample application on GitHub implements a few more features like boosting, custom analyzers, tokenization, character filters, etc. You can find that in ElasticsearchExtensions.cs file.

A thing to keep in mind is - make sure you double check everything before going into production.

First of all, you don't want Elasticsearch or Kibana's port exposed publicly! It should be accessible from your app backed only. It can (and should) also be protected with authentication. Check out X-Pack Authenticate API and SSL Certificate API for that.

Second, don't just throw everything into the index. Pick up only the data that makes sense. Adding a bunch of data just for the sake of having them indexed will hurt the performance, but more importantly, you'll get into trouble when you need to delete something. Remember GDPR? User data should be kept out of the index unless it's absolutely necessary. The other security-critical information too. Data breaches happen all the time. Don't be a part of the statistics.

So, what's my final thought on Elasticsearch? It's an excellent and powerful tool and it fulfilled my expectations.

However, what I didn't expect is the quality of the documentation. It's fantastic! There's an API reference, getting started documentation, best practices, an excellent documentation for the clients, etc. And not just the documentation for Elasticsearch, but for Docker and ASP.NET Core too. Long gone are the days where we had dry MSDN documentation with unoptimized and often wrong samples written by technical writers and not by developers.

Getting started with something as complex as Elasticsearch these days is easy thanks to an excellent documentation, so kudos to people from Elastic and community for writing them! All the Elasticsearch docs are editable on GitHub. Kudos also go to Docker and ASP.NET Core documentation that's also available for editing on GitHub. This is truly a documentation renaissance.

Conference Bonanza

Mon, 16 Apr 2018 00:00:00 GMT

The following few weeks will be pretty furious for me, as I'm going to attend several conferences as a speaker.

Microsoft NetWork 8, Neum

This is our local Microsoft conference now almost traditionally held in Neum, a small town in Bosnia and Herzegovina on the Adriatic Sea.

Back on NetWork after a 2 year break. My slot is on Thursday at 11 am with a talk "Docker and ASP.NET Core (2.1)". The sample for this talk can be found on GitHub where I'll also put a link to the slides after the presentation.

Microsoft WinDays 18, Poreč

A week after, I'm off to Croatia and again to the Adriatic Sea. Microsoft WinDays conference is held in Poreč this year, with WinDays Technology from 25th to 27th of April.

This is my first WinDays conference which I'm really looking forward to. I got the last slot on Friday, just before the lunch at 1:30 pm. Only half an hour so I had to reorganize my demos a bit. The talk is "Building Production-Ready APIs with ASP.NET Core 2.1" which is my old talk but with latest ASP.NET Core 2.1 changes incorporated. The samples can also be found on GitHub. Link to the slides will be available after the presentation.

Weblica 2018, Čakovec

Finally, on May 12th, I'm in Croatia again. This time in Čakovec, a small town in the north part of Croatia. Unlike the previous two conferences Weblica is community driven.

I had a pleasure of presenting on this conference few years ago. They have great people there, fantastic nature and also great food. My slot is the first one after the keynote, at 9:30 am and the talk is the same as on WinDays but 15 minutes longer.

Honorable mentions

Tarabica 2018, Belgrade

Another community conference this time in Belgrade, Serbia. My plan was to nominate the talk there too this year, but unfortunately it's on the same day as Weblica where I was already accepted as a speaker. Nah, maybe next year. For those interested to attend, you can find more info on http://www.tarabica.org. The attendance is free.

Seavus conference, Skopje

Finally, my employer Seavus is planning a one day conference in Skopje. But guess what, also on May 12th. There must be something about that day...

Anyway, three conferences are more than enough for such a short period. I'm looking forward to meet a lot of other speakers / friends and of course enjoy a bit of time off from my daily routine.

Upcoming HTTP API related changes in ASP.NET Core 2.1

Sun, 18 Feb 2018 00:00:00 GMT

Two weeks ago ASP.NET team unveiled its roadmap for ASP.NET Core 2.1 release. In addition to some highly expected features like new SignalR version, Identity changes and WebHooks, the things that I'm most excited of are Web API improvements. These changes are summed up in an initiative with a funny name - Project KodKod - and a goal "to make MVC into a opinionated, forward-thinking, batteries included framework for HTTP APIs".

Ever since ASP.NET Web API was introduced, almost 6 years ago, it became THE way that I was working with ASP.NET. I used it mostly to build a backend for SPA applications and on a few API only projects. My experience of building APIs is summed up in a talk that I've been presenting on local conferences and user group meetings, called "Building production ready APIs with ASP.NET Core 2.0". The samples and the conference PowerPoint presentations can be found on GitHub. As ASP.NET Core 2.1 is coming with a number of new API-related features, it could be a good time to update my presentation. So, let's see what are some of those features...

HTTPS by default

While not really an API specific feature, it's something that is more or less a must for public facing APIs. When you create a new ASP.NET Core 2.1 project, the template will enable HTTPS by default. A default local certificate will be created during .NET Core SDK installation. There will also be a new tool for managing certificates that will probably be installed as global tool. Global tools are a feature similar to Node global tools which will enable creation and distribution of tools ecosystem via NuGet. You can read more about it on .NET Core 2.1 roadmap.

In addition to HTTPS by default, the template will also enable HSTS - HTTP Strict Transport Security protocol - which will prevent browsers to try HTTP address. HTTPS will be forced.

Better Swagger / OpenAPI specification support

For a long time, Swagger was de facto a standard for describing RESTful APIs but there were other tools too. That changed last year when SmartBear Software, a company behind Swagger, donated Swagger 2.0 specification to the OpenAPI initiative. Today, it's known as OpenAPI specification 3.0 and it's backed up by all the big players in API space.

ASP.NET Core 2.1 will come with a new type - ActionResult<T> which will enable discoverability of the action result type, without the need for additional attributes that is required now to get the correct metadata.

Also, a new tool will be added for build-time OpenAPI generation - at the moment we have only runtime generation. More features are planned for future versions.

`[ApiController]` attribute

This is my favorite new feature that will bring back some conventions we had in old ASP.NET Web API. Basically, you will decorate controller class with [ApiController] and MVC will be able to infer some defaults and do additional processing on your action methods. This is what we will have for start:

Automatic model state validation

No need to write if (!ModelState.IsValid) return BadRequest(ModelState);. Validation will be done automatically before calling your action method.

One of the best practices I've been preaching is wrapping a response in an object that has properties like Error and IsSuccessful in addition to the actual data. ASP.NET Core 2.1 will take a different approach by introducing a validation error response in the shape of RFC 7807 standardized response, but you will be able to override it.

Inferring defaults on action method parameters

One thing that we lost in transition from the old ASP.NET Web API were automatic recognition of the source for action method parameters. This is coming back to ASP.NET Core 2.1 controllers decorated with [ApiController]. [FromBody] will be default for complex types. [FromRoute] will be used when possible and otherwise [FromQuery].

Other

There are few more things that will be enabled with the new [ApiController] attribute. You can find more in depth review of this attribute in a post by Filip W.

Sample

To summarize, let's take a look at one of the action methods that I have in my presentation sample code, and how it would look like in ASP.NET Core 2.1.

// Sample: ASP.NET Core 2.0
[Authorize]
[Route("api/games")]
public class GamesController : Controller
{
    private readonly IGamesRepository _gamesRepository;

    public GamesController(IGamesRepository gamesRepository)
    {
        _gamesRepository = gamesRepository;
    }
    
    /// <summary>
    /// Create a new game from the supplied data.
    /// </summary>
    /// <param name="model">Data to create the game from.</param>
    /// <response code="200">Returns the created game.</response>
    [Authorize(Roles = "admin")]
    [HttpPost]
    [ProducesResponseType(typeof(ApiResult<Game>), 200)]
    public IActionResult Post([FromBody] GameInput model)
    {
        if (!ModelState.IsValid)
            return BadRequest(ModelState);

        var game = new Game();
        model.MapToGame(game);

        _gamesRepository.Create(game);

        var url = $"{Request.Scheme}://{Request.Host}/api/games/{game.Id}";

        return Created(url, game.WrapData());
    }       
}

// Sample: ASP.NET Core 2.1
[ApiController]
[Authorize]
[Route("api/games")]
public class GamesController : Controller
{
    private readonly IGamesRepository _gamesRepository;

    public GamesController(IGamesRepository gamesRepository)
    {
        _gamesRepository = gamesRepository;
    }
    
    /// <summary>
    /// Create a new game from the supplied data.
    /// </summary>
    /// <param name="model">Data to create the game from.</param>
    [Authorize(Roles = "admin")]
    [HttpPost]
    public ActionResult<Game> Post(GameInput model)
    {
        // No model state validation code here, hooray!

        var game = new Game();
        model.MapToGame(game);

        _gamesRepository.Create(game);

        var url = $"{Request.Scheme}://{Request.Host}/api/games/{game.Id}";

        return Created(url, game);
    }       
}

Conclusion

Since I haven't posted on my blog in a while, I felt obliged to share some of my thoughts on the current state of .NET (Core).

As a long-time ASP.NET developer, it's really nice to see how rejuvenated ASP.NET Core is rapidly improving with each version. At one moment, before .NET Core became a thing, it looked like .NET ecosystem became stale. Even I (an early proponent of .NET) have took a foray into Node.

.NET Core, .NET Standard and ASP.NET Core have brought back the hope for .NET developers in general. Open-source approach, multi-platform, beautiful C# language and a great performance could make ASP.NET Core a framework of choice and a force to recon in the server-side world.

We could even see a full-stack C# (similar to full-stack JavaScript with Node). Blazor, an experiment to create a client-side .NET web framework that's running in a browser via Web Assembly is now on ASP.NET team's GitHub repository. To learn more about it, watch ASP.NET Community Standup from two weeks ago.

If you didn't know, ASP.NET Community Standups have a new home on YouTube, under the .NET Foundation channel.

Finally, after some struggle, the future of .NET looks bright!

From Jekyll to Wyam

Wed, 19 Jul 2017 00:00:00 GMT

Back to .NET

After doing mostly JavaScript development in the last few years I decided that it's time to head back to .NET world and see what's new. Actually, I never really left. There was a bunch of older .NET projects that I have maintained in the meantime and few new ones, but all of them were on full .NET Framework. My plan is to dive into .NET Core and ASP.NET Core. While I've been closely following all the new development around .NET Core, I'm yet to do a concrete project with it. Hopefully, this is about to change.

For start, I'm switching this blog to Wyam, a .NET Core based static site generator. Hexo was one of the alternatives that I was looking into, but since it's Node.js based, I decided it's more appropriate to go with .NET Core based platform.

It seems that each time when I try to return to blogging I switch the blog platform, so let's continue with that practice :)

Phase 1 - Installing and initializing Wyam

Installation was easy as described in Wyam documentation. I have downloaded the latest Windows Installer and run it. After that it's necessary to go to %LocalAppData%\Wyam and run Wyam.Windows add-path to add the Wyam installation folder to Windows PATH variable.

Next step, reading the documentation. Seriously, I do prefer to read the docs first to get myself more familiar with something I'm interested in and Wyam has a pretty good documentation.

My blog is hosted on GitHub Pages. Old version was using Jekyll. To start with the migration, I have created a new git branch. Initializing Wyam was as simple as wyam new -r Blog to create a new configuration using Blog recipe.

Wyam has created config.wyam file that can be modified. This is my first configuration:

#recipe Blog

Settings[Keys.Host] = "blog.miroslavpopovic.com";
Settings[BlogKeys.IncludeDateInPostPath] = true;
Settings[BlogKeys.RssPath] = "feed.xml";
Settings[BlogKeys.Title] = "Miroslav Popovic";
Settings[BlogKeys.Description] = "Full-stack .NET and JavaScript software architect";

Few things that are changed from the default. I prefer to have date in URL, so BlogKeys.IncludeDateInPostPath is set to true. By default, Wyam generates two feed files, one for RSS - feed.rss and one for Atom - feed.atom format. My old setup had one RSS file - feed.xml. To prevent subscribers from making changes in their feed readers, BlogKeys.RssPath was set to feed-xml. Other settings should be self-expanatory.

With this it was possible to build the blog wyam build or build and watch for changes wyam build --watch. For previewing the result in browser wyam preview runs the integrated server on port 5080 by default.

Phase 2 - Moving assets

Jekyll used assets relative to root folder, like static pages (about.md), /images, favicons, etc. Wyam uses /input as a root, so all the files need to be moved there.

Phase 3 - Migrating posts

Wyam Blog recipe also supports markdown by default. Migrating posts to Wyam was as simple as moving them from Jekyll's _posts folder to Wyam's input/posts folder and changing few things in FrontMatter.

FrontMatter is a bit of metadata at the top of the post which you can use to define title, description, tags, dates, or any other custom metadata. There are some differences between Jekyll and Wyam FrontMatter syntax. I.e. tags in Jekyll are defined separated with space, like tags: tag1 tag2 tag3 and that will create a single tag in Wyam. For Wyam, you need to either define them with array syntax tags: [tag1, tag2, tag3] or split them to multiple lines:

tags:
  - tag1
  - tag2
  - tag3

Another difference is with redirects. Jekyll redirects are defined with redirect_from: "/some-url/" and Wyam supports this syntax: RedirectFrom: /some-url/. The fact that you can define multiple redirects using the same syntax as for tags made me very happy. This is especially usefull if you are doing several migrations, like I did (from FunnelWeb to Jekyll to Wyam):

RedirectFrom:
  - resurrection
  - 2012/06/10/resurrection

Since I don't have that many posts, I did all of these changes manually, but you could easily to search/replace in files.

Phase 4 - Tuning up the theme

The default Clean Blog theme looks very good, so that's what I have used. Overriding the parts of layout is as simple as copying and modifying the partial views from Clean Blog theme source, like _Scripts.cshtml (for defining Google Analytics script), _Head.cshtml (for favicons and other meta tags), etc. Modifying CSS was also simple. All that is required is a new file for style overrides - assets/css/override.css.

My blog is using Disqus for comments. Adding Disqus is described on Wyam docs. I was a bit concerned with preserving existing comments, but there are solutions for that too. One is described by Erik Onarheim in his migrating to Wyam post and another one is to use Disqus URL mapper.

Phase 5 - Deployment

Finally, the time has come to deploy. There's a pretty good guide about setting up the continuous deployment on Wyam docs so I won't repeat it here.

One problem I had is with git branches. My previous setup with Jekyll had master and gh-pages branches. Unfortunately, having the code in master branch and output in gh-pages does not work for user and organization pages on GitHub and my blog code is on user page. At least that's what the documentation told me. It only allows serving from master so I reorganized my git repository a bit. "Source" code is in source branch and AppVeyor build copies the output to master branch.

Finally

This blog is now generated using Wyam. At least until the next migration :)

Speaking Engagements

Mon, 27 Apr 2015 00:00:00 GMT

On Wednesday, 29. April, I'm holding a talk "Tales from the client side" on 5th Microsoft Bosnia and Herzegovina NetWork conference. The samples and presentation are available at https://github.com/miroslavpopovic/msnetwork5-sample.

At Saturday, 9. May I'm heading to Čakovec Croatia for Weblica conference, where I'm holding a talk "Building modern web in Microsoft world".

Looking forward to them!

Update: Weblica presentation is available at https://github.com/miroslavpopovic/web-ms-2015.

Switching to Jekyll

Mon, 23 Mar 2015 00:00:00 GMT

I decided to switch my blog from FunnelWeb to Jekyll and host it on GitHub Pages. There were some problems along the way so I'm documenting it here in case it might help someone. If you want a more detailed introduction to Jekyll, read Brian Rinaldi's Getting Started with Jekyll post.

Installing Jekyll on Windows

Since I'm not a designer, I decided to choose one of many Jekyll themes and modify if necessary. Changing the theme directly on GitHub would be clumsy, since a lot of files are involved. Also doing little changes and testing the outcome would require a lot of git commits. Instead, I cloned my repository locally and installed Jekyll and its requirements on my Windows machine.

There's a very good tutorial for installing Jekyll on Windows. Unfortunately it's a little bit older. I followed the guide and installed the latest version of x64 build of Ruby, Ruby DevKit, Jekyll, x64 build of Python and Pygments. The latest Ruby version at the time of writing was 2.2.1.

It looked like everything went smoothly, but when trying to run Jekyll serve on my blog repository, it failed. The problem was with one of the Ruby gems called nokogiri. Apparently, it doesn't work with Ruby 2.2.1 on Windows, so I had to fall back to older Ruby version - 2.1.5.

Of course, something had to go wrong with that too. After installing Ruby 2.1.5 x64 and Ruby DevKit, gem installation with the following message:

gem install jekyll
ERROR:  Could not find a valid gem 'jekyll' (>= 0), here is why:
       	Unable to download data from https://rubygems.org/ - SSL_connect returned=1 errno=0 state=SSLv3 read server certificate B: certificate verify failed (https://api.rubygems.org/latest_specs.4.8.gz)

This SO answer helped and I was able to install Jekyll after that.

Since I'm referencing few Ruby gems in _config.yml I had to install those too:

gem install jekyll-sitemap
gem install jekyll-redirect-from
gem install jemoji

Finally, running the following command started the build process and enabled file change watcher. Success!

jekyll serve --watch

I tested several themes locally, before settling up with Pixyll theme.

Creating user repository

There's an easy getting started guide on Smashing Magazine. I ended up with user repository forked from John Otander's Pixyll theme, instead of Jekyll Now that's described in the guide above.

In _config.yml file permalink is set to pretty. That's what I want it to be, since I prefer to have date in URL and no extension. My blog posts didn't have date in URL before, so I had also added jekyll-redirect-from gem to gems section. With this gem installed, you can tell Jekyll to create redirects from defined URL to the current page or post. This is done with Front Matter instruction on top of the post. For example:

---
layout: post
title: Resurrection
redirect_from: "/resurrection/"
---

Note that the redirect_from value needs to have trailing slash, otherwise GitHub Pages will serve the generated document as file download instead of a regular page, causing browsers to download it. Hopefully, this will not cause SEO problems since my previous URLs were without the trailing slash.

GitHub itself can serve as an editor for your posts. Since there were only nine posts on my blog, it was not necessary to create some kind of migration tool. I just added them one by one through GitHub repository (they were already in Markdown format).

One thing that needed to be changed was the format of links. Markdown supports two types of links inline and reference. I had reference links in my posts. They were processed correctly on post pages, but post excerpts on home page did not process them - they were displayed in markdown syntax. After switching to inline links it worked correctly.

Domain redirection

My old blog was hosted on ASPnix under a custom subdomain. Following the GitHub guide, I had to delete the subdomain first and create a custom cname record for blog that points to miroslavpopovic.github.io.

Also, FeedBurner had to be redirected to use /feed.xml file instead of /feed. Users that were subscribed to my RSS feed will get one time refresh of all items, since post ids are different.

Disqus was used for my blog comments and since my post URLs are changed, I also needed to create the map between old and new URLs. There's a migrate tool in Admin area of Disqus for that. To get to Admin area, log in to Disqus, and select Admin from your profile drop-down menu on top right. Select your blog if not already selected and go to Discussion / Tools / Upload a URL map. You'll find the instructions on how to create CSV map file and upload it.

Final words

That's it. Migration was relatively straightforward with few problems here and there. My blog is now a Jekyll generated static site hosted on GitHub Pages.

GitHub repository for my blog is available here.

ECMAScript 2015 (ES6) Presentation

Sun, 08 Mar 2015 00:00:00 GMT

Ten days ago, I held a talk "ECMAScript 2015 (ES6)" on our local user group meeting. Slides on English and Serbian language, with examples, can be found here: http://miroslavpopovic.github.io/ecmascript6/.

Thanks to all who attended.

MS Community 2014 Presentation

Fri, 19 Sep 2014 00:00:00 GMT

I held a talk "Building modern web in Microsoft world" on this year's Microsoft Community conference. Thanks for everyone who attended. The conference was great as always. Damir and Enis did a great job organizing it.

You can find the presentation and a sample on my BitBucket account. Thanks!

Time to learn AngularJS

Tue, 22 Apr 2014 00:00:00 GMT

A week ago, Rob Eisenberg announced that the future version of Durandal will be called AngularJS 2.0. What seemed to be a late April 1. joke proved to be true. Rob joined AngularJS core team as a full-time external contractor and they are already on the way, building the web's most advanced framework.

This was a mind blowing news, at least for me. A little over a year ago, I chose Durandal to be my front-end framework of choice. Usually, I lean toward the most used framework / library, and Angular was (and still is) on the fire. Having widespread adoption and a huge community, Angular looked like a clear winner.

However, there was Durandal, a small framework built by one of the most inspiring developers. It used Knockout library for data binding and just built an MV* framework around it. Since I was a long time Knockout user, Durandal was so natural and easy to start with.

As always, Rob (and other contributors) did an excellent job. I've always admired him, ever since I tried old Caliburn MVVM framework for WPF. He bought me completely with an inspiring talk on building your own MVVM framework which later become Caliburn.Micro, a framework without which I cannot think of doing any XAML based app.

The amount of code you don't need to write when using Caliburn.Micro in your XAML apps is simply astonishing. Convention over configuration at it's best. Bindings everywhere. No need for all those ceremonial code, like IDelegateCommand etc. that other MVVM frameworks have. Just write your plain and simple .NET code. Heck, it even had coroutines since day 1, which are basically async/await pattern, way before Microsoft brought it to .NET framework. Amazing.

The same concepts are implemented in Durandal. Again, convention over configuration rules. There is a little to none infrastructure code you need to write in your view models / controllers. Just write simple JavaScript modules and let Durandal handle the rest.

I used Durandal with success on a private project and also on several client projects at work, so I can consider myself as an intermediate user. Now I'll try to deep dive into current version of Angular, to gain a perspective on what to expect in Angular 2.0. It might be better to wait for 2.0 and start learning then, since there will be considerable changes, but I'm a sucker for learning. Besides, I would like to compare the philosophies behind both frameworks before that.

Now if I could only think of some small project to play around with...

An advanced guide to HTML and CSS

Sun, 19 Jan 2014 00:00:00 GMT

Lately, I'm catching up with my reading list - have a bunch of links bookmarked over the last year or so. Found a little gem today that I would like to share...

Shay Howe put together a fantastic guide on HTML and CSS called An Advanced Guide to HTML & CSS. Even seasoned front-end developers can learn a thing or two from it. Highly recommended!

Oh yeah, and there's also A Beginner's Guide to HTML & CSS.

Rise of the SilverReader

Fri, 28 Jun 2013 00:00:00 GMT

Yes, you read that right. Rise of the SilverReader, not Rise of the Silver Surfer.

Right after the news that shocked the world (at least our world) my friend Radenko Zec suggested that we build an alternative to Google Reader. So, few months ago, together with another friend of ours Igor Markovic, we started working on it and apparently, we weren’t alone.

And now, just few days before our beloved Google Reader shuts down, we have published our first live beta version!

You can read the official announcement on SilverReader blog. Also, Radenko has made a blog post explaining a technical side of the story.

Try the SilverReader now. If you need any help, or want to submit an idea or issue, visit SilverReader Knowledge Base.

Enjoy!

MS NetWork 2013 Presentation and Samples

Fri, 05 Apr 2013 00:00:00 GMT

Microsoft NetWork 2013 conference was great. It's the biggest IT conference in Bosnia and Herzegovina, held in Teslić this year. I had a chance to meet some pretty cool people. Thanks to organizers for making an excellent event.

My friend Radenko Zec and I held a talk there - "Easy Transition to HTML5 using MVVM". Thanks to everyone who attended. We didn't expect the full room. Hopefully, the talk wasn't too boring. For anyone interested, the presentation and sample code can be found on GitHub: https://github.com/miroslavpopovic/easy-transition-sample. The presentation is in local language, but the samples are in English.

We had an interesting question about organizing JavaScript view models when using Knockout. We suggested Durandal as an excellent new framework for that. For alternatives, take a look at the great TutsPlus article, posted few days ago: Building Large, Maintainable, and Testable Knockout.js Applications.

jQuery UI Autocomplete - Filter words starting with term

Sat, 23 Jun 2012 00:00:00 GMT

I had an interested problem with jQuery UI Autocomplete yesterday. The client required that the search / filtering should be done from the beginning of the word only. By default, jQuery UI Autocomplete filters through the list matching the term in the middle of the word.

There are solutions with using function as an Autocomplete source. It would be OK if we weren't using jqAuto Knockout binding by RP Niemeyer which already takes over the Autocomplete source option.

The solution was pretty easy though. After searching thru jQuery UI's source, I found the filter method used just for that. All that needs to be done is replacing that function with this:

// Overrides the default autocomplete filter function to
// search only from the beginning of the string
$.ui.autocomplete.filter = function (array, term) {
  var matcher = new RegExp("^" + $.ui.autocomplete.escapeRegex(term), "i");
  return $.grep(array, function (value) {
    return matcher.test(value.label || value.value || value);
  });
};

This is actually the copy of the default jQuery UI's filter method with a single change. Regex is prefixed with "^" sign which matches the beginning of the string.

Please note that this is a global change. It will affect all autocomplete boxes on your page.

Here's a fiddle for that, if you want to play around (just try commenting / uncommenting the filter method):

Using FluentMigrator with MSBuild

Tue, 12 Jun 2012 00:00:00 GMT

I have been playing with FluentMigrator lately, trying to implement the features I had with my old, SQL script based tool.

My plan was to write a blog post about integrating FluentMigrator with MSBuild, but the size kind of went out of hand. Instead of splitting it to multiple blog posts, I decided to write a CodeProject article instead.

Here's the link if you are interested: http://www.codeproject.com/Articles/402430/Using-FluentMigrator-with-MSBuild

Resurrection

Sun, 10 Jun 2012 00:00:00 GMT

A lot of things have happen last two-three years for me. I did some experiments (business ones, not with drugs :) ), that proved unsuccessful. During this period I neglected some important and other not so important things. Now I'm trying to get back and reset.

One of neglected things is blogging. So, in my reset mode, I have decided to abandon Blogger and start fresh on a new platform - FunnelWeb. Currently, a default FunnelWeb theme is used. I plan to tweak it up a little when I get time and/or inspiration.

Old blog posts aren't imported. If you are interested in some of my older ramblings, go to codemind.blogspot.com. This new blog also has a new feed, so please update your feed readers: http://feeds.feedburner.com/miroslavpopovic/blog.

Enough of gibberish. What's going on now?

Lately, I'm doing a lot of web development, improving my JavaScript skills and trying to follow a large community behind HTML5. While doing that, I have collected a bunch of links to various web development resources. I got tired of having all those as browser shortcuts, so in an effort to organize it a bit, Web Resources page was made. Hopefully, you'll find something useful there. I'm planing to maintain that list in a future. You can also fork it on GitHub, if you want to base your own list on it.

Also, expect a link to my new CodeProject article.

See you soon (hopefully).

Miroslav Popovic

ASP.NET Core 3.0 Workshop

Workshop content

Introduction

Live workshop

2018 in review

Seavus

Conferences and other community events

BLbit user group

Plans for 2019

ASP.NET Core Identity and Aurelia

Creating a new ASP.NET Core project with Aurelia and Identity enabled

Bonus: Authorizing API calls from Aurelia app with JWT tokens

Summary

Using Elasticsearch with ASP.NET Core and Docker

Elasticsearch installation

Sample project creation

Configuring Elasticsearch client

Indexing blog posts

Implementing search operation

Summary

Conference Bonanza

Microsoft NetWork 8, Neum

Microsoft WinDays 18, Poreč

Weblica 2018, Čakovec

Honorable mentions

Tarabica 2018, Belgrade

Seavus conference, Skopje

Upcoming HTTP API related changes in ASP.NET Core 2.1

HTTPS by default

Better Swagger / OpenAPI specification support

[ApiController] attribute

Automatic model state validation

Inferring defaults on action method parameters

Other

Sample

Conclusion

From Jekyll to Wyam

Back to .NET

Phase 1 - Installing and initializing Wyam

Phase 2 - Moving assets

Phase 3 - Migrating posts

Phase 4 - Tuning up the theme

Phase 5 - Deployment

Finally

Speaking Engagements

Switching to Jekyll

Installing Jekyll on Windows

Creating user repository

Domain redirection

Final words

ECMAScript 2015 (ES6) Presentation

MS Community 2014 Presentation

Time to learn AngularJS

An advanced guide to HTML and CSS

Rise of the SilverReader

MS NetWork 2013 Presentation and Samples

jQuery UI Autocomplete - Filter words starting with term

Using FluentMigrator with MSBuild

Resurrection

`[ApiController]` attribute