DEV Community: Kevin Boosten

How I use an OpenAPI spec in my Angular projects

Kevin Boosten — Thu, 11 Feb 2021 00:00:00 +0000

If you are working on a project that has an OpenAPI spec, then you can generate your Angular Code and even generate a simulator for development and test purposes. This reduces time and complexity of integrating with a OpenAPI gateway tremendously. Let me show you how I use OpenAPI to boost up my productivity!

Here is a brief introduction if you’re not familiar with OpenAPI in general:

The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to RESTful APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined, a consumer can understand and interact with the remote service with a minimal amount of implementation logic.

Or maybe you know Swagger, so what’s the difference? Check it out here: Differences between Swagger and OpenAPI.

OpenAPI Generator

So your backend colleague gave you the endpoint of their api so you can start integrating your web application with some real data. So what will be your next step? You’re quite a Typescript enthousiast and want to make sure that your web application has some type safety, so you start typing out some TS interfaces that we can use. Okay, check ✅. Next step? Maybe add some abstraction and reusability to your stack? So you create an Angular Service that uses the HttpClient and so wraps the actual endpoint. Sounds good and eventually this will be a good approach. But it feels a bit repetitive to do this for every project again. Besides that, I think you can spend your time better on building actual features for your application, right?

So what if we could automate these steps to safe some precious time 🧐? In a few steps we can generate Angular specific code based on our OpenAPI spec. Let’s get started 👨‍💻!

Create Angular app

First install the Angular CLI if you dont have this installed already:

npm install -g @angular/cli

Start with a new angular app and choose the default options:

ng new angular-openapi-demo
cd angular-openapi-demo

Start the application to verify everything went well:

ng serve

Create an OpenAPI yaml file

A well defined api comes with some documentation. An api built with OpenAPI comes with a yaml, or JSON, spec that describes the actual api. We can build this spec by creating a yaml file in our application. In order to have a real working api, we will use the well known JSON Placeholder public test api.

Add a file openapi.yaml to the root of your application and add the following content:

You can also download the file from the demo repo

openapi: 3.0.0
info:
  title: JSON Placeholder OpenAPI
  description: Example spec of the well known JSON Placeholder website
  version: 0.1.9
servers:
  - url: https://jsonplaceholder.typicode.com
paths:
  /posts:
    get:
      summary: Returns a list of Posts.
      description: Optional extended description in CommonMark or HTML.
      operationId: GetPosts
      responses:
        '200':
          description: A JSON array of Posts
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Post'
components:
  schemas:
    Post:
      required:
        - id
        - userId
        - title
        - body
      type: object
      properties:
        id:
          type: number
          description: record id
          example: 1
        userId:
          type: string
          description: unique user identifier
          example: 2
        title:
          type: string
          description: title of this Post
          example: sunt aut facere repellat provident occaecati excepturi optio reprehenderit
        body:
          type: string
          description: description of this post
          example: quia et suscipit\nsuscipit recusandae consequuntur expedita et cum\nreprehenderit molestiae ut ut quas totam\nnostrum rerum est autem sunt rem eveniet architecto

I think that this kind of documenting is quite self explanatory, but let’s discuss a couple of things:

Post: this is a way of defining a model. We can use this model by using the $ref keyword.
servers: here we define one or more base url’s for our spec.
example: give a hint about what value to expect. Later on I will explain you why this is handy when creating a simulator.

Tip! Make working with OpenApi spec easier in VSCode by installing the Swagger Viewer extension

Generate Angular Services

We’re going to generate our Angular code with the CLI of openapi-generator. We can install this via NPM as devDependency:

npm i @openapitools/openapi-generator-cli -D

This packages has a lot of generators available, we’re going to use the typescript-angular one.

Add a npm script to your package.json file for more convenient usage:

{
  "scripts": {
    // other scripts
    "generate:api": "openapi-generator-cli generate -i ./openapi.yaml -g typescript-angular -o src/app/core/api/v1"
  }
}

We use the default configuration over here. But you can customize this based on your needs.

One example could be the option removeOperationIdPrefix to prevent redundant method names. Take for example the following operationId in your spec:

operationId: Posts_GetPosts

The generator will use the operationId to determine the Angular Service name and the method name. If we use the default configuration, our class will look like this:

// this looks redundant
export class PostsService {
  public postsGetPosts() {}
}

