Motivation​

Suppose you work on ASP.NET Core web application that solves some business-related tasks. You know, a few forms where users enter their data and get some reports. Although such a project may not require any complex logic on the client, you still probably need to write some JavaScript code to make user interaction with your application more convenient and enjoyable. For example, you may need a simple prompt popup on item deletion since it's not quite right to use a separate page for that. Or, you want to do client-side validation. Or ... it really can be any other client-side task, you name it.

Of course, you can add a few lines of script on each page (with vanilla JavaScript or using the good old JQuery) but it is really hard to maintain all these small pieces when your project gets bigger. Moreover, some of these pieces do the same things, so you either need to replicate them in many places (bad decision) or you end up creating a small library that contains all client-side functions, structures, and classes used in your project.

This article describes how to create such a JS library for your ASP.NET Core project with minimal effort and in a way that will provide better support for further changes.

Solution​

Long story short, we are going to put all our client-side code to separate files (with classes, functions, data structures) and then bundle them with the help of WebPack 5. The resulting script can be included right into your _Layout.cshtml (so, it will be available on all pages of your web app) or you can include it only on the pages where it's necessary.

Moreover, we will use TypeScript instead of pure JavaScript because, you know, static typing is good and it allows us to catch a lot of errors at compile time.

In addition, you can consider this article as a quick introduction to client-side development. Especially if you are a .NET developer who still tends to stay backend-only and who is afraid of all that fancy client-side stuff (as I was some time ago).

Getting started​

Here we will describe the steps necessary to set up the configuration for bundling a small TypeScript library with your own code. For the sake of simplification, this library will contain just one function for now.

0. Install Node.JS​

I'm pretty much sure you already have it installed. In case you don't - please do it. We will need Node.JS version 10.13.0 (or newer) on your dev/build machine.

1. ClientScript sub-folder​

We will put all our scripts and configuration files into a separate sub-folder ClientScript of your main project's folder. It's similar to ClientApp sub-folder used in most of the SPA (single page application) templates available for ASP.NET Core.

2. Add configuration files​

We will need 3 configuration files:

• package.json - to define our bundle and all dependencies,
• webpack.config.js - for WebPack configuration
• tsconfig.json - for TypeScript settings.

For now, you can just copy these files as-is. We will describe each of them later.

{
  "name": "myapp-client-bundle",
  "version": "1.0.0",
  "description": "This is client-side scripts bundle for MyApp",
  "private": true,
  "scripts": {
    "build": "webpack --mode=development",
    "build:prod": "webpack --mode=production"
  },
  "devDependencies": {
    "ts-loader": "^9.2.5",
    "typescript": "^4.4.3",
    "webpack": "^5.52.1",
    "webpack-cli": "^4.8.0"
  },
  "dependencies": {
  }
}

const path = require('path');

module.exports = {
  entry: './src/index.ts',
  module: {
    rules: [
      {
        test: /\.tsx?$/,
        use: 'ts-loader',
        exclude: /node_modules/,
      },
    ],
  },
  resolve: {
    extensions: ['.tsx', '.ts', '.js'],
  },
  output: {
    library: {
      name: 'MYAPP',
      type: 'var'
    },
    filename: 'app-client.js',
    path: path.resolve(__dirname, '../wwwroot/js'),
  }
};

{
  "compilerOptions": {
    "outDir": "./dist/",
    "noImplicitAny": true,
    "module": "es6",
    "target": "es5",
    "allowJs": true,
    "moduleResolution": "node"
  }
}

3. Add TypeScript files​

For the sake of simplicity, our library in this initial stage will contain only one function hello() that simply prints Hello world to the browser's console. Here are two files we need for that outstanding :) functionality:

hello.ts​

This file contains our function packed into the funcs namespace, so we will be able to call it as MYAPP.funcs.hello()

export namespace funcs {
    export function hello(): void {
        const message = 'Hello world!';
        console.log(message);
    }
}

index.ts​

This is our entry point. This TypeScript file will not contain any functions or classes. It will just define which parts of our code (functions, interfaces, classes, etc) we are going to expose to the outside world. Since we have only one file with "real" functionality our index.ts will as simple as:

export * from './hello';

and it means that we would to "reveal" all public (exported) parts inside our hello.ts

4. Build your library​

That's it. We are ready to build our bundle script. To do so, open your terminal program, move to ClientScript folder and run the following 2 commands:

npm install

and then

npm run build

The first one will install all necessary NPM libraries (the ones which are listed in the dependencies and devDependencies sections of your package.json). You will need to run it before the first build and then only when you add a new dependency (another NPM package) to your package.json.

The second command actually runs WebPack that compiles (or, to be more correct, "transpiles") your TypeScript files to JavaScript, then bundles all JS code into one file app-client.js and puts that file into wwwroot/js folder of your web project as defined in webpack.config.js configuration file.

According to the output/library section of that file, all functions or structures of your new bundle will be accessible via the MYAPP global variable.

5. Attach the final script to your app​

To use our script you just need to include it on your page as any other JS file:

<script src="/js/app-client.min.js"></script>

You can add that line either to the _Layout.cshtml (to make it available on all pages of your web application) or to the view or Razor page where it's necessary.

Now you can call the function(s) from our new JS library:

<script>
MYAPP.funcs.hello();
</script>

Configuring the scope​

One of the great features of using TypeScript and WebPack is organizing your code in modules and then combining those modules into namespaces using WebPack's configuration and TypeScript's namespace structure.

There are several possible options.

1. Use module names and their aliases​

You can put functions and classes in a module and export that module either "as-is" or with an alias.

For example, if we have the following module:

export class Dialog {
    ... 
}

export function showDialog() { 
    ...  
}

and we use this export declaration in our index.ts:

export * from './dialogs';

then our Dialog class and showDialog() function will be available right under MYAPP namespace as MYAPP.Dialog and MYAPP.showDialog().

You can also specify an alias for that dialogs module:

export * as dlg from './dialogs';

Now our class and the function will be accessible as MYAPP.dlg.Dialog and MYAPP.dlg.showDialog() correspondingly.

2. Using namespace clause​

You can also use the namespace clause and then re-export the imported modules, so all functions, variables, and types that belong to the same namespace even in different modules will be merged together.

For example, we have the following two modules:

export namespace ui {
    export class Dialog1 {
        ... 
    }

    export function showDialog1() {
        ...  
    }
}

and

export namespace ui {
  export class Widget1 { ... }

  export function renderWidget1() { ... }
}

w, if we place the following two lines in our index.ts module:

export * from './dialogs';
export * from './widgets';

we will be able to access all those exported functions and classes under the MYAPP.ui namespace. For example: MYAPP.ui.renderWidget1().

Using third-party libraries​

Maybe the most significant advantage of this setup (that may seem a little complicated for just a "hello world" function) is the possibility to use any third-party JS library from hundred of thousands available on NPM repository.

As an example, we slightly modify our hello() function so that it will take a parameter name and will print the phrase Hello, {name} to the console. Before printing, the string stored in the name variable will be capitalized with the help of capitalize() function from the well-known lodash library.

Here are the steps we should take to achieve this goal:

1. Add lodash library to your package.json​

Just open a terminal inside your ClientScript folder and type:

npm install lodash

As the result of this operation, you will see something like the following in the dependencies section of your package.json file:

"dependencies": {
    "lodash": "^4.17.21"
}

(the actual version number can be different).

2. Import lodash functions in your hello.ts file​

Add the following line at the beginning of hello.ts:

import * as _ from 'lodash';

3. Modify hello() function​

Now we can use all lodash library functions using _ global variable (this is the default way of using lodash functions since the times it was not an NPM library). So, our hello function will look the following:

export function hello(name : string): void {
  const message = 'Hello, ' + _.capitalize(name);
  console.log(message);
}

Additionally, we will modify the function call on our page:

<script>
MYAPP.funcs.hello('sergiy');
</script>

When we rebuild our script (npm run build), run the app, and open the main page, we will see the following string in the console panel of our browser:

Hello, Sergiy

Watch mode​

It's unnecessary to run the build command each time you change something in your script or add a new package to your project. Instead, you can use the watch mode once, and WebPack will re-build your project every time something was changed:

npm run watch

Conclusions​

As we can see, using TypeScript with WebPack to build vanilla JS client-side scripts for your ASP.NET Core projects has a lot of benefits:

