Create New gRPC Service

info

Before continuing, ensure your workstation has been set up with the Core Components, as well as components specific to the language ecosystem you're working in: [JavaScript] [Java] [.Net] [Python] [Rust]

This document provides a step-by-step guide to creating a new .NET gRPC service using archetect. By leveraging tools like Protocol Buffers (Protobuf) and the .NET gRPC framework, you can rapidly develop high-performance, strongly-typed APIs with minimal boilerplate. This guide simplifies the process, allowing you to focus on defining your service's core functionality while automating much of the repetitive setup. Whether you're building a new microservice or integrating with existing systems, these steps will help you efficiently create and deploy a scalable gRPC service.

Generating the Service

Using Archectect command below, generate the base web application

archetect render git@github.com:p6m-archetypes/dotnet-grpc-service.archetype.git

Archetect Prompts

When rendering the archetype, you'll be prompted for the following values:

Prompt	Description	Example	Required
Org Name	Organization this project belongs to	afi,a1p,...	Yes
Solution Name	Project name	apps, booking-app,...	Yes
Project Prefix	Prefix for the Service Name	order, payment, booking	Yes
Project Suffix	Suffix for the Service Name	Service, Orchestrator	No
Persistence	Whether to use an incluster DB	CockroachDB,None,...	No

For this tutorial, please use the below prompt values:

Prompt	Value
Org Name	a1p
Solution Name	apps
Project Prefix	Order
Project Suffix	Service
Persistence	CockroachDB

Completing the above steps & providing prompts, should generate an order-service in your working directory.

    - order-service
        -- OrderService.API
            This module contains the protobuf API specification
        -- OrderService.Core
            This module contains the main business logic file (e.g. OrderService.Core.cs)
        -- OrderService.Persistence
            This module contains the entities and persistence layer within the service
        -- OrderService.Server
            This module contains the server runtime for the .NET service
        -- OrderService.IntegrationTests
            This module contains all the unit and integration tests for the service
        -- OrderService.Client
            This module contains the generated .NET client for this service. This can be used to share it with other backend services (e.g. domain gateways)

Running the service

Docker

Please ensure you have Docker running on the machine

Step 1 - Start the server

From the order-service folder run the below command. (i.e. cd order-service before running below command)

dotnet run --project OrderService.Server

Step 2 - Test server health

Test the server by running below command:

curl http://localhost:5031/health

Step 3 - Invoke an API

Test one API using below command:

grpcurl -plaintext -d '{"start_page": "1", "page_size": "5"}' localhost:5030 \
    a1p.apps.order_service.grpc.OrderService/GetOrders

Above should return you an empty list in json since no orders have been created yet.

Step 4 - Publish the gRPC Client

Publish the service packages

Before we can run the Order Domain Gateway (upcoming tutorial) and expose the REST API, we need to update the Order Service Client to be available in the local artifact package store.

cd ORDER_SERVICE_ROOT_FOLDER

(e.g. cd /code/order-service)

dotnet pack -c Release -o ~/.nuget_local

Additional documentation

The generated service contains a README.md in the root service folder. i.e. (order-service/README.md) Please go through this as well for additional information.