// and when you invoke it, it is redundant and looks weird...
const postsService = new PostsService();
postsService.postsGetPosts();

Using the arguments -p=removeOperationIdPrefix=true will remove the Posts_ part of the operationId: Posts_GetPosts

// this looks redundant
export class PostsService {
  public getPosts() {}
}

That already looks better to me! As I said, there’re plenty configuration options. And you probably will be using some of them from time to time depending on the spec you receive.

Next step is to actually generate our code with our custom NPM script:

npm run generate:api

We now have the following directory structure because we told the generator to output (-o) to the src/app/core/api/v1 directory:

Use generated NgModule and services

The most important parts of the generated code are the following files:

posts.services.ts: the actual Angular service.
post.ts: a TS interface that matches the Post model of our OpenAPI spec.
api.module.ts: a NgModule that can be imported to your AppModule.
README.md: README file with usage instructions.

Add this ApiModule to your AppModule. This will use the ‘default’ server endpoint that is available in your openapi.yaml. You can see that in the generated posts.service.ts:

@Injectable({
  providedIn: 'root',
})
export class PostsService {
  protected basePath = 'https://jsonplaceholder.typicode.com';
  // ...
}

// without configuring providers
import { ApiModule } from '';
import { HttpClientModule } from '@angular/common/http';

@NgModule({
  imports: [
    ApiModule,
    // make sure to import the HttpClientModule in the AppModule only,
    // see https://github.com/angular/angular/issues/20575
    HttpClientModule,
  ],
  declarations: [AppComponent],
  providers: [],
  bootstrap: [AppComponent],
})
export class AppModule {}

If you want to override or provide a different endpoint, you can do this by passing in a factory function in the forRoot method of the ApiModule:

import { NgModule } from '@angular/core';
import { AppComponent } from './app.component';
import {
  ApiModule,
  Configuration,
  ConfigurationParameters,
} from './core/api/v1';

export function apiConfigFactory(): Configuration {
  const params: ConfigurationParameters = {
    basePath: 'https://staging.jsonplaceholder.typicode.com',
  };
  return new Configuration(params);
}

@NgModule({
  imports: [ApiModule.forRoot(apiConfigFactory)],
  declarations: [AppComponent],
  providers: [],
  bootstrap: [AppComponent],
})
export class AppModule {}

And we can go one step further by moving the basePath to the Angular environment files:

// environment.ts
export const environment = {
  production: false,
  basePath: 'https://dev.jsonplaceholder.typicode.com',
};

// environment.prod.ts
export const environment = {
  production: true,
  basePath: 'https://jsonplaceholder.typicode.com',
};

So now we can import the environment.basePath variable to configure our ApiModule.

There are even more variables in the Configuration object that can be set, see Configuration.ts on the demo repo.

import { NgModule } from '@angular/core';
import { environment } from '../environments/environment';
import { AppComponent } from './app.component';
import {
  ApiModule,
  Configuration,
  ConfigurationParameters,
} from './core/api/v1';

export function apiConfigFactory(): Configuration {
  const params: ConfigurationParameters = {
    basePath: environment.basePath,
  };
  return new Configuration(params);
}

@NgModule({
  imports: [ApiModule.forRoot(apiConfigFactory)],
  declarations: [AppComponent],
  providers: [],
  bootstrap: [AppComponent],
})
export class AppModule {}

Usage example

We can now start using our generated services in our application! Change your app.component.ts to this:

import { Component } from '@angular/core';
import { PostsService } from './core/api/v1';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.css'],
})
export class AppComponent {
  // Create a `cold` observable - we will be subscribing to this observable in the template
  posts$ = this.postService.getPosts();

  // Inject the generated Angular service as a dependency of this class
  constructor(private postService: PostsService) {}
}

And in your app.component.html we can use the posts$ variable by subscribing to it with the async pipe:

<ul>
  <li *ngFor="let post of posts$ | async as list">
    <h2> - </h2>
    <p></p>
  </li>
</ul>

Your browser should now show you a list of Posts from JsonPlaceholder:

🎉 Done! That was all we needed to do to generate ourselves some Angular services and spare us some time.

Next steps

In this example I’m generating and putting my code in my project’s repository. That’s fine for most of my projects because we’re using monorepo’s and also using client specific api’s. Another approach could be to publish your generated code as a NPM package that can be installed by others. These steps are also described by the OpenAPI generator itself in the README. So it depends on your needs which approach fits better.

Simulator

