• A single default (parameter less) private constructor.
  It prevents other classes from instantiating it. It also prevent subclassing. If it gets subclasses, then those classes can create an instance and pattern is violated. Factory pattern can be used if you need single instance of the base type, but the exact type is known until runtime.

• The class is sealed. Unnecessary, due to the above point, but may help the JIT to optimise.

• A static variable which holds a reference to the single created instance.

• A public static means of getting the reference to the single created instance

Naive Singleton

public sealed class NaiveSingleton
{
    private static NaiveSingleton? _instance;

    // private constructor to prevent instantiation from outside
    private NaiveSingleton() { }

    // public method to get the instance of the singleton
    public static NaiveSingleton GetInstance()
    {
        if (_instance == null)
        {
            _instance = new NaiveSingleton();
        }
        return _instance;
    }
}

This particular method isn’t thread safe. Two different threads can evaluate _instance == null as true and then both of those threads will create a new instance of the Singleton.

Thread Safe Using Double-Check Locking

public sealed class Singleton
{
    private static Singleton? _instance;
    private static readonly object _lock = new object();

    // private constructor to prevent instantiation from outside
    private Singleton() { }

    // Public method to get the instance of the singleton
    public static Singleton GetInstance()
    {
        if (_instance == null)
        {
            lock (_lock)
            {
                if (_instance == null)
                {
                    _instance = new Singleton();
                }
            }
        }
        return _instance;
    }
}

Imagine that the program has just been launched.
Since, there's no Singleton instance yet, multiple threads can simultaneously pass the first if (_instance == null) conditional and reach to the point where it request a lock on the object lock(_lock) almost at the same time. The first of them will acquire lock and will proceed further, while the rest will wait here.
The first thread to acquire the lock, reaches the second if (_instance == null)conditional, goes inside and creates the Singleton instance. Once it leaves the lock block, a thread that might have been waiting for the lock release may then enter this section. But since the Singleton field is already initialized, the thread won't create a new object.

Sometimes, you might find the first conditional missing and directly locking the object. But this attempts to reduce the overhead of locking by first checking if the instance exists outside of the lock, and only locking if it's not instantiated already.

Volatile with Java

It doesn't work in Java. Odd thing to mention here, but if there’s a chances you’ll be writing playing around Java too.
Java allowed instruction reordering by Java compiler. So another thread could see _instance != null before the constructor is finished running, leading to strange bugs like using an incompletely constructed object. (chatgpt if you’re curious here).
To prevent this redording you must use volatile keyword in Java to prevent this reordering.

for your reference, java code with double check locking and using volatile keyword.

public class Singleton {
    private static volatile Singleton instance;

    private Singleton() { }

    public static Singleton getInstance() {
        if (instance == null) {
            synchronized (Singleton.class) {
                if (instance == null) {
                    instance = new Singleton();
                }
            }
        }
        return instance;
    }
}

Somewhat Lazy, Thread-safe without locks

public sealed class Singleton
{
    private static readonly Singleton _instance = new Singleton ();

    // - Explicit static constructor to tell C# compiler not to mark type as beforefieldinit.
    // - static constructors in C# are specified to execute only 
    //   when an instance of the class is created or a static member is referenced, 
    //   and to execute only once per AppDomain 
    // - not as lazy. if you have static members other than Instance, 
    //   the first reference to those members will involve creating the instance.
    static Singleton () { }

    // private constructor to prevent instantiation from outside
    private Singleton () { }
}

But why is it thread-safe and how lazy is it?
In C#, a static constructor runs automatically the first time you either create an object of the class or access one of its static members—and it only runs once for the entire lifetime of the application (within each AppDomain).
It is not as lazy, i.e. if you have static members other than _instance, the first reference to those members will involve creating the instance.

Full Lazy Instantiation

public sealed class Singleton
{
    // private so no one can create an instance of this class
    private Singleton() { }

    public static Singleton Instance
    {
        get
        {
            // instantiation is triggered by the first 
            // reference to the static member of the nested class,
            // which only occurs in Instance.
            return Nested.Instance;
        }
    }

    private class Nested
    {
        // static constructor is called only once, when the type is first accessed.
        // it ensures that the instance is created in a thread-safe manner.
        static Nested() { }

        internal static readonly Singleton Instance = new Singleton();
    }
}

Read comments inline. Instantiation is triggered by the first reference to the static member of the nested class. So this only run the static constructor of Nested class when the Nested.Instance is referenced and it is only referenced in the enclosing class.

Using Lazy<T>

It provides lazy initialization with access from multiple threads.

