Cosmos DB is a popular NoSQL database offering from Microsoft's cloud provider Azure. It offers an extremely scalable, super-fast, and highly available platform as a service database. All data is stored as JSON, in a logical grouping called a container. Containers can scale independently of one another and configure independent partitioning strategies.

If containers, partitioning, and NoSQL databases are new to you, I would recommend reading the Cosmos DB documentation found here.

Paging use cases

Why do you need to page data? There are many cases for paging data. But I believe there are two examples that best explain the different paging options provided by Cosmos DB. However, these use cases apply to all databases.

The first is a common scenario you've probably used in social media, infinite scrolling. Think of Twitter, for example, you load some tweets then scroll down the feed. As you read the first set of tweets more are loaded for you to read, and so on. This is a form of paging. You can scroll back up the tweets but it won't re-query the database for those tweets again. The tweets are already loaded onto your device so you just scroll back up, and they are still there. The fact it does not re-query the database is important in this example. If you think of this from an implementation point of view, this is like a marker, and as you read the next page that marker moves. However, this "marker" always moves forward's never backward in this example. This is important to remember for later.

The second example I like to use, is a typical table, in an application that has common features. Such as next and previous buttons, a dropdown to allow you to specify the maximum number of results returned, and so on. Something like the table below taken from MD Bootstraps docs.

This allows a user to have random access to any page, moving back and forth through the pages, potentially changing the sorting and filtering of the data and the page size of the given results. This as you can imagine, requires the database do a lot more work, but also offers a lot more flexibility in terms of what you can offer to a user.

The Cost of Paging

Paging in any database is an expensive feature in terms of resources that will be used up by a database if it is frequently paging data. In the random-access scenario, a lot of implementations rely on either skip and take, or limit and offset approaches. A common example of this could be making a query to retrieve page 5 of some data with a page size of 25. You would have a query that skips the first 100 records but limits the returned records of the query to 25 records. This is supported by Cosmos DB and many other databases but this means the database has to skip 100 rows which it still has to process, it can't just jump to a point in time or to a cursor for example. When you translate this into Cosmos DB terms this skip will add to the number of RUs that your query costs. In a lot of cases making some queries very expensive if run frequently.

What are "RU's"? RU's or request units are the cost of an operation, think of this as the currency of a Cosmos database read more on this here.

Taking a step back to the infinite scroll scenario described earlier if you were to implement something like this in Cosmos DB there is an awesome feature that can be utilized. Cosmos DB implements continuation tokens for its paging operations, this is a stateless marker in a database of where a current query is at. This means when provided back to Cosmos DB it can pick up right where you left off with a mostly consistent RU charge. The beauty of these being stateless means you could make a query and then not come back and request the next page of data for a few hours or days and it will pick up just where you left off.

Want to know more about continuation tokens? Check out the Cosmos DB docs!

Paging Code Samples

The following code examples come in the form of .NET 6 Web API projects, both of which can be found here. The first example uses the raw .NET Cosmos SDK and the second uses the Azure Cosmos Repository. Some of the code from these samples will be excluded in this post. This is to focus on paging implementation using both libraries.

The Azure Cosmos Repository wraps the .NET Cosmos SDK, aiming to take away some of the ceremony involved with the .NET SDK when working with containers.

Paging in Cosmos DB using the .NET SDK

The skip, take approach

The first code example is an API endpoint that allows a client to page through a container with a set of people records.

app.MapGet("/skipTake", async (
    [FromServices] CosmosClient client,
    [FromQuery] int pageNumber,
    [FromQuery] int pageSize) =>
{
    var container = await GetPeopleContainer(client);

    QueryRequestOptions queryOptions = new()
    {
        MaxItemCount = pageSize
    };

    IQueryable<Person> query = container
        .GetItemLinqQueryable<Person>(requestOptions: queryOptions)
        .Where(x => x.PartitionKey == nameof(Person))
        .Skip(pageSize * (pageNumber - 1))
        .Take(pageSize);

    var (items, charge, _) =
        await GetAllItemsAsync(query, pageSize);

    return new
    {
        requestUnits = charge,
        count = items.Count,
        people = items,
    };
});

In the above example, there is a method called GetAllItemsAsync(...) this does a lot with the SDK to properly get the results and map them into a list. This can be found here

This example work's as expected making a request such as GET https://{{host}}:{{port}/skipTake?pageSize=25&pageNumber=1 returns 25 people and costs 3.6 RUs. See the response below.

