Forem: John Reilly

Azure Open AI: handling capacity and quota limits with Bicep

John Reilly — Thu, 17 Aug 2023 08:28:26 +0000

We're currently in the gold rush period of AI. The world cannot get enough. A consequence of this, is that rationing is in force. It's like the end of the second world war, but with GPUs. This is a good thing, because it means that we can't just spin up as many resources as we like. It's a bad thing, for the exact same reason.

If you're making use of Azure's Open AI resources for your AI needs, you'll be aware that there are limits known as "quotas" in place. If you're looking to control how many resources you're using, you'll want to be able to control the capacity of your deployments. This is possible with Bicep.

This post grew out of a GitHub issue around the topic where people were bumping on the message the capacity should be null for standard deployment as they attempted to deploy. At the time that issue was raised, there was very little documentation on how to handle this. Since then, things have improved, but I thought it would be useful to have a post on the topic.

Viewing capacity and quota limits in the Azure Open AI Studio

If you take a look at the Azure Open AI Studio you'll notice a "Quotas" section:

You'll see above that we've got two deployments of GPT-35-Turbo in our subscription. Both of these contribute towards an overall limit of 360K TPM. If we try and deploy resources and have an overall capacity total that exceeds that, our deployment will fail.

That being the case, we need to be able to control the capacity of our deployments. This is possible with Bicep.

Controlling capacity and quota limits with Bicep

Consider the following account-deployments.bicep:

@description('Name of the Cognitive Services resource')
param cognitiveServicesName string

@description('Name of the deployment resource.')
param deploymentName string

@description('Deployment model format.')
param format string

@description('Deployment model name.')
param name string

@description('Deployment model version.')
param version string = '1'

@description('The name of RAI policy.')
param raiPolicyName string = 'Default'

@allowed([
  'NoAutoUpgrade'
  'OnceCurrentVersionExpired'
  'OnceNewDefaultVersionAvailable'
])
@description('Deployment model version upgrade option. see https://learn.microsoft.com/en-us/azure/templates/microsoft.cognitiveservices/2023-05-01/accounts/deployments?pivots=deployment-language-bicep#deploymentproperties')
param versionUpgradeOption string = 'OnceNewDefaultVersionAvailable'

@description('''Deployments SKU see: https://learn.microsoft.com/en-us/azure/templates/microsoft.cognitiveservices/2023-05-01/accounts/deployments?pivots=deployment-language-bicep#sku
eg:

sku: {
  name: 'Standard'
  capacity: 10
}

''')
param sku object

// https://learn.microsoft.com/en-us/azure/templates/microsoft.cognitiveservices/2023-05-01/accounts?pivots=deployment-language-bicep
resource cog 'Microsoft.CognitiveServices/accounts@2023-05-01' existing = {
  name: cognitiveServicesName
}

// https://learn.microsoft.com/en-us/azure/templates/microsoft.cognitiveservices/2023-05-01/accounts/deployments?pivots=deployment-language-bicep
resource deployment 'Microsoft.CognitiveServices/accounts/deployments@2023-05-01' = {
  name: deploymentName
  parent: cog
  sku: sku
  properties: {
    model: {
      format: format
      name: name
      version: version
    }
    raiPolicyName: raiPolicyName
    versionUpgradeOption: versionUpgradeOption
  }
}

output deploymentName string = deployment.name
output deploymentResourceId string = deployment.id

We can use this to deploy.... deployments (naming here is definitely confusing) to Azure like so:

var cognitiveServicesDeployments = [
  {
    name: 'OpenAi-gpt-35-turbo'
    shortName: 'gpt35t'
    model: {
      format: 'OpenAI'
      name: 'gpt-35-turbo'
      version: '0301'
    }
    sku: {
      name: 'Standard'
      capacity: repositoryBranch == 'refs/heads/main' ? 100 : 10 // capacity in thousands of TPM
    }
  }
]

// Model Deployment - one at a time as parallel deployments are not supported
@batchSize(1)
module openAiAccountsDeployments35Turbo 'account-deployments.bicep' = [for deployment in cognitiveServicesDeployments: {
  name: '${deployment.shortName}-cog-accounts-deployments'
  params: {
    cognitiveServicesName: openAi.outputs.cognitiveServicesName
    deploymentName: deployment.name
    format: deployment.model.format
    name: deployment.model.name
    version: deployment.model.version
    sku: deployment.sku
  }
}]

We're currently only deploying a single account deployment in our array, but we do it this way as it's not unusual to deploy multiple deployments together. Notice the sku portion above:

    sku: {
      name: 'Standard'
      capacity: repositoryBranch == 'refs/heads/main' ? 100 : 10
    }

Here we provision a larger capacity for our feature branch deployments than our main branch deployments. This demonstrates our own usage, whereby we deploy a smaller capacity for our feature branches so that we can test things out, but then deploy a larger capacity for our main branch deployments.

Significantly, we're controlling the capacity of our deployments. The way in which you choose to decide on the capacity of your deployments is up to you, but the above demonstrates how you can do it with Bicep and stick within your quota limits.

Azure Pipelines meet Vitest

John Reilly — Sat, 05 Aug 2023 07:56:19 +0000

This post explains how to integrate the tremendous test runner Vitest with the continuous integration platform Azure Pipelines. If you read the post on integrating with Jest, you'll recognise a lot of common ground with this. Once again we want:

Tests run as part of our pipeline
A failing test fails the build
Test results reported in Azure Pipelines UI

This post assumes we have a Vitest project set up and an Azure Pipeline in place. Let's get started.

Tests run as part of our pipeline

First of all, lets get the tests running. We'll crack open our azure-pipelines.yml file and, in the appropriate place add the following:



- bash: npm run test:ci
  displayName: 'npm test'
  workingDirectory: src/client-app