public sealed class Singleton
{
    private static readonly Lazy<Singleton> _lazyInstance =
        new Lazy<Singleton>(() => new Singleton());

    // private constructor to prevent instantiation from outside
    private Singleton() { }

    // Public method to get the instance of the singleton
    public static Singleton Instance
    {
        get
        {
            return _lazyInstance.Value;
        }
    }
}

Use lazy initialization to defer the creation of a large or resource-intensive object, or the execution of a resource-intensive task, particularly when such creation or execution might not occur during the lifetime of the program.
Lazy<T> initialization occurs the first time the Lazy.Value property is accessed.

You can use LazyThreadSafetyMode to specify how Lazy<T> instance synchronizes access among multiple threads.
Lazy<Singleton> _lazy = new Lazy<Singleton>(() => new Singleton(), LazyThreadSafetyMode.ExecutionAndPublication);

• LazyThreadSafetyMode.None - The Lazy<T> instance is not thread safe; if the instance is accessed from multiple threads, its behavior is undefined.

• LazyThreadSafetyMode.PublicationOnly - When multiple threads try to initialize a Lazy<T> instance simultaneously, all threads are allowed to run the initialization method (or the parameterless constructor, if there is no initialization method). The first thread to complete initialization sets the value of the Lazy instance.This is referred to as Publication in the field names. That value is returned to any other threads that were simultaneously running the initialization method, unless the initialization method throws exceptions on those threads. Any instances of T that were created by the competing threads are discarded. Effectively, the publication of the initialized value is thread-safe in the sense that only one of the initialized values can be published and used by all threads.

• LazyThreadSafetyMode.ExecutionAndPublication - Locks are used to ensure that only a single thread can initialize a Lazy instance in a thread-safe manner. Effectively, the initialization method is executed in a thread-safe manner (referred to as Execution in the field name). Publication of the initialized value is also thread-safe in the sense that only one value may be published and used by all threads.

References:
- https://refactoring.guru/design-patterns/singleton
- https://csharpindepth.com/Articles/Singleton

Thanks for reading.

LinkedIn: https://www.linkedin.com/in/ankurcharan
Twitter: https://twitter.com/ankurcharan

Now if you need some way to export the swagger api documentation during your build for CI/CD or any other things, this is for you.

Pre-requisite

I am assuming you already have a service from which you can access the swagger JSON/UI.

Generating Swagger on Build

set up dotnet-tools

• Run dotnet new tool-manifest at root of your project.

• it will create a .config directory with dotnet-tools.json in it. this file will have references to the packages that you've installed.

• install swashbuckle cli. run dotnet tool install --local Swashbuckle.AspNetCore.Cli

add post build step

• in the project csproj file, add a new post build step.

• add step

<Target Name="SwaggerGenerate" AfterTargets="PostBuildEvent">
    <Exec Command="dotnet tool restore" />
    <Exec Command="dotnet swagger tofile --output /path/to/swagger.json .\$(OutputPath)$(AssemblyName).dll v1" />
</Target>

• OutputPath and AssemblyName are the project variable, and they have the path to where the build is and .dll is generated.

• If you have multiple version of the APIs, you can have v1 or v2 in the second command.

• Build your csproj and your openapi spec (swagger json) is created during the build.

PostScript

Feel free to reach out to me if you need any help.

linkedin.com/in/ankurcharan
instagram.com/ankurcharan
dev.to/ankurcharan
twitter.com/ankurcharan
ankurcharan.hashnode.dev

Here we'll automate the entire API deployment using bicep scripts.

If you're not too familiar with BICEP, you can use the Microsoft Bicep Docs

Azure Resource Group

Create a resource group on azure portal that you want to deploy APIM into. I have created api-devops resource group.

Virtual Network

Without Virtual Network (VNet)

You can skip the virtualNetworkConfiguration and virtualNetworkType properties modules\apiManagement.bicep when creating the APIM instance.

For this article, I am going to create this in a private VNet.

Within Private Virtual Network (VNet)

• Create a VNet and a subnet for APIM within the VNet.

• Created subnet apim-subnet in VNet that I will use.

  

• Get the resource id of the subnet using az-cli.

  

• Copy the id (resourceId) of the subnet. You will need it later.

Bicep Refresher

This is a very basic refresher of what we need. Please refer Bicep Docs for more in-depth documentation.

• param <param-name> <param-type>
  this is to tell that the template accepts a parameter <param-name> of type <param-type>
  Ex. param x string - accepts a parameter x of type string.
  type can be array, object, int, string

