DEV Community: Guillaume Faas

How I Removed 1,500 Lines of Boilerplate with a Source Generator

Guillaume Faas — Tue, 08 Jul 2025 08:53:41 +0000

In my previous blog post, I explained why I rely so heavily on the Builder pattern. It facilitates the creation of my requests, guiding developers when creating objects.

This wasn't just a personal preference. I ended up there because Builders ticked all the boxes:

Predictable object creation
Control over validation failure
Support for both mandatory and optional parameters
A way to guide users with a Fluent API

But implementing those builders came with a heavy cost: boilerplate code. Each builder added 50+ lines of code on average; for simple/repetitive ones, and much more for complex ones.
That doesn't scale well: multiply this by 30+ use cases, and you get a lot of code that you have to write and maintain.

Let's address that particular problem.

What do we need?

The problem is not the builder itself. It's how much (repetitive) code it takes to get there, especially when a lot of them are very similar.

What we want is a way to:

Declare which requests require a builder
Declare mandatory and optional properties
Add validation rules
Return a Result upon creation, that will represent either a Request or a failure

In short, we want the same benefits, but with zero boilerplate.

Of course, we will not be able to apply this everywhere; some builders are quite specific, with internal behaviors. The goal is to remove the basic ones, the majority of them.

What are source generators?

Source Generators let you write code that runs at compile-time and generates other code.

In our case, we can write a class to make the generator:

Detect specific attributes
Create a builder dynamically
Generate a .g.cs file with all the code

For us, it means fewer files to maintain, less code to write. We also keep a consistent pattern across the codebase.
Also, adding a new builder is completely transparent; all we have to do is to create a new class with the rightattributes, and "voilà".

The Basics

If you want to build something similar, here are the foundational steps you'll need to follow:

Create a new Class Library project for the Generator
Create a Generator class that implements IIncrementalGenerator
Use Roslyn's syntax/semantic model to detect classes and their attributes
Generate new .cs file using SourceProductionContext

Here's a minimal example of what the setup looks like:

[Generator]
public class BuilderGenerator : IIncrementalGenerator
{
    public void Initialize(IncrementalGeneratorInitializationContext context)
    {
        var structDeclarations = IdentifyBuilders(context);
        context.RegisterSourceOutput(structDeclarations,
            (productionContext, structSymbols) =>
            {
                structSymbols.ToList().ForEach(symbol => GenerateSourceCode(symbol, productionContext));
            });
    }

    private static void GenerateSourceCode(INamedTypeSymbol structSymbol, SourceProductionContext productionContext)
    {
        var generatedCode = ... // Generate the builder's code
        var fileName = $"{structSymbol.Name}Builder.g.cs";
        productionContext.AddSource(fileName, SourceText.From(generatedCode, Encoding.UTF8));
    }
}

We'll walk you through the building blocks in the next section.

Under the Hood

Here's how I structured the generator.

I have four attributes:

"Builder" which will decorate a struct, marking them as requiring builder.
"Mandatory" which will decorate a property, marking it as mandatory.
"Optional" which will decorate a property, marking it as optional.
"Validation" which will decorate a method, used to validate the request.

The generator will find all structs marked with Builder...

private static bool HasBuilderAttribute(SyntaxNode node) =>
    node is StructDeclarationSyntax declaration && declaration.AttributeLists
        .SelectMany(syntax => syntax.Attributes)
        .Any(syntax => syntax.Name.ToString() == BuilderAttribute);

private static IncrementalValueProvider<ImmutableArray<INamedTypeSymbol>> IdentifyBuilders(
    IncrementalGeneratorInitializationContext context) =>
    context.SyntaxProvider
        .CreateSyntaxProvider(
            static (node, _) => HasBuilderAttribute(node),
            static (context, _) => GetStructSymbol(context)
        )
        .Where(symbol => symbol is not null)
        .Select((symbol, _) => symbol)
        .Collect();

And fetch properties marked as Mandatory or Optional.

private static IEnumerable<MandatoryProperty> GetMandatoryProperties(INamedTypeSymbol structSymbol) =>
    GetMembersForAttribute(structSymbol, MandatoryProperty.AttributeName).Select(MandatoryProperty.FromMember);

private static IEnumerable<IPropertySymbol> GetMembersForAttribute(INamedTypeSymbol structSymbol,
    string attributeName) =>
    structSymbol.GetMembers().OfType<IPropertySymbol>()
        .Where(member =>
            member.GetAttributes().Any(attribute => attribute.AttributeClass?.Name == attributeName));

When all the data is gathered, we proceed to create our Builder, line by line:

Our using statements
The namespace
Interface declarations
Our builder
etc...

We're essentially creating the entire file ourselves, as a string:

public string GenerateCode()
{
    var code = string.Concat(this.GenerateUsingStatements(),
        this.GenerateNamespace(),
        this.GenerateInterfaceDeclarations(),
        this.ExtendTypeWithPartial(),
        this.GenerateBuilder()
    );
    return FormatCode(code);
}

private string GenerateUsingStatements()
{
    var builder = new StringBuilder();
    builder.AppendLine("using Vonage.Common.Client;");
    builder.AppendLine("using Vonage.Common.Monads;");
    builder.AppendLine("using Vonage.Common.Validation;");
    var parameters = type.GetAttributes()
        .First(attr => attr.AttributeClass!.Name == "BuilderAttribute")
        .ConstructorArguments;
    if (parameters.Any())
    {
        parameters.First().Values.Select(value => value.Value?.ToString()).ToList()
            .ForEach(value => builder.AppendLine($"using {value};"));
    }

    return builder.ToString();
}

private string GenerateNamespace() =>
    string.IsNullOrEmpty(type.ContainingNamespace?.ToDisplayString())
        ? string.Empty
        : $"namespace {type.ContainingNamespace.ToDisplayString()};\n\n";

private string GenerateInterfaceDeclarations() =>
    string.Concat(this.GetBuilderInterfaces().Select(builderInterface => builderInterface.BuildDeclaration()));

// ...

Example: from Request to Builder

You'll find below an example: VerifyCodeRequest, which allows us to verify a 2FA code with our [Verify (https://developer.vonage.com/en/verify/overview) API.

This is the code from my initial request:

namespace Vonage.VerifyV2.VerifyCode;

[Builder] // This request requires a builder
public readonly partial struct VerifyCodeRequest : IVonageRequest
{
    [Mandatory(1)] // Code is mandatory, and second property to set
    public string Code { get; internal init; }

    [JsonIgnore]
    [Mandatory(0)] // RequestId is mandatory, and first property to set
    public Guid RequestId { get; internal init; }

    ...

    [ValidationRule] // ValidationRule for our builder
    internal static Result<VerifyCodeRequest> VerifyCodeNotEmpty(
        VerifyCodeRequest request) =>
        InputValidation
            .VerifyNotEmpty(request, request.Code, nameof(request.Code));

    [ValidationRule] // ValidationRule for our builder
    internal static Result<VerifyCodeRequest> VerifyRequestIdNotEmpty(
        VerifyCodeRequest request) =>
        InputValidation.VerifyNotEmpty(request, request.RequestId, nameof(request.RequestId));
}

And this is the builder (VerifyCodeRequestBuilder.g.cs), generated by our source generator:

using Vonage.Common.Client;
using Vonage.Common.Monads;
using Vonage.Common.Validation;

namespace Vonage.VerifyV2.VerifyCode;
public interface IBuilderForRequestId
{
    IBuilderForCode WithRequestId(System.Guid value);
}

public interface IBuilderForCode
{
    IBuilderForOptional WithCode(string value);
}

public interface IBuilderForOptional : IVonageRequestBuilder<VerifyCodeRequest>
{
}

public partial struct VerifyCodeRequest
{
    public static IBuilderForRequestId Build() => new VerifyCodeRequestBuilder();
}

internal struct VerifyCodeRequestBuilder : IBuilderForRequestId, IBuilderForCode, IBuilderForOptional
{
    private System.Guid requestid;
    private string code;
    public VerifyCodeRequestBuilder()
    {
        this.requestid = default;
        this.code = default;
    }

    public IBuilderForCode WithRequestId(System.Guid value) => this with
    {
        requestid = value
    };
    public IBuilderForOptional WithCode(string value) => this with
    {
        code = value
    };
    public Result<VerifyCodeRequest> Create() => Result<VerifyCodeRequest>.FromSuccess(new VerifyCodeRequest { RequestId = this.requestid, Code = this.code, }).Map(InputEvaluation<VerifyCodeRequest>.Evaluate).Bind(evaluation => evaluation.WithRules(VerifyCodeRequest.VerifyCodeNotEmpty, VerifyCodeRequest.VerifyRequestIdNotEmpty));
}

You probably noticed a couple of other things:

Our builder is in the same namespace as our request (Vonage.VerifyV2.VerifyCode), making it transparent for people who uses our code. They don't know, and they don't need to know, that the builder has been automatically generated.
We also extend our partial Request to add a static method Build() to initialize the builder with Request.Build()

Finally, here's a usage example:

var request = VerifyCodeRequest.Build()
    .WithRequestId(Guid.Parse("68c2b32e-55ba-4a8e-b3fa-43b3ae6cd1fb"))
    .WithCode("123456789")
    .Create()

In my case, my builders were already thoroughly tested before I introduced source generators. I used my test suite to guarantee that no builder's public api changed in the process, making sure that not a single breaking change was introduced.

Testing

Talking about testing, it's relatively straightforward.

You need to initialize your source generator (BuilderGenerator is the generator we created earlier), run the generation and compare the result with your expectation:

private static string GenerateCode(string inputCode)
{
    var compilation = CSharpCompilation.Create(TestNamespace, [CSharpSyntaxTree.ParseText(inputCode)],
        [MetadataReference.CreateFromFile(typeof(object).Assembly.Location)],
        new CSharpCompilationOptions(OutputKind.DynamicallyLinkedLibrary)
    );
    var driver = CSharpGeneratorDriver.Create(new AttributesGenerator(), new BuilderGenerator());
    driver.RunGeneratorsAndUpdateCompilation(compilation, out var outputCompilation, out _);
    return outputCompilation.SyntaxTrees.Last().ToString().Trim();
}

[Theory]
[InlineData("...")]
[InlineData("...")]
[InlineData("...")]
[InlineData("...")]
[InlineData("...")]
public void VerifyCodeGeneration(string sample)
{
    var inputCode = File.ReadAllText($"Files/{sample}_Input.txt").Trim();
    var expectedGeneratedCode = File.ReadAllText($"Files/{sample}_Expected.txt").Trim();
    Assert.Equal(NormalizeLineBreaks(expectedGeneratedCode), NormalizeLineBreaks(GenerateCode(inputCode)));
}

Each test data focuses on a specific feature.
For example, here's my input file when testing a mandatory property with a validation rule:

namespace Vonage.TestProduct.TestRequest;
using Vonage.Common.Validation;

[Builder]
public readonly partial struct MyRequest : IVonageRequest
{
    [Mandatory(0)]
    public string Name { get; internal init; }

    [ValidationRule]
    internal static Result<MyRequest> VerifyName(MyRequest request) =>
        InputValidation.VerifyNotEmpty(request, request.Name, nameof(request.Name));
}

And here's the expected output that I will compare to the generator's output:

using Vonage.Common.Client;
using Vonage.Common.Monads;
using Vonage.Common.Validation;

namespace Vonage.TestProduct.TestRequest;
public interface IBuilderForName
{
    IBuilderForOptional WithName(string value);
}

public interface IBuilderForOptional : IVonageRequestBuilder<MyRequest>
{
}

public partial struct MyRequest
{
    public static IBuilderForName Build() => new MyRequestBuilder();
}

internal struct MyRequestBuilder : IBuilderForName, IBuilderForOptional
{
    private string name;
    public MyRequestBuilder()
    {
        this.name = default;
    }

    public IBuilderForOptional WithName(string value) => this with
    {
        name = value
    };
    public Result<MyRequest> Create() => Result<MyRequest>.FromSuccess(new MyRequest { Name = this.name, }).Map(InputEvaluation<MyRequest>.Evaluate).Bind(evaluation => evaluation.WithRules(MyRequest.VerifyName));
}

Resources

Everything I shared above is publicly available.

Whether you'd like to verify I'm not lying, see the entire implementation or take some code, please yourself; it's all open-source code.

SourceGenerator project: https://github.com/Vonage/vonage-dotnet-sdk/tree/main/Vonage.SourceGenerator
SourceGenerator test project: https://github.com/Vonage/vonage-dotnet-sdk/tree/main/Vonage.SourceGenerator.Test
VerifyCodeRequest: https://github.com/Vonage/vonage-dotnet-sdk/blob/main/Vonage/VerifyV2/VerifyCode/VerifyCodeRequest.cs
VerifyCodeRequest tests: https://github.com/Vonage/vonage-dotnet-sdk/blob/main/Vonage.Test/VerifyV2/VerifyCode/RequestBuilderTest.cs

Wrapping up

With source generators, I was (so far) able to remove roughly 1'500 lines of repetitive code without making compromises on functionalities, nor any change in my builder's public api. It is also much easier to add new builders now: a couple attributes on a request, and we're ready to roll.

The next step is to iterate on my source generator to support more advanced use cases.I already handle more specific use cases that I didn't detailed above, like

Optional Booleans which defines a default value and exposes an explicit method to change the state, like default is true, and "Disable" sets the value to false. This improves the experience overall by making the intent explicit, instead of relying on true/false values.
Optional values with default which allows setting default values for Optional properties.

For sure, I won't be able to replace all my builders; but being able to substitute standard ones is already a big win.

I hope you learned something today.
Happy coding, and see you soon!

During presentations of "Throw exceptions... away from your codebase", I've been asked a lot "Why I use so much on the Builder pattern?". So, I just wrote a post about it. On the menu: Immutability, Parsing, Validation, and Fluent APIs.

Guillaume Faas — Mon, 17 Feb 2025 06:11:05 +0000

Why I use (and abuse) the Builder pattern

Guillaume Faas ・ Feb 13

#dotnet #monads #design #programming

Why I use (and abuse) the Builder pattern

Guillaume Faas — Thu, 13 Feb 2025 06:22:31 +0000

When presenting my talk about Monads, one question kept coming up: "Why do you rely so much on the Builder pattern?".

I didn't implement that pattern just because it looks cool. I've observed recurring problems, and solving them led me to that particular solution.

So, when people see one of my builders, they often don't see what led to this particular implementation.

Let's answer that one today.

Disclaimer: This post is highly personal and opinionated. It's based on my experience, observations and preferences. It's not a one-size-fits-all solution, nor the only way to solve the problems I'm going to present. It's just the way I do it.

How we got here

We've all, at some point, instantiated an object like this:

public class Food
{
    public string Name { get; set; }
    public DateTime ExpirationDate { get; set; }
    public string Description { get; set; }
}

var apple = new Food
{
    Name = "Apple",
    ExpirationDate = DateTime.Now.AddDays(7),
    Description = "An apple",
};

It's simple, clean, efficient and works... except, I see a multitude of issues. I won't even talk about Food being an anemic model (pure DTO style) without any proper behavior and absolutely no encapsulation. This is for another time.

Problem #1: Mutability

Our Food class is mutable - we can change its properties anytime:

var apple = new Food
{
    Name = "Apple",
    ExpirationDate = DateTime.Now.AddDays(7),
    Description = "An apple",
};
apple.ExpirationDate = DateTime.Now.AddDays(14);

Mutability seems useful, but it's a ticking bomb. Changing an object's state introduces complexity, and you'll find yourself constantly evaluating the state of such object.

Immutability, on the other hand, ensures an object cannot be changed after its creation, leading to benefits like data integrity, thread safety, and a limitation of side effects.

We have options to make our Food class immutable, such as using readonly/init-only properties or transforming it into a record.

// Init-only properties
public class Food
{
    public string Name { get; init; }
    public DateTime ExpirationDate { get; init; }
    public string Description { get; init; }
}

// Record
public record Food(string Name, DateTime ExpirationDate, string Description);

A question often arises at this stage: "What if we need to change the state of an immutable object?". Simple, you don't - you create a new object with a new state:

var freshApple = apple with { ExpirationDate = DateTime.Now.AddDays(14) };

Happy yet? Not really. We fixed one problem, but others remain.

Problem #2: Parsing

Making our class immutable already simplifies validation: since the object can’t change, validation occurs only once.

I follow the "Parse, don't Validate" approach which ensures only valid objects can be created. Parsing is about transforming a less structured input into a more structured output - in our case, turning {string, DateTime, string} into a Food object.

However, validation with auto-properties is tricky. One option is to define the validation as a lambda inside each init property with an explicit backing fields - but that feels clunky, especially since properties aren't mandatory, meaning you can't enforce required field. So... you'll have to validate post-creation, and we're back to square one. Another option is to enforce the use of a constructor, which record types already do.

For example, we don't want a Food instance to be created with past expiration dates:

var apple = new Food("Apple", DateTime.Now.AddDays(-10), string.Empty };

public record Food(string Name, DateTime ExpirationDate, string Description)
{
     // Validation logic...
}

But here's the problem: A valid input will produce a valid Food object - what will an invalid input produce?

With constructors, we have no control over the return type - the constructor must return a Food instance. This leaves two possible options:

Returning null - a dangerous option, it's called the "billion-dollar mistake" by Tony Hoare for a reason.
Throwing an exception - terrible choice for a predictable validation failure.

Neither is great.

A better approach is to rely on a static factory method as the single point of entry to create a Food object, giving us control over the return type.

var apple = Food.Create("Apple", DateTime.Now.AddDays(-10), string.Empty);

public static Food Create(string name, DateTime expirationDate, string description)
{
    // Validation logic.
}

One important thing to note: we have to rule out the record type. Even with a private constructor, with expressions can bypass our single point of entry.

I put code transparency and predictability quite high in my priorities, which is why I would favor Monads for this (see my "The Monad Invasion" series).

var apple = Food.Create("Apple", DateTime.Now.AddDays(-10), string.Empty);

public record Error(string Reason);
public static Either<Error, Food> Create(string name, DateTime expirationDate, string description)
{
    if (string.IsNullOrEmpty(name))
    {
        return new Error("Name cannot be empty");
    }

    if (expirationDate < DateTime.Now)
    {
        return new Error("Expiration date cannot be in the past");
    }

    return new Food(name, expirationDate, description);
}

The intent is clear, and the outcome is transparent: creating a Food instance can fail.

Problem #3: Too many parameters

Our Food class currently has three properties. What if it had 15? 20? 50?

public static Food Create(string name, 
    DateTime expirationDate, 
    string description,
    string category,
    decimal weight,
    decimal price,
    ...)
{
    // ...
}

Our static factory method solved a problem, but it struggles as the number of parameters grows. IDEs often provide warnings against constructors with more than 5 parameters, and for good reason. Methods with many parameters or multiple overloads are a nightmare to maintain.

We need a better way to create complex objects while keeping the benefits we've gained so far.

This is where the Builder pattern offers an interesting solution.

var apple = Food.Builder()
    .WithName("Apple")
    .WithExpirationDate(DateTime.Now.AddDays(7))
    .WithDescription("An apple")
    .Build();

Each method takes one parameter, and Build handles validation before creating the object.

The Builder ticks all the boxes

Immutability - the builder acts as a factory, and is able to create immutable objects.
Validation - the builder can validate the object when we want to create it.
Control over validation failure - the builder is able to return a predictable result when validation fails.
Scalability - the builder handles a large number of parameters without becoming a mess.

A well-designed Builder pattern also helps guide users. By chaining methods, developers naturally discover what fields are required and what comes next - your IDE will show it for you.

For example, our API ensures Name and ExpirationDate are mandatory, while Description is optional (can be null or empty).

var apple = Food.Builder()
    // Only option is .WithName
    .WithName("Apple")
    // Only option is .WithExpirationDate
    .WithExpirationDate(DateTime.Now.AddDays(7))
    // User has two options:
    // Optional properties like .WithDescription
    // Or .Build() to create the object
    .WithDescription("An apple")
    // User has two options:
    // Other optional properties
    // Or .Build() to create the object
    .Build();

In open-source software, making code self-explanatory is a game-changer.

Downsides

If Builders were free, everybody would use them. Sadly, they're not and require a fair amount of boilerplate. Your builder needs a class, a method for each property, and interfaces to guide the user - not to mention that you should also test your code.

Overall, we're talking about 50+ extra lines of code for an object like Food. This is one. simple. object.

Libraries like FluentBuilder generate builders via SourceGenerators, helping a lot with the boilerplate, but we're losing the flexibility for custom scenarios.

While Builders solve many problems, they aren't always the best choice. If your object is simple and rarely changes, a factory method might be sufficient. On my end, I prefer to start with a factory method and switch to a Builder when the object becomes more complex.