Now that we've generated our Angular services, let’s have a look how wo can utilize the OpenAPI spec even better in our front-end application stack! What we’re going to use for this is a great package called: OpenAPI backend from Viljami Kuosmanen.

As Viljami describes it in one sentence:

OpenAPI Backend is a Framework-agnostic middleware tool for building beautiful APIs with OpenAPI Specification.

OpenAPI backend has a couple of useful features, but the feature that we’re going to use is the auto-mocking responses behavior.

Setting up simulator project

The simulator project will be a independent project but within your current directory structure and so it will also be part of your git repo. So actually we’re going to create a monorepo: a single repository that contains all our code. I’m an advocate when it comes down to monorepos. If you want to learn more about useful tooling around monorepos, then you certainly should check out the following tools:

Lerna - easy to use, quick to set up
NX.dev - managing monorepos like a pro 😉

I’m not going to use any of these tools for the sake of this tutorial.

Let’s get started by creating a directory where our simulator will live and go to the directory:

mkdir simulator
cd simulator

Initialize a new npm project to generate a package.json file:

npm init -y # -y will answer the questions with yes

Install the required dependencies:

npm i openapi-backend # the actual dependency we need :-)
npm i --save-dev typescript # we will be using Typescript, so transpilation needs to be done
npm i express # To serve our simulated endpoints
npm i --save-dev @types/express # typescript types for express
npm i cors
npm i --save-dev @types/cors

As you see we’re using Typescript. We need a tsconfig.json file, you can initialize this with the following command:

npx tsc --init

We used the locally installed typescript compiler by running it via npx. It will run the tsc bin from your local node_modules because we installed it as our devDependency:

Open the generated tsconfig.json file and configure the output directory. Your file should look like this:

{
  "compilerOptions": {
    "target": "es5",
    "module": "commonjs",
    "outDir": "./dist", /* Redirect output structure to the directory. */
    "strict": true, /* Enable all strict type-checking options. */
    "esModuleInterop": true, /* Enables emit interoperability between CommonJS and ES Modules via creation of namespace objects for all imports. Implies 'allowSyntheticDefaultImports'. */
    "skipLibCheck": true, /* Skip type checking of declaration files. */
    "forceConsistentCasingInFileNames": true /* Disallow inconsistently-cased references to the same file. */
   }
}

We’re almost there. Update the npm scripts in your package.json so we can build and run our simulator. Your package.json should now look like this:

{
  "name": "simulator",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "start": "tsc && node dist/index.js"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "dependencies": {
    "cors": "^2.8.5",
    "express": "^4.17.1",
    "openapi-backend": "^3.9.1"
  },
  "devDependencies": {
    "@types/cors": "^2.8.10",
    "@types/express": "^4.17.11",
    "typescript": "^4.2.3"
  }
}

And the last thing we need to do is to actually create a simulator instance with the openapi-backend package. Do this by adding a file called index.ts to your simulator directory and add this content to it:

import cors from 'cors';
import express from 'express';
import OpenAPIBackend, { Request } from 'openapi-backend';

// Create api with your definition file or object. This points to the openapi yaml spec
const api = new OpenAPIBackend({ definition: '../openapi.yaml' });

// Register your framework specific request handlers here
api.register({
  notFound: (c, req, res) => res.status(404).json({ err: 'not found' }),
  notImplemented: (c, req, res) => {
    const { status, mock } = c.api.mockResponseForOperation(
      c.operation.operationId ?? ''
    );
    return res.status(status).json(mock);
  },
});

// Initialize the backend
api.init();

// Initialize the express server that will serve the api backend
const port = 9000;
const app = express();
app.use(express.json());
// Allow cors on all origins - its okay to do this for our simulator
app.use(cors());
app.use((req, res) => api.handleRequest(req as Request, req, res));
app.listen(port, () =>
  console.info(`api listening at http://localhost:${port}`)
);

Registering the notImplemented handler that we will be using to mock the response is the most important part of this configuration. As the documentation states: The notImplemented handler gets called by .handleRequest() if no other Operation Handler has been registered for the matched operation. The mockResponseForOperation method will then mock a response based on the available example data.

Running the simulator

Now run npm start in your simulator directory and open your browser on http://localhost:9000/posts to see some Posts🚀! The response should look like this:

So where is this data actually coming from? Do you remember the example keyword that I mentioned earlier? That’s how we can return some useful response data to our requests. Here you can check out the official documentation about this example keyword.

