Forem: Matt Nield

Getting the latest content from Kontent.ai

Matt Nield — Wed, 02 Nov 2022 10:04:20 +0000

The Kontent.ai delivery API enables us to retrieve content from the CMS easily. For content that updates regularly, via the management API or frequent content updates it also provides a way to ensure that the content being retrieved is not stale. It's an easy feature to use so long as you know how and when to use it.

Keeping content up to date is important in any channel. If content updates regularly either via integrations with the CMS or a busy editorial team, we want to make sure that the latest updates are available to our users.

When we're querying Kontent.ai using the Delivery REST API, there is an HTTP header we can use that instructs the API to only return fresh data. It's named X-KC-Wait-For-Loading-New-Content.

When this header is set, the API will wait for new content to be processed before data is returned from the API, ignoring any previously cached data for the same request. If we don't set it, then the delivery API will return a cached response to our query.

Adding the `X-KC-Wait-For-Loading-New-Content` Header

Depending on which stack we're using, how we add the header can look a little different.

In JavaScript, you can see that the query configuration can be passed in per request:

// Set wait header in JavaScript
const client = KontentDelivery.createDeliveryClient({
  projectId: '<PROJECT_ID>',
});

const response = await client.item('my_post')
  .queryConfig({ waitForLoadingNewContent: true })
  .toPromise();

Whereas the following example in .NET sets up the client as always waiting for fresh content:

// Set wait header in dotnet
IDeliveryClient client = DeliveryClientBuilder
    .WithOptions(builder => builder
        .WithProjectId("<PROJECT_ID>")
        .UseProductionApi
        .WaitForLoadingNewContent
        .Build())
    .Build();

IDeliveryItemResponse<Post> response = await client.GetItemAsync<Post>("my_post");

Overall, I prefer the JavaScript approach here, as it allows developers to be explicit about when the fresh content is important to our application. With the .NET approach, it feels a little like a sledgehammer and might cause us to think about registering multiple clients to get the best performance for our application.

What are we waiting for?

A key thing to note is that, when the header is set, only the root items of the query are checked for freshness. Any linked items/modular content will not wait for stale content to be flushed.

In the above diagram, the root item in the query itself has not changed but the linked items have. When we request the root item and include the linked items, the delivery API will return a cached query response.

In my example, I have a Courses type that has Availability Slots as linked items. A scheduled job keeps my availability slots synchronised with an external service. When these slots are updated, I then create a denormalised view of my data in an Azure Cognitive Search index to allow users to search for courses. But, If I process my data too quickly relying on getting the course and its availability slots in a single query, then I run into problems.

To make sure I get the latest versions of the linked items, I request them at the root level of a query as follows:

// in order to get the latest availability data, we need to request the slots directly
  const availabilitySlots = await getClient()
    .items()
    .queryConfig({ waitForLoadingNewContent: true })
    .inFilter(
      'system.id',
      course.availability.value.map((a: any) => a.system.id),
    )
    .toPromise()
    .then((response) => response.items);

This promotes the course availability slots to the root of the query and waits for the updates to finish processing to make sure that the fresh data is returned.

Bulk Update Content Types in Kontent by Kentico

Matt Nield — Fri, 17 Jun 2022 11:04:58 +0000

Mature projects in any CMS will have a large number of content types. Maintaining those with scripts makes changes to that model more repeatable, but it can be overwhelming if you need to update a lot of types. You can leverage the management API in Kontent by Kentico to update multiple content types in a single script to lessen your workload.

In a recent project, I've used Cloudinary for all media assets and the Cloudinary custom element from the custom element gallery. This has been working for me just fine, but at one point I needed to change the settings for the custom element across the whole project. In this project, we'd added the settings for custom elements each time they were created, so updating my content model with 70 content types was going to take some effort to update.

As we'd been using the Kontent CLI to manage content model changes, each change to the content model results in a new script getting created. When faced with a large update like this, we didn't want to manually script each content type change, so we wrote a script using the Kontent Management API to automate the task.

To script this, we needed to do three things:

Identify the content types and elements that need to be changed
Prepare the change that we want to be applied
Loop through the content type list, updating as we go

In our project, the change in question affected sixteen content types. Our method of documenting the content model using Mind Map diagrams in Miro meant that we could easily identify the types in question and their elements and codenames. So all we needed was a simple array of content type codenames.

We captured this data in a simple array with the codenames of the content type and elements respectively as shown below.

const contentTypes = [ 
  ['comp_homepage_hero', 'image'], 
  ['comp_hero_quote', 'image'], 
  ['menu_item', 'tile_image'], 
  ['comp_image', 'image'], 
  ['comp_hero_slim', 'image'], 
  ['location_facility', 'icon'], 
  ['comp_hero_tile', 'image'], 
  ['restaurant', 'tile_image']];

We could have written an additional script to identify the content types that need changing if needed which would mean that the script could be re-run as the content model grows.

For our update, we were changing the details for our Cloudinary connection. This means that for each content type, we need the following:

const updateData = (codename) => { return [ { 
  op: 'replace', 
  path: `/elements/codename:${codename}/json_parameters`, 
  value: "{\"cloudName\":\"NEW_CLOUD_NAME\",\"apiKey\":\"123451234512345\"}" } ] }

The ${codename} will be a parameter that we can pass in to determine the name of the element to update.

Then, we just need to bring it all together by looping through the contentTypes array as follows.

await Promise.all(contentTypes.map(async (type) => { await apiClient.modifyContentType().byTypeCodename(type[0]) .withData(updateData(type[1])).toPromise() }));

The first time we had this, we did not use await Promise.all(...), which confused me for a while. This is important to ensure that all changes are applied before the script ends.

Once run, this takes all of the content types in our codename array and modifies them. The basic idea of looping here is simple but often overlooked. To make this more reusable, we added this to a utility file in our project so that we could easily re-run it with other changes, such as adding new content types to the allowed list in linked items.

How to use next/image with cloud providers

Matt Nield — Fri, 20 May 2022 13:11:46 +0000

Using the next/image component in your site is a quick and easy way to add responsive images. If you’re using a cloud-based asset management platform, you need to make sure that you configure it properly in order to get the best performance and benefit from the features that maybe be provided.

On a previous project, the responsive image implementation didn’t work as I would’ve expected, so I decided to dig further into how it should work. If you’re able to watch it, I created a video that walks through adding the Image component to a next.js application, configuring it to look at an asset management provider, and adding a custom loader to take advantage of the image capabilities provided rather than having the webserver do all of the work.

If you’re more inclined to read about it, these are the steps I took.

First, in Visual Studio Code’s terminal, we can use yarn create next-app and accept the defaults. This created a new folder called my-app that contains our application. We can then run cd my-app and then code . (or code . -r for the current window).

We then change index.js to remove most of the content and add in a simple image, leaving the following:

<main className={styles.main}>
  <div className={styles.hero}> <img alt="Styled photo of a retro microphone" className={styles.heroImage} src="/retro-mic.jpg" />
    <h1 className={styles.title}> Welcome to <a href="https://nextjs.org">Next.js!</a> </h1>
    <p className={styles.description}> Get started by editing <code className={styles.code}>pages/index.js</code> </p>
  </div>
</main>

Well also add to the CSS to style things up a little:

/* modified to add a position and z-index */ 
.title, .description { 
  position: relative; 
  text-align: center; 
  z-index: 0; } 

/* these two are new to make something look acceptable */ .hero { 
  margin: 1rem; 
  padding: 1.5rem; 
  text-align: left; 
  color: inherit; 
  text-decoration: none; 
  border: 1px solid #eaeaea; 
  border-radius: 10px; 
  transition: color 0.15s ease, border-color 0.15s ease; 
  position: relative; 
  display: flex; 
  align-items: center; 
  justify-content: center; 
  flex-wrap: wrap; 
  max-width: 800px; 
  overflow: hidden; } 

.heroImage { 
  position: absolute; 
  top: 0; 
  left: 0; 
  min-height:100%; 
  width: 100%; 
  height:auto; 
  object-fit: cover; 
  mix-blend-mode:color-burn; 
  z-index: -1; 
  opacity: 0.25; }

This just gives us something to look at:

Our simple page for this example
If we look in the dev tools when the page load, we see this:

Network traffic for our image in Chrome developer tools
Nice, but even when we go down to mobile, we get the same image at the same size and a little over 300kB :

Image size for mobile in Chrome developer tools
Let’s add some basic formatting and the Image component from next/image tag gives us something a bit nicer.

When we’ve done that in index.js, the hero looks as follows:

<div className={styles.hero}>
  <Image layout="fill" alt="Styled photo of a retro microphone" className={styles.heroImage} src="/retro-mic.jpg" />
  <h1 className={styles.title}> Welcome to <a href="https://nextjs.org">Next.js!</a> </h1>
  <p className={styles.description}> Get started by editing <code className={styles.code}>pages/index.js</code> </p> </div>

Then, in next.config.js we add the images element in order to add our default configuration:

const nextConfig = { 
  reactStrictMode: true, 
  images: { 
    loader: 'default', 
    deviceSizes: [640, 750, 828, 1080, 1200, 1920, 2048, 3840], 
    formats: ['image/webp'], 
  }, 
}

If we restart the app, we can see now, as we resize, new images are created and they’re webp format:

In our dev tools, we can see that images sizes are more reasonable as well:

If we look in .next/cache/images we can also see the images that have been created:

This is great, but we want to pull these images from our CMS or DAM. To do that, we need to tell next/image where we can get images from using the domains setting.

const nextConfig = { 
  reactStrictMode: true, 
  images: { 
    loader: 'default', 
    domains: ['assets-us-01.kc-usercontent.com'],
    deviceSizes: [640, 750, 828, 1080, 1200, 1920, 2048, 3840], 
    formats: ['image/webp'], 
  }, 
}

Now we can update our image source for our remote image (in this case, coming from the assets in Kontent by Kentico).

<div className={styles.hero}>
  <Image layout="fill" alt="Styled photo of a retro microphone" className={styles.heroImage} src="https://assets-eu-01.kc-usercontent.com/36a6ba89-afdc-013f-dda5-806bb0d472c1/f125b960-fd12-42fb-8656-124600d6d61f/retro-mic.jpg" />
  <h1 className={styles.title}> Welcome to <a href="https://nextjs.org">Next.js!</a> </h1> 
  <p className={styles.description}> Get started by editing <code className={styles.code}>pages/index.js</code> </p> 
</div>

When we reload the application and look in the cache directory, we’ll see that images are yet again created with resized and optimised versions of our files. Given our CMS or DAM might already have the ability to resize images and may also have a globally distributed CDN, we can reduce the requests to our server and let the CDN do its works by adding a custom loader to the mix.

Out of the box, the Image components default loaders support includes Vercel, Squoosh (default), Imgix, Cloudinary, and Akamai. Creating our own can be a simple task depending on what we need.

We can add a really simple loader for Kontent by adding the following to index.js:

const kontentLoader = ({ src, width, quality }) => { 
  return `${src}?w=${width}&q=${quality || 75}&auto=format` }

and then make a small change to the image by adding loader={kontentLoader}:

<div className={styles.hero}>
  <Image loader={kontentLoader} layout="fill" alt="Styled photo of a retro microphone" className={styles.heroImage} src="https://assets-eu-01.kc-usercontent.com/36a6ba89-afdc-013f-dda5-806bb0d472c1/f125b960-fd12-42fb-8656-124600d6d61f/retro-mic.jpg" />
  <h1 className={styles.title}> Welcome to <a href="https://nextjs.org">Next.js!</a> </h1>
  <p className={styles.description}> Get started by editing{' '} <code className={styles.code}>pages/index.js</code> </p> 
</div>

Now, if we restart our app, we still see the images loading in the network tab of our dev tools, but nothing is being added to the cache folder, as the images are being requested directly from the source. 💪

Useful Links

Using the REST Client in Visual Studio Code

Matt Nield — Mon, 09 Aug 2021 06:49:13 +0000

Getting ready to test a new service or API for your project is a common requirement. Normally we’d just create something in PostMan or run a curl command straight from the terminal. But what if you could do something that becomes part of your project in source control instead, wouldn’t that be pretty neat? This is where the REST Client for Visual Studio Code comes in useful.

The REST Client extension by Huachou Mao is a seemingly simple, yet powerful tool to have at your disposal when working in a service-oriented environment. It allows you to quickly make calls to an API endpoint, and to easily repeat those calls, all within Visual Studio Code.

In this article, I’ll describe how I came across the REST Client extension, how I use it in projects, and how I use it to try out new APIs.

I first came across the REST Client plugin a few years ago at a .NET Oxford Meetup event. As I recall, the presenter was using it to quickly test their API endpoints, seeing the response in a new tab within Visual Studio Code. It was such a perfectly simple implementation that I went and installed it that night. It was impressive, but until recently, I’d been using Postman as my go-to tool for checking out REST API calls. It had served me well and I’d invested a lot of time in setting up collections, but recently, I wanted to make some changes to my setup.

This is when I remembered the REST Client. The idea of being able to execute web requests quickly from my VS Code instance was an immediate pull. So I decided to investigate further to see if it would tick all the boxes.

The question is, what were the boxes that I was trying to tick? I really wanted to achieve a couple of simple things:

Add my calls to source control. I don’t want to lose them, and I’ll more than likely run them more than once.
Secure my API key. We don’t want those in source control!

Source Control

So this one is simple. Once you've installed the plugin, you need to create and open a file in Visual Studio Code with a file extension of ‘.http’. Of course, once you get your API calls into source control, you need to take a look at one very important thing - API keys.

Securing API Keys

Most of the APIs that I work with require authorization and that’s probably true in the majority of cases. Storing your key in a source repository (especially a public one) is not good practice. That gave me the conundrum of how I might make calls and not check those API keys into source control.

If you consider the following API call:

curl --request POST \
  --url https://manage.kontent.ai/v2/projects/7af531c3-f4b9-4af6-8f9e-383f51ad3e4b/types \
  --header 'Authorization: Bearer ew0KICAiYWxnIjogIkhTMjU214ZIiwNCiAgInR5cCI6ICJKV1QiDQp9.ew08KICAianRpIjogImJhYzhkODIxMzI1NTRlNGZiNGQxMGQ5MzAFYNhNDZlZmQyIiwNC629iAgImlhdCI6ICIxNjE5NzcwODE5IiwNCiAgImV4cCI6ICIxOTY1MzcwODE5IiwNCiAgInByb2plY3RfaWQiOiAiY2MzODBiODg1OTcwMDFiMzQzZjUwMmE3Y2FkNmU4NjIiLA0KICAidmVyIjogIjIuMS4wIiwNCiAgInVpZCBCI6ICJ1c3JfMHZPTjBVTDFBQ2ZVOXNyYjVUczQyWSIsDQogICJhdWQiOiAibWFuYWdlLmtlbnRpY29jbG91ZC5jb20iDQp9.4-gWmqdw7eybaZu3YkwgpoDieZr8zS2cKMOqBMX-t_E' \
  --header 'Content-type: application/json'

  --data '
{
  "external_id": "article",
  "name": "Article",
  "codename": "article",
  "elements": [
    {
      "name": "Article title",
      "codename": "title",
      "type": "text"
    },
    {
      "name": "Article body",
      "codename": "body",
      "type": "rich_text"
    },
    {
      "name": "Author bio",
      "codename": "bio",
      "allowed_blocks": [
        "images",
        "text"
      ],
      "type": "rich_text"
    }
  ]
}’

Great, it does what I need, but I really don’t want that authorization token stored in my source control, so what can we do about that?

(don’t worry, the example keys above are invalid 🤓)

Variables and Environments

This is where variables and environments come in with the REST Client extension. You can add new environments in your settings.json file to cater for this. As an example, I have the following in the project that I'm currently working on:

    "rest-client.environmentVariables": {
        "$shared": {

        },
        "dev": {
            "project_id": "b82a...yeah-not-the-real-key...3a62",
            "preview_api": "ew0K...yeah-not-the-real-key...UeMk",
            "management_api": "ew0K...yeah-not-the-real-key...H4p0",
        },
        "prod": {
          "project_id": "db3f...yeah-not-the-real-key...a2f4",
          "preview_api": "ew0K...yeah-not-the-real-key...68ZI",
          "management_api": "ewto...yeah-not-the-real-key...oC3E",
      },
    },

These variables can now be used inline, so our initial API call now looks like this:

curl --request POST \
  --url https://manage.kontent.ai/v2/projects/{{project_id}}/types \
  --header 'Authorization: Bearer {{management_api}}' \
  --header 'Content-type: application/json'

  --data '
{
  "external_id": "article",
  "name": "Article",
  "codename": "article",
  "elements": [
    {
      "name": "Article title",
      "codename": "title",
      "type": "text"
    },
    {
      "name": "Article body",
      "codename": "body",
      "type": "rich_text"
    },
    {
      "name": "Author bio",
      "codename": "bio",
      "allowed_blocks": [
        "images",
        "text"
      ],
      "type": "rich_text"
    }
  ]
}’

That's not only simpler to read, but those API keys are not stored in our file or the project as a whole, keeping them out of source control.

When using the extension, these environments can be selected in VS code, making it easy to move between them.

Wrapping it all up

The REST Client extension is a really useful tool to have at your disposal. In this article, I've really only scratched the surface of what it can do. It's well worth taking a few moments to look through the documentation in GitHub to find out what it's capable of.

I can honestly say that this extension has saved me a lot of time and it's in my list of default extensions that I would recommend to anyone using VS Code.

14 great free resources to help get you going fast with Kentico Kontent and .NET

Matt Nield — Tue, 30 Mar 2021 08:47:46 +0000

How do you find the resources that your development team will need to get up and running with Kentico Kontent in .NET?

Working with a headless CMS provides a number of benefits, one of which is the freedom to choose the technology stack that suits you. You might be making a choice based on your channel or perhaps based upon your in-house team's skillset. If you're heading into a new Kentico Kontent project with a .NET team, where do you start?