• Strong-typed TypeScript code with all advantages of the latest JavaScript features: classes, arrow functions, modules, scopes, and promises.
• Better support by code editors (like Visual Studio Code) with syntax highlighting, IntelliSense, etc.
• A possibility to use 3-party libraries with typing definitions.
• More compact and optimized JS 5 code generated by WebPack.
• Hot reload of the changes you make in the code editor.
• Better debugging experience (I'm going to write a separate article about it). It's possible to debug your original TypeScript code instead of minimized JS code available for your web app.

There is one more note. We used WebPack in this article since it's the most popular module bundler for now. However, I believe that we can quickly get the same results with any other bundler like Browserify, Parcel, or Rollup.

Please let me know (via my Twitter account @korzhs or here in the comments) if this article was valuable and informative for you.

Happy coding!

Introduction​

There are many ways to create a web application today. We have a lot of different platforms, frameworks, and libraries: PHP, Python, Java, NodeJS, and a dozen of others.

While ASP.NET (Core) was always a good choice for developing enterprise-level web applications (with many complex web pages, some Web API endpoints, static resources, etc.), it's never been the best choice for creating a small web service with just a few endpoints to handle REST API requests in JSON or plain text formats.

Well, that was true until .NET 5 was released last year. With support for top-level statements and new features in C# language, .NET 5 allows us to create a solid web service in just a few minutes and with a single code file.

Single code file ASP.NET Core web service​

Below you will find an example of a very basic "echo" web service with only one endpoint that just takes the content of a POST request and returns it back in JSON format. Not quite a real-world task of course, but enough for demonstration purposes.

So, to create our single-code-file web service just open your terminal, create an empty folder and type the following command:

dotnet new web

This command will create a simple ASP.NET Core project with two code files: Program.cs and Startup.cs.

Since our purpose is to get only one file, we remove Startup.cs. Yeah, it's that simple.

After that just copy/paste the following piece of code into Program.cs file:

using System.IO;
using System.Net.Mime;

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.AspNetCore.Http;
using Microsoft.Extensions.Hosting;


Host.CreateDefaultBuilder(args)
    .ConfigureWebHostDefaults(webBuilder => webBuilder
        .Configure(app => app.Run(async context => {
            if (context.Request.Path == "/api/echo" && context.Request.Method == "POST") {
                //getting the content of our POST request
                using var reader = new StreamReader(context.Request.Body);
                var content = await reader.ReadToEndAsync();

                //sending it back in the response
                context.Response.ContentType = MediaTypeNames.Text.Plain;
                await context.Response.WriteAsync(content);
            }
            else {
                //Return 404 for any other endpoint
                context.Response.StatusCode = StatusCodes.Status404NotFound;
                await context.Response.WriteAsync($"WRONG ENDPOINT: {context.Request.Path.ToString()}. Use POST request to /api/echo instead");
            }
        })))
    .Build().Run();

Let's take a closer look what happens here.

Top-level statements​

Fist we have a block of using statement. That's usual for any C# file. Nothing special.

After that, we start straight with an instruction. We call CreateDefaultBuilder() method of Host class. If you've had experience with C# before, you may be a little bit confused by this approach. No namespaces, no class definitions. You may even say that this piece of code has the wrong syntax and will not be compiled.

But it will. It's possible to do now with C# 9 and it's called top-level statements.

Creating a host​

As we already mentioned above the only instruction we actually have in our little program is Host.CreateDefaultBuilder() call. It creates a generic host builder with default settings for logging, configuration, and Dependency Injection container.

Setting up the web application​

After that, the ConfigureWebHostDefaults method loads the configuration, set Kestrel as the webserver, enables IIS integrations, and adds some default middlewares.

Finally, we call Configure method to set up the middleware pipeline, or, to define the only middleware that will actually process all requests to our web service (with that app.Run(...) call).

The next piece of code is self-explanatory. If it's a POST request to /api/echo we read the content of the request's body and just write it back to the response stream. Otherwise, we return the 404 code with some error message.

As I mentioned above, this is a very basic example of a microweb service, but I intentionally made it simple to show how everything works in general without going into detail.

Running the app​

To run this simple web service just type in the terminal (while you are in the project's directory):

dotnet run

Here is what you get in response by sending a POST request to /api/echo using Postman utility:

Implementing CRUD operations in your ASP.NET Core application can be a very tedious and time-consuming task. EasyData helps to add all necessary functionality (and even more) in a matter of minutes.

Problem​

One of the first tasks for most business applications is to implement CRUD (Create, Read, Update, Delete) operations for the main entities the app works with.

Every developer faces the following problems as part of solving the task:

• The creation of CRUD pages and forms is very boring and time-consuming. Believe me, I’ve been there a lot of times.

• If you do it manually, it can be very slow and error-prone (missed fields, forgotten validators, etc).

• Of course, you can use the scaffolding tool provided by Visual Studio. However, it’s also not a quick process either, because you need to run that tool for each model class. As a result, you get many .cs and .cshtml files, which you'll have to edit manually if something in the default behavior or appearance doesn't suit your needs. In the event of changes in the model classes, you'll need to update those generated controllers and pages manually or regenerate the code and forms from scratch for each affected model class.

• Moreover, even the built-in scaffolding doesn't provide some important, often essential functions such as paging or search.

Solution: EasyData library​

To solve most (if not all) of those problems we created the EasyData library. The main advantage of EasyData is that it employs a declarative approach.

The whole process can be split into two main steps:

1. You “describe” what data (entities and attributes) you want to work with and how your application should work with that data (types, constraints, relations between entities, etc).

2. Based on this information, the EasyData library establishes an API endpoint for CRUD operations and a vanilla JavaScript-based UI that lets your users perform those operations via the API.

The most wonderful thing here is that when using Entity Framework Core, all you need for the first step (“describing” the data) is your DbContext. Simply “feed” it to the library, and EasyData automatically extracts all the information needed to create the API endpoints and CRUD UI.

Quick demo​

Here's a small introduction video that shows how EasyData works:

Getting Started​

First of all, to test EasyData you can open and run one of the sample projects available in this repository.

Installing EasyData to your project takes the following three simple steps:

1. Install EasyData NuGet packages​

• EasyData.AspNetCore
• EasyData.EntityFrameworkCore.Relational

2. Add EasyData middleware in Startup.Configure​

using EasyData.Services;
.    .    .    .    .

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapEasyData(options => {
            options.UseDbContext<AppDbContext>();
        });

        endpoints.MapRazorPages();
    });

In the middleware options, we also specify the type of DbContext object that will be used as the source of the metadata.

3. Set up a catch-all page for all CRUD operations​

