.NET

Structured Data using Schema.NET

2nd July 2017

What is Schema.org?

Schema.org defines a set of standard classes and their properties for objects and services in the real world. There are nearly 700 classes at the time of writing defined by schema.org. This machine readable format is a common standard used across the web for describing things.

Where is Schema.org Used?

Websites

Websites can define Structured Data in the head section of their html to enable search engines to show richer information in their search results. Here is an example of how Google can display extended metadata about your site in it’s search results.

Using structured data in html requires the use of a script tag with a MIME type of application/ld+json like so:

<script type="application/ld+json">
{
  "@context": "http://schema.org",
  "@type": "Organization",
  "url": "http://www.example.com",
  "name": "Unlimited Ball Bearings Corp.",
  "contactPoint": {
    "@type": "ContactPoint",
    "telephone": "+1-401-555-1212",
    "contactType": "Customer service"
  }
}
</script>

{

"@context": "http://schema.org",

"@type": "Organization",

"url": "http://www.example.com",

"name": "Unlimited Ball Bearings Corp.",

"contactPoint": {

"@type": "ContactPoint",

"telephone": "+1-401-555-1212",

"contactType": "Customer service"

}

</script>

Windows UWP Sharing

Windows UWP apps let you share data using schema.org classes. Here is an example showing how to share metadata about a book.

Enter Schema.NET

Schema.NET is Schema.org objects turned into strongly typed C# POCO classes for use in .NET. All classes can be serialized into JSON/JSON-LD. Here is a simple Schema.NET example that defines the name and URL of a website:

var website = new WebSite()
{
    AlternateName = "An Alternative Name",
    Name = "Your Site Name",
    Url = new Uri("https://example.com")
};
var jsonLd = website.ToString();

var website = new WebSite()

{

AlternateName = "An Alternative Name",

Name = "Your Site Name",

Url = new Uri("https://example.com")

};

var jsonLd = website.ToString();

The code above outputs the following JSON-LD:

{
    "@context":"http://schema.org",
    "@type":"WebSite",
    "alternateName":"An Alternative Name",
    "name":"Your Site Name",
    "url":"https://example.com"
}

{

"@context":"http://schema.org",

"@type":"WebSite",

"alternateName":"An Alternative Name",

"name":"Your Site Name",

"url":"https://example.com"

}

There are dozens more examples based on Google’s Structured Data documentation with links to the relevant page in the unit tests of the Schema.NET project.

Classes & Properties

schema.org defines classes and properties, where each property can have a single value or an array of multiple values. Additionally, properties can have multiple types e.g. an ‘Address’ property could have a type of ‘string’ or a type of ‘PostalAddress’ which has it’s own properties such as ‘StreetAddress’ or ‘PostalCode’ which breaks up an address into it’s constituent parts.

To facilitate this Schema.NET uses some clever C# generics and implicit type conversions so that setting a single or multiple values is possible and that setting a ‘string’ or ‘PostalAddress’ is also possible:

// Single string address
var organization = new Organization()
{
    Address = "123 Old Kent Road E10 6RL"
};
// Multiple string addresses
var organization = new Organization()
{
    Address = new List<string>()
    {
        "123 Old Kent Road E10 6RL",
        "456 Finsbury Park Road SW1 2JS"
    }
};
// Single PostalAddress address
var organization = new Organization()
{
    Address = new PostalAddress()
    {
        StreetAddress = "123 Old Kent Road",
        PostalCode = "E10 6RL"
    }
};
// Multiple PostalAddress addresses
var organization = new Organization()
{
    Address = new List<PostalAddress>()
    {
        new PostalAddress()
        {
            StreetAddress = "123 Old Kent Road",
            PostalCode = "E10 6RL"
        },
        new PostalAddress()
        {
            StreetAddress = "456 Finsbury Park Road",
            PostalCode = "SW1 2JS"
        }
    }
};

// Single string address

var organization = new Organization()

{

Address = "123 Old Kent Road E10 6RL"

};

// Multiple string addresses

var organization = new Organization()

{

Address = new List<string>()

{

"123 Old Kent Road E10 6RL",

"456 Finsbury Park Road SW1 2JS"

}

};

// Single PostalAddress address

var organization = new Organization()

{

Address = new PostalAddress()

{

StreetAddress = "123 Old Kent Road",

PostalCode = "E10 6RL"

}

};

// Multiple PostalAddress addresses

var organization = new Organization()

{

Address = new List<PostalAddress>()

{

new PostalAddress()

{

StreetAddress = "123 Old Kent Road",

PostalCode = "E10 6RL"

new PostalAddress()

{

StreetAddress = "456 Finsbury Park Road",

PostalCode = "SW1 2JS"

}

};

This magic is all carried out using the ‘Value<T>’, ‘Value<T1, T2>’, ‘Value<T1, T2, T3>’ etc. types. These types are all structs for best performance too.

Where to Get It?

Download the Schema.NET NuGet package or take a look at the code on GitHub. At some point I’ll find the time to write a quick ASP.NET Core tag helper that wraps Schema.NET.

ASP.NET Core Lazy Command Pattern

All, ASP.NET MVC / 15 comments

8th April 2017

TLDR: Move your ASP.NET Core MVC action method logic into lazily loaded commands using the command pattern.

When writing your Controllers in ASP.NET Core, you can end up with a very long class if you’re not careful. You may have written several action methods with a few lines of code in each, you may be injecting a few services into your controller and you may have commented your action methods to support Swagger. The point is it’s very easy to do, here is an example:

[Route("[controller]")]
public class RocketController : Controller
{
    private readonly IPlanetRepository planetRepository;
    private readonly IRocketRepository rocketRepository;
    public RocketController(
        IPlanetRepository planetRepository,
        IRocketRepository rocketRepository)
    {
        this.planetRepository = planetRepository;
        this.rocketRepository = rocketRepository;
    }
    [HttpGet("{rocketId}")]
    public async Task<IActionResult> GetRocket(int rocketId)
    {
        var rocket = await this.rocketRepository.GetRocket(rocketId);
        if (rocket == null)
        {
            return this.NotFound();
       }
        return this.Ok(rocket);
    }
    [HttpGet("{rocketId}/launch/{planetId}")]
    public async Task<IActionResult> LaunchRocket(int rocketId, int planetId)
    {
        var rocket = await this.rocketRepository.GetRocket(rocketId);
        if (rocket == null)
        {
            return this.NotFound();
        }
        var planet = await this.planetRepository.GetPlanet(planetId);
        if (planet == null)
        {
            return this.NotFound();
        }
        this.rocketRepository.VisitPlanet(rocket, planet);
        return this.Ok(rocket);
    }
}

[Route("[controller]")]

public class RocketController : Controller

{

private readonly IPlanetRepository planetRepository;

private readonly IRocketRepository rocketRepository;

public RocketController(

IPlanetRepository planetRepository,

IRocketRepository rocketRepository)

{

this.planetRepository = planetRepository;

this.rocketRepository = rocketRepository;

}

[HttpGet("{rocketId}")]

public async Task<IActionResult> GetRocket(int rocketId)

{

var rocket = await this.rocketRepository.GetRocket(rocketId);

if (rocket == null)

{

return this.NotFound();

}

return this.Ok(rocket);

}

[HttpGet("{rocketId}/launch/{planetId}")]

public async Task<IActionResult> LaunchRocket(int rocketId, int planetId)

{

var rocket = await this.rocketRepository.GetRocket(rocketId);

if (rocket == null)

{

return this.NotFound();

}

var planet = await this.planetRepository.GetPlanet(planetId);

if (planet == null)

{

return this.NotFound();

}

this.rocketRepository.VisitPlanet(rocket, planet);

return this.Ok(rocket);

}

The Command Pattern

This is where the command pattern can come in handy. The command pattern moves logic from each action method and injected dependencies into their own class like so:

[Route("[controller]")]
public class RocketController : Controller
{
    private readonly Lazy<IGetRocketCommand> getRocketCommand;
    private readonly Lazy<ILaunchRocketCommand> launchRocketCommand;
    public RocketController(
        Lazy<IGetRocketCommand> getRocketCommand,
        Lazy<ILaunchRocketCommand> launchRocketCommand)
    {
        this.getRocketCommand = getRocketCommand;
        this.launchRocketCommand = launchRocketCommand;
    }
    [HttpGet("{rocketId}")]
    public Task<IActionResult> GetRocket(int rocketId) =>
        this.getRocketCommand.Value.ExecuteAsync(rocketId);
    [HttpGet("{rocketId}/launch/{planetId}")]
    public Task<IActionResult> LaunchRocket(int rocketId, int planetId) =>
        this.launchRocketCommand.Value.ExecuteAsync(rocketId, planetId);
}
public interface IGetRocketCommand : IAsyncCommand<int>
{
}
public class GetRocketCommand : IGetRocketCommand
{
    private readonly IRocketRepository rocketRepository;
    public GetRocketCommand(IRocketRepository rocketRepository) =>
        this.rocketRepository = rocketRepository;
    public async Task<IActionResult> ExecuteAsync(int rocketId)
    {
        var rocket = await this.rocketRepository.GetRocket(rocketId);
        if (rocket == null)
        {
            return new NotFoundResult();
        }
        return new OkObjectResult(rocket);
    }
}

[Route("[controller]")]

public class RocketController : Controller

{

private readonly Lazy<IGetRocketCommand> getRocketCommand;

private readonly Lazy<ILaunchRocketCommand> launchRocketCommand;

public RocketController(

Lazy<IGetRocketCommand> getRocketCommand,

Lazy<ILaunchRocketCommand> launchRocketCommand)

{

this.getRocketCommand = getRocketCommand;

this.launchRocketCommand = launchRocketCommand;

}

[HttpGet("{rocketId}")]

public Task<IActionResult> GetRocket(int rocketId) =>

this.getRocketCommand.Value.ExecuteAsync(rocketId);

[HttpGet("{rocketId}/launch/{planetId}")]

public Task<IActionResult> LaunchRocket(int rocketId, int planetId) =>

this.launchRocketCommand.Value.ExecuteAsync(rocketId, planetId);

}

public interface IGetRocketCommand : IAsyncCommand<int>

{

}

public class GetRocketCommand : IGetRocketCommand

{

private readonly IRocketRepository rocketRepository;

public GetRocketCommand(IRocketRepository rocketRepository) =>

this.rocketRepository = rocketRepository;

public async Task<IActionResult> ExecuteAsync(int rocketId)

{

var rocket = await this.rocketRepository.GetRocket(rocketId);

if (rocket == null)

{

return new NotFoundResult();

}

return new OkObjectResult(rocket);

}

All the logic and dependencies in the controllers gets moved to the command which now has a single responsibility. The controller now has a different set of dependencies, it now lazily injects one command per action method.

You may have noticed the IAsyncCommand interface. I keep four of these handy to inherit from. They all outline an ExecuteAsync method to execute the command and return an IActionResult but they have a differing number of parameters. I personally feel if you are needing more than three parameters you should be using a class to represent your parameters, so I’ve put the limit on three parameters.

public interface IAsyncCommand
{
    Task<IActionResult> ExecuteAsync();
}
public interface IAsyncCommand<T>
{
    Task<IActionResult> ExecuteAsync(T parameter);
}
public interface IAsyncCommand<T1, T2>
{
    Task<IActionResult> ExecuteAsync(T1 parameter1, T2 parameter2);
}
public interface IAsyncCommand<T1, T2, T3>
{
    Task<IActionResult> ExecuteAsync(T1 parameter1, T2 parameter2, T3 parameter3);
}

public interface IAsyncCommand

{

Task<IActionResult> ExecuteAsync();

}

public interface IAsyncCommand<T>

{

Task<IActionResult> ExecuteAsync(T parameter);

}

public interface IAsyncCommand<T1, T2>

{

Task<IActionResult> ExecuteAsync(T1 parameter1, T2 parameter2);

}

public interface IAsyncCommand<T1, T2, T3>

{

Task<IActionResult> ExecuteAsync(T1 parameter1, T2 parameter2, T3 parameter3);

}

Why so Lazy?

Why do we use Lazy<T>? Well the answer is that if we have multiple action methods on our controller, we don’t want to instantiate the dependencies for every action method if we are only planning on using one action method. Registering our Lazy commands requires a bit of extra work in out Startup.cs. We can register lazy dependencies like so:

public void ConfigureServices(IServiceCollection services)
{
    // ...Omitted
    services
        .AddScoped<IGetRocketCommand, GetRocketCommand>()
        .AddScoped(x => new Lazy<IGetRocketCommand>(
            () => x.GetRequiredService<IGetRocketCommand>()));
}

public void ConfigureServices(IServiceCollection services)

{

// ...Omitted

services

.AddScoped<IGetRocketCommand, GetRocketCommand>()

.AddScoped(x => new Lazy<IGetRocketCommand>(

() => x.GetRequiredService<IGetRocketCommand>()));

}

HttpContext and ActionContext

Now you might be thinking, how do I access the HttpContext or ActionContext if I want to set a HTTP header for example? Well, you can use the IHttpContextAccessor or IActionContextAccessor interfaces for this purpose. You can register them in your Startup class like so:

public void ConfigureServices(IServiceCollection services)
{
    // ...Omitted
    services
        .AddSingleton<IHttpContextAccessor, HttpContextAccessor>()
        .AddSingleton<IActionContextAccessor, ActionContextAccessor>();
}

public void ConfigureServices(IServiceCollection services)

{

// ...Omitted

services

.AddSingleton<IHttpContextAccessor, HttpContextAccessor>()

.AddSingleton<IActionContextAccessor, ActionContextAccessor>();

}

Notice that they can be registered as singletons. You can then use them to get hold of the HttpContext or ActionContext objects for the current HTTP request. Here is a really simple example.

public class SetHttpHeaderCommand : ISetHttpHeaderCommand
{
    private readonly IHttpContextAccessor httpContextAccessor;
    public GetRocketCommand(IHttpContextAccessor httpContextAccessor) =>
        this.httpContextAccessor = httpContextAccessor;
    public async Task<IActionResult> ExecuteAsync()
    {
        this.httpContextAccessor.HttpContext.Response.Headers.Add("X-Rocket", "Saturn V");
        return new OkResult();
    }
}

public class SetHttpHeaderCommand : ISetHttpHeaderCommand

{

private readonly IHttpContextAccessor httpContextAccessor;

public GetRocketCommand(IHttpContextAccessor httpContextAccessor) =>

this.httpContextAccessor = httpContextAccessor;

public async Task<IActionResult> ExecuteAsync()

{

this.httpContextAccessor.HttpContext.Response.Headers.Add("X-Rocket", "Saturn V");

return new OkResult();

}

Unit Testing

Another upside to the command pattern is that testing each command becomes super simple. You don’t need to setup a controller with lots of dependencies that you don’t care about. You only need to write test code for that single feature.

Conclusions

For a full working example, take a look at the ASP.NET MVC Boilerplate API project template which makes full use of the Lazy Command Pattern.

dotnet new Feature Selection

All, Tools / 2 comments

26th March 2017

In my last post I showed how to get started with using dotnet new to build project templates. In this post, I’m going to build on that knowledge and show how to add feature selection to your project template so developers can choose to add or remove bits of your template. If you check out my Boilerplate API project template, you’ll see that I have 17 features for you to set. If you run the help command against my template you’ll see a description of each and instructions on how you can set them (I’ve cleaned up the CLI output, the current help commands output is pretty awful but this is being addressed in the next version of dotnet new).

PS C:\Users\rehan.saeed> dotnet new bapi --help
Template Instantiation Commands for .NET Core CLI.
Usage: dotnet new [arguments] [options]
Arguments:
  template  The template to instantiate.
Options:
  -l|--list         List templates containing the specified name.
  -lang|--language  Specifies the language of the template to create
  -n|--name         The name for the output being created. If no name is specified, the name of the current directory is
used.
  -o|--output       Location to place the generated output.
  -h|--help         Displays help for this command.
  -all|--show-all   Shows all templates
ASP.NET Core 1.1.1 MVC 6 Boilerplate API (C#)
Author: Muhammad Rehan Saeed (RehanSaeed.com)
Options:
  -Ti|--Title: The name of the project which determines the assembly product name. If the Swagger feature is enabled,
    shows the title on the Swagger UI.
    string - Optional
    Default: Project Title
  -D|--Description: A description of the project which determines the assembly description. If the Swagger feature is
    enabled, shows the description on the Swagger UI.
    string - Optional
    Default: Project Description
  -Au|--Author: The name of the author of the project which determines the assembly author, company and copyright
    information.
    string - Optional
    Default: Project Author
  -Sw|--Swagger: Swagger is a format for describing the endpoints in your API. Swashbuckle is used to generate a
    Swagger document and to generate beautiful API documentation, including a UI to explore and test operations,
    directly from your routes, controllers and models.
    bool - Optional
    Default: true
  -T|--TargetFramework: Decide which version of the .NET Framework to target.
    .NET Core         - Run cross platform (on Windows, Mac and Linux). The framework is made up of NuGet packages
                        which can be shipped with the application so it is fully stand-alone.
    .NET Framework    - Gives you access to the full breadth of libraries available in .NET instead of the subset
                        available in .NET Core but requires it to be pre-installed.
    Both              - Target both .NET Core and .NET Framework.
    Default: Both
  -P|--PrimaryWebServer: The primary web server you want to use to host the site.
    Kestrel        - A web server for ASP.NET Core that is not intended to be internet facing as it has not been
                     security tested. IIS or NGINX should be placed in front as reverse proxy web servers.
    WebListener    - A Windows only web server. It gives you the option to take advantage of Windows specific
                     features, like Windows authentication, port sharing, HTTPS with SNI, HTTP/2 over TLS
                     (Windows 10), direct file transmission, and response caching WebSockets (Windows 8).
    Default: Kestrel
  -Re|--ReverseProxyWebServer: The internet facing reverse proxy web server you want to use in front ofthe primary
    web server to host the site.
    Internet Information Services (IIS) - A flexible, secure and manageable Web server for hosting anything on the
                                          Web using Windows Server. Select this option if you are deploying your site
                                          to Azure web apps. IIS is preconfigured to set request limits for security.
    NGINX                               - A free, open-source, cross-platform high-performance HTTP server and
                                          reverse proxy, as well as an IMAP/POP3 proxy server. It does have a Windows
                                          version but its not very fast and IIS is better on that platform. If the
                                          HTTPS Everywhere feature is enabled, NGINX is pre-configured to enable the
                                          most secure TLS protocols and ciphers for security and to enable HTTP 2.0
                                          and SSL stapling for performance.
    Both                                - Support both reverse proxy web servers.
    Default: Both
  -C|--CloudProvider: Select which cloud provider you are using if any, to add cloud specific features.
    Azure    - The Microsoft Azure cloud. Adds logging features that let you see logs in the Azure portal.
    None     - No cloud provider is being used.
    Default: None
  -A|--Analytics: Monitor internal information about how your application is running, as well as external user
    information.
    Application Insights    - Monitor internal information about how your application is running, as well as
                              external user information using the Microsoft Azure cloud.
    None                    - Not using any analytics.
    Default: None
  -Ap|--ApplicationInsightsInstrumentationKey: Your Application Insights instrumentation key
    e.g. 11111111-2222-3333-4444-555555555555.
    string - Optional
    Default: APPLICATION-INSIGHTS-INSTRUMENTATION-KEY
  -H|--HttpsEverywhere: Use the HTTPS scheme and TLS security across the entire site, redirects HTTP to HTTPS and
    adds a Strict Transport Security (HSTS) HTTP header with preloading enabled. Configures the primary and reverse
    proxy web servers for best security and adds a development certificate file for use in your development environment.
    bool - Optional
    Default: true
  -Pu|--PublicKeyPinning: Adds the Public-Key-Pins (HPKP) HTTP header to responses. It stops man-in-the-middle
    attacks by telling browsers exactly which TLS certificate you expect. You must have two TLS certificates for this
    to work, if you get this wrong you will have performed a denial of service attack on yourself.
    bool - Optional
    Default: false
  -CO|--CORS: Browser security prevents a web page from making AJAX requests to another domain. This restriction is
    called the same-origin policy, and prevents a malicious site from reading sensitive data from another site.
    CORS is a W3C standard that allows a server to relax the same-origin policy. Using CORS, a server can explicitly
    allow some cross-origin requests while rejecting others.
    bool - Optional
    Default: true
  -X|--XmlFormatter: Choose whether to use the XML input/output formatter and which serializer to use.
    DataContractSerializer - The default XML serializer you should use. Requires the use of [DataContract] and
                             [DataMember] attributes.
    XmlSerializer          - The alternative XML serializer which is slower but gives more control. Uses the
                             [XmlRoot], [XmlElement] and [XmlAttribute] attributes.
    None                   - No XML formatter.
    Default: None
  -S|--StatusController: An endpoint that returns the status of this API and its dependencies, giving an indication
    of its health. This endpoint can be called by site monitoring tools which ping the site or by load balancers
    which can remove an instance of this API if it is not functioning correctly.
    bool - Optional
    Default: true
  -R|--RequestId: Require that all requests send the X-Request-ID HTTP header containing a GUID. This is useful where
    you have access to the client and server logs and want to correlate a request and response between the two.
    bool - Optional
    Default: false
  -U|--UserAgent: Require that all requests send the User-Agent HTTP header containing the application name and
    version of the caller.
    bool - Optional
    Default: false
  -Ro|--RobotsTxt: Adds a robots.txt file to tell search engines not to index this site.
    bool - Optional
    Default: true
  -Hu|--HumansTxt: Adds a humans.txt file where you can tell the world who wrote the application. This file is a good
    place to thank your developers.
    bool - Optional
    Default: true

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

119

120

121

PS C:\Users\rehan.saeed> dotnet new bapi --help

Template Instantiation Commands for .NET Core CLI.

Usage: dotnet new [arguments] [options]

Arguments:

template The template to instantiate.

Options:

-l|--list List templates containing the specified name.

-lang|--language Specifies the language of the template to create

-n|--name The name for the output being created. If no name is specified, the name of the current directory is

used.

-o|--output Location to place the generated output.

-h|--help Displays help for this command.

-all|--show-all Shows all templates

ASP.NET Core 1.1.1 MVC 6 Boilerplate API (C#)

Author: Muhammad Rehan Saeed (RehanSaeed.com)

Options:

-Ti|--Title: The name of the project which determines the assembly product name. If the Swagger feature is enabled,

shows the title on the Swagger UI.

string - Optional

Default: Project Title

-D|--Description: A description of the project which determines the assembly description. If the Swagger feature is

enabled, shows the description on the Swagger UI.

string - Optional

Default: Project Description

-Au|--Author: The name of the author of the project which determines the assembly author, company and copyright

information.

string - Optional

Default: Project Author

-Sw|--Swagger: Swagger is a format for describing the endpoints in your API. Swashbuckle is used to generate a

Swagger document and to generate beautiful API documentation, including a UI to explore and test operations,

directly from your routes, controllers and models.

bool - Optional

Default: true

-T|--TargetFramework: Decide which version of the .NET Framework to target.

.NET Core - Run cross platform (on Windows, Mac and Linux). The framework is made up of NuGet packages

which can be shipped with the application so it is fully stand-alone.

.NET Framework - Gives you access to the full breadth of libraries available in .NET instead of the subset

available in .NET Core but requires it to be pre-installed.

Both - Target both .NET Core and .NET Framework.

Default: Both

-P|--PrimaryWebServer: The primary web server you want to use to host the site.

Kestrel - A web server for ASP.NET Core that is not intended to be internet facing as it has not been

security tested. IIS or NGINX should be placed in front as reverse proxy web servers.

WebListener - A Windows only web server. It gives you the option to take advantage of Windows specific

features, like Windows authentication, port sharing, HTTPS with SNI, HTTP/2 over TLS

(Windows 10), direct file transmission, and response caching WebSockets (Windows 8).

Default: Kestrel

-Re|--ReverseProxyWebServer: The internet facing reverse proxy web server you want to use in front ofthe primary

web server to host the site.

Internet Information Services (IIS) - A flexible, secure and manageable Web server for hosting anything on the

Web using Windows Server. Select this option if you are deploying your site

to Azure web apps. IIS is preconfigured to set request limits for security.

NGINX - A free, open-source, cross-platform high-performance HTTP server and

reverse proxy, as well as an IMAP/POP3 proxy server. It does have a Windows

version but its not very fast and IIS is better on that platform. If the

HTTPS Everywhere feature is enabled, NGINX is pre-configured to enable the

most secure TLS protocols and ciphers for security and to enable HTTP 2.0

and SSL stapling for performance.

Both - Support both reverse proxy web servers.

Default: Both

-C|--CloudProvider: Select which cloud provider you are using if any, to add cloud specific features.

Azure - The Microsoft Azure cloud. Adds logging features that let you see logs in the Azure portal.

None - No cloud provider is being used.

Default: None

-A|--Analytics: Monitor internal information about how your application is running, as well as external user

information.

Application Insights - Monitor internal information about how your application is running, as well as

external user information using the Microsoft Azure cloud.

None - Not using any analytics.

Default: None

-Ap|--ApplicationInsightsInstrumentationKey: Your Application Insights instrumentation key

e.g. 11111111-2222-3333-4444-555555555555.

string - Optional

Default: APPLICATION-INSIGHTS-INSTRUMENTATION-KEY

-H|--HttpsEverywhere: Use the HTTPS scheme and TLS security across the entire site, redirects HTTP to HTTPS and

adds a Strict Transport Security (HSTS) HTTP header with preloading enabled. Configures the primary and reverse

proxy web servers for best security and adds a development certificate file for use in your development environment.

bool - Optional

Default: true

-Pu|--PublicKeyPinning: Adds the Public-Key-Pins (HPKP) HTTP header to responses. It stops man-in-the-middle

attacks by telling browsers exactly which TLS certificate you expect. You must have two TLS certificates for this

to work, if you get this wrong you will have performed a denial of service attack on yourself.

bool - Optional

Default: false

-CO|--CORS: Browser security prevents a web page from making AJAX requests to another domain. This restriction is

called the same-origin policy, and prevents a malicious site from reading sensitive data from another site.

CORS is a W3C standard that allows a server to relax the same-origin policy. Using CORS, a server can explicitly

allow some cross-origin requests while rejecting others.

bool - Optional

Default: true

-X|--XmlFormatter: Choose whether to use the XML input/output formatter and which serializer to use.

DataContractSerializer - The default XML serializer you should use. Requires the use of [DataContract] and

[DataMember] attributes.

XmlSerializer - The alternative XML serializer which is slower but gives more control. Uses the

[XmlRoot], [XmlElement] and [XmlAttribute] attributes.

None - No XML formatter.

Default: None

-S|--StatusController: An endpoint that returns the status of this API and its dependencies, giving an indication

of its health. This endpoint can be called by site monitoring tools which ping the site or by load balancers

which can remove an instance of this API if it is not functioning correctly.

bool - Optional

Default: true

-R|--RequestId: Require that all requests send the X-Request-ID HTTP header containing a GUID. This is useful where

you have access to the client and server logs and want to correlate a request and response between the two.

bool - Optional

Default: false

-U|--UserAgent: Require that all requests send the User-Agent HTTP header containing the application name and

version of the caller.

bool - Optional

Default: false

-Ro|--RobotsTxt: Adds a robots.txt file to tell search engines not to index this site.

bool - Optional

Default: true

-Hu|--HumansTxt: Adds a humans.txt file where you can tell the world who wrote the application. This file is a good

place to thank your developers.

bool - Optional

Default: true

As you can see from the output, there are a few different types of feature you can create. You can also choose to make a feature required or optional. An optional feature, if not specified by the user will fall-back to a default value. Here are the different types available:

bool – This feature can be turned on or off and has a default of true or false.
string – This can be used to do a string replacement in your template. It has a default value which you can set to any arbitrary value.
choice – This is a feature with two or more named choices. Each choice can have it’s own description. The default value must be one of the choices.
computed – These are features flags that can be computed based on other symbols.

Bool Symbols

You can create a boolean feature by adding symbols section to your template.json file. If you look at the example below, I’ve specified an optional bool symbol, with a default value of true.

{
  ...
  "symbols": {
    "Swagger": {
      "type": "parameter",
      "datatype": "bool",
      "isRequired": false,
      "defaultValue": "true",
      "description": "Your description..."
    }
  }
}

{

...

"symbols": {

"Swagger": {

"type": "parameter",

"datatype": "bool",

"isRequired": false,

"defaultValue": "true",

"description": "Your description..."

}

In your code, you can then use the symbol name, in this case ‘Swagger’ as a pre-processor directive in C# code:

#if (Swagger)
Console.WriteLine("Swagger feature was selected");
#else
Console.WriteLine("Swagger feature was not selected");
#endif

#if (Swagger)

Console.WriteLine("Swagger feature was selected");

#else

Console.WriteLine("Swagger feature was not selected");

#endif

This is really cool because you can still run the application as a template author and the project will still work. If you define a ‘Swagger’ constant in your project properties, your feature will turn on or off too. This makes debugging your project template very easy as a template author.

If you want to use the symbol in files other than C# where pre-processor directives do not exist, you can use the comment syntax specific to that file extension, so in a JavaScript file would use the ‘//’ syntax:

//#if (Swagger)
console.log('Swagger feature was selected');
//#else
console.log('Swagger feature was not selected');
//#endif

//#if (Swagger)

console.log('Swagger feature was selected');

//#else

console.log('Swagger feature was not selected');

//#endif

Most file extensions that have their own comment syntax have been catered for. For text files where there is no comment syntax or for any file extension that the templating engine doesn’t know about you can use the ‘#’ character:

##if (Swagger)
Swagger feature was selected
##else
Swagger feature was not selected
##endif

##if (Swagger)

Swagger feature was selected

##else

Swagger feature was not selected

##endif

You can look at this code in the templating engine for a full list of supported file extensions and comment types.

String Symbols

String symbols can be used to do simple file replace operations.

{
  ...
  "symbols": {
    "Title": {
      "type": "parameter",
      "datatype": "string",
      "isRequired": false,
      "defaultValue": "Default Project Title",
      "replaces": "PROJECT-TITLE",
      "description": "Your description..."
    }
  }
}

{

...

"symbols": {

"Title": {

"type": "parameter",

"datatype": "string",

"isRequired": false,

"defaultValue": "Default Project Title",

"replaces": "PROJECT-TITLE",

"description": "Your description..."

}

The above symbol looks for a ‘PROJECT-TITLE’ string and replaces it with whatever the user specifies or with the default value ‘Default Project Title’ if the user doesn’t set anything.

Choice Symbols

A choice symbol is useful when you have more than two options and can’t use bool.

{
  ...
  "symbols": {
    "TargetFramework": {
      "type": "parameter",
      "datatype": "choice",
      "isRequired": false,
      "choices": [
        {
          "choice": ".NET Core",
          "description": "Your description..."
        },
        {
          "choice": ".NET Framework",
          "description": "Your description..."
        },
        {
          "choice": "Both",
          "description": "Your description..."
        }
      ],
      "defaultValue": "Both",
      "description": "Your description..."
    }
}

{

...

"symbols": {

"TargetFramework": {

"type": "parameter",

"datatype": "choice",

"isRequired": false,

"choices": [

{

"choice": ".NET Core",

"description": "Your description..."

{

"choice": ".NET Framework",

"description": "Your description..."

{

"choice": "Both",

"description": "Your description..."

}

"defaultValue": "Both",

"description": "Your description..."

}

In the example above, you have the choice of selecting a target framework, with a value of .NET Core, .NET Framework or Both. Each choice has it’s own description and the overall symbol also has it’s description.

Computed Symbols

In the above example, you can’t use the value ‘.NET Core’ as a C# pre-processor variable because it contains a dot and a space. This is where a computed symbol comes in handy.

{
  ...
  "symbols": {
   "NETCore": {
      "type": "computed",
      "value": "(TargetFramework == \".NET Core\" || TargetFramework == \"Both\")"
    },
    "NETFramework": {
      "type": "computed",
      "value": "(TargetFramework == \".NET Framework\" || TargetFramework == \"Both\")"
    }
  }
}

{

...

"symbols": {

"NETCore": {

"type": "computed",

"value": "(TargetFramework == \".NET Core\" || TargetFramework == \"Both\")"

"NETFramework": {

"type": "computed",

"value": "(TargetFramework == \".NET Framework\" || TargetFramework == \"Both\")"

}

Here I have set up two computed symbols which determines whether ‘.NET Core’ or ‘.NET Framework’ was selected individually in the previous choice symbol. I have named these symbols without a dot or space i.e. ‘NETCore’ and ‘NETFramework’ so I can use these as C# pre-processor symbols, the same way I showed above.

Conditionally Deleting Files or Folders

You can also use symbols to delete certain files or folders. In this example, I’ve extended my bool symbol example to additionally remove two files and a folder if the feature is deselected by the user.

{
  ...
  "symbols": {
    "Swagger": {
      "type": "parameter",
      "datatype": "bool",
      "isRequired": false,
      "defaultValue": "true",
      "description": "Your description..."
    }
  },
  "sources": [
    {
      "modifiers": [
        {
          "condition": "(!Swagger)",
          "exclude": [
            "Constants/HomeControllerRoute.cs",
            "Controllers/HomeController.cs",
            "ViewModelSchemaFilters/**/*"
          ]
        }
      ]
    }
  ]
}

{

...

"symbols": {

"Swagger": {

"type": "parameter",

"datatype": "bool",

"isRequired": false,

"defaultValue": "true",

"description": "Your description..."

}

"sources": [

{

"modifiers": [

{

"condition": "(!Swagger)",

"exclude": [

"Constants/HomeControllerRoute.cs",

"Controllers/HomeController.cs",

"ViewModelSchemaFilters/**/*"

]

}

]

}

]

}

You do this by adding source modifiers. I’ve added one here with a condition and three file and folder exclusions. The exclusions use a globbing pattern.

What’s Next?

There are several other useful features of the templating engine which I’ll cover in a follow up post as this is starting to get quite long. Feel free to take a look at the source code for my API template to see a full example.

Cleaning Up CSPROJ

.NET, All / 1 comment

18th March 2017

TLDR: I show how to make csproj XML concise and pretty for hand editing.

I used project.json since Beta 7 and got used to hand editing it, I’ve continues that practice with csproj and I think you should too. Recent version of Visual Studio have made a lot of performance improvements but it’s still a lot slower than hand editing a text file.

The NuGet package screen in Visual Studio is achingly slow. Bulk editing takes seconds. I can update NuGet package references, package properties etc. all in one go, rather than visiting multiple disparate UI’s in Visual Studio. Finally, I create new projects by copying and pasting an existing csproj and tweaking it. Much faster than Visual Studio’s New Project dialogue.

Install Project File Tools

The Project File Tools Visual Studio extension gives you intellisense for NuGet packages in the new csproj projects. Unfortunately, due to MSBuild being around for so long and being so complex, intellisense for the rest of the project XML consists of a massive list of possible properties so it becomes less useful than it was in project.json.

dotnet migrate – Wow that’s ugly!

After migrating my project.json projects to csproj using Visual Studio 2017 (You could also use the dotnet migrate command), I found that that the XML generated was pretty ugly and contained superfluous elements you just didn’t need. Here is an example csproj library project straight after migration:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <Description>...</Description>
    <Copyright>Copyright © Muhammad Rehan Saeed. All rights Reserved</Copyright>
    <AssemblyTitle>ASP.NET Core MVC 6 Boilerplate Framework</AssemblyTitle>
    <VersionPrefix>2.2.2</VersionPrefix>
    <Authors>Muhammad Rehan Saeed (RehanSaeed.com)</Authors>
    <TargetFrameworks>netstandard1.6;net461</TargetFrameworks>
    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
    <GenerateDocumentationFile>true</GenerateDocumentationFile>
    <AssemblyName>Boilerplate.AspNetCore</AssemblyName>
    <AssemblyOriginatorKeyFile>../../../Key.snk</AssemblyOriginatorKeyFile>
    <SignAssembly>true</SignAssembly>
    <PublicSign Condition=" '$(OS)' != 'Windows_NT' ">true</PublicSign>
    <PackageId>Boilerplate.AspNetCore</PackageId>
    <PackageTags>ASP.NET;ASP.NET Core;MVC;MVC 6;Boilerplate;Muhammad Rehan Saeed;Framework</PackageTags>
    <PackageReleaseNotes>Updated to ASP.NET Core 1.1.2.</PackageReleaseNotes>
    <PackageIconUrl>https://raw.githubusercontent.com/RehanSaeed/ASP.NET-MVC-Boilerplate/master/Images/Icon.png</PackageIconUrl>
    <PackageProjectUrl>https://github.com/ASP-NET-MVC-Boilerplate/Framework</PackageProjectUrl>
    <PackageLicenseUrl>https://github.com/ASP-NET-MVC-Boilerplate/Framework/blob/master/LICENSE</PackageLicenseUrl>
    <PackageRequireLicenseAcceptance>true</PackageRequireLicenseAcceptance>
    <RepositoryType>git</RepositoryType>
    <RepositoryUrl>https://github.com/ASP-NET-MVC-Boilerplate/Framework.git</RepositoryUrl>
    <GenerateAssemblyConfigurationAttribute>false</GenerateAssemblyConfigurationAttribute>
    <GenerateAssemblyCompanyAttribute>false</GenerateAssemblyCompanyAttribute>
    <GenerateAssemblyProductAttribute>false</GenerateAssemblyProductAttribute>
  </PropertyGroup>
  <ItemGroup>
    <ProjectReference Include="..\Boilerplate\Boilerplate.csproj" />
  </ItemGroup>
  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.Mvc.Abstractions" Version="1.1.2" />
    <PackageReference Include="Microsoft.AspNetCore.Mvc.Core" Version="1.1.2" />
    <PackageReference Include="Microsoft.Extensions.Caching.Abstractions" Version="1.1.1" />
    <PackageReference Include="Microsoft.Extensions.Configuration.Binder" Version="1.1.1" />
    <PackageReference Include="Newtonsoft.Json" Version="9.0.1" />
    <PackageReference Include="StyleCop.Analyzers" Version="1.0.0">
      <PrivateAssets>All</PrivateAssets>
    </PackageReference>
  </ItemGroup>
  <ItemGroup Condition=" '$(TargetFramework)' == 'netstandard1.6' ">
    <PackageReference Include="System.Xml.XDocument" Version="4.3.0" />
  </ItemGroup>
  <ItemGroup Condition=" '$(TargetFramework)' == 'net461' ">
    <Reference Include="System.ServiceModel" />
    <Reference Include="System.Xml" />
    <Reference Include="System.Xml.Linq" />
    <Reference Include="System" />
    <Reference Include="Microsoft.CSharp" />
  </ItemGroup>
</Project>

<AssemblyTitle>ASP.NET Core MVC 6 Boilerplate Framework</AssemblyTitle>

<Authors>Muhammad Rehan Saeed (RehanSaeed.com)</Authors>

<TargetFrameworks>netstandard1.6;net461</TargetFrameworks>

<AssemblyName>Boilerplate.AspNetCore</AssemblyName>

<PackageId>Boilerplate.AspNetCore</PackageId>

<PackageTags>ASP.NET;ASP.NET Core;MVC;MVC 6;Boilerplate;Muhammad Rehan Saeed;Framework</PackageTags>

<PackageReleaseNotes>Updated to ASP.NET Core 1.1.2.</PackageReleaseNotes>

<PackageIconUrl>https://raw.githubusercontent.com/RehanSaeed/ASP.NET-MVC-Boilerplate/master/Images/Icon.png</PackageIconUrl>

<PackageProjectUrl>https://github.com/ASP-NET-MVC-Boilerplate/Framework</PackageProjectUrl>

<PackageLicenseUrl>https://github.com/ASP-NET-MVC-Boilerplate/Framework/blob/master/LICENSE</PackageLicenseUrl>

<RepositoryUrl>https://github.com/ASP-NET-MVC-Boilerplate/Framework.git</RepositoryUrl>

<GenerateAssemblyConfigurationAttribute>false</GenerateAssemblyConfigurationAttribute>

<GenerateAssemblyCompanyAttribute>false</GenerateAssemblyCompanyAttribute>

<GenerateAssemblyProductAttribute>false</GenerateAssemblyProductAttribute>

</PropertyGroup>

</ItemGroup>

</PackageReference>

</ItemGroup>

</ItemGroup>

</ItemGroup>

</Project>

Understanding new csproj Projects

The top of the project contains a new SDK property. This imports some MSBuild targets and props files in your dotnet installation folder shown below:

If you root around in those files, you can find defaults for all kinds of settings. Here are some of the nuggets I discovered about the web projects:

The NETStandard.Library version 1.6.1 NuGet package is referenced for you by default.
The wwwroot folder is excluded from compilation but included in the published output.
web.config, .cshtml and .json files are published by default.
Server garbage collection is turned on by default using the ServerGarbageCollection setting.
PreserveCompilationContext is set to true by default.
node_modules, jspm_packages and bower_components are excluded by default.

AssemblyInfo.cs is Partially Dead

You don’t need AssemblyInfo.cs anymore by default as the csproj Package settings also set many of the assembly attributes. In fact, you didn’t really need it with project.json either but the default templates mostly included it for some reason. However, I still found I needed to resurrect it in some cases to use the InternalsVisibleTo attribute. InternalsVisibleTo allows my unit test projects to access internal members in my library project. After a dotnet migrate, you may see the following elements which stop certain assembly attributes from being generated. You can safely delete these.

<PropertyGroup>
  <!-- ...Omitted -->
  <GenerateAssemblyConfigurationAttribute>false</GenerateAssemblyConfigurationAttribute>
  <GenerateAssemblyCompanyAttribute>false</GenerateAssemblyCompanyAttribute>
  <GenerateAssemblyProductAttribute>false</GenerateAssemblyProductAttribute>
<PropertyGroup>

<GenerateAssemblyConfigurationAttribute>false</GenerateAssemblyConfigurationAttribute>

<GenerateAssemblyCompanyAttribute>false</GenerateAssemblyCompanyAttribute>

<GenerateAssemblyProductAttribute>false</GenerateAssemblyProductAttribute>

Remove System.* References

You no longer need to explicitly reference System.* references in your csproj. David Fowler recommends that you always reference the NETStandard.Library meta NuGet package gives you most System.* references. You get NETStandard.Library by default if you use the SDK attribute at the top of the csproj:

<Project Sdk="Microsoft.NET.Sdk">
  <!-- ...Omitted -->
</Project>

</Project>

This meant that I could remove the entire code block below except System.ServiceModel because that reference is not given to you by the NETStandard.Library NuGet package.

<ItemGroup Condition=" '$(TargetFramework)' == 'netstandard1.6' ">
  <PackageReference Include="System.Xml.XDocument" Version="4.3.0" />
</ItemGroup>
<ItemGroup Condition=" '$(TargetFramework)' == 'net461' ">
  <Reference Include="System.ServiceModel" />
  <Reference Include="System.Xml" />
  <Reference Include="System.Xml.Linq" />
  <Reference Include="System" />
  <Reference Include="Microsoft.CSharp" />
</ItemGroup>

</ItemGroup>

</ItemGroup>

Turn Elements into Attributes

For some reason dotnet migrate produces overly verbose XML in some cases by outputting XML elements instead of attributes. I have a NuGet reference to StyleCop.Analyzers which is a build time dependency and I don’t want it to be output to my bin directory. You do this by setting the PrivateAssets property but you can turn this:

<PackageReference Include="StyleCop.Analyzers" Version="1.0.0">
  <PrivateAssets>All</PrivateAssets>
</PackageReference>

</PackageReference>

Into this:

<PackageReference Include="StyleCop.Analyzers" PrivateAssets="All" Version="1.0.0" />

1	<PackageReference Include="StyleCop.Analyzers" PrivateAssets="All" Version="1.0.0" />

Label your Sections

You can label your PropertyGroup and ItemGroup elements using the Label attribute:

<PropertyGroup Label="Package">
  <!-- NuGet Packages Omitted -->
</PropertyGroup>

</PropertyGroup>

So the question becomes, how should we label them? Well, the convention I use is to use the same label names as the ones in Visual Studio’s project properties screen:

The End Result

This is what my csproj looks like at the end of all that. I’ve removed all the extra fluff you don’t need and labelled the properties in a way that makes navigating the file with yoour eye that much quicker.

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup Label="Build">
    <TargetFrameworks>netstandard1.6;net461</TargetFrameworks>
    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
    <GenerateDocumentationFile>true</GenerateDocumentationFile>
    <CodeAnalysisRuleSet>../../../MinimumRecommendedRulesWithStyleCop.ruleset</CodeAnalysisRuleSet>
  </PropertyGroup>
  <PropertyGroup Label="Package">
    <VersionPrefix>2.2.2</VersionPrefix>
    <Authors>Muhammad Rehan Saeed (RehanSaeed.com)</Authors>
    <Product>ASP.NET Core MVC 6 Boilerplate Framework</Product>
    <Description>...</Description>
    <Copyright>Copyright © Muhammad Rehan Saeed. All rights Reserved</Copyright>
    <PackageRequireLicenseAcceptance>true</PackageRequireLicenseAcceptance>
    <PackageLicenseUrl>https://github.com/ASP-NET-MVC-Boilerplate/Framework/blob/master/LICENSE</PackageLicenseUrl>
    <PackageProjectUrl>https://github.com/ASP-NET-MVC-Boilerplate/Framework</PackageProjectUrl>
    <PackageIconUrl>https://raw.githubusercontent.com/RehanSaeed/ASP.NET-MVC-Boilerplate/master/Images/Icon.png</PackageIconUrl>
    <RepositoryUrl>https://github.com/ASP-NET-MVC-Boilerplate/Framework.git</RepositoryUrl>
    <RepositoryType>git</RepositoryType>
    <PackageTags>ASP.NET;ASP.NET Core;MVC;MVC 6;Boilerplate;Muhammad Rehan Saeed;Framework</PackageTags>
    <PackageReleaseNotes>Updated to ASP.NET Core 1.1.2.</PackageReleaseNotes>
  </PropertyGroup>
  <PropertyGroup Label="Signing">
    <SignAssembly>true</SignAssembly>
    <AssemblyOriginatorKeyFile>../../../Key.snk</AssemblyOriginatorKeyFile>
    <PublicSign Condition=" '$(OS)' != 'Windows_NT' ">true</PublicSign>
  </PropertyGroup>
  <ItemGroup Label="Project References">
    <ProjectReference Include="..\Boilerplate\Boilerplate.csproj" />
  </ItemGroup>
  <ItemGroup Label="Package References">
    <PackageReference Include="Microsoft.AspNetCore.Mvc.Abstractions" Version="1.1.2" />
    <PackageReference Include="Microsoft.AspNetCore.Mvc.Core" Version="1.1.2" />
    <PackageReference Include="Microsoft.Extensions.Caching.Abstractions" Version="1.1.1" />
    <PackageReference Include="Microsoft.Extensions.Configuration.Binder" Version="1.1.1" />
    <PackageReference Include="Newtonsoft.Json" Version="9.0.1" />
    <PackageReference Include="StyleCop.Analyzers" PrivateAssets="All" Version="1.0.0" />
  </ItemGroup>
  <ItemGroup Condition=" '$(TargetFramework)' == 'net461' " Label=".NET 4.6.1 Package References">
    <Reference Include="System.ServiceModel" />
  </ItemGroup>
</Project>

<TargetFrameworks>netstandard1.6;net461</TargetFrameworks>

<CodeAnalysisRuleSet>../../../MinimumRecommendedRulesWithStyleCop.ruleset</CodeAnalysisRuleSet>

</PropertyGroup>

<Authors>Muhammad Rehan Saeed (RehanSaeed.com)</Authors>

<Product>ASP.NET Core MVC 6 Boilerplate Framework</Product>

<PackageLicenseUrl>https://github.com/ASP-NET-MVC-Boilerplate/Framework/blob/master/LICENSE</PackageLicenseUrl>

<PackageProjectUrl>https://github.com/ASP-NET-MVC-Boilerplate/Framework</PackageProjectUrl>

<PackageIconUrl>https://raw.githubusercontent.com/RehanSaeed/ASP.NET-MVC-Boilerplate/master/Images/Icon.png</PackageIconUrl>

<RepositoryUrl>https://github.com/ASP-NET-MVC-Boilerplate/Framework.git</RepositoryUrl>

<PackageTags>ASP.NET;ASP.NET Core;MVC;MVC 6;Boilerplate;Muhammad Rehan Saeed;Framework</PackageTags>

<PackageReleaseNotes>Updated to ASP.NET Core 1.1.2.</PackageReleaseNotes>

</PropertyGroup>

</PropertyGroup>

</ItemGroup>

</ItemGroup>

</ItemGroup>

</Project>

Custom Project Templates Using dotnet new

All, Tools / 11 comments

18th January 2017

Current dotnet new

If you run dotnet new today, you can create a simple console app. The command has very few options, including selecting the language you want to use (C#, VB or F#). However, this is all about to change. Sayed I. Hashimi and Mike Lorbetske who work at Microsoft in the .NET tooling team have been kind enough to show me what they’ve been working on with the intention of getting some feedback.

dotnet new3

Microsoft is working on a new version of the dotnet new command with support for installing custom project templates from NuGet packages, zip files or folders. If you head over to the dotnet/templating GitHub repository you can follow the very simple instructions and try out a fairly complete version of this command which is temporarily called ‘dotnet new3’. The full ‘dotnet new’ experience is due to be released in conjunction with Visual Studio 2017.

If you take a look at the screenshot above, you’ll notice that there are a lot more options available. You can list all installed project templates and install new ones too.

Creating New Templates

Creating a new project template involves taking a folder containing your project (Mine is called Api-CSharp) and adding a .template.config folder to it containing two files.

Template Metadata

The template.json file is where you specify metadata about your project template. This metadata is displayed when someone lists their installed project templates. A really basic one looks like this:

{
  "author": "Muhammad Rehan Saeed (RehanSaeed.com)",
  "classifications": [ "WebAPI", "Boilerplate" ], // Tags used to search for the template.
  "name": "ASP.NET MVC Boilerplate API",
  "identity": "Boilerplate.Api.CSharp",   // A unique ID for the project template.
  "shortName": "webapib",                 // You can create the project using this short name instead of the one above.
  "tags": {
    "language": "C#"                      // Specify that this template is in C#.
  },
  "sourceName": "ApiTemplate",            // Name of the csproj file and namespace that will be replaced.
  "guids": [                              // Guids used in the project that will be replaced by new ones.
    "837bc53e-0271-4e9c-b5b5-c60ea7a7c7b5",
    "113f2d04-69f0-40c3-8797-ba3f356dd812"
  ],
}

{

"author": "Muhammad Rehan Saeed (RehanSaeed.com)",

"classifications": [ "WebAPI", "Boilerplate" ], // Tags used to search for the template.

"name": "ASP.NET MVC Boilerplate API",

"identity": "Boilerplate.Api.CSharp", // A unique ID for the project template.

"shortName": "webapib", // You can create the project using this short name instead of the one above.

"tags": {

"language": "C#" // Specify that this template is in C#.

"sourceName": "ApiTemplate", // Name of the csproj file and namespace that will be replaced.

"guids": [ // Guids used in the project that will be replaced by new ones.

"837bc53e-0271-4e9c-b5b5-c60ea7a7c7b5",

"113f2d04-69f0-40c3-8797-ba3f356dd812"

}

The templating repositories Wiki page talks about what all of the properties mean in a lot more detail but I’ve added some basic comments for your understanding.

Installing Templates

Installing the above template from a folder is as easy as using the install command. You can also install templates from zip files and NuGet packages the same way.

Template NuGet Packages

So how do you create a NuGet package containing a project template thats compatible with dotnet new? I’m assuming you are familiar with creating NuGet packages, if not take a look at the NuGet documentation. You can create NuGet packages of your project templates by creating a Templates.nuspec file like the one below and placing all of your templates in a content folder beside it. The content folder is a special folder which NuGet understands to contain static files. If you look at the nuspec file below, you’ll notice the packageType element. This is a new way to tell NuGet that this NuGet package contains project templates.

<?xml version="1.0" encoding="utf-8"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
  <metadata>
    <id>Boilerplate.Templates</id>
    <version>1.0.0</version>
    <description>My project description.</description>
    <authors>Muhammad Rehan Saeed (RehanSaeed.com)</authors>
    <packageTypes>
      <packageType name="Template" />
    </packageTypes>
  </metadata>
</package>

<?xml version="1.0" encoding="utf-8"?>

<id>Boilerplate.Templates</id>

<description>My project description.</description>

<authors>Muhammad Rehan Saeed (RehanSaeed.com)</authors>

</packageTypes>

</metadata>

</package>

There is More!

What I’ve not told you is that it’s possible to add features to your project template that developers can turn on or off based on command line switches a bit like Yeoman does for Node based NPM packages. As many of you will know I already do this in my ASP.NET MVC Boilerplate project template but I came up with my own custom method. dotnet new makes this all a lot easier and I’ll cover how to do this in a later blog post.

Why This is Better

Traditionally, to create project templates, you could use Visual Studio to create zip files containing your project template or if you were brave you could create Visual Studio extensions (VSIX) to enable installing them directly into Visual Studio and share them on the Visual Studio Marketplace.

This new method makes creating project templates about as easy as it’s ever going to get and allows really easy sharing, versioning and personalization of project templates. At some point I envisage a website (Possible the Visual Studio Marketplace) where you could go and install these NuGet based project templates.

ASP.NET Core Boilerplate API

I’ve been working on a brand new project template for building API’s using dotnet new with a lot of help from the guys at Microsoft. My project templates are quite complex so it’s a good test of the system. The API comes jam packed full of security, performance and best practice features and also implements Swagger right out of the box. It’s still in alpha quality but you can try installing it with dotnet new3 from MyGet and soon NuGet when I get a chance to polish it up a little more.

Conclusions

Overall I’m really impressed with where the new project templating system is headed. It’s very easy to do something simple but also very powerful should you need to do something complicated. There is a few blog posts worth of material here, so expect a few more posts in the coming weeks.

Reactive Extensions (Rx) – Part 8 – Timeouts

All, Reactive Extensions (Rx), Task Parallel Library (TPL) / 1 comment

2nd January 2017

In part six of this series of blog posts I talked about using Reactive Extensions for adding timeout logic to asynchronous tasks. Something like this:

public async Task<string> WaitForFirstResultWithTimeOut()
{
    Task<string> task = this.DownloadTheInternet();
    return await task
        .ToObservable()
        .Timeout(TimeSpan.FromMilliseconds(1000))
        .FirstAsync();
}

public async Task<string> WaitForFirstResultWithTimeOut()

{

Task<string> task = this.DownloadTheInternet();

return await task

.ToObservable()

.Timeout(TimeSpan.FromMilliseconds(1000))

.FirstAsync();

}

Last week I was working on a project and wanted to add a Timeout to my task but since it was an ASP.NET MVC project, I had no references to Reactive Extensions. After some thought I discovered another possible method of performing a timeout which may help in certain circumstances.

var cancellationTokenSource = new CancellationTokenSource(TimeSpan.FromMilliseconds(1000));
try
{
    return await this.DownloadTheInternet(cancellationTokenSource.Token);
}
catch (OperationCanceledException exception)
{
    Console.WriteLine("Timed Out");
}

var cancellationTokenSource = new CancellationTokenSource(TimeSpan.FromMilliseconds(1000));

try

{

return await this.DownloadTheInternet(cancellationTokenSource.Token);

}

catch (OperationCanceledException exception)

{

Console.WriteLine("Timed Out");

}

I’m using an overload on CancellationTokenSource which takes a timeout value. Then passing the CancellationToken to DownloadTheInternet. This method should be periodically checking the CancellationToken to see if it has been cancelled and if so, throw an OperationCanceledException. In this example you’d probably use HttpClient which handles this for you if you give it the CancellationToken.

The main reason why this method is better is that the task is actually being cancelled and stopped from doing any more work. In my above reactive extensions example, the task continues doing work but it’s result is just ignored.

SEO Friendly URL’s for ASP.NET Core

All, ASP.NET MVC / 7 comments

17th December 2016

For some reason there are not a lot of Search Engine Optimization (SEO) blog posts or projects out there. Taking a few simple steps can make your site rank higher in Google or Bing search results so it’s well worth doing. Here are a few other of my SEO related blog posts:

What is an SEO Friendly URL?

This Mozilla blog post called ‘15 best practices for structuring URL’s’ is the best article on the subject of SEO friendly URL’s I found and it’s well worth a read.

Essentially you want a simple short URL that tells the user what they are clicking on at a glance. It should also contain keywords pertaining to what is on the page for better Search Engine Optimization (SEO). In short, a page will appear higher up in search results if the term a user searches for appears in the URL. Your URL should look like this:

The URL contains an ID for a product and ends with a friendly title. The title contains alphanumeric characters with dashes instead of spaces. Note that the ID of the product is still included in the URL, to avoid having to deal with two friendly titles with the same name.

If you elect to omit the ID, then you have to do a lot of footwork to make things work. Firstly, you have to use the title as a kind of primary key to get the product data from your database and secondly, you also have to figure out what to do when there are two pages with the same title. Each time you want to create a new title, you have to scan your data store to see if the title already exists and if it does either error and force the creation of a different title or add make it unique by adding a number on the end. This is a lot of work but does produce a nicer URL, the choice is yours.

How to Build One

Take a look at the controller action below. It is a very simple example of how to use SEO friendly URL’s. In our example we have a product class which has a ID and title properties, where the title is just the name of the product.

[HttpGet("product/{id}/{title}", Name = "GetProduct")]
public IActionResult GetProduct(int id, string title)
{
    // Get the product as indicated by the ID from a database or some repository.
    var product = this.productRepository.Find(id);
    // If a product with the specified ID was not found, return a 404 Not Found response.
    if (product == null)
    {
        return this.NotFound();
    }
    // Get the actual friendly version of the title.
    string friendlyTitle = FriendlyUrlHelper.GetFriendlyTitle(product.Title);
    // Compare the title with the friendly title.
    if (!string.Equals(friendlyTitle, title, StringComparison.Ordinal))
    {
        // If the title is null, empty or does not match the friendly title, return a 301 Permanent
        // Redirect to the correct friendly URL.
        return this.RedirectToRoutePermanent("GetProduct", new { id = id, title = friendlyTitle });
    }
    // The URL the client has browsed to is correct, show them the view containing the product.
    return this.View(product);
}

[HttpGet("product/{id}/{title}", Name = "GetProduct")]

public IActionResult GetProduct(int id, string title)

{

// Get the product as indicated by the ID from a database or some repository.

var product = this.productRepository.Find(id);

// If a product with the specified ID was not found, return a 404 Not Found response.

if (product == null)

{

return this.NotFound();

}

// Get the actual friendly version of the title.

string friendlyTitle = FriendlyUrlHelper.GetFriendlyTitle(product.Title);

// Compare the title with the friendly title.

if (!string.Equals(friendlyTitle, title, StringComparison.Ordinal))

{

// If the title is null, empty or does not match the friendly title, return a 301 Permanent

// Redirect to the correct friendly URL.

return this.RedirectToRoutePermanent("GetProduct", new { id = id, title = friendlyTitle });

}

// The URL the client has browsed to is correct, show them the view containing the product.

return this.View(product);

}

All the work is done by the FriendlyUrlHelper which turns the product title which may contain spaces, numbers or other special characters (which would not be allowed in a URL without escaping them) into a lower-kebab-case title.

This generated friendly title is compared with the one that is passed in and if it is different (Someone may have omitted the friendly title or mis-spelled it) we perform a permanent redirect to the product with the same ID but now with the friendly title. This is important for SEO purposes, we want search engines to only find one URL for each product. Finally, if the friendly title matches the one passed in we return the product view.

The FriendlyUrlHelper

The FriendlyUrlHelper was inspired by a famous StackOverflow question ‘How does Stack Overflow generate its SEO-friendly URLs?‘. The full source code for it is shown below.

/// <summary>
/// Helps convert <see cref="string"/> title text to URL friendly <see cref="string"/>'s that can safely be
/// displayed in a URL.
/// </summary>
public static class FriendlyUrlHelper
{
    /// <summary>
    /// Converts the specified title so that it is more human and search engine readable e.g.
    /// http://example.com/product/123/this-is-the-seo-and-human-friendly-product-title. Note that the ID of the
    /// product is still included in the URL, to avoid having to deal with two titles with the same name. Search
    /// Engine Optimization (SEO) friendly URL's gives your site a boost in search rankings by including keywords
    /// in your URL's. They are also easier to read by users and can give them an indication of what they are
    /// clicking on when they look at a URL. Refer to the code example below to see how this helper can be used.
    /// Go to definition on this method to see a code example. To learn more about friendly URL's see
    /// https://moz.com/blog/15-seo-best-practices-for-structuring-urls.
    /// To learn more about how this was implemented see
    /// http://stackoverflow.com/questions/25259/how-does-stack-overflow-generate-its-seo-friendly-urls/25486#25486
    /// </summary>
    /// <param name="title">The title of the URL.</param>
    /// <param name="remapToAscii">if set to <c>true</c>, remaps special UTF8 characters like 'è' to their ASCII
    /// equivalent 'e'. All modern browsers except Internet Explorer display the 'è' correctly. Older browsers and
    /// Internet Explorer percent encode these international characters so they are displayed as'%C3%A8'. What you
    /// set this to depends on whether your target users are English speakers or not.</param>
    /// <param name="maxlength">The maximum allowed length of the title.</param>
    /// <returns>The SEO and human friendly title.</returns>
    /// <code>
    /// [HttpGet("product/{id}/{title}", Name = "GetDetails")]
    /// public IActionResult Product(int id, string title)
    /// {
    ///     // Get the product as indicated by the ID from a database or some repository.
    ///     var product = ProductRepository.Find(id);
    ///
    ///     // If a product with the specified ID was not found, return a 404 Not Found response.
    ///     if (product == null)
    ///     {
    ///         return this.HttpNotFound();
    ///     }
    ///
    ///     // Get the actual friendly version of the title.
    ///     var friendlyTitle = FriendlyUrlHelper.GetFriendlyTitle(product.Title);
    ///
    ///     // Compare the title with the friendly title.
    ///     if (!string.Equals(friendlyTitle, title, StringComparison.Ordinal))
    ///     {
    ///         // If the title is null, empty or does not match the friendly title, return a 301 Permanent
    ///         // Redirect to the correct friendly URL.
    ///         return this.RedirectToRoutePermanent("GetProduct", new { id = id, title = friendlyTitle });
    ///     }
    ///
    ///     // The URL the client has browsed to is correct, show them the view containing the product.
    ///     return this.View(product);
    /// }
    /// </code>
    public static string GetFriendlyTitle(string title, bool remapToAscii = false, int maxlength = 80)
    {
        if (title == null)
        {
            return string.Empty;
        }
        int length = title.Length;
        bool prevdash = false;
        StringBuilder stringBuilder = new StringBuilder(length);
        char c;
        for (int i = 0; i < length; ++i)
        {
            c = title[i];
            if ((c >= 'a' && c <= 'z') || (c >= '0' && c <= '9'))
            {
                stringBuilder.Append(c);
                prevdash = false;
            }
            else if (c >= 'A' && c <= 'Z')
            {
                // tricky way to convert to lower-case
                stringBuilder.Append((char)(c | 32));
                prevdash = false;
            }
            else if ((c == ' ') || (c == ',') || (c == '.') || (c == '/') ||
                (c == '\\') || (c == '-') || (c == '_') || (c == '='))
            {
                if (!prevdash && (stringBuilder.Length > 0))
                {
                    stringBuilder.Append('-');
                    prevdash = true;
                }
            }
            else if (c >= 128)
            {
                int previousLength = stringBuilder.Length;
                if (remapToAscii)
                {
                    stringBuilder.Append(RemapInternationalCharToAscii(c));
                }
                else
                {
                    stringBuilder.Append(c);
                }
                if (previousLength != stringBuilder.Length)
                {
                    prevdash = false;
                }
            }
            if (i == maxlength)
            {
                break;
            }
        }
        if (prevdash)
        {
            return stringBuilder.ToString().Substring(0, stringBuilder.Length - 1);
        }
        else
        {
            return stringBuilder.ToString();
        }
    }
    /// <summary>
    /// Remaps the international character to their equivalent ASCII characters. See
    /// http://meta.stackexchange.com/questions/7435/non-us-ascii-characters-dropped-from-full-profile-url/7696#7696
    /// </summary>
    /// <param name="character">The character to remap to its ASCII equivalent.</param>
    /// <returns>The remapped character</returns>
    private static string RemapInternationalCharToAscii(char character)
    {
        string s = character.ToString().ToLowerInvariant();
        if ("àåáâäãåąā".Contains(s))
        {
            return "a";
        }
        else if ("èéêëę".Contains(s))
        {
            return "e";
        }
        else if ("ìíîïı".Contains(s))
        {
            return "i";
        }
        else if ("òóôõöøőð".Contains(s))
        {
            return "o";
        }
        else if ("ùúûüŭů".Contains(s))
        {
            return "u";
        }
        else if ("çćčĉ".Contains(s))
        {
            return "c";
        }
        else if ("żźž".Contains(s))
        {
            return "z";
        }
        else if ("śşšŝ".Contains(s))
        {
            return "s";
        }
        else if ("ñń".Contains(s))
        {
            return "n";
        }
        else if ("ýÿ".Contains(s))
        {
            return "y";
        }
        else if ("ğĝ".Contains(s))
        {
            return "g";
        }
        else if (character == 'ř')
        {
            return "r";
        }
        else if (character == 'ł')
        {
            return "l";
        }
        else if (character == 'đ')
        {
            return "d";
        }
        else if (character == 'ß')
        {
            return "ss";
        }
        else if (character == 'Þ')
        {
            return "th";
        }
        else if (character == 'ĥ')
        {
            return "h";
        }
        else if (character == 'ĵ')
        {
            return "j";
        }
        else
        {
            return string.Empty;
        }
    }
}

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

119

120

121

122

123

124

125

126

127

128

129

130

131

132

133

134

135

136

137

138

139

140

141

142

143

144

145

146

147

148

149

150

151

152

153

154

155

156

157

158

159

160

161

162

163

164

165

166

167

168

169

170

171

172

173

174

175

176

177

178

179

180

181

182

183

184

185

186

187

188

189

190

191

192

193

194

195

196

197

198

199

200

201

202

203

204

205

206

207

208

209

210

/// <summary>

/// Helps convert <see cref="string"/> title text to URL friendly <see cref="string"/>'s that can safely be

/// displayed in a URL.

/// </summary>

public static class FriendlyUrlHelper

{

/// <summary>

/// Converts the specified title so that it is more human and search engine readable e.g.

/// http://example.com/product/123/this-is-the-seo-and-human-friendly-product-title. Note that the ID of the

/// product is still included in the URL, to avoid having to deal with two titles with the same name. Search

/// Engine Optimization (SEO) friendly URL's gives your site a boost in search rankings by including keywords

/// in your URL's. They are also easier to read by users and can give them an indication of what they are

/// clicking on when they look at a URL. Refer to the code example below to see how this helper can be used.

/// Go to definition on this method to see a code example. To learn more about friendly URL's see

/// https://moz.com/blog/15-seo-best-practices-for-structuring-urls.

/// To learn more about how this was implemented see

/// http://stackoverflow.com/questions/25259/how-does-stack-overflow-generate-its-seo-friendly-urls/25486#25486

/// </summary>

/// <param name="title">The title of the URL.</param>

/// <param name="remapToAscii">if set to <c>true</c>, remaps special UTF8 characters like 'è' to their ASCII

/// equivalent 'e'. All modern browsers except Internet Explorer display the 'è' correctly. Older browsers and

/// Internet Explorer percent encode these international characters so they are displayed as'%C3%A8'. What you

/// set this to depends on whether your target users are English speakers or not.</param>

/// <param name="maxlength">The maximum allowed length of the title.</param>

/// <returns>The SEO and human friendly title.</returns>

/// <code>

/// [HttpGet("product/{id}/{title}", Name = "GetDetails")]

/// public IActionResult Product(int id, string title)

/// {

/// // Get the product as indicated by the ID from a database or some repository.

/// var product = ProductRepository.Find(id);

///

/// // If a product with the specified ID was not found, return a 404 Not Found response.

/// if (product == null)

/// {

/// return this.HttpNotFound();

/// }

///

/// // Get the actual friendly version of the title.

/// var friendlyTitle = FriendlyUrlHelper.GetFriendlyTitle(product.Title);

///

/// // Compare the title with the friendly title.

/// if (!string.Equals(friendlyTitle, title, StringComparison.Ordinal))

/// {

/// // If the title is null, empty or does not match the friendly title, return a 301 Permanent

/// // Redirect to the correct friendly URL.

/// return this.RedirectToRoutePermanent("GetProduct", new { id = id, title = friendlyTitle });

/// }

///

/// // The URL the client has browsed to is correct, show them the view containing the product.

/// return this.View(product);

/// }

/// </code>

public static string GetFriendlyTitle(string title, bool remapToAscii = false, int maxlength = 80)

{

if (title == null)

{

return string.Empty;

}

int length = title.Length;

bool prevdash = false;

StringBuilder stringBuilder = new StringBuilder(length);

char c;

for (int i = 0; i < length; ++i)

{

c = title[i];

if ((c >= 'a' && c <= 'z') || (c >= '0' && c <= '9'))

{

stringBuilder.Append(c);

prevdash = false;

}

else if (c >= 'A' && c <= 'Z')

{

// tricky way to convert to lower-case

stringBuilder.Append((char)(c | 32));

prevdash = false;

}

else if ((c == ' ') || (c == ',') || (c == '.') || (c == '/') ||

(c == '\\') || (c == '-') || (c == '_') || (c == '='))

{

if (!prevdash && (stringBuilder.Length > 0))

{

stringBuilder.Append('-');

prevdash = true;

}

else if (c >= 128)

{

int previousLength = stringBuilder.Length;

if (remapToAscii)

{

stringBuilder.Append(RemapInternationalCharToAscii(c));

}

else

{

stringBuilder.Append(c);

}

if (previousLength != stringBuilder.Length)

{

prevdash = false;

}

if (i == maxlength)

{

break;

}

if (prevdash)

{

return stringBuilder.ToString().Substring(0, stringBuilder.Length - 1);

}

else

{

return stringBuilder.ToString();

}

/// <summary>

/// Remaps the international character to their equivalent ASCII characters. See

/// http://meta.stackexchange.com/questions/7435/non-us-ascii-characters-dropped-from-full-profile-url/7696#7696

/// </summary>

/// <param name="character">The character to remap to its ASCII equivalent.</param>

/// <returns>The remapped character</returns>

private static string RemapInternationalCharToAscii(char character)

{

string s = character.ToString().ToLowerInvariant();

if ("àåáâäãåąā".Contains(s))

{

return "a";

}

else if ("èéêëę".Contains(s))

{

return "e";

}

else if ("ìíîïı".Contains(s))

{

return "i";

}

else if ("òóôõöøőð".Contains(s))

{

return "o";

}

else if ("ùúûüŭů".Contains(s))

{

return "u";

}

else if ("çćčĉ".Contains(s))

{

return "c";

}

else if ("żźž".Contains(s))

{

return "z";

}

else if ("śşšŝ".Contains(s))

{

return "s";

}

else if ("ñń".Contains(s))

{

return "n";

}

else if ("ýÿ".Contains(s))

{

return "y";

}

else if ("ğĝ".Contains(s))

{

return "g";

}

else if (character == 'ř')

{

return "r";

}

else if (character == 'ł')

{

return "l";

}

else if (character == 'đ')

{

return "d";

}

else if (character == 'ß')

{

return "ss";

}

else if (character == 'Þ')

{

return "th";

}

else if (character == 'ĥ')

{

return "h";

}

else if (character == 'ĵ')

{

return "j";

}

else

{

return string.Empty;

}

The difference between my version and the one in the StackOverflow answer is that mine optionally handles non-ASCII characters using the boolean remapToAscii parameter. This parameter remaps special UTF8 characters like ‘è’ to their ASCII equivalent ‘e’. If there is no equivelant, then those characters are dropped. All modern browsers except Internet Explorer and Edge display the ‘è’ correctly. Older browsers like Internet Explorer percent encode these international characters so they are displayed as’%C3%A8′. What you set this to depends on whether your target users are English speakers and if you care about supporting IE and Edge. I must say that I was hoping Edge would have added support so that remapToAscii could be turned off by default but I’m sorely dissapointed.

Using the third parameter you can specify a maximum length for the title with any additional characters being dropped. Finally, the last thing to say about this method is that it has been tuned for speed.

Where Can I Get It?

This is a great little snippet of code to make your URL’s a human readable, while giving your site an SEO boost. It doesn’t take much effort to use either. This helper class is available in the Boilerplate.AspNetCore NuGet package or you can look at the source code in the ASP.NET MVC Boilerplate Framework GitHub page.

Making Application Insights Fast & Secure

All, ASP.NET MVC / 0 comments

11th December 2016

What is Application Insights?

It’s an application monitoring tool available on Microsoft’s Azure cloud that you can use to detect errors and usage in your application. For ASP.NET Core apps, it can do this for both your C# and JavaScript code. It’s main competitors are New Relic and RayGun.

Implementing Application Insights

Following the Getting Started guide for ASP.NET Core applications requires you to add the following HTML helper to your _Layout.cshtml file:

<head>
    @* ...Omitted *@
    @Html.ApplicationInsightsJavaScript(TelemetryConfiguration)
</head>

<head>

@* ...Omitted *@

@Html.ApplicationInsightsJavaScript(TelemetryConfiguration)

</head>

This HTML helper adds an inline script containing the minified JavaScript in snippet.js.

<script type="text/javascript">
        var appInsights=window.appInsights||function(config){{
            function i(config){{t[config]=function(){{var i=arguments;t.queue.push(function(){{t[config].apply(t,i)}})}}}}var t={{config:config}},u=document,e=window,o="script",s="AuthenticatedUserContext",h="start",c="stop",l="Track",a=l+"Event",v=l+"Page",y=u.createElement(o),r,f;y.src=config.url||"https://az416426.vo.msecnd.net/scripts/a/ai.0.js";u.getElementsByTagName(o)[0].parentNode.appendChild(y);try{{t.cookie=u.cookie}}catch(p){{}}for(t.queue=[],t.version="1.0",r=["Event","Exception","Metric","PageView","Trace","Dependency"];r.length;)i("track"+r.pop());return i("set"+s),i("clear"+s),i(h+a),i(c+a),i(h+v),i(c+v),i("flush"),config.disableExceptionTracking||(r="onerror",i("_"+r),f=e[r],e[r]=function(config,i,u,e,o){{var s=f&amp;&amp;f(config,i,u,e,o);return s!==!0&amp;&amp;t["_"+r](config,i,u,e,o),s}}),t
        }}({{
            instrumentationKey: '{0}'
        }});
        window.appInsights=appInsights;
        appInsights.trackPageView();
</script>

var appInsights=window.appInsights||function(config){{

}}({{

instrumentationKey: '{0}'

}});

window.appInsights=appInsights;

appInsights.trackPageView();

</script>

This script is responsible for:

Containing the users instrumentation key (The HTML helper adds this for you).
Downloading the full application insights script asynchronously which actually does all the work.
Recording any logs that occur while the full script is downloaded

The Problem

For most websites, this is fine and you can stop here. Here is what can be improved for the rest:

The above adds 1KB to every HTML page. Moving this script into a separate file would mean that this script could be cached in the browser the first time it was downloaded. A separate file could also be dirstributed to a CDN and globally distributed very quickly.
If you are using a Content Security Policy (CSP) to secure your site using inline scripts in your site is a big no no. You could use a nonce (A nonce means you can’t cache the page as each page becomes unique) or even better a hash of the script contents but browser support for CSP 2.0 is not great. Using an external script would be the simplest option.

Making It Slightly Faster and More Secure

So what does it take to move the above snippet.js file into a separate file? Well, it turns out that you can get snippet.js from the applicationinsights-js NPM package which you can add to your package.json like so:

{
  "dependencies": {
    "applicationinsights-js": "1.0.5"
    // ...
  }
  // ...
}

{

"dependencies": {

"applicationinsights-js": "1.0.5"

// ...

}

// ...

}

The next step is to inject your instrumentation key into snippet.js and also the URL to the full application insights script which is missing from the snippet.js file in the NPM package. I do this using a gulp task like so:

var gulp = require('gulp'),
    sourcemaps = require('gulp-sourcemaps'),    // Creates source map files (https://www.npmjs.com/package/gulp-sourcemaps/)
    replace = require('gulp-replace-task'),     // String replace (https://www.npmjs.com/package/gulp-replace-task/)
    uglify = require('gulp-uglify');            // Minifies JavaScript (https://www.npmjs.com/package/gulp-uglify/)
gulp.task('build-app-insights-js',
    function() {
        return gulp
            .src('./node_modules/ApplicationInsights-JS/JavaScript/JavaScriptSDK/snippet.js')
            .pipe(sourcemaps.init())               // Set up the generation of .map source files for the JavaScript.
            .pipe(
                replace({                          // Carry out the specified find and replace.
                    patterns: [
                        {
                            // match - The string or regular expression to find.
                            match: 'CDN_PATH',
                            // replacement - The string or function used to make the replacement.
                            replacement: 'https://az416426.vo.msecnd.net/scripts/a/ai.0.js'
                        },
                        {
                           match: 'INSTRUMENTATION_KEY',
                           replacement: '11111111-2222-3333-4444-555555555555'
                        }
                    ],
                    usePrefix: false
                }))
            .pipe(uglify())                        // Minifies the JavaScript.
            .pipe(sourcemaps.write('.'))           // Generates source .map files for the JavaScript.
            .pipe(gulp.dest('./wwwroot/js/'));     // Saves the JavaScript file to the specified destination path.
});

var gulp = require('gulp'),

sourcemaps = require('gulp-sourcemaps'), // Creates source map files (https://www.npmjs.com/package/gulp-sourcemaps/)

replace = require('gulp-replace-task'), // String replace (https://www.npmjs.com/package/gulp-replace-task/)

uglify = require('gulp-uglify'); // Minifies JavaScript (https://www.npmjs.com/package/gulp-uglify/)

gulp.task('build-app-insights-js',

function() {

return gulp

.src('./node_modules/ApplicationInsights-JS/JavaScript/JavaScriptSDK/snippet.js')

.pipe(sourcemaps.init()) // Set up the generation of .map source files for the JavaScript.

.pipe(

replace({ // Carry out the specified find and replace.

patterns: [

{

// match - The string or regular expression to find.

match: 'CDN_PATH',

// replacement - The string or function used to make the replacement.

replacement: 'https://az416426.vo.msecnd.net/scripts/a/ai.0.js'

{

match: 'INSTRUMENTATION_KEY',

replacement: '11111111-2222-3333-4444-555555555555'

}

usePrefix: false

}))

.pipe(uglify()) // Minifies the JavaScript.

.pipe(sourcemaps.write('.')) // Generates source .map files for the JavaScript.

.pipe(gulp.dest('./wwwroot/js/')); // Saves the JavaScript file to the specified destination path.

});

Finally we can include the script in our HTML. Don’t forget to include the cross0rigin attribute on all your script tags, which allows full stack traces to be reported. You can read more about the crossorigin attribute here.

<script asp-append-version="true"
        crossorigin="anonymous"
        src="~/js/application-insights.js"></script>

crossorigin="anonymous"

src="~/js/application-insights.js"></script>

Conclusion

As usual, all of the above is built in to the ASP.NET MVC Boilerplate project template, available as a Visual Studio extension if you select the optional Application Insights feature.

The Dotnet Watch Tool

All, ASP.NET MVC / 13 comments

10th September 2016

The ‘dotnet watch’ tool is a file watcher for dotnet that restarts the application when changes in the source code are detected. If you are using IIS Express then, it actually does this restart for you already. The ‘dotnet watch’ tool is only really useful if you like to run your app in the console. I personally like to do this over using IIS Express because I can see all my logs flashing by in the console like the movies which is occasionally useful if you get an exception.

In both cases you have to be careful to start the application by clicking Debug -> Start Without Debugging or hitting the CTRL+F5 keyboard shortcut.

project.json

Setting up the ‘dotnet watch’ tool is as easy as installing the Microsoft.DotNet.Watcher.Tools NuGet package into the tools section of your project.json file like so (You may need to manually restore packages as there is a bug in the tooling which doesn’t restore packages if you only change the ‘tools’ section):

{
  ...
  "tools": {
    "Microsoft.DotNet.Watcher.Tools": "1.0.0-preview2-final"
    ...
  },
  ...
}

{

...

"tools": {

"Microsoft.DotNet.Watcher.Tools": "1.0.0-preview2-final"

...

}

Now using powershell, you can navigate to your project folder and run the ‘dotnet watch run’ command and your set. But using the command line is a bit lame if you are using Visual Studio, we can do one better.

launchSettings.json

The launchSettings.json file is used by Visual Studio to launch your application and controls what happens when you hi F5. It turns out you can add additional launch settings here to launch the application using the ‘dotnet watch’ tool. You can do so by adding a new launch configuration as I’ve done at the bottom of this file:

{
  "iisSettings": {
    "windowsAuthentication": false,
    "anonymousAuthentication": true,
    "iisExpress": {
      "applicationUrl": "http://localhost:8080/",
      "sslPort": 44300
    }
  },
  "profiles": {
    // Run the app using IIS Express. Use CTRL+F5 or Debug -> Start Without Debugging to edit code and refresh the browser
    // to see your changes while the app is running.
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "launchUrl": "https://localhost:44300/",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    // Run the app in console mode using 'dotnet run'.
    "dotnet run": {
      "commandName": "Project",
      "commandLineArgs": "--server.urls http://*:8080",
      "launchBrowser": true,
      "launchUrl": "http://localhost:8080/",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    // Use CTRL+F5 or Debug -> Start Without Debugging to use this launch profile. Launches the app using 'dotnet watch',
    // which allows you to edit code and refresh the browser to see your changes while the app is running.
    "dotnet watch": {
      "executablePath": "C:\\Program Files\\dotnet\\dotnet.exe",
      "commandLineArgs": "watch run --server.urls http://*:8080",
      "launchBrowser": true,
      "launchUrl": "http://localhost:8080/",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  }
}

{

"iisSettings": {

"windowsAuthentication": false,

"anonymousAuthentication": true,

"iisExpress": {

"applicationUrl": "http://localhost:8080/",

"sslPort": 44300

}

"profiles": {

// Run the app using IIS Express. Use CTRL+F5 or Debug -> Start Without Debugging to edit code and refresh the browser

// to see your changes while the app is running.

"IIS Express": {

"commandName": "IISExpress",

"launchBrowser": true,

"launchUrl": "https://localhost:44300/",

"environmentVariables": {

"ASPNETCORE_ENVIRONMENT": "Development"

}

// Run the app in console mode using 'dotnet run'.

"dotnet run": {

"commandName": "Project",

"commandLineArgs": "--server.urls http://*:8080",

"launchBrowser": true,

"launchUrl": "http://localhost:8080/",

"environmentVariables": {

"ASPNETCORE_ENVIRONMENT": "Development"

}

// Use CTRL+F5 or Debug -> Start Without Debugging to use this launch profile. Launches the app using 'dotnet watch',

// which allows you to edit code and refresh the browser to see your changes while the app is running.

"dotnet watch": {

"executablePath": "C:\\Program Files\\dotnet\\dotnet.exe",

"commandLineArgs": "watch run --server.urls http://*:8080",

"launchBrowser": true,

"launchUrl": "http://localhost:8080/",

"environmentVariables": {

"ASPNETCORE_ENVIRONMENT": "Development"

}

Notice that I renamed the second launch profile (which already exists in the default template) to ‘dotnet run’ because that’s actually the command it’s running and makes more sense.

The ‘dotnet watch’ launch profile is running ‘dotnet watch run’ but it’s also passing in the server.urls argument which lets us override the port number. Now we can see the new launch profile in the Visual Studio toolbar like so:

ASP.NET MVC Boilerplate

If you read my blog posts, you’ll be seeing a trend by now. I built the above feature into the ASP.NET MVC Boilerplate project template by default so you can create a new project with this feature built-in, right out of the box. Happy coding!

Social TagHelpers for ASP.NET Core

All, ASP.NET MVC / 0 comments

19th March 2016

Social media websites like Facebook, Twitter, Google+, Pintrest etc. provide ways to enhance the experience of sharing a page from your site through the use of meta tags. These provide metadata about what is on your page in a standardized format that these sites can use to better display your content. Here are two quick examples of the enhanced content that Twitter and Facebook display when you add these meta tags to your page:

It turns out that most of the social media sites use only two standard sets of meta tags, namely Open Graph (Facebook) and Twitter Cards. I have built ASP.NET Core TagHelpers and ASP.NET 4.6 HTML Helpers which make it easy to add these meta tags to your site.

Author Meta Tag

This is nothing to do with social media meta tags but worth mentioning. The author meta tag has been around for many years and is a standard but very basic way of telling search engines and others, who authored your page. It’s unclear where if anywhere this tag is used but as it’s a standard I like to put it in anyway as it doesn’t hurt to do so.

<meta name="author" content="Muhammad Rehan Saeed">

1	<meta name="author" content="Muhammad Rehan Saeed">

Open Graph (Facebook)

Open Graph is an open standard (it’s set by Facebook and doesn’t seem so open to me as I’ll explain), containing several sets of meta tags which represent various things, such as:

Website
Music Album
Music Song
Music Playlist

Video Movie
Video Episode
Video TV Show
Video Other

Article
Book
Profile

Here is an example of what the meta tags for a page looks like for the ‘Website’ set. Note the ‘type’ tag which determines the name of the set used:

<meta property="og:type" content="website">
<meta property="og:title" content="ASP.NET MVC Boilerplate">
<meta property="og:url" content="http://example.com/">
<meta property="og:image" content="http://example.com/1200x630.png">
<meta property="og:image:type" content="image/png">
<meta property="og:image:width" content="1200">
<meta property="og:image:height" content="630">
<meta property="og:site_name" content="ASP.NET MVC Boilerplate">

What I find perplexing is that Facebook also have their own custom sets of meta tags over and above the ones in Open Graph. These are:

Article
Books Author
Books Book
Books Genre
Business
Fitness Course
Game Achievement
Music Album

Music Playlist
Music Radio Station
Music Song
Place
Product
Product Group
Product Item
Profile

Restaurant Menu
Restaurant Menu Item
Restaurant Menu Section
Restaurant
Video Episode
Video Movie
Video Other
Video TV Show

As you can see there is a lot more choice and detail here. What’s confusing is that there is overlap between the Open Graph and Facebook meta tags. Both have sets covering music, video and books, with the Facebook sets requiring you to add far more detailed metadata. The Open Graph tags may play nicer with other social media sites that use these tags while the Facebook ones will obviously give the best experience for the user on Facebook. The above meta tags can be set using my tag helpers or HTML helpers depending on the version of ASP.NET you are using like so:

<open-graph-website site-name="My Website"
                    title="Page Title"
                    main-image="@(new OpenGraphImage(
                        Url.AbsoluteContent("~/img/1200x630.png"),
                        ContentType.Png,
                        1200,
                        630))"
                    determiner="OpenGraphDeterminer.Blank">

<open-graph-website site-name="My Website"

title="Page Title"

main-image="@(new OpenGraphImage(

Url.AbsoluteContent("~/img/1200x630.png"),

ContentType.Png,

1200,

630))"

determiner="OpenGraphDeterminer.Blank">

@Html.OpenGraph(new OpenGraphWebsite(
    "Page Title",
    new OpenGraphImage(
        Url.AbsoluteContent("~/1200x630.png"))
        {
            Height = 630,
            Type = ContentType.Png,
            Width = 1200
        })
    {
        Determiner = OpenGraphDeterminer.Blank,
        SiteName = "My Site"
    });

@Html.OpenGraph(new OpenGraphWebsite(

"Page Title",

new OpenGraphImage(

Url.AbsoluteContent("~/1200x630.png"))

{

Height = 630,

Type = ContentType.Png,

Width = 1200

})

{

Determiner = OpenGraphDeterminer.Blank,

SiteName = "My Site"

});

Of course there are tag helpers and HTML helpers for all of the above meta tag sets.

Twitter Cards

Twitter cards require meta tags representing one of several ‘cards’ which can represent different things:

App – A phone app.
Gallery – A photo gallery.
Photo – A single photo.
Player – A video.
Product – A product you want to sell.
Summary – A summary of the current page. This is usually the default choice for any page.
Summary Large Image – The same as summary but with a large image.

If you have already added Open Graph meta tags, then Twitter can make use of them and you can omit some of the meta tags that Twitter requires. This makes adding a Twitter Card very easy and in fact, most of the time all you need to do is include a Twitter username and the card type. Here is an example of what Twitter card meta tags look like given that you already have Open Graph meta tags:

<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:site" content="@RehanSaeedUK">

1 2	<meta name="twitter:card" content="summary_large_image"> <meta name="twitter:site" content="@RehanSaeedUK">

Below, is an example of how to generate the above code using my tag helpers or HTML helpers. I have used the ‘Summary Large Image’ card (Notice the double ‘@’ sign in the tag helper, this is because ‘@’ is a special character in Razor and a double ‘@@’ escapes the character):

<twitter-card-summary-large-image username="@@RehanSaeedUK">

1	<twitter-card-summary-large-image username="@@RehanSaeedUK">

@Html.TwitterCard(new SummaryLargeImageTwitterCard("@RehanSaeedUK"));

1	@Html.TwitterCard(new SummaryLargeImageTwitterCard("@RehanSaeedUK"));

There are also tag helpers and HTML helpers for all of the above Twitter cards. The other cards are a little more complicated than the summary card I have shown in my example above.

Google+, Pintrest & Others

Due to the proliferation of Facebooks Open Graph and Twitters card meta tags, other social media sites, search engines and other sites also use them. By implementing the above meta tags, you can cover most of the ground with very little effort.

Validating Meta Tags

Due to the difficulty of getting these meta tags correct, there are several validator tools that the various social media companies provide which let you confirm that you have not made any mistakes. Now, if you’ve used my tag helpers or HTML helpers you should be ahead of the game and things should just work but it’s worth checking out:

Performance

When I was looking into implementing these tag helpers and HTML helpers, I looked at a few other efforts on GitHub. However, for some strange reason all of them used reflection behind the scenes. At this point I’d like to go on a short rant against using reflection. I’ve seen a lot of ‘clever’ code use reflection over the years and I’ve seen a far too many developers hammer far too many nails using it. It’s a very powerful tool but gets abused far too often. Now, back to resuming normal service. This made these libraries pretty slow for generating a few meta tags, not to mention that they don’t support ASP.NET Core. My implementation uses a single StringBuilder and should be fairly fast. At some point I will even use object pooling to reuse copies of StringBuilder.

Where Can I Get It?

This tag or HTML helper is available in a few ways:

Use the ASP.NET MVC Boilerplate project template which includes these helpers as an optional extra.
The ASP.NET MVC 5 Boilerplate Framework or� ASP.NET MVC 6 Boilerplate Framework NuGet package. Note that I will be renaming the ASP.NET MVC 6 package when RC2 comes out to be in line with it’s new naming convention.
Check out source code in the GitHub page for ASP.NET MVC Boilerplate.