Another downside is that validation gets separated from the object itself - data is on the object, while validation is on the Buidler. This can potentially lead to encapsulation issues (See Tell, Don't Ask). My advice: keep them close to maintain strong cohesion and use the internal keyword to expose only what's necessary. That being said, I've never encountered a scenario where it was a critical problem.

Example

Here's an actual implementation from my current codebase, the Vonage .NET SDK.

This is the initial object we're willing to create.

public readonly struct CheckRequest : IVonageRequest
{
    // Immutable properties
    public PhoneNumber PhoneNumber { get; internal init; }
    public int Period { get; internal init; }
    // The static Build() method exposes the builder
    public static IBuilderForPhoneNumber Build() => new CheckRequestBuilder();
}

Source: CheckRequest

This is the builder itself. We're using interfaces to direct what the user can do: the phone number is mandatory, the period is optional (with a default value).

There are two possible paths here:

PhoneNumber (mandatory) -> Build
PhoneNumber (mandatory) -> Period (optional) -> Build

internal struct CheckRequestBuilder : IBuilderForPhoneNumber, IBuilderForOptional
{
    private const int DefaultPeriod = 240;
    private const int MaximumPeriod = 2400;
    private const int MinimumPeriod = 1;
    private int period = DefaultPeriod;
    private string number = default;

    public Result<CheckRequest> Create() =>
        Result<CheckRequest>.FromSuccess(new CheckRequest
            {
                Period = this.period,
            }).Merge(PhoneNumber.Parse(this.number), (request, validNumber) => request with {PhoneNumber = validNumber})
            .Map(InputEvaluation<CheckRequest>.Evaluate)
            .Bind(evaluation => evaluation.WithRules(VerifyAgeMinimumPeriod, VerifyMaximumPeriod));

    // Assign value on the builder
    public IVonageRequestBuilder<CheckRequest> WithPeriod(int value) => this with {period = value};
    // Assign value on the builder
    public IBuilderForOptional WithPhoneNumber(string value) => this with {number = value};

    // Validation
    private static Result<CheckRequest> VerifyAgeMinimumPeriod(CheckRequest request) =>
        InputValidation.VerifyHigherOrEqualThan(request, request.Period, MinimumPeriod, nameof(request.Period));
    // Validation
    private static Result<CheckRequest> VerifyMaximumPeriod(CheckRequest request) =>
        InputValidation.VerifyLowerOrEqualThan(request, request.Period, MaximumPeriod, nameof(request.Period));
}

public interface IBuilderForPhoneNumber
{
    // Will return the next step in the builder, for optional values or to build the object
    IBuilderForOptional WithPhoneNumber(string value);
}

public interface IBuilderForOptional : IVonageRequestBuilder<CheckRequest>
{
    // Will return the final step in the builder to build the object
    IVonageRequestBuilder<CheckRequest> WithPeriod(int value);
}

Source: CheckRequestBuilder

This is a usage example, from the test suite.

[Trait("Category", "Request")]
public class RequestBuilderTest
{
    [Theory]
    [InlineData("")]
    [InlineData(" ")]
    [InlineData(null)]
    public void Build_ShouldReturnFailure_GivenNumberIsNullOrWhitespace(string value) =>
        CheckRequest.Build()
            .WithPhoneNumber(value)
            .Create()
            .Should()
            .BeFailure(ResultFailure.FromErrorMessage("Number cannot be null or whitespace."));

    // ...

    [Theory]
    [InlineData(1)]
    [InlineData(2400)]
    public void Build_ShouldSetPeriod(int value) =>
        CheckRequest.Build()
            .WithPhoneNumber("1234567")
            .WithPeriod(value)
            .Create()
            .Map(number => number.Period)
            .Should()
            .BeSuccess(value);

    // ...
}

Source: RequestBuilderTest

Wrapping Up

Each problem I solved narrowed down the pool of possible solutions, and I landed on Builders because they address issues I consider important. You may disagree, and that's totally fine.

I hope you learned something during that post, and I'm curious to know your thoughts on the subject.

Until next time, cheers!

The Monad Invasion - Part 3: Railway-Oriented Programming

Guillaume Faas — Fri, 15 Nov 2024 12:09:01 +0000

Hello friends,

Our previous post, "The Monad Invasion - Part 2: Monads in action!", introduced a set of various Monads and how they can fit in real-world scenarios.

Today, we will focus on Railway-Oriented Programming (ROP), a functional approach to error handling.

Spoiler: If you've read our previous posts, you observed ROP without actually being aware of it.

Quick Recap

We used our Two-Factor Authentication (2FA) as a real example. This two-steps workflow requires initiating a verification first and then verifying the code sent to the user.

var myPhoneNumber = ...
var result = await StartVerificationRequest.Build()
    .WithBrand("Monads Inc.")
    .WithWorkflow(SmsWorkflow.Parse(myPhoneNumber))
    .Create() // Build the authentication request
    .BindAsync(request => verifyClient.StartVerificationAsync(request)) // Process the authentication request
    .BindAsync(VerifyCodeAsync) // Start the second step if it's a success
    .Match(AuthenticationSuccessful, AuthenticationFailed);

private async Task<Result<Unit>> VerifyCodeAsync(StartVerificationResponse response)
{
    var myCode = ... // Receive verification code based on the specified workflow
    return await response
        .BuildVerificationRequest(myCode) // Build the verification request
        .BindAsync(request => verifyClient.VerifyCodeAsync(request)); // Process the verification request
}

As suggested previously, this snippet already applies ROP. You probably have a lot of questions right now. What is ROP? How does it work? Why is it useful?

Let's start from the beginning, shall we?

Failure Is Expected

It is strictly impossible to build software without handling errors. In the real world, failure can occur at any point during the execution, and we cannot ignore them.

What if we had the same workflow, written in an imperative style?

var myPhoneNumber = ...
var request = await StartVerificationRequest.Build().WithBrand("Monads Inc.").WithWorkflow(SmsWorkflow.Parse(myPhoneNumber)).Create();  
var response = verifyClient.StartVerificationAsync(request);
var myCode = ... // Receive verification code based on the specified workflow
var verificationRequest = response.BuildVerificationRequest(myCode)
var result = verifyClient.VerifyCodeAsync(verificationRequest);    
this.AuthenticationSuccessful();

It looks similar but something important is missing - error handling. Indeed, this snippet only shows the happy path, where everything goes as expected.

Of course, this is not enough - we aim for feature parity between these snippets. In its current state, any failure would cause our system to crash. As we previously mentioned, this flow can fail at various locations:

When building the authentication request
When processing the authentication request
When building the verification request
When processing the verification request

What's the difference if we decide to handle errors then?

var myPhoneNumber = ...
var request = await StartVerificationRequest.Build().WithBrand("Monads Inc.").WithWorkflow(SmsWorkflow.Parse(myPhoneNumber)).Create();
if (request.IsFailure)
{
    // Can fail when Brand is invalid
    // Can fail when PhoneNumber is invalid
    return this.AuthenticationFailed(new Failure("Invalid input."));
}

var response = verifyClient.StartVerificationAsync(request);
if (response.IsFailure)
{
     // Can fail when process can't be initiated
     return this.AuthenticationFailed(new Failure("Cannot initiate verification process."));
}

var myCode = ... // Receive verification code based on the specified workflow
var verificationRequest = response.BuildVerificationRequest(myCode)
if (response.IsFailure)
{
    // Can fail when the code input is invalid
    return this.AuthenticationFailed(new Failure("Invalid code."));
}

var result = verifyClient.VerifyCodeAsync(verificationRequest);    
if (result.IsFailure)
{
    // Can fail when the verification fails
    return this.AuthenticationFailed(new Failure("Verification failed."));
}

return this.AuthenticationSuccessful();

We need to add an important boilerplate code to deal with potential failure. This code is dense and hard to read. We now have more code to handle failures than the happy path itself, which is not a coincidence. We only have a single happy path but multiple reasons to fail.

There's something important to observe here:

This snippet offers the same behaviour as the one from the Quick Recap section, except it takes roughly three times more code to do it.
The cyclomatic complexity also increases significantly, from 1 to 6, in a blink of an eye.

Have I piqued your interest yet? It's time to introduce Railway-Oriented Programming.

Railway-Oriented Programming

Note: This section shares resources from the
talk "Railway-Oriented Programming — error handling in a functional way"
by Scott Wlaschin.
More details are available on F#ForFunAndProfit.

Railway-Oriented Programming is a functional approach to error handling. The main idea is to consider the "Happy Path" (Green) as the main track, providing our expected behaviour.

In the example above, our workflow is composed of three steps:

Validate an input.
Update a record - if the input is valid.
Send a notification - if the record update is successful.

Here's what it looks like in an imperative fashion:

if (this.Validate(input))
{
    try
    {
        var record = this.Update(input);
        this.SendNotification(record);
    }
    catch (Exception)
    {
        ...        
    }
}

We consider our workflow successful only if these three steps are successful.

We remain on that "Happy Path" until we face an error, which leads us to a "Failure Path" (Red). When this happens, we carry the failure until the end of the flow. It's crucial that we stick to the main path, as it's the only way to ensure the full execution of our workflow.

In the example above, we skip the update step when the validation fails. This is only possible because our functions return multiple possible states: a Success or a Failure.

Does it ring a bell? What a coincidence, we use Monads for that! You didn't see that one coming - or did you?

In our previous post, we saw how to change the status of a Monad from one state to another using the .Bind() method. This fundamental concept allows us to create this branching between tracks.

There's no magic here. The branching didn't disappear with a magic wand or anything like that. The branching is now internal to our Monad.

Have a look at how Bind is implemented on our custom Monad:

return this.IsFailure ? Result<TB>.FromFailure(this.failure) : bind(this.success);

Our decision mechanism - a ternary operator - verifies if the current state is a failure or a success.

If it is a failure, we return the current failure; nothing happens.
If it is a success, we call the bind function to continue the flow.

As such, we can chain our operations together, and the flow will automatically switch to the failure path if any of the operations fail.

Here's the same workflow as before, but this time using ROP:

var result = input.Bind(Validate).Bind(Update).Bind(SendNotification);

Impressive, right? We reduced our code to a single line while covering the same features.

Let's Play a Little Game

Here's a code sample from our .NET SDK that allows us to authenticate for one of our Network APIs.

Can you find out what the railway tracks look like? Where can our workflow fail?

You don't need to know what's happening here; there's no logic. Focus on the flow.

public Task<Result<AuthenticateResponse>> AuthenticateAsync(Result<AuthenticateRequest> request) =>
    request.Map(BuildAuthorizeRequest)
        .BindAsync(this.SendAuthorizeRequest)
        .Map(BuildGetTokenRequest)
        .BindAsync(this.SendGetTokenRequest)
        .Map(BuildAuthenticateResponse);

The answer is quite simple - our railway contains two points of branching:

When sending the authorize request.
When sending the get token request.

This is explicit because we rely on the Bind method for those operations.

For another comparison, here's the same code written in an imperative style:

public async Task<Result<AuthenticateResponse>> AuthenticateAsync(AuthenticateRequest request)
{
    var authorizeRequest = BuildAuthorizeRequest(request);
    var authorizeResponse = await this.SendAuthorizeRequest(authorizeRequest);
    if (authorizeResponse.IsFailure)
    {
        return Result<AuthenticateResponse>.FromFailure(authorizeResponse.Failure);
    }

    var getTokenRequest = BuildGetTokenRequest(authorizeResponse.Success);
    var getTokenResponse = await this.SendGetTokenRequest(getTokenRequest);
    if (getTokenResponse.IsFailure)
    {
        return Result<AuthenticateResponse>.FromFailure(getTokenResponse.Failure);
    }

    return BuildAuthenticateResponse(getTokenResponse.Success);
}

As you can see, reading and understanding the flow is much easier than in the imperative style, and the function is smaller.
We achieved that by reducing the cognitive load of our method — reducing the required quantity of technical information (branching,
logic, variables, etc.) helps to make the code "fit in your head" (
see "Code that fits in your head" by Mark Seemann).

Processes Fail For Multiple Reasons

Looking at our previous example, our workflow can fail at two points - this could be a problem for us.

Our failure path carries what we define as a Failure state. We implemented our Monad so that it can carry either a Success or a Failure value using generics. We can picture it as a Result<TFailure, TSuccess.

See where I'm going?

Because of how generics work in C#, an instance of Result must always carry the same type of failure. In other terms, all our failures must have the same type - that's a problem as you may decide to treat a parsing failure differently than an API failure.

We cannot blame Monads or ROP for this issue - it is a language limitation. In comparison, this is where a language like F# shines, as it allows us to define a discriminated union type that can carry multiple types of failures. Still, hope is possible - discriminated unions will eventually come to C#.

While we can't ignore this limitation, it doesn't mean we're entirely stuck. One way to group different failures under
the same generic type is to use a base class or an interface.

In the .NET SDK, I implemented an IResultFailure interface that all failures must implement. It allows us to group different failures (or reasons to fail - parsing, authentication, etc.) on the same failure path and define dedicated behaviours using the Type property.

public interface IResultFailure
{
    /// <summary>
    ///     The type of failure.
    /// </summary>
    Type Type { get; }

    /// <summary>
    ///     Returns the error message defined in the failure.
    /// </summary>
    /// <returns>The error message.</returns>
    string GetFailureMessage();

    /// <summary>
    ///     Converts the failure to an exception.
    /// </summary>
    /// <returns>The exception.</returns>
    Exception ToException();

    /// <summary>
    ///     Converts the failure to a Result with a Failure state.
    /// </summary>
    /// <typeparam name="T">The underlying type of Result.</typeparam>
    /// <returns>A Result with a Failure state.</returns>
    Result<T> ToResult<T>();
}

This is not a perfect solution and probably not the most elegant one. But this is similar to handling different types of exceptions, like the following example:

try { ... }
catch (ExceptionA) { ... }
catch (ExceptionB) { ... }
catch (ExceptionC) { ... }

// ---

switch (failure)
{
    case HttpFailure httpFailure:
        DoSomethingWithHttpFailure(httpFailure);
        break;
    case ResultFailure resultFailure:
        DoSomethingWithResultFailure(resultFailure);
        break;
    default:
        DoSomethingWithFailure(failure);
        break;
}

As you can see, ROP allows us to use the same functionalities as exceptions - it's not a replacement, just an alternative to error handling which looks a bit different.

Conclusion

And there we have it — our third post in "The Monads Invasion" series. This time, we focused on Railway-Oriented Programming (ROP) to show how you can use Monads even further to handle errors.

The key takeaway? There's no loss when using Monads for error handling compared to a standard exception-based approach; everything you do using exceptions can be done with Monads. You'll likely find your code cleaner, easier to read, and more explicit about its intent.

Now, the real question: are you ready to try it?

I suggest starting small and easing into it. There's a learning curve like anything new, but stick with it, and you'll see the benefits.

If you have any questions or want to chat, feel free to hit me up on my LinkedIn, share your feedback on the .NET SDK repository or join us on
the Vonage Developer Slack. You can also message us on @VonageDev on X. We're all in this together, and your voice matters.

Happy coding, and I'll catch you later!

How I Became a Millionaire with Vonage APIs

Guillaume Faas — Wed, 13 Nov 2024 07:28:12 +0000

Spoiler: I'm not actually a millionaire.

We’ve all dreamt about it — sitting in the hot seat on 'Who Wants to Be a Millionaire', staring down that final question, the host waiting for your answer.
But what if, in a world of multiverses and alternate realities, I walked away with a fat check in hand?

What if I told you that I figured out a way to win. Every. Single. Time.

In this post, we'll be stepping into this alternate universe for a moment — where Vonage’s APIs made me a millionaire, and no one suspected a thing.

The Perfect Heist

In this universe, I'm not just a contestant on a game show - I'm the mastermind behind the perfect heist.
One final questions separates me from the grand prize.
I have carefully saved my last lifeline, "Call a friend", for this exact moment.
The stakes couldn't be higher, but I'm cool.
I'm in control.

Why? Because this isn't your ordinary phone call.

I've got an ace up my sleeve - a friend who knows everything.
Instead of calling an actual person, I've set up something a little... unconventional.
The number I gave the show is a virtual phone number I purchased from Vonage.

The second the host dials the number, my meticulous planned operation kicks into action.
No one in the audience, not even the host, has any idea what's happening behind the scenes.
A chain of automated processes, all powered by Vonage APIs, springs to life to provide me the right answer.

The perfect heist isn't just about getting away with it - it's about pulling it off so smoothly that no one even realizes anything unusual happened.

Let me guide you through how I pulled it off.

Insert 'Evil Laugh' here

Step 1: We Need A Number

Every heist starts with the right tools, and in this case, we need a number — a virtual one.
Why a virtual number?
Because it’s the key to controlling the flow of information, giving us the ability to intercept the call and manipulate it on our terms.
It supports both inbound and outbound for calls and messages.
No device required, no manual intervention — just a virtual number and a webhook.

A virtual number allows you to receive calls and route them anywhere — even to an automated system.
In this case, the call will trigger a series of interactions without anyone realizing it’s anything other than a normal phone call.
You can read more about virtual numbers here.

More specifically with Vonage, the process is relatively straightforward.
You can get started with the Vonage Voice API to purchase a number and configure it to point to a webhook of your choice — in this case, the webhook that will handle the call.

Once the host dials the number, the call will automatically be routed to our webhook.
From there, the real fun begins.

Step 2: Our Inside Man

When the host dials the number, someone has to pick up the phone, right?
But it’s not just anyone on the other end of the line.
No, this is where we introduce our inside man: Adam.
He’s a very knowledgeable 40-year-old friend, living in London, ready to help with the toughest questions.

But here’s the twist — Adam doesn’t actually exist.
He’s completely synthetic, brought to life by Text-to-Speech (TTS) feature.
When the host calls, Adam’s voice is generated in real-time, and it’s so smooth and convincing that no one would ever suspect they're not talking to a real person.

He has the full package: a relaxed, natural-sounding voice and a proper London accent, making him the perfect accomplice.

// Our webhook
[HttpPost("answer")]
public IActionResult Answer()
{
    // Creating a Talk action with Adam's greeting message
    var talkAction = VoiceAdapter.MakeAdamTalk(GreetingsMessage);
    ...
    // Return a call control object to define the call flow 
    return this.Ok(new Ncco(talkAction, ...));
}

public static TalkAction MakeAdamTalk(string text) =>
    new TalkAction
    {
        Text = text,
        Language = "en-GB",
        Style = 6, 
        Premium = true, // Provides a more natural voice    
    };

private const string GreetingsMessage = "Adam here. What can I do for you?";

As shown in the code snippet, we return a Call Control Object (NCCO) with a Talk action to make Adam speak.
When the call comes through, he will greet the host with a message, ensuring the conversation feels real from the very first word.

Step 3: Text transcription

We've been welcomed by our inside man; it's time to share our final question with him.
The next step in our heist is critical: converting my spoken question into text.
For this, we'll use the Speech-to-Text functionality of Vonage Voice API.

In our webhook, after Adam's greeting, we need to add a Speech input action to capture my question.

[HttpPost("answer")]
public IActionResult Answer()
{
    var talkAction = VoiceAdapter.MakeAdamTalk(GreetingsMessage);
    var inputAction = new MultiInputAction
    {
        Type = [NccoInputType.Speech],
        // Url where the transcription will be sent
        EventUrl = apiUrl + "/Webhooks/asr"],
        Speech = new SpeechSettings
        {
            Language = "en-GB",
            MaxDuration = 20,
            EndOnSilence = 2,
        },
    };
    return this.Ok(new Ncco(talkAction, inputAction));
}