Kontent Learning Resources

Kentico Kontent has provided a good set of resources available to help you along your way. Most of this content can be accessed from either the Kentico Kontent site or from Kentico’s GitHub pages.

Resource Centre

https://kontent.ai/resources

The resource centre is a great place to get started, with a plethora of webinars, white papers, ebooks, guides, videos, and more to set your team on the right path. Here you can look at things like approaches to content modelling, transitioning to microservices, or perhaps just seeing how others are getting on with things. It's not .NET focussed but looks at the wider product.

GitHub Community

https://kentico.github.io/

This is more of a developer-focused resource in my mind. It is not restricted to Kentico Kontent as it also contains Kentico Xperience resources. You need to join this community through GitHub to get access.

Tutorial

https://docs.kontent.ai/tutorials/develop-apps?tech=dotnet

In my opinion, this is the best of the .NET tutorials for developers who are just starting out. It is regularly updated as the platform updates, so by keeping the packages mentioned in this tutorial up to date, developers can very quickly create a simple application as a starting point to learn some of the basics and build up some core concepts.

Developer Resource Links

https://kentico.github.io/Home/RESOURCES

In 2020, the Kentico MVP program split into two groups: Kentico Kontent and Kentico Xperience. Before that happened, the MVPs put together a list of useful links about each of the products. It contains links to a multitude of resources including social media accounts, blogs, user groups etc. as well as links to Kentico documentation, and partners.

.NET Core Kontent Delivery API & SDKs

OK, so let's focus a little more on .NET. It's fair to say that the JavaScript world gets a lot of attention, but that does not mean to take anything away from the .NET stack. JavaScript has been the biggest uptake for Kentico Kontent for a while now, but there are still plenty of .NET resources that are available.

SDKs

As mentioned, there are a few SDKs that wrap-up the APIs provided by the Kontent team. Broadly speaking there are three to consider:

The Delivery SDK

https://github.com/Kentico/kontent-delivery-sdk-net

This is the most used SDK in .NET and provides the mechanisms for extracting information from Kentico Kontent to display in the application. You can also download the Delivery SDK form NuGet (this is preferred to pulling or forking from GitHub).

Content Management SDK

https://github.com/Kentico/kontent-management-sdk-net

The Content Management SDK is used to manipulate data in Kontent using the Management API. As an example, this can be used to migrate data, or even import content models into the Kontent project. Project structures can be documented in JSON and imported via the API or imported via code. At the moment, this is a little behind the JavaScript version of this SDK, with things like content types missing.

Recommendations SDK

https://github.com/Kentico/kontent-recommendations-net/tree/vNext

The Smart Recommendations SDK uses artificial intelligence (Recombee) to recommend relevant content to your visitors based on the content their content consumption and other similar journey's.

Best practices for Delivery SDK for .NET

https://github.com/Kentico/kontent-delivery-sdk-net/wiki

There are some great tips here for not only working with Kentico Kontent in .NET, but also just working with .NET web apps in general. This is a resource that I don't believe many teams are aware of, but its full of some very useful practices that support a solid foundation for your projects. 💪

.NET Sample Applications

Dancing Goat MVC

https://github.com/Kentico/kontent-sample-app-net

If you know Kentico, then you know of Dancing Goat. 🐐 I think of it as Kentico's very on Contoso/Northwind. This is a more fully-formed Dancing Goat sample site. It goes further than the tutorials, though it's not e-commerce enabled unlike some of the Kentico Xperience Dancing Goat samples that Kentico have provided over the years.

Dancing Goat Razor Pages

https://github.com/Kentico/kontent-sample-app-razorpages

Another .NET implementation of Dancing Goat, this time using Razor Pages as the approach rather than MVC. This implementation is less polished than the MVC implementation, and perhaps not quite as useful, but if you're up razor pages it is a starting point.

Kontent Development Tools

.NET Model Generator

https://www.nuget.org/packages/Kentico.Kontent.ModelGenerator/

The Kentico Kontent model generator is a key tool when working with Kontent and .NET. It was developed to map the content types in your project into .NET classes that can be used with the .NET Delivery SDK. You can see this in both of the code examples above.

Backup Manager

https://github.com/Kentico/kontent-backup-manager-js

The backup manager can provide the basis of the Kontent project migration; to import project structures and content via the Content Management API (CMAPI) and could possibly be used independently to create an internally managed/private set of project templates for Kentico Kontent.

Kontent Online Tools

Kontent Template Manager

https://kentico.github.io/kontent-template-manager/

The Kontent Template Manager allows for the import and export of a project from Kentico Kontent. Exports will take all the content type structure and data and export them to a single ZIP archive. This archive can then be imported into another project and used as a template.

As the name suggests, there are also templates here. A template is made up of application source files and a ZIP file containing the content for the application. There are a few to choose from, four of which are on the .NET stack.

To use this tool, the projects need to have the Management API enabled in the project settings.

Environment Comparer

https://github.com/Simply007/kontent-environments-comparer

Built by Ondřej Chrastina, the environment comparer is a great tool that will allow you to select two different environments to compare. The output is a git-styled diff of all of the content types in your project. This really useful when trying out changes quickly in Kontent using environments and provides a pointer to the scripts needed for the CLI in order to create a new migration.

What isn't in .NET?

As I mentioned above, javascript especially has a lot of traction and support when it comes to Kentico Kontent. As a result, there are still a number of places where developers might need to brush up on their JavaScript. For me the two main areas here are:

Custom Elements. These allow you to extend the Kontent user interface to add your own field type and integrations (i.e. a YouTube video selector). You require some JS to put these together as they need to interact with the DOM and the Kontent application.
Kontent CLI. Most developers will tell you that being able to script things makes them happy. This is because a script is less susceptible to typos and - more often than not - 100% repeatable. Being able to create and update a project on the command-line is a must for any serious project of scale. If your team want this, then they'll need either JavaScript or TypeScript skills.

So, what next?

If you need to get your team up to speed, then I hope the above has given you something useful to look at. If I were to suggest my top two things to look at, it would be Best practices for Delivery SDK for .NET, and the Resource Center. These two give a good balance between technical and more business-oriented knowledge, which can give you more confidence as you move forward.

Returning to .NET

Matt Nield — Thu, 11 Mar 2021 09:26:58 +0000

I've had a website built in Gatsby for a while now, but I really did miss having it in .NET. Here's how and why I moved to a .NET static-site instead of Gatsby.

Just over a year ago, I rebuilt my personal website in Gatsby.js. Having maintained that for a while now, I wanted to move back to .NET, so I'd like to share how that project worked out.

I don't create new content on an hourly basis, so for me having a server-rendered site doesn't really make much sense. Up-to-date means that when I publish some content, it appears on my site and stays there until something new comes along. At the time I was on my journey into the world of Gatsby, I was in the mindset of someone who had heard great things about JAMStack and wanted to try it out. That's what I decided to do one day on the train into London.

Rather than just blindly hacking away until I had a new site though, I set myself a few goals:

🚀 Create a site that was blazingly fast.
💰 Reduced hosting costs.
🚫 No changes to my content model.
🎓 Learn something new.

