---
id: configure_project_netcore
title: Configure REST API with CQRS project
linkTitle: Configure REST API with CQRS project
weight: 2
keywords:
  - .net core
  - rest api
  - cqrs
  - azure
  - application insights
  - cosmos db
  - aws sns
  - build
  - run
  - application
  - configure
  - docker
---

:imagesdir: ../../../../../../../images

== Configuring the project

All security sensitive information is passed as a secret in our configuration. We have a library called https://github.com/Ensono/stacks-dotnet-packages-configuration[Ensono.Stacks.Configuration] that reads secrets from the environment before the application starts and makes the needed substitutions in the configuration files.

=== Configuring Cosmos DB

The project can be set to use Azure **Cosmos DB** or an **InMemory** database to store the example application data. The **InMemory** database works out of the box and no further setup is required aside from creating your project. Depending on your desired setup you'll have to provide some or all of the configuration in the `appsettings.json` file section showed below.

.<PROJECT-NAME>/cqrs/src/api/xxENSONOxx.xxSTACKSxx.API/appsettings.json
[source, json]
----
{
  "CosmosDb": {
    "DatabaseAccountUri": "<Add CosmosDB Account URI here>"
  },
  "DatabaseName": "Stacks",
  "SecurityKeySecret": {
    "Identifier": "COSMOSDB_KEY",
	...
  }
}
----

.Using the Cosmos DB Emulator to run the database locally
[%collapsible]
=====
Move to the `<PROJECT-NAME>/cqrs/src/api` folder and run the next commands in **terminal**.

For running on local environments (Windows/Linux/macOS) please follow the https://docs.microsoft.com/en-us/azure/cosmos-db/local-emulator?tabs=ssl-netstd21[instructions provided by Microsoft.]

. Navigate to the local Cosmos DB URL in your browser as indicated in the documentation given in the above link.

. Identify the **Primary Key**. Please refer to the field in the screenshot below.
+
image::cosmosdb_emulator_3.png[CosmosDB]
+
. Cosmos DB has to contain a fixed structure depending on your project. Create a collection `Stacks` (this corresponds to `DatabaseName` in the `appsettings.json` file) with a container id `Menu` (name of domain object) and the partition key `/id`. Keep in mind that if you've changed the domain (default being `Menu`), you have to supply your own domain when creating the container.
+
image::cosmosdb_emulator_1.png[CosmosDB]

[NOTE]
.CosmosDb environment variable
====
To interact with CosmosDb there is a environment variable called `COSMOSDB_KEY` that needs to be set before running your application. This variable holds the value of the **Primary Key** you got from step 2. Please see the next section on details of how to set it on your machine.
====
=====

.Setting the COSMOSDB_KEY environment variable on Windows
[%collapsible]
=====
There are a couple of different ways to set the environment variable

[discrete]
=== Using Powershell for COSMOSDB_KEY

You can use `Powershell` with administrator privileges to execute the command below. Substitute `<PRIMARY-KEY-HERE>` with your own key.

.Run PS command to add the COSMOSDB_KEY system variable
[source, shell]
----
[Environment]::SetEnvironmentVariable("COSMOSDB_KEY", "<PRIMARY-KEY-HERE>", [EnvironmentVariableTarget]::Machine)
----

[discrete]
=== Using Visual Studio for COSMOSDB_KEY

. Open the project in Visual Studio. The solution file is located at `src/api/xxENSONOxx.xxSTACKSxx.API.sln`.

. Add **COSMOSDB_KEY** environment variable to the **launchSettings.json** file generated by Visual Studio and add the Cosmos DB Primary Key value.

.src/api/xxENSONOxx.xxSTACKSxx.API/properties/launchSettings.json
[source, json]
----
{
  ...
  "profiles": {
    "xxENSONOxx.xxSTACKSxx.API": {
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development",
        "COSMOSDB_KEY": "<PRIMARY-KEY-HERE>"
        ...
      }
    }
  }
}
----

[discrete]
=== Using VSCode for COSMOSDB_KEY

If you're using VSCode that means you'll have a `launch.json` file generated when you try to run the project. In that file there's an `env` section where you can put environment variables for the current session.

.launch.json
[source, json]
----
{
  "env": {
    ...
    "COSMOSDB_KEY": "<PRIMARY-KEY-HERE>",
    ...
  }
}
----

[NOTE]
.Usage
====
The variable is referenced in **appsettings.json**. As mentioned in the beginning section of this page this environment variable name will be substituted with the actual value on startup.