Using the simulator in our Angular app

Now that we’ve our simulator project configured and running, we can use it in our Angular app. Open the environment.ts file located at: src/environments/environment.ts and change the basePath property to our local running simulator. You file should look like this:

export const environment = {
  production: false,
  basePath: 'http://localhost:9000',
};

This is the default environment file that Angular will use when you run the project with npm start or ng serve without any configuration parameters. You could add a specific environment configuration. Check out the official docs to learn more: https://angular.io/guide/build#configure-environment-specific-defaults

If you still have your Angular app running, then you should now see a single Post record being displayed in your browser. Otherwise restart your Angular app by running npm start in the root of your application. Our Angular application is now running against a local simulator!

Enhancing DX (Developer Experience)

Angular applications already utilizing the npm start command to eventually run ng serve. We need to make some adjustmenst in order to start our Angular application and simultanously start our simulator. I really appreciate it, and actually expect it, when I only have to run two commands to start the project: npm i && npm start. Why? Nobody wants to have some superfluous starter doc that you need to read, handle mentally and do all kinds of set up tasks. To give your project a first good impression it should be ready to use within seconds! I’m not saying you should not have a README.md file, the opposite! The README file could describe other helpful information that your reader should know (e.g. different configurations).

So what’s the problem with the repo that we created along this tutorial? As a developer you now need to:

Run the Angular app via npm start in the root of your application
And start the simulator via npm start in the subdirectory simulator.

In practice this requires the developer to open two terminal windows/tabs and run the commands. Not a great Developer Experience if you ask me. We can do better!

So let’s assume that we want to always run against the simulator in the default configuration, so when running the npm start command. We need to be able to start two tasks in parallel. And maybe you’re already quite familiar with npm, but there’s a package for that called: npm-run-all.

Install it as a devDependency in the root of our project:

npm install npm-run-all --save-dev

Now open the package.json of our root project and alter the scripts section it like this by adding two scripts and changing the start script:

"start": "npm-run-all --parallel start:app start:simulator",
"start:app": "ng serve",
"start:simulator": "npm --prefix simulator start",

I guess the scripts do explain themselves, but here’s a brief description:

start will now use the npm-run-all package to run two other npm scripts. The --parallel flag will run them in parallel.
start:app will start the Angular application
start:simulator will start the simulator. Because its located in a subdirectory, we need to pass the --prefix argument to npm to point it to the simulator directory.

Running the npm start command from the root should now start our Angular app + starting the local simulator! Do not forget to update your README.md file with a sidenote about this behavior.

Custom handlers

As you might have noticed is that our simulator only returns a single record on an endpoint that could return multiple records. This is fine for some situations, but sometimes you’re developing a new feature that incorporates a list of items, or Posts in our context. Returning a single Post will not help you very much if you want to see how your list is working when multiple items are in it. Think about applying staggered animations on lists, filling the available space etc. In this situation the example data is not sufficient for our use-case. What we can do is providing specific handlers for our Openapi operations. A simple example for our Posts api is this:

api.register('GetPosts', function (c, req, res) {
  return res.status(200).json([
    {
      id: 1,
      userId: 1,
      title: 'a',
      body: 'a',
    },
    {
      id: 2,
      userId: 2,
      title: 'b',
      body: 'b',
    },
  ]);
});

You should add this to your simulator/index.ts file before app.init().

This way we created our very own response for the endpoint that is described in our api spec file! Great for developing and testing purposes if you ask me!

Check the docs for more info:https://github.com/anttiviljami/openapi-backend/blob/master/DOCS.md#registeroperationid-handler

When you are going to provide or ‘override’ multiple endpoints, make sure that you keep your simulator code maintainable: so splitting up custom handlers in separate files and keeping your index.ts file clean.

Conclusion

The OpenAPI spec is already very helpful to describe your api’s. I showed you how I utilize this spec to generate code in our Angular application and generate a simulator that we can use for development purposes. What I did not describe is how I use this same simulator to act as a api for my integration tests that I run with Cypress. Another great use-case for your OpenAPI spec!

So, what else could you do with it? Let me know!

How to use Angular environment files in your Azure DevOps multi-stage yml release pipeline

Kevin Boosten — Sat, 16 May 2020 00:00:00 +0000

Angular has the concept of environment files that can be used to configure environment specific values. There are multiple ways to handle environments in your Angular web application.