If you're using Razor Pages, add a new page (for example EasyData.chstml). If it’s MVC, you'll need a controller and a view. This page will "catch" all URLs that begin with a certain prefix (/easydata by default but it's configurable). So, we use a special catch-all parameter in the route definition ("/easydata/{**entity}").

We also add EasyData styles and the script file (easydata.min.js), which renders the data-management UI and handles all CRUD operations on the client-side.

@page "/easydata/{**entity}"
@{
    ViewData["Title"] = "EasyData";
}
<link rel="stylesheet" href="https://cdn.korzh.com/ed/1.2.2/easydata.min.css" />

<div id="EasyDataContainer"></div>

@section Scripts {
    <script src="https://cdn.korzh.com/ed/1.2.2/easydata.min.js" type="text/javascript"></script>
    <script>
        window.addEventListener('load', function () {
            new easydata.crud.EasyDataViewDispatcher().run()
        });
    </script>
}

That’s it. Now you can run your web app, open the /easydata URL and enjoy CRUD functionality.

The result will be something like this:

List view screen for one entity:​

"Edit Record" dialog:​

"Lookup" dialog (was opened from "Edit Record"):​

How it works​

Let's briefly go over how all this magic works. As we mentioned before EasyData takes care of three main things:

• It collects database metadata.

• It establishes an API for the main CRUD operations.

• It renders UI (again, based on the metadata) and processes all user interactions in that UI.

Let’s explore all these parts in detail.

Metadata​

Metadata is the data about your data: what entities (tables) are stored in your database, how they're connected, what attributes (fields) they have, what the types of attributes are and what the constraints are with respect to the values we can store in those attributes.

EasyData collects metadata (in one way or another) and stores it in the instance of MetaData class. This object contains the list of entities (tables), the attributes (fields) for each entity, the connections between entities, and some additional information used in API and during UI rendering and processing.

To fill the MetaData object, we specify a metadata loader. In the example above, we did it with the UseDbContext call. So, the metadata is loaded from a DbConext object. Currently (in version 1.2) this is the only metadata loader available. In future versions, it will be possible to load metadata directly from a DbConnection object or perhaps with some other method.

EasyData middleware​

EasyData middleware is responsible for establishing a REST API for all CRUD (and not only) operations initiated by the client side.

To add the middleware to your pipeline use MapEasyData extension function inside UseEndpoints configuration delegate:

   app.UseEndpoints(endpoints =>
    {
       endpoints.MapEasyData(options => {
            options.UseDbContext<AppDbContext>();
        });
    }

This call should be made before MapMvc or MapRazorPages. By default, EasyData middleware is assigned to /api/easydata endpoint, but you can change it via the configuration function (action) passed in the parameter.

The only thing that's required in order to configure for MapEasyData is to tell it where to take the metadata. Currently, there's just one option available: getting metadata from a DbContext. So, that’s why we add UseDbContext<AppDbContext>() call in the example above. Besides getting metadata, UseDbContext also provides our middleware with all the means for performing CRUD operations (via the DbContext object).

EasyData UI root page​

The third part of the EasyData setup process is the page where the CRUD user interface is rendered. It must be a so-called "catch-all" Razor page or MVC view. By default, this page must be opened for any path that starts with the /easydata/ prefix. (So, all paths like /easydata/student or /easydata/invoice must be processed by this page.)

NB: /easydata is the default prefix. You can use another name, but in this case, it will be necessary to specify it in the options of our RootDispatcherView object.

Our catch-all page can contain any HTML element of your choice. However, to ensure the visualization and normal operation of the CRUD UI, it must include the following 4 elements:

• <link> element with a reference to EasyData CSS file (easydata.min.cs)

• Container (empty div element), in which our interface will be displayed. By default, it must have the ID EasyDataContainer, but this can also be configured with options.

• <script> element with a reference to easydata.min.js.

• And a small script that creates and launches the EasyDataViewDispatcher object on page load.

An example of the simplest “catch-all” page you can see in the Getting Started section above.

Wrapping up​

Currently, EasyData can work with .NET Core 3.1 and .NET 5. Obviously, all ASP.NET Core and Entity Framework Core versions that can work with the specified releases of .NET (Core) are supported. However, it won't be a problem to add support for previous versions of .NET Core or even .NET Framework 4.x. If anyone needs it, please submit an issue in EasyData's GitHub repository.

EasyData can be a good tool with which to quickly prototype a new project or create a POC (proof of concept) when we already understand what data we'll need but don't want to spend a lot of time on the simplest operations with that data. However, we hope that in time it will be possible to fully use this solution in the production environment.

So, we look forward to hearing from you with any comments or advice you may have. Of course, don't forget to ad a start for the EasyData repository on GitHub, especially if this library helped you and saved some time.

So, we look forward to hearing from you with any comments or advice you may have. Of course, don't forget to add a star for the EasyData repository on GitHub, especially if this library helped you and saved some time.

This is the second part of the article, where we take apart the default ASP.NET Core solution template piece by piece and try to explain the purpose of each part and how exactly it works. You can consider it as a reference where you can check why a particular part was added to your project and find a link to the relevant documentation that explains it in detail.

Startup class​

As we already mentioned in the first article, the Startup class is the entry point for all initialization codes in your application. Long story short, the Startup defines what your application will do and how exactly it will work.

By default, any Startup class in the ASP.NET Core application includes three main parts:

• The constructor where you can define some internal variables, set up some configuration settings, or perform application-wide initializations. For example, we suggest our users set here their license keys for our EasyQuery library.

• ConfigureServices method. Here we register all necessary services in the DI (dependency injection) container and define the configuration settings for some of them. In case you are not aware of what Dependency Injection is, here is an article on our blog that explains this concept in simple words.

• Configure method. This is the stage when you set up the middleware pipeline for your project.

Both ConfigureServices and Configure methods are called automatically while the application starts. You just need to define the services and the middlewares there correspondingly.

Now, let’s take a look at each of these sections more in detail.

Startup class constructor​

The default ASP.NET Core project template contains only the following one line of code in the constructor:

        public Startup(IConfiguration configuration)
        {
            Configuration = configuration;
        }

It just saves in the class property the configuration object passed here by the DI container, so we can use it in other methods. In the first article, we have already considered the configuration mechanism used in ASP.NET Core applications.

ConfigureServices method​

As it was mentioned before, the ConfigureServices method contains the function calls that register different application services in the DI container. These can be authentication/authorization services, MVC or Razor Pages engine, the classes for working with DB, or any other possible services.

The only parameter of the ConfigureServices method has IServiceCollection type that represents a list of ServiceDescriptor items. Each of those items maps some type (usually an interface) to a particular implementation of this type.

According to the interface, we can use only usual IList or ICollection functions like Add, AddRange, Remove, and other methods. However, as you have already noticed, ConfigureServices contains such calls as services.AddDbContext, services.AddRazorPages, and similar. You may ask, “How is it possible?” The answer is extension methods. Each sub-system used in our project (like Entity Framework Core or MVC engine) defines an extension method (sometimes even a few) for the IServiceCollection interface to simplify the registration in the DI and configuration of the services available in that sub-system.

NB: Please note that the order of the services you register in the ConfigureServices method is not important. This method is executed only once upon your application start.

So, let's take a closer look at the default ConfigureServices’ content.

public void ConfigureServices(IServiceCollection services)
{
    services.AddDbContext<ApplicationDbContext>(options =>
        options.UseSqlServer(
            Configuration.GetConnectionString("DefaultConnection")));
    services.AddDefaultIdentity<IdentityUser>(options => options.SignIn.RequireConfirmedAccount = true)
        .AddEntityFrameworkStores<ApplicationDbContext>();
    services.AddRazorPages();
}

So, there are only three calls there: AddDbContext, AddDefaultIdentity, and AddRazorPages. Let’s inspect each of them separately.

AddDbContext​

This method is provided by the Entity Framework Core framework. It registers and configures our database context. The Actiondelegate passed in the parameter allows us to define the parameters of this DbContext. For example, with UseSqlServer call, we tell our DbContext to use a particular type of connection (SqlConnection) with a particular connection string. The connection string itself is taken from the configuration so it can be easily changed in Development or Production environments. You can find the default connection string in the appsettings.json configuration file, which we already analyzed in the first article.

A few words about the “Builder” pattern​

You may have noticed an interesting way of passing settings for DbContext. Instead of sending an object with options, we use a procedure (Action) with one-parameter options of the DbContextOptionsBuilder type.

That's because, to construct the DbContext settings properly, Entity Framework Core uses the Builder Pattern. This pattern is helpful when you need to perform several steps to construct some complex objects and simply defining a class or structure is not enough. For example, when you need to call some methods depending on the settings in the configuration. As it happens in our case with UseSqlServer().

There is one more reason why we use a delegate (function) instead of a plain object. There may be a situation when you don't need that service (DbContext) at all. For example, your web app has some actions that do not require database access. The DbContext object will never be created for such requests, and so, we will not need to set its options. The good thing about a delegate is that it can be called exactly when you need to construct the necessary object.

I paid so much attention to this pattern because it is used quite often, especially in the process of registering services in DI (and we will use that for the next function call as well).

AddDefaultIdentity​

The second function call in the ConfigureServices was added here because of the Authentication option we turned on when creating our project. It registers a bunch of services for authentication and authorization tasks such as IUserStore, IRoleStore, IPasswordHasher, UserManager, SignInManager, and many others. The are all part of the ASP.NET Core Identity sub-system.

This method also uses the Builder Pattern, but in a slightly different way. Instead of passing the builder in the delegate’s parameter, this function returns an IdentityBuilder object, so you can call other functions with simple chaining.

The only function called there is AddEntityFrameworkStores. It tells ASP.NET Identity where to store all the entities required for auth tasks (users, roles, claims, etc.). As the name of the method suggests, we will use our Entity Framework services for these tasks. The type of parameter in this method (between < .. >) defines the DbContext class used to store all auth objects.

AddRazorPages​

The last function call in the ConfigureServices adds the services necessary for Razor Pages engine. It appears here because of the template we chose at the beginning. If we had selected a template with Model-View-Controller approach at that point, we would have had something like services.AddMvc() here.

Configure method​

The last method in the Startup class defines the middleware pipeline of our ASP.NET Core program. If you don't know what a middleware pipeline is, you might want to learn more about it because it determines how your web application handles HTTP requests.

Unlike the services registered in ConfigureServices (remember, their order is not important), the order of middlewares defined in Configure has crucial significance. As you can see from the picture above, the first defined middleware is called for each request while every next one in the pipeline processes only those requests that were not processed by the middlewares defined before it.

So at the beginning of the pipeline, we need to place the middlewares that are necessary for auxiliary tasks (like logging or authentication) and that don’t consume a lot of memory and processing time.

Let’s take a look at the default implementation of this method for the chosen project template:

        public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
        {
            if (env.IsDevelopment()) {
                app.UseDeveloperExceptionPage();
                app.UseDatabaseErrorPage();
            }
            else {
                app.UseExceptionHandler("/Error");
                app.UseHsts();
            }

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

            app.UseRouting();

            app.UseAuthentication();
            app.UseAuthorization();

            app.UseEndpoints(endpoints => {
                endpoints.MapRazorPages();
            });
        }

So, let’s go through the middlewares defined here one by one.

Exception handling and security transport​

The first lines define different middlewares for Development and Production modes. If we are in the Development mode, we define the middlewares that catch all exceptions in the pipeline and show a special page with extra information about the error (exception message, stack trace, etc.).

It's possible to do because (as you can see from the image above) the processing of the request is returned to the first middleware in the pipeline before being sent back to the client.

In the Production mode, we also catch all exceptions and then re-execute the request with the specified path (‘/Error’ in our case).

The second call executed only in Production is UseHsts. It adds a middleware that implements HTTP Strict Transport Security Protocol.

The next in the pipeline is HTTPS redirection middleware (app.UseHttpsRedirection). The name is self-explanatory. It just redirects all HTTP requests to HTTPS ones. These two middlewares (app.UseHsts and app.UseHttpsRedirection calls) are added because of the Configure for HTTPS option we turned on (actually, it was turned on by default) during the project creation.

Processing static files (UseStaticFiles)​

The next middleware (added by the app.UseStaticFiles() call) takes care of all static files. Simply put, if the application gets a request for some .js, .css, or an image file (.png, .jpg, etc.), this middleware looks for a file with the requested name inside wwwroot folder and returns it in response (if the file was found). If not, it sends back a response with a 404 status code (“not found”).

There are overloads of UseStaticFiles that allow us to define another root folder for static files and set some other options.

Routing (UseRouting and UseEndpoints)​

The next pair of middlewares are, maybe, the most important ones in the pipeline, since they define the routing for all other endpoints in your web app.

In simple words, they match a particular request to a particular endpoint, a piece of executable code that handles the request.

So, how exactly does it work?

In the Configure method, we call app.UseRouting() to add EndpointRoutingMiddleware to our pipeline.

After that, we call app.UseEndpoints() to add EndpointMiddleware to the pipeline and define the endpoints. Each endpoint is an object that contains (as mentioned above) a delegate (so, a piece of code) that actually handles the request, plus some metadata (like an authorization policy).

We can use such extension methods as MapGet, MapPost, and others to add an endpoint that matches a particular request path or a path template. For example, the following pattern /something/{path*}, will be matched for all requests started with /something/.

Additionally, other services can define their own extension functions that are used to create necessary endpoints. For example, you can use the MapRazorPages function for Razor Pages or MapHub for SingleR. In our EasyData library we defined MapEasyData function that adds an endpoint for the API that processes all CRUD operations.

When our web app gets a new request (and it’s not processed by any middleware defined before UseRouting), the EndpointRoutingMiddleware matches it to some endpoint. So, one endpoint among all defined at the application start is becoming selected at that moment.

Then EndpointMiddleware actually calls the endpoint’s delegate to handle the request. Other middlewares that are added after app.UseRouting() but before app.UseEnpoints() can see which endpoint is selected and can change something (e.g., to apply an authorization policy) before EndpointMiddleware dispatches to the selected endpoint.

Authentication/Authorization (UseAuthentication, UseAuthorization)​

These two middlewares are added in the Configure because of the Authentication option we turned on when we created our project. As already mentioned above, they already know which endpoint is selected and so can add some additional identity-related information to the request’s context (like filling its User property) or redirect to the “sign-in/sign up” pages if the current request is anonymous but the selected endpoint requires authorization.

Wrapping Up​

So, in this article, I tried to cover all pieces of one of the most-used ASP.NET Core application templates and figure out why they are used and how they work (from a very general point of view).

I hope this information will help you better understand the internal mechanism of the ASP.NET Core framework and make your code more clear and efficient.

Thanks for the reading, and take care!

Introduction​

When you start learning a programming language, one of your first exercises will probably be to write a “Hello World” application to figure out the basic concepts. This exercise works well if you’re writing a simple console program that will only print out the greetings on the screen.

However, once you move onto learning to write web apps using a new framework, such as ASP.NET Core, such a simple code is not enough — partially because web apps are more complex. And also because, right off the bat, the tools and frameworks used for writing web apps try to introduce advanced techniques and approaches for building and maintaining them once they scale.

It all can seem like too much for a beginner. Here we will take apart the default ASP.NET Core solution template piece by piece, then figure out the purpose of each piece and how exactly it works.

Please note that this isn’t a full-scale tutorial on all the aspects of creating web apps in ASP.NET Core. Rather, it is a short guide where you can check why a particular part is added to your project or find a piece of code and a link to the relevant documentation that explains it in detail.

As an example, I used a new solution that targets .NET 5. However, most of this article's information will also be relevant for the ASP.NET Core projects that target .NET Core 3.1 or the upcoming .NET 6.

Creating a New Web Project​

Let’s start with creating a new empty web app with the “Create a new project” wizard in Visual Studio.

Here is how this step should look:

When you press Next, the wizard will ask you to choose the names of the new solution and project and the folder to place the solution files in:

Tip #1: Place the project and the solution into separate folders. Choosing the same location for both is convenient only for very small applications. Once you start adding other layers to your solution (domain classes, data layers, API, etc.), having them in separate projects will be more practical.

Tip #2: Use the general name of your application for the name of the solution (like “MyCoolApp”) and add the “.Web” suffix for the project name (e.g., “MyCoolApp.Web”).

Project Structure​

After finishing the steps described above, you will get a new solution with one project inside it.

The structure of that project will look similar (or even the same) to the following one:

Let’s take a closer look at each part of your new project.

1. Connected Services​

This is the first node in your project’s structure and possibly the less-used one. It is intended to automate the multiple steps necessary to connect a project to an external service (like Azure Storage or Application Insights). You can right-click on this node and select “Add connected service…” to run a wizard that will lead you through the process. Usually, it just adds necessary packages and gives you basic instructions on how to start using your app's service. As I’ve already mentioned, there is a good chance you will not use this node during your project’s lifetime.

2. Dependencies​

This element of your project structure contains all packets or other projects on which your project depends.

There are four main folders inside this node:

• Analyzers
  They help you make your code better: cleaner, error-free. Each analyzer checks that your code satisfies a list of rules incorporated in it. If any part of your code does not apply to one of the rules, you will see either a Warning or an Error while you build your project.

Please note that analyzers work only at compile time and do not affect your resulting application.

• Frameworks
  This folder contains a list of frameworks your project depends on. This information is important if you publish your web app as a runtime-dependent (as opposed to a self-contained one). In this case, all the frameworks listed here must be installed on the server where you will run your app.

NB: You can use dotnet --info console command to check the list of installed frameworks.*

• Packages
  This is the main item in this node. It lists all NuGet packages you added (installed) to your project. If any of those packages depend on other packages, they will be installed automatically and listed as sub-nodes of the root-level packages. You can remove each installed package here (right-click / Remove).

• Projects
  This is the list of other projects in this solution your current project depends on. You can reference other projects using the “Add reference” command from the right-click menu. Obviously, this node is empty now since we have only one project in the solution.

3. Properties​

This part contains different properties of your project that you can modify by double-clicking on this node in the Solution Explorer. Most of the properties there affect the compile- and debug-time behavior of your project.

The only item inside this node is a “launchSettings.json” file containing the launch profiles. Each profile defines how to run your project when you click on the “Run” button in Visual Studio.

4. wwwroot​

This folder contains all the static files of your web application: CSS files, JavaScript files, images, and icons. As you might figure out from its name, this will be the root folder of your web app. So if you put an “image1.png” file into the “wwwroot/images/dir1” folder, it will be accessible in the browser by the “/images/dir/image1.png” address.

5. Areas​

This folder is added because we selected the “Individual Accounts” value for the “Authentication Type” option when created the project.

In addition to the core authentication/authorization packages (which is called ASP.NET Core Identity), the default template also adds the “Microsoft.AspNetCore.Identity.UI” package. This is a Razor-class library that contains all forms and partial views for authentication and user management: Login, Registration, Reset Password, User Profile, and many others. All these forms will use your layout (defined in Pages/Shared/_Layout.cshtml) and so will match your website’s design.

However, you still might want to change some of those forms (or even all of them). In this case, you can use the Scaffold command and add the necessary files to your project. The scaffolded files will be added to the Areas/Identity folder.

6. Data​

As in the previous case, this folder appears in our new project because of the “Authentication Type” option that was turned on at the beginning.

By default, all user-related information (users, their roles, claims, etc.) is stored in a database accessed with Entity Framework Core ORM (object-relational mapping) framework. If you are not familiar with EF Core, you can find a lot of tutorials on Microsoft Docs.

The “Data” folder contains your DB context class named “ApplicationDbContext.” This class is derived from the “IdentityDbContext” class defined in the “Microsoft.AspNetCore.Identity.EntityFrameworkCore” assembly, and it includes all DB sets (tables) necessary to store user-related information.

You can use this class or create another DbContext class to add your models.

Additionally, the “Data” folder also includes “Migrations” sub-folder with all your Entity Framework Core migrations.

7. Pages​

This folder contains all pages (forms) of your web applications. ASP.NET Core has two default approaches for content rendering: MVC (Model View Controller) and Razor Pages (which is, actually, a kind of MVC, where each controller and the corresponding view are stored together). Both approaches use Razor syntax that you can think of as HTML + C#.

Each Razor page is represented by a “.cshtml” file. The code related to it is stored in a so-called “code-behind” file with the same name and a “.cshtml.cs” extension.

From the start, the “Pages” folder contains a few default pages, such as Index (the home page of your web app), Privacy, and Error. Additionally, you can find the main layout file (_Layout.cshtml) and some partial views in the “Pages/Shared” folder.

NB: It’s a common practice to prefix the names of the layouts and partial views with _ symbol.

8. Root Folder Files​

Now, when we’ve looked over all the main folders created with the default ASP.NET Core application template, let’s take a closer look at the files stored in the project’s root folder. They are the most important part of the project.

Program.cs​

This file defines the “Program” class with one static method, “Main,” which is the entry point of your web application.

The only purpose of this method is to define the host and then pass the control to the Startup class. For more information about the default host builder, look at an article about Generic Host on Microsoft’s Docs.

application.settings​

This is a JSON file that stores the application’s settings. The settings have a hierarchical structure and can be accessed with the Configuration object defined in the Startup class or in any other place of your program where you injected IConfiguration service. For example:

var defaultLogLevel = Configuration.GetValue<string>("Logging:LogLevel:Default");

The different levels of hierarchy are separated by the colon (:) symbol.

By default, in addition to “application.settings”, the ASP.NET Core template also includes an “application.Development.settings” file. The settings defined in this file are loaded only into the Development environment and are not available in production. To learn more about the “.settings” files and configuration in ASP.NET Core projects in general, please read this article on Microsoft’s Docs.

Startup.cs​

This is the final part of the ASP.NET Core project’s structure. The “Startup” class serves three main purposes:

• It performs all initialization tasks (setting application-wide constants, DB seeding, migrations, etc.).

• It registers all services used in this project in the DI (dependency injection) container.

• It defines the middleware pipeline of your web-application.

This class contains a lot of code (as for a project that has just been created) from the beginning and will become even bigger when you start adding new features to your application.

We will take a look at it in more detail in the next article.

Choosing a framework is not easy when you start reflecting on your future as a software developer, especially if you are a newbie. Mastering any programming language takes long hours and an effort you don’t want to waste. And it’s stressful to think that the wrong option might lead you to a job where you will have to change your knowledge base again.

Ok, let’s switch to the positive side. Since you are here, your options are narrowed down to these two: Java or .NET. That’s already a huge move forward. Both options are already a kind of win. Java and .NET are both well-established and are used for enterprise-level development. That means you might land a job at a huge company with lots of resources and opportunities.

Let’s take a quick look at the job market. As of April 2020, Monster.com lists more than 41k jobs for “Java Developer” and 8.5k for “.NET Developer.” According to Glassdoor, the average salary estimation for a Java developer (irrespective of level and location) is about USD 79k and USD 76.5k for an ASP.NET/C# developer.

Don’t be too fast with the conclusions though. Next, you might want to know which of the two is better for you personally and is more relevant to the future of technologies. Let’s have a closer look at both options.

Old-school Java​

At the moment, Java is one of the most popular technologies worldwide. It often ranks first in various ratings, and this is probably the main reason developers stick to it. The technology was created in 1995.

It is relatively easy to learn, and there are many free training resources available. In addition, there is an enormous community that can help a newbie through the learning process. Java is suitable for almost every type of project: web applications, mobile apps, cloud computing, etc.

Java is a free technology, as is the Oracle JDK (Java Development Kit), or Oracle OpenJDK, that’s used to create software in Java. It also makes it possible to work with other programming languages, such as Kotlin, Groovy, or Scala, which would be relatively easy to learn as an addition. And as we have just pointed out, the job market is full of offers for Java developers from all over the planet. Sound good?

But hold on — there is a slippery slope under any ideal image. Some downsides include:

Licesing mess​

Maybe you think that you will start your way in Java by writing a small "Hello World" program, right? Wrong. Today, before you actually can learn Java itself, you first need to understand licensing on this platform. Otherwise, you may appear in a situation when you at first have to pay Oracle a couple of thousands of dollars for the licensing before delivering your work to the customer. Therefore, first, carefully study what Oracle JDK is and how it differs from Oracle Open JDK. And how they both differ from the community-led AdoptOpenJDK. What is Binary Code License and how much rights you have with GPLv2+CPE license. Several official FAQs seem to explain the situation with licensing (one on Oracle’s site and another one on Java.com) but make it even more confusing. In addition, you can easily find a bunch of blog posts, queries on Quora (like "Is Java still free"), and even videos on this topic.

The question is: do you really want to deal with all this?

Legacy code​

Many long-standing companies have something written in Java. Eventually, a young and passionate Java learner might end up on a job where they are working with an obsolete code instead of some new and prominent technology. For example, a library a company has been accumulating for 20 odd years might be too expensive and time-consuming to modernize.

High competition​

In addition to the huge number of vacancies, there’s an even bigger number of candidates. That’s because virtually everyone who studies all the ratings sees Java in the top positions — and here we go! Another thousand newbie learners opt for Java.

A More Promising Option: the .NET Framework​

There is another very popular free open-source developer platform that can serve you better — .NET. Here is why it may be more promising for you.

Source: https://devblogs.microsoft.com/dotnet/introducing-net-5/

1. Free, open, and cross-platform​

Interestingly enough, about five to six years ago all the features mentioned in the previous section would have made Java a better option, as .NET was then fully controlled by Microsoft and ran only on Windows.

This situation has completely changed in the last few years.

The tables have turned, and now Java is becoming more closed off under Oracle guidance, while the approach of Microsoft is quite the opposite. .NET now is an open-source platform with no licensing costs. They claim freedom for developers as one of the platform’s core values. For the time being, Microsoft seems to practice what they preach.

The latest version of the .NET platform — .NET Core — is compatible with all the major operating systems: Windows, Linux, and iOS. There are basic .NET tools open for immediate use and lots of add-ons for building and editing apps, as well as third-party tools. Multiple libraries built specifically for .NET make the development process even more comfortable.

2. All application types​

The .NET framework (and its Core edition in particular) allow you to develop almost any kind of application, be it an enterprise-level web app, desktop or mobile software, gaming project, or even an IoT service or an AI solution.

With the advent of the WebAssembly technology and Blazor framework, .NET can be used even for building client-side applications running in a browser — web apps where both client and server-side code is written in C#, thus eliminating the need to use JavaScript.

Source: https://dotnet.microsoft.com/learn/dotnet/what-is-dotnet

3. Quick progress and regular updates​

The .NET framework has been constantly evolving throughout its 20-year history. But in the last four to five years, the pace of its progress has increased significantly.

Since the initial release of .NET Core back in 2016, we have received a major update almost once per year.

In November 2020 Microsoft plans to release another big update to the platform — .NET 5. It is supposed to take the best of the previous versions and become a united platform for all the development tasks. Moreover, at its annual conference in 2019 Microsoft introduced a roadmap for the .NET platform that gives a clear understanding of what to expect and when.

Source: https://devblogs.microsoft.com/dotnet/introducing-net-5/

4. Great performance​

For years, the applications created either with Java or on .NET/C# had a similar level of performance. However, Microsoft and many third-party contributers have made some significant investments in the optimization of this aspect and continues to improve. For example, the ASP.NET Core web framework allows you to serve 7 million requests per second on a single server. And according to TechEmpower tests, ASP.NET Core is way ahead of any Java web framework.

Here's another good demonstration of the performance that can be achieved on the .NET platform — an example of a super-fast network driver written in different languages. The driver written in C# shows almost the same level of performance as C and Rust, slightly better than the Go language, and way ahead of all other high-level languages, including Java.

5. C# — modern and versatile​

.NET was initially designed to support many programming languages. The most widely employed among them are C# (pronounced “see sharp”) and F# (which offers a more functional approach).

The most popular and loved is definitely C# — a general-purpose and object-oriented programming language. It is easy to learn and is widely used for all kinds of software development, from enterprise-level solutions to low-level IoT and gaming projects. It makes simple many features that are overly complicated in Java.

Despite its long history, C# keeps up with the times. A lot of features, such as LINQ queries, lambda expressions, asynchronous operations with async/await, and others were introduced in C# way ahead of other programming languages. Java still doesn’t have many features that were available in C# for years.

.NET Limitations​

Just like we said about Java, there is always a downside to any ideal picture. With .NET, it is still not good enough for the client-side development. JavaScript is still considered the best option. The same goes for the ML (Machine Learning) and NLP (Natural Language Processing) applications. Here Python is number one.

Wrap Up​

The choice between Java and .NET is one between two solid enterprise-level development options. Though Java now ranks number one in all the ratings, it is highly competitive in terms of the job market and slow in terms of relevant updates.

The other option — .NET — is an open-source object-oriented solution that can be used for developing all sorts of applications, and it has a clear roadmap for the future. In 2020 there will emerge .NET 5, an update that will unite all the best features of the previous .NET versions. This makes learning a well-structured, easy, and modern technology even more attractive.

Useful links:​

• Looking for a job as a .NET developer?
  Use Jooble to post your CV and start getting job offers.

• Need to implement CRUD (create, read, update, delete) operations in your ASP.NET Core project and don't know where to start?
  EasyData open-source library to the rescue! With EasyData you can get full CRUD functionality in just 10 minutes and with just a few lines of code.

• What to improve the user experience of your DB-related .NET application?
  EasyQuery framework can help you to implement custom search, data-filtering, reporting, data exporting (to CSV, Excel, PDF), and many other tasks that commonly arise in data management solutions.

The concept of Dependency Injection can look over complicated especially for beginners. Here, I have tried to explain it by using a very simple example from the real world: a food delivery app on your mobile phone.

So, imagine you open such an app on your smartphone. Let’s see what we have here:

Menu (interfaces)​

Photo by Levi Elizaga on Unsplash

Obviously, this app has a menu with a description of each item available there. To make it more similar to the Dependency Injection (DI) container let’s suppose all items on the menu are more or less generic. So, you have such options as a burger, chips, green salad, a soda drink, coffee, etc. However, you don’t know what meat is used for that burger, how exactly those chips are cooked, and what is the exact soda drink you will get. These menu items are your interfaces. They describe the main characteristics of each snack but don’t bother you with the exact implementation.

Actual snacks (implementations)​

Then, you have the actual snacks which are delivered to you when you place an order. These are the implementations of your interfaces. Obviously, the implementations can differ depending on which particular restaurant they are delivered from.

Delivery (injection)​

Now, let’s suppose that your app, in some magical way, has a zero-time delivery function (OK, almost zero-time). So, at whatever place you are now (whatever part of your project), you select the items you need, press the “Order” button, and the chosen snacks instantly appear in your hands. We can say that they are injected to the place where you are now :) Moreover, if a snack (like breakfast or combo-meal) depends on other snacks, those dependant snacks are created automatically and also “injected” into your combo-meal. For example, a Big Mac Combo Meal includes a BigMac burger, some fries, and a drink. You don’t need to order them separately. They will all be created and delivered to you automatically.

Providers​

Now let’s suppose you can choose which restaurant will deliver your snacks. You can choose either it will be a McDonald’s or Burger King or your favorite cafe nearby.

Moreover, you can also choose the type of food (with meat, fish only, vegetarian, kosher, etc). So, now you can still order a burger but if you selected “vegetarian”, our magical app will deliver to you a burger with soy meat or a burger made from that cultured meat popular nowadays.

The main point here is this: with this app, you can easily change the actual provider (so, the implementation) of your snacks without changing the simplicity and convenience of the whole process.

Wrapping up​

Your food delivery app here is a Dependency Injection (DI) Container. The menu items are interfaces of the services you might need somewhere in your project. The actual snacks are the implementations (actual classes that implement those services). When you need your some snacks (services) you tell your app (DI container) what you need and they are delivered (injected in the place you are now) to you immediately.

You may ask, why DI does matter? What is so special about this concept that has made it so popular?

As you can see from this real-word example, dependency injection has a lot of benefits. Let’s list the most important ones (again, with a real-world example for each of them):

1. Simplicity
   With DI, you don’t need to write a lot of code just to create an object of a particular class. Especially when this object requires several other objects for its work (like a combo-meal in our example). You just “tell” your DI container (your food delivery app) what you need and it’s delivered to you right away.

2. Maintainability
   n terms of code, your classes become loosely coupled (each of the classes is less dependent on the concrete implementations of other classes), so your code will be easier to maintain. In terms of our food delivery app, it’s easier to maintain one app and order (inject) necessary snacks, instead of thinking where to buy all the ingredients for each of them and then cook everything yourself.

3. Flexibility
   With DI, your code becomes loosely coupled and so, more flexible, since you depend on interfaces and it’s very easy to replace the implementation. For example, you have a repository interface for storing data about users. The initial implementation of this repository will save the data to files. After that, you can decide to use the database. The implementation of the repository is changed but all the code that uses it remains the same.
   It’s similar to how you switch the provider of the snacks (or the preferred type of food) in your app. The process of order and delivery remains the same, you just start getting other snacks.

Conclusions​

As you can see, Dependency Injection is a very useful and convenient technique, the main principles of which can be applied not only in coding but in some real-world situations. In terms of programming, you get more maintainable, more readable, more flexible, and more extensible code. These are good enough reasons to get better acquainted with this technology and start using it in your projects.

Introduction​

This is a second edition of the previous post on the same topic. The reason why I wrote this one is because of some drastic changes made in ASP.NET Core Authentication system from version 2.0 to version 2.2 - so most of the code presented in the first article doesn't work with the new version.

So, the code in the following articles was built for and tested with ASP.NET Core 2.2. The main concept, however, is still the same and were not changed since ASP.NET Identity 2.0 (I guess).

As in the previous case, we will start with a description of the problem.

Problem​

Let's suppose we created a new ASP.NET Core project using one of the default templates and chose "Individual user account" option for "Authentication".

Now when we start that newly created project and register new user we will see something like Hello YourEmailAddress@YourCompany.com in the top right part of the index web-page.

Obviously, such kind of greeting is useless in a real-world application and you would like to see the name of the currently logged user there instead (e.g. Hello John Doe).
Let's figure out how to do it.

Solution​

Here we guess you are already familiar with the claims and claims-based approach for authorization used in ASP.NET Core Identity. If not - please read ASP.NET Core Security article first.

To achieve our goal we need to do 2 things:

1. Add necessary information to the list of the claims attached to the user's identity.
2. Have a simple way of getting that info when needed.

But before implementing these two tasks we will need to add a new ContactName field to our model class and update our registration and user management pages accordingly.

Step 0: Preparations​

Before we can add a new claim to a user object (the one you can access via HttpContext.User) we need a place to store that additional info somewhere. Here I am going to describe how to get this done for a new ASP.NET Core project built by a default template.

If already you work with your real-world application - you most probably already did similar changes before. In this case, you can skip this section and move right to the step #1.

0.1 New ApplicationUser class​

Add a new ApplicationUser class with `ContactName' property:

    public class ApplicationUser : IdentityUser
    {
        public string ContactName { get; set; }
    }

Of course, you can add more properties to store some additional information with the user account. For example: FirstName, LastName, Country, Address, etc. All of them can be placed to claims the same way as ContactName we discuss here.

0.2 Replace IdentityUser with ApplicationUser​

Now you need to replace IdentityUser with ApplicationUser everywhere in your project.

The default ASP.NET Core template uses predefined IdentityUser type everywhere. Since we what to use ApplicationUser instead of it - we need to search for all inclusions of IdentityUser in your project and replace with ApplicationUser.

It will include your DbContext class, one line in Startup class (in ConfigureServices method) and two lines with @inject directives in _LoginPartial.cshtml view.

Here is how your new ApplicationDbContext class will look like after that:

public class ApplicationDbContext : IdentityDbContext<ApplicationUser, IdentityRole, string>
{
    public ApplicationDbContext(DbContextOptions<ApplicationDbContext> options)
        : base(options)
    {
    }
}

0.3. Update your database.​

Now you need to add a new migration and then update your DB. Just run the following 2 commands from your project's folder:

dotnet ef migrations add AddUserContactName

dotnet ef database update

0.4. Update "User Profile" page​

Finally, we will need to add our new field to the "User Profile" page to make it possible for users to modify it.

The default ASP.NET Core template uses all identity-related pages directly from a special Razor UI library (Microsoft.AspNetCore.Identity.UI). The good news is: we can override any of those pages if we want. Here are the steps we need to do:

1. Right-click on your project in VS and select Add | New Scaffolding item.

2. In the "Add Scaffold" dialog select Identity on the left side tree and then Identity in the main list and click "Add".

3. In the dialog that appears select only Account\Manage\Index page and then click on "Add" as well. When the process is finished you will find a new page 'Index.cshtml' in Areas/Identity/Pages folder.

4. After that make the following changes to that Index page:

In the Index.cshtml itself add the following piece of markup right before update-profile-button button.

<div class="form-group">
    <label asp-for="Input.ContactName"></label>
    <input asp-for="Input.ContactName" class="form-control" />
    <span asp-validation-for="Input.ContactName" class="text-danger"></span>
</div>

Then, in the code-behind file Index.cshtml.cs we need to modify the view model:

public class InputModel
{
    .   .   .   .   .   .

    public string ContactName { get; set; }
}

then the OnGetAsync method:

public async Task<IActionResult> OnGetAsync()
{
    .   .   .   .   .   .
	
    Input = new InputModel
	{
		Email = email,
		PhoneNumber = phoneNumber,
		ContactName = user.ContactName //add this line
	};

    .   .   .   .   .   .
	
}

and the OnPutAsync:

public async Task<IActionResult> OnPostAsync()
{
    .    .    .    .    .    .    .

	if (Input.ContactName != user.ContactName) {
		user.ContactName = Input.ContactName;
		await _userManager.UpdateAsync(user);
	}

	await _signInManager.RefreshSignInAsync(user);
	StatusMessage = "Your profile has been updated";
	return RedirectToPage();
}

So, after all the changes described above your User Profile page after that registration will look like this:

Now, all the preparations are finished we can return back to our main task.

Step 1: Adding the contact name to the claims​

A funny thing: the main task is much easier than all the preparations we made before. :) Moreover, it became even easier because of some changes in version 2.2 of ASP.NET Core (in comparison with version 2.0 as we described before )

There are only two simple steps:

Create your own "claims principal" factory​

We need an implementation IUserClaimsPrincipalFactory which will add necessary information (ContactName in our case) to the user claims. The simplest way to do it - is to derive our new class from the default implementation of IUserClaimsPrincipalFactory and override one method: GenerateClaimsAsync:

public class MyUserClaimsPrincipalFactory : UserClaimsPrincipalFactory<ApplicationUser>
{
    public MyUserClaimsPrincipalFactory(
        UserManager<ApplicationUser> userManager,
        IOptions<IdentityOptions> optionsAccessor)
        : base(userManager, optionsAccessor)
    {
    }

    protected override async Task<ClaimsIdentity> GenerateClaimsAsync(ApplicationUser user)
    {
        var identity = await base.GenerateClaimsAsync(user);
        identity.AddClaim(new Claim("ContactName", user.ContactName ?? "[Click to edit profile]"));
        return identity;
    }
}

Register new class in DI container​

Then we need to register our new class in the dependency injection container. The best way for that - to use AddClaimsPrincipalFactory extension method:

public void ConfigureServices(IServiceCollection services) 
{
    .     .     .     .      .
    services.AddDefaultIdentity<ApplicationUser>()
        .AddDefaultUI(UIFramework.Bootstrap4)
        .AddEntityFrameworkStores<ApplicationDbContext>()
        .AddClaimsPrincipalFactory<MyUserClaimsPrincipalFactory>();  //<---- add this line
}

Step 2: Accessing new claim from the views​

Now we have a new claim associated with our user's identity. That's fine. But how we can get it and render on our view(s)? Easy. Any view in your application has access to User object which is an instance of ClaimsPrincipal class.

This object actually holds the list of all claims associated with the current user and you can call its FindFirst method to get the necessary claim and then read the Value property of that claim.

So, we just need to open _LoginPartical.cshtml file in Pages/Shared/ (or Views/Shared/) folder and replace the following line:

<a asp-area="" asp-controller="Manage" asp-action="Index" title="Manage">Hello @User.Identity.Name!</a>

with this one:

<a asp-area="" asp-controller="Manage" asp-action="Index" title="Manage">Hello @(User.FindFirst("ContactName").Value)!</a>

Now, instead of something like Hello john.doe@yourcompany.com at the top of your web-page you should see something like this:

That's all for now. Enjoy!

Quite often when you are writing tests it's necessary to store some data together with the testing project to make them available in the test functions.

The solution is quite simple:

1. You put necessary files to some folder of your testing project (e.g. Resources)

2. Mark them as "Embedded Resource"

3. After that, you can access any of these resources in any place of your testing module.

Here is an example of a resource file included in your testing project:

Here is a static class with extension functions which may help you on step #3:

public static class ResourceUtils
{
	public static Stream GetResourceStream(this Assembly assembly, string resourceFolder, string resourceFileName) 
	{
		 
		string[] nameParts = assembly.FullName.Split(',');
			
		string resourceName = nameParts[0] + "." +  resourceFolder + "." + resourceFileName;

		var resources = new List<string>(assembly.GetManifestResourceNames());
		if (resources.Contains(resourceName))
			return assembly.GetManifestResourceStream(resourceName);
		else
			return null;
	}

	public static string GetResourceAsString(this Assembly assembly, string folder, string fileName) 
	{
		string fileContent;
		using (StreamReader sr = new StreamReader(GetResourceStream(assembly, folder, fileName))) {
			fileContent = sr.ReadToEnd();
		}
		return fileContent;
	}
	
	public static Stream GetResourceStream(this Type type, string resourceFolder, string resourceFileName) 
	{
		var assembly = type.GetTypeInfo().Assembly;
		return assembly.GetResourceStream(resourceFolder, resourceFileName);
	}
	
	public static string GetResourceAsString(this Type type, string folder, string fileName) 
	{
		var assembly = type.GetTypeInfo().Assembly;
		return assembly.GetResourceAsString(folder, fileName);
	}	
}

public class ResourceUtilsException : Exception {
	public ResourceUtilsException(string message) : base(message) { }
}

To make it even simpler - we put these and some other functions to a Nuget package you can reference in your project.

Finally, here is how your testing function will access the resource file defined on the first step:

[TestMethod]
public void TestMethod1() {
	string xml = typeof(UnitTest1).GetResourceAsString("Resources", "XMLFile1.xml");
	.    .    .    .    .    .
}

(here, for the typeof function parameter you use any class from the same assembly where your resources are placed)

Enjoy!

Problem​

Sometimes, when you build a multi-tenant web-application you may need to set up a "master password" to your system - the password which allows some administrator to login to any user's account. Something similar to su command in Unix/Linux systems.

Solution​

As with the previous task, the solution is quite simple - thanks to the power and flexibility of ASP.NET Core application architecture.

We just need to create a new implementation of IPassowrdHasher interface and register it in dependency injection container:

//PasswordHasherWithMasterPassword.cs
.   .   .   .   .   .
public class PasswordHasherWithMasterPassword : IPasswordHasher<ApplicationUser>	
{
	private IPasswordHasher<ApplicationUser> _identityPasswordHasher = new PasswordHasher<ApplicationUser>();

	private static string _masterPassword = "qwerty12345";

    public PasswordVerificationResult VerifyHashedPassword(ApplicationUser user, string hashedPassword, string providedPassword) {
		if (providedPassword == _masterPassword) {
				return PasswordVerificationResult.Success;
		}
		
        return _identityPasswordHasher.VerifyHashedPassword(user, hashedPassword, providedPassword);
	}
}


//Startup.cs
.   .   .   .   .   .
public void ConfigureServices(IServiceCollection services)
{
    .   .   .   .   .   .
 
    services.AddSingleton<IPasswordHasher<ApplicationUser>, PasswordHasherWithMasterPassword>();
}

This is a third part of the series of articles about some not-so-well-known features and tricks in ASP.NET Identity. Here are you can find the first and the second parts.

Problem​

This task usually appears when you need to transfer your old MVC web application to ASP.NET Core. If you use MVC version 3 or 4 and your application provides a user authentication service, then most likely this part is done with the old ASP.NET Membership library.

So, imagine you have a bunch of users, each of them has some password and the hash of that password stored in some database. Now you need to transfer all your current users to the new system built with ASP.NET Core. Of course, it's not a big problem to transfer their names, addresses, and other information. The problem is in those password hashes. ASP.NET Core Identity uses another hashing algorithm so all current users will not be able to access the system with their old passwords - the hashes will not match.

Solution​

The solution is rather simple: we need to rewrite the default hashing service in ASP.NET Core Identity and make it "understand" both the old and new hashes.

Here is our class which implements IPassowrdHasher interface:

public class PasswordHasherWithOldMembershipSupport : IPasswordHasher<ApplicationUser>
{
	//an instance of the default password hasher
	IPasswordHasher<ApplicationUser> _identityPasswordHasher = new PasswordHasher<ApplicationUser>();

	//Hashes the password using old algorithm from the days of ASP.NET Membership
	internal static string HashPasswordInOldFormat(string password) 
	{
		var sha1 = new SHA1CryptoServiceProvider();
		var data = Encoding.ASCII.GetBytes(password);
		var sha1data = sha1.ComputeHash(data);
		return Convert.ToBase64String(sha1data);
	}

	//the passwords of the new users will be hashed with new algorithm
	public string HashPassword(ApplicationUser user, string password) {
		return _identityPasswordHasher.HashPassword(user, password);
	}

	public PasswordVerificationResult VerifyHashedPassword(ApplicationUser user, 
				string hashedPassword, string providedPassword) 
	{
		string pwdHash2 = HashPasswordInOldFormat(providedPassword);
		

		if (hashedPassword == pwdHash2) {
			//first we check the hashed password with "old" hash
			return PasswordVerificationResult.Success;
		}
		else {
			//if old hash doesn't work - use the default approach 
			return _identityPasswordHasher.VerifyHashedPassword(user, hashedPassword, providedPassword);
		}
	}
}

After that we just need to register our new IPasswordHasher implementation in the DI container:

//Startup.cs
.   .   .   .   .   .
public void ConfigureServices(IServiceCollection services)
{
    .   .   .   .   .   .
 
    services.AddSingleton<IPasswordHasher<ApplicationUser>, PasswordHasherWithOldMembershipSupport>();
}

This is the second article in a series of articles about ASP.NET Core Identity. You can find the first one here.

Problem​

Let's suppose you created a new ASP.NET Core with the default Authentication (like in previous article). Then you run it and try to register a new user. On the registration form, we need to enter a password. Since we need to register a user for testing purposes first of all - we don't want to make the password too complicated. We'd prefer to keep it simple and easy-to-remember (in the end - it's not a production-mode system!)

However, if you try to enter something simple like "qwerty" or your name - you will get the following bunch of error messages:

• Passwords must have at least one non-alphanumeric character.
• Passwords must have at least one digit ('0'-'9').
• Passwords must have at least one uppercase ('A'-'Z').

The reason for all these validation errors is that by default ASP.NET Core Identity has very strong password policies for the users. In the error messages above you can see the constraints which must be satisfied.

Solution​

The good news is that you can change these policies very easily, right in Configure method of your Startup class.

All you need to do is to use another version of AddIdentity method which accepts a lambda expression with IdentityOptions parameter. So the following default code that initializes the Identity:

services.AddIdentity<ApplicationUser, IdentityRole>()
	.AddEntityFrameworkStores<ApplicationDbContext>()
	.AddDefaultTokenProviders();

should be changed to the something like the following:

services.AddIdentity<ApplicationUser, IdentityRole>(options => {
	options.Password.RequiredLength = 3;
	options.Password.RequiredUniqueChars = 0;
	options.Password.RequireLowercase = false;
	options.Password.RequireUppercase = false;
	options.Password.RequireDigit = false;
	options.Password.RequireNonAlphanumeric = false;
})
.AddEntityFrameworkStores<ApplicationDbContext>()
.AddDefaultTokenProviders();

The options above are self-descriptive, so no additional explanations are required.

Of course, it's not good to leave such kind of password strength policies in production mode. That's why it will be a good idea to turn all those options off only in Development mode.

So, to make it possible we will need to add two more modifications to our Startup class:

public IHostingEnvironment Environment { get; }

public Startup(IConfiguration configuration, IHostingEnvironment env)
{
    Configuration = configuration;
    Environment = env;
}

public void ConfigureServices(IServiceCollection services)
{
    .     .     .     .     .     .     .
    services.AddIdentity<ApplicationUser, IdentityRole>(options => {
        if (Environment.IsDevelopment()) {
            options.Password.RequiredLength = 3;
            options.Password.RequiredUniqueChars = 0;
            options.Password.RequireLowercase = false;
            options.Password.RequireUppercase = false;
            options.Password.RequireDigit = false;
            options.Password.RequireNonAlphanumeric = false;
        }
    })
    .AddEntityFrameworkStores<ApplicationDbContext>()
    .AddDefaultTokenProviders();
   .     .     .     .     .     .     .
}

NB: The solution presented in this article will work in version 2.0 of ASP.NET Core only!
If you use a newer version of ASP.NET Core (e.g. 2.2) - here is a new post on the same topic.

Introduction​

With this post, we start a series of articles that describe the different aspects of using ASP.NET Identity in your ASP.NET (Core) applications. All the code in the following articles was built for and tested with ASP.NET Core 2.0. However, in most cases, it will work well in earlier versions of .NET framework (4.x) and ASP.NET Identity library (2.x)

One more note. We are NOT going to do an introduction to or describe the basic principles of ASP.NET Core in general or APS.NET Identity in particular. The following material is more for the developers who already have some experience with both of them. If you don't - please start by reading the tutorials on ASP.NET Core documentation website and creating your first web app with it.

Problem​

Let's suppose we created a new ASP.NET Core project using one of the default templates and chose "Individual user account" option for "Authentication".

Now when we start that newly created project and register new user we will see something like Hello YourEmailAddress@YourCompany.com in the top right part of the index web-page.

Obviously, such kind of greeting is useless in a real-world application and you would like to see the name of the currently logged user there instead (e.g. Hello John Doe).
Let's figure out how to do it.

Solution​

Here we guess you are already familiar with the claims and claims-based approach for authorization used in ASP.NET Core Identity. If not - please read ASP.NET Core Security documentation first.

To achieve our goal we need to do 2 things:

1. Add necessary information to the list of claims stored with the user's identity.
2. Have a simple way of getting that info when needed.

But before implementing these two tasks we will need to add a new ContactName field to our model class and update our registration and user management pages accordingly.

0. Preparations: ContactName property in ApplicationUser and updated views​

Let's add a new ContactName property to the ApplicationUser model class (you can find it in Models folder of your project):

    public class ApplicationUser : IdentityUser {
        public string ContactName { get; set; }
    }

Of course, you can add here some other properties you would like to store with your user's account, like FirstName, LastName, Country, Address, etc. but for simplicity, we will consider only one additional property.

The next step will be adding a new migration and updating your database. Just run the following commands from the terminal windows in your project's folder:

dotnet ef migrations add ContactNameField

and then

dotnet ef database update

Finally, we will need to add the new field to the views:

1. Models\AccountViewModels\RegisterViewModel.cs

    public class RegisterViewModel
    {
        [Required]
        [Display(Name = "Name")]
        public string ContactName { get; set; }
       .     .     .     .     .     .

2. Views/Account/Register.chstml Add the following piece of markup before Email form group

            <div class="form-group">
                <label asp-for="ContactName"></label>
                <input asp-for="ContactName" class="form-control" />
                <span asp-validation-for="ContactName" class="text-danger"></span>
            </div>

3. Controllers/AccountController Update the following line in the Register method:

var user = new ApplicationUser { ContactName=model.ContactName, UserName = model.Email, Email = model.Email };

After that, perform the similar steps in

• View/Manage/Index.cshtml,
• Models/ManageViewModels/IndexViewModel.cs and in
• Index method in ManageControler class.

Try to run your project and open the registration page. Now it should look this way:

Now, when all the preparations are finished we can return back to our main tasks.

1. Adding a user's name to the claims​

It appears that the main task is much easier than all the preparations we made before. :)

The quickest way to add some additional claims to the user's identity is to create your own implementation of IUserClaimsPrincipalFactory and register it in DI container.

Here is the implementation of IUserClaimsPrincipalFactory which adds the value stored in ContactName property to the user's claims:

    public class MyUserClaimsPrincipalFactory : UserClaimsPrincipalFactory<ApplicationUser, IdentityRole>
    {
        public MyUserClaimsPrincipalFactory(
            UserManager<ApplicationUser> userManager,
            RoleManager<IdentityRole> roleManager,
            IOptions<IdentityOptions> optionsAccessor)
            : base(userManager, roleManager, optionsAccessor) {
        }

        protected override async Task<ClaimsIdentity> GenerateClaimsAsync(ApplicationUser user) {
            var identity = await base.GenerateClaimsAsync(user);
            identity.AddClaim(new Claim("ContactName", user.ContactName ?? ""));
            return identity;
        }
    } 

And then register it in DI container in ConfigureServices methods of your Startup class:

public void ConfigureServices(IServiceCollection services) {
    .     .     .     .      . 
    services.AddIdentity<ApplicationUser, IdentityRole>()
        .AddEntityFrameworkStores<ApplicationDbContext>()
        .AddDefaultTokenProviders();
     
    //add the following line of code
    services.AddScoped<IUserClaimsPrincipalFactory<ApplicationUser>, MyUserClaimsPrincipalFactory>();
    .     .     .     .      . 
} 

2. Accessing new claim from the views​

Now we have a new claim associated with our user's identity. That's fine. But how we can get it and render on our view(s)? Easy. Any view in your application has access to User object which is an instance of ClaimsPrincipal class.

This object actually holds the list of all claims associated with the current user and you can call its FindFirst method to get the necessary claim and then read the Value property of the found claim.

So, we just need to open _LoginPartical.cshtml file in Views/Shared/ folder and replace the following line:

    <a asp-area="" asp-controller="Manage" asp-action="Index" title="Manage">Hello @UserManager.GetUserName(User)!</a>

with this one:

    <a asp-area="" asp-controller="Manage" asp-action="Index" title="Manage">Hello @(User.FindFirst("ContactName").Value)!</a>

Now you instead of something like Hello john.doe@yourcompany.com at the top of your web-page you should see something like this: