DEV Community: Pieter Jan Geutjens

Mastering Azure through Cloud Katas

Pieter Jan Geutjens — Sat, 07 Mar 2020 14:37:03 +0000

Introduction
Before you Start
Kata Datasheet
Kata 1: Provisioning a Linux VM in the Azure Portal
Katas 2 and 3: Provisioning a Linux VM using the Azure CLI or Powershell
Kata 4 - Setting up an Azure Monitor Metrics Alert using Azure CLI
Kata 5 - Building an ARM template for an Azure Storage Account in VS Code
Conclusion

Introduction

In his best-selling work on habit creation Atomic Habits, author James Clear states at one point

You don't want to merely be planning, you want to be practicing. If you want to master a habit, the key is to start with repetition, not perfection. You don't need to map out every feature of a new habit. You just need to practice it.

If you manage to work the practice of a task into a daily routine, you will get better and better at it over time, to the point even of allowing you to execute the tasks with hardly any conscious thought. It has become second nature to you.

There is one major problem with endless repetition though. There's no two ways about it, repeating some identical task day in day out will get.. well.. boring after some time. While it may be true that the ability to persevere with the boring stuff can be a great help in mastering a skill or field, there may be a better approach.

Research on teaching methodologies has long searched for the optimal way to teach skills to humans and non-humans alike. Results show that one of the determining factors in learning speed and motivation is the difficulty of the task, or more specifically the level of challenge the student experiences while training. This has led to the introduction of the term 'Goldilocks zone' of task difficulty for optimal motivation and learning.^{1, 2} The idea is to continuously move along a learning path towards mastering a field where each task is right at the edge of the trainee's current ability. Not too easy or too hard but just right. Combining this approach with an accurate measure of progress tends to lead to the best results.

In this blog post we will apply these insights to learning about and getting hands-on with the Azure Cloud. Through executing a series of short exercises or katas³ revolving around VM creation, monitoring and ARM templating, our goal is for the reader to become increasingly familiar with and skilled using the Azure Cloud. Meanwhile we track the execution time of the tasks to measure progress towards mastery.

Before you Start

Some initial notes before starting the exercises

You will need an Azure Subscription to execute the katas.
At the start of each kata you will find an indication of the total time to run the exercise and the distribution of time spent in the portal, PowerShell and a bash shell. The latter also includes time running commands using the azure cli.
Try timing your runs to collect your own results as you repeat the katas, you'll get a good view on your progress.
The first three katas produce the same results but show different activity distributions. We do not however want to favor one method or tool over another, as this choice is most often determined by previous experience and existing environments.
If you're planning on taking any of the Microsoft Associate Level exams, these katas are an excellent preparation for familiarising yourself with some of the required skills that will be tested!

REMARK: When you finish a set of katas, don't forget to remove the resource groups you created! The resources we create do represent a real cost to your Azure Subscription.

Kata Datasheet

In the following paragraphs we will present five starter katas. The table below shows an overview to give you an idea of the topics, time requirements and tools used for each exercise. The timings are only an indication to use as a baseline. If you have a limited time to run kata exercises, they may help you select which one(s) you want to practice. Your results may vary depending on typing speed, familiarity with the tools, and repetition.

#	kata title	duration	uses
1	Provisioning a Linux VM with nginx in the Azure Portal	8 -12 minutes	portal, bash
2	Provisioning a Linux VM with nginx using Azure CLI	6 - 8 minutes	bash, az-cli
3	Provisioning a Linux VM with nginx using PowerShell	10 - 12 minutes	bash, PowerShell
4	Setting up an Azure Monitor Metrics Alert using Azure CLI	12 - 15 minutes	bash, az-cli
5	Building and Deploying an ARM template using VS Code	12 - 15 minutes	vscode, PowerShell

Kata 1: Provisioning a Linux VM in the Azure Portal

total time: 8-12 minutes

distribution:

The goal of this exercise is to execute the Azure Quickstart exercise you can find at https://docs.microsoft.com/en-us/azure/virtual-machines/linux/quick-create-portal

You will provision a Linux VM, open up network access to port 80, and install the nginx web server to host a static website. Our results indicated a roughly equal amount of time spent in the portal, the bash shell, and waiting for the resources to provision.

Continue running through this exercise until you feel like you've reached a basic level of comfort. Your execution time should also reflect this.

Katas 2 and 3: Provisioning a Linux VM using the Azure CLI or Powershell

total time: 6-8 minutes for CLI, 10-12 minutes for PowerShell

distribution - CLI:

distribution - PowerShell:

Like kata 1, this exercise will have you provision a Linux VM running an nginx web server. This time however you will achieve this using either Azure CLI commands or PowerShell cmdlets from the Azure Cloud Shell.

You can get an instance of the Cloud Shell by pointing your browser to https://shell.azure.com or by opening a shell from the Azure Portal

For this kata, have a go at one of these two Quickstart exercises

A quick tip for the PowerShell version: you can run VS Code either on your machine or in the cloud shell to quickly edit the copied code blocks. Try running the different commands one by one in the PowerShell Cloud Shell so you always have the required variables available for the next steps.

Notice how both exercises produce the same end result through different procedures. Try them both and see how you improve through repetition. Does one feel more familiar to you than the other, are you progressing quicker? We also noticed that the actual provisioning times of the resources were significantly lower here than in kata 1 where we used the Portal.

Kata 4 - Setting up an Azure Monitor Metrics Alert using Azure CLI

total time: 12-15 minutes

distribution:

In our fourth kata we will have a look at Azure Monitor. Collection of metrics and generating alerts based on their values are two core functionalities of the Azure platform. Knowing your way around the Azure Monitoring features is also a key skill when preparing for the various Azure certifications.

In this exercise you will use the Azure CLI to create (and test) a metric alert rule on an Azure Virtual Machine that will trigger when the machine's average CPU load exceeds 85%. In order to complete this kata you should have a running Linux VM available in your subscription. You could run through one of the previous katas to quickly create one.

Log in to the Cloud Shell from either the Azure Portal or from https://shell.azure.com. You can use either a bash or PowerShell instance, as the az executable is available in both.

You can start the exercise by executing the --help option of the az monitor command to list available commands for interacting with metric alerts.

az monitor metrics alert --help

Make a note of the target VM's resource ID. You can quickly get a list of Ids for a resource group by running this command

az vm list --query "[0:1].id" -g <group name> -o tsv

Our goal is to send out an email when the alert is triggered. In order to set this up you'll first create an action group defining the target email address.

az monitor action-group create --action email <receiver name> <receiver email> --name EmailActionGroup --resource-group <group name>

Next, create a simple metrics alert that will trigger when the average CPU load of the VM exceeds 85% for 5 minutes.

az monitor metrics alert create --name csKataCPU85 -g csKata1 --scopes <VM resource ID> --condition "avg Percentage CPU > 85" --description "avg CPU > 85%"

And finally update the Metric Alert and add the action to it.

az monitor metrics alert update --resource-group csKata1 --name csKataCPU85 --add-action EmailActionGroup

Testing the Alert Rule

In order to test the alert you will install the stress tool on your Linux VM. Connect to the machine via SSH.

ssh azureuser@<ip address>

Install the stress tool.

sudo apt-get -y install stress

And start a 10 minute test in the background.

stress --cpu 2 --timeout 600 &

You can monitor the test using the htop command which will show you CPU load as well as the runtime for the stress processes. After a couple of minutes you should receive the alert mail from Azure

Kata 5 - Building an ARM template for an Azure Storage Account in VS Code

preparation (one-time): 5 - 10 minutes

total time: 10 - 15 minutes

distribution:

In the final kata of this first series you will set up Visual Studio code to work with Azure Resource Manager (ARM) templates, and use it to run through an exercise building a template for Storage Account,

Preparation: Setting up Visual Studio Code to author ARM templates

If you don't have Visual Studio Code installed yet, head over to https://code.visualstudio.com/ and install the version for your operating system. Launch the editor and head over to the Extensions tab on the left sidebar. We highly recommend installing the following list of extensions for working with ARM templates:

Azure Resource Manager (ARM) Tools
Azure Resource Manager Snippets
ARM Params Generator
ARM Template Viewer

Once these are installed create a working folder for your kata, and create a file named azuredeploy.json

Authoring the ARM template

Open the azuredeploy.json file and type the word arm. This should trigger the ARM Snippets extension and show you a list of available templates. Select the empty resource group template which should give you the following starting point

{
    "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {},
    "variables": {},
    "resources": [],
    "outputs": {}
}

Next, move your cursor into the "resources" array and, once again typing arm, select the arm-storage template. this will result in the following azuredeploy.json file contents

{
    "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {},
    "variables": {},
    "resources": [
        {
            "name": "storageaccount1",
            "type": "Microsoft.Storage/storageAccounts",
            "apiVersion": "2015-06-15",
            "location": "[resourceGroup().location]",
            "tags": {
                "displayName": "storageaccount1"
            },
            "properties": {
                "accountType": "Standard_LRS"
            }
        }
    ],
    "outputs": {},
    "functions": []
}

While the injected snippet is perfectly valid, at the time of this writing the Visual Studio Code extension uses an API version that is almost 5 years out of date. Therefore, replace the code with the following changed resource definition

 "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {},
    "variables": {},
    "resources": [
        {
            "type": "Microsoft.Storage/storageAccounts",
            "apiVersion": "2019-04-01",
            "name": "storageAccount1",
            "location": "[resourceGroup().location]",
            "sku": {
                "name": "Standard_LRS"
            },
            "kind": "StorageV2",
            "properties": {
            }
        }
    ],
    "outputs": {},
    "functions": []

As the idea behind using an ARM template is to have a re-usable artifact for multiple deployments, you will now introduce 2 parameters to hold the per-deployment values of the storage account name and redundancy tier or sku.

To do this move your cursor to the "parameters" section of the template and, again using the snippets extension, introduce 2 parameters like this

"parameters": {
    "storageName": {
        "type": "string",
        "metadata": {
            "description": "Storage Account Name"
        }
    },
    "storageSKU": {
        "type": "string",
        "defaultValue": "Standard_LRS",
        "allowedValues": [
            "Standard_LRS",
            "Standard_GRS",
            "Standard_RAGRS",
            "Standard_ZRS",
            "Premium_LRS",
            "Premium_ZRS",
            "Standard_GZRS",
            "Standard_RAGZRS"
        ]
    }
}

To finish off we incorporate the parameters in the template, you'll also add an output object specifying we want the storage account's endpoints listed upon completion of the deployment. This can once again be done through the ARM snippets extension. Move the cursor into the "outputs" object and add and tweak an arm-output snippet. This leaves you with the following final contents of azuredeploy.json

{
    "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "storageName": {
            "type": "string",
            "metadata": {
                "description": "Storage Account Name"
            }
        },
        "storageSKU": {
            "type": "string",
            "defaultValue": "Standard_LRS",
            "allowedValues": [
                "Standard_LRS",
                "Standard_GRS",
                "Standard_RAGRS",
                "Standard_ZRS",
                "Premium_LRS",
                "Premium_ZRS",
                "Standard_GZRS",
                "Standard_RAGZRS"
            ]
        }
    },
    "variables": {},
    "resources": [
        {
            "type": "Microsoft.Storage/storageAccounts",
            "apiVersion": "2019-04-01",
            "name": "[parameters('storageName')]",
            "location": "[resourceGroup().location]",
            "sku": {
                "name": "[parameters('storageSKU')]"
            },
            "kind": "StorageV2",
            "properties": {
            }
        }
    ],
    "outputs": {
        "storageEndpoint": {
            "type": "object",
            "value": "[reference(parameters('storageName')).primaryEndpoints]"
        }
    },
    "functions": [
    ]
}

Deploying the ARM Template to a Resource Group

Before deploying the template to Azure, let's first leverage the ARM Params Generator extension to extract the parameters file for the deployment. Launch the command palette in Visual Studio Code by pressing Ctrl-Shift-P (Cmd-Shift-P on a Mac) and select Azure ARM: Generate parameters file.

This will create a new azuredeploy.parameters.json file. Open it and edit as follows

{
    "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentParameters.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "storageName": {
            "value": "cskata20200225"
        },
        "storageSKU": {
            "value": "Standard_LRS"
        }
    }
}

Next, open up an Azure Cloud Shell and select PowerShell as the environment. Once it's running cd into your working directory.

cd /home/pieter

Use the upload/download file button at the top of the terminal to upload the azuredeploy.json and azuredeploy.parameters.json files your created locally.

Finally deploying the template is a two-step process. First you'll define some variables and create the target resource group, and finally you launch the deployment.

$rgName = "csKata5"
$location = "westeurope"
$template = "./azuredeploy.json"
$params = "./azuredeploy.parameters.json"

New-AzResourceGroup -Location $location -Name $rgName

New-AzResourceGroupDeployment -Name "csKata5StorageAccount" -ResourceGroupName $rgName -TemplateFile $template -TemplateParameterFile $params

Just a short while later the deployment should complete and you get output listing all the URL's where your storage account lives.

NOTE: While this first kata exercise in authoring and deploying templates was relatively basic, the possibilities for extending this kata are endless. Using more complex resource combinations and/or more features of ARM template syntax, you can make this kata as short or as long, as easy or as complex as you like.

Conclusion

Hopefully running through this first set of katas has convinced you that repeating these kinds of small exercises until the become familiar and you get them into you muscle memory is a great way to hone your cloud skills. Especially with the inclusion these days of hands-on labs in many of the Microsoft Azure Certification exams, diving in and getting your hands dirty is key in preparing to take the tests.

If you enjoyed this way of familiarising yourself with the Azure Cloud environment, its tools and practices, be sure to expand on it! Think of new scenario's that will support your study efforts, try them out, and repeat to the point of mastery.

Footnotes

1: https://www.nature.com/articles/s41467-019-12552-4 "The Eighty Five Percent Rule for optimal learning"

2: https://jamesclear.com/goldilocks-rule "Goldilocks rule" from Atomic Habits

3: Kata is a term from Japanese martial arts referring to a set of fundamental movements or routines that allow a student, through repetition, to improve their skill level.

Building an Azure Cognitive Search Results page in Vue.js (Part III)

Pieter Jan Geutjens — Sun, 23 Feb 2020 09:52:33 +0000

Introduction

In part I and part II of this blog series we built an Azure Search Results Viewer in Vue, inspired by the demo application of Evan Boyle's AzSearch.js project. As a final step in the process we will now publish our application to an Azure Storage static site using an Azure DevOps project and pipeline.

Azure DevOps is Microsoft's cloud offering in the CI/CD and team collaboration space. It evolved out of the Visual Studio Team Services Platform and includes code repositories, kanban boards, CI/CD pipelines, test plans and artifact repositories. It is a complete environment for agile software development and deployment automation, and also allows for gradual adoption by teams with existing workflows and tools.

Prerequisites

If you want to follow along with this blog post, you will need the following prerequisites:

access to an Azure DevOps organisation with the ability to create projects.
access to an Azure Subscription that can hold the storage account.

For those who don't yet have access to an Azure DevOps organisation, you can get up and running for free in no time by heading over to the Azure DevOps landing page. Let's start by setting up our Azure DevOps project.

Step 1 — Setting up an Azure DevOps Project

Enter a name for the project into the form provided. Choose the visibility, and set the initial source control type to Git, and work item process to Basic in the Advanced section.

When we find ourselves on the welcome page for our new project, our first step will be setting up a source control repository to hold the application source code. To do this click on Repos in the left-hand sidebar. You'll see the starter screen for your project's default repository. We have 2 options for getting the starter code into our repo. In either case you should start by browsing to the git repo for our sample applicaton.

Once there you can get the code by either forking the repo (if you'd like to keep the commit history) or by downloading the code and setting up your own repository. We will choose the latter option.

Start by opening a terminal and changing into your working directory. We will create a folder for our project

mkdir azure-search-vuex
cd azure-search-vuex
git init

Back in the browser, on the top right side of the page, select Download as Zip from the dropdown menu

Extract the contents of the zip file into your working directory and execute the commands as indicated on your DevOps project's starter page.

git remote add origin https://<your organisation>@dev.azure.com/<organisation>/azure%20search%20results%20viewer/_git/azure%20search%20results%20viewer
git add .
git commit -m "initial commit"
git push -u origin --all

Refreshing the repository page now you should see it filled up with the source files. In the next section we'll get started on the release pipeline.

Step 2 — Setting up a Starter Pipeline

Thanks to Microsoft providing an excellent onboarding experience, setting up our initial pipeline is a straight forward process. After clicking on the Pipelines option in the sidebar menu we are greeted with a landing page where we can easily create our first pipeline. We first identify the source code repository we'll be using.

Next we select a starter template for the pipline. The folks at Microsoft were actually kind enough to provide a Node.js with Vue template, excellent!

And that's it! Just four clicks and we have a starter template in place that will build our Vue application. The initial steps are quite self-explanatory, installing node.js and building our Vue app. Also notice how saving the pipeline results in the addition of an azure-pipelines.yml file to our repo. This is the file that contains all the steps we set up.

Step 3 — Defining Environment Variables for Build

In order to successfully build our application we will need the to have 2 environment variables available on the pipeline agent during build. To provide these can use pipeline variables as they are made available as environment variables in the agent runtime.

Click the Variables button on the top right of the pipeline editor. A popup will appear allowing you to define a first variable. name it VUE_APP_SEARCHURL and give it the value https://<search service>.search.windows.net

Add another variable called VUE_APP_SEARCHKEY to hold your query key, you might want to check the Keep this value secret checkbox.

This will allow us to build the application, let's now add some extra steps to the process.

Step 4 — Adding Testing and Artifact Publication to the Pipeline

Let's take a moment to make a mental model of the tasks we want to include in our Continuous Integration pipeline.

clone the git repository
run the unit tests
build the application
zip up the dist folder
publish the .zip as an artifact

Steps 1 and 3 are already covered by our existing pipeline. We will add steps for testing and creating the artifact. The testing step is actually a variation of the existing steps. Modify the pipelie code to contain the following:

# Node.js with Vue
# Build a Node.js project that uses Vue.
# Add steps that analyze code, save build artifacts, deploy, and more:
# https://docs.microsoft.com/azure/devops/pipelines/languages/javascript

trigger:
- master

pool:
  vmImage: 'ubuntu-latest'

steps:
- task: NodeTool@0
  inputs:
    versionSpec: '10.x'
  displayName: 'Install Node.js'

- script: npm install
  displayName: 'npm install'

- script: npm run test:unit
  displayName: 'npm test'

- script: npm run build
  displayName: 'npm build'

To add the step to zip up the resulting build, search for the Archive files task on the right side of the pipeline editor and fill it out as shown below. We will deselect the Prepend root folder name.. option because we want the contents of the dist/ folder in the root of our archive.

This will result in the following addition to our pipeline

...
- task: ArchiveFiles@2
  inputs:
    rootFolderOrFile: 'dist/'
    includeRootFolder: true
    archiveType: 'zip'
    archiveFile: '$(Build.ArtifactStagingDirectory)/$(Build.BuildId).zip'
    replaceExistingArchive: true

Notice how standard tasks available from the tasks library are defined by a unique name and version number combination, ArchiveFiles@2 in this case, and receive the appropriate inputs for execution.

Similarly add another step to the pipeline by searching for the Publish build artifacts task. Leave the options default, which will result in the following addition

- task: PublishBuildArtifacts@1
  inputs:
    PathtoPublish: '$(Build.ArtifactStagingDirectory)'
    ArtifactName: 'drop'
    publishLocation: 'Container'

That's it, the pipeline now executes all the tasks we had envisioned in our initial outline. Save the pipeline, resulting in a new commit on the repository's master branch. This will automatically trigger an execution of the pipeline too.

Step 5 — Deploying to Azure Storage

We're almost there. The final step in the process is to publish our newly built website project to an Azure Storage static site. We will add a Release pipeline to our Azure DevOps project for this purpose.

Setting up the Azure storage account for static site hosting

First things first. In the Azure Portal, browse to the storage account you have prepared and navigate to the Static website blade via the sidebar menu. Make sure the option is enabled here and save your changes. Make a note of the Primary endpoint URL. As you can read on the page, enabling this option has created a storage container named $web which will hold the files we built earlier.

Adding a Release Pipeline in Azure DevOps

Heading back to our Azure DevOps project, navigate to the Releases submenu under Pipelines and add new pipeline. When prompted to select a template, go for the 'start with an Empty job' option at the top. Give the stage an appropriate name like 'Deploy'.

As we will need to use the artifact that resulted from the Build pipeline we created and ran earlier, let's start by hooking this up. Click on Add an artifact in the Artifacts block of the release pipeline and select your project. The artifact we're looking to use should be automatically selected.

Moving on to the Deploy stage, clicking on the 1 job, 0 task link brings up the designer. Again starting with our mental model of the deployment pipeline, the 2 tasks we want to accomplish are

extract the zip file from the artifact
publish the resulting files to the $web container of our storage account

Luckily we can make use of standard tasks for both these steps. For the first step, add a task to the Agent job by clicking the + on the side, and looking for Extract files. Fill out the task's details as follows

Add another task to the Agent job, this time looking for Azure file copy. Under Source select the folder where we extracted our .zip file like you can see below, and pick your subscription. At this point you will possibly have to authorize the creation of an Azure service principal to gain access to the Azure resources. Subsequently fill out the rest of the fields, choosing Azure Blob as the destination type, selecting your storage account and filling in $web as the container name. At this point you can save the release pipeline.

The very last step of this process will be to ensure that every time a new artifact gets created by our build pipeline, it will automatically start the deployment of the site to our Azure storage static website. To achieve this, in the editor of the release pipeline, click on the little lightning bolt icon at the top right of the Artifacts step, and simple switch the toggle to enable automatic deployment.

All that's left to do now is saving the release pipeline and triggering a new release by either manually queueing an execution of our build pipeline, or by commiting some changes to the code of our results viewer, it's all hands-off from there and we end up with a static site showing us some nice real estate! :)

Series Conclusion and Where to Go from Here

At the end of this series, we ran an end-to-end pipeline that builds our results viewer and deploys our website! Let's take a moment to list our achievements here:

we built a website from scratch leveraging the Azure Cognitive Search service
we used the Vue.js framework to get the search results on the page
we added a number of nice features such as search faceting, pagination and sorting
we set up continuous deployment of our code using Azure DevOps pipelines

What this means is, whenever we change our results viewer website and commit the code to the Azure DevOps Repository, about a minute and a half later, our updated site will be available online!

The goal of this third part of the blogs series was to give an idea of the wide range of possible scenario's that can be supported by Azure DevOps pipelines. We've really only scratched the surface, but if you're excited about the possibilities, be sure to head over to the Azure Documentation to learn more! And if you want to experiment, I'll leave you with these 2 links to check out:

Azure Devops Labs: fun labs to try out some real-life scenario's
Azure DevOps Demo Generator: one-click deployment of sample Azure Devops projects!

Good luck, Have fun!

Azure DevOps Demo Generator - Signing In to Another Profile

Pieter Jan Geutjens — Sat, 15 Feb 2020 08:32:59 +0000

Introduction

When trying out new things in Azure DevOps I really like using the Azure DevOps Demo Generator website to quickly spin up a sample environment to work with. I kept running into an issue though where I would see organisations showing up in the Select Organization dropdown box that were not the ones I was working with in the Azure DevOps Portal.

I quicky realised this is probably related to the fact that I have multiple directories linked to the email address I log in with. It proved to be quite challenging to cleanly get signed out of and back in to the right profile, so in this blogpost I'll share the procedure that works for me.

Procedure

close all browser windows and open a new browser.
go to https://app.vssps.visualstudio.com/_signout
once you're signed out, close all browser windows again.
open a new brower and go to https://aex.dev.azure.com/me and sign in.
select the directory or account on the left side that contains the correct Azure Devops organisations.
go back to the Azure DevOps Demo Generator and sign in.
You should now see the correct organisation(s) in the dropdown.

Building an Azure Cognitive Search Results page in Vue.js (Part II)

Pieter Jan Geutjens — Fri, 31 Jan 2020 08:40:59 +0000

Introduction

In part I of the series we made a start building a Vue.js equivalent to the Azure Search demo app built by Evan Boyle. We finished with a functional results page showing the first 50 search results returned by the Azure Search index. In this part we will extend the solution, diving further into the Azure Search API to drive features we're missing: facet filtering, pagination and sorting.

Prerequisites

If you followed along with part I of the series, you're good to go! If not, you can also check out the complete source code of the application on this Azure DevOps Repo.

If you clone the github repo you can checkout the 'part-1' branch to start following along.

git clone https://leapconsulting@dev.azure.com/leapconsulting/cloudskills.io/_git/azuresearch-vuex-demo
cd azuresearch-vuex
git checkout part-1

You will also need a .env file in the root of the project with the following contents

VUE_APP_SEARCHURL=<your index base url>
VUE_APP_SEARCHKEY=<your index query key>

Step 1 — Starting with a Bugfix

There's a bug in the application. I'm hesistant to say it actually took some time before I realised something was wrong, but it turns out when you enter a search string in the input field of the application and press Enter, the page refreshes... *oops*

In order to fix this we will explicitly prevent the default handling of the enter event on the input and trigger a custom event that explicitly updates the searchString to the value of the input field. Make the following changes to the Header component.

<!-- src/components/Header.vue -->

<template>
  <b-navbar toggleable="lg" type="dark" variant="dark">
    <b-navbar-brand href="#">azuresearch-vuex</b-navbar-brand>

    <b-navbar-toggle target="nav-collapse"></b-navbar-toggle>

    <b-collapse id="nav-collapse" is-nav>
      <b-navbar-nav >
        <b-nav-form>
          <b-form-input @keydown.enter.prevent="handleInputEnter" lazy v-model="searchString" size="sm" class="mr-sm-6" placeholder="Search"></b-form-input>
          <b-button size="sm" variant="info" @click="executeSearch">Search</b-button>
          <b-button size="sm" variant="primary" @click="resetSearchString">Reset</b-button>
        </b-nav-form>
      </b-navbar-nav>
    </b-collapse>
  </b-navbar>
</template>

<script>
export default {
  computed: {
    searchString: {
      get() {
        return this.$store.state.searchString;
      },
      set(value) {
        this.$store.dispatch('setSearchString', value);
      },
    },
  },
  methods: {
    executeSearch() {
      this.$store.dispatch('setSearchString', this.searchString);
    },
    resetSearchString() {
      this.$store.dispatch('setSearchString');
    },
    handleInputEnter(e) {
      this.$store.dispatch('setSearchString', e.target.value);
    }
  }

}
</script>

I honestly kinda hate that we have to use this extra handler to fix this bug, and I'm still not sure why this component's v-model attribute does not behave as expected.

Step 2 — The $filter Query Parameter in Azure Search

Really if we want to build out our app with more interactive features allowing users to query the document set, the main focus point of our study of the Azure Search REST API will be the $filter Query Parameter. The docs describe this parameter as

A structured search expression in standard OData syntax. When calling via POST, this parameter is named filter instead of $filter. See OData Expression Syntax for Azure Cognitive Search for details on the subset of the OData expression grammar that Azure Cognitive Search supports.

Knowing our search operations will initially revolve around 2 input types, the search string which is passed separately in the query, and the facets we will select on the page, we can deduce that our filters will have to look something like this:

$filters=([facet1-key] eq [selection 1] or [facet1-key] eq [selection 2]) and ([facet2-key] eq [selection 3])

This might look a bit too abstract, so let's clarify this with an example. If we want to get all realestate items that are appartments containing 2 or 3 baths and 2 bedrooms, our filter would be

$filter=(type eq 'Appartment') and (baths eq 2 or baths eq 3) and (beds eq 2)

In order to capture this logic into our Vuex state we will use 2 variables to hold info related to the active filters

an object, filters, which has fields for each facet. Each field's value will contain the current selection.
a string, filterString, containing the equivalent $filter OData statement based on the active filters.

// src/store/state.js

export default {
  results: [],
  resultsCount: 0,
  facets: [],
  searchString: '*',
  filters: {},
  filterString: ''
};

// src/store/actions.js

/* eslint-disable no-unused-vars */
import searchClient from "@/services/azsearch.service";

export default {
  executeSearch({ state, commit }) {
    searchClient.search(
      "realestate-us-sample-index",
      {
        search: `${state.searchString}`,
        filter: `${state.filterString}`,
        facets: ["beds", "baths", "type"],
        count: true
      },
      (err, results, raw) => {
        commit("SET_RESULTS", results);
        commit("SET_RESULTS_COUNT", raw["@odata.count"]);
        commit("SET_FACETS", raw["@search.facets"]);
      }
    );
  },

  setSearchString({ dispatch, commit }, value = "*") {
    commit("SET_SEARCHSTRING", value);
    dispatch("executeSearch");
  },

  setFilter({ dispatch, commit }, payload) {
    commit("SET_FILTERS", payload);
    dispatch("executeSearch");
  },

  clearFilters({ commit }) {
    commit("CLEAR_FILTERS");
  }
};

// src/store/mutations.js

...

 SET_FILTERS(state, payload) {
    if (payload.selected == null) {
      delete state.filters[payload.facet];
    } else {
      state.filters[payload.facet] = Array.isArray(payload.selected)
        ? payload.selected
        : payload.selected.split();
    }

    let allFilters = [];
    let allFiltersString = "";

    const keys = Object.keys(state.filters);
    keys.map(key => {
      const filterArray = [];
      let filterString = "";
      state.filters[key].map(selectedValue => {
        // handle query string for numbers or strings, add quotes depending
        const filter =
          typeof selectedValue === "number"
            ? selectedValue
            : `'${selectedValue}'`;
        return filterArray.push(`${key} eq ${filter}`);
      });
      filterString += filterArray.join(" or ");
      return allFilters.push(`(${filterString})`);
    });

    allFilters = allFilters.filter(f => f.length && f !== '()');
    allFiltersString = allFilters.join(" and ");
    state.filterString = allFiltersString;
  },

  CLEAR_FILTERS(state) {
    state.filters = {};
    state.filterString = "";
  },

At this point we'll move on right away, adding in new UI elements that will tie together the filter mutations and facet selections

Step 3 — Adding Dropdown- and CheckboxFacet elements to the UI

We will add 3 new components to our application for use in the Sidebar

a checkbox facets selector allowing multi-selection of desired facet values
a dropdown facets selector allowing single-selection of a desired facet value
a "clear filters" element resetting all active filters

The Checkbox Facet Selector

<!-- src/components/CheckboxFacet.vue -->

<template>
  <b-form-group :disabled="options.length <= 1 && selected.length == 0">
      <b-list-group>
        <b-list-group-item>{{field}}</b-list-group-item>
        <b-list-group-item>
      <b-form-checkbox-group class="border-transparent"
        v-model="selected"
        stacked>
        <b-list-group-item
          v-for="option in options"
          :key="option.value"
          class="d-flex justify-content-between align-items-center border-0">
          <b-form-checkbox :value="option.value">
            {{option.text}}
          </b-form-checkbox>
            <b-badge v-show="option.count > 0"
            :variant="selected.includes(option.value) ? 'primary': 'light'"
            pill>
              {{option.count}}
            </b-badge>
        </b-list-group-item>
      </b-form-checkbox-group>
        </b-list-group-item>
      </b-list-group>

    </b-form-group>
</template>

<script>
import { mapState } from 'vuex';
const _ = require('lodash');
export default {
  props: [
    'facet',
    'field',
  ],
  data() {
    return {
      selected: [],
      options: (this.facet.map(item => ({
        text: `${item.value}`,
        value: item.value,
        count: item.count,
      }))).sort((a, b) => a.value - b.value),
    };
  },
  computed: {
    ...mapState([
      'filters',
    ]),
  },
  watch: {
    selected() {
      const payload = {
        facet: this.field,
        selected: this.selected,
      };
      this.$store.dispatch('setFilter', payload);
    },
    facet() {
      _.forEach(this.options, (obj) => {
        _.set(obj, 'count', 0);
      });
      this.facet.forEach((v) => {
        this.options.find(o => o.value === v.value).count = v.count;
      });
    },
    filters() {
      if (!this.filters[this.field]) {
        this.selected = [];
      }
    },
  },
};
</script>
<style>
  .form-group {
    margin-top: 20px;
  }
  .list-group-item {
    border: none;
  }
</style>

Notice how this component receives a specific set of facet data as a prop, along with a field identifier, then builds up a UI element and tracks the selections the user makes, triggering the SetFilter action from the previous section when changes are detected.

The Dropdown Facet Selector

The DropdownFacet element is very similar to the Checkbox Selector. So similar actually one might argue that building a single component to cover both types of facet selector is a good idea. I'll leave this as an exercise for the reader though :-)

<!-- src/components/DropdownFacet.vue -->

<template>
  <b-form-group :disabled="options.length <= 1 && selected.length == 0">
      <b-list-group>
        <b-list-group-item>{{field}}</b-list-group-item>
        <b-list-group-item>
          <b-form-group :id="'dropdown-'+facet.field">
            <b-form-select
              :id="field"
              v-model="selected"
              :options="options"
            ></b-form-select>
          </b-form-group>
        </b-list-group-item>
      </b-list-group>
    </b-form-group>
</template>

<script>
import { mapState } from 'vuex';
export default {
  props: [
    'facet',
    'field',
  ],
  data() {
    return {
      selected: [],
      options: [{ text: 'All', value: null }, ...(this.facet.map(item => ({
        text: `${item.value}`,
        value: item.value,
        count: item.count,
      }))).sort((a, b) => a.value - b.value)]
      ,
    };
  },
  watch: {
    selected(newVal) {
      if (typeof (newVal) !== 'string' || !newVal) return;
      const payload = {
        facet: this.field,
        selected: this.selected,
      };
      this.$store.dispatch('setFilter', payload);
    },
    filters() {
      if (!this.filters[this.field]) {
        this.selected = [];
      }
    },
  },
  computed: {
    ...mapState([
      'filters',
    ]),
  },
};
</script>
<style>
  .form-group {
    margin-top: 20px;
  }
  .list-group-item {
    border: none;
  }
</style>

Clearing the Filters

Finally the ClearFilters component maps the current filterString from Vuex state and its content switches between a passive span and an active link depending on whether there is a filter active. Clicking the link clears the filters.

<!-- src/components/ClearFilters.vue -->

<template>
      <p>
      <a
        v-if="filtersActive"
        @click="clearFilters"
        class="action-link">
        clear filter(s)
      </a>
      <span v-else class="text-muted">
          clear filter(s)
      </span>
    </p>
</template>
<script>
import { mapState } from 'vuex';
export default {
  computed: {
    ...mapState([
      'filterString',
    ]),
    filtersActive() {
      return !!this.filterString;
    }
  },
  methods: {
    clearFilters() {
      this.$store.dispatch('clearFilters');
    },
  },
};
</script>
<style scoped>
a,span {
  float:right;
}
a {
  cursor: pointer;
  color: lightblue!important;
}
</style>

We will incorporate the new UI elements into the Sidebar Component, resulting in a search page that has gained some much needed filtering functionality!

<!-- src/components/Sidebar.vue -->

<template>
  <nav class="col-md-2 d-none d-md-block bg-light sidebar">
    <div class="sidebar-sticky">
      <ul class="nav flex-column">
              <li class="nav-item col-12">
                <b-list-group>
                  <b-list-group-item>
                    <span>
                      Showing {{resultsCount}} results
                    </span>
                  </b-list-group-item>
                </b-list-group>
                <ClearFilters />
              </li>
              <li class="nav-item col-12" v-if="facets.type">
                <DropdownFacet v-bind:facet="facets.type" field="type" />
              </li>
              <li class="nav-item col-12" v-if="facets.beds">
                <CheckboxFacet v-bind:facet="facets.beds" field="beds" />
              </li>
              <li class="nav-item col-12" v-if="facets.baths">
                <CheckboxFacet v-bind:facet="facets.baths" field="baths" />
              </li>
              <li class="nav-item col-12">
                <ClearFilters />
              </li>
            </ul>
    </div>
  </nav>
</template>
<script>
  import { mapState } from 'vuex';
  import CheckboxFacet from '@/components/CheckboxFacet.vue';
  import DropdownFacet from '@/components/DropdownFacet.vue';
  import ClearFilters from '@/components/ClearFilters.vue';
  export default {  
    components: {
      DropdownFacet,
      CheckboxFacet,
      ClearFilters,
    },
    computed: {
      ...mapState([
        'resultsCount',
        'facets',
        ])
    }
  }
</script>

Step 4 — Adding Tests for Mutations

As indicated at the start of Part I, we will make a short foray into testing the Vuex mutations in our application. This is not supposed to be a full overview of testing with Vue and Vuex, as that is not the focus of this blog post. Rather it's meant to hint to the fact that testing should be considered a very important part of the development process, even though we cannot take the time here to do a deep dive into the subject.

Up until the introduction of the search filters, our Vuex mutations had been pretty simple. We have now introduced a more interesting mutation though that converts the user's selections to a suitable filterstring. Below you can find three example tests for the Vuex mutations, two simple test for the SET_RESULTS and SET_FACETS functions, and a more extensive one for SET_FILTERS. The latter uses Jest's test.each() function to bundle a number of scenario's. Hopefully these examples can serve as inspiration to those who might want to expand the test suite.

REMARK: We actually run into another reason here why splitting out the mutations into a separate file in Part I was a good idea. As the mutations object is already exported there, the functions are easily imported here to be tested.

// tests/unit/mutations.spec.js

import mutations from "@/store/mutations";

const {
  SET_RESULTS,
  SET_FACETS,
  SET_FILTERS,
} = mutations;

const sampleData = {
  "@odata.context":
    "https://xxxx.search.windows.net/indexes('realestate-us-sample-index')/$metadata#docs(*)",
  "@odata.count": 4959,
  "@search.facets": {
    baths: [
      { count: 1833, value: 1 }, { count: 1350, value: 2},
      { count: 954, value: 3}, { count: 616, value: 4},
      { count: 206, value: 5}
    ],
    beds: [
      { count: 1051, value: 1 }, { count: 994, value: 4 },
      { count: 983, value: 5 }, { count: 982, value: 3 },
      { count: 949, value: 2 }
    ],
    type: [
      { count: 2513, value: "House" }, { count: 2446, value: "Apartment" }
    ]
  },
  value: [
    {
      "@search.score": 1,
      listingId: "9384540",
      beds: 2,
      baths: 1,
      description:
        "This is a ranch style house and is a beautiful home.  This property has lake access located in a gated community and features sub-zero appliances, french doors throughout and a large laundry room.",
      ...
    },
    ...
    {
        ...
    }
  ]
};

describe('mutations', () => {
  it("SET_RESULTS", () => {
    const state = {
      results: []
    };

    SET_RESULTS(state, sampleData.value);

    expect(state.results.length).toEqual(sampleData.value.length);
    expect(state.results).toContain(sampleData.value[0]);
  });

  it("SET_FACETS", () => {
    const state = {
      facets: []
    };

    SET_FACETS(state, sampleData["@search.facets"]);

    const expected = Object.getOwnPropertyNames(sampleData["@search.facets"]);
    const result = Object.getOwnPropertyNames(state.facets);

    expect(result).toEqual(expected);
  });

  it.each`
  description                 | initialState                   | selected                              | expected
  ${'initial selection'}      | ${{}}                          | ${{facet: "beds", selected: [2]}}     | ${'(beds eq 2)'}, 
  ${'add to existing'}        | ${{beds: [2]}}                 | ${{facet: "beds", selected: [2, 3]}}  | ${'(beds eq 2 or beds eq 3)'}
  ${'remove from existing'}   | ${{beds: [2, 3]}}              | ${{facet: "beds", selected: [2]}}     | ${'(beds eq 2)'}
  ${'remove entire facet'}    | ${{beds: [2, 3], baths: [1]}}  | ${{facet: "beds", selected: null}}    | ${'(baths eq 1)'}
  ${'clear all'}              | ${{beds: [2, 3]}}              | ${{facet: "beds", selected: null}}    | ${''}}
  `('SET_FILTER - $description', ({initialState, selected, expected}) => {
  const state = {
    filters: initialState
  };

  SET_FILTERS(state, selected);

  expect(state.filterString).toEqual(expected);
  })
})

The contents of the sampleData variable in the code view above was truncated for obvious reasons, but it's pretty easy to generate. If you browse to your Azure Search Index's page in the Azure portal, you'll find a link to the Search Explorer. Copy/paste the results of a query into your testing mock and off you go! In order to have some facet data too add the following query string:

facet=beds&facet=baths&facet=type&count=true

You can run the test suite by executing the command

yarn test:unit

Step 5 — Pagination and Sorting

A final feature we will add to our application is the option for a user to sort the results and determine the number of results per page. The Azure Search REST API Documentation documents a number of query parameters we can use to get this working

$skip and $top parameters allow us to get a certain 'page' of results
the $orderBy parameter contains a comma-separated expression to sort the results by

Let's add some data to the Vuex state to map these parameters and the matching Vuex actions and mutations and update the executeSearch action to include these new parameters in the query.

// src/store/state.js

export default {
  results: [],
  resultsCount: 0,
  facets: [],
  searchString: "*",
  filters: {},
  filterString: "",
  currentPage: 1,
  resultsPerPage: 10,
  orderBy: "",
};

// src/store/actions.js

/* eslint-disable no-unused-vars */
import searchClient from "@/services/azsearch.service";

export default {
  executeSearch({ state, commit }) {
    searchClient.search(
      "realestate-us-sample-index",
      {
        search: `${state.searchString}`,
        filter: `${state.filterString}`,
        facets: ["beds", "baths", "type"],
        top: state.resultsPerPage,
        skip: (state.currentPage - 1) * state.resultsPerPage,
        orderby: `${state.orderBy}`,
        count: true
      },
      (err, results, raw) => {
        commit("SET_RESULTS", results);
        commit("SET_RESULTS_COUNT", raw["@odata.count"]);
        commit("SET_FACETS", raw["@search.facets"]);
      }
    );
  },

  setSearchString({ dispatch, commit }, value = "*") {
    commit("SET_SEARCHSTRING", value);
    dispatch("executeSearch");
  },

  setFilter({ dispatch, commit }, payload) {
    commit("SET_FILTERS", payload);
    dispatch("executeSearch");
  },

  clearFilters({ commit }) {
    commit("CLEAR_FILTERS");
  },

  setCurrentPage({ dispatch, commit }, page) {
    commit('SET_CURRENT_PAGE', page);
    dispatch('executeSearch');
  },

  setResultsPerPage({ dispatch, commit }, count) {
    commit('SET_RESULTS_PER_PAGE', count);
    dispatch('executeSearch');
  },

  setOrderBy({ dispatch, commit }, value) {
    commit('SET_CURRENT_PAGE', 1);
    commit('SET_ORDERBY', value);
    dispatch('executeSearch');
  },
};

// src/store/mutations.js

...
SET_CURRENT_PAGE(state, page) {
    state.currentPage = page;
  },

SET_RESULTS_PER_PAGE(state, count) {
  state.resultsPerPage = count;
},

SET_ORDERBY(state, value) {
  state.orderBy = value;
}

In the frontend, we will create a new SearchResults component. and bundle the pagination and sorting controls in a new ResultsNavigation component. Bootstrap-vue fortunately provides us with an easy-to-use pagination control. Notice how the different orderByOptions map to statements passed into the $orderBy query parameter. We need to define explicit getters and setters for the currentPage, resultsPerPage and orderBy values to keep Vue.js from complaining about missing setters.

<!--  src/components/ResultsNavigation.vue  -->

<template>
  <b-row>
      <b-col>
        <b-pagination
          v-model="currentPage"
          :total-rows="resultsCount"
          :per-page="resultsPerPage"
          aria-controls="results-group">
        </b-pagination>
      </b-col>
      <b-col>
        <b-input-group append="Per Page">
          <b-form-select v-model="resultsPerPage" :options="perPageOptions">
            <template v-slot:first>
              <option :value="null" disabled>-- Results Per Page --</option>
            </template>
          </b-form-select>
        </b-input-group>
      </b-col>
      <b-col>
        <b-input-group prepend="Sort">
          <b-form-select v-model="orderBy" :options="orderByOptions"></b-form-select>
        </b-input-group>
      </b-col>
    </b-row>
</template>
<script>
import { mapState } from 'vuex'
export default {
  data() {
    return {
      perPageOptions: [
        { text: '10', value: 10, disabled: false },
        { text: '50', value: 50, disabled: false },
        { text: '100', value: 100, disabled: false },
      ],
      orderByOptions: [
        { text: 'Search Score', value: 'search.score() desc', disabled: false},
        { text: 'Price Low To High', value: 'price asc', disabled: false },
        { text: 'Price High to Low', value: 'price desc', disabled: false },
        { text: 'Sqft High to Low', value: 'sqft desc', disabled: false },
      ],
    };
  },
  computed: {
    ...mapState([
      'resultsCount',
      ]),
      currentPage: {
        get() {
          return this.$store.state.currentPage;
        },
        set(value) {
          this.$store.dispatch('setCurrentPage', value);
        },
      },
      resultsPerPage: {
        get() {
          return this.$store.state.resultsPerPage;
        },
        set(value) {
          this.$store.dispatch('setResultsPerPage', value);
        },
      },
      orderBy: {
        get() {
          return this.$store.state.orderBy;
        },
        set(value) {
          this.$store.dispatch('setOrderBy', value);
        },
      },
  }
}
</script>

<!-- src/components/SearchResults.vue -->

<template>
  <div>
    <results-navigation></results-navigation>
    <b-row>
      <b-card-group>
        <ResultItem v-for="result in results" :item="result" :key="result.listingId"/>
      </b-card-group>
    </b-row>
  </div>

</template>

<script>
import { mapState } from 'vuex';
import ResultItem from '@/components/ResultItem.vue';
import ResultsNavigation from '@/components/ResultsNavigation.vue';
export default {
  components: {
    ResultItem,
    ResultsNavigation,
  },
  computed: {
    ...mapState([
      'results',
      'resultsCount',
      'currentPage',
      'resultsPerPage',
      'orderBy',
      ]),
  }
}
</script>

<!-- src/components/Main.vue -->

<template>
  <main role="main" class="col-md-10 ml-sm-auto col-lg-10 px-4">
    <SearchResults/>
  </main>
</template>

<script>
import SearchResults from '@/components/SearchResults.vue'
export default {
  components: {
    SearchResults
  },
}
</script>

In the end we have a functional search results viewer, complete with search, sorting and pagination!

Conclusion and Next Steps

We now have a fully functional search results viewer for Azure Search. While Evan's example includes a number of extra features like range selectors and support for suggestions, what we have built here is very similar in functionality, so mission accomplished!

In Part III of the series we will change gears and move on to a new topic: publishing the application in Azure. We will publish our web app to a Azure Storage static site, and we'll use an Azure DevOps pipeline to do it! Hope to see you there!

Building an Azure Cognitive Search Results page in Vue.js (Part I)

Pieter Jan Geutjens — Thu, 16 Jan 2020 17:25:19 +0000

Introduction

Exploring datasets and offering users an intuitive interface for searching and filtering results is one of the main use cases for (web) applications. With the introduction of Azure Search in 2014, Microsoft provided a fully managed search service to their cloud platform, offering sophisticated search capabilities for your applications.

While the documentation that Microsoft provides is excellent, the tutorials and samples are largely targeting C# and the .NET SDK. At the time of this writing there is a single node.js tutorial available but it focuses mainly on manipulation of the search indexes and indexers, less on the search query API. Luckily Scott Klein and Evan Boyle did a great channel9 episode in 2017 showing off AzSearch.js, a javascript library that facilitates incorporating Azure Search into your applications. The accompanying github repo even contains a fully functional demo of a search page implemented using React and Redux.

In this article we will build a similar appliciation using the Vue.js JavaScript Framework and the Vuex state management library. Doing so will not only result in a useful Vue application, it will also provide a context for exploring the Azure Search query API. The goal is to take small, logical steps working towards the final result to highlight the process as well as the code involved.

Prerequisites

If you want to follow along with this guide, you should have the following prerequisites set up:

An Azure Search index, as set up in this quickstart from Microsoft Docs.
I selected the realestate-us-sample-index to stay in sync with the existing demo app, but you could easily follow along using a custom data source.
A text editor of your choice, I will be using Visual Studio Code
The Vue CLI, setup instructions can be found here
Very basic knowledge of Vue and Vuex
I will be using the Vue Devtools browser plugin.

You can check out the final version of this application on github at https://github.com/pjgeutjens/azuresearch-vuex.git

Step 1 — Initial Project Setup and Vuex initialisation

Let's start by scaffolding a new Vue project. Move into your working directory and execute

vue create azuresearch-vuex

To get up and running quickly we'll manually select a couple of custom options in the initial setup dialog. Let's add Vuex to our project stub as well as Unit Tests.

I picked all default options except for the unit testing framework where I chose Jest over Mocha + Chai. This is a personal preference so feel free to choose what you prefer. I should note here that testing is a topic that will only be touched upon in part 2 of this series, so you could leave this out entirely. However, I've always had the reflex of including it in all my projects.

that's it! Let's cd into our project directory and get coding!

cd azuresearch-vuex

We'll start by doing a little bit of initial setup of the Vuex store. Picking it as an option in the initial dialog has scaffolded a store in the src/store folder. One initial change I like to make is splitting out the state, actions and mutations into their own separate file. this results in the following:

// src/store/index.js

import Vue from 'vue';
import Vuex from 'vuex';

import state from "./state";
import actions from "./actions";
import mutations from "./mutations";

Vue.use(Vuex)

export default new Vuex.Store({
  state,
  mutations,
  actions,
})

the initial actions, and mutations export empty objects

// src/store/actions.js
// src/store/mutations.js

export default {}

To finish up this section we'll define a field in the initial state object to hold the search results of our queries. We'll initialize it as an empty array.

// src/store/state.js

export default {
  results: [],
}

We're ready now to look into connecting our app to the Azure Search Index.

Step 2 — Creating and Hooking up the Azure Search Service

In this section we'll integrate the azure-search library into our application and extend Vuex to allow querying the index. As a first step however we'll create an environment file to store some data. Specifically we'll need to store these 2 values:

the base url of our Azure Search Index
the query key to use with the requests (do NOT use an admin key for your search service!)

Getting the Azure Search URL and query key

You can find the base url of your search index by going to the Azure Portal, navigating to your search service and copying the base URL on the right side of the page. It has the form of https://[search service name].search.windows.net

To add a query key you can again use the portal, navigating to the Keys blade of your search service. While technically you could use one of the 2 admin keys, they come with WAY to many access rights for this use case, so add a custom query key, give it a name and copy the value

Setting up the environment file

To make the values you collected just now available to your application, you can create a .env file in the root of your project that contains the following:

VUE_APP_SEARCHURL=<your index base url>
VUE_APP_SEARCHKEY=<your index query key>

We're naming the variables to start with VUE_APP in order to have them statically embedded later on in our app's client bundle (this by the way is another reason for using a read-only query key). For more details on this topic, check out this page in the Vue docs.

If, like me, you prefer to keep these environment settings out of your git repo, naming the file .env.local will automatically exclude it from your commits.

REMARK: If you're using the vue development server, you'll want to execute a vue build after setting these environment variables so they become available in the app.

Using the azure-search library

In this project we will be using the azure-search npm package. It's a client library for the Azure Search service that provides functions on top of the Azure Search API. It's very straight-forward to use and set up.

yarn add azure-search

To use this package we'll create a separate service file in our project. Importing this service in the Vuex actions. we get a service we can use to make a connection to the search indexer and execute a first query on the stored documents.

// src/services/azsearch.service.js

import AzureSearch from 'azure-search';

const searchClient = AzureSearch({
  url: process.env.VUE_APP_SEARCHURL,
  key: process.env.VUE_APP_SEARCHKEY,
});

export default searchClient;

// src/store/actions.js

/* eslint-disable no-console */
/* eslint-disable no-unused-vars */
import searchClient from "@/services/azsearch.service";

export default {
  executeSearch({ commit }) {
    searchClient.search(
      "realestate-us-sample-index",
      {
        search: `*`,
        count: true
      },
      (err, results, raw) => {
        console.log(raw);
      }
    );
  }
};

You'll notice, for now we console.log the search results we get. Let's finish off this section by calling our Vuex action after the main vue component mounts. We'll also take the opportunity to clean up the component so it ends up looking like this:

<!-- src/App.vue -->

<template>
  <div id="app">
    Home
  </div>
</template>

<script>
export default {
  name: 'app',
  mounted() {
    this.$store.dispatch('executeSearch');
  }
}
</script>

If all goes well, if you now launch your app and open the browser devtools, you should see some search results logged in the console :-). We'll build on this in the next section and get this data into Vuex.

Step 3 — Getting Search Results into Vuex State

Hooking up Vuex state in our application is essentially a 2-step process. We'll start by adding some items to the initial state, and then add mutators that will replace the console.log statement in our action and modify the stored values.

Let's take a moment first though to decide which data points we want to put into the global state. Our app currently has only very basic functionality but looking at the AzSearch.js sample application for inspiration teaches us we'll want to end up with a results page where the user can

filter using a search string
filter with facets for a number of properties of the search results
control the pagination of the results display
sort the results according to a number of criteria

Looking at the Azure Search REST API Documentation, it's clear that these use cases are a close match to the query parameters that are available to specify search behaviour. As a user enters data on our search page, or selects options for filtering and sorting the results, we'll want to send an updated search request to our index.

We'll start small though, adding 2 items to our Vuex state to begin with:

// src/store/state.js

export default {
  results: [],
  resultsCount: 0,
  facets: []
};

To populate these values when we execute our search we'll add a couple of very simple mutators and modify our executeSearch action, adding some facets to the query and (for now) a static "select all" search string.

// src/store/mutations.js

export default {
  SET_RESULTS(state, data) {
    state.results = data;
  },

  SET_FACETS(state, data) {
    state.facets = data;
  },

  SET_RESULTS_COUNT(state, count) {
    state.resultsCount = count;
  }
};

/* eslint-disable no-unused-vars */
import searchClient from "@/services/azsearch.service";

export default {
  executeSearch({ commit }) {
    searchClient.search(
      "realestate-us-sample-index",
      {
        search: `*`,
        facets: ["beds", "baths", "type"],
        count: true
      },
      (err, results, raw) => {
        commit("SET_RESULTS", results);
        commit("SET_RESULTS_COUNT", raw["@odata.count"]);
        commit("SET_FACETS", raw["@search.facets"]);
      }
    );
  }
};