Create an environment specific .ts file and rebuild the complete application per environment. (e.g. environment.ts, environment.tst.ts, environment.stg.ts, environment.prd.ts). This works, but has the drawback that we need to rebuild the complete application when we go from staging to production. I don’t think we want that.
Put your environment settings in a config.json file in your assets directory and request this file at runtime via the HttpClient during the start up. You could use the APP_INITIALIZER to make sure the environment settings are available before your application code is executed.

There’re already enough articles about this approach. But it introduces extra code and start up dependencies because we’ve to wait for the config.json file to load over http. Of course this is negligible if we compare it to all the other files, but still it’s another request the browser has to make.

Or….just use the default environment files and make use of replacement tokens!

I’ll show you how to do this in a Azure DevOps multi-stage yml pipeline. So besides a way to handle environments in your Angular app, you’ll also learn something about Azure DevOps multi-stage yml release pipelines!

Start with an Angular app

The first thing we need is an minimal Angular app. So let’s start with that:

ng new azure-angular-release-demo --minimal --routing=false

In your project you will find the default generated environment.ts and environment.prod.ts files. Don’t loose them, we’ll need them shortly 😉

Push this repo to your Github or Azure DevOps account so you can use it in Azure DevOps.

Create Azure DevOps project

I assume that you’re already in the ecosystem of Microsoft and you’ve got a Organization where you can create a new project. Otherwise consult the docs.

Create initial pipeline

Now that we have an Angular app and our project set up, we can configure our pipeline. You can do this via the portal or simply create a file azure-pipelines.yml in the root of your repository and add the following content to it:

trigger:
  - master

pool:
  vmImage: "ubuntu-latest"

steps:
  - script: echo Hello, world!
    displayName: "Run a one-line script"

For this demo I’m starting from the portal:

In your DevOps project navigate to Pipelines and select Create Pipeline
Choose the location where you code is. In this demo I used GitHub.
Select your repository
Choose the Starter pipeline
Eventually we want this in our pipeline to start with
Save and run your pipeline to see if it works

Change to multi-stage pipeline

Multi-stage pipelines are the new way to configure your release via code. We were already using the azure-pipeline.yml file to define our build steps, but now we can also use it to deploy our application to several environments. The ‘classic’ way to do this in Azure DevOps is by configuring a release via the portal. This configuration will not be saved to your repository.

Multi-stage pipelines are still in preview, so it’s possible that you have to toggle the preview feature. But at the time of writing I do not see the feature toggle anymore, so maybe it’s not in preview anymore 🎉.

Check their website for more information about multi-stage pipelines.

We are now going to change our starter pipeline to a multi-stage pipeline with three stages. Copy this code to your azure-pipelines.yml file:

trigger:
  - master

pool:
  vmImage: "ubuntu-latest"

stages:
  - stage: build
    jobs:
      - job:
        steps:
          - script: echo Hello, world!

  - stage: deploy_dev
    displayName: Deploy to development
    jobs:
      - job:
        steps:
          - script: echo Hello, world!

  - stage: deploy_prod
    displayName: Deploy to production
    jobs:
      - job:
        steps:
          - script: echo Hello, world!

After committing your changes a new build will start, first thing you will notice are the extra green circles. These are our stages. We now own three stages, all managed by our yml file.

On the detail page of your run you can see some more information to see what is happening per stage. You can even rerun stages if they failed or you want to rerun them with different environment variables.

Configure build stage

We still don’t have anything to deploy other than some echo scripts. It’s building time 👷🏻‍♂!

Add the necessary steps to our yml file to build the Angular app. We will install NodeJS, install our project’s npm dependencies and eventually build and publish an optimized production version.

Change the build stage of our pipeline:

stages:
  - stage: build
    jobs:
      - job:
        steps:
          - task: NodeTool@0
            inputs:
              versionSpec: "10.x"
          - script: npm install
          - script: npm run build -- --prod
          - publish: dist
            artifact: dist

Commit your changes and let DevOps start a new pipeline run. After the run you can validate the output by checking the produced artifacts:

Configure deployment stages

Okay, we are now able to set up, configure and build an Angular application via Azure DevOps ✅👏. This is a great moment to grab yourself a coffee or beer, depending on what time it is 😉.Next stop: the deployment stages.

We are not going to deploy our application to a real server because that goes beyond the scope of this article. Let’s save that for a future article about deploying with ARM templates!