• param <param-name> <param-type> = <default-value>
  if a value is not passed for the parameter, its default value is used.

• module <symobolic-name> <path-to-file> = <params>
  we can declare the resources in modules and re-use the module in templates.

• [for i in list] - add a for loop to the templates

• if (condition) - only deploy resources if the condition is true

Deployment

After each step, you can verify your deployment using az-cli.
az deployment group create --resource-group api-devops --template-file apim.bicep --parameters ./apim.parameters.json

Create APIM Instance

• Check the code at https://github.com/ankurcharan/azure-api-management-devops/tree/createApim

• At modules/apiManagement.bicep it accepts multiple parameters and then we can create the instance of APIM.

resource apiManagementService 'Microsoft.ApiManagement/service@2021-08-01' = {
  name: apiManagementInstanceName
  location: location
  tags: tags
  sku: {
    capacity: skuCount
    name: sku
  }
  properties: {
    publisherEmail: 'ankurcharan@outlook.com'
    publisherName: 'Ankur Charan'
    virtualNetworkConfiguration: {
      subnetResourceId: subnetResourceId
    }
    virtualNetworkType: virtualNetworkType
  }
}

Parameters:

• name: name of the apim instance

• location: azure region you want the instance to be created in

• sku:

  • capacity: capacity of the sku (number of deployed units of the sku)

  • name: name of the sku

• properties:

  • publisherEmail: email of publisher

  • publisherName: name of publisher

Note: You can skip the below VNet configurations if you want to use a public-facing backend. If you want to use a private VNet then you can use these two configurations.

• virtualNetworkType: The type of VPN in which API Management service needs to be configured in. None (Default Value) means the API Management service is not part of any Virtual Network, External means the API Management deployment is set up inside a Virtual Network having an Internet Facing Endpoint, and Internal means that API Management deployment is setup inside a Virtual Network having an Intranet Facing Endpoint only.
  Allowed values are 'External', 'Internal' and 'None'.

• virtualNetworkConfiguration.subnetResourceId: it takes the resource id of the subnet if you want this to have a private VNet.

With this much, you will have an API Management instance running in your resource group.

• and then we have declared the output values of the instance created

output name string = apiManagementInstanceName
output resourceId string = apiManagementService.id
output apimGatewayUrl string = apiManagementService.properties.gatewayUrl

• this module is used at apim.bicep

module apiManagementService 'modules/apiManagement.bicep' = {
    name: apiManagementServiceName
    params: {
        tags: tags
        apiManagementInstanceName: apiManagementServiceName
        location: location
        subnetResourceId: subnetResourceId
        virtualNetworkType: 'External'
    }
}

To create the APIM instance, it used the module defined above. Also the outputs received from this module can be used later.

• Parameters file

  • We also have parameters file apim.parameters.json which currently only has two parameters.

  • apiManagementServiceName will be the name of your APIM instance.

  • subnetResourceId is the resource id of your apim subnet.

• APIM instance created

Adding global policy

We will add a global policy that will apply to all APIs in the APIM. I have kept it empty and would just forward all requests as it is. You can read more about APIM policies at https://learn.microsoft.com/en-us/azure/api-management/api-management-policies

• Check the code at https://github.com/ankurcharan/azure-api-management-devops/tree/globalPolicy

• Added a new xml file policies/global-policy.xml this is the global policy xml.

• A new step is added at modules/apiManagement.bicep

resource globalPolicy 'Microsoft.ApiManagement/service/policies@2021-12-01-preview' = {
  name: 'policy'
  parent: apiManagementService
  properties: {
    value: loadTextContent('../policies/global-policy.xml')
    format: 'rawxml'
  }
}

• Parameters

  • parent is given the APIM instance. it is used to create resource names for ARM templates. You can read more at https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/child-resource-name-type

  • format is the format of the policy. It supports different formats. We are giving it XML. So it's rawxml

  • value is the contents of the policy.

• loadTextContent('path/to/file') is a bicep function that loads the contents of the file to the bicep.

• You can check the global policy from the Azure portal. Go to API from the left nav. Click on All APIs. and that is where your contents of global policy would reflect.

Swagger

• Check the code at https://github.com/ankurcharan/azure-api-management-devops/tree/swaggerFile

• Added a swagger specification at api-spec/jsonplaceholder.json

• Normally, you would create this file in the build pipeline and then use it to deploy APIs. I have added this explicitly for simplicity.

• Swagger is an api-specification tool, checkout swagger.io. And you can have a demo at https://editor.swagger.io/

Adding APIs

