Build and Run REST API with CQRS
You can run the API created by the templates either locally or in a Docker container.
Depending on the options selected when creating the CQRS API, additional configuration may be required. before running the project. It is important to complete the Configure REST API with CQRS project section of this guide before building and running the project.
Building and Running
Build and run locally
- Windows
- Mac and Linux
The following example shows how to build and run the Stacks CQRS API solution. In this example, the solution is located in the c:\dev directory, and the project is named Company.Project. If you have chose a different directory or project name when creating your solution, adjust the commands accordingly.
-
Open a terminal.
You can use either Command Prompt or PowerShell. -
Navigate to the project directory.
Change your directory to the API project directory. In this example, the solution was created in the c:\dev folder and was named Company.Project.cd c:\dev\company.project\src\cqrs\src\api
-
Build the solution
Use thedotnet build
command to build the solution in this directory.dotnet build
-
Run the API project.
Finally, use thedotnet run
command to start the API project.
Replace Company.Project with your project's name.dotnet run --project Company.Project.API/Company.Project.API.csproj
If your folder structure is too deep, you may encounter a build failure. This issue arises due to our dependency on Pact for contract testing. The error will looks like this: -
Error MSB3491 Path: File exceeds the OS max path limit. The fully qualified file name must be less than 260 characters.
There are two fixes for this issue: -
- Enable long file paths on Windows.
- Create your folder at a higher level, so that paths won't exceed 260 characters.
Below is an example of how to build and run the Stacks CQRS API solution. In this example, the solution is located in a folder called dev in the home directory, and the project is named Company.Project. If you have used a different directory or project name, adjust the commands accordingly.
-
Open a terminal.
-
Navigate to the project directory.
Change to the API project directory within the solution. In this example, the solution was created in a folder called dev inside anneexample's home directory and was named Company.Project.cd ~/users/anneexample/dev/company.project/src/cqrs/src/api
-
Build the solution
Use thedotnet build
command to build the solution in this directory.dotnet build
-
Run the API project.
Finally, use thedotnet run
command to start the API project.
Replace Company.Project with your actual project name.dotnet run --project Company.Project.API/Company.Project.API.csproj
Build and run in a Docker container
- Windows
- Mac and Linux
The following example shows how to build and run the Stacks CQRS API solution. In this example, the solution is located in the c:\dev directory, and the project is named Company.Project. If you have used a different directory or project name, adjust the commands accordingly.
-
Open a terminal.
You can use either Command Prompt or PowerShell. -
Navigate to the project directory.
Change to the project's root directory within the solution. In this example, the solution was created in c:\dev and was named Company.Project.cd c:\dev\company.project\
-
Build the Docker Image
Use thedocker build
command to build the Docker image from the Dockerfile in this folder.docker build -t dotnet-api -f src/cqrs/src/api/Dockerfile --build-arg self_repo_src=src/cqrs/src/api .
-
Run the Docker Image.
Use thedocker run
command to start a container from the image that we just built. Use one of the commands below, bt you will need to change the--mount
switch so that it matches the path to your appsettings.json. You will also need to provide the values of the environment variables that you made a note of in the previous section and delete the environment variables that you are not using.Command Linedocker run -p 5000:8080 ^
--mount type=bind,source=C:/dev/company.project/src/cqrs/src/api/company.project.API/appsettings.json,target=/app/config/appsettings.json ^
-e COSMOSDB_KEY=your-key ^
-e EVENTHUB_CONNECTIONSTRING=your-aeh-connection-string ^
-e SERVICEBUS_CONNECTIONSTRING=your-asb-connection-string ^
-e STORAGE_CONNECTIONSTRING=your-aeh-storage-connection-string ^
-e TOPIC_ARN=your-aws-sns-topic-arn ^
dotnet-api:latestPowerShelldocker run -p 5000:8080 `
--mount type=bind,source=C:/dev/company.project/src/cqrs/src/api/company.project.API/appsettings.json,target=/app/config/appsettings.json `
-e COSMOSDB_KEY=your-key `
-e EVENTHUB_CONNECTIONSTRING=your-aeh-connection-string `
-e SERVICEBUS_CONNECTIONSTRING=your-asb-connection-string `
-e STORAGE_CONNECTIONSTRING=your-aeh-storage-connection-string `
-e TOPIC_ARN=your-aws-sns-topic-arn `
dotnet-api:latest
-
Open Terminal.
-
Navigate to the project directory.
Change to the API project directory within the solution. In this example, the solution was created in a folder called dev inside anneexample's home directory and was named Company.Project.cd ~/users/anneexample/dev/company.project
-
Build the Docker Image
Use thedocker build
command to build the Docker image from the Dockerfile in this folder.docker build -t dotnet-api -f src/cqrs/src/api/Dockerfile --build-arg self_repo_src=src/cqrs/src/api .
-
Run the Docker Image.
Use thedocker run
command to start a container from the image that we just built. Use one of the commands below, bt you will need to change the--mount
switch so that it matches the path to your appsettings.json. You will also need to provide the values of the environment variables that you made a note of in the previous section and delete the environment variables that you are not using.docker run -p 5000:8080 \
--mount type=bind,source=C:/dev/company.project/src/cqrs/src/api/company.project.API/appsettings.json,target=/app/config/appsettings.json\
-e COSMOSDB_KEY=your-key \
-e SERVICEBUS_CONNECTIONSTRING=your-asb-connection-string \
-e EVENTHUB_CONNECTIONSTRING=your-aeh-connection-string \
-e STORAGE_CONNECTIONSTRING=your-aeh-storage-connection-string \
dotnet-api:latest
When running the Docker container, you need to pass your environment variables using the -e
switch. The commands above show every environment variable. You should replace the placeholders with actual secrets that you made a note of when you followed the Configure REST API with CQRS project step of this guide and remove the environment variables that you are not using.
The table below describes each environment variable.
Environment Variable name | Environment Variable required when... |
---|---|
COSMOSDB_KEY | When Cosmos DB is your database service. |
EVENTHUB_CONNECTIONSTRING | When Azure Event Hubs is your messaging service. |
SERVICEBUS_CONNECTIONSTRING | When Azure Service Bus is your messaging service. |
TOPIC_ARN | When AWS SNS is your messaging service. |
Note that we mount the appsettings.json file when running locally, but we do not do this when the full project is deployed to Azure. This is because when the project is deployed to Azure, the build process will perform the substitution.
Verify that the application has started
If you changed the domain object name during project creation, the URL path will reflect that change. For example, if your domain object is named foo
, the path will be ../v1/foo
instead of ../v1/menu
.
Browse to http://localhost:5000/v1/menu.
This should return a valid JSON response.
The application configuration uses Swagger/OAS3 to represent the API endpoints. The Swagger UI can be viewed by directing your browser to http://localhost:5000/swagger/index.html.