.src/api/xxENSONOxx.xxSTACKSxx.API/appsettings.json
[source, json]
----
{
  "CosmosDb": {
    ...
    "SecurityKeySecret": {
      "Identifier": "COSMOSDB_KEY",
      ...
    }
  }
}
----
====

=====

.Setting the COSMOSDB_KEY environment variable on Unix
[%collapsible]
=====
There are a couple of different ways to set the environment variable

[discrete]
=== Using terminal for COSMOSDB_KEY

You can use the `terminal` to execute the command below. Substitute `<PRIMARY-KEY-HERE>` with your own key. This will set the environment variable only for the current session of your terminal.

.Run terminal command to add the COSMOSDB_KEY system variable
[source, bash]
----
export COSMOSDB_KEY=<PRIMARY-KEY-HERE>
----

To set the environment variable permanently on your system you'll have to edit your `bash_profile` or `.zshenv` file depending on which shell are you using.

.Example for setting env variable in .zchenv
[source, bash]
----
echo 'export COSMOSDB_KEY=<PRIMARY-KEY-HERE>' >> ~/.zshenv
----

[discrete]
=== Using Visual Studio Code for COSMOSDB_KEY

If you're using VSCode that means you'll have a `launch.json` file generated when you try to run the project. In that file there's an `env` section where you can put environment variables for the current session.

.launch.json
[source, json]
----
{
  "env": {
    ...
    "COSMOSDB_KEY": "<PRIMARY-KEY-HERE>",
    ...
  }
}
----

[NOTE]
.Usage
====

The variable is referenced in **appsettings.json**. As mentioned in the beginning section of this page this environment variable name will be substituted with the actual value on startup.

.src/api/xxENSONOxx.xxSTACKSxx.API/appsettings.json
[source, json]
----
{
  "CosmosDb": {
    ...
    "SecurityKeySecret": {
      "Identifier": "COSMOSDB_KEY",
      ...
    }
  }
}
----
====

=====

.Connecting to deployed Cosmos DB instance
[%collapsible]
=====
When choosing not to run the CosmosDB locally via the emulator, further configuration needs to be changed in the `appsettings.json` file.

Aside from setting the `COSMOSDB_KEY` as an environment variable (described in the previous section), you'll have to set the CosmosDB URI parameter `DatabaseAccountUri` as well.

.<PROJECT-NAME>/cqrs/src/api/xxENSONOxx.xxSTACKSxx.API/appsettings.json
[source, json]
----
{
  "CosmosDb": {
    "DatabaseAccountUri": "<Add CosmosDB Account URI here>",
    "DatabaseName": "Stacks",
    "SecurityKeySecret": {
      "Identifier": "COSMOSDB_KEY",
      ...
    }
  }
}
----
=====

=== Configuring DynamoDB

You need a DynamoDB instance in order to connect the API to it. You can follow the official instructions provided by AWS https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/SettingUp.DynamoWebService.html[here].

Relevant documentation pages that you can follow to set up your profile:

- https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html[Configuration and credential file settings]

- https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-profiles.html[Named profiles]

The template and NuGet package assumes you'll use the `AWS CLI` tools and will have configured your access keys via the `aws configure` command.

Depending on your desired setup you'll have to provide some or all of the configuration in the `appsettings.json` file section showed below.

.<PROJECT-NAME>/cqrs/src/api/xxENSONOxx.xxSTACKSxx.API/appsettings.json
[source, json]
----
{
  "DynamoDb": {
    "TableName": "Menu",
    "TablePrefix": ""
  }
}
----

=== Ensono.Stacks.DynamoDB package

This template uses the https://github.com/Ensono/stacks-dotnet-packages-dynamodb[Ensono.Stacks.DynamoDB] package to connect and use DynamoDB.

=== Configuring AWS SNS

The project can be set to use AWS **SNS** to publish and consume events. In order to publish messages to a Queue you will also require a version of AWS SQS running on AWS cloud. For SNS to work out the box with AWS you will have to provide some configuration in the `appsettings.json` file section showed below as well as subscribeaing your SNS topic to your SQS queue.

You will also be required to set the `TOPIC_ARN` as an environment variable (see section **Setting the TOPIC_ARN environment variable**).

.<PROJECT-NAME>/cqrs/src/api/xxENSONOxx.xxSTACKSxx.API/appsettings.json
[source, json]
----
{
  "AwsSnsConfiguration": {
    "TopicArn": {
      "Identifier": "TOPIC_ARN",
      ...
    }
  },
  "AWS": {
    "Region": "eu-west-2"
  }
}
----

.Using the AWS SNS to publish messages
[%collapsible]
=====
For running on local environments you will still require a version of AWS SNS running on AWS cloud.

1. Navigate to the SNS Topic in your browser.

2. Identify the **TopicArn**. This is located within: Amazon SNS --> Topics --> topic-name (e.g. stacks-dev) --> TopicArn

3. Apply the **TopicArn** obtained to the environmental variable called `TOPIC_ARN` (Please see the next section on details of how to set it on your machine).

4. Run your application and carry out some event worth actions (create domain objects, retrieve domain objects, delete domain objects etc...). Any time you carry out an action which should raise an event, there will be an event raised within your AWS SQS queue.

5. Navigate to the SQS Queue in your browser and select `Send and receive messages`. Select `Poll for messages` and see all the events raised.
=====

.Setting the TOPIC_ARN environment variable on Windows
[%collapsible]
=====
There are a couple of different ways to set the environment variable

[discrete]
=== Using Powershell for TOPIC_ARN

You can use `Powershell` with administrator privileges to execute the command below. Substitute `<TOPIC-ARN-HERE>` with your own key.

.Run PS command to add the TOPIC_ARN system variable
[source, shell]
----
[Environment]::SetEnvironmentVariable("TOPIC_ARN", "<TOPIC-ARN-HERE>", [EnvironmentVariableTarget]::Machine)
----

[discrete]
=== Using Visual Studio for TOPIC_ARN

1. Open the project in Visual Studio. The solution file is located at `src/api/xxENSONOxx.xxSTACKSxx.API.sln`.

2. Add **TOPIC_ARN** environment variable to the **launchSettings.json** file generated by Visual Studio and add the SNS topic ARN value.

.src/api/xxENSONOxx.xxSTACKSxx.API/properties/launchSettings.json
[source, json]
----
{
  ...
  "profiles": {
    "xxENSONOxx.xxSTACKSxx.API": {
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development",
        "TOPIC_ARN": "<TOPIC-ARN-HERE>"
        ...
      }
    }
  }
}
----

[discrete]
=== Using VSCode for TOPIC_ARN

If you're using VSCode that means you'll have a `launch.json` file generated when you try to run the project. In that file there's an `env` section where you can put environment variables for the current session.

.launch.json
[source, json]
----
{
  "env": {
    ...
    "TOPIC_ARN": "<TOPIC-ARN-HERE>",
    ...
  }
}
----

[NOTE]
.Usage
====
The variable is referenced in **appsettings.json**. As mentioned in the beginning section of this page this environment variable name will be substituted with the actual value on startup.

.src/api/xxENSONOxx.xxSTACKSxx.API/appsettings.json
[source, json]
----
{
  "AwsSnsConfiguration": {
    "TopicArn": {
      "Identifier": "TOPIC_ARN",
      ...
    }
  }
}
----
====

=====

.Setting the TOPIC_ARN environment variable on Unix
[%collapsible]
=====
There are a couple of different ways to set the environment variable

[discrete]
=== Using terminal for TOPIC_ARN

You can use the `terminal` to execute the command below. Substitute `<TOPIC-ARN-HERE>` with your own key. This will set the environment variable only for the current session of your terminal.

.Run terminal command to add the TOPIC_ARN system variable
[source, bash]
----
export TOPIC_ARN=<TOPIC-ARN-HERE>
----

To set the environment variable permanently on your system you'll have to edit your `bash_profile` or `.zshenv` file depending on which shell are you using.

.Example for setting env variable in .zchenv
[source, bash]
----
echo 'export TOPIC_ARN=<TOPIC-ARN-HERE>' >> ~/.zshenv
----

[discrete]
=== Using Visual Studio Code for TOPIC_ARN

If you're using VSCode that means you'll have a `launch.json` file generated when you try to run the project. In that file there's an `env` section where you can put environment variables for the current session.

.launch.json
[source, bash]
----
{
  "env": {
	...
    "TOPIC_ARN": "<TOPIC-ARN-HERE>",
    ...
}
}
----

[NOTE]
.Usage
====
The variable is referenced in **appsettings.json**. As mentioned in the beginning section of this page this environment variable name will be substituted with the actual value on startup.

.src/api/xxENSONOxx.xxSTACKSxx.API/appsettings.json
[source, bash]
----
{
  "AwsSnsConfiguration": {
  "TopicArn": {
		"Identifier": "TOPIC_ARN",
	...
	}
}
}
----
====
=====