• Checkout the code at https://github.com/ankurcharan/azure-api-management-devops/tree/api

• Now here is a new module at modules/apiManagement.api.bicep

resource api 'Microsoft.ApiManagement/service/apis@2021-01-01-preview' = {
  parent: service
  name: apiServiceName
  properties: {
    description: apiServiceDescription
    type: 'http'
    isCurrent: true
    subscriptionRequired: false
    displayName: apiServiceDisplayName
    serviceUrl: apiServiceUrl
    path: suffix
    protocols: [
      protocol
    ]
    value: apiSpecification
    format: specificationFormat
    apiType: 'http'
  }
}

• value is the api-specification content. In our case the swagger file.

• format is the format of the api-spec used. If its OpenApi3.0 (openapi / openapi+json) or if its Swagger2.0 (swagger-json) of it its link to the swagger.

• We have used this module in apim.bicep

• There is a new parameter apiInformation with the default value being array of api information objects. You can pass the value of this from the parameter file but then you have to serialize the swagger specification file in a string and then pass it. Using bicep, it gives us a function loadTextContent('path') which does that for you. And since this is not going to change much if you're doing this for same application (or multi-region / multi-tenant) then we can use this default value of the parameters.

• this also has another resource declaration

resource service 'Microsoft.ApiManagement/service@2021-08-01' existing = {
  name: apiManagementServiceName
}

• existing keyword checks for existing resources.

• this checks the api management instance that exists with the name apiManagementServiceName and then proceeds with creating the API.

• using this module from apim.bicep

module apisDeploy 'modules/apiManagement.api.bicep' = [for (config, i) in apiInformation: {
    name: '${i}-${config.apiName}-import-${apiManagementServiceName}'
    params: {
        apiSpecification: config.apiSpecContent
        apiServiceUrl: config.serviceUrl
        apiServiceDisplayName: config.apiDisplayName
        apiServiceName: config.apiName
        suffix: config.suffix
        apiManagementServiceName: apiManagementServiceName
        specificationFormat: config.specificationFormat
    }
}]

• we have traversed the array of api information and used it to create all the apis that are defined in the array. this is useful if you have multiple microservices that you want to expose to the customers and manage through APIM i.e. if you're going to add more apis add another item in apiInformation array and you're done.

• apiInfomation[0] object is

{
    apiName: 'json-placeholder'
    apiDisplayName: 'JsonPlaceholder'
    specificationFormat: 'openapi+json'
    suffix: '/jp'
    serviceUrl: 'https://jsonplaceholder.typicode.com/'
    apiSpecContent: loadTextContent('api-spec/jsonplaceholder.json')
}

• apiName is the name of the api to be used for referencing it if you want to create products or policies etc.

• apiDisplayName is what you'll see on the portal.

• specificationFormat is the format of the api-specification.

• serviceUrl is the backend url of the service.

• apiSpecContent is the specification content of the apis.

• dependsOn - this is an array of resources that your current resource is dependent on.

dependsOn: [
    apiManagementService
]