You can read about my experience of moving to Gatsby in my earlier post, but the key point is that all four of those boxes got ticked, and I ended up with a site that I was reasonably pleased with. (I must point out that I'm no designer, so while the design might have been lacking, I was pleased with how it was put together behind the scenes). My one gripe was that I'm still a .NET developer/fan and I did feel a little naughty building a site in JavaScript! 😳

Why I rebuilt in .NET

Back in November 2020 (yes, that year), this tweet from Ondrej Chrastina caught my attention:

Technology moves fast, and more recently we've seen Statiq appear on the scene. Statiq is a .NET site generator created by Dave Glick (yes, the brains behind the Wyam project). This gave me an opportunity to think about how I might be able to get back to .NET and keep my static site .

For a while, I just played around with the Kontent.Statiq module and my Kontent project, but ultimately decided that - given I needed to make my site look nice - Statiq was a nice opportunity to learn something new while making some much-needed improvements to my site.

So great - what were my goals for creating a new site:

🤓 It has to be in .NET
🚀 Still needs to be really fast, so basically still static.
💰 Still needs to be low-cost/no-cost hosting.
👁 It has to not look terrible.
🎓 It needs to teach me something new.

Blazingly fast with .NET

Points 1 and 2 were solved by using Statiq. There are more reasons than just speed for having a static site, but for now, my focus was speed. My speed benefit turned out to be a bit more than I was expecting. Being more familiar/comfortable with .NET, I was simply coding quicker with Statiq. There was definitely a learning curve involved, but it was nowhere near that which I'd experienced with picking up Gatsby. Being honest, I did miss the simplicity of GraphQL. My build times pipelines actually run similar times on both .NET and npm, they're within a few seconds. The biggest gain was probably the final file size. I reduced the overall size of the pages as there was less involved. For the most part, I'm just rendering HTML - sure there is some JavaScript involved for the menu toggle etc, but other than that, it is truly static.

Hosting on the cheap

Hosting was an issue for me. I really wanted to use Azure Static Web Apps, but two things were a bit annoying. The first thing was that I needed to use GitHub Actions to deploy (given it's still in beta), and my thoughts at the time were that I wanted to use Azure DevOps. From what I can see, Microsoft does not support that in the beta (which seems like an odd choice and makes me wonder how long Azure DevOps is going to be around). The second was that kicking off a GitHub action from a Kontent webhook wasn't as straight forward as it is in Netlify and I'm was looking for a simple solution.

So, off I went building a new Pipeline in Azure DevOps that would publish to Netlify. This worked, it wasn't fast, but it worked. While I then started to look at triggering the build from the Kontent webhook, I came across something I didn't know at the very end of an article on the Netlify blog written by the Kontent developer relations team about why .NET developers should be interested in JAMStack.

Simply put, Netlify can do .NET Core builds now - amazing! 🥳. So my build went from a fairly average YML file to a simple dotent run command. I don't know when this became possible in Netlify, but I'm really happy that it did. .NET 5 is included on the default build image and performs better than my build pipeline on Azure DevOps.

That's hosting sorted and the third point checked off, I just stay on Netlify.

I will point out that I'm super happy with the free version of Netlify. It gives me plenty of build minutes (my build is less than 60 seconds) and my personal use of the data fits well within the limits. If you're doing this commercially though, it's well worth paying for the service to ensure that you have the number of build minutes that you need for preview etc.

Making it look pretty

The look and feel was my next item. Now, this doesn't really have much to do with my choice of .NET. If I had stuck with Gatsby, I would have been addressing my somewhat lacking visual design anyway.

As I said, I'm no designer, and while I was enjoying exploring what I could do with CSS and UX, it really wasn't doing anyone else any favours. 😳 I needed something simple for my site that was clean and accessible. Rather than try again to build something from scratch. I conceded that I really needed a template and so I ended up choosing the Alpha template from html5up.com for this. If you visit HTML5Up, you'll find some awesome templates that you can use to start your projects.

I'm always learning

.NET has been my choice for building web applications since it's initial release back in 2002. In recent years - and especially with .NET Core - it feels like things have been moving much faster. Newer C# language features have a more functional feel to them, and this can change the way that we approach code.

The approach that Statiq uses isn't one that I'd used extensively and was something that I was keen to practice more. Statiq uses pipelined and modules to process content, with each module being immutable and essentially taking in some metadata and outputting some metadata.

It sure takes some getting used to, but once you break into that idea that it's all just metadata things really fall into place quickly. So in picking up Statiq, that checks off the last goal of learning something new. Do I know it inside-out? No, but the more I use it the more I like it.

As an added bonus on the learning front, I used the Kentico Konent CLI to manage the changes in my content types. I made some changes to my content model as part of this project. I made the changes and previewed the site in a separate environment within Kontent, and in order to put these changes live without the risk of me making a terrible typo, I opted to script the changes. The process of doing that was simple and is definitely something I will be doing again in my upcoming projects.

Did it work?

Yes, completely. In this project, I managed to build a site that achieved all of the goals that I'd set. Even while I'm writing this, I know I have more that I want to add to this project. For now, I've replaced my website with something that I can easily maintain, builds quickly, has a small footprint, and ultimately puts me back in .NET.

Is this site a JAMStack site? No, not yet. There is still more to come, but if you subscribe to the notion that a JAMStack site must be static, then this is clearly headed in the right direction.

Using Kentico Kontent in LINQPad

Matt Nield — Thu, 25 Feb 2021 15:37:31 +0000

Sometimes you simply want to try out some code without having to go through the ceremony of setting up a project. Using tools like LINQPad can help by providing you with a quick way to run .NET small queries and programs in isolation, with a really powerful set of methods to output the object graphs to a results window.

I use LINQPad a lot, and most recently with the Kentico Kontent headless CMS. Kontent has a set of .NET SDK which wraps it's API and makes it super easy to use as a .NET developer.

In this video, I'll introduce LINQPad and show you how I use it with Kentico Kontent.

Using Preview in Kentico Kontent on your Local Development Site

Matt Nield — Wed, 30 Sep 2020 10:34:23 +0000

With a lot of teams working remotely, being able to share what you're working on with your team easily is increasingly important. If you're working on some new features for a project, you don't really want to screen share whenever another team member needs to check out your progress. You also don't want to push something into source control just so that your CI pipeline produces a new version of your app from someone them to view.

Lets assume your project is a website and you're working on adding an e-commerce capability - this is brand new work and there is nothing like it on your existing website. How can you let your colleagues see your new changes to the website? Well, if you're working Kentico Kontent allows you to have Preview URLs setup in your project.

What are Preview URLs?

The Preview URLs allow you to provide a different URL structure for each content type. These URLs expose a couple of macros to allow key identifiers from your content to be added to your URL. This includes the URL slug, language variant, the codename and the ID of a content item.

So on our site for example, a preview URL for a product might be as follows

https://example.com/products/{Codename}

If the preview URL is publicly available, then anyone who has access can see it. With a local development environment you need to create a 'tunnel' in order to be able to give someone outside your home or office network access.

Creating a tunnel to your environment

In order to create a tunnel to the development environment, we're going to use a service called ngrok.

ngrok is an application that exposes your local development server through a secure tunnel via the ngrok cloud service. The tunnel is exposed via a URL on a subdomain of ngrok.io. The ngrok application on your local machine then forwards the request to your local development server and returns the response back to the service. The short story being that you can expose your local development machine over the net to anyone who wants/needs to see it. It also gives some nice features like being able to see all requests and responses, as well as re-running requests as needed (which is great for testing).

Using the .NET boilerplate template for Kentico Kontent and performing a dotnet run will start up a local server and make it available on the following two bindings by default:

Port 5000 for HTTP (http://localhost:5000)
Port 5001 for HTTPS (https://localhost:5001)

When we test out site, we really want to be using HTTPS, so we'll want to tell ngrok to use that port number. In order to specify a port number, we need a signed-up account with ngrok. That doesn't cost us anything as long as we can accept the random generated subdomain. In our case this is fine, but upgrading to the basic plan with ngrok will allow you to use a fixed sub-domain.

To illustrate this, I make a screen capture of me running a .NET application from the command line and then making this accessible on the web.

As you can see from the above video, to create the tunnel we just need to run the following command from the terminal:

ngrok http https://localhost:5001

This then lists out the URLs that the ngrok service is listening for. We can take the HTTPS URL and then add this to the Preview URL settings in Kentico Kontent.

Updating Kentico Kontent

Updating Kentico Kontent with the required URLs is as simple as navigating to the project settings and modifying the URLs for the content types that you want to preview.

Once this has been set, Kentico Kontent will allow you to click the preview URL button, which will open the page in a new tab/window in your browser.

Quick summary

You can use ngrok to expose your local development environment in order to give access to other members of your team. By adding the addresses to the Preview URL configuration for your project/feature environment in Kentico Kontent you can enable other project members to see your work using the Kentico Kontent administration interface with minimal effort. 💪

The setup here is pretty simple, but it can work to facilitate collaboration during the early phases of a project where you really are not ready to push anything up to your build server. It's worth noting that the same principal also exists for web hooks. I you want to test that your cache is correctly flushed or debug that the Azure Function that you're working on, ngrok can be a great help.

What next?

This article has shown how to set up basic preview URLs in your Kentico Kontent project on your local development environment using ngrok to give access to remote team members. Given our level of remote working in 2020 😷, that's a pretty useful thing to have set. But this is not the end of the story. In September 2020, Kentico Kontent also released the Web Spotlight feature, which closes the gap between a headless CMS and the desire of marketers and content editors to be able to easily and visually maintain and create content. I'm really excited about Web Spotlight, but sadly have not used it yet, so that is my next project 😃

Cover photo by Thought Catalog

Creating a .gitignore file using the .NET Core SDK

Matt Nield — Wed, 16 Sep 2020 21:01:45 +0000

I recently saw a tweet from fellow Kentico MVP Brian McKeiver about creating a .gitignore file using the .NET SDK. His question being why he'd not known it was a thing before now. Well, neither had I, and I wanted to take a look at it as it sounds like quite a time/life saver.

// Detect dark theme var iframe = document.getElementById('tweet-1305876595249483776-179'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1305876595249483776&theme=dark" }

So, when did this become a thing? Looking at the .NET Core SDK documentation, we can see that back in September of 2019, Microsoft release the 3.0 SDK. This obviously had quite alot of additions, and some of those were some new templates for the dotnet new command.

The list of additional features in 3.0 is as follows:

WPF Application
WPF Class library
WPF Custom Control Library
WPF User Control Library
Windows Forms (WinForms) Application
Windows Forms (WinForms) Class library
Worker Service
Razor Component
Blazor Server App
ASP.NET Core gRPC Service
dotnet gitignore file
Dotnet local tool manifest file
Protocol Buffer File

Obviously the one that I care about here is dotnet gitignore file. It's a realy easy command to use, but it can save you from some of the basic mistakes when creating an new project.

Running the command just consists of the following:

dotnet new gitignore

There are no other options here, what you're going to get is a fairly comprehensive .gitignore (I've listed it out at the end of this article). In terminal, you'll see something like this:

Typically you'll have a .gitignore file that you might copy and paste from project to project, or you might build it up as you go along. The later of those two option is always more prone to error, so being able to create this as a starter is certainly going to be helpful for that next new project!

The generated `.gitignore` file

## Ignore Visual Studio temporary files, build results, and
## files generated by popular Visual Studio add-ons.
##
## Get latest from https://github.com/github/gitignore/blob/master/VisualStudio.gitignore

# User-specific files
*.rsuser
*.suo
*.user
*.userosscache
*.sln.docstates

# User-specific files (MonoDevelop/Xamarin Studio)
*.userprefs

# Mono auto generated files
mono_crash.*

# Build results
[Dd]ebug/
[Dd]ebugPublic/
[Rr]elease/
[Rr]eleases/
x64/
x86/
[Aa][Rr][Mm]/
[Aa][Rr][Mm]64/
bld/
[Bb]in/
[Oo]bj/
[Ll]og/

# Visual Studio 2015/2017 cache/options directory
.vs/
# Uncomment if you have tasks that create the project's static files in wwwroot
#wwwroot/

# Visual Studio 2017 auto generated files
Generated\ Files/

# MSTest test Results
[Tt]est[Rr]esult*/
[Bb]uild[Ll]og.*

# NUNIT
*.VisualState.xml
TestResult.xml

# Build Results of an ATL Project
[Dd]ebugPS/
[Rr]eleasePS/
dlldata.c

# Benchmark Results
BenchmarkDotNet.Artifacts/

# .NET Core
project.lock.json
project.fragment.lock.json
artifacts/

# StyleCop
StyleCopReport.xml

# Files built by Visual Studio
*_i.c
*_p.c
*_h.h
*.ilk
*.meta
*.obj
*.iobj
*.pch
*.pdb
*.ipdb
*.pgc
*.pgd
*.rsp
*.sbr
*.tlb
*.tli
*.tlh
*.tmp
*.tmp_proj
*_wpftmp.csproj
*.log
*.vspscc
*.vssscc
.builds
*.pidb
*.svclog
*.scc

# Chutzpah Test files
_Chutzpah*

# Visual C++ cache files
ipch/
*.aps
*.ncb
*.opendb
*.opensdf
*.sdf
*.cachefile
*.VC.db
*.VC.VC.opendb

# Visual Studio profiler
*.psess
*.vsp
*.vspx
*.sap

# Visual Studio Trace Files
*.e2e

# TFS 2012 Local Workspace
$tf/

# Guidance Automation Toolkit
*.gpState

# ReSharper is a .NET coding add-in
_ReSharper*/
*.[Rr]e[Ss]harper
*.DotSettings.user

# JustCode is a .NET coding add-in
.JustCode

# TeamCity is a build add-in
_TeamCity*

# DotCover is a Code Coverage Tool
*.dotCover

# AxoCover is a Code Coverage Tool
.axoCover/*
!.axoCover/settings.json

# Visual Studio code coverage results
*.coverage
*.coveragexml

# NCrunch
_NCrunch_*
.*crunch*.local.xml
nCrunchTemp_*

# MightyMoose
*.mm.*
AutoTest.Net/

# Web workbench (sass)
.sass-cache/

# Installshield output folder
[Ee]xpress/

# DocProject is a documentation generator add-in
DocProject/buildhelp/
DocProject/Help/*.HxT
DocProject/Help/*.HxC
DocProject/Help/*.hhc
DocProject/Help/*.hhk
DocProject/Help/*.hhp
DocProject/Help/Html2
DocProject/Help/html

# Click-Once directory
publish/

# Publish Web Output
*.[Pp]ublish.xml
*.azurePubxml
# Note: Comment the next line if you want to checkin your web deploy settings,
# but database connection strings (with potential passwords) will be unencrypted
*.pubxml
*.publishproj

# Microsoft Azure Web App publish settings. Comment the next line if you want to
# checkin your Azure Web App publish settings, but sensitive information contained
# in these scripts will be unencrypted
PublishScripts/

# NuGet Packages
*.nupkg
# The packages folder can be ignored because of Package Restore
**/[Pp]ackages/*
# except build/, which is used as an MSBuild target.
!**/[Pp]ackages/build/
# Uncomment if necessary however generally it will be regenerated when needed
#!**/[Pp]ackages/repositories.config
# NuGet v3's project.json files produces more ignorable files
*.nuget.props
*.nuget.targets

# Microsoft Azure Build Output
csx/
*.build.csdef

# Microsoft Azure Emulator
ecf/
rcf/

# Windows Store app package directories and files
AppPackages/
BundleArtifacts/
Package.StoreAssociation.xml
_pkginfo.txt
*.appx
*.appxbundle
*.appxupload

# Visual Studio cache files
# files ending in .cache can be ignored
*.[Cc]ache
# but keep track of directories ending in .cache
!?*.[Cc]ache/

# Others
ClientBin/
~$*
*~
*.dbmdl
*.dbproj.schemaview
*.jfm
*.pfx
*.publishsettings
orleans.codegen.cs

# Including strong name files can present a security risk
# (https://github.com/github/gitignore/pull/2483#issue-259490424)
#*.snk

# Since there are multiple workflows, uncomment next line to ignore bower_components
# (https://github.com/github/gitignore/pull/1529#issuecomment-104372622)
#bower_components/

# RIA/Silverlight projects
Generated_Code/

# Backup & report files from converting an old project file
# to a newer Visual Studio version. Backup files are not needed,
# because we have git ;-)
_UpgradeReport_Files/
Backup*/
UpgradeLog*.XML
UpgradeLog*.htm
ServiceFabricBackup/
*.rptproj.bak

# SQL Server files
*.mdf
*.ldf
*.ndf

# Business Intelligence projects
*.rdl.data
*.bim.layout
*.bim_*.settings
*.rptproj.rsuser
*- Backup*.rdl

# Microsoft Fakes
FakesAssemblies/

# GhostDoc plugin setting file
*.GhostDoc.xml

# Node.js Tools for Visual Studio
.ntvs_analysis.dat
node_modules/

# Visual Studio 6 build log
*.plg

# Visual Studio 6 workspace options file
*.opt

# Visual Studio 6 auto-generated workspace file (contains which files were open etc.)
*.vbw

# Visual Studio LightSwitch build output
**/*.HTMLClient/GeneratedArtifacts
**/*.DesktopClient/GeneratedArtifacts
**/*.DesktopClient/ModelManifest.xml
**/*.Server/GeneratedArtifacts
**/*.Server/ModelManifest.xml
_Pvt_Extensions

# Paket dependency manager
.paket/paket.exe
paket-files/

# FAKE - F# Make
.fake/

# CodeRush personal settings
.cr/personal

# Python Tools for Visual Studio (PTVS)
__pycache__/
*.pyc

# Cake - Uncomment if you are using it
# tools/**
# !tools/packages.config

# Tabs Studio
*.tss

# Telerik's JustMock configuration file
*.jmconfig

# BizTalk build output
*.btp.cs
*.btm.cs
*.odx.cs
*.xsd.cs

# OpenCover UI analysis results
OpenCover/

# Azure Stream Analytics local run output
ASALocalRun/

# MSBuild Binary and Structured Log
*.binlog

# NVidia Nsight GPU debugger configuration file
*.nvuser

# MFractors (Xamarin productivity tool) working folder
.mfractor/

# Local History for Visual Studio
.localhistory/

# BeatPulse healthcheck temp database
healthchecksdb

# Backup folder for Package Reference Convert tool in Visual Studio 2017
MigrationBackup/

##
## Visual studio for Mac
##


# globs
Makefile.in
*.userprefs
*.usertasks
config.make
config.status
aclocal.m4
install-sh
autom4te.cache/
*.tar.gz
tarballs/
test-results/

# Mac bundle stuff
*.dmg
*.app

# content below from: https://github.com/github/gitignore/blob/master/Global/macOS.gitignore
# General
.DS_Store
.AppleDouble
.LSOverride

# Icon must end with two \r
Icon


# Thumbnails
._*

# Files that might appear in the root of a volume
.DocumentRevisions-V100
.fseventsd
.Spotlight-V100
.TemporaryItems
.Trashes
.VolumeIcon.icns
.com.apple.timemachine.donotpresent

# Directories potentially created on remote AFP share
.AppleDB
.AppleDesktop
Network Trash Folder
Temporary Items
.apdisk

# content below from: https://github.com/github/gitignore/blob/master/Global/Windows.gitignore
# Windows thumbnail cache files
Thumbs.db
ehthumbs.db
ehthumbs_vista.db

# Dump file
*.stackdump

# Folder config file
[Dd]esktop.ini

# Recycle Bin used on file shares
$RECYCLE.BIN/

# Windows Installer files
*.cab
*.msi
*.msix
*.msm
*.msp

# Windows shortcuts
*.lnk

# JetBrains Rider
.idea/
*.sln.iml

##
## Visual Studio Code
##
.vscode/*
!.vscode/settings.json
!.vscode/tasks.json
!.vscode/launch.json
!.vscode/extensions.json

How to ensure you have the right security headers

Matt Nield — Wed, 20 May 2020 08:08:56 +0000

Security headers - loved by security teams and loathed by developers. They tell the consumers of your web application what to expect and what it can do. The question is, how can you ensure that your application has the right headers set?

I find myself getting more involved in headless CMS development these days. My choice of platform is Kentico Kontent, and I've been building static sites using Gatsby. I found that a large number of sites built this way do not have security headers set. For me, part of a go-live checklist needs to ensure that your application keeps you, your customers and your organisation safe. A good step forward here is setting the security headers on your site.

Let's take a quick look at what security headers are and then take a look at how we can set them.

Why we need security headers

We use security headers to inform the browser of the expectations of our application. This covers things like:

what external data and script sources we intend to use
how our application can present itself
what features of the device our application interacts with

These headers help to keep our application, data, and users safe from attacks. Most of the headers in this article address cross-site scripting (XSS). XSS is the term used when injecting harmful code into an application.

A common requirement of any web application project is to engage the services of a 3rd party to perform penetration or ‘pen’ testing on your application. One of the first things that will be tested for is the security headers. This goes hand-in-hand with the commonly seen ‘Top 10’ from OWASP. As a result, there is a dedicated OWASP security headers project that gives a good level of detail.

But why is this important if you're generating a static site? It depends on what your site (or application) does. As you add external services for customer reviews, contact forms, and eCommerce integration etc., we increase the number of possible vulnerabilities of the application. It may be true that your core data is on accessed when you rebuild your application, but all of those other features added can leave you, your customers, and your organisation exposed. Being frank, even if you don't add external services there is a risk. This risk is easily reduced using some basic security headers.

Which headers should you include?

Typically you want to cover off as many of these as possible. There is however no value in setting a security header in a completely insecure manner. In those instances, I would say that the header can be and probably should be excluded.

The OWASP list of security headers is as follows:

For our purposes, I have chosen a few of the headers that make the most impact concerning XSS. The following three headers are those that get a little more press and are more essential when it comes to application security.

Content-Security-Policy (CSP)

The CSP is one of the stronger ways to protect your application against XSS. In a nutshell, it whitelists sources of approved content for use in your application. The CSP instructs the browser not to load any other content sources in our application.

This is quite a powerful header and is difficult to set up for web applications. It's common for a web application to use many content sources to provide functionality, content, and UI flare. It's tricky because you can set the following directives comprehensively. The list can be found on the Mozilla developer site:

https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy

Conveniently, any directive not set, the browser will use the default-src value.

There are a couple of things to note about CSP (which is why it appears more complex):

Unlike some other headers, you can only set the CSP header once. Whichever is the last one read by the browser is the one which will be used.
Inline script and styles fall foul of this and require you either set unsafe-inline or perform a bit of additional logic.

Catering for inline scripts and styles needs you to create a hash of the content. It’s mostly a simple thing to do. Chrome makes it quite easy to understand with a helpful message in the console (in this case for <script>alert('Hello, world.')</script>):

We’re given the has that we need to add as 'sha256-qznLcsROx4GACP2dm0UCKCzCG+HiZ1guq6ZZDob/Tng='. But you can do the following in at the comment line too if you want to:

echo -n "alert('Hello, world.');" | openssl dgst -sha256 -binary | openssl enc -base64

If you're unsure what your CSP needs to contain, you can instead use the Content-Security-Policy-Report-Only header. For this, you provide your anticipated directives and an endpoint to collect violations. This allows you to build an accurate set of directives before they are applied. This can be especially useful when using 3rd party sources such as Google Tag Manager that may inject content from multiple sources.

For the rest of this article, this is the header I will focus on.

Feature-Policy

Feature Policy allows us to specify which web platform features our application can and cannot use. This caters for vibrate events, camera use and microphone use. The full list of things you can control is extensive and can be found on the Mozilla developer site:

https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Feature-Policy Strict-Transport-Security

Often referred to as HSTS, this header instructs the user agent to enforce the use of HTTPS, strengthening your implementation of TLS. Under the hood, the purpose of this header is to remind the user agent that this site should be accessed on HTTPS.

The common example is accessing your usual internet banking from a public WiFi location. So long as you’ve been on your bank’s website from a secure location (and HSTS was set), the user agent will know that the site should be accessed over HTTPS. This means that if the public WiFi is compromised in some way, the user agent will not accept the non-HTTPS connection.

As a bonus, because the user agent knows that the application needs to be served over HTTPS, unnecessary 301 redirects for non-HTTPS versions of the application can be avoided.

X-Frame-Options

The X-Frame-Options header instructs the user agent whether you want to allow your site to be framed or not. Preventing the application being embedded in a frame you can help to reduce the likelihood of clickjacking attacks.

How to set the headers

How you build and host your application has a great influence on how you set the security headers. Different hosting providers have different ways to set headers at an application level, and different stacks give you different options too. I.e JAMSTack vs. .NET Core.

Here I’ll touch on how to set these headers in a Gatsby application hosted in Netlify. As an additional bonus, I presented this topic recently at a .NET meetup, so there are some examples for .NET too.

Setting in HTML

One of the simplest methods of setting HTTP response headers for a web page is to add them into the head of the HTML document.

<meta http-equiv="Content-Security-Policy" 
      content="script-src 'self';
               style-src 'self';
               image-src ‘self;">

The http-equiv instructs the user agent to use the supplied content as an HTTP response header. What I've noticed with this in Chrome is that it does not always pick up correctly. You'll still get console notifications if your CSP header is incorrectly set, but it will not necessarily show up in the Network tab when you view the document headers.

This approach also allows you to set individual values for each page, rather than applying the same value across the entire application.

Setting headers in Gatsby.js

When we think about static site generators like Gatsby, we look at separation from the data source and decide that they are secure, as there is no access to the source data. In reality, we add forms and connect other services to create a more rounded application. So for example adding FormStack or Snipcart to our application to add contact forms or e-commerce capabilities.

There are several options available with static sites, and some of them depend on where you are hosting your application.

From the CSP perspective, you can add the gatsby-plugin-csp plugin. This plugin allows you to configure the common parts of the CSP header, but also can automatically add in the hashes for inline components as your application is built.

As an example, here's the gatsby-plugin-csp configuration (in gatsby-config.js) that I was experimenting with for my site.

{
  resolve: `gatsby-plugin-csp`,
  options: {
    disableOnDev: false,
    mergeScriptHashes: true,
    mergeStyleHashes: true,
    mergeDefaultDirectives: true,
    directives: {
      "default-src": "'self' https:",
      "script-src": "'self' 'unsafe-inline' https:",
      "style-src": "'self' 'unsafe-inline' https: blob: ",
      "img-src": "'self' data: https:",
      "font-src": "'self' data: https:",
    },
  },
},

The result is that - as above - the CSP header is added as an http-equiv as shown above. In reality, the above example allows anything so long as it's HTTPS.

Using the `_headers` file

Netlify uses a file to specify the headers that can be applied to the applications that it hosts. This file is named _headers and sits in the publish directory of your site.

When I use this file, I place it in my static folder. Typically, I use a fairly simple file, but it can become more complex if you need it to. Here's an example from a site I've been working on recently:

/*
  X-Frame-Options: SAMEORIGIN
  X-XSS-Protection: 1; mode=block
  X-Content-Type-Options: nosniff
  Content-Security-Policy: default-src 'self' https://*.kc-usercontent.com https://*.google-analytics.com; font-src data:; style-src 'self' 'unsafe-inline' https://*.googletagmanager.com; script-src 'self' 'unsafe-inline' https://*.googletagmanager.com https://*.google-analytics.com
  Referrer-Policy: strict-origin-when-cross-origin
  Feature-Policy: geolocation 'self'
  Feature-Policy: midi 'self'
  Feature-Policy: notifications 'self'
  Feature-Policy: push 'self'
  Feature-Policy: sync-xhr 'self'
  Feature-Policy: microphone 'self'
  Feature-Policy: camera 'self'
  Feature-Policy: magnetometer 'self'
  Feature-Policy: gyroscope 'self'
  Feature-Policy: speaker 'self'
  Feature-Policy: vibrate 'self'
  Feature-Policy: fullscreen 'self'
  Feature-Policy: payment 'self'

Read about setting custom headers in Netlify.

Setting headers in ASP.NET Core

There are a number of places that you can add security headers in ASP.NET. First, you could add them in the application configuration itself by adding the following instartup.cs:

app.Use(async (context, next) => {
  context.Response.Headers.App(
    "Content-Security-Policy",
    "script-src 'self'; " +
    "style-src 'self'; " +
    "img-src 'self'");

  await next();
});

This policy simply stated that any scripts, styles, or image must come from the same origin as the application. This is going to apply the header to all requests to the application.

Another approach is to use the web.config file as follows:

<configuration>
   <system.webServer>
      <httpProtocol>
         <customHeaders>
            <add name="Content-Security-Policy" value="script-src 'self'; style-src 'self'; img-src 'self'; " />
         </customHeaders>
      </httpProtocol>
   </system.webServer>
</configuration>

Again, this approach will add the same CSP to all requests tot he application.

There are also external libraries that you can use to control security headers. A great example is aspnetcore-security-headers by Joonas W (available on NuGet). It deals with a CSP, HSTS, and HTTP Public Key Pinning (HPKP) headers, but also allows you to cater for inline resources throughout the application using nonces.

How to test security headers

When it comes to testing your headers, there are two things to consider:

Are they even there at all?
They are there, but do they work?

Testing for the first question is simple. The simplest thing is to use the developer tools in your browser to view the response headers and see what is present - but you need to know what you're looking for.

There are also plenty of free tools available online that will scan your application and tell you which headers it has found. Two which I fall back on the most are:

The two are very similar in the way that they work. Once your scan is complete, you get more detail and a summary of the headers that have been checked. SecurityHeaders.com will give you a rating from A+ to F (and R, which I think should stand for ‘Run Away’), whereas SerpWorx gives you a score out of 100.

Checking that the headers work is a more complex task. It requires you to understand how each of the headers that you implement behaves. Once you understand that, you can create test scenarios to ensure that the headers are working.

Example of testing the Content Security Policy (CSP)

Let's consider the following HTML document:

<!DOCTYPE html>
<html>
  <head>
    <title>Setting CSP Reponse Header</title>
  </head>
  <body>
    <main>
      <h1 style="color:rebeccapurple">Setting CSP Reponse Header</h1>
      <p>Sample page to test the CSP header</p>
      <img src="https://placehold.it/600x300" alt="yup" />
    </main>
    <script>
        (function () {
            alert("Hello, World");
        })();
    </script>
  </body>
</html>

This document currently has no security headers set. ON page load, it greets the world with a javascript popup, it uses an inline style attribute to add colour to our heading, and it displays an image from an external source. Once loaded it looks a bit like this:

What we want to do is add a basic CSP to the page to help lock things down. This can be done by adding the following to the document head:

<meta  http-equiv="Content-Security-Policy"  content="
  default-src 'self' ;
  ">

But now when we refresh our page, it looks like this:

The image is broke, the inline style is not working, and the javascript pop-up does not trigger. CHrome's developer tools tell us all about these three issues in the console log. We have three issues, so let's see how they can be addressed.

The first issue is that our inline style violates our set directive:

index.html:12 Refused to apply inline style because it violates the following Content Security Policy directive: "default-src 'self' ". Either the 'unsafe-inline' keyword, a hash ('sha256-NcqL2O3Vi61pA+um5+nt0/EJDYXH4MJIaeZnKVe0Yro='), or a nonce ('nonce-...') is required to enable inline execution. Note also that 'style-src' was not explicitly set, so 'default-src' is used as a fallback.

Because we've set this using an attribute on the h1, we're left with only one option. We have to set unsafe-inline in the style-src directive.

<meta  http-equiv="Content-Security-Policy"  content="
  default-src 'self' ;
  style-src 'self' 'unsafe-inline' ;
  ">

But why use 'unsafe-inline' rather than a hash or a nonce? The hash and nonce don't work for attributes, they only apply to elements. You can go ahead and try adding the hash for the inline style, but Chrome is going to ignore you.

It's worth noting that Gatsby uses a fair bit inline attributes, so those sites are going to need 'unsafe-inline'.

The second issue that the image cannot be loaded as if comes from a different origin.

index.html:14 Refused to load the image 'https://placehold.it/600x300' because it violates the following Content Security Policy directive: "default-src 'self' ". Note that 'img-src' was not explicitly set, so 'default-src' is used as a fallback.

To resolve this, we can add https://placehold.it to the img-src directive:

<meta  http-equiv="Content-Security-Policy"  content="
  default-src 'self' ;
  style-src 'self' 'unsafe-inline' ;
  img-src 'self' https://placehold.it ;
  ">

And finally, our exciting javascript alert is not working:

index.html:16 Refused to execute inline script because it violates the following Content Security Policy directive: "default-src 'self' ". Either the 'unsafe-inline' keyword, a hash ('sha256-M0EvshAmM+P/2ftO4FhRfWslEE4wBspM79DQuiCW9SE='), or a nonce ('nonce-...') is required to enable inline execution. Note also that 'script-src' was not explicitly set, so 'default-src' is used as a fallback.

In this instance, we using an inline script element, so we can add the hash to the script-src directive to fix this:

<meta  http-equiv="Content-Security-Policy"  content="
  default-src 'self' ;
  style-src 'self' 'unsafe-inline' ;
  img-src 'self' https://placehold.it ;
  script-src 'self' 'sha256-M0EvshAmM+P/2ftO4FhRfWslEE4wBspM79DQuiCW9SE=' ;
  ">

You may notice that I've specified 'self' on all of the directives. You don't need to do this, but its purpose is to allow that specific directive from our origin. In most cases, you'll probably trust your origin.

Once those are all saved, we can reload the page and everything works again. The difference now is that we're telling the user agent what to expect and asking it to ignore everything else.

Conclusion

Security headers perform an important role in asserting the capabilities and requirements of your application to the user agent. How you set them depends upon how your application is created and hosted, but then the result is a set of directives that the user agent should follow.

Adding the CSP will most definitely break things at first. In reality, it is supposed to. When you move to production, you may well find that you need different values - so you need to test!

Not only do these contribute to the overall security of the application, but in some cases and also help to improve SEO by contributing to faster page load times.

Keeping your keys safe in JAMStack

Matt Nield — Fri, 20 Mar 2020 09:42:13 +0000

Working with Kentico Kontent and Gatsby has been a nice learning curve for me, as I pick up and build upon my front-end developer skillset. You can end up taking quite a lot for granted when you're working with .NET. Securing your calls to an API can be one of these things, as you add things like API keys to your .config files and make sure that you don't push those files into your git repo.

When I started on my journey with Gatsbyjs and Kentico Kontent, I wasn't clear on a method that I could use to hide my API keys. 😕 As with most things though, a little digging on Google goes a long way and I managed to find two solutions:

Using environment variables
Create a settings object

Let's look at these in a little more detail.

Environment Variables

Creating and using environment variables

Environment variables are settings that are usually stored as key-value pairs that you can use in your application. To store your application settings in environment variables, you can create a .env file in your project folder.
The .env file format is just a simple flat file, no hierarchy. As an example, my .env file looks as follows (obviously the values in brackets are replaced):

KONTENT_PROJECT_ID=<Kontent Project ID>
KONTENT_PREVIEW_KEY=<Kontent API Key>
KONTENT_PREVIEW_ENABLED=<true of false>

Reading that file requires you to have the dotenv module in your project. You can install this using the following:

npm install dotenv

The using it is as simple as setting it up (in my case at the top of my gatsby.config file):

require('dotenv').config();

As it happens, in my Gatsby project, I have two .env files, one for running gatsby develop and one for gatsby build (one uses the preview mode of Kentico Kontent while the other does not). In order to do this, I pass a little more info to dotnet to tell the configuration which file to look for, bypassing in the node environment:

require("dotenv").config({
  path: `.env.${process.env.NODE_ENV}`,
})

This means that when I look at my gatsby.config file, I have a much cleaner file that I can commit to my repo that does not contain my various keys as follows:

{
  resolve: `@kentico/gatsby-source-kontent`,
  options: {
    deliveryClientConfig: {
      projectId: process.env.KONTENT_PROJECT_ID,
      previewApiKey: process.env.KONTENT_PREVIEW_KEY,
      globalQueryConfig: {
        usePreviewMode: (process.env.KONTENT_PREVIEW_ENABLED == 'true'),
      },
    },
    languageCodenames: [
      `default`
    ]
  }
}

What you may notice is that I'm not simply using the value from the .env file for the value of usePreviewMode. There is a good reason for this and very simple reason for this and that is that dotenv does not support boolean values. If you want to debug out your environment variables you can use the following:

console.log(process.env);

which means you'll see something like this:

{
  KONTENT_PREVIEW_ENABLED: 'true',
  KONTENT_PREVIEW_KEY: 'Swiper, no swiping!',
  KONTENT_PROJECT_ID: 'Swiper, no swiping!',
  NODE_ENV: 'development',
}

(I actually have a load more in there from my Windows environment variables like PATH, but we don't need to worry about those here)
That's it. When you run npm run build or npm run develop everything should now be picking up your new settings!

Ignore the `.env` file!

A key point here is, add your .env files to the .gitignore file. The whole point here for me is to not commit your keys and other sensitive data to the git repository.

To achieve this, just add the following to your .gitignore file:

# dotenv environment variable files
.env*

Using environment variables with Netlify

I'm my scenario, I'm using Netlify to build and host my solution. If you are too, then you may have already come across the environment variables in your projects build & deploy settings:

Netlify has no concept of build or develop environment variables in my setup (hot I think it can support them), so when we run npm run build, it simply picks up the available variables and gets on with business.

Using environment variables with Azure DevOps

At Ridgeway, we use Azure DevOps for our build pipelines. Typically, we set up the pipelines using yaml files, but the screenshot here uses the classic designer (it's quite an old one):

If you're editing a yaml pipeline, then the option is still there if you click Variables in the top right while editing the pipeline.

Then you can just set the values you want. The options here to make things secret are quite a nice touch, as are the tips on how to use them.

Settings object

Creating and using a settings object

Another option I've seen in use is the creation of a settings object in a separate file. So for example, on one project we have a file called gatsby.keys as follows:

module.exports = {
  enablePreviewMode:  false,
  enableSecuredMode:  true,
  securedApiKey:  'Swiper, no swiping!',
  previewApiKey:  'Swiper, no swiping!'
};

This is then used in the gatsby.config file as follows:

const  keys = require('./gatsby-keys');

The variables are then used to set up the plugins as before.

This method supports boolean values, so we don't need to do any additional work with those. Again, this file needs to be excluded from the repository using the .gitignore file to make sure that we don't push the keys into the wrong place.

Settings objects in build pipelines

I've only tried this with Azure DevOps, and it required me to add a custom pipeline component to create the key's file. So I have a step in my yaml that looks like this:

- task: eliostruyf.build-task.custom-build-task.file-creator@5
  displayName: 'Create settings keys'
  inputs:
    fileoverwrite: true
    filepath: 'gatsby-keys.js'
    filecontent: |
      module.exports = {
        enablePreviewMode: true,
        enableSecuredMode: false,
        securedApiKey: 'Swiper, no swiping!',
        previewApiKey: 'Swiper, no swiping!'
      };

You can probably spot the flaw in this implementation, right? I'm not using variables so actually, this is a massive fail as those keys are directly in my yaml file and so also in source control.

(on the upside, it's a private repo)

Summary

These are to the two methods that I came across while working on both work and personal projects. The first exposure I had was the settings object. While it solves the issue of booleans, it's note really my favourite. The environment variables appears to be a much more robust approach to things and it's the one I'm going to be using (and asking my team to use) going forward.

If you can find the time, I recommend testing both out and seeing which works best in your case.

Cover photo by Chunlea Ju on Unsplash

Testing Macros in Kentico

Matt Nield — Wed, 26 Feb 2020 15:20:15 +0000

Macros are a very powerful part of Kentico and can be essential when it comes to extending admin areas of Kentico and adding your own custom modules and UI elements. This simple - sometimes overlooked tip - will help you along your way.

Kentico provides the developer with a powerful tool in the shape of macros. Most developers who have either developed with the Kentico portal engine or extended the admin area will have come across them. Surprisingly, most people I speak to are reliant on the event log when they need to figure out why their page or permissions are not working. What can be much more helpful is to use the Macro Console

How to open and use the macro console

To open the macro console in Kentico, you navigate to System > Macros > Console (see below). The console itself is fairly straightforward. Once opened, you see the following four elements:

A text area for entering your expressions
An option of the evaluation mode to be used
A results tree
An output text area

Expression

This is a simple as it sounds; a text area for entering a macro expression that you want to evaluate. It benefits from auto-complete to make your life easier and will take account of any custom macro methods or module classes that you have registered in your solution.

As an example, entering the expression SiteObjects.Documents.TopN(5) will return a list of the top 5 documents on the site (ordered by NodeID).

You’re able to do quite a lot in here, from simply listing our objects or properties to applying transformations. So something like ...TopN(5).ApplyTransformation("Ridgeway.Product.Card") would result in the generated markup from the supplied transformation being displayed in the Output.

Evaluation modes

The three evaluation modes that you have available are:

Virtual Data
Real data
Real data with displayed values

These options affect how the information in the macro tree are presented back to you. I personally find the Real data with displayed values to be the most useful mode, as you get to see the display names in the tree.

Results

The results are a macro tree representing the returned result of the resolved expression. Clicking on an item in the results tree will update the expression. The next time you click Execute, your updated expression is the one which will be run.

In our example above, we get and InfoObjectCollection, which contains 5 elements. If you’re using Real data with displayed values, then you should see something like this in the result:

Output

This is the text output of the resolved expressions. I’ve found this to be of most use when quickly testing transformations in modules, simple text transformations, and checking UI element permissions.

Again, with the above example you’ll see something like this:

Example - UI Elements

A recent project I’ve been working featured a lot of extensions to Kentico with a single, large module that encapsulated areas of the businesses order fulfilment. This meant a lot of new classes and a lot of checking permissions before accessing data. Permissions and a UI access are of course all delivered out-of-the-box with Kentico, but we needed more. An example of this was that we had physical stores that would accept click-and-collect orders. Members of the store team needed to be able to log into a collection management application that we created in Kentico to view and manage the orders for their store. Here, permissions and UI controls can only do so much, we either need to start creating some custom pages and controls, order use Kentico's UI tools to filter the data that individuals can see.

The model we built was to create a binding table between our Store class and Kentico’s User class as shown below.

This binding table was then used to show a list of all of the assigned users for a given store (or vice versa) so that the admin team could set up the users correctly. All of that was pretty straightforward, but limiting the data for a given user was where we needed to start using macros.

The first macro method in use was simply called GetUserStores. As its name suggests, this method returns a list of the stores which the user is already assigned to. There is also naturally a counterpart that will return the users assigned to a given store.

For the UI element, we just used a simple UI grid as described in the Creating Custom Modules example in the Kentico documentation; the macro method was going to be used to filter the data that the UI grid would display. This was achieved by setting the where condition of the listing to the following macro expression:

This says that anyone with the ViewAllStores permission or who has an admin privilege or above can see everything, otherwise, we limit the list of results to those that the current user is assigned.

By now you’re probably wondering when I’m going to get to the bit about testing macros rather than how we built the UI. The above expression was originally written using the Macro Console. The key part of the expression above is CurrentUser.GetUserStores().Table.Rows.Transform("{%StoreID%"+"},") %}. This is a fairly simple expression, but to make sure we get it right, we created it in the macro console before testing in the UI grid. One thing that always catches me out when using Transform() is that I can't terminate the expression using %}. Doing this prematurely terminates the entire macro expression, so you need to break it apart by concatenating the string. Finding this out in the Macro Console is much easier than wondering why your page isn't quite loading as you'd expected or why the UI page that you just made isn't displaying the data that you'd expect.

Summary

The Macro Console is a great and underused part of the Kentico platform. It allows a developer to quickly test out the expressions that they need without needing to make more fundamental changes to transformations or UI elements. It’s also very useful in production sites for quickly checking the information in a safe manner (i.e. not digging about in SQL server). Now that we're preparing to move on to Kentico 12 and aiming towards MVC for future solutions at Ridgeway, I still know that this is going to continue to play a role for us as we continue to build on top of Kentico admin UI to meet our client’s needs.

Forem: Matt Nield

Getting the latest content from Kontent.ai

Adding the X-KC-Wait-For-Loading-New-Content Header

What are we waiting for?

Bulk Update Content Types in Kontent by Kentico

How to use next/image with cloud providers

Useful Links

Using the REST Client in Visual Studio Code

Source Control

Securing API Keys

Variables and Environments

Wrapping it all up

14 great free resources to help get you going fast with Kentico Kontent and .NET

Kontent Learning Resources

Resource Centre

GitHub Community

Tutorial

Developer Resource Links

.NET Core Kontent Delivery API & SDKs

SDKs

The Delivery SDK

Content Management SDK

Recommendations SDK

Best practices for Delivery SDK for .NET

.NET Sample Applications

Dancing Goat MVC

Dancing Goat Razor Pages

Kontent Development Tools

.NET Model Generator

Backup Manager

Kontent Online Tools

Kontent Template Manager

Environment Comparer

What isn't in .NET?

So, what next?

Returning to .NET

Why I rebuilt in .NET

Blazingly fast with .NET

Hosting on the cheap

Making it look pretty

I'm always learning

Did it work?

Using Kentico Kontent in LINQPad

Using Preview in Kentico Kontent on your Local Development Site

What are Preview URLs?

Creating a tunnel to your environment

Updating Kentico Kontent

Quick summary

What next?

Creating a .gitignore file using the .NET Core SDK

The generated .gitignore file

How to ensure you have the right security headers

Why we need security headers

Which headers should you include?

Content-Security-Policy (CSP)

Feature-Policy

X-Frame-Options

How to set the headers

Setting in HTML

Setting headers in Gatsby.js

Using the _headers file

Setting headers in ASP.NET Core

How to test security headers

Example of testing the Content Security Policy (CSP)

Conclusion

Keeping your keys safe in JAMStack

Environment Variables

Creating and using environment variables

Ignore the .env file!

Using environment variables with Netlify

Using environment variables with Azure DevOps

Settings object

Creating and using a settings object

Settings objects in build pipelines

Summary

Testing Macros in Kentico

How to open and use the macro console

Expression

Evaluation modes

Results

Adding the `X-KC-Wait-For-Loading-New-Content` Header

The generated `.gitignore` file

Using the `_headers` file

Ignore the `.env` file!