So, what was the actual topic of this article again🤔? When I started writing this article I wanted to focus primarily on handling environment specific settings in an Angular application with the environment.ts file. But why not add a real life example to it with some nice additions about Azure multi-stage yml releases too? So you can release your Angular application properly in Azure.

Change to deployment jobs

We are now going to change the yml file a bit to change our temporary deployment stages to real deployment jobs.

A deployment job is a special type of job. It’s a collection of steps to run sequentially against the environment. In YAML pipelines, we recommend that you put your deployment steps in a deployment job.

- stage: deploy_dev
  displayName: Deploy to development
  jobs:
    - deployment: DeployWeb
      environment: DEV
      strategy:
        runOnce:
          deploy:
            steps:
              - script: echo Hello, development world!

- stage: deploy_prd
  displayName: Deploy to production
  jobs:
    - deployment: DeployWeb
      environment: PRD
      strategy:
        runOnce:
          deploy:
            steps:
              - script: echo Hello, production world!

Not much changes, just following the documentation from Microsoft. Thing that you will notice is the environment setting. This is, in our case, just a label to group our deployment and see the history of our deployments. It also gives you Approval configuration. More about that later.Check this link to learn more about environments in DevOps.

You can now see your environments in the portal too:

Extend environment.ts

So, now we are getting close to our actual end goal: handling environment specific variables in a Angular application via Azure multi-stage pipelines.At this moment our environment.ts and environment.prod.ts files don’t contain anything environment specific. Let’s add some dummy environment settings for the sake of this article. We pretend that we have an API that is environment specific and we’re using Auth0 as our authentication provider.

// environment.ts
export const environment = {
  production: false,
  auth: {
    clientID: "my-local-clientid",
    domain: "local.eu.auth0.com",
  },
  apiEndpoint: "https://local.myapi.io",
};

// environment.prod.ts
export const environment = {
  production: true,
  auth: {
    clientID: "#{authClientID}#",
    domain: "#{authDomain}#",
  },
  apiEndpoint: "#{apiEndpoint}#",
};

Okay Kevin, I don’t think #{authClientID}# is a valid client id. You’re completely right, of course 🙃. These are, so called, replacement tokens. And we’re going to utilize them during our deployment stages to replace the tokens with the actual values.But first, don’t forget to commit and push your changes.

Use environment variables in your code

If we do not use these variables in our code, tree shaking will remove the code from the build. So that would not be very useful for this tutorial.So add this line of code to your app.component.ts file:

@Component({
  selector: "app-root",
  templateUrl: "./app.component.html",
  styleUrls: ["./app.component.css"],
})
export class AppComponent {
  title = `is production: ${environment.production}, auth: ${environment.auth.clientID} - ${environment.auth.domain}, api: ${environment.apiEndpoint}`;
}

Add Azure DevOps extension

We now know that we want these tokens to be replaced by the actual values. You could roll your own script to accomplish this, but we’re going to use an extension for this. This extension needs to be installed on organization level, so it could be possible that you need to request this extension to your organization owner. The extension we’re going to install is called Replace Tokens from Guillaume Rouchon.

Add variable groups

With our extension in place, it’s time to add the actual variables that will be used to substitute the tokens.Navigate to the Library section to create two variable groups that contain variables for our two environments: DEV and PRD.

Variable groups overview
Add the variables for DEV
Add the variables for PRD (clone your previous variable group and replace values)
Eventually, you should now have two groups

Reference your variable groups in your pipeline

We can now use these variables groups in our yml pipeline. Add the variables property to each deployment stage below the displayname property:

- stage: deploy_dev
  displayName: Deploy to development
  variables:
    - group: DEV
  jobs:
    ...

  - stage: deploy_prd
    displayName: Deploy to production
    variables:
      - group: PRD
    jobs:
     ...

Add Replace token task

Extensions installed ✅
Variable groups created ✅
Variable groups referenced in yml ✅

Now add the replace tokens extension as step to each deployment stage. Make sure you configure the value of targetFiles properly. What we’re doing here is changing all occurrences of our replacement tokens in the main*.js files. So that would include the main-es5.*.js and main-es2015.*.js file.