// Webhook that will receive the text transcription
[HttpPost("asr")]
public async Task<IActionResult> Speech(MultiInput speechResponse) 
{
    ...
}

Our Call Control Object now contains two actions that will execute in sequence: Adam will greet the host, and then the system will listen for my question.
Once the system detects that my speech has ended, either by a period of silence or reaching the maximum duration, the transcription will be sent to the webhook we’ve set up.

Here's the transcription of my question:

Hey Adam! Look, I'm currently in the game "Who wants to be a millionaire" with Jeremy Clarkson, and I'm calling you as part of my last joker "Call a friend".
I need your help with the final question. Here it is: "During the Cold War, the US government built a bunker to house Congress under what golf resort?"
A: The Breakers  B: The Greenbrier C: Pinehurst D: The Broadmoor

This step is absolutely essential. Text is data — and in this heist, data is everything. It can be manipulated, analyzed, and, most importantly, passed along to the next phase of our plan.

Step 4: The Oracle

Now that we have the text transcription of the question, it’s time to consult our all-knowing entity: GPT4.
In this heist, it is our oracle — the one who holds all the answers.

Once the transcription reaches our webhook, we send the text, along with a custom prompt, to GPT4.
This prompt ensures that the AI delivers the accurate response we need to win, as Adam.

Context: 
We're in the game "Who wants to be a millionaire", and I'm calling you as part of my last joker "Call a friend".
You are Adam, a 40 year old male using en-UK language. 
You answer must look like you genuinely picked up the phone to give me an answer, and pretend to think about the answer.
You answer will be transcribed through text-to-speech so avoid anything a person wouldn't say. 
No need for greetings, and wish me luch for the game at the end of your reply.

[HttpPost("asr")]
public async Task<IActionResult> Speech(MultiInput speechResponse) =>
    await FetchQuestion(speechResponse.Speech.SpeechResults)
        .MapAsync(aiAdapter.AskAsync)
        .Map(VoiceAdapter.MakeAdamTalk)
        .Map(this.Ok)
        .IfNone(this.Ok(VoiceAdapter.MakeAdamTalk(FailedToUnderstandQuestion)));

private static Maybe<string> FetchQuestion(SpeechRecognitionResult[] results) =>
    results.Length != 0 ? results.First().Text : Maybe<string>.None;

public Task<string> AskAsync(string question)
{
    var client = new ChatGpt(
        configuration["openai-key"] ?? throw new InvalidOperationException("Missing OpenAI key."),
        new ChatGptOptions { Model = "gpt-4-turbo" });
    return client.Ask(configuration["prompt"] + "\n" + question);
}