The above will, when run, trigger a npm run test:ci in the src/client-app folder of the project (it's here where the app lives). What does test:ci do? Well, it's a script in the package.json that looks like this:



"test": "vitest",
"test:ci": "vitest run --reporter=default --reporter=junit --outputFile=reports/junit.xml",

You'll note above we've got 2 scripts; test and test:ci. The former is the default script that Vitest will run when you run npm test. The latter is the script that we'll use in our pipeline. The difference between the two is that the test:ci script will:

Doesn't run in watch mode
Fail the build if any tests fail
Produce a JUnit XML report which details test results. This is the format that Azure Pipelines can use to ingest test results.

The test results are written to reports/junit.xml which is a path relative to the src/client-app folder. Because you may test this locally, it's probably worth adding the reports folder to your .gitignore file to avoid it accidentally being committed.

Report test results in Azure Pipelines UI

Our tests are running, but we're not seeing the results in the Azure Pipelines UI. For that we need the PublishTestResults task.

We need to add a new step to our azure-pipelines.yml file after our npm run test:ci step:



- task: PublishTestResults@2
  displayName: 'supply npm test results to pipelines'
  condition: succeededOrFailed() # because otherwise we won't know what tests failed
  inputs:
    testResultsFiles: 'src/client-app/reports/junit.xml'

This will read the test results from our src/client-app/reports/junit.xml file and pump them into Pipelines. Do note that we're always running this step; so if the previous step failed (as it would in the case of a failing test) we still pump out the details of what that failure was.

And that's it! Azure Pipelines and Jest integrated.

Putting it all together

The complete azure-pipelines.yml additions look like this:



- bash: npm run test:ci
  displayName: 'npm test'
  workingDirectory: src/client-app

- task: PublishTestResults@2
  displayName: 'supply npm test results to pipelines'
  condition: succeededOrFailed() # because otherwise we won't know what tests failed
  inputs:
    testResultsFiles: 'src/client-app/reports/junit.xml'

Please note, there's nothing special about the reports/junit.xml file. You can change the name of the file and/or the location of the file. Just make sure you update the testResultsFiles value in the PublishTestResults task to match.

Azure Container Apps, Bicep, bring your own certificates and custom domains

John Reilly — Thu, 20 Jul 2023 15:13:45 +0000

Azure Container Apps supports custom domains via certificates. If you're looking to make use of the managed certificates in Azure Container Apps using Bicep, then you might want to take a look at this post on the topic.

This post will instead look at how we can use the "bring your own certificates" approach in Azure Container Apps using Bicep. Well, as much as that is possible; there appear to be limitations in what can be achieved with Bicep at the time of writing.

This post assumes you already have an Azure Container App in place and you want to bind a custom domain to it. If you don't have an Azure Container App in place, then you might want to take a look at this post on the topic.

Make a certificate

So the first thing we need to do is make a certificate. This is pretty simple, and in my case amounts to the following command:

sudo openssl req -x509 -newkey rsa:4096 -sha256 -days 3650 -nodes \
  -keyout poorclaresarundel.org.key -out poorclaresarundel.org.crt -subj "/CN=poorclaresarundel.org" \
  -addext "subjectAltName=DNS:poorclaresarundel.org,DNS:www.poorclaresarundel.org,IP:8.8.8.8"
sudo chmod +r poorclaresarundel.org.key
cat poorclaresarundel.org.crt poorclaresarundel.org.key > poorclaresarundel.org.pem

This makes a certificate with a 10 year expiry date. You'll note the 8.8.8.8 listed as the IP address above. You should replace that with the static IP address of your Container Apps Environment. You can find that in the Azure Portal. It's listed on the "Overview" tab of your Azure Container App. It's the "Static IP" value:

You'll also note the poorclaresarundel.org listed as the domain name above. You should replace that with your domain name. You'll need to do that in two places; in the openssl command and in the subjectAltName value. More on the significance of that particular domain name later.

Container apps environment and certificates

Now, we'll crack open our Azure Container App's environment in the Azure Portal and navigate to the "Certificates" tab. Then we need to click on the "Bring your own certificates (.pfx)" tab, and we are presented with a screen like this:

Note the "Add certificate" button. Use that to upload your certificate - in my case that's the poorclaresarundel.org.pem file. You'll need to provide the password for the certificate too. Oh and you'll be asked for a friendly name. We'll remember the friendly name you use - we'll need it later.

This is a real world example; my aunt's website. My aunt is Poor Clare nun and, for years, I've done an average job of maintaining her convent's website. If I was her, I'd be wishing her nephew was a designer rather than an engineer. Or maybe an engineer with more of a sense what looks good. But here we are - she's a nun and so consequently much too nice to say that. Anyway, I digress. The point is, I've got a certificate for her website and I'm going to use it here.

Bicep for the custom domain

I haven't managed to work out how one would handle the certificate upload in Bicep (and I rather suspect it is not supported). However, I have worked out how to handle the certificate in the Azure Container App once it's been uploaded with regards to custom domains. Find the Microsoft.App/containerApps resource in your Bicep and add a customDomains property to it. It should look something like this:

resource environment 'Microsoft.App/managedEnvironments@2022-10-01' = {
  name: environmentName
  // ...
}

resource webServiceContainerApp 'Microsoft.App/containerApps@2022-10-01' = {
  name: webServiceContainerAppName
  tags: tags
  location: location
  properties: {
    // ...
    configuration: {
      // ...
      ingress: {
        // ...
        customDomains: [
          {
              name: 'www.poorclaresarundel.org'
              // note the friendly name of "poorclaresarundel.org" forms the last segment of the id below
              certificateId: '${environment.id}/certificates/poorclaresarundel.org'
              bindingType: 'SniEnabled'
          }
        ]
      }
    }
    // ...
  }
}

Conclusion

With the above post you should be able to deploy an Azure Container App with a custom domain and provide your own certificate, which is then referenced using Bicep. If you'd like to see the full Bicep file, then you can find it here.

Attributions

Certificate icon in title image created by Freepik - Flaticon

TypeScript 5.1: declaring JSX element types

John Reilly — Sun, 09 Jul 2023 08:53:37 +0000

A new feature arrives with TypeScript 5.1, it is described as "Decoupled Type-Checking Between JSX Elements and JSX Tag Types".

It's all about handing control of JSX type definitions to libraries. With this feature, libraries can control what types are used for JSX elements. Why does this matter? Great question! Until version 5.1, TypeScript did an imperfect job of representing what is possible with JSX. This feature allows libraries to do a better job of that, and we'll look into it in this post.

It's probably worth saying, that this is a complicated feature. If you don't understand it (and as the author of this post I'll confess that I had to work quite hard to understand it), that is okay. This is a low level feature that is only likely to be used by library / type definition authors. It's a primitive that will unlock possibilites for people writing JSX - but it's something that people will mainly feel the benefit of, without directly doing anything themselves, or necessarily noticing that things have changed for the better.

What's the problem?

TypeScript creates a type system which sits on top of JavaScript, and provides static typing capabilities. As the language has grown more sophisticated, it has been able to get closer and closer to representing the full range of possibilities that JavaScript offers. As an example of this evolution, if you remember the early days of TypeScript, you'll remember a time before union types. Back then, you had to use any to represent a value that could be one of a number of types. That imperfect representation of JavaScript was solved with union types:

-function printStringOrNumber(stringOrNumber: any) {
+function printStringOrNumber(stringOrNumber: string | number) {
    console.log(stringOrNumber);
}

The problem we're looking at here is in the same vein. But it specifically applies to JSX; which is widely used in libraries like React. With JSX support in TypeScript (up to and including 5.0), it was not possible to accurately represent all JSX possibilities. This is because the type of a JSX element returned from a function component was always JSX.Element | null. This is a type that is defined in the TypeScript compiler, and is not something that can be changed by a library author.

How does this play out? Well, let's take a look at a simple example. Let's say we have a function component that returns a number. We might write something like this:

function ComponentThatReturnsANumber() {
  return 42;
}

<ComponentThatReturnsANumber />;

The above is legitimate JSX, but it is not legitimate TypeScript. The TypeScript compiler will complain:

You can see this in the TypeScript Playground

This errors because function components that return anything but JSX.Element | null are not allowed as element types in React according to TypeScript. However, in React, function components can return a ReactNode. That type includes number | string | Iterable<ReactNode> | undefined (and will likely include Promise<ReactNode> in the future).

As an aside, a return value of number would be perfectly fine in class components - the restrictions are different there. I spoke to Sebastian about this and he said:

An interesting note is that before function components we did have full control. Due to ElementClass, class components already could return ReactNode at the type level. It was just function components that were missing full control (or any other component types Suspense or Profiler).

So this is the problem: is not possible to represent in TypeScript today what is actually possible in React (or other JSX libraries). Furthermore, what's returned from JSX may change over time, and TypeScript needs to be able to represent that.

The arrival of `JSX.ElementType`

Sebastian Silbermann opened a pull request to TypeScript. It had the title "RFC: Consult new JSX.ElementType for valid JSX element types". In that PR Sebastian explained the issue we've just looked at above, and proposed a solution. The solution was to introduce a new type, JSX.ElementType.

To illustrate the what JSX.ElementType actually is as compared to a JSX element, consider this illustration:

// <Component />
//  ^^^^^^^^^    JSX element type
// ^^^^^^^^^^^^^ JSX element

The significance of JSX.ElementType is that it is used to represent the type of a JSX element and allow library authors to control what types are used for JSX elements. This control was not available before.

The TypeScript pull request was merged, and so Sebastian (who helps maintain the React type definitions) exercised the new powers in this pull request to the DefinitelyTyped repository for the React type definitions. At the time of writing, this pull request is still open, but once merged and shipped the React community will feel the benefits.

The changes are subtle; You can see in this pull request that ReactElement | null is generally replaced with ReactNode:

     type JSXElementConstructor<P> =
-        | ((props: P) => ReactElement<any, any> | null)
+        | ((props: P) => ReactNode)
         | (new (props: P) => Component<any, any>);

Remember how we mentioned earlier on that function components couldn't return numbers? Let's look at the updated tests in the PR:

    const ReturnNumber = () => 0xeac1;
+   const FCNumber: React.FC = ReturnNumber;
    class RenderNumber extends React.Component {
        render() {
          return 0xeac1;
        }
    }

With this change, React components that return numbers are now valid JSX elements. This is because JSX.ElementType is now ReactNode, which includes numbers. Essentially this represents that new things are possible as a consequence of this change. The library and type definition author now has more control over what is possible in JSX.

To quote Sebastian again:

Now we have control over any potential component type.

Let's look again at our component that produces a number again:

function ComponentThatReturnsANumber() {
  return 42;
}

<ComponentThatReturnsANumber />;

With Sebastian's changes, this becomes valid TypeScript. And as React, and other JSX libraries evolve, TypeScript compatibility can also.

Summary

The TL;DR of this post is "TypeScript will better allow for the modelling of JSX in TypeScript 5.1". I'm indebted to Sebastian Silbermann and Daniel Rosenwasser for their explanations of this feature. Thanks in particular to Sebastian for implementing this feature and for reviewing this post.

I hope this post helps you understand the feature a little better.

This post was originally published on LogRocket.

Azure Container Apps, Bicep, managed certificates and custom domains

John Reilly — Sat, 17 Jun 2023 20:16:49 +0000

Azure Container Apps support managed certificates and custom domains. However, deploying them with Bicep is not straightforward - although it is possible. It seems likely there's a bug in the implementation in Azure, but I'm not sure. Either way, it's possible to deploy managed certificates and custom domains using Bicep. You just need to know how.

If, instead, you're looking to make use of the "bring your own certificates" approach in Azure Container Apps using Bicep, then you might want to take a look at this post on the topic.

I've facetiously subtitled this post "a three pipe(line) problem" because it took three Azure Pipelines to get it working. This is not Azure Pipelines specific though, it's just that I was using Azure Pipelines to deploy the Bicep. Really, this applies to any way of deploying Bicep. GitHub Actions, Azure CLI or whatever.

If you're here because you've encountered the dread message:

Creating managed certificate requires hostname '....' added as a custom hostname to a container app in environment 'caenv-appname-dev'

Then you're in the right place. I'm going to explain how to get past that error message and get your custom domain working with your Azure Container App whilst still using Bicep. It's going to get ugly. But it will work.

A three pipe(line) problem

I spent much of the last week attempting to attach a custom domain to an Azure Container App. I was using Bicep to deploy the infrastructure and I was using Azure DevOps to deploy the Bicep.

There wasn't any documentation I could find about this, and so I decided to try and work it out for myself. I was able to get it working, but it was a bit of a journey. I'm going to share the steps I took here in the hope that it helps someone else.

I titled this section "A three pipe(line) problem" because it turned out it required three Azure Pipeline runs to deploy a custom domain with a managed certificate. That, and the fact that it seemed a great way to get a Sherlock Holmes pun into the mix. I feel justified; there was no small amount of detective work involved.

Reverse engineering the Bicep from the Azure Portal

I knew that to get a custom domain working with an Azure Container App I would need to do two things:

Create a managed certificate on my managed environment
Create a custom domain on my container app

So I fired up the Azure Portal and did those two things. Then I went to the export template option and downloaded the ARM template. I was hoping to see how the Azure Portal did it. Since my eyes bleed a little when I attempt to read ARM templates, I decompiled the ARM template into the Bicep equivalent.

It actually seemed relatively simple. First there was a Microsoft.App/managedEnvironments/managedCertificates resource which created the managed certificate:

resource managedEnvironmentManagedCertificate 'Microsoft.App/managedEnvironments/managedCertificates@2022-11-01-preview' = {
  parent: managedEnvironment
  name: '${managedEnvironment.name}-certificate'
  location: location
  tags: tags
  properties: {
    subjectName: customDomainName
    domainControlValidation: 'CNAME'
  }
}

Then there was the addition of a customDomains property to the Microsoft.App/containerApps resource which referenced the managed certificate:

resource containerApp 'Microsoft.App/containerApps@2022-11-01-preview' = {
  //...
  properties: {
    configuration: {
      //...
      ingress: {
        //...
        customDomains: [
          {
            name: managedEnvironmentManagedCertificate.properties.subjectName
            certificateId: managedEnvironmentManagedCertificate.id
            bindingType: 'SniEnabled'
          }
        ]
        //...
      }
      //...
    }
    //...
  }
  //...
}

It looked simple enough. I added those two resources to my Bicep file and ran the pipeline. It failed. I got this error:

Creating managed certificate requires hostname '....' added as a custom hostname to a container app in environment 'caenv-appname-dev'

Googling that error message didn't lead me to this issue on the Azure Container Apps GitHub repo. Other people were having similar issues. I was able to gather enough clues from that issue to get me to a working approach. I may be the first person in the world to have got this far... Wouldn't that be special?

The three pipe(line) solution

So whilst the original approach I came up with looked like it should work, it did not. What succeeded was an approach where I ran one pipeline to deploy some Bicep, a second pipeline to deploy some tweaked Bicep, and a third pipeline to deploy some more tweaked Bicep. Then profit.

Herewith the details of the three pipelines / three Bicep deployments:

Bicep template 1: Create a disabled custom domain

Our first Bicep template is going to create a custom domain on our container app. However, we're going to set the bindingType property to Disabled.

resource containerApp 'Microsoft.App/containerApps@2022-11-01-preview' = {
  //...
  properties: {
    configuration: {
      //...
      ingress: {
        //...
        customDomains: [
          {
            name: customDomainName
            bindingType: 'Disabled'
          }
        ]
        //...
      }
      //...
    }
    //...
  }
  //...
}

Deploy the above template and you'll have a custom domain on your container app, but it won't be active. This will be graduated to an active custom domain in the third Bicep template.

Bicep template 2: Create the managed certificate

Now we're going to create the managed certificate by adding the following resource to our Bicep template:

resource managedEnvironmentManagedCertificate 'Microsoft.App/managedEnvironments/managedCertificates@2022-11-01-preview' = {
  parent: managedEnvironment
  name: '${managedEnvironment.name}-certificate'
  location: location
  tags: tags
  properties: {
    subjectName: customDomainName
    domainControlValidation: 'CNAME'
  }
}

At present there's no relation between the managed certificate and the custom domain. We'll fix that in the third Bicep template. Deploy this template and you'll have a managed certificate. However, the deployment will likely fail with an following error of the following form:

{
  "status": "Failed",
  "error": {
    "code": "AuthorizationFailed",
    "message": "The client 'GUID-GOES-HERE' with object id 'GUID-GOES-HERE' does not have authorization to perform action 'Microsoft.App/locations/managedCertificateOperationStatuses/read' over scope '/subscriptions/SUBSCRIPTION-ID-GOES-HERE/providers/Microsoft.App/locations/West Europe/managedCertificateOperationStatuses/GUID-GOES-HERE' or the scope is invalid. If access was recently granted, please refresh your credentials."
  }
}

Don't sweat it. You should have a managed certificate. That's what we need.

Bicep template 3: Create an active custom domain

Ready for the big finish? We're going to take our Bicep template back to what we originally tried:

resource managedEnvironmentManagedCertificate 'Microsoft.App/managedEnvironments/managedCertificates@2022-11-01-preview' = {
  parent: managedEnvironment
  name: '${managedEnvironment.name}-certificate'
  location: location
  tags: tags
  properties: {
    subjectName: customDomainName
    domainControlValidation: 'CNAME'
  }
}

resource containerApp 'Microsoft.App/containerApps@2022-11-01-preview' = {
  //...
  properties: {
    configuration: {
      //...
      ingress: {
        //...
        customDomains: [
          {
            name: managedEnvironmentManagedCertificate.properties.subjectName
            certificateId: managedEnvironmentManagedCertificate.id
            bindingType: 'SniEnabled'
          }
        ]
        //...
      }
      //...
    }
    //...
  }
  //...
}

Note that the customDomains property of the Microsoft.App/containerApps resource now references the managed certificate and is SniEnabled. Deploy this template and you'll have a working managed certificate and a working custom domain on your container app. Huzzah!

Conclusion

I write this post purely to help others who may be struggling with this. I'm assuming this is some kind of bug, and I'm hoping the Azure Container Apps team will fix it soon. I've raised a specific issue on the Azure Container Apps GitHub repo for this problem. You can find it here.

Attributions

Pipe icon in title image created by Freepik - Flaticon

Azure Container Apps, Easy Auth and .NET authentication

John Reilly — Sun, 11 Jun 2023 08:17:20 +0000

Liquid syntax error: Unknown tag 'endraw'

Private Bicep registry authentication with AzureResourceManagerTemplateDeployment@3

John Reilly — Sun, 04 Jun 2023 08:36:15 +0000

If you deploy Bicep templates to Azure in Azure DevOps, you'll likely use the dedicated Azure DevOps task; the catchily named AzureResourceManagerTemplateDeployment@3. This task has had support for deploying Bicep since early 2022. But whilst vanilla Bicep is supported, there's a use case which isn't supported; private Bicep registries.

"Unable to restore the module... Status: 401 (Unauthorized)"

Private Bicep registries are a great way to share Bicep modules across your organisation. We use them in the organisation that I'm part of; it's a good a way to help us move faster and to share common security baselines.

Alas it turns out that the AzureResourceManagerTemplateDeployment@3 task doesn't presently play well with private Bicep registries. This is because it's necessary to authenticate to a private registry before you can consume modules. And that's not supported by the AzureResourceManagerTemplateDeployment@3 task. What does that mean? Well take a look at the following Azure Pipeline:

- task: AzureResourceManagerTemplateDeployment@3
  name: DeployInfra
  displayName: Deploy infra
  retryCountOnTaskFailure: 3
  inputs:
    deploymentScope: Resource Group
    azureResourceManagerConnection: ${{ variables.serviceConnection }}
    subscriptionId: $(subscriptionId)
    action: Create Or Update Resource Group
    resourceGroupName: $(resourceGroupName)
    location: $(location)
    templateLocation: Linked artifact
    csmFile: 'infra/main.bicep'

You'll note that it passes a Bicep file to the csmFile property. This is the file that will be deployed. But what if that file references modules from a private registry? Well, you'll see an error like this:

As you can see from the Status: 401 (Unauthorized), we have an authentication problem; the task doesn't know how to authenticate to the private registry.

Workaround

You might think, "oh well that's it then, I can't use private Bicep registries with the AzureResourceManagerTemplateDeployment@3 task". But you'd be wrong. There's a workaround. Essentially, when the AzureResourceManagerTemplateDeployment@3 task runs, it attempts to restore the modules it needs as a first step to compiling the Bicep in to ARM. But it only does this if it needs to. If we perform the restore manually first, then the task won't need to do it again. That's the trick.

Before the AzureResourceManagerTemplateDeployment@3 task runs, we can run a task to restore the modules. We can use the AzureCLI@2 task to do this. Here's an example:

- task: AzureCLI@2
  displayName: Bicep restore
  inputs:
    azureSubscription: service-connection-with-access-to-registry
    scriptType: bash
    scriptLocation: inlineScript
    inlineScript: |
      bicep restore infra/main.bicep

Where service-connection-with-access-to-registry is an Azure Resource Manager service connection using service principal authentication which has access to the private Bicep registry.

So if the above task runs prior to the AzureResourceManagerTemplateDeployment@3 task, then the modules will be restored and the AzureResourceManagerTemplateDeployment@3 task will be able to compile the Bicep in to ARM and deploy it to Azure. This solves the problem; albeit at the cost of an extra task in the pipeline.

In the box, in the future?

It would be tremendous if authentication to private Bicep registries was supported by the AzureResourceManagerTemplateDeployment@3 task. I've raised a feature request for this here. If you'd like to see this too, please do add your voice to the issue.

Static Web Apps CLI and Node.js 18: could not connect to API

John Reilly — Sun, 21 May 2023 08:50:06 +0000

I make use of Azure Static Web Apps a lot. I recently upgraded to Node.js 18 and found that the Static Web Apps CLI no longer worked when trying to run locally; the API would not connect when running swa start:

[swa] ❌ Could not connect to "http://localhost:7071/". Is the server up and running?

This post shares a workaround.

The issue

My own setup is a Vite front end and a Function App back end. I have a package.json in the folder of the front end app with the following scripts:

"dev": "vite",
"start": "swa start http://localhost:5173 --run \"npm run dev\" --api-location ../FunctionApp"

I could see both front end and back end starting up in the console, but inevitably the SWA CLI would report:

[swa] ❌ Could not connect to "http://localhost:7071/". Is the server up and running?

It turned out this came down to the version of Node.js I was using. I was using Node.js 18. Or rather it was due to an issue with a dependency of the Static Web Apps CLI; the wait-on library which waits for endpoints to become available. With Node.js 18 this is broken. It's not clear a fix is imminent.

The workaround

Various workarounds are suggested in this GitHub issue. I shared my own there, and I'm sharing it here too. (Mostly for me, I'll lay money I need this again and again.)

In the root of my project I installed concurrently:

npm i concurrently

Then, again in the root of my project I added the following scripts:

"debug": "concurrently -n \"staticwebapp,functionapp\" -c \"bgBlue.bold,bgMagenta.bold\" \"npm run debug:staticwebapp\" \"npm run debug:functionapp\"",
"debug:staticwebapp": "cd src/StaticWebApp && npm run debug",
"debug:functionapp": "cd src/FunctionApp && func start",

What's happening here is that I'm running the Static Web Apps CLI and the Function App CLI in separate processes, and running them concurrently when we run npm run debug. You'll note that the debug:staticwebapp script is running another debug script with the Static Web Apps CLI in the src/StaticWebApp folder:

"debug": "swa start http://localhost:5173 --run \"npm run dev\" --api-location http://127.0.0.1:7071",

The --api-location flag is pointing to the endpoint the Function App is surfaced at. This is the key to the workaround.

Summary

This takes us back to having a setup that will work with Node.js 18. Hopefully this is only needed for a short while, but it's good to have a workaround in the meantime.

TypeScript 5: importsNotUsedAsValues replaced by ESLint consistent-type-imports

John Reilly — Tue, 09 May 2023 14:55:00 +0000

I really like type imports that are unambiguous. For this reason, I've made use of the "importsNotUsedAsValues": "error" option in tsconfig.json for a while now. This option has been deprecated in TypeScript 5.0.0, and will be removed in TypeScript 5.5.0. This post will look at what you can do instead.

What `"importsNotUsedAsValues": "error"` provided

Prior to TypeScript 5.0, if you wanted to make your type imports explicit, you could use the "importsNotUsedAsValues": "error" option in tsconfig.json. This would mean that you would need to use import type for type imports, and import for value imports. Consider the following:

import { ResourceGraphClient } from '@azure/arm-resourcegraph';

In my code I was only using ResourceGraphClient as a type, so I would need to change it to:

import type { ResourceGraphClient } from '@azure/arm-resourcegraph';

import { type ResourceGraphClient } from '@azure/arm-resourcegraph';

And if I rebelled, the TypeScript compiler would complain:

This import is never used as a value and must use 'import type' because 'importsNotUsedAsValues' is set to 'error'.ts(1371)

TypeScript 5 deprecates `importsNotUsedAsValues`

However, when I upgraded to TypeScript 5, I started seeing the following error:

Option 'importsNotUsedAsValues' is deprecated and will stop functioning in TypeScript 5.5. Specify compilerOption '"ignoreDeprecations": "5.0"' to silence this error. Use 'verbatimModuleSyntax' instead.

The error was the result of this pull request. The message made me think I just needed to migrate to verbatimModuleSyntax, like so:

```diff title="tsconfig.json"

"importsNotUsedAsValues": "error",
"verbatimModuleSyntax": true, ```

However, when I did so, my terminal became a sea of errors:

src/telemetry.ts:7:13 - error TS1286: ESM syntax is not allowed in a CommonJS module when 'verbatimModuleSyntax' is enabled.

import * as task from './task.json';
            ~~~~

src/telemetry.ts:9:1 - error TS1287: A top-level 'export' modifier cannot be used on value declarations in a CommonJS module when 'verbatimModuleSyntax' is enabled.

export async function sendTelemetry({

It turns out that in verbatimModuleSyntax, you can't write ESM syntax in files that will emit as CommonJS - which is exactly what my codebase is doing. Andrew Branch, who is part of the TypeScript team, sent me an explanation from a draft of some new TypeScript docs:

In TypeScript 5.0, a new compiler option called verbatimModuleSyntax was introduced to help TypeScript authors know exactly how their import and export statements will be emitted. When enabled, the flag requires imports and exports in input files to be written in the form that will undergo the least amount of transformation before emit. So if a file will be emitted as ESM, imports and exports must be written in ESM syntax; if a file will be emitted as CJS, it must be written in the CommonJS-inspired TypeScript syntax (import fs = require("fs") and export = {}). This setting is particularly recommended for Node projects that use mostly ESM, but have a select few CJS files. It is not recommended for projects that currently target CJS, but may want to target ESM in the future.

It further turns out that importsNotUsedAsValues was never intended to be used in in the way that I did; effectively as a linting mechanism. Andrew said this on the topic:

importsNotUsedAsValues was made to serve the opposite purpose you (and basically everyone) were using it for. By default, TypeScript elides unneeded import statements from JS emit even without marking them as type imports. importsNotUsedAsValues was created as a way to escape that behavior, not (primarily) to make it more explicit. verbatimModuleSyntax allows you to escape the elision behavior, and takes the explicitness of what your imports mean a step further by making you write CJS-style imports when emitting to CJS. So in my book, all the important cases that importsNotUsedAsValues (and preserveValueImports) covered, plus more, are covered by verbatimModuleSyntax, which is way more explainable. It’s mostly a matter of reducing complexity for the sake of explanation.

Until the world has finished migrating to ES Modules (which will be a while), I'm going to need to stick with CommonJS as my emit target, whilst still planning to write ES Module imports in my code. But I really like being explicit about my imports. So what can I do?

ESLint and `@typescript-eslint/consistent-type-imports` to the rescue

I mentioned that I was using importsNotUsedAsValues essentially as a linting mechanism. And it transpires that the answer to my need lives in ESLint itself. There's a rule named @typescript-eslint/consistent-type-imports which tackles exactly this. If you're using ESLint and typescript-eslint, you can add this rule to your .eslintrc.js:

```js title="eslintrc.js"
module.exports = {
// ...
rules: {
// ...
'@typescript-eslint/consistent-type-imports': 'error', // the replacement of "importsNotUsedAsValues": "error"
},
};




Or if you prefer to have the type imports inline, you can use:



```js title="eslintrc.js"
module.exports = {
  // ...
  rules: {
    // ...
    '@typescript-eslint/consistent-type-imports': [
      'error',
      {
        fixStyle: 'inline-type-imports',
      },
    ], // the replacement of "importsNotUsedAsValues": "error"
  },
};

With this in place, we're back to where we were before; just with a different engine:

All imports in the declaration are only used as types. Use import type.eslint@typescript-eslint/consistent-type-imports

And we even have the ability to auto-fix the errors as well now. Thanks typescript-eslint!

`no-import-type-side-effects`

We are not quite done. There's another typescript-eslint rule that we can use to help us. no-import-type-side-effects is a rule that will warn you if you have any side effects in your type imports. What does that mean? Well, consider the following code:

import { type A, type B } from 'mod';

// is transpiled to
import {} from 'mod';

// which is the same as
import 'mod';

You may not want a runtime import at all. You can do that by using a top-level type qualifier for imports when it only imports specifiers with an inline type qualifier:

import type { A, B } from 'mod';

// is transpiled to.... nothing! Hence no side effects

So if side effects is something you're concerned about, consider this rule as well. Note that whether import { type A } from 'mod' transpiles to a side-effect import or gets completely removed depends on your tsc options, or what transpiler you’re using. But import type statements always get removed.

Summary

Thanks to Andrew Branch for reviewing this post, and massively improving it! Any mistakes are mine, not his.

Migrating Azure Functions from JSDoc JavaScript to TypeScript

John Reilly — Mon, 08 May 2023 06:15:30 +0000

I wrote previously about how to implement a dynamic redirect mechanism for Azure Static Web Apps using Azure Functions. I implemented this using JSDoc JavaScript. I've since migrated this to TypeScript and I thought it would be interesting to share the process.

Why migrate from JSDoc JavaScript to TypeScript?

As regular readers will know, I'm both a big fan of TypeScript and a big fan of JSDoc JavaScript. I think both are great. So why migrate from JSDoc JavaScript to TypeScript? For me it's mostly about the developer experience; JSDoc is more verbose, and the wider ecosystem does a lot more TypeScript than it does JSDoc JavaScript. So when you get beyond a simple application, for me at least, TypeScript is a better choice.

My blog is an Azure Static Web App with an Azure Functions back end. I've been using JSDoc JavaScript for my Azure Functions. This post will take the back end and migrate it to TypeScript. There's various affordances that I have in place already that I don't want to lose along the way:

I can debug in VS Code
I deploy using GitHub Actions
I have automated tests in place using Jest

All of these affordances are available to me with TypeScript, and I want to keep them. Let's begin migrating. Incidentally, the code for this migration lies in this PR.

Migrating the `tsconfig.json`

Our tsconfig.json manages the way the TypeScript compiler interacts with our code. We'll start by migrating this:

```diff title="tsconfig.json"
{
"compilerOptions": {

"noEmit": true,
"noEmit": false,
"outDir": "dist",
"rootDir": ".",
"sourceMap": true,
"allowJs": false,
"checkJs": false,
"moduleResolution": "node",
}
}

Let's look at the changes we've made:

We're now emitting files from our compilation thanks to noEmit being set to false. We will no longer be actually running the code we write, but we will run the JavaScript we emit.
We're specifying an outDir of dist - this is where our compiled JavaScript will be emitted.
We're specifying a rootDir of . - this is the root of our TypeScript source files.
We're creating source maps for our emitted JavaScript files - this will help us debug our original source code. (Even though we're not running it.)
We're no longer allowing JavaScript files to be part of our program thanks to allowJs being set to false. (And we're not checking them either thanks to checkJs being set to false - I suspect this is implicitly set to false to allowJs being false - just to be clear I've specified it.)
We're specifying a moduleResolution of node - this is how TypeScript will look up a file from a given module specifier.

Migrating the `package.json`

To migrate our package.json we'll need to add some dependencies and tweak our scripts:

```diff title="package.json"
"scripts": {
"build": "tsc",

"watch": "tsc -w",
"prestart": "npm run build", "start": "func start", "test": "jest" }, "devDependencies": { "@azure/functions": "^3.5.0",
"@types/jest": "^29.2.5",
"@types/node": "^18.x", "jest": "^29.3.1",
"ts-jest": "^29.1.0", "typescript": "^5.0.0" } } ```

We're adding two scripts:

watch - this will watch our TypeScript files and recompile them when they change - we don't need this really; but it can be useful depending on your preferred workflow.
prestart - this will run before start and will ensure our TypeScript files are compiled, and we have up to date JavaScript to run.

In our devDependencies we're adding dependencies for Jest and Node.js. We're also adding ts-jest which will allow us to run Jest tests written in TypeScript.

Migrating `.vscode/settings.json` and `.vscode/tasks.json`

I mentioned debugging earlier - to get that in place we need to work on the settings.json and tasks.json files in the .vscode folder. First the settings.json:

```diff title="settings.json"

"azureFunctions.projectLanguage": "JavaScript",
"azureFunctions.projectLanguage": "TypeScript", ```

The above is pretty self explanatory. We're changing the language of our Azure Functions project from JavaScript to TypeScript. Now the tasks.json:

```diff title="tasks.json"
{
"version": "2.0.0",
"tasks": [

{
"type": "shell",
"label": "npm build (functions)",
"command": "npm run build",
"dependsOn": "npm install (functions)",
"problemMatcher": "$tsc",
"options": {
"cwd": "${workspaceFolder}/blog-website/api"
}
}, ] } ```

We've got a new task in place here that runs our npm run build script. This will compile our TypeScript files to JavaScript. We've also got a cwd set to blog-website/api - this is the folder where our Azure Functions live - your own will likely be different. Alongside this new script, there's some tweaks to existing tasks to make them depend on our new build task:

```diff title="tasks.json"
{
"version": "2.0.0",
"tasks": [
{
"type": "func",
"label": "func: host start",
"command": "host start",
"problemMatcher": "$func-node-watch",
"isBackground": true,

"dependsOn": "npm build (functions)",
"options": {
"cwd": "${workspaceFolder}/blog-website/api"
} }, // ... { "type": "shell", "label": "npm prune (functions)", "command": "npm prune --production",
"dependsOn": "npm build (functions)", "problemMatcher": [], "options": { "cwd": "${workspaceFolder}/blog-website/api" } } ] } ```

Migrate our Azure Functions

This isn't going to be an exhaustive guide of migrating from JSDoc JavaScript to TypeScript. I'm going to focus on the things that I found most relevant to Azure Functions. Let's start with the fallback/function.json file that powers our dynamic redirects and lives at /api/fallback:

```diff title="fallback/function.json"
{
"bindings": [
{
"authLevel": "anonymous",
"type": "httpTrigger",
"direction": "in",
"name": "req",
"methods": ["get", "post"]
},
{
"type": "http",
"direction": "out",
"name": "res"
}
],

"scriptFile": "../dist/fallback/index.js" } ```

There's one addition here, to repoint the scriptFile to the compiled JavaScript.

Now let's look at the code for the function. Originally a JavaScript file named index.js; it must be renamed to index.ts. The original code looked like this:

```js title="fallback/index.js"
const redirect = require('./redirect');
const saveToDatabase = require('./saveToDatabase');

/**
*

@param { import("@azure/functions").Context } context
@param { import("@azure/functions").HttpRequest } req */ async function fallback(context, req) { //... }

module.exports = fallback;




After renaming to `index.ts` and adding some TypeScript types, it looks like this:



```ts title="fallback/index.ts"
import type { AzureFunction, Context, HttpRequest } from '@azure/functions';

import { redirect } from './redirect';
import { saveToDatabase } from './saveToDatabase';

const httpTrigger: AzureFunction = async function (
  context: Context,
  req: HttpRequest
): Promise<void> {
  //...
};

export default httpTrigger;

As we can see, the type importing becomes much more succinct. We're also exporting the function as default rather than module.exports. This is because we're using ES Modules rather than CommonJS modules for authoring. We can also see that we're using import rather than require to import our functions. Whilst CommonJS was more straightforward to use, the syntax for ES Modules feels much nicer to use; at least to me. (It's worth noting that we're not using ES Modules in our compiled JavaScript - we're still using CommonJS there; but we don't need to think about that when we're writing our code.)

I won't walk through migrating the other files, but the process is the same. Rename the file to .ts, add TypeScript types, and use import rather than require.

Migrating our tests

We're pretty much on the home stretch now; we just need to migrate our tests. Let's start with the jest.config.js:

```diff title="jest.config.js"

preset: 'ts-jest',
testPathIgnorePatterns: ['/node_modules/', '/dist/'], ```

We're adding a preset of ts-jest which will allow us to run TypeScript tests. If you recall we added the ts-jest dependency earlier; it was for this.

We're also adding dist to our testPathIgnorePatterns - this is because we don't want to run our tests against our compiled JavaScript - we'd end up running the tests twice without this.

Let's turn our attention to the tests directly. Again we do the classic rename from .js to .ts, and our imports become terser and more ES Module-y:

```diff title="redirect.test.ts"
-/**

* @typedef { import("@azure/functions").Logger } Logger
*/ +import type { Logger } from '@azure/functions'; -const { describe, expect, test } = require('@jest/globals'); +import { describe, expect, test } from '@jest/globals'; -const redirect = require('./redirect'); +import { redirect } from './redirect'; ```

Beautiful. Finally we've got some tweaks to the code of the tests themselves. Firstly, declaring our mock becomes much easier:

```diff title="redirect.test.ts"
-/** @type {jest.Mock} */ const mockLogger = jest.fn();
+const mockLogger: jest.Mock = jest.fn();




Secondly, casting our mock to the type we want is much more straightforward:



```diff title="redirect.test.ts"
-/** @type {any} */ (mockLogger)
+mockLogger as unknown as Logger

I have no real how to as cast twice in JSDoc - and now I don't need to.

Conclusion

We now have a TypeScript Azure Functions codebase, with all of the debugging / testing / deployment affordances we had before. We didn't have to do anything around deployment, because it just works™️. I hope this post has been useful to you!

Teams Direct Message API with Power Automate

John Reilly — Thu, 04 May 2023 07:29:27 +0000

I've written previously about sending Teams notifications using a webhook, and it's a technique I've used a lot. But I've always wanted to be able to send a direct message to a user, and that's not possible with the webhook approach. I work with a marvellous fellow named Chris Tacey-Green, and he's figured out a way to do this using Power Automate and the Teams Notification API. I'm going to describe how he did it here, with a little help from him.

It's probably worth saying, both Chris and I work for Investec, and we're going to share some of the things we've learned about using Teams and Power Automate in the hope that it's useful to others. But we're not speaking on behalf of Investec, and we're not suggesting that this is the best way to do things. This is likely in the "do things that do not scale" category. Significantly though, it works!

You will see some screenshots of our internal Teams environment, but we've tried to keep them to a minimum, and we're not going to share any sensitive information.

What are we trying to do?

Teams is a great way to keep people informed of what's going on. But sometimes you want to send a message to a specific person. You can @mention them in a channel, but that's not the same as a direct message. And you can send them an email, but that's not the same as a direct message either. What we want is a way to send a direct message to a user in Teams, via an API. Because we want to automate. Tragically, sending DMs in Teams via an API is not supported at the time of writing (or if it is - please let us know!)

All is not lost.

Power Automate

Power Automate is a tool that allows you to automate tasks. It's a low-code/no-code tool that allows you to create workflows that can be triggered by events. It's a great tool for automating tasks. And it's a great tool for sending direct messages in Teams. Or so it turns out.

You see, it's possible to send a notification to a user in Teams using the Teams Notification API. And it's possible to trigger a Power Automate workflow using the "when a new channel message is added" trigger. So if we can get a notification to the Teams Notification API, we can trigger a Power Automate workflow. And if we can trigger a Power Automate workflow, we can send a direct message to a user in Teams.

This post will do two things:

Describe how to set up a Power Automate workflow that sends a direct message to a user in Teams
Describe how to trigger that workflow using the Teams Notification API and Adaptive Card messages

Setting up the Power Automate workflow

First things first, we need to create a Power Automate workflow that sends a direct message to a user in Teams. This is pretty straightforward, but when it came to doing this, I knew nothing.

Before we start this, I should warn you there's going to be lots of screenshots. As far as I'm aware, there's not a code-first way to create Power Automate flows, so point and click is the only game in town.

The first thing to do, is fire up Teams and install the Power Automate app:

This allows us to access the Power Automate app. There we can create a new workflow (from blank) with the "when a new channel message is added" trigger:

We then need to select the team and channel that we want to trigger the workflow:

You'll note in the screenshot above, we've got a dedicated channel for this workflow. This is because we don't want to disturb channels people are already using with the messages we will write to this channel. To all intents and purposes, this channel could actually be invisible to users - we just need it to exist to be our carrier pidgeon.

With the trigger in place, we need to create the action. We're going to use the "apply to each" control, which will run for every message that comes through. We want to use the "Message mentions" output, which will give us the user that was mentioned in the message. We don't want to use the similarly named "Message mentions item":

The message mention gives us our user, we'll then use the "Get user profile (V2)" operation so we can look up that user up.

It's at this point, that we start to do something slightly more complicated in the Power Automate UI. We're going to need to supply an id to the "Get user profile (V2)" operation. We're going to use an expression to determine this id. The expression we're going to use is:

triggerOutputs()?['body/mentions'][0].mentioned.user.id

This expression is operating on JSON similar to the following:

{
  "@odata.type": "#microsoft.graph.chatMessage",
  "etag": "1683099494281",
  "messageType": "message",
  "createdDateTime": "2023-05-03T07:38:14.281Z",
  "lastModifiedDateTime": "2023-05-03T07:38:14.281Z",
  // ...
  "mentions": [
    {
      "id": 0,
      "mentionText": "John Reilly",
      "mentioned": {
        "application": null,
        "device": null,
        "conversation": null,
        "tag": null,
        "user": {
          "@odata.type": "#microsoft.graph.teamworkUserIdentity",
          "id": "my-id-it-is-a-guid",
          "displayName": "John Reilly",
          "userIdentityType": "aadUser"
        }
      }
    }
  ]
  // ...
}

So that expression is just some JavaScript that gets us to the value we need; the id of the first mentioned user. We provide that in the "Expression" field and then click the "OK" button:

Now it's time for our final action - sending on the message with the "post card in chat or channel" operation:

We'll post as the Flow bot, post in a chat with the Flow bot and make our recipient "Mail" (which behind the scenes is the expression outputs('Get_user_profile_(V2)')?['body/mail']).

Finally, it's once more expression time, as we use this value for our Adaptive Card:

triggerOutputs()?['body/attachments'][0]['content']

Hopefully, what you've realised is that we're just taking the Adaptive Card from the message that triggered the workflow and passing it on to the recipient. We're intentionally doing as little as possible in the Power Automate workflow, as it's the trickiest part of our solution to work with. (Debugging Power Automate workflows is possible, but it's not the most fun you'll ever have.)

We now have our complete workflow, and it looks like this:

Triggering the Power Automate workflow

Whilst we have a workflow, we don't have anything to trigger it yet. To do that, we'll need to send a message to the channel we created earlier. We can do this using the Teams Notification API. And it needs to be a special kind of message; it needs to be an Adaptive Card, which includes a mention of the person we want to direct message.

My post on sending Teams notifications using a webhook describes how to send a message to a channel using the Teams Notification API. We're going to use the same technique, but we're going to send an Adaptive Card instead of a plain message. I won't repeat the details of creating a webhook connector here, instead let's just focus on what we need to send to the API.

Ultimately, it's just a POST request to the webhook connector, with a JSON body that looks like this:

{
  "type": "message",
  "attachments": [
    {
      "contentType": "application/vnd.microsoft.card.adaptive",
      "contentUrl": null,
      "content": {
        "type": "AdaptiveCard",
        "version": "1.0",
        "body": [
          {
            "type": "TextBlock",
            "size": "medium",
            "text": "Hey <at>John Reilly</at>!\n\nYou have 102 unresolved secret findings! Click on the button below to view them.",
            "wrap": true
          }
        ],
        "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
        "msteams": {
          "entities": [
            {
              "type": "mention",
              "text": "<at>John Reilly</at>",
              "mentioned": {
                "id": "John.Reilly@investec.co.uk",
                "name": "John Reilly"
              }
            }
          ]
        },
        "actions": [
          {
            "type": "Action.OpenUrl",
            "title": "View findings",
            "url": "https://some.url.com/",
            "role": "button"
          }
        ]
      }
    }
  ]
}

The part that's relevant to us is the msteams property. This is where we specify the user we want to mention. We do this by specifying the id and name properties. The id property is the email address of the user we want to mention. The name property is the display name of the user we want to mention.

This is the secret sauce that allows our Power Automate flow to work. It reads these values and uses them to send a message to the user we want to mention. Alongside that, the msteams.entities[].text property must be in your message body. That's what Teams uses to link the mention to the part of the message that's "doing the mentioning" (thanks Chris for pointing this out).

Testing it out

So far, so screenshots and code. Does it work? Let's find out.

When we run our tool for triggering the Teams Notification API, we get a message in our channel:

Note that it has the @mention of the user: me. Now that this message in the relevant channel exists, our Power Automate workflow will be triggered. I've seen it take between 2 and 10 minutes for the trigger to fire. When it does, the flow runs and we get a direct message from the Flow bot:

And this is our handrolled direct message to a user in Microsoft Teams. It's the same message we sent to the channel, just forwarded on by the Flow bot. Brilliant. The eagle eyed amongst you will note the ugly <at id="0">John Reilly</at>; we're losing something in our forwarding. This could be remedied if we made our Power Automate flow a little more complex, but as mentioned, we're trying to keep our flow as simple as possible. The <at id="0"> is a small price to pay for the simplicity of our flow.

User blocked the conversation with the bot

As you look at your Power Automate Flow runs, you can sometimes spot failures along these lines:

If you look to the right on that screenshot you can see the error message:

Request to the Bot framework failed with error:

{
  "error": {
    "code":"ConversationBlockedByUser",
    "message":"User blocked the conversation with the bot."
  }
}

These kinds of failures appear to be a consequence of someone having blocked the Power Automate Flow bot. If you dig into the inputs ("Click to download" in the screenshot) you can discover the user who blocked the bot and have a conversation with them about it. Unblocking seems to be fairly straightforward; you just need to right-click / ctrl-click on the Power Automate app in Teams and select "Unblock":

In our experience, this is a rare occurrence, but it's worth being aware of.

Conclusion

Together we've built a mechanism for sending a direct message to a user in Microsoft Teams. We've used the Teams Notification API to send a message to a channel, and we've used Power Automate to pick up that message and send it on to the user we want to mention.

Thanks so much to Chris for coming up with this novel way of sending a direct message to a user in Microsoft Teams. I hope you've found this post useful.

Docusaurus: Structured Data FAQs with MDX

John Reilly — Sat, 08 Apr 2023 20:30:07 +0000

import FAQStructuredData from "../../src/theme/MDXComponents/FAQStructuredData";

export const faqs = [
{
question: "How do I use the FAQ Structured Data component?",
answer:
"Simply create an import statement for the component and then use it in your MDX file. You'll need to pass in an array of FAQs. This array can be inline, you can declare it as a variable, or you can import it from another file.",
},
{
question: "How do I use the FAQ Structured Data component in a blog post?",
answer:
"The usage is the same as in a regular MDX file. But the import statement will sit after the frontmatter of the blog post.",
},
{
question:
"Can I use the FAQ Structured Data component in a regular MD file?",
answer: "Yes! It just works™️.",
},
];

I've written previously about using Structured Data with React. This post goes a little further and talks about how to use Structured Data with Docusaurus and MDX. More specifically it looks at how to create a component that both renders FAQs into a page, and the same information as Structured Data.

FAQs and Structured Data

I've been working with Growtika to repair my SEO after shredding it somehow last year. One of the experiments we ran was to add FAQs to a post, and with that, the equivalent FAQ Structured Data. The intent being to see if this would help with the SEO for that post.

My blog is written in MDX, and hosted on Docusaurus. I wanted to see if I could create an MDX component that would render the FAQs into a page, and the same information as Structured Data. The Docusaurus docs suggested this was feasible, and I wanted to see if I could make it work.

And it turns out that other people are interested in this too; there's a feature request on Docusaurus's Canny for exactly this.

So I created a component that could be used to render FAQs into a page as markdown, and the same information as Structured Data. I thought it would be useful to share that component with the world. Hello world, herewith the component:

The FAQStructuredData MDX component

I created a directory called FAQStructuredData in the `src/theme/MDXComponents directory. This directory is where I keep my custom MDX components. I then created an index.js file in that directory. This is the file that contains the component:

`jsx title="src/theme/MDXComponents/FAQStructuredData/index.js"
/**

@typedef { import('./types').FAQStructuredDataProps } FAQStructuredDataProps
@typedef { import('./types').FAQStructuredData } FAQStructuredData */

import React from 'react';

/**

A component that renders a FAQ structured data and markdown entries *
@see https://developers.google.com/search/docs/appearance/structured-data/faqpage
@param {FAQStructuredDataProps} props
@returns
/
export default function FAQStructuredData(props) {
/* @type {FAQStructuredData} */ const faqStructuredData = {
'@context': 'https://schema.org',
'@type': 'FAQPage',
mainEntity: props.faqs.map((faq) => ({
'@type': 'Question',
name: faq.question,
acceptedAnswer: {
'@type': 'Answer',
text: faq.answer,
},
})),
};
return (
<>
<br> {JSON.stringify(faqStructuredData)}<br>

FAQs
{faqStructuredData.mainEntity.map((faq) => (
{faq.name}
{faq.acceptedAnswer.text} ))} </> ); } `

`ts title="src/theme/MDXComponents/FAQStructuredData/types.d.ts"
export interface FAQ {
question: string;
answer: string;
}

export interface FAQStructuredDataProps {
faqs: FAQ[];
}

export interface FAQStructuredData {
'@context': string;
'@type': string;
mainEntity: FAQQuestionStructuredData[];
}

export interface FAQQuestionStructuredData {
'@type': 'Question';
name: string;
acceptedAnswer: {
'@type': 'Answer';
text: string;
};
}
`

Some things to note about this component:

The code is written in JavaScript, but it's using TypeScript types via JSDoc. I don't believe you can write MDX components in TypeScript (please someone let me know if it turns out this is possible). But static typing is useful, and still possible thanks to JSDoc.
On that, we have a types.d.ts file that contains the types for the component. Using TypeScript directly is still possible alongside JSDoc, as long as there is no runtime code in the file, and a definition file (which the types.d.ts file is), has no runtime code. We can simply use it to store types that we import into the component.
The component expects an faqs prop. This is an array of FAQs. Each FAQ is an object with a question and answer property. The component then renders the FAQs as markdown, and the same information as JSON-LD Structured Data. We're using the Google guidelines for FAQ Structured Data.
The component renders a h2 tag titled "FAQs". Under that, each FAQ is rendered with a h3 tag and the answer sits directly below it.

Importing our MDX component

Now the FAQStructuredData component is created, we can use it in our MDX (or straight MD) files. We can import the component and create an array called faqs like so:

`mdx

slug: docusaurus-structured-data-faqs-mdx
title: 'Docusaurus: Structured Data FAQs with MDX'
authors: johnnyreilly
tags: [Docusaurus, Structured Data]
image: ./title-image.png
description: 'This demos how to make an MDX component that renders FAQs into a page, and the same information as Structured Data. It also shows how to use it with Docusaurus.'

hide_table_of_contents: false

import FAQStructuredData from '../../src/theme/MDXComponents/FAQStructuredData';

export const faqs = [
{
question: 'How do I use the FAQ Structured Data component?',
answer:
"Simply create an import statement for the component and then use it in your MDX file. You'll need to pass in an array of FAQs. This array can be inline, you can declare it as a variable, or you can import it from another file.",
},
{
question: 'How do I use the FAQ Structured Data component in a blog post?',
answer:
'The usage is the same as in a regular MDX file. But the import statement will sit after the frontmatter of the blog post.',
},
{
question:
'Can I use the FAQ Structured Data component in a regular MD file?',
answer: 'Yes! It just works™️.',
},
];

;
`

Note we're doing this in a blog post and the import statement is after the frontmatter. Then we can use the component like so:

`mdx <FAQStructuredData faqs={faqs} /> `

We'll do that, right here, right now:

Testing the Structured Data

You can see, we have FAQs rendered in the body of our blog post. If we put the URL of the post into the Google Structured Data Testing Tool, we can see that the Structured Data is being rendered correctly:

We can even go one better, shortly after I posted this article, I did a search in Google for "how do you have Docusaurus with Structured Data FAQs with MDX" and I got this:

That's our FAQs being surfaced as a featured snippet. Nice!

Conclusion

We've now got a reusable FAQs component that renders the FAQs as markdown, and the same information as Structured Data. We can use it in our MDX files, and we can use it in our blog posts. We can also use it in regular MD files. Yay! I've only used this in the context of Docusaurus, but I suspect it can be used in other contexts too.

I'd rather like it if this was built into Docusaurus, and if it could read directly from the Markdown files. But this is a good start. I hope you find it useful.

Forem: John Reilly

Azure Open AI: handling capacity and quota limits with Bicep

Viewing capacity and quota limits in the Azure Open AI Studio

Controlling capacity and quota limits with Bicep

Azure Pipelines meet Vitest

Tests run as part of our pipeline

Report test results in Azure Pipelines UI

Putting it all together

Azure Container Apps, Bicep, bring your own certificates and custom domains

Make a certificate

Container apps environment and certificates

Bicep for the custom domain

Conclusion

Attributions

TypeScript 5.1: declaring JSX element types

What's the problem?

The arrival of JSX.ElementType

Summary

Azure Container Apps, Bicep, managed certificates and custom domains

A three pipe(line) problem

Reverse engineering the Bicep from the Azure Portal

The three pipe(line) solution

Bicep template 1: Create a disabled custom domain

Bicep template 2: Create the managed certificate

Bicep template 3: Create an active custom domain

Conclusion

Attributions

Azure Container Apps, Easy Auth and .NET authentication

Private Bicep registry authentication with AzureResourceManagerTemplateDeployment@3

"Unable to restore the module... Status: 401 (Unauthorized)"

Workaround

In the box, in the future?

Static Web Apps CLI and Node.js 18: could not connect to API

The issue

The workaround

Summary

TypeScript 5: importsNotUsedAsValues replaced by ESLint consistent-type-imports

What "importsNotUsedAsValues": "error" provided

TypeScript 5 deprecates importsNotUsedAsValues

ESLint and @typescript-eslint/consistent-type-imports to the rescue

no-import-type-side-effects

Summary

Migrating Azure Functions from JSDoc JavaScript to TypeScript

Why migrate from JSDoc JavaScript to TypeScript?

Migrating the tsconfig.json

Migrating the package.json

Migrating .vscode/settings.json and .vscode/tasks.json

Migrate our Azure Functions

Migrating our tests

Conclusion

Teams Direct Message API with Power Automate

What are we trying to do?

Power Automate

Setting up the Power Automate workflow

Triggering the Power Automate workflow

Testing it out

User blocked the conversation with the bot

Conclusion

Docusaurus: Structured Data FAQs with MDX

FAQs and Structured Data

The FAQStructuredData MDX component

FAQs

{faq.name}

Importing our MDX component

`mdx

hide_table_of_contents: false

Testing the Structured Data

Conclusion

The arrival of `JSX.ElementType`

What `"importsNotUsedAsValues": "error"` provided

TypeScript 5 deprecates `importsNotUsedAsValues`

ESLint and `@typescript-eslint/consistent-type-imports` to the rescue

`no-import-type-side-effects`

Migrating the `tsconfig.json`

Migrating the `package.json`

Migrating `.vscode/settings.json` and `.vscode/tasks.json`