- stage: deploy_dev
  displayName: Deploy to development
  variables:
    - group: DEV
  jobs:
    - deployment: deploy
      environment: DEV
      strategy:
        runOnce:
          deploy:
            steps:
              - script: echo Hello, development world!
              - task: replacetokens@3
                inputs:
                  targetFiles: "$(Pipeline.Workspace)/dist/**/main*.js"
                  encoding: "auto"
                  writeBOM: true
                  verbosity: "detailed"
                  actionOnMissing: "warn"
                  keepToken: false
                  tokenPrefix: "#{"
                  tokenSuffix: "}#"
                  useLegacyPattern: false
                  enableTelemetry: true

- stage: deploy_prd
  displayName: Deploy to production
  variables:
    - group: PRD
  jobs:
    - deployment: deploy
      environment: PRD
      strategy:
        runOnce:
          deploy:
            steps:
              - script: echo Hello, production world!
              - task: replacetokens@3
                inputs:
                  targetFiles: "$(Pipeline.Workspace)/dist/**/main*.js"
                  encoding: "auto"
                  writeBOM: true
                  verbosity: "detailed"
                  actionOnMissing: "warn"
                  keepToken: false
                  tokenPrefix: "#{"
                  tokenSuffix: "}#"
                  useLegacyPattern: false
                  enableTelemetry: true

Now let’s run this pipeline by committing and pushing your changes 🚀!

Because we’re not deploying our code to a working environment, we can’t verify if the replacement action actually worked…What we can do is check the logging. So open the last run in the DevOps portal and click on the replacetokens job to see: 3 tokens replaced out of 3

DEV
PROD

Bonus: add dependsOn and conditions

As you can see, your pipeline will sequentially run all stages. But you want to make sure that your production deployment will only be executed in certain conditions.We can make use of dependsOn and conditions to restrict the execution a bit. Add these properties to your deployment stages:

....
displayName: Deploy to development
dependsOn:
  - build
condition: and(succeeded(), eq(variables['Build.SourceBranch'], 'refs/heads/master'))
....


....
displayName: Deploy to production
dependsOn:
  - build
  - deploy_dev
condition: and(succeeded(), eq(variables['Build.SourceBranch'], 'refs/heads/master'))
....

Our stages do now depend on the build and/or deploy_dev stage and so will only run when that stage succeeds. Also we introduced the condition that the git branch should be equal to master.This gives you a bit more control about your pipeline. You can even introduce manual intervention by configuring an Approval step on the specific environment:

Conclusion

Building and deploying Angular applications doesn’t need to be very complex if we’re talking about environments. I showed you how to utilize the Angular environment files properly in a Azure DevOps multi-stage yml release pipeline without the need to rebuild the application for every environment. And we did not introduce any extra start up complexity to our application. So no need to load our app configuration via the APP_INITIALIZER and delaying the actual start up of our web app. Just use the already provided environment files properly, environment.ts for local development and environment.prod.ts for production, and you’re good to deploy with confidence!

What approach are you using at this moment?

Build and release your Ionic + Capacitor app via Microsoft App Center

Kevin Boosten — Wed, 06 May 2020 00:00:00 +0000

Building and deploying mobile applications can be challenging. I like developing mobile applications for iOS and Android. My framework of choice to do this is Ionic. Now Capacitor became the preferred way to access your native SDK’s in your hybrid app, building apps with App Center became a lot easier.

If you’re building a hybrid application with Ionic, you probably are using Capacitor as your native bridge to get access to API’s like your camera, push notifications and others. If you’re not using it yet then you should definitely give it a try.

Capacitor is a spiritual successor to Apache Cordova and Adobe PhoneGap, with inspiration from other popular cross-platform tools like React Native and Turbolinks, but focused entirely on enabling modern web apps to run on all major platforms with ease. Capacitor has backwards-compatible support for many existing Cordova plugins.

Check out the Capacitor docs for a brief introduction and how to add capacitor to your application.

App Center

Visual Studio App Center is a Microsoft product for continuously build, test, release and monitor your apps. In this article we’re only going to focus on the building part of App Center.App Center supports a variety of operating systems: iOS, Android, Windows, MacOS and even tvOS. The platforms, besides the native ones, that are available are: React Native, Cordova (preview), Xamarin and Unity. Enough to cover your needs, I guess!

Before the introduction of Capacitor, it was not possible to build your Ionic + Cordova app with App Center. There is a Cordova (preview) feature but unfortunately it does not support building. Capacitor has a different philosophy than Cordova. With Capacitor you have full access to your iOS and Android projects and these will also be part of your git repository. Cordova generates these projects on every build, so you can not make changes without making use of the Cordova config.xml file.