Thanks to our custom prompt, the Oracle will generate a text response where Adam appears to be thoughtfully considering the answer.
Whether it’s a complex historical fact or a tricky bit of trivia, it will produce the perfect response, ready to be delivered in Adam’s voice.

Here's the response we get from my question:

Hmm... that’s a tough one. Let me think... 
I remember reading about this a while ago. 
I don’t think it’s The Breakers or Pinehurst, those don’t seem right. 
I’m leaning towards The Greenbrier, if I’m not mistaken. 
Yeah, I’m pretty sure it’s B: The Greenbrier. 
That’s the one they used for Congress during the Cold War.

Good luck, hope you nail it!

However, there’s one caveat: these things don’t happen as fast as snapping your fingers.
Let’s consider our scenario:

I deliver my question.
After two seconds of silence, the voice feed is transcribed into text.
The question is sent to GPT, which generates the answer.

We’re looking at potential latency — anywhere from five to ten seconds before we receive the answer.
That’s precious time ticking away, and it could jeopardize my whole plan.

A potential technical solution would be to rely on OpenAI's Realtime API, which was recently released.
But unfortunately, that's a luxury of time I don't have.

Instead, I’ve thought of a clever workaround: small talk.
I know Jeremy Clarkson loves his Ford GT40, and if I casually bring it up, I can get him talking.
His enthusiasm for cars will buy me the few extra seconds I need for the AI to generate the answer.

And once it’s ready?
We send a Talk action with the response as a response to our endpoint, and Adam will confidently deliver the correct answer to the host.

Step 5: The Win

With the answer in hand, I repeat Adam’s response — "B: The Greenbrier" — back to the host, calm as ever.
And just like that, I’ve won!

From the outside, no one suspects a thing. To the audience, it looks like I’ve called a living, breathing human who just happens to know every answer. Little do they know, it was all powered by Vonage APIs, a bit of AI, and — most importantly — creativity.

The perfect heist wasn’t about the tools, but about how I used them.

Wrapping Up

Back to reality, I’m obviously not a millionaire — nor a criminal mastermind.

In truth, my plan has plenty of holes.
For one, I’d have to make sure the host doesn’t ask Adam any follow-up questions, or worse, call the number before the final moment.
The workflow I’ve set up is also pretty rigid: Greeting → Question → Answer.
If we deviate from that, the entire plan falls apart.

And, of course, there’s the small matter of making it to the final question!
I don’t have the knowledge to answer 14 questions on "Who Wants to Be a Millionaire" — maybe one of my multiverse variants does, but certainly not me.

On the technical side, Speech-to-text and Text-to-speech may not be new technologies, but they remain incredibly useful.
However, the real takeaway from this post comes from automation - plugging platforms together like Vonage and OpenAI to create specific workflow.
It's not just about using cutting-edge tools, but how you combine them to create something unique.

As usual, feel free to hit me up on my LinkedIn or join us on the Vonage Developer Slack.
You can also message us on @VonageDev on X.

Happy coding, and I'll catch you later!

Migration Guide for .NET SDK v7.0.0

Guillaume Faas — Tue, 09 Apr 2024 11:26:51 +0000

Hello friends,

Our .NET SDK welcomed a new major release
recently - v7.0.0 is now available!

Being a major release, you might encounter side effects while updating to this version.
This is what this blog post is about: helping you identify and fix those problems.

The overall purpose of this release is to support new features which required a breaking change and start de-cluttering
the codebase.

Prerequisites

This migration guide applies when migrating from v6.X.X - If you're still on v5.X.X, we highly recommend upgrading
to v6.16.0 first, using the
dedicated migration guide.

Migration Steps

Everything Flagged With an 'Obsolete' Annotation Has Been Removed

When upgrading to a newer release, you may have noticed a warning indicating you're using an obsolete method.
Indeed, we flagged these changes with an Obsolete tag.

Please note that there's always a substitute when we decommission something.

Synchronous Methods

So far, many features are available with both synchronous/asynchronous implementation.
All synchronous methods have been removed in v7.0.0.
If you are still required to call a Vonage API in a synchronous context, you will have to call the asynchronous version
with
either .Result or .Wait() to wait for the result synchronously.

// Using v6.X.X
applicationClient.DeleteApplication(applicationId);

// Using v7.X.X and above
await applicationClient.DeleteApplicationAsync(applicationId);
// Or
applicationClient.DeleteApplicationAsync(applicationId).Wait();

SubAccounts Features on 'AccountClient'

SubAccounts features were initially implemented by a contributor on the AccountClient while the product was still in
beta.
With the GA release, all SubAccounts features are available on the SubAccountsClient, which makes previous features
obsolete.

// Using v6.X.X
var subAccount = await vonageClient.AccountClient.RetrieveSubAccountAsync(subAccountKey);
// Using v7.X.X and above
var request = GetSubAccountRequest.Parse(subAccountKey);
var subAccount = await vonageClient.SubAccountClient.GetSubAccountAsync(request);

'CreateApplicaitonAsync' on 'ApplicationClient'

The current method contains a typo.

// Using v6.X.X
var application = await applicationClient.CreateApplicaitonAsync(request);

// Using v7.X.X and above
var application = await applicationClient.CreateApplicationAsync(request);

'CreateCall' on 'VoiceClient'

This method offers three different signatures.
Only the one with a CallCommand parameter will remain to avoid Primitive Obsession and rely on a proper
ValueObject.

// Using v6.X.X
var callResponse = voiceClient.CreateCallAsync(toNumber, fromNumber, ncco);
var callResponse = voiceClient.CreateCallAsync(toEndpoint, fromNumber, ncco);
var callResponse = voiceClient.CreateCallAsync(callCommand);


// Using v7.X.X and above
var callResponse = voiceClient.CreateCallAsync(callCommand);

Constructors on 'Credentials'

Creating a Credentials instance should be done using a factory method or from a Configuration instance.
Constructors will be hidden, and the object will remain immutable.

We highly recommend you use
our extension methods to dynamically
initialize Credentials from your appsettings.json file.

// Using v6.X.X
var credentials = new Credentials()
{
    ApiKey = apiKey,
};
var credentials = new Credentials(apiKey, apiSecret);
var credentials = Credentials.FromApiKeyAndSecret(apiKey, apiSecret);
var credentials = Credentials.FromAppIdAndPrivateKey(apiKey, apiSecret);


// Using v7.X.X and above
var credentials = Credentials.FromApiKeyAndSecret(apiKey, apiSecret);
var credentials = Credentials.FromAppIdAndPrivateKey(apiKey, apiSecret);
var credentials = configuration.BuildCredentials();
// Recommended
var credentials = serviceCollection.GetRequiredService<Credentials>();

Access to Vonage URLs

All URLs have been moved to a nested object (VonageUrls) to simplify the Configuration class and allow
multi-region URLs.

// Using v6.X.X
var url = configuration.NexmoApiUrl;
var url = configuration.RestApiUrl;
var url = configuration.VideoApiUrl;
var url = configuration.EuropeApiUrl;

// Using v7.X.X and above
var url = configuration.VonageUrls.Nexmo;
var url = configuration.VonageUrls.Rest;
var url = configuration.VonageUrls.Video;
var url = configuration.VonageUrls.Get(VonageUrls.Region.EMEA);

Remove 'Input' Webhook Object

This item has been rendered obsolete due to the new multi-input functionality. Please add the Dtmf arguments to your
input action and use the MultiInput object, as recommended in
our documentation.

Remove 'Portuguese" Language in Meetings API

This language has been removed in favor of 'Portuguese-Brazilian'.

// Using v6.X.X
var language = UserInterfaceLanguage.Pt;


// Using v7.X.X and above
var language = UserInterfaceLanguage.PtBr;

Remove 'VoiceName' From 'TalkCommand' and 'TalkAction' in Voice

This parameter has been made obsolete
by the language and style fields.

Add New Timeouts on Voice Webhooks in Application API

Adding new timeouts requested (connection_timeout, socket_timeout) on Voice Webhooks.
Creating a specific structure, different from other webhooks, required to break the Capability inheritance.

Rename Settings Key From 'appSettings' to 'vonage'

In order to make the settings more explicit and reduce the chances of conflict with other libraries, the base key has
been
updated.

Also, "Vonage." has been removed from every key to de-clutter the section. Finally, a few keys have been completely
renamed:

Old Key	New Key
Vonage.Vonage_key	Api.Key
Vonage.Vonage_secret	Api.Secret
Vonage.Vonage.Url.Api.Europe	Url.Api.EMEA
N/A	Url.Api.AMER
N/A	Url.Api.APAC

Using v6.X.X

{
  "appSettings": {
    "Vonage.UserAgent": "...",
    "Vonage.Url.Rest": "...",
    "Vonage.Url.Api": "...",
    "Vonage.Url.Api.Europe": "...",
    "Vonage.Url.Api.Video": "...",
    "Vonage.Vonage_key": "...",
    "Vonage.Vonage_secret": "...",
    "Vonage.Application.Id": "...",
    "Vonage.Application.Key": "...",
    "Vonage.Security_secret": "...",
    "Vonage.Signing_method": "...",
    "Vonage.RequestsPerSecond": "...",
    "Vonage.RequestTimeout": "..."
  }
}

Using v7.X.X and above

{
  "vonage": {
    "UserAgent": "...",
    "Url.Rest": "...",
    "Url.Api": "...",
    "Url.Api.EMEA": "...",
    "Url.Api.AMER": "...", 
    "Url.Api.APAC": "...",
    "Url.Api.Video": "...",
    "Api.Key": "...",
    "Api.Secret": "...",
    "Application.Id": "...",
    "Application.Key": "...",
    "Security_secret": "...",
    "Signing_method": "...",
    "RequestsPerSecond": "...",
    "RequestTimeout": "..."
  }
}

Make StartTime Nullable on Answered Webhook

As defined in the specs, the StartTime
is now nullable.

Remove 'EventUrl' and 'EventMethod' From 'ConversationAction'

As defined in the specs,
the Conversation action doesn't have an EventUrl or an EventMethod.

Make 'From' Mandatory in VerifyV2 WhatsApp Workflow

The From property used to be optional - it is now mandatory.

// Using v6.X.X
var workflow =  WhatsAppWorkflow.Parse(ValidToNumber);
var workflow =  WhatsAppWorkflow.Parse(ValidToNumber, ValidFromNumber);

// Using v7.X.X and above
var workflow =  WhatsAppWorkflow.Parse(ValidToNumber, ValidFromNumber);

Conclusion

The migration guide is also available on
our GitHub repository.

Don't hesitate to report any issue on GitHub or join us on
the Vonage Developer Slack, and we will get back to you.
You can also follow us on X to stay up-to-date with our latest news.