{
  "requestUnits": 3.6,
  "count": 25,
  "people": //excluded for brevity
}

3.6 RUs isn't certainly not an expensive query in Cosmos DB terms. However, when you query for page 10 with a request such as GET https://{{host}}:{{port}/skipTake?pageSize=25&pageNumber=10. This request costs nearly 10 RUs, see below.

{
  "requestUnits": 9.86,
  "count": 25,
  "people": //excluded for brevity
}

This links back to some of the problems with the skip, take approach explained earlier. You can imagine as the page size increases and you begin to query for page 50 or 100 on a larger data set, this charge keeps on increasing.

Paging with continuation tokens

The next example shows how the infinite scroll scenario can be implemented using the .NET SDK.

app.MapGet("/tokenBased", async (
    HttpContext context,
    [FromServices] CosmosClient client,
    [FromQuery] int pageSize) =>
{
    string? continuationToken = 
        context.Request.Headers["X-Continuation-Token"];

    var container = await GetPeopleContainer(client);

    QueryRequestOptions queryOptions = new()
    {
        MaxItemCount = pageSize
    };

    IQueryable<Person> query = container
        .GetItemLinqQueryable<Person>(
            requestOptions: queryOptions, 
            continuationToken: continuationToken)
        .Where(x => x.PartitionKey == nameof(Person));

    var (items, charge, newContinuationToken) =
        await GetAllItemsAsync(query, pageSize);


    context.Response.Headers["X-Continuation-Token"] =
        newContinuationToken;

    return new
    {
        count = items.Count,
        requestUnits = charge,
        people = items,
    };
});

The above example tries to read a token from a header named X-Continuation-Token. This is not required to read the first page. This will then return a token stored in the same header for the response if there is another page.

The header X-Continuation-Token was chosen to return the token to a client because, if this was returned in a JSON object the quotes would have to be escaped. This when provided back to Cosmos DB is rejected as an invalid continuation token. See an example of a valid continuation token below.

[
    {
        "token": "+RID:~47VbALuANL8ZAAAAAAAAAA==#RT:1#TRC:25#ISV:2#IEO:65567#QCF:4#FPC:ARkAAAAAAAAALAEAAAAAAAA=",
        "range": {
            "min": "",
            "max": "FF"
        }
    }
]

Running the samples and working through the pages of data, for each request the RU charge remains consistent. There is not a large increase in cost as you work further through the pages. This is in large contrast to the skip, take approach that costs more the further through the pages you go.

Up to now continuation tokens are looking like the best option. However, there are a few things you cannot do with continuation tokens. The first thing is you can only move forward, you cannot go back a page. The second is that you cannot change the query. Let's say you ordered by age and read the first page. You then got a continuation token back from that request. If you then tried to change the ordering to order by name and passed the same continuation token. Then you would get an error from Cosmos DB. This was something I found the hard way, see this GitHub issue for more information.

Note on query execution in Cosmos DB

There is one part of the two examples I wanted to draw attention to and that is the method that is used in both GetAllItemsAsync(query, pageSize);. The implementation of this is below.

static async Task<(
    List<Person> items, 
    double charge, 
    string? continuationToken
    )> GetAllItemsAsync(
    IQueryable<Person> query,
    int pageSize)
{
    string? continuationToken = null;
    List<Person> results = new();
    int readItemsCount = 0;
    double charge = 0;
    using FeedIterator<Person> iterator = query.ToFeedIterator();

    while (readItemsCount < pageSize && iterator.HasMoreResults)
    {
        FeedResponse<Person> next = 
            await iterator.ReadNextAsync();

        foreach (Person result in next)
        {
            if (readItemsCount == pageSize)
            {
                break;
            }

            results.Add(result);
            readItemsCount++;
        }

        charge += next.RequestCharge;
        continuationToken = next.ContinuationToken;
    }

    return (results, charge, continuationToken);
}

The main points to note in this method are the while loop and the readItemsCount variable that allows this method to make sure it returns all the available results back from a given paging query.

The reason this is needed is that even though we are paging. The .NET SDK will also perform some paging for larger results sets. The other reason is that when we set the MaxItemCount property on the QueryRequestOptions object, this is specifically a maximum item count. This means in some cases Cosmos DB may return fewer results, even though there are more available. Learn more about this by reading the docs

Paging in Cosmos DB using the Cosmos Repository Library