Ionic AppFlow

Of course there are alternatives to build you mobile application. If you’re primarily building Ionic applications then Ionic AppFlow will maybe be the better choice for you. They also have got ‘Publishing to Store’ functionality since a couple of months! So no need to manually download your artifacts from AppFlow and upload them to the stores anymore.But if you’re working in a company that also builds Xamarin and React Native apps and is also using Microsoft Azure, then App Center makes more sense.

Create a test app

Skip this section if you already have an Ionic+Capacitor app

So let’s start with creating a Ionic + Capacitor app so we can use that as our app that we’re going to use in App Center.

You can also fork this demo application from GitHub.

First install the Ionic CLI

      npm install -g @ionic/cli

Create an Angular application with Capacitor integration. At this point we just have a normal Angular web application, nothing special so far.

ionic start myApp tabs --capacitor --type=angular
cd myApp

Start the application to verify everything went well

ionic serve

Okay, you should now see a tabbed application with some dummy data in it.

Let’s add the native platforms to it. In order to do this, we should have at least build our application once, so run:

ionic build

Add the native platforms after that:

npx cap add ios
npx cap add android

Push your changes to a (private) repository and you are good to go!

Configuring App Center

We’re now going to create an app in App Center and connect it to our repository.

Go to App Center to create a new application: https://appcenter.ms/apps

Enter a name for your application, select iOS en choose a release type. The release type is just a label and it does not have any affect on your build.

Select Build from the side-menu and connect your git repo.

Now click on the branch that you would like to configure for building (or click on the wrench icon). And click on Configure build

It’s possible that you see the error You must add a shared scheme.
Follow the instructions in the link to set your workspace scheme to
“Shared”. Also add the necessary Provisioning Profile and Certificate to build a valid .ipa file.

In case you forked the demo repo, you need to change the Team ID and
App ID in Xcode manually and push these changes to your fork. Also
provide a provisioning profile and certificate that matches your app.
You don’t need to have paid developer account to create a valid
provisioning profile, just export the certificate and profile from
your machine that you use in Xcode._Still having trouble? Maybe this
can help you: iOS signing issues explained

You can also change other settings like building on each push and auto incrementing your build number.

Now click on Save & Build to see what happens!

❌ Aiiii, that escalated quickly! What happened? Remember we are trying to build a hybrid application? So what did we do to actually build the web part of the app?

And here comes the ‘trick’💡! App Center supports several build scripts that run at pre-defined stages: post-clone, pre-build and post-build. That’s exactly what we need to build our hybrid application with App Center. We’re going to use the post-clone script in order to perform some steps that are required to build our app. Let’s add a file appcenter-post-clone.sh to the iOS (ios/App/appcenter-post-clone.sh) and Android (android/app/appcenter-post-clone.sh) projects.

#!/usr/bin/env bash

# fail if any command fails
set -e
# debug log
set -x

# Required nodeJS version
NODE_VERSION=10.17.0

# workaround to override the v8 alias
npm config delete prefix
. ~/.bashrc
nvm install "$NODE_VERSION"
nvm alias node10 "$NODE_VERSION"

# go to root of project
cd ../..

# install dependencies
npm i

# run optimized production build
npm run build -- --prod

# copy the web assets to the native projects and updates the native plugins and dependencies based in package.json
npx cap sync

The first couple of lines are just to override the default NodeJS version that App Center is using. After that, we’re installing our npm dependencies, running an production build and finally invoking a Capacitor specific command to sync our web part of the application to the native projects.

Go back to the configuration and be sure to click on “Save & Build” button to let App Center know that new build specific files need to be indexed.

Your build should now succeed after waiting for a couple of minutes 🎉.

Conclusion

So, long story short: add the appcenter-post-clone.sh script to both native projects in your Ionic + Capacitor project, and you will be able to use App Center as your CI/CD platform.

You obviously can extend this script with all the things you need. For example: you could change the dev/prod mode based on an environment variable that you can set in your App Center build configuration. Definitely take a look at the Microsoft sample-build-scripts repo.

Next steps?

Extend your build configuration to your needs
Distribute builds to distribution groups
Publish your application to the public stores

In my next blog I will describe how to properly distribute your app for testing purposes and how to add new test devices to your apps provisioning profile for your iOS distribution.

Stay tuned and happy building 🏗👷🏻‍♂️👷🏻‍♀️!