Happy coding, and see you soon!

The Monad Invasion - Part 2: Monads in Action!

Guillaume Faas — Tue, 27 Feb 2024 09:18:41 +0000

Hello friends,

In our previous post "The Monad Invasion - Part 1: What's a Monad?", we chose a pragmatic approach to introduce Monads, incrementally building our own.
By now, you should be familiar with the concept, understanding how to transform its value with either .Map() or .Bind() and how to extract it with .Match().

In this article, we want to demonstrate practical applications for various Monads, and we'll use an example from the Vonage .NET SDK. But first, let's have a quick recap.

Quick Recap

We previously crafted the Optional Monad, which can exist in one of two states: Some, indicating the presence of a value, or None, indicating the absence of value.

private static SchrodingerBox<int> Half(int value) =>
    value % 2 == 0 
        ? SchrodingerBox<int>.Some(value / 2)
        : SchrodingerBox<int>.None();

private static int Increment(int value) => value + 1;

SchrodingerBox<int>.Some(0)
    .Map(Increment) // Some(0) becomes Some(1)
    .Map(Increment) // Some(1) becomes Some(2)
    .Bind(Half) // Some(2) becomes Some(1)
    .Map(Increment) // Some(1) becomes Some(2)
    .Match(some => $"The value is some {some}!", () => "The value is none")
    .Should()
    .Be("The value is some 2!");

SchrodingerBox<int>.Some(0)
    .Map(Increment) // Some(0) becomes Some(1)
    .Bind(Half) // Some(1) becomes None - the Monad's state has changed
    .Map(Increment) // None remains None
    .Match(some => $"The value is some {some}!", () => "The value is none")
    .Should()
    .Be("The value is none");

Our box provides three essential functionalities:

.Map(operation) empowers you to generate a new value based on an existing one and wrap the new value into a new box. The operation is only executed if the box is in Some state.
.Bind(operation) is a transformation mechanism similar to .Map(). However, it differs by enabling the alteration of the box's state as the function returns a box instead of a value. Like .Map(), the operation is only executed if the box is in Some state.
.Match(some, none) evaluates the box's state and invokes the corresponding function.

The box allows you to manipulate a value without knowing its current state.

In essence, the state becomes irrelevant as your sequence of operations remains the same. As you probably observed, the code has no branching constructs (if/else).

When Is It Worth Using A Monad?

Given their nature of opposing states, Monads prove to be irrelevant in scenarios with operations yielding a singular outcome. For Monads to be applicable, the operation must present at least two distinct possible results.

So far, we have worked with the Optional monad, but many more exist. To share examples of other monads, let's explore which monads the library Language-Ext offers and find out their useful contexts.

Option

Given our prior implementation, you should be pretty familiar with this one by now. It shines when wrapping an optional value or a value that may (or may not) exist.

private async Task<Option<User>> FindUser(Guid id)
{
    var user = await this.repository.Users.FirstOrDefaultAsync(user => user.Id == id);
    return user ?? Option<User>.None;
}

Try

The Try<T> Monad represents an operation that may encounter failure:

Success indicates the operation succeeded, yielding the result <T>.
Exception indicates the operation resulted in an exception. The Monad will return the exception instead of throwing it.

private static Try<decimal> Divide(decimal value, decimal divisor) => 
        Try(() => value / divisor);

In the above example, we can encapsulate a potentially "risky" operation within a Try.

Invoking Divide(50,2) will return a Success state with the value 25.
Invoking Divide(50,0) will return a Exception state with a DivideByZeroException.

Either

The Either<L, R> Monad represents an operation that can return two distinct types, defined by Leftor Right. This Monad is extremely versatile, given <L, R> are both generics types. Nevertheless, the Left state usually represents errors or exceptional cases.

private static Either<Error, decimal> Divide(decimal value, decimal divisor) =>
    divisor == 0
        ? new Error("Cannot divide by 0.")
        : value / divisor;

private record Error(string Message);

In line with the previous scenario:

Invoking Divide(50,2) will return a Right state with the value 25.
Invoking Divide(50,0) will return a Left state with an Error record explaining why it wasn't processed.

Validation

The Validation<Fail, Success> Monad represents a validation operation that may fail for multiple reasons.

private record User(string Firstname, string Lastname, MailAddress Email);

private static Validation<string, User> CreateUser(string firstname, string lastname, string email)
{
    var errors = new Seq<string>();
    if (string.IsNullOrWhiteSpace(firstname))
    {
        errors = errors.Add("Firstname cannot be empty.");
    }

    if (string.IsNullOrWhiteSpace(lastname))
    {
        errors = errors.Add("Lastname cannot be empty.");
    }

    if (!MailAddress.TryCreate(email, out var address))
    {
        errors = errors.Add("Invalid mail address.");
    }

    return errors.Any()
        ? Validation<string, User>.Fail(errors)
        : Validation<string, User>.Success(new User(firstname, lastname, address));
}

In this example:

Invoking CreateUser("Jane", "Doe", "jane.doe@email.com") will return a Success with a valid User instance.
Invoking CreateUser(null, null, null) (or any invalid value) will return a Failure with the collection of encountered errors.

Referential Transparency

These Monads all have something in common: they're all transparent about an operation's potential outcomes, whether it can fail, throw an exception or return various values.
As such, the method's return type must communicate the result of those outcomes instead of an invisible and unpredictable mechanism (an exception).

Here, we're talking about Referential Transparency. It applies when we can always replace an expression by its value.

// Referentially Opaque examples
public User FindUser(Guid id) => this.users.First(user => user.Id == id);
public int Divide(int a, int b) => a/b;
public void SetName(string name)
{
    ArgumentNullException.ThrowIfNull(name);
    this.Name = name;
}