The next set of examples shows how you can achieve paging with the two methods shown using the .NET SDK, using the Cosmos Repository. This library aims to take away a lot of the complexity and boilerplate that is included in the .NET SDK sample.

Hopefully, you will see how concise these examples are and furthermore, how the amount of code you are required to write decreases by using this library. See the full sample here.

You can find the Azure Cosmos Repository on GitHub and on [Nuget].(https://www.nuget.org/packages/IEvangelist.Azure.CosmosRepository)

Cosmos Repository Setup

In order to set up the Cosmos Repository, you can use a simple extension provided by the library, which extends the ServiceCollection provided by Microsoft. See below.

using CosmosRepositoryPagingSample;
using Microsoft.Azure.CosmosRepository;

var builder = WebApplication.CreateBuilder(args);

const string databaseName = "people-database";
const string peopleContainerName = "people-container";
const string partitionKey = "/partitionKey";

builder.Services.AddCosmosRepository(options =>
{
    // In order to set this connection string run
    // dotnet user-secrets set RepositoryOptions:CosmosConnectionString "<your-connection-string>
    // options.CosmosConnectionString = "<taken-from-config>";

    options.DatabaseId = databaseName;
    options.ContainerPerItemType = true;

    options.ContainerBuilder
        .Configure<Person>(containerOptionsBuilder =>
    {
        containerOptionsBuilder
            .WithContainer(peopleContainerName)
            .WithPartitionKey(partitionKey);
    });
});

var app = builder.Build();

The only other thing you need to do is ensure that the model you are wanting to use implements the IItem interface. There are a set of base classes that are provided by the library that also implements this interface, such as FulllItem. This is used in the example of the Person object below.

class Person : FullItem
{
    public Person(
        string name, 
        int age, 
        string address)
    {
        Id = name;
        Name = name;
        Age = age;
        Address = address;
        PartitionKey = nameof(Person);
    }

    [JsonConstructor]
    private Person(
        string id, 
        string name, 
        int age, 
        string address, 
        string partitionKey)
    {
        Id = id;
        Name = name;
        Age = age;
        Address = address;
        PartitionKey = partitionKey;
    }

    public string Name { get; }
    public int Age { get; }
    public string Address { get; }
    public string PartitionKey { get; }

    protected override string GetPartitionKeyValue() =>
        PartitionKey;

The final thing to do is to inject an instance of the IRepository<Person> into any consumer and use the extensive set of methods provided. See this interfaces definition here.

Continuation token paging using the Cosmos Repository

The following endpoint demonstrates how you can use the Cosmos Repository to implement continuation token paging.

app.MapGet("/tokenBased", async (
    HttpContext context,
    [FromServices] IRepository<Person> repository,
    [FromQuery] int pageSize) =>
{
    string? continuationToken = 
        context.Request.Headers["X-Continuation-Token"];

    IPage<Person> result = await repository.PageAsync(
        x => x.PartitionKey == nameof(Person),
        pageSize,
        continuationToken);

    context.Response.Headers["X-Continuation-Token"] =
        result.Continuation;

    return new
    {
        requestUnits = result.Charge,
        count = result.Total,
        people = result.Items
    };
});

Skip, take paging using the Cosmos Repository

The skip, take approach using the Azure Cosmos Repository is shown below.

app.MapGet("/skipTake", async (
    [FromServices] IRepository<Person> repository,
    [FromQuery] int pageNumber,
    [FromQuery] int pageSize) =>
{

    IPageQueryResult<Person> result = await repository.PageAsync(
            x => x.PartitionKey == nameof(Person),
            pageNumber,
            pageSize);

    return new
    {
        requestUnits = result.Charge,
        count = result.Total,
        pages = result.TotalPages,
        people = result.Items
    };
});

The response that reading the 10th page resulted in is also shown below.

{
    "requestUnits": 14.100000000000001,
    "count": 400,
    "pages": 16,
    "people": [
        {
            "name": "Harry Pouros",
            "age": 26,
            "address": "635 Predovic Heights",
            "partitionKey": "Person",
            "etag": "\"0600097c-0000-0d00-0000-61e309330000\"",
            "timeToLive": null,
            "lastUpdatedTimeUtc": "2022-01-15T17:49:39",
            "lastUpdatedTimeRaw": 1642268979,
            "createdTimeUtc": null,
            "id": "Harry Pouros",
            "type": "Person"
        },
        //Excluded the rest of the results for brevity
    ]
}

Why use the Cosmos Repository?

I hope that the code samples above, look concise and succinct that was the aim. Furthermore, the IPage<TItem> and IPageQueryResult<TItem interfaces offer some extra properties returned back from a paging operation, such as how many items there are in total, how many pages there are, and it also includes the RU charge. These paging implementations also handle all of the query execution bits that were discussed earlier.

I may be slightly biased, being a passionate maintainer of the Cosmos Repository, but I feel this library offers a super-thin wrapper around the .NET SDK that includes a ton of great features! These features took a lot of time and effort to implement, this is time saved for any consumer of this package in my opinion. I would love anyone reading to try this out and offer any feedback via the GitHub repository.

It is worth also noting that there has been a lot of work by the EF Core team to integrate Cosmos DB into EF Core. It is certainly also worth considering this an option. See this blog post on some of the new features they have added.

Final words

Thank you for taking the time to read this and I certainly hope it has helped explain some of the options you have available for paging in Cosmos DB. I am happy to answer any questions feel free to reach out via the comments or tweet me @billydev5.

Sometimes when creating an object or performing a task via an API the creator of that API may want to ensure certain things happen sometimes in a specific order. It may also be the case that some things are required to happen and some things are not. A fluent API is a great way to guide a developer into a direction and also provides a great experience for them while being a client of your API.

There is a high likelihood that if you are reading this and have heard of the term fluent API or not that you will have used one before. It is highly likely that you will have made an API or seen an API made in ASPNET Core. If you have then you will have seen the Startup class. This class has two methods as shown below. Note that this example, shown below does not make separate calls to services or app it chains all of these calls together.

public class Startup
{
    public void ConfigureServices(IServiceCollection services) =>
        services.AddCosmosRepository(o =>
            {
                o.DatabaseId = "dogs-db";
                o.ContainerId = "dogs";
            })
            .AddSwaggerGen()
            .AddMvc();

    public void Configure(IApplicationBuilder app, IWebHostEnvironment env) =>
        app.UseSwagger()
            .UseSwaggerUI()
            .UseRouting()
            .UseEndpoints(endpoints =>
            {
                endpoints.MapControllers();
                endpoints.MapGet("/", async context =>
                {
                    await context.Response.WriteAsync("Dog API");
                });
            });
}

What makes an API fluent?

In the example of the Startup class shown above, we can see that every call to register some services or to configure some middleware on the app return an instance of the interface back from the method call. IServiceCollection and IApplicationBuilder respectively. The example shown above is one of the more flexible fluent APIs as it just returns an instance of the class over & over it does not guide a user down a specific path.

Guiding a developer

In order to guide a developer down a specific path when creating a fluent API, interfaces are used to restrict the next method that the user has access to when chaining the methods calls together. This is best shown via an example. This example will show an AccountBuilder, this has a few requirements.

1. An account must have an email address.
2. An account must have a password.
3. An account must verify the password used.
4. An account must have a password with a length of at least 6 characters.
5. An account must have a password with at least one of the special characters @$.
6. An account can optionally have a username.
7. An account can optionally have many roles.

In order to meet these requirements, an object has been defined for an account that exposes all of these properties to meet the requirements above. See below.

public class Account
{ 
    public string Id { get; set; } = Guid.NewGuid().ToString();

    public string Email { get; set; } = string.Empty;

    public string Password { get; set; } = string.Empty;

    public string? Username { get; set; }

    public List<string> Roles { get; set; } = new();
}

This class is all well and good but defines a public constructor. This means a client to this class could create it has not met any of the requirements listed above. What would be better is if we made this constructor internal and made the client create an account via a fluent API named AccountBuilder. This is going to make a user first, provide their email address, then provide a password, then verify that password before optionally providing a username and some roles. In order to let a user start the process, we will define a factory that returns an interface that only allows the user to initially provide their email address see the example below.

public interface IAccountBuilderWithEmail
{
    IAccountBuilderWithPassword WithEmailAddress(string email);
}

public static class AccountFactory
{
    public static IAccountBuilderWithEmail AccountBuilder() => new AccountBuilder();
}

The example above show's how the factory initially only lets the user of the api call the method WithEmailAddress(...). Until they have done this they do not get access to the interface named IAccountBuilderWithPassword which will then let them provide a password. See below.

public interface IAccountBuilderWithPassword
{
    IAccountBuilderWithVerifiedPassword WithPassword(string password);
}

This method then lets them verify this password via the interface IAccountBuilderWithVerifiedPassword but again nothing more. What this example ends up with is an interface per method that must be called and once completed, the method returns the next method that must be called. This is in essence guiding a developer through the process of creating an account. See all of the interfaces below to see how this starts to guide the user up until the optional part of the process is defined by the interface IAccountBuilder.

public interface IAccountBuilderWithEmail
{
    IAccountBuilderWithPassword WithEmailAddress(string email);
}

public interface IAccountBuilderWithPassword
{
    IAccountBuilderWithVerifiedPassword WithPassword(string password);
}

public interface IAccountBuilderWithVerifiedPassword
{
    IAccountBuilder VerifyPassword(string password);
}

public interface IAccountBuilder
{
    IAccountBuilder WithUsername(string username);

    IAccountBuilder WithRole(string role);

    IAccountBuilder WithRoles(params string[] roles);

    IAccountBuilder WithRoles(IEnumerable<string> roles);

    Account Build();
}

See how this is starting to come together? I hope so. The final interface that is returned once all the required methods have been called is IAccountBuilder. This then optionally allows the user to define roles & a user name before getting access to the Account object by calling Build() which completes the process of building an account.

The neat part about this is that all of the implementations for our fluent API can live inside a single class called AccountBuilder even though there are many interfaces guiding a client through this process. See the implementation below.

class AccountBuilder : 
        IAccountBuilderWithEmail, 
        IAccountBuilderWithPassword, 
        IAccountBuilderWithVerifiedPassword, 
        IAccountBuilder
    {
        readonly Account _account = new();

        public IAccountBuilderWithPassword WithEmailAddress(string email)
        {
            _account.Email = email;
            return this;
        }

        public IAccountBuilderWithVerifiedPassword WithPassword(string password)
        {
            if (password.Length < 6)
                throw new InvalidOperationException("A password must be at least 6 characters.");

            if (password.Contains('@') is false && password.Contains('$') is false)
                throw new InvalidOperationException("A password must contain one of the special characters '@$'.");

            _account.Password = password;
            return this;
        }

        public IAccountBuilder VerifyPassword(string password)
        {
            if (_account.Password != password)
                throw new InvalidOperationException("The passwords provided do not match.");

            return this;
        }

        public IAccountBuilder WithUsername(string username)
        {
            _account.Username = username;
            return this;
        }

        public IAccountBuilder WithRole(string role)
        {
            _account.Roles.Add(role);
            return this;
        }

        public IAccountBuilder WithRoles(params string[] roles)
        {
            _account.Roles.AddRange(roles);
            return this;
        }

        public IAccountBuilder WithRoles(IEnumerable<string> roles)
        {
            _account.Roles.AddRange(roles);
            return this;
        }

        public Account Build() => _account;
    }

Notice how this class implements all of the interfaces and after each method call it just returns this or itself back to the client to carry on building that account.

Putting it all together

The sample for this post can be found here and contains a console application which builds an Account and generates some JSON for that Account. See below.

Console Application

using System;
using System.Text.Json;
using FluentAccountApi.Sample;

Console.WriteLine("Starting the account builder demo.");

Account account = AccountFactory
    .AccountBuilder()
    .WithEmailAddress("joe.bloggs@gmail.com")
    .WithPassword("Test123@")
    .VerifyPassword("Test123@")
    .WithRoles("admin", "super")
    .WithUsername("joe123")
    .Build();

Console.WriteLine("Built account ->");
Console.WriteLine(JsonSerializer.Serialize(account, new JsonSerializerOptions{WriteIndented = true}));

Output

Starting the account builder demo.
Built account ->
{
  "Id": "dc2cc20f-153c-4371-a053-caa071012773",
  "Email": "joe.bloggs@gmail.com",
  "Password": "Test123@",
  "Username": "joe123",
  "Roles": [
    "admin",
    "super"
  ]
}

Final Words

Fluent APIs can really help a developer through the process of building an object from your library. They can be used in many places and a lot of developers really like using them. Please try out the example provided and get to grips with how it works. Hopefully, you will start to notice fluent APIs in the .NET ecosystem or maybe even create your own!

Find the source code here: https://github.com/mumby0168/blog-samples/tree/main/FluentAccountApi.Sample

Nuget packages are great and allow developers to make use of useful libraries put together by other developers. The version number is often important to developers many use the common pattern of Major.Minor.Patch in order to communicate changes to a package with other developers.

Major version increase usually represents a change to the public API surface that would likely require a developer to update their code that uses the API provided. Minor version increases, maybe a new feature to the package that maybe adds to the API surface, while maintaining backward compatibility with the previous versions. Patch usually contains a set of bug fixes that again are backward compatible.

Integrating with CI/CD

There are many, many nuget packages which are open source, and authors often encourage contributors to help maintain & evolve their packages. The most common way for this to be done currently is usually via GitHub. This allows developers, who are using a package, to see the source code, raise issues, fix bugs, and also fork the repository to later be merged back into the main repository with any changes they might make.

GitHub also offers Actions that allow you to perform continuous integration (CI) & continuous delivery (CD) of a piece of software. We can make use of GitHub tools to help us manage, deploying a package to nuget.org.

The Deployment Plan

So in order to do this, we want to really be creating a release of the package and as this happens and the version is specified by the individual making the release along with, detailing what that release includes. Then a workflow is triggered to build, test & deploy the package to nuget.org. GitHub offers this in the form of releases which at the same time tags a commit on a branch usually main/master with the version number specified. This article details how to create a release in GitHub here is a sneak peek at what that form looks like and what information it can include. The final step once we have created this release we want a GitHub Actions workflow to run, build, test, and pack our source code, apply for the version number and push it up to nuget.org which we will do in the next section.

Note where the version is specified.

Putting the Plan into (GitHub) Action(s)

So in order to implement this, we need a new pipeline within the repository that contains the library we want to package up. This is triggered when a tag is applied to a branch, more than likely the main branch. A sample pipeline is shown below, each step is explained after this snippet.

name: Release Package Version
on:
  push:  
    tags:
     - v*     
jobs: 
  build:
    if: github.event.base_ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:    

    - name: Print Tag Ref
      run: echo $GITHUB_REF

    - name: Extract Version Number
      uses: actions-ecosystem/action-regex-match@v2
      id: regex-match
      with:
        text: ${{ github.ref }}
        regex: '[0-9.]+'

    - name: Print Version Number
      run: echo '${{ steps.regex-match.outputs.match }}'

    - uses: actions/checkout@v2
    - name: Setup .NET  
      uses: actions/setup-dotnet@v1
      with:
        dotnet-version: 5.0.x

    - name: Restore dependencies
      run: dotnet restore ./Fruitless/Fruitless.csproj

    - name: Build
      run: dotnet build ./Fruitless/Fruitless.csproj

    - name: Pack
      run: dotnet pack ./Fruitless/Fruitless.csproj -p:PackageVersion='${{ steps.regex-match.outputs.match }}' --output packages

    - name: Publish Package
      run: nuget push **\*.nupkg -NoSymbols -Source 'https://api.nuget.org/v3/index.json' -ApiKey ${{secrets.NUGET_API_KEY}}

    - name: Upload Package
      uses: actions/upload-artifact@v2
      with:
        name: fruitless-pkg-v${{ steps.regex-match.outputs.match }}
        path: packages/

The pipeline explained

1. So the initial section of this pipeline is stating that this pipeline will only be triggered when a tag is applied to a branch that starts with a v.

2. The next section details a single job to run called build and this build has an if the condition that means if the branch is not main then this job will not run and will be skipped. This contains a set of steps detailed below.

3. It then prints the tag name that has triggered this pipeline.

4. It is then using a community provided regex tool to match the Major.Minor.Patch section from a string. (A tag of v1.2.3 would extract 1.2.3).

5. It then simply prints out the extracted version number extract via the match step.

6. Next it is just setting up the dotnet sdk version to use.

7. Then the project is built using dotnet build (tests can also be run at this point using dotnet test).

8. Then the package is packed using the package version extracted from step 4.

9. Last but not least, the package is pushed using an API key for nuget.org stored as a secret for this GitHub repository.

10. Finally, the .nupkg file/files are uploaded as an artifact for that build inside of GitHub actions.

Final Words

This is a simple way to get started with versioning packages and having them published via GitHub actions. The repository that this sample comes from is here. You can also see my trial and error here (everything doesn't always work the first time).

This can be expanded on in order to remove the regex part of the pipeline is to make use of the nuget package MinVer. This approach has been taken on one of my OSS projects and can be found here.

There are a few concepts glossed over here in terms of how GitHub Actions works and some of its syntax the documentation can be found here.