this means that current resource deployment depends on the resource represented by the symbolic name apiManagementService (apim instance, cause obviously, you'd want to create the APIs only if APIM exists).

• APIs added to APIM instance

you can also see all the operations (endpoints/routes) are added to APIM.

Adding API Policy

• You might want to add api-specific policies on APIM.

• Check code at https://github.com/ankurcharan/azure-api-management-devops/tree/apiPolicy

• In apim.bicep we have added a new line in apiInformation to load the contents of the policy. policyContents: loadTextContent('policies/apiPolicy-jsonplaceholder.xml')

• added a new API policy at policies/apiPolicy-jsonplaceholder.xml

• added a policy deployment module at modules/apiManagement.api.policy.bicep

• api policy is deployed against an api so it first checks that the particular API already exists in the APIM

// checks if API exists
resource api 'Microsoft.ApiManagement/service/apis@2021-01-01-preview' existing = {
  parent: service
  name: apiServiceName
}

// add APIs policy
resource apiPolicy 'Microsoft.ApiManagement/service/apis/policies@2021-01-01-preview' = {
  parent: api
  name: 'policy'
  properties: {
    value: policyXML
    format: xmlFormat
  }
}

• notice how we have added api as the parent of apiPolicy. So now we don't have to explicitly add a dependsOn property for the resource.

• this module is used at apim.bicep

module apiPolicyDeploy 'modules/apiManagement.api.policy.bicep' = [for (config, i) in apiInformation: {
    name: '${i}-${config.apiName}-policy'
    params: {
        apiManagementServiceName: apiManagementServiceName
        apiServiceName: config.apiName
        policyXML: config.policyContents
    }
    dependsOn: [
        apisDeploy
    ]
}]

• apiServiceName is the api name in the APIM instance for which to deploy policies.

• policyXML is the contents of the policy. You can read more about APIM policies at https://learn.microsoft.com/en-us/azure/api-management/api-management-policies.

• You can see the API policy at

• Whatever policy you have added for your API will be updated here.

Final Code

You can browse through the final code at https://github.com/ankurcharan/azure-api-management-devops/tree/main

You can run this template and this would automate your APIM creation and API deployment using Swagger.

Let me know if you want to add more features of the APIM to this template like Products, Subscriptions, Groups, LogAnalytics Workspace etc.

Thanks for reading.**Ankur Charan**

LinkedIn: https://www.linkedin.com/in/ankurcharan
Twitter: https://twitter.com/ankurcharan

You can have modules to divide your arm templates into multiple groups. And you refer the existing resources to get their property values. (You can do this in ARM also, the syntax is easier in Bicep).

You also have a VSCode extension with intelli-sense to help you write Bicep templates. BicepExtension

ARM to Bicep

with CLI

Once, you have installed bicep-tools, you can use the command az bicep decompile --file <armTemplateFile>.json to convert them to bicep.
Although it is a best effort decompilation. It attempts to convert the file, but there is no guaranteed mapping from ARM template JSON to Bicep. You may need to fix warnings and errors in the generated Bicep file. Or, decompilation can fail if an accurate conversion isn't possible.

manual

Once you have decompiled, you can manually reduce the errors and warnings. Or you can convert the entire template.

If you have worked with ARM template, there format is

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",

  "parameters": {
    // parameters
  },
  "resources": [
    {
      "type": "<resourceType>",
      "apiVersion": "<apiVersion>",
      "name": "<resourceName>",
      "location": "<resourceLocation>",
      "properties": {
        // resource properties
      }
    }
  ],
  "outputs": {
    // trimmed
  }
}

So all of the properties and values are still the same. But the syntax is a little different. (bicep syntax highlighting is not available here)

resource <resourceSymbolicName> '<resourceType>@<apiVersion>' = {
  name: '<resourceName>'
  location: 'resourceLocation'
  properties: {
    // properties
  }
}

Example

Lets say you want to create key azure key vault.

with ARM

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "parameters": {
    "name": {
      "type": "string",
      "metadata": {
        "description": "Required. key vault name."
      }
    },
    "location": {
      "type": "string",
      "metadata": {
        "description": "Required. location of the key vault"
      }
    }
  },
  "resources": [
    {
      "type": "Microsoft.KeyVault/vaults",
      "apiVersion": "2023-02-01",
      "name": "[parameters('name')]",
      "location": "[parameters('location')]",
      "properties": {
        "sku": {
          "family": "A",
          "name": "standard"
        },
        "tenantId": "[subscription().tenantId]",
        "enabledForDeployment": true,
        "enabledForTemplateDeployment": true,
        "enabledForDiskEncryption": false,
        "enableSoftDelete": true
      }
    }
  ],
  "outputs": {
    "name": {
      "type": "string",
      "value": "[parameters('name')]"
    },
    "vaultUri": {
      "type": "string",
      "value": "[reference(resourceId('Microsoft.KeyVault/vaults', parameters('name')), '2023-02-01').vaultUri]"
    }
  }
}

This template deploys the key vault and has some properties set for the resource.

with Bicep

You can have the same template as above in Bicep as below. (again no syntax highlighting for Bicep yet)

@description('Required. key vault name.')
param name string

@description('Required. location of the key vault')
param location string

resource kv 'Microsoft.KeyVault/vaults@2023-02-01' = {
  name: name
  location: location
  properties: {
    sku: {
      family: 'A'
      name: 'standard'
    }
    tenantId: subscription().tenantId
    enabledForDeployment: true
    enabledForTemplateDeployment: true
    enabledForDiskEncryption: false
    enableSoftDelete: true
  }
}

// outputs
output name string = kv.name
output vaultUri string = kv.properties.vaultUri

Now if you match, you can see this is just easier to write and the intelli-sense from VSCode Bicep Extension will help alot.

And all the other things that Bicep brings, like modules and using dot operator to access the properties of existing resource.

PostScript

Read more at bicep-documentation. Feel free to reach out to me if you need any help.

linkedin.com/in/ankurcharan/
instagram.com/ankurcharan/
dev.to/ankurcharan
twitter.com/ankurcharan