// Referentially Transparent examples
public Maybe<User> FindUser(Guid id) => this.users.FirstOrDefault(user => user.Id == id) ?? Maybe<User>.None;
public Try<decimal> Divide(decimal value, decimal divisor) => Try(() => value / divisor);
public int Add(int a, int b) => a+b;
public Either<Error, Unit> SetName(string name)
{
    if (name is null)
    {
        return new Error("Name cannot be null);
    }

    this.Name = name;
    return Unit.Value;
}

You probably noticed that .SetName() returns a Either<Error, Unit>. You may have come across Unit in libraries like MediatR or Language-Ext. It's a simple construct representing a type with only one possible value. We use it as a placeholder for operations that do not return a value but may return another state. In our example, .SetName() is a Command that does not return a value but may fail. Therefore, the monad Either<Error, Unit> carries two possible states: Right (without value) or Left (with an Error).

Although Referential Transparency doesn't inherently solve specific problems, it significantly improves code predictability and readability. Making everything explicit in the method's signature minimizes the potential for the unexpected.
Uncle Bob emphasizes in his book "Clean Code: A Handbook of Agile Software Craftsmanship" that "the ratio of time spent reading versus writing is well over 10 to 1. We are constantly reading old code as part of the effort to write new code... Therefore, making it easy to read makes it easy to write". This highlights the importance of code clarity and transparency in facilitating both comprehension and efficient development.

This was my primary motivation behind the making of "Throw exceptions... out of your codebase".

Vonage SDK Example

So far, we focused on relatively simple examples. However, what about using Monads in more complex flows? Let's look at an example from our .NET SDK involving our two-factor authentication API Verify.

Custom Monads

Previously, we built an Optional and showed an existing set based on Language-Ext, but various libraries also offer Monad implementations. In the case of our SDK, we deliberately avoided relying on external libraries like Language-Ext. Indeed, Monads are a part of the SDK's public API, and relying on an external library would introduce a dependency over which we would have limited control.

Our approach involved creating our custom Monad implementations tailored to the specific needs of the SDK. This strategy allowed us to maintain control over the design and functionality of these Monads while avoiding dependencies on external libraries.

Furthermore, our goal was to present a lightweight and user-friendly version of specific Monads, ensuring easier adoption from developers working with our SDK.

Our SDK implements the following Monads:

Result<T> Monad, similar to an Either<IFailure, T> with a more concise syntax - C# being verbose regarding generics.
Maybe<T> Monad, similar to an Option<T>.

Example With Two-Factor Authentication

2FA is a two-step workflow. We first initiate an authentication process, resulting in the customer receiving a validation code based on the specified workflow (SMS, WhatsApp, Email, Voice, SilentAuth). Once the code is received, we send it to our API for verification.

var myPhoneNumber = ...
var result = await StartVerificationRequest.Build()
    .WithBrand("Monads Inc.")
    .WithWorkflow(SmsWorkflow.Parse(myPhoneNumber))
    .Create() // Build the authentication request
    .BindAsync(request => verifyClient.StartVerificationAsync(request)) // Process the authentication request
    .BindAsync(VerifyCodeAsync) // Start the second step if it's a success
    .Match(AuthenticationSuccessful, AuthenticationFailed);

private async Task<Result<Unit>> VerifyCodeAsync(StartVerificationResponse response)
{
    var myCode = ... // Receive verification code based on the specified workflow
    return await response
        .BuildVerificationRequest(myCode) // Build the verification request
        .BindAsync(request => verifyClient.VerifyCodeAsync(request)); // Process the verification request
}

Everything we've covered so far remains applicable as our workflow contains fetching user input, parsing operations, and making API calls.

Once again, we successfully removed branching from our code, maintaining a consistent flow regardless of the Monad's state. It's worth noting our process can fail at five distinct locations:

When building the authentication request
When processing the authentication request
When building the verification request
When processing the verification request
When calling the second step VerifyCodeAsync

If you remember, in our previous post, we talked about keeping a Monad active as long as possible. In this scenario, the value remains in our Result<T> from the beginning until the end of the flow, allowing us to chain the entire sequence of operations.

To Be Or Not To Be... Pure?

In our previous example, you may have noticed that our Monad did not remain pure during the workflow. Indeed, we provided unpure functions to .Bind(), like request => verifyClient.StartVerificationAsync(request) or request => verifyClient.VerifyCodeAsync(request). Is it problematic, though?

By definition, a pure function does not refer to any global state and should not produce any side effect. It consistently produces an output that solely depends on the input, ensuring the same output for a specific input - in other words, high predictability.

While the concept of "pure monad" might be discussed, it's essential to understand that using monads does not necessarily require the Monad itself to be pure. Instead, monads are often used to structure computations involving impure operations while adhering to functional programming principles. Indeed, interactions with external resources, such as databases or APIs, introduce side effects.

Impure Monads... With Exceptions?

The default behaviour ensures that our monads won't throw any exception, even if the parameter function within them does. This design choice helps us maintain referential transparency.

public Result<TB> Bind<TB>(Func<T, Result<TB>> bind)
{
    try
    {
        return this.IsFailure
            ? Result<TB>.FromFailure(this.failure)
            : bind(this.success);
    }
    catch (Exception exception)
    {
        return SystemFailure.FromException(exception).ToResult<TB>();
    }
}

public Result<TB> Map<TB>(Func<T, TB> map)
{
    try
    {
        return this.IsFailure
            ? Result<TB>.FromFailure(this.failure)
            : Result<TB>.FromSuccess(map(this.success));
    }
    catch (Exception exception)
    {
        return SystemFailure.FromException(exception).ToResult<TB>();
    }
}

However, what if you prefer to stick with exceptions instead of extracting the value with .Match()? We wanted our monads to be versatile, so we introduced a GetSuccessUnsafe() functionality. This function will throw an exception if the monad is in the Failure state.

public T GetSuccessUnsafe() => this.IfFailure(value => throw value.ToException());

The type and data of the exception depend on the underlying failure value:

ResultFailure will throw a VonageException
ParsingFailure will throw a VonageException
HttpFailure will throw a VonageHttpRequestException
AuthenticationFailure will throw a VonageAuthenticationException
And so on...

Here's how you can incorporate exceptions into your monadic flow using the same example as before:

try
{
    await StartVerificationRequest.Build()
        .WithBrand("Monads Inc.")
        .WithWorkflow(SmsWorkflow.Parse(myPhoneNumber))
        .Create()
        .BindAsync(request => verifyClient.StartVerificationAsync(request))
        .BindAsync(VerifyCodeAsync)
        .GetSuccessUnsafe(); // Will throw exception if in the Failure state
    AuthenticationSuccessful();
}
catch (Exception exception)
{
    AuthenticationFailed(exception);
}

Whether you choose the standard monadic approach or opt for exceptions, our goal is to accommodate different styles of error handling, ensuring that our monads align with your coding preferences.

Wrapping Up

We've concluded the second post of our "The Monads Invasion" series. This article aimed to demonstrate various sets of Monads, including our custom implementations, and illustrate their use in extended workflows.

At this point, you should realize Monads offers an alternative approach to error handling in your workflows - and that's no coincidence. Indeed, our upcoming post will bring more light on the methodology behind the chaining of operations. Stay tuned for more!

If you have any questions or want to chat, feel free to hit me up on my LinkedIn or join us on the Vonage Developer Slack.

Happy coding, and I'll catch you later!

The Monad Invasion - Part 1: What's a Monad?

Guillaume Faas — Tue, 27 Feb 2024 09:17:29 +0000

Hey there,

During a presentation, two things can potentially make developers run away. The first is a speaker delivering a dreadfully dull presentation; the second is the mere mention of the word "Monad".

Monads have a reputation for scaring people off. Digging into Category Theory introduces a web of complex terminologies, like "Monads", making it more tricky to provide a simple and straightforward explanation.

This is the first post in a series that aims to demystify Monads and help you benefit from them, using real-life examples from our .NET SDK. Watch my related talk "Throw exceptions... out of your codebase" which was more about Monads than it was about exceptions, even if the title says otherwise.

So... What's a Monad?

I'm sorry to disappoint, but I won't dive into the theory aspect. I could say that a Monad is a Monoid from the category of endofunctors, but where do you go from there?

To put it simply, think of a functor as a box you can map a function over, which means you can apply a function to what's inside the box without mutating it. Now, a Monad is just a step up from a functor. It's like a super-powered box that not only allows you to map functions but also offers extra capabilities to control the sequence of operations.

Do you get it? Not yet? That's alright! We'll switch to a more pragmatic scenario for real-world examples as we delve deeper.

Schrodinger's Cat

Yes, this example comes from Quantum Mechanics, but there's no need to freak out, as it's relatively straightforward.

Imagine a scenario with a box and a cat. However, this isn't your typical box because it also contains a device that can release deadly poison at any moment, and you won't know when it happens.

Erwin Schrödinger's perspective is that the moment you place the cat inside the box and close it, you can't determine whether the cat is alive or dead until you open the box again. The cat isn't simultaneously dead and alive; it is either dead or alive, but you have to consider both possibilities until you can observe the actual state.

This is a way to illustrate the concept of quantum superposition where you must entertain the idea that a situation exists in multiple states until you can make an observation.

You may wonder where I'm going with all that; well, let's look at some code.

A Box With a Cat

Disclaimer: no cats were harmed during the creation of these code snippets.

Here's a relatively straightforward implementation of our box:

internal class SchrodingerBox
{
    private readonly Cat? cat;

    // Creates a box with an alive cat inside
    private SchrodingerBox(Cat cat) => this.cat = cat;

    // Creates a box with a dead cat
    private SchrodingerBox()
    {
    }

    // Look inside the box
    public Cat? OpenBox() => this.cat;

    // Shakes the box. The cat doesn't like it. Meow.
    public SchrodingerBox Shake()
    {
        this.cat?.Meow();
        return this;
    }

    // Shakes the box (too hard), then returns a new box with a dead cat
    public SchrodingerBox ShakeTooHard()
    {
        this.Shake();
        return new SchrodingerBox();
    }

    // Creates a box with a cat
    public static SchrodingerBox WithAliveCat(Cat cat) => new(cat);
}

internal readonly struct Cat
{
    private readonly Action<string> log;

    public Cat(Action<string> log) => this.log = log;

    public void Meow() => this.log("Meow");
}

I want to emphasize a few key points here:

When interacting with the public API, the only way to create a box with a living cat is by using the static factory method .WithAliveCat(Cat).
Cat is a struct and, therefore, cannot be null. In this context, when the cat field is declared nullable, we understand that an instance of Cat denotes a living cat, while null indicates that the cat has passed away.
There is no direct way to inspect the cat inside the box, as no properties expose the cat's status. To determine whether the cat is alive or deceased, you must open the box using the .OpenBox() method.

The box provides three distinct behaviours:

Shaking the box: If the cat is alive, it might not appreciate the shaking and "meows". Using the null-propagation operator ensures that we only call .Meow() if the cat is alive. Nothing occurs if the cat is no longer among the living.
Shaking the box too hard: Similar to the previous behaviour, the call will "meow" if alive. However, poison is released in this case, and the cat meets an unfortunate end.
Opening the box: By opening the box, we receive the cat, either alive (an instance) or deceased (null).

To witness the box in action, let's look at some code:

private readonly ITestOutputHelper helper;
private Cat GetAliveCat() => new(value => this.helper.WriteLine(value));

// "Meow" is logged three times in the console.
SchrodingerBox.WithAliveCat(this.GetAliveCat())
    .Shake()
    .Shake()
    .Shake();

// "Meow" is logged twice in the console, given we killed the cat on the second call.
SchrodingerBox.WithAliveCat(this.GetAliveCat())
    .Shake()
    .ShakeTooHard()
    .Shake();

// OpenBox() returns an instance when the cat is alive.
SchrodingerBox.WithAliveCat(this.GetAliveCat())
    .Shake()
    .OpenBox()
    .Should()
    .Be(this.GetAliveCat());

// OpenBox() returns null when the cat is dead.
SchrodingerBox.WithAliveCat(this.GetAliveCat())
    .ShakeTooHard()
    .OpenBox()
    .Should()
    .BeNull();

You'll notice that we can work with the box without needing to check the cat's state; even shaking the box when the cat is deceased doesn't lead to any consequences.

Now, that's all well and good, but in its present form, this example doesn't offer much utility. Integrating this box into your codebase won't address any real problems.

However, that doesn't mean we should discard it entirely.
Currently, our box holds a cat, but Cat is just a specific structure. With the power of generics, we could swap it out for any type!

A Box of T

When it comes to replacing Cat with a generic type, there's an important aspect to ponder: Shaking the box doesn't make sense anymore. What would be the purpose of such an action?

Going ahead, we will allow any value in our box - but it has to be universally helpful. We need to offer functionalities like mutating a value or transforming the value into another type.

Here's where .Map<TResult>(Func<T, TResult>) comes into play!

internal class SchrodingerBox<T> where T : struct
{
    private bool IsSome { get; }
    private readonly T value;

    // Constructor for Some
    private SchrodingerBox(T value)
    {
        this.value = value;
        this.IsSome = true;
    }

    // Constructor for None
    private SchrodingerBox() => this.IsSome = false;

    // Applies the function on the value IF our box contains a value
    public SchrodingerBox<TResult> Map<TResult>(Func<T, TResult> map) =>
        this.IsSome
            ? Some(map(this.value))
            : SchrodingerBox<TResult>.None();

    // Creates a box without a value
    public static SchrodingerBox<T> None() => new();

    public T? OpenBox() => this.IsSome ? this.value : null;

    // Creates a box with a value
    public static SchrodingerBox<TResult> Some<TResult>(TResult value) where TResult : struct => new(value);
}

The Map operation represents a significant advancement, empowering us to "alter" the underlying value. Well, "alter" might not be the right term, as we're not directly modifying the value. Instead, we're using it to generate a new value placed into another container.

You can think of this operation as being similar to .Select(Func<TSource, TResult>) in LinQ.

// We start with 3 and perform three increments. The result is then 6.
SchrodingerBox<int>.Some(3)   
    .Map(value => value + 1)
    .Map(value => value + 1)
    .Map(value => value + 1)
    .OpenBox()
    .Should()
    .Be(6);

// The box is empty, and despite three increments, the result remains null.
SchrodingerBox<int>.None()
    .Map(value => value + 1)
    .Map(value => value + 1)
    .Map(value => value + 1)
    .OpenBox()
    .Should()
    .BeNull();

This concept aligns with the previous .Shake() method:

When the box lacks a value, no action is taken.

But when the box contains a value, it applies the function to that value and delivers the result in a new box.

Source: Aditya Bhargava's blog - probably the best drawings I've seen to illustrate this mechanism

Even though we've only covered a simple transformation operation, we managed to turn our box into a Functor! Remember our earlier explanation?

"Think of a functor as a box you can map a function over, which means you can apply a function to what's inside the box without mutating the box itself."

So, what's missing for our box to evolve into a Monad?

Monadic Bind

You might have noticed that when using .Map<TResult>(Func<T, TResult>), the internal state of our box remains unchanged. Whether in a Some or None state, mapping it will preserve that state, and it's impossible to alter it.

However, this is where the Bind mechanism takes the spotlight! Unlike Map, which takes a function returning a value, the Bind method anticipates a function that returns a new box, expecting the following parameter Func<T, SchrodingerBox<TResult>>.

Let's see how it stacks up against Map:

public SchrodingerBox<TResult> Map<TResult>(Func<T, TResult> map) where TResult : struct =>
    this.IsSome
        // The outcome of the "map" operation is a result,
        // which means we need to wrap this value within a box
        ? Some(map(this.value))
        : SchrodingerBox<TResult>.None();

public SchrodingerBox<TResult> Bind<TResult>(Func<T, SchrodingerBox<TResult>> bind) where TResult : struct =>
    this.IsSome
        // The outcome of the "bind" operation is already a box,
        // so, we can return it
        ? bind(this.value)
        : SchrodingerBox<TResult>.None();

With Bind, we can implement behaviours that modify the box's state based on specific business logic. You might think: "The initial box containing the cat was already doing that, transitioning from alive to deceased" - and you're correct.

However, there's a significant distinction: previously, the box held the responsibility for that change as it hosted the logic (.ShakeTooHard()). Now, the responsibility lies with the function.
We successfully delegated this to the caller, expanding the possibilities of our box.

In the upcoming example, we introduce a new method, .Increment(int), which increments the value as long as it remains below three. However, if the value equals or surpasses three, it returns an empty box.

private static SchrodingerBox<int> Increment(int value) =>
    value < 3 ? SchrodingerBox<int>.Some(value + 1) : SchrodingerBox<int>.None();

//  We successfully incremented our value to three
SchrodingerBox<int>.Some(0)
    .Bind(Increment)
    .Bind(Increment)
    .Bind(Increment)
    .OpenBox()
    .Should()
    .Be(3);

// On the last call, our "Increment" method returns an empty box
// This signifies our box transitioned from a "Some" state to a "None" state.
// The box didn't not produce the change; the ".Increment(int)" function did.
SchrodingerBox<int>.Some(0)
    .Bind(Increment)
    .Bind(Increment)
    .Bind(Increment)
    .Bind(Increment)
    .OpenBox()
    .Should()
    .Be(null);

Our box is finally a Monad! It now includes both Map and Bind functionalities, enabling us to manipulate a wrapped value without knowing its initial state.

However, there's still one more aspect we need to tackle.

Opening The Box

Our Monad, often known as Optional (Option or Maybe, depending on your language preference), can be in one of two states: it can represent the presence of a value (Some) or the absence of a value (None).

Currently, when we open the box, it may return null if there's no value inside. However, this doesn't align with the intent of our Monad because the absence of value is different from a null value.

This raises an intriguing question: How do you represent the absence of value? Well, you don't - instead, you provide a fallback behaviour.

And this is where .Match<TResponse>(Func<T, TResponse> some, Func<TResponse> none) comes into play!

// Applies a function depending on the state of the box to return a TResponse
public TResponse Match<TResponse>(Func<T, TResponse> some, Func<TResponse> none) =>
    this.IsSome ? some(this.value) : none();

.Match(some, none) will assess the Monad's state and invoke the corresponding function.

If the state is Some, it will call some with the inner value to generate a result.
If the state is None, it will invoke none, relying on a fallback mechanism to generate a result.

Now, let's apply Match in place of Openboxusing the previous example:

// When the stae is Some(3)
// Match will employ the some function
// and return "The value is some 3!"
SchrodingerBox<int>.Some(0)
    .Bind(Increment)
    .Bind(Increment)
    .Bind(Increment)
    .Match(some => $"The value is some {some}!", () => "The value is none")
    .Should()
    .Be("The value is some 3!");

// When the state is None (because Bind returned an empty box in the last call),
// Match will employ the none function
// and return "The value is none"
SchrodingerBox<int>.Some(0)
    .Bind(Increment)
    .Bind(Increment)
    .Bind(Increment)
    .Bind(Increment)
    .Match(some => $"The value is some {some}!", () => "The value is none")
    .Should()
    .Be("The value is none");

Initially, our box held an int. When extracting the value from the box, we focused on the "big picture" and generated a message for the end-user.
Another approach could have involved providing a default int value when the state was None, assuming it would be meaningful.

The cherry on the cake: we've successfully got rid of nullability - this is always a win!

It's worth noting that the entire workflow remains consistent, whether a value is present or not. This isn't a coincidence, and I'll explore the underlying reasons later in the series.

However, this shift requires a broader consideration of the value's purpose - what are the implications of the absence of a value when nullability is no longer an option?

What does it mean in the context of an end-to-end operation?

When Should We Open The Box?

This is often the point where individuals face challenges - at least, that was the case for me - because we tend to make the rookie mistake of extracting the value prematurely.

Keeping the value inside the box makes sense as long as both states result in distinct side effects.

For instance, your monad will have a relatively brief lifespan if you can generate a value quite early, as demonstrated with the .Match(some, none) example. On the contrary, if your entire flow depends on the presence of a value, like updating a user, you will have to stick with it until the very end.

I recommend keeping your Monad active for as long as possible, extracting the value at the latest moment.

It's All About States

Monads revolve around the concept of managing and manipulating states.

Obviously, our Monad is just one example among many others, each designed to handle various states.
Here are a few others, along with the different states they handle:

Result (Success|Failure)
Either (Left|Right)
Validation (Success|ValidationError)
etc.

For this presentation, we developed our custom box, but it's important to note that you don't have to do the same!

There are numerous libraries available that offer ready-made Monads.
Here are a few recommendations:

Language-Ext is my personal favourite, but it can be a bit overwhelming for beginners due to its extensive feature set
FluentResults
CSharpFunctionalExtensions
OneOf

Wrapping up

I hope you had fun reading this article, and I tried to make Monads less scary for you. They can be tricky when you first dive into them, but trust me, it's worth it. They changed how I approach software, and I hope they'll do the same for you.

Remember what Douglas Crockford once said: "[...] Monads are also cursed, and the curse of the Monad is that [...] once you understand, you lose the ability to explain it to anybody"

As I mentioned earlier, this blog post was just a warm-up.
The topic is so vast that it won't all fit into one post, and we're about to explore some cool new stuff in the next one.
So, stay tuned for that.

If you have any questions or just want to chat, feel free to hit me up on my LinkedIn or join us on the Vonage Developer Slack.

Happy coding, and catch you later!

Implicit Configuration in .NET

Guillaume Faas — Tue, 27 Feb 2024 09:15:17 +0000

Hello friends,

In our last post, we demonstrated the process of registering Vonage clients within the .NET IoC container. This was a valuable step in simplifying interactions with our SDK.

Now, let's take a moment to ponder: What if we were to take this a step further?

Where Did We Leave Off?

Just a refresher: here's how we used to register those clients:

// Initialize credentials
Credentials credentials = ...
// Register our clients with a 'Transient' lifetime...
builder.Services.AddVonageClientTransient(credentials);
// Or a 'Scoped' lifetime
builder.Services.AddVonageClientScoped(credentials);

You had to initialize a Credentials instance, typically from an ApiKey/ApiSecret pair or an ApplicationId/PrivateKey pair.
These values often came from your configuration file or were plucked from our Configuration instance.

You see where I'm going, don't you?

Implicit Configuration Loading

No more fussing about that Credentials instance anymore.
We've taken it further and tweaked the method to accept an IConfiguration instance immediately.

// Register our clients with a 'Transient' lifetime...
builder.Services.AddVonageClientTransient(builder.Configuration);
// Or a 'Scoped' lifetime
builder.Services.AddVonageClientScoped(builder.Configuration);

Now, we handle all the heavy lifting as we'll grab all the necessary data straight from your configuration file.

Less manual work for you!

Extending With Environment-Specific Configuration

Until v6.9.0, we could only load configuration data from settings.json or appsettings.json.
It could be problematic if you wanted to use environment-specific values, for example, with a staging environment deployment.

You might have noticed that we are discussing loading data based on your local configuration.
What's the scoop there?

We're fetching all those crucial configuration values from sources you've loaded into your configuration builder.
For example, we can retrieve values from appsettings.{environment}.json, the default naming convention on a new .NET application.

Signing Off

Stay tuned for more features and quality-of-life improvements.

As always, we value your feedback!
So, feel free to hit up our GitHub repository to report issues, suggest improvements, or even contribute your pull requests. If you have questions, join us on the Vonage Developer Slack, and we will get back to you.

Happy coding, and see you soon!

Simplifying Dependency Injection in .NET

Guillaume Faas — Tue, 27 Feb 2024 09:13:31 +0000

Hey there, fellow developers!

We've got some exciting news to share about our .NET SDK!
We've just rolled out a fantastic new feature that will make your lives much easier.
You know how initializing the client used to be a bit of a pain, right?
Well, fear no more!

Since version v6.4.0, we integrated a solution that takes the hassle out of the process.
Now, you can use a cool extension method to register our client in the ASP.NET default Dependency Injection container.
Intrigued? Keep reading to find out more!

Standard Client Initialization

Imagine we'd like to use Meetings API features.
We would have to initialize an instance of the main client (VonageClient) to fetch the specific MeetingsClient.

Credentials credentials = ...
VonageClient vonageClient = new VonageClient(credentials);
IMeetingsClient meetingsClient = vonageClient.MeetingsClient;

It's indeed quite straightforward as the client only expects a Credentials object to be created.
So far, nothing new; you've been there.

Even if it's relatively easy, it has a few downsides:

You must create a VonageClient while you only need a IMeetingsClient
You create unnecessary coupling to the VonageClient implementation, which makes your code harder to test

And there's more to it: if you want to inject any of our clients, you must register all of them in your container. Manually.

There's definitely room for some improvement.

Enters our DI Registration!

Okay, let's get to the good stuff!
With our new extension method, you no longer have to do that.

Check out how easy it is to use:

using Microsoft.Extensions.DependencyInjection;
using Vonage;
using Vonage.Extensions;

// ...

public void ConfigureServices(IServiceCollection services)
{
    //...

    // Initialize credentials
    Credentials credentials = ...
    // Register our clients with a 'Transient' lifetime...
    services.AddVonageClientTransient(credentials);
    // Or a 'Scoped' lifetime
    services.AddVonageClientScoped(credentials);

    // ...
}

That's it!

It relies on ASP.NET DI Container from Microsoft.Extensions.DependencyInjection, which means it's compatible as long as you're handling an IServiceCollection instance.
This is provided by default on ASP.NET WebApi and WebApp, but you can also integrate it with ConsoleApps and Services.

You can choose between two ServiceLifetime options:

Transient: objects are always different
Scoped: objects are the same for a given request but differ across each new request

By calling services.AddVonageClient{lifetime}, you're telling the DI container set up the VonageClient for you.

You can now enjoy dependency resolution with the main client or any subclient:

[ApiController]
[Route("[controller]")]
public class VonageController : ControllerBase
{
    ...

    public VonageController(VonageClient client) => this.client = client;
}

[ApiController]
[Route("[controller]")]
public class VonageController : ControllerBase
{
    ...

    public VonageController(IMeetingsClient client) => this.client = client;
}

Wrapping Up

We're proud to make your developer journey smoother with new quality-of-life improvements.
It's never been easier to integrate our SDK into your .NET applications.

And guess what?
Your feedback and contributions matter to us!

So, feel free to hit up our GitHub repository to report issues, suggest improvements, or even contribute your pull requests.
If you have questions, join us on the Vonage Developer Slack, and we will get back to you.

Happy coding, friends!