Getting started

Getting Started

This guide will walk through the ADDS Mock project, outline its contents, and show you how to create a simple mock service.

Setup

Clone the repository code, and open ADDS-Mock.sln in Visual Studio. Build the solution, and we're ready to go.

Project	Description
UKHO.ADDS.Mocks	The ADDS Mock service. You will add your mock services here
UKHO.ADDS.Mocks.LocalHost	A .NET Aspire local orchestrator project, showing how ADDS Mock can be used in an Aspire project. It also provides a very handy way of running ADDS Mock locally, and accessing its UI features.
UKHO.ADDS.Mocks.SampleService	A sample service, showing how the behaviour of ADDS Mock can be extended and overridden on a case-by-case basis.
UKHO.ADDS.Mocks.Client	Contains an HTTP client factory that makes writing tests against ADDS Mock simple.
UnitTestExamples	An example of how to use UKHO.ADDS.Mocks.Client

How do I add a service?

We will now walk through how to add a new service mock to ADDS Mock. We'll call it the "Sample Service". We will be working solely inside the UKHO.ADDS.Mocks project to begin with.

Registering the service

Open the MockServices.cs file. We need to add a service definition, to register our mock with ADDS Mock.

In the AddServices() method, add the following call to ServiceRegistry.AddDefinition():

public static void AddServices()
{
    ServiceRegistry.AddDefinition(new ServiceDefinition("sample", "Sample Service", ["get-file"]));
}

ServiceDefinition takes three parameters. The first is the service prefix ("sample"). This defines the root path for the service - when the mock is called, all endpoints that are defined will be prefixed. For example, we will define an endpoint with the URL /files in our sample mock. When the mock runs, the endpoint will be found at https://localhost/sample/files.

The second parameter is the name of the service. This is used in various parts of the ADDS Mock UI, which we will look at later.

The third parameter defines any states we may wish to use with the service. We'll take a look at states, what they're for and why you might want to use them a bit later on. If you don't want to use them, just pass an empty array here.

We now need to add an area in the project for our mock service files to live. In the Configuration folder, you will see two subdirectories:

• Files Any files copied in here will be available to read and use in your mock code. Each mock has its own subdirectory.
• Mocks This is where the code for all of the mocks lives. Each mock has its own subdirectory.

It is important that the names of these subdirectories is lowercase, and has exactly the same name as the service prefix we have defined when we register the mock service (in our case, "sample")

So, we will create two subdirectories, Files\sample and Mocks\sample.

Files

Create a simple text file readme.txt with some simple content, and copy it under the Files\sample folder.

Creating an endpoint

Under the Mocks\sample folder, create a C# class file called GetFilesEndpoint.cs.

Amend the file as follows:

namespace UKHO.ADDS.Mocks.Configuration.Mocks.sample
{
    public class GetFilesEndpoint : ServiceEndpointMock
    {
        public override void RegisterSingleEndpoint(IEndpointMock endpoint)
        {
            endpoint.MapGet("/files", () => Results.Ok("Hello!"));
        }
    }
}

You will see here that we have used a Minimal API to define our mock endpoint.

Important

ADDS Mocks 2.0 leverages the full power of Microsoft Minimal APIs. Within reason, anything you can do with a Minimal API, you can use in your mock. This includes:

• The full ASP routing engine for URL matching
• POCO request and response models. Just define these in your mock subdirectory, and you can use them
• Inserting a breakpoint, and debugging your mock

Run the Aspire local project, which will start ADDS Mock.

Take a note of the port that Aspire has used to start ADDS Mock in the dashboard, navigate to localhost:(insert your port here)/sample/files, and you should see the message "Hello!"

Adding documentation

Now that we've written our first endpoint, we should add some documentation for it. Add the following:

namespace UKHO.ADDS.Mocks.Configuration.Mocks.sample
{
    public class GetFilesEndpoint : ServiceEndpointMock
    {
        public override void RegisterSingleEndpoint(IEndpointMock endpoint)
        {
            endpoint.MapGet("/files", () => Results.Ok("Hello!"))
            .WithEndpointMetadata(endpoint, d =>
            {
                d.Bold("Gets a file")
                .AppendNewLine()
                .Italic("Just a demo method, nothing too exciting");
            });                
        }
    }
}

We can go and view this documentation in the Scalar UI provided by ADDS Mock. Start the Aspire project again, and start the Scalar UI using the context menu in the Aspire dashboard.

You will see our new endpoint listed there. Notice that the endpoints are neatly grouped by the service name we provided earlier. You can also see the documentation we have added, and a description of where to find the endpoint definition in the ADDS Mock project.

You can now test your mock endpoint by clicking the 'Test Request' button.