Notice here how, while the result items that come back from the azure search API are available in a dedicated field, we'll have to grab the facet data and resultsCount from the raw response data.

Now serving our application and opening the Vue devtools in the browser, when you navigate to the Vuex tab, you should see something like this:

Step 4 — Displaying Results on the Page

Finally, let's get some search results on the page of our application! We have everything in place now to show the first 50 results.

Really the work is just beginning. We'll start by adding the excellent bootstrap-vue package to our project which will give us easy access to the bootstrap 4 grid system and over 100 of its components. I've never been the best frontend designer so I'll take any help I can get building out the page layouts!

yarn add bootstrap bootstrap-vue

// src/main.js
import Vue from 'vue'
import App from './App.vue'
import store from './store'

import BootstrapVue from "bootstrap-vue";
import "bootstrap/dist/css/bootstrap.css";
import "bootstrap-vue/dist/bootstrap-vue.css";

Vue.use(BootstrapVue);

Vue.config.productionTip = false

new Vue({
  store,
  render: h => h(App)
}).$mount('#app')

As we'll be adding our search field in the UI soon, we will include the search string in the Vuex state and update our executeSearch action to use this value. We will also want to manipulate this field's value from the UI so we also need to add the required Vuex action and mutation. Notice how, when calling the setSearchString action, we immediately call the executeSearch action to update our search results.

// src/store/state.js

export default {
  searchString: '*',
  results: [],
  resultsCount: 0,
  facets: [],
};

// src/store/mutations.js

...

SET_SEARCHSTRING(state, value) {
  state.searchString = value;
}

...

// src/store/actions.js

/* eslint-disable no-unused-vars */
import searchClient from "@/services/azsearch.service";

export default {
  executeSearch({ state, commit }) {
    searchClient.search(
      "realestate-us-sample-index",
      {
        search: `${state.searchString}`,
        facets: ["beds", "baths", "type"],
        count: true
      },
      (err, results, raw) => {
        commit("SET_RESULTS", results);
        commit("SET_RESULTS_COUNT", raw["@odata.count"]);
        commit("SET_FACETS", raw["@search.facets"]);
      }
    );
  },

  setSearchString({ dispatch, commit }, value = "*") {
    commit("SET_SEARCHSTRING", value);
    dispatch("executeSearch");
  }
};

And finally, we flesh out the different UI components, map in Vuex state where needed, and bring it all together.

<!-- src/components/ResultItem.vue -->

<template>
  <b-card
    :title="item.street"
    :img-src="item.thumbnail"
    img-alt="Image"
    img-top
    tag="article"
    class="overflow-hidden" 
    style="max-width: 300px; min-width: 300px;"
  >
    <b-card-text>
      {{item.description}}
    </b-card-text>
  </b-card>
</template>
<script>
export default {
  props: [
    'item',
  ],
};
</script>
<style>
.card {
  margin: 5px 5px;
}
</style>

<!-- src/components/Main.vue -->
<template>
  <main role="main" class="col-md-10 ml-sm-auto col-lg-10 px-4">
    <b-card-group>
        <ResultItem v-for="result in results" 
        :item="result" :key="result.listingId"/>
    </b-card-group>
  </main>
</template>

<script>
import { mapState } from 'vuex';
import ResultItem from '@/components/ResultItem.vue'
export default {
  components: {
    ResultItem,
  },
  computed: {
    ...mapState(['results'])
  }
}
</script>

<!-- src/components/Header.vue -->

<template>
  <b-navbar toggleable="lg" type="dark" variant="dark">
    <b-navbar-brand href="#">azuresearch-vuex</b-navbar-brand>

    <b-navbar-toggle target="nav-collapse"></b-navbar-toggle>

    <b-collapse id="nav-collapse" is-nav>
      <b-navbar-nav >
        <b-nav-form>
          <b-form-input lazy 
            v-model="searchString"
            size="sm" class="mr-sm-6"
            placeholder="Search">
          </b-form-input>
          <b-button
            size="sm"
            variant="info"
            @click="executeSearch">Search
          </b-button>
          <b-button size="sm"
            variant="primary"
            @click="resetSearchString">Reset
          </b-button>
        </b-nav-form>
      </b-navbar-nav>
    </b-collapse>
  </b-navbar>
</template>

<script>
export default {
  computed: {
    searchString: {
      get() {
        return this.$store.state.searchString;
      },
      set(value) {
        this.$store.dispatch('setSearchString', value);
      },
    },
  },
  methods: {
    executeSearch() {
      this.$store.dispatch('setSearchString', this.searchString);
    },
    resetSearchString() {
      this.$store.dispatch('setSearchString');
    }
  }

}
</script>

<!-- src/components/Sidebar.vue -->
<template>
  <nav class="col-md-2 d-none d-md-block bg-light sidebar">
    <div class="sidebar-sticky">
      {{resultsCount}} results found
    </div>
  </nav>
</template>
<script>
  import { mapState } from 'vuex';
  export default {  
    computed: {
      ...mapState(['resultsCount'])
    }
  }
</script>

<!-- // src/App.vue -->

<template>
  <div id="app">
    <Header/>
      <div class="container-fluid">
        <div class="row">
          <Sidebar/>
          <Main/>
        </div>
      </div>
  </div>
</template>

<script>
import Header from '@/components/Header.vue'
import Sidebar from '@/components/Sidebar.vue'
import Main from '@/components/Main.vue'
export default {
  name: 'app',
  components: {
    Header,
    Sidebar,
    Main,
  },
  mounted() {
    this.$store.dispatch('executeSearch');
  }
}
</script>

Conclusion and Next Steps

After all this we end up with a functional search results viewer that's starting to look like something. We'll want to continue working to extend the UI with search facets, sorting and pagination controls. For this, please join me in part 2 of the series! :-)

DEV Community: Pieter Jan Geutjens

Mastering Azure through Cloud Katas

Table of Contents

Introduction

Before you Start

Kata Datasheet

Kata 1: Provisioning a Linux VM in the Azure Portal

Katas 2 and 3: Provisioning a Linux VM using the Azure CLI or Powershell

Kata 4 - Setting up an Azure Monitor Metrics Alert using Azure CLI

Testing the Alert Rule

Kata 5 - Building an ARM template for an Azure Storage Account in VS Code

Preparation: Setting up Visual Studio Code to author ARM templates

Authoring the ARM template

Deploying the ARM Template to a Resource Group

Conclusion

Footnotes

Building an Azure Cognitive Search Results page in Vue.js (Part III)

Introduction

Prerequisites

Step 1 — Setting up an Azure DevOps Project

Step 2 — Setting up a Starter Pipeline

Step 3 — Defining Environment Variables for Build

Step 4 — Adding Testing and Artifact Publication to the Pipeline

Step 5 — Deploying to Azure Storage

Setting up the Azure storage account for static site hosting

Adding a Release Pipeline in Azure DevOps

Series Conclusion and Where to Go from Here

Azure DevOps Demo Generator - Signing In to Another Profile

Introduction

Procedure

Building an Azure Cognitive Search Results page in Vue.js (Part II)

Introduction

Prerequisites

Step 1 — Starting with a Bugfix

Step 2 — The $filter Query Parameter in Azure Search

Step 3 — Adding Dropdown- and CheckboxFacet elements to the UI

The Checkbox Facet Selector

The Dropdown Facet Selector

Clearing the Filters

Step 4 — Adding Tests for Mutations

Step 5 — Pagination and Sorting

Conclusion and Next Steps

Building an Azure Cognitive Search Results page in Vue.js (Part I)

Introduction

Prerequisites

Step 1 — Initial Project Setup and Vuex initialisation

Step 2 — Creating and Hooking up the Azure Search Service

Getting the Azure Search URL and query key

Setting up the environment file

Using the azure-search library

Step 3 — Getting Search Results into Vuex State

Step 4 — Displaying Results on the Page

Conclusion and Next Steps