DEV Community: Steve Lorello

Querying Redis with GraphQL using Redis OM .NET

Steve Lorello — Thu, 14 Dec 2023 01:55:20 +0000

Note: This post is part of C# Advent 2023, to check out the entire series check out the whole Calender Big shoutout to @mgroves for organizing.

Earlier this year I received an issue whereby one of our users had taken to extending Redis OM .NET to integrate with GraphQL and was experiencing difficulty. Redis OM .NET is a LINQ-based Redis Search and Query client.

Now, integrating with GraphQL is not a supported feature, but given that the user had contributed to the library in the past, and offered up their own PR, I figured I ought to take a look. Now, I'm not by any stretch of the imagination a GrpahQL expert, but by golly the thing seemed to actually work. Not only that, but it seemed to work with minimal intervention needed from the user. So in this post I'm going to lay out what you need to do to get GraphQL issuing well-formed Redis Queries.

Note: this is not offically supported by Redis OM .NET
Big shoutout to Rohan Edman whose issue inspired this post.

Prerequisties

.NET 7 SDK
Docker
A GraphQL IDE (I'm using Banana Cake Pop)

Start Redis Stack

First and foremost we need to start our Redis Stack instance, just run docker run -p 6379:6379 redis/redis-stack-server or otherwise your favorite way to run Redis Stack.

Jump straight to the code

All the code for this project can be found by cloning this Repo.

git clone https://github.com/slorello89/redis-om-graphql-example

You can just clone that and

Integrating HotChocolate with Redis OM .NET

Hot Chocolate is part of the Chilli Cream GraphQL platform that serves as a GraphQL Server for .NET instances. That's what we'll be using to esentially serve as the first step of middleware in our translation layer between GraphQL and Redis.

Create the project

Create the project by running:

dotnet new web -n GraphQL

And changing directories into the project.

cd GraphQL

Add Redis.OM and Hot Chocloate Packages

Now you just need to add the hot chocloate and Redis OM Packages:

dotnet add package Redis.OM
dotnet add package HotChocolate.AspNetCore --version 13.7.0
dotnet add package HotChocolate.Data --version 13.7.0

Fetch the data needed for this project

In the source Repo, there's a folder called data, download these json files and add them to a new directory in the root of your project called data. Then in the .csproj file add the following directive to see that they are copied to the build directory:

<ItemGroup>
    <Content Include="./data/*.*">
        <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
    </Content>
</ItemGroup>

Create Model

We are going to be inserting a bunch of book data into Redis, we need to add a simple data model to do this:

using Redis.OM.Modeling;

namespace GraphQL;

[Document(StorageType = StorageType.Json)]
public class Book
{
    [Indexed]
    [RedisIdField]
    public string? Id { get; set; }

    [Searchable]
    public string? Title { get; set; }

    [Searchable]
    public string? SubTitle { get; set; }

    [Searchable]
    public string? Description { get; set; }

    [Indexed]
    public string? Language { get; set; }

    [Indexed]
    public long? PageCount { get; set; }

    [Indexed]
    public string? Thumbnail { get; set; }

    [Indexed]
    public double? Price { get; set; }

    [Indexed]
    public string? Currency { get; set; }

    public string? InfoLink { get; set; }

    [Indexed]
    public string[]? Authors { get; set; }
}

In Redis Terms, the Indexed attributes indicate that they will be stored as tag fields for Exact matches, and Searchable indicates that the field will be stored as a Text field for full-text search.

Create Bootstrapping Service

We will add an IHostedService to seed Redis with all the necessary data. Create a file called StartupService.cs and add the following:

using System.Text.Json;
using Redis.OM;
using Redis.OM.Contracts;

namespace GraphQL;

public class StartupService : IHostedService
{
    private readonly IRedisConnectionProvider _provider;

    public StartupService(IRedisConnectionProvider provider)
    {
        _provider = provider;
    }

    public async Task StartAsync(CancellationToken cancellationToken)
    {
        var books = _provider.RedisCollection<Book>();
        _provider.Connection.DropIndexAndAssociatedRecords(typeof(Book));
        await _provider.Connection.CreateIndexAsync(typeof(Book));

        var files = Directory.GetFiles("data");
        foreach (var file in files)
        {
            var tasks = new List<Task>();
            var str = await File.ReadAllTextAsync(file, cancellationToken);
            var options = new JsonSerializerOptions { PropertyNameCaseInsensitive = true };
            var booksInFile = JsonSerializer.Deserialize<Book[]>(str, options);
            foreach (var book in booksInFile)
            {
                tasks.Add(books.InsertAsync(book));
            }

            await Task.WhenAll(tasks);
        }

    }

    public Task StopAsync(CancellationToken cancellationToken) => Task.CompletedTask;
}

At startup this will:

Drop the Books index and anything that was in it.
Create the Books index
Insert all the books read out of our json files in the data directory into Redis

Create Query Class

Hot Chocolate requires you to have a query class to perform the queries on your data. Let's just crate a file Query.cs and add the following to it:

using HotChocolate.Resolvers;
using Redis.OM.Contracts;
using Redis.OM.Searching;

namespace GraphQL;

[ExtendObjectType("Query")]
public class Query
{
    private readonly IRedisCollection<Book> _books;

    public Query(IRedisConnectionProvider provider)
    {
        _books = provider.RedisCollection<Book>();
    }

    [UsePaging(IncludeTotalCount = true, MaxPageSize = 10)]
    [UseProjection]
    [UseFiltering]
    public IQueryable<Book> GetBook(IResolverContext context) => _books.Filter(context);
}

In here, we are depenency injecting an IRedisConnectionProvider to create the Books collection, and then we are simply calling the extension Filter on our Books collection using the ResolverContext, that comes from HotChocolate tellin the IQueryable _books how to query for books in Redis. the IRedisCollection<Book> is an IQueryable that just knows how to properly parse the expressions it's provided by Hot Chocolate into a usable RediSearch Query.

Configure our Services / App

Finally, in Program.cs we need to depenency inject our IRedisConnectionProvider:

builder.Services.AddSingleton<IRedisConnectionProvider>(new RedisConnectionProvider("redis://localhost:6379"));

then we need to add our StartupService:

builder.Services.AddHostedService<StartupService>();

then we need to configure our GrpahQL Service:

builder.Services.AddGraphQLServer()
    .AddProjections()
    .AddFiltering()
    .AddQueryType(d => d.Name("Query"))
    .AddType<Query>();

Notice how we are adding projection, filtering, and our query type.

Then we need to build our app and map our GraphQL service:

var app = builder.Build();

app.MapGet("/", () => "Hello World!");
app.MapGraphQL();
app.Run();

And that's it!

Start the Project

To start the project just run dotnet run from the directory you clone the GitHub repo into.

The exact endpoint that it will take on will displayed in your terminal, in my case the endpoint is http://localhost:5097

Open up your GraphQL GUI of choice, and point it at <Your-endpoint>/graphql, et voila, you have a graphQL endpoint that will faithfully take your GraphQL queries and attempt to parse them as Redis Queries. take the following example:

This query:

query {
  book(where: { description: { eq: "Redis" } pageCount: {lt: 100}}) {
    nodes {
      title
      subTitle
      description
      pageCount, 
      infoLink
    }
  }
}

Is translated to:

"FT.SEARCH" "book-idx" "((@PageCount:[-inf (100]) (@Description:\"Redis\"))" "LIMIT" "0" "11" "RETURN" "15" "Title" "AS" "Title" "SubTitle" "AS" "SubTitle" "Description" "AS" "Description" "PageCount" "AS" "PageCount" "$.InfoLink" "AS" "InfoLink"

In Redis, which is exactly what you would expect. and it does all of this with what minimal code and effort.

Resources

The code for this post is all in its Repo
You can Learn more about Hot Chocolate on their website
To learn more about Redis OM, visit its Repo
To learn more about Redis, visit redis.io

Redis University RU102N: Redis for .NET Developers

Steve Lorello — Wed, 01 Feb 2023 13:16:05 +0000

Hello all! I wanted to share the culmination of something I've been working on the last few months, and realistically have been concocting since I metaphorically stepped through the doors at Redis as its .NET Advocate in June of 2021. I've just released the new RU102N: Redis for .NET Developers course in Redis University.

Redis University is a free, online learning platform that's intended to teach you everything you need to know about Redis.

What You'll Learn

The best practices for using the Redis client StackExchange.Redis
How to do all the normal Redis things (data structures, streams, pipelining, pub/sub, transactions).
How to interact with Redis from ASP.NET (both core and classic), and deploy some of the most common use-cases of Redis in these environments.
How to interact with Redis Stack from .NET. Both directly from the StackExchange.Redis ad-hoc API, as well as the third-party ecosystem that's sprung up around it.
How to index, store, query, and aggregate your objects in Redis using Redis OM .NET

How You'll Learn

The course is run through Redis University's Learning Management System(LMS), and is chock full of code examples that you can use to learn by doing. At the end of the course there's an assessment to see what you've learned. If you pass the assessment you'll be awarded a certificate for the course. You can also interact with me and other learners in our course Discord Channel on Redis's Discord server. The course is slated for "6 weeks" for about 3 hours per week, but it is mostly self paced (we do turn the courses over ever 6 weeks so just finish on time!) You could realistically sit down with the materials for a few days and come away with a strong knowledge of how to use Redis from .NET.

Special Thanks

I want to give a big shout out Simon Prickett who was my second set of eyes on the course, and who helped me navigate our LMS.
Also a huge thanks to Marc Gravell and Nick Craver, who are the maintainers of StackExchange.Redis, and without whom this course literally would not be possible.
Naturally, a huge thanks to those .NET users of Redis who's collective knowledge and experience I've sought to condense and synthesize into this course.

Course Resources

The course itself is in Redis University
The course's GitHub Repo
If you are not familiar with Redis, RU101 covers everything you'd need to know from Redis' perspective prior to starting the course.

Happy learning! Tell your friends!

Indexing and Querying Embedded Objects with Redis OM .NET

Steve Lorello — Mon, 19 Dec 2022 11:37:17 +0000

This post is my entry for this year's C# Advent - I'd encourage anyone reading this to look at this year's advent calendar and check out some of the great content that's been produced for it!

Before I get started - for those .NET devs interested learning Redis, I'd encourage you to sign up for my free course Redis For .NET Developers, coming early next year - it'll be a deep dive into using Redis from the .NET eco-system.

Anyway let's get stared. For those of you who were here last year, you might remember my 2021 C# Advent post was CRUD With Redis OM .NET - the LINQ based Object Relation Mapper(ORM) (well really just OM since there's no relations in Redis:) ). It was a prescient moment to write that post given I had just released the first version of Redis OM days earlier. In this post, we'll walk through what I think is the most consequential new feature added to Redis OM .NET since I authored it in late 21' - the ability to index and query embedded objects within your documents in Redis.

Jump Straight to the code

The code for this post is located in GitHub

Prerequisites

A .NET SDK that complies with .NET Standard 2.0 - I'm going to use the .NET 7 SDK, but you can easily adapt these examples to your workflow
An IDE to work with C# from (I'll use Rider)
Docker

Spin up Docker

First things first, we'll need to spin up docker, you'll need to use an instance of Redis Stack for this, the easiest way to get one
up and running is to use:

docker run -d -p 6379:6379 redis/redis-stack-server

Embedded Objects in Redis. . . Huh????

Hold-on, index and query? You might say. Redis is a key-value store what do you mean by that? Well, if you read through my C# Advent post from last year: CRUD With Redis OM .NET you'll see that RediSearch (which would be folded into Redis Stack which you are now running in docker) provides the ability to store, index, and query documents in Redis. And Redis OM .NET, the library I wrote to go along with Redis Stack's indexing and querying capabilities. So what's an embedded object? In this context, we mean that you have a complex object stored within a document. So if we have the following model:

public class Elf
{
    public string Id { get; set; }
    public string FirstName { get; set; }
    public string LastName { get; set; }
    public int Age { get; set; }
    public Address HomeAddress { get; set; }
    public Address WorkAddress { get; set; }
}

public class Address
{
    public string StreetAddress { get; set; }
    public string PostalCode { get; set; }
    public GeoLoc Location { get; set; }
    public Address ForwardingAddress { get; set; }
}

In the initial version of Redis OM .NET, you would have been able to index all the simple scalars at the top level of Elf(FirstName, LastName, Age), but you would not be able to index and query Elf.HomeAddress and Elf.WorkAddress. However, as of v0.1.8, you can now index and query embedded documents in Redis. So let's get to it!

Create our project

First things first, let's create our project and then cd into it, run the following in your terminal:

dotnet new console -n CS.Advent.TwentyTwo
cd CS.Advent.TwentyTwo

Add Redis OM .NET to your project

Next, you just need to add Redis OM .NET to your project file, the simplest way to do this, since you're already in your terminal is to run:

dotnet add package Redis.OM

Now you can open CS.Advent.TwentyTwo in your IDE of choice.

Create our Model

Create a file Model.cs to it, and add the model from above to it. Now, if you followed along with my other post, you'll see that you can define a storage type for them (use JSON here) by using the DocumentAttribute - so for our Elf class we could use one like:

[Document(StorageType = StorageType.Json, IndexName = "Elves", Prefixes = new []{"Elf"})]
public class Elf

Since we aren't actually going to be storing addresses at the root level, we do not need to add a DocumentAttribute to our Address class.

Index our Scalars

The next thing we need to do is to define the index on our scalars. This is straight forward, with the exception of StreetAddress add a Indexed attribute to each scalar (including the GeoLoc, but excluding the Address typed fields). For StreetAddress add the Searchable tag, and for the Id field add the RedisIdField attribute as well, when you're done the model should look like this:

[Document(StorageType = StorageType.Json, IndexName = "Elves", Prefixes = new []{"Elf"})]
public class Elf
{
    [RedisIdField] [Indexed] public string Id { get; set; }
    [Indexed] public string FirstName { get; set; }
    [Indexed] public string LastName { get; set; }
    [Indexed] public int Age { get; set; }
    public Address HomeAddress { get; set; }
    public Address WorkAddress { get; set; }
}

public class Address
{
    [Searchable] public string StreetAddress { get; set; }
    [Indexed] public string PostalCode { get; set; }
    [Indexed] public GeoLoc Location { get; set; }
    public Address ForwardingAddress { get; set; }
}

Index our Embedded Objects

Now that we've indexed our scalars, we'll want to index our embedded objects. That's our HomeAddress, WorkAddress, and ForwardingAddress. There's two ways to do this

Provide the JSON Path to the parts of the document to Index.
Cascade into the document to a certain depth.

JSON Path Indexing

To index via JSON path, add a JSON path in your IndexAttribute defining exactly what you want to index. So if you wanted to index only the PostalCode and Location of the WorkAddress you would just need to add the JSON path to them in a series of IndexedAttributes.

[Indexed(JsonPath = "$.PostalCode")]
[Indexed(JsonPath = "$Location")]
public Address WorkAddress { get; set; }

Cascading Index

If you want to cascade into the object and index everything underneath it as defined, you just need to set a CascadeDepth. When the CascadeDepth property is specified in the Indexed attribute, Redis OM will recursively search the object tree down to the specified depth and index everything underneath it. So if we wanted to pick up our HomeAddress.ForwardingAddress you would set the ForwardingAddress's cascade depth to 1:

[Indexed(CascadeDepth = 1)]
public Address ForwardingAddress { get; set; }

And the HomeAddress's cascade depth to 2:

[Indexed(CascadeDepth = 2)]
public Address HomeAddress { get; set; }

Create our Index

Let's switch gears and actually create our index in Redis. All we need to do to do that is connect our RedisConnectionProvider and call IRedisConnection.CreateIndex, switch over to our Program.cs file and add the following:

using CS.Advent.TwentyTwo;
using Redis.OM;

var provider = new RedisConnectionProvider("redis://localhost:6379");
provider.Connection.CreateIndex(typeof(Elf));

Add our Elves

Let's add a couple elves from Christmas cannon into Redis. We'll use Buddy from Elf, and Bernard from the Santa Clause - an amusing constraint for Redis is that it cannot index anything above the 85th parallel, so we'll put Bernard in Alaska, and Buddy in NY:

var buddy = new Elf
{
    FirstName = "Buddy",
    LastName = "Hobbs",
    Age = 30,
    HomeAddress = new Address { StreetAddress = "55 Central Park West", PostalCode = "10023", Location = new GeoLoc(-73.979,40.772) },
    WorkAddress = new Address { StreetAddress = "119 West 31st Street", PostalCode = "10001", Location = new GeoLoc(-73.991,40.748) }
};

var bernard = new Elf
{
    FirstName = "Bernard",
    LastName = "The Arch Elf",
    Age = 1530,
    HomeAddress = new Address{StreetAddress = "101 St Nicholas Dr", PostalCode = "99705",Location = new GeoLoc(-147.343, 64.755)},
    WorkAddress = new Address{StreetAddress = "101 St Nicholas Dr", PostalCode = "99705",Location = new GeoLoc(-147.343, 64.755)}
};

var elves = provider.RedisCollection<Elf>();

elves.Insert(buddy);
elves.Insert(bernard);

Query our Elves

Now all we need to do is try querying our elves. If you wanted to query all the elves at the postal code 99705, all you'd need to do is run the query:

var elvesAt99705 = elves.Where(x=>x.WorkAddress.PostalCode == "99705");

foreach (var elf in elvesAt99705)
{
    Console.WriteLine($"{elf.FirstName} works in the 99705 postal code");
}

Likewise if you want to query all the Elves near Macy's you can do so bu running a geo-filter against the Location property:

var elvesNearMacys = elves.GeoFilter(x=>x.HomeAddress.Location, -73.991,40.750,2, GeoLocDistanceUnit.Miles);

foreach (var elf in elvesNearMacys)
{
    Console.WriteLine($"{elf.FirstName} is near Macy's");
}

Run our Code

All that's left to do is run our code, if you run:

dotnet run

from the terminal, everything will execute, and you'll see that Bernard is in fact in Alaska, and Buddy is in NY!

Wrapping up

Thanks for stopping by the C# Advent, hopefully you found this useful. Here's some more resources for you if you're interested in Redis, Redis Stack, and Redis OM:

The Best place to learn about Redis OM is currently it's README in GitHub
There's also a tutorial for Redis OM .NET on Redis Developer
As I mentioned at the top, I am putting together a course- Redis for .NET Developers which is free and will be available early next year
If you're interested in my work - please follow me on Twitter or GitHub

CRUD with Redis OM .NET - C# Advent

Steve Lorello — Thu, 16 Dec 2021 11:26:37 +0000

Tis the season of C# Advent again and for my topic, I'm going to talk about a library I recently wrote, Redis OM. Big thanks to all the contributors of C# advent and to Matthew Groves and Calvin Allen for organizing it this year. if you haven't yet, make sure you check out all the great content the community has put out this year.

Redis is a NoSQL database that's loved for its simplicity and speed. Those two virtues make it the most loved database by developers. But there's a problem inherent in Redis if you want to store more complicated objects. Redis is a key-value data structure store. This means that if you're going to perform CRUD(Create Read Update and Delete) operations on your data, and the only way you care to access the data is by your key, you'll have no problem. But what if we wanted to look up items by value? This is where things can get tricky in Redis, and that's also where the story of Redis OM begins. Querying items by their values in Redis requires a fair amount of legwork on the developers' part to manually build and maintain secondary indexes for those objects. After that, you need to execute several commands to perform your query. With Redis OM and RedisJSON, you can build your model ahead of time and query them with a LINQ interface.

Our Model

We're going to use this Customer object as our model throughout our examples:

public class Customer
{
   public string FirstName { get; set; }
   public string LastName { get; set; }
   public string Email { get; set; }
   public int Age { get; set; }
}

We will assume that we want to search on any field in Customer. With that in mind, we'll go through what we would have to do in Redis OM and what we would have had to do in prior iterations of Redis for the basic operations of persistent storage - Create Read Update and Delete (CRUD).

Setting up

Start up Redis

First, we'll set up our environment. Then, for development purposes, we'll use Docker to run Redis:

docker run -p 6379:6379 redislabs/redismod

Set up our project

Next, we'll set up our project. Then, finally, we'll just run this all as a console app:

dotnet new console -n RedisOmComparison

Cd into the RedisOmComparison directory, and run dotnet add package Redis.OM to install Redis OM.

Initialize connection objects

Now we'll initialize our two connection objects. The ConnectionMultiplexer for our standard redis Setup and the RedisConnectionProvider for the Redis OM setup. In program.cs run the following:

// Standard Redis
var muxer = await ConnectionMultiplexer.ConnectAsync("localhost");
var db = muxer.GetDatabase();

// Redis OM
var provider = new RedisConnectionProvider("redis://localhost:6379");

Initialize Bob

So we are consistent, we'll use the same customer object across both examples, Bob:

var bob = new Customer 
{
   Age = 35, 
   Email = "foo@bar.com", 
   FirstName = "Bob", 
   LastName = "Smith"
};

Create indexed objects in Redis with Redis OM

To create an object in Redis with Redis OM, we'll start with our initial model but add some attributes to it. First, we'll decorate the class itself with the Document Attribute, and then we'll decorate each of the properties with the Indexed attribute. After this is done, our Customer object should look like this:

[Document]
public class Customer
{
   [Indexed(Sortable = true)] public string FirstName { get; set; }
   [Indexed(Sortable = true)] public string LastName { get; set; }
   [Indexed(Sortable = true)] public string Email { get; set; }
   [Indexed(Sortable = true)] public int Age { get; set; }
}

This should be stored in a new file - Customer.cs

Create the index

Now that you've declared the Customer with indexing in mind, you'll just create the index. This only has to be done once per index. In Program.cs add:

provider.Connection.CreateIndex(typeof(Customer));

Add a customer

All that's left to do is add a customer, create a RedisCollection<Customer>, and simply insert a new customer into Redis.

var customers = provider.RedisCollection<Customer>();
var customerId = await customers.InsertAsync(bob);

Create indexed objects in Redis without Redis OM

Creating indexed objects without Redis OM will be a bit more complicated. We're going to have to go through three stages, which will need to run each time we add something.

Create a key name
Map the object to a hash and create the hash
Update the indexes associated with each item

Key name

We'll use Customer:AGuid as our key name to keep it simple.

var keyName = $"Customer:{Guid.NewGuid()}";

Create the object's hash

The natural data structure to use when storing indexable objects in Redis (without a module) is a Redis Hash. To store an object in a Redis hash, we'll need to break it down into a set of field-value pairs that we can send off to our Redis along with our Redis key. Once this is done, the object is actually stored in redis. You can do that by calling the HashSetAsync method on the DB object and passing in the properties/values of Bob as field value pairs:

await db.HashSetAsync(keyName, new HashEntry[]
{
    new HashEntry(nameof(Customer.FirstName), bob.FirstName),
    new HashEntry(nameof(Customer.LastName), bob.LastName),
    new HashEntry(nameof(Customer.Email), bob.Email),
    new HashEntry(nameof(Customer.Age), bob.Age)
});

Set up the index

Unlike Redis OM, the indexes are not set & forgotten in standard redis. Each indexed field needs to have its own separate index maintained. For this purpose, for each field, we'll keep different sorted sets. For each string field name, this will be a sorted set for each value, and forage will be a single sorted set. Mind you, later, when we update items in Redis, these will also need to be updated. To create the indexes, run the following code:

await db.SortedSetAddAsync($"Customer:FirstName:{bob.FirstName}", keyName, 0);
await db.SortedSetAddAsync($"Customer:LastName:{bob.LastName}", keyName, 0);
await db.SortedSetAddAsync($"Customer:Email:{bob.Email}", keyName, 0);
await db.SortedSetAddAsync($"Customer:Age", keyName, bob.Age);

Comparison

So after the preliminary steps to initialize the index for redis OM (decorating the class and calling CreateIndex once), creating a customer object is very straightforward:

var customerId = await customers.InsertAsync(bob);

Versus doing so without Redis OM:

var keyName = $"Customer:{Guid.NewGuid()}";

await db.HashSetAsync(keyName, new HashEntry[]
{
    new HashEntry(nameof(Customer.FirstName), bob.FirstName),
    new HashEntry(nameof(Customer.LastName), bob.LastName),
    new HashEntry(nameof(Customer.Email), bob.Email),
    new HashEntry(nameof(Customer.Age), bob.Age)
});

await db.SetAddAsync($"Customer:FirstName:{bob.FirstName}", keyName);
await db.SetAddAsync($"Customer:LastName:{bob.LastName}", keyName);
await db.SetAddAsync($"Customer:Email:{bob.Email}", keyName);
await db.SortedSetAddAsync($"Customer:Age", keyName, bob.Age);

Naturally, the former is much more straightforward, and it only requires a single round trip to Redis to accomplish!

Reading data out of Redis with an Id

Now that we've inserted our data into Redis, how can we read it? Well, there are two dimensions to think about 1: How are you querying objects? 2: How are you marshaling your objects?

There are two types of ways to query your objects 1: by key 2: by values. In the former case, querying is straightforward in both cases:

With Redis OM

To read an Item out of Redis with Redis OM, just use the generic FindById command:

var alsoBob = await customers.FindByIdAsync(customerId);

Without Redis OM

Without Redis OM, you'll need to call HGETALL and then build a new instance of the object from the hash, which takes a bit more effort:

var bobHash = await db.HashGetAllAsync(keyName);
var manuallyBuiltBob = new Customer
{
    Age = (int)bobHash.FirstOrDefault(x=>x.Name == "Age").Value,
    FirstName = bobHash.FirstOrDefault(x=>x.Name == "FirstName").Value,
    LastName = bobHash.FirstOrDefault(x=>x.Name == "LastName").Value,
    Email = bobHash.FirstOrDefault(x=>x.Name == "Email").Value,
};

Reading data out of Redis by Value

This is where things start to get interesting. Many database use cases require the ability to look items up by values. For Example, if we wanted to find all the customers named "Bob" in a traditional SQL database, we'd just run SELECT * FROM Customers WHERE FirstName = 'Bob'. However, by default, Redis lacks the concept of a table scan to look up records by a given value. That's why earlier, we constructed secondary indexes for both types. So now, let's look at querying items by their values.

Query by FirstName Redis OM

To query by the FirstName property in Redis OM, all you need is a simple LINQ statement:

var bobsRedisOm = customers.Where(x => x.FirstName == "Bob");

Then when that collection enumerates, all of the Bobs currently in Redis will be populated as Customers.

Querying by FirstName without Redis OM

Querying by First Name without Redis OM is more complicated, as has been typical so far. This time, you need to read the Set containing all the Bobs, and then you need to query each of those Ids individually:

var bobIds = await db.SortedSetRangeByRankAsync($"Customer:FirstName:Bob");
var bobsWithoutOm = new List<Customer>();

foreach (var id in bobIds)
{
    var hash = await db.HashGetAllAsync(id.ToString());
    bobsWithoutOm.Add(new Customer
    {
        Age = (int)hash.FirstOrDefault(x=>x.Name == "Age").Value,
        FirstName = hash.FirstOrDefault(x=>x.Name == "FirstName").Value,
        LastName = hash.FirstOrDefault(x=>x.Name == "LastName").Value,
        Email = hash.FirstOrDefault(x=>x.Name == "Email").Value,
    });
}

Query by Age Redis OM

To query by Age in Redis OM, we can use the typical operators we would use for numerics >=,<=,>,<,==

var under65RedisOm = customers.Where(x=>x.Age < 65);

Query by Age without Redis OM

Querying by Age without Redis OM is similar to how querying strings would work. Except for this time, you would just send a range query to the sorted Set:

var under65IdsWithoutRedisOm = db.SortedSetRangeByScore($"Customer:Age", 0, 65);
var under65WithoutRedisOm = new List<Customer>();

foreach (var id in under65IdsWithoutRedisOm)
{
    var hash = await db.HashGetAllAsync(id.ToString());
    under65WithoutRedisOm.Add(new Customer
    {
        Age = (int)hash.FirstOrDefault(x=>x.Name == "Age").Value,
        FirstName = hash.FirstOrDefault(x=>x.Name == "FirstName").Value,
        LastName = hash.FirstOrDefault(x=>x.Name == "LastName").Value,
        Email = hash.FirstOrDefault(x=>x.Name == "Email").Value,
    });
}

Updating objects in Redis

The mechanics of updating objects in Redis is pretty straightforward. For a hash, you simply call HSET and pass in the key and the field/value pairs you'd like to update. However, when you're indexing items, you need to coordinate the indexes as well, at least when you're not using Redis OM:

Updating an item in Redis with Redis OM

To update an item in Redis using Redis OM, simply change an item in an enumerated collection and call Save on the collection:

foreach (var customer in customers)
{
    customer.Age += 1;
}
await customers.SaveAsync();

This will be the same regardless of what you update in the item.

Updating an item in Redis without Redis OM

To update an item in Redis without Redis OM, you'll need to first make the call to update the item, and then for each field, you update you need to adjust its index. So let's go ahead and see how we would update the Email and age attributes without Redis OM.

Updating the data

Updating the data is fairly straightforward - call HashSet on the key and each of the fields within it you want to update.

await db.HashSetAsync(keyName, new HashEntry[]{new ("Age", bob.Age + 1), new("Email", "bar@foo.com")});

Updating the indexes

With the data updated, we now have to go in and update the indexes as well. For our Email, this will involve deleting the record from the previous Email's Set and then adding it to the new Email's Set. For Age, this just means updating the members score in the sorted Set:

await db.SortedSetRemoveAsync($"Customer:Email:{bob.Email}", keyName);
await db.SortedSetAddAsync($"Customer:Email:@bar@foo.com", keyName, 0);

await db.SortedSetAddAsync($"Customer:Age", keyName, bob.Age + 1);

Deleting indexed items

With Redis OM

When deleting an indexed item in Redis with Redis OM, it's as easy as calling Unlink on the item's key:

provider.Connection.Unlink(customerId);

Without Redis OM

Without Redis OM, you will, in addition to having to delete the key, have to go into all the sets for the accompanying indexed fields and remove the key from there too:

await db.KeyDeleteAsync(keyName);
await db.SortedSetRemoveAsync($"Customer:Email:{bob.Email}", keyName);
await db.SortedSetRemoveAsync($"Customer:FirstName:{bob.FirstName}", keyName);
await db.SortedSetRemoveAsync($"Customer:LastName:{bob.LastName}", keyName);
await db.SortedSetRemoveAsync($"Customer:Age", keyName);

Summing up

As we've seen throughout this article, Redis OM is a real boon when you are performing all of the CRUD operations with Redis, as it vastly decreases the complexity of each type of operation. Not only that, but because you can complete everything in Redis OM with a single command, you remove any concerns of conflicting updates and any cross-shard complexity associated with updating stuff in Redis.

Resources

There's a tutorial for Redis OM on developer.redis.com
If you want to open an issue or PR for Redis OM - feel free to stop by in GitHub
To learn more about Redis in general - check out redis.io
To learn more about RedisJSON - the module that powers the search features in Redis - checkout redisjson.io

Analyzing Stocks with .NET

Steve Lorello — Sun, 26 Jul 2020 17:28:38 +0000

Year after year, hedge fund managers somehow manage to outperform their benchmarks and even create profits with extreme market headwinds. How do they do it is a reasonable question to ask. There's a varied set of answers to that question. Much of it has to do with physical location and infrastructure. Part of it that I like to take solace in is that they do it largely with computational models and algorithms with which many programmers are familiar. They build models that analyze stocks at many levels and have programs that execute the trading strategies they've trained their models to implement. Most hedge fund Quantitative Analysts (Quants) have backgrounds in Computer Science, Math, Engineering, and Physics rather than or in addition to traditional MBAs. And it's the skills they learned in those fields that are great value adds.

In this post, we'll be brushing the surface of these folks do. We'll learn to study historical price and volume data of stocks in an attempt to indicate future performance.

Technical Analysis

Technical Analysis is the study of historical price and volume data of equity in an attempt to forecast what it will do in the future. Before we begin, I'll lay one big caveat. According to some varieties of the Efficient Market Hypothesis, all information is baked into the price of a stock. So there's no edge to be had by studying historical data. Despite this, hedge funds persist in analyzing these trends, and consequentially so shall we!

What's an Indicator

We'll be attempting to extract indicators from our historical price data, but what is an indicator? An indicator boils down to a number that "indicates" to us the direction of the price. Generally, we'll be looking for outliers in the price to determine whether there's a basis to assume the stock is "oversold" (less expensive than it should be) or "overbought" (more expensive than it should be). If we detect those signals, we can move on the equity and potentially exploit an arbitrage in a slightly less than efficient market while the price of the stock corrects itself. We'll be looking at two such indicators - Simple Moving Average(SMA) Ratio, and Bollinger Bands® Percentage(BBP). We will also be looking at several other indicators used to calculate the SMA Ratio and the BBP. These indicators include the SMA, rolling volatility, and Bollinger Bands®.

Create the Project

We'll dive right into the code now, so go ahead and create a .NET Core Console Application project and add the following NuGet packages to it:

Daany.DataFrame
Numpy
ScottPlot

Python heavily inspires virtually everything we're going to do here. The NumPy library, which is what we're going to use to speed up our analysis, is dependant on a python runtime that ships with it.

For now create a folder called data, and files BollingerBandsPercentage.cs, RollingVolatility.cs, and SimpleMovingAverage.cs.

Getting Historical Data

The key thing we'll need for technical analysis is historical stock data these data are readily available online at Yahoo Finance. It's a matter of searching for a particular equity, going to it's Historical Data tab, deciding on a period you'd like to grab records for and downloading it. These records come in Comma Separated Value (CSV) files. I'm going to get five years of this data for Apple (AAPL), JP Morgan Chase (JPM), and a major S&P 500 ETF (SPY). Add the three CSV files to your data folder. In Visual Studio, set the build action CSV to Content and the Copy to Output Directory to Copy Always.

Reading in The Data

Now that we have all this historical stock data, we are going to read it in. We'll do this with the DataFrame.FromCsv method and store it in a DataFrame object. We'll also declare a constant int WINDOW which we're going to use as the window over which we'll be calculating our window averages.

const int WINDOW = 20;
var symbol = "AAPL";
var df = DataFrame.FromCsv(Path.Join("data", $"{symbol}.csv"));

The df variable will now contain a dataframe, an in-memory representation of the .csv file. As we discussed earlier, there are two things we can study in technical analysis, Volume, and Price. These CSV files contain several prices, Open, High, Low, Close, Adj Close, and a representation of the Volume and Date for each date in the record.

Open is the price of the equity at the opening bell. High is the high highest price the equity traded for that day. Conversely, low is the lowest price the equity traded for that day.

Then there are two fields representing the closing price on the date. The "Close" is the price the stock traded for at the end of the day. And the Adjusted Close is the closing price adjusted for any stock splits or dividends. The Adjusted Close has to be updated whenever we hit one of those events. It's this Adj Close field that we will be paying the most attention to for these examples.

Extracting Out the Adj Close

The DataFrame are represented more like dictionaries in C# as opposed to the traditional python Pandas. You can access the set of Adjusted Closes by indexing into the DataFrame on Adj Close. Then we can use a little bit of LINQ to pull the values into an array.

I'm going to store this in a NumPy array, slice the first 20 records out as that's our window size.

var close = np.array(df["Adj Close"].Select(f => Convert.ToDouble(f)).ToArray()[rng])[$"{WINDOW - 1}:"];

Notice how we access the ranges inside the NumPy array? It looks a lot like traditional NumPy slicing notation, except it's using a string.

Calculating Simple Moving Average

The simplest, pardon the pun, of the indicators we are going to look at is the Simple Moving Average. The SMA is, for each date in the data frame, the mean of the current point and a lookback window of the point. We will use a window of 20 trading days. Thus if we wanted to calculate the SMA for September 29th, 2015, we would take that day and the previous 19 trading days, sum them up, and divide them by 20. One of the cool things about a DataFrame structure is that it makes it easy to calculate these rolling products. I've defined a separate class to run this from SimpleMovingAverage, but the method itself is just a static NDarray.

public class SimpleMovingAverage
{
    const int WINDOW = 20;
    public static NDarray CalculateSma(DataFrame df, Range rng)
    {
        return np.array(df.Rolling(WINDOW, Aggregation.Avg)["Adj Close"].Select(f => Convert.ToDouble(f)).ToArray()[rng])[$"{WINDOW - 1}:"];
    }
}

Pretty easy, right? Let's look at what we're doing here, we are calling Rolling on our dataframe, we are passing in a WINDOW of 20, and telling it to aggregate the average. Then we are accessing the Adj Close Column from our DataFrame and pulling that row out. We drop the first 20 rows from this because the first 20 rolls will be NaN as there wasn't a valid calculation.

Calculating Rolling Volatility

Another metric that we want to look at is volatility. When we are thinking about equities in general, we consider high returns (the amount of money it makes) and a low risk to be ideal - low-risk high reward! We can calculate the volatility of a particular equity by finding its standard deviation from its rolling mean. This operation is similar to calculating the SMA, but for each point, we calculate the rolling standard deviation instead.

public class RollingVolatility
{
    const int WINDOW = 20;
    public static NDarray CalculateRollingVolatility(DataFrame df, Range rng)
    {
        return np.array(df.Rolling(WINDOW, Aggregation.Std)["Adj Close"].Select(f => Convert.ToDouble(f)).ToArray()[rng])[$"{WINDOW - 1}:"];
    }
}

Bollinger Bands®

BB's are easy to understand, and powerful indicator for seeing where the price of a stock is relative to where we'd expect it.

In the graph above, we have three lines, an upper, lower, and a close. The upper band is the upper limit of the BB; the lower is the lower limit, and the close is where the stock ended up that day. When studying equities, it's threshold events that we tend to look at with indicators. In this instance, the criteria we are looking for are for the price of the stock to cross the upper or lower band. If we see it cross the upper band, it is generally a signal that the stock is overbought and primed to come back down to earth. When an equity is oversold, it can be a good time to short the stock (basically place a bet that it will go down). Conversely, if the equity sinks below it's lower Bollinger Band, it is considered oversold and primed to go up.

Calculating a Bollinger band is pretty straight forward after you've gotten the SMA and moving standard deviation. Simply multiply the standard deviation by two, then add the result to the SMA, and you have your upper band. Subtract that quantity, and you have the lower band. With what we've already built, this is a snap.

var sma = SimpleMovingAverage.CalculateSma(df, rng);
var std2x = 2 * RollingVolatility.CalculateRollingVolatility(df, rng);
var upper = sma + std2x;
var lower = sma - std2x;

There you have it; the Bollinger bands are simply two standard deviations above and below the simple moving average.

Bollinger Bands aren't gospel and can certainly be wrong. For example - Tesla (TSLA) is at the moment killing it against it's Bollinger Bands. The losses you would have gotten hit with if you followed this strategy would have almost certainly created a margin call on your account - personally, with that level of risk and volatility in share price, I'm staying well away!

Bollinger Bands Percentage

Now that we have our Bollinger Bands, we're going to want an easily calculable number to serve as an indicator as to when we can move on an equity. Bollinger Bands Percentage gives us just that. We can calculate it by finding the difference between the price and the lower band, and then dividing that by the difference between the upper and lower band. If the result is north of one, it's crossed the upper band, below zero, and it's dropped below the lower band. With what we've built so far, calculating this is just one line of code.

var bbp = (close - lower) / (upper - lower);

Simple Moving Average Ratio

Another indicator we can use to look at whether an equity is overbought or oversold is to look at the SMA ratio. You can calculate this by dividing the price by the SMA. This indicator can also tell you whether the equity is oversold or overbought. The thresholds are bit murkier, I've heard .95 to 1.05 is normal anything above being overbought, anything below being oversold - but this is likely highly dependant on the equity. Regardless this is also easy to calculate given the SMA and the closing price:

var smaRatio = close / sma;

Displaying the Indicators

Now that we've calculated them, we're going to want to display them. We're going to be using ScottPlot, which provides some pretty nice plotting functionality. We're going to display these in scatter plots. These plots will look like lines because they are so dense. Get started by initializing a plot object and setting its size, generating a set of consecutive points with DataGen.Consecutive passing in the number of points that we have.

var plt = new Plot(600, 400);
double[] xs = DataGen.Consecutive(bbp.size);

Plot SMA Ratio

We'll start by plotting the SMA ratio. Add a title to the plot, then plot the xs points with the smaRatio points (call GetData on the NDArray to pull in all the data from it), pass it a label and set the marker size to 1.

Next, tell it to put the legend in the lower-left corner. Label the Y-axis Ratio and the X-axis Day, then save a png of the plot with the SaveFig function and clear out the plot.

plt.Title($"SMA Ratio for {symbol} {startDate.ToShortDateString()} to {endDate.ToShortDateString()}");
plt.PlotScatter(xs, smaRatio.GetData<double>(), label: "SmaRatio", markerSize: 1);
plt.Legend(location: legendLocation.lowerLeft);
plt.YLabel("Ratio");
plt.XLabel("Day");
plt.SaveFig("SmaRatio.png");
plt.Clear();

The process for the other items is very similar. For the Bollinger Bands, you'll plot three different sets of data, and I found it easier to put the legend in the upper left.

Plot Bollinger Bands

plt.Title($"Bollinger Bands® for {symbol} {startDate.ToShortDateString()} to {endDate.ToShortDateString()}");
plt.PlotScatter(xs, close.GetData<double>(), label: "Close", markerSize: 1);
plt.PlotScatter(xs, upper.GetData<double>(), label: "Upper", markerSize: 1);
plt.PlotScatter(xs, lower.GetData<double>(), label: "Lower", markerSize: 1);
plt.YLabel("Dollars");
plt.XLabel("Day");
plt.Legend(location: legendLocation.upperLeft);
plt.SaveFig("BB.png");
plt.Clear();

Plot Bollinger Band Percentage

plt.Title($"Bollinger Bands® Percentage for {symbol} {startDate.ToShortDateString()} to {endDate.ToShortDateString()}");
plt.PlotScatter(xs, bbp.GetData<double>(), label: "BBP", markerSize: 1);
plt.YLabel("Dollars");
plt.XLabel("Day");
plt.Legend(location: legendLocation.lowerLeft);
plt.SaveFig("BBP.png");
plt.Clear();

After running these, plots will be written out to our bin directory looking something along the lines of these:

BB.png

BBP.png

SmaRatio.png

Wrapping up

There are lots of other indicators that you can play with each with its merit. But these are some pretty simple ones you can use to whet your appetite. It's a fascinating field, and we're just scratching the surface of it. Obviously, consult a financial advisor before investing - but hopefully, this has provided you with a glimpse into how some trading strategies work!

Next Steps

Now that we've started to create some indicators for us to look at, we can start thinking about using them in a trading strategy. Above, I listed some rules of thumb regarding the uses of these indicators in developing a strategy. Now that we have all these indicators organized so well, we can use them to create ML models to make those calls for us.

Resources

A list of technical indicators and how to calculate them that I reference can be found here
The code that I used to build this can be found on GitHub

How to Receive an SMS Message with ASP.NET Core MVC and SignalR

Steve Lorello — Mon, 20 Jul 2020 15:35:14 +0000

A core requirement of managing SMS messages in your app is receiving and acting on them in real-time. In this tutorial, we’ll learn how to receive SMS Messages from the Vonage Messaging API, and push them out to a browser in real-time. We will use ASP.NET Core MVC for our API server and web page, and we will be using SignalR to allow us to receive SMS messages in real-time.

Jump Right to the Code

If you want to just pull the code from this demo, it can all be found in GitHub

Prerequisites

You’ll need a Vonage API account
You’ll need the latest version of the .NET Core 3.1 SDK
You’ll need either Visual Studio 2019, Visual Studio for Mac, or Visual Studio Code, I will be using Visual Studio 2019 for this demo
Optional – I used Ngrok to test this demo

Vonage API Account

To complete this tutorial, you will need a Vonage API account. If you don’t have one already, you can sign up today and start building with free credit. Once you have an account, you can find your API Key and API Secret at the top of the Vonage API Dashboard.

Create the App

Open Visual Studio and click “Create a new project,” select “ASP.NET Core Web Application” and click “Next.” Give your application a name. I am going to be naming my application, “ReceiveSmsAspNetCoreMvc.” Then click create. On the next page, select “Web Application (Model-View-Controller)” and click “Create.”

Install Dependencies

Since we are using SignalR, there are two types of dependencies we need to add. First, we’ll need to add our NuGet package dependencies; then, we’ll need to add our client package dependencies.

NuGet Dependencies

We need to install two NuGet packages:

Nexmo.Csharp.Client
Microsoft.AspNetCore.SignalR.Core

There are multiple ways to do this; I will just use the dotnet CLI. Navigate to the project directory for your project and just run:

dotnet add package Nexmo.Csharp.Client
dotnet add package Microsoft.AspNetCore.SignalR.Core

Client Side Packages

Since we are dependant on the SignalR Client-Side library, we shall also need to add the SignalR Client-Side library.

In Visual Studio, right-click on your projects wwwrooot got to add->Client-Side Library. That will bring up a little dialog to help you add the library. For this demo, I used the following.

Provider: unpkg
Library: @microsoft/signalr@latest
Choose Specific files: I only selected Files/dist/browser/signalr.js and Files/dist/browser/signalr.min.js
Target Location: wwwroot/js/signalr

After completing the form, it will look something like:

After filling out this form, you can click install, and it will install the required files under wwwroot/js/signalr

Create an SMS Hub

The way SignalR works, client browsers connect to something called Hubs. Hubs push messages from the server to each of their clients over whatever available mechanism they have. Typically is a WebSocket but can be done via Server-Side-Events(SSE) or Long-Polling. We need to create a Hub in our server to connect our server to our browser clients.

Create a new folder under your project called Hubs. Under that folder, create a new C# file SmsHub.cs. This file doesn’t need to do much. It will just declare a class extending the Hub class. The file should look like the following.

using Microsoft.AspNetCore.SignalR;

namespace ReceiveSmsAspNetCoreMvc.Hubs
{
    public class SmsHub : Hub
    {
    }
}

Configure Middleware

Configure Services

We now need to go into our startup.cs file, and add the SignalR endpoints to our middleware. Adding the middleware will allow the SMS hub route to stand up and allow us to use SignalR in our browser clients. Let’s crack open startup.cs and find our way to the ConfigureServices method. Add the line services.AddSignalR(); to this method, that will add the SignalR middleware to our server. After finishing our ConfigureServices method will look like this:

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllersWithViews();
    services.AddSignalR();
}

Configure

Stay in startup.cs and find the Configure method. This method will contain a call to app.UseEndpoints, which takes a function as an argument, inside that function, we will map the SmsHub to the path /smsHub. After finishing the app.UseEndpoints call will look like:

app.UseEndpoints(endpoints =>
{
    endpoints.MapHub<SmsHub>("/smsHub");
    endpoints.MapControllerRoute(
        name: "default",
        pattern: "{controller=Home}/{action=Index}/{id?}");
});

Build an SMS Controller

Now that we have the middleware sorted, we need to add the method that will receive the SMS from Vonage. We will use an empty MVC Controller to this end. Right-click on the Controllers folder and go to add -> Controller, select “MVC Controller – Empty” and click “Add” name this SmsController and click “Add” again.

Inject our SmsHub’s Context

The first thing we’ll need to do in our SmsController injects the HubContext for the SmsHub. Declare an IHubContext<SmsHub> property called HubContext, and then declare a SmsController constructor that takes an IHubContext<SmsHub> as an argument and assign this parameter to the HubContext property. Through the magic of dependency injection, the controller receives the hub context at creation.

/// <summary>
/// Allows access to all browser clients subscribed through the /smsHub
/// </summary>
public IHubContext<SmsHub> HubContext { get; set; }

public SmsController(IHubContext<SmsHub> hub)
{
    HubContext = hub;
}

Add an Inbound Sms Handler

Now that we have access to the Hub Context, we need to add an API route for the inbound SMS. This route will be the route that Vonage uses to send a webhook to our application. This method will take the request, parse an InboundSms object from it, and send an InboundSms signal to all of the clients connected to the hub. This method will then push the MSISDN and the text of the message down to the user. For reference, the MSISDN is the number from which the message originated. Add the following to your SmsController.

[HttpPost("webhooks/inbound-sms")]
public async Task<IActionResult> InboundSms()
{
    using (var reader = new StreamReader(Request.Body))
    {
        var json = await reader.ReadToEndAsync();
        var inbound = JsonConvert.DeserializeObject<InboundSms>(json);
        await HubContext.Clients.All.SendAsync("InboundSms", inbound.Msisdn, inbound.Text);
    }
    return NoContent();
}

Build a Frontend

With that taken care of, we just need to add a frontend to our app. To this end, we’ll just take over the Home View. Open /Vies/Home/Index.cshtml and go ahead and remove the div that contains the welcome text, we won’t need that.

Next, we’ll just add a couple of script imports. We’ll import ~/js/sms.js (which we’ll create in a moment) and ~/js/signalr/dist/browser/signalr.js which is the client library we imported before. Just add these two tags, and we’ll be good to go.

<script src="~/js/signalr/dist/browser/signalr.js"></script>
<script src="~/js/sms.js"></script>

The last thing we need to do here is to add the table where we’ll display messages. We’ll just give it two columns, From Number and Message – those will correspond to the Msisdn and the Text from our inbound SMS messages.

<h1>Messages</h1>

<table class="table" id="messageList">
    <thead>
        <tr>
            <th>From Number</th>
            <th>Message</th>
        </tr>
    </thead>
    <tbody>

    </tbody>
</table>

Add the SignalR Event Handler

The last thing that we need to do is to add an event handler for our InboundSms event. We’ll do that in the sms.js file that we just referenced. Go ahead and add an sms.js file to the /wwwroot/js directory. There are three things we need to do in this file.

Build the SignalR connection to the smsHub
Register an event handler for InboundSms that will add a new row to our list of messages
Start the SignalR connection.

We can do all three of these by adding the following to the sms.js file.

"use strict";

var connection = new signalR.HubConnectionBuilder().withUrl("/smsHub").build();

connection.on("InboundSms", function (fromNumber, text) {
    var rowHtml =
        '<tr><td>' +
        fromNumber +
        '</td><td>' +
        text +
        '</td></tr>';
    $('#messageList tbody').append(rowHtml);
});

connection.start()
    .then(function () {
        console.log("connection started");
    })
    .catch(function (err) {
        console.log("Error encountered: " + err);
    })

Testing

From a development perspective, that’s all we needed to do, so let’s go ahead and get into testing. We’re going to test this with Ngrok to test this demo. Ngrok allows us to build a publicly accessible tunnel to our app, which is useful when we need to expose publicly accessible HTTP endpoints to our apps. If you are going to be testing this with IIS Express like I am, you will want to check out our explainer on the subject as there are special considerations. What this boils down to is that we need to add a --host-header option when we start up ngrok.

In Visual Studio, right-click on your csproj file and go to properties. In there, click on the Debug tab. For convenience, when we are testing, we are going to un-check the Enable SSL checkbox. Take note of the app URL and the port number from the end of it.

Start Ngrok

Next, we’ll start up ngrok. We’ll point incoming requests to the port from our app URL, and we will have the host and port replace the incoming host header. Start ngrok by running the following command in a new terminal(replace the port number with your port).

ngrok http --region=us --host-header="localhost:51835" 51835

This command will result in your terminal being taken over by ngrok. It will show you a URL accessing that URL will forward requests to your local server. This URL will be of the form http://randomhash.ngrok.io. My random hash came up d98024d97b04, so for the remainder of this explainer, just replace that value with whatever value came up for yours.

After starting up my app in IIS Express, I can navigate to my ngrok URL to ensure that it’s publicly accessible.

Configure Webhooks

If you’ll recall, we annotated our InboundSms method in our SmsController with [HttpPost("webhooks/inbound-sms")] this establishes a route for me to http://d98024d97b04.ngrok.io/webhooks/inbound-sms to make the call to inbound-sms. The last thing I need to do before I’m off and testing is to tell the Vonage where to send my SMS messages to the URL I just mentioned.

To do this, let’s navigate to https://dashboard.nexmo.com/settings. Under Default SMS Settings, set the Inbound Messages field to that URL, and change the HTTP Method to POST-JSON. Click Save Changes, and we’re ready to test. Navigate to your home page and go ahead and send your Vonage API Virtual number a test message. If you’re not sure what your Vonage Virtual Number is, you can find it in your dashboard under numbers. After messaging the server, you’ll see the SMS messages come into your server in real-time by watching the web page associated with the app.

And that’s all we need to do to receive messages and display them in real-time!

Resources

All the code for this demo can be found in GitHub

The post How to Receive an SMS Message with ASP.NET Core MVC and SignalR appeared first on Vonage Developer Blog.

SignalR without Javascript, the Promise of Blazor

Steve Lorello — Sun, 19 Jul 2020 15:38:58 +0000

SignalR is the canonical client-side async notification library for ASP.NET. With it, we can build clients that are ultra-responsive to changing conditions on our servers. But SignalR has always had one major flaw. To use it, you needed to use JavaScript. That's fair, right? We're writing web clients, which are always running in the browser, so of course, we need to use JavaScript. We'll suffer without type safety because of the functionality we're getting. It's always been a necessary evil, and we've dealt with it as such.

With the dawn of Blazor, this age of compromise is over. We can manage all of the data transfers between our servers and clients straight out of CLR types! That is what we're going to be demonstrating now.

Objectives

Let's concretize our objectives here. We're going to build a trivial Single-Paged-App(SPA) in Blazor wasm. That app will have a simple form to read inputs from users, and a table to see incoming messages.

Prerequisites

Latest .NET Core 3.1 SDK
Visual Studio Code or the latest version of Visual Studio. I will be using VS Code for this

Create Project

Navigate to your source directory in the console and run the following command.

dotnet new blazorwasm -ho -n SignalRClr

This will create a new directory SignalRClr, in that directory it will create a solution called SignalRClr and then projects:

SignalRClr.Shared.csproj
SignalRClr.Server.csproj
SignalRClr.Client.csproj

Those projects are what they say they are. The Shared will be the shared models between the client and the server. The client is going to be the compiled wasm that ends up in our client's browser. The Server is our server-side code. Run cd SignalRClr to navigate into the project's folder, then run code . to open it in VS Code.

Add Dependencies

We need to add a Microsoft.AspNetCore.SignalR.Client dependency to our SignalRClr.Client project, and a Microsoft.AspNetCore.SignalR.Core dependency to our SignalRClr.Server project. We will also need the System.ComponentModel.Annotations class for our Shared project. Cd into Client and run the following:

dotnet add package Microsoft.AspNetCore.SignalR.Client

Then cd into the Server directory parallel to the Client directory and run the following:

dotnet add package Microsoft.AspNetCore.SignalR.Core

Then cd into the Shared directory and run the following:

dotnet add package System.ComponentModel.Annotations

Build the Model

Add a file to our SignalRClr.Shared project folder called Message.cs. Here we'll add a simple message class that takes a UserName and Text. We'll annotate them to make both UserName and Text required.

using System.ComponentModel.DataAnnotations;
namespace SignalRClr.Shared
{
    public class Message
    {
        [Required]
        public string UserName { get; set; }
        [Required]
        public string Text { get; set; }
    }
}

Add Message Hub

In the Server Project, add a new folder called Hubs. In that folder, add a MessageHub class, we will add a new Hub class MessageHub that will only have one method SendMessage which will push the inbound message down to all of the HubConnection Client's using the SendAsync method.

using Microsoft.AspNetCore.SignalR;
using SignalRClr.Shared;
using System.Threading.Tasks;
namespace SignalRClr.Server.Hubs
{
    public class MessageHub : Hub
    {
        public async Task SendMessage(Message message)
        {
            await Clients.All.SendAsync("ReceiveMessage", message);
        }
    }
}

Configure Middleware

In the Startup.cs file, we'll need to add a couple of lines of code to enable the MessageHub. In ConfigureServices the line:

services.AddSignalR();

Then in the app.UseEndpoints's delegate in the Configure method, map the hub. Your UseEndpoints should look like:

app.UseEndpoints(endpoints =>
{
    endpoints.MapRazorPages();
    endpoints.MapControllers();
    endpoints.MapFallbackToFile("index.html");
    endpoints.MapHub<Hubs.MessageHub>("/messageHub"); //Add this line
});

Build the Frontend

We're going use the Client/Pages/Index.razor file for our frontend. Mind you, I'm not an expert on frontend development, so this will look simple.

So as you can see here, we have two sections, a Messages Table and a form that we'll use to send the messages.

Pull in Dependencies

We need to add a reference to Microsoft.AspNetCore.SignalR.Client and SignalRClr.Shared. We also need to inject a NavigationManager, and to clean up the HubConnection we're going to use we'll need to implement IDisposable. We will declare all this for our Index component with the following:

@page "/"
@using Microsoft.AspNetCore.SignalR.Client
@using SignalRClr.Shared
@inject NavigationManager NavigationManager
@implements IDisposable

Add the Messages Table

We now need to add a Messages Table to our component. One of the cool things about razor/blazor is that we can do all of this with the CLR types that we want to use. In particular, our Message Model. We'll create a table; then, in the Table's body, we'll loop through a Messages Array that we will declare later, and add the UserName and the Text as table data.

<h2>Messages</h2>
<table class="table-active">
    <thead>
        <tr>
            <th>User Name</th>
            <th>Text</th>
        </tr>
    </thead>
    <tbody>
        @foreach(var message in _messages)
        {
            <tr>
                <td>@message.UserName</td>
                <td>@message.Text</td>
            </tr>
        }
    </tbody>
</table>

Add Message Form

Next, we'll add an EditForm to provide it our Message model and add a ValidSubmit method to run when the form has successfully validated.

<EditForm Model="@_message" OnValidSubmit="SendMessage">
    <DataAnnotationsValidator />
    <ValidationSummary />
    <h3>User Name</h3>
    <input @bind="@_message.UserName" placeholder="User Name" class="input-group-text" />
    <h3>Text</h3>
    <input @bind="@_message.Text" placeholder="User Name" class="input-group-text" />
    <br />
    <button class="btn btn-primary" type="submit">Send Message</button>
</EditForm>

Add Component Code

We will need to add a @code block to our component now. This block is all the logic our page needs to execute. We will add a _hubConnection property, which will manage the sending and receiving messages from our server over SignalR. We will add a _messages list, which is simply the messages we've received from the server. And we'll add a _message field, which will simply be the model we use for sending messages.

When initializing the Component, we will create the HubConnection, mapping it to the /messageHub URI we declared in our middleware. When that HubConnection gets a Receive Message signal, it will add the inbound message to our _messages collection and notify the component the state has changed. Naturally, when we get a valid submission from our form, we will submit that new message to the server. Finally, when finalizing the component, we will dispose of the _hubConnection. All the code to do this looks like:

@code {
    private HubConnection _hubConnection;
    private List<Message> _messages = new List<Message>();
    private Message _message = new Message();

    protected override async Task OnInitializedAsync(){
        _hubConnection = new HubConnectionBuilder()
            .WithUrl(NavigationManager.ToAbsoluteUri("/messageHub"))
            .Build();

        _hubConnection.On<Message>("ReceiveMessage",
            (message)=>{
                _messages.Add(message);
                StateHasChanged();
        });
        await _hubConnection.StartAsync();
    }

    public async Task SendMessage()
    {
        await _hubConnection.SendAsync("SendMessage", _message);
        _message = new Message();
    }

    public void Dispose()
    {
        _ = _hubConnection?.DisposeAsync();

    }
}

That's It

And that's it! Everything we need to do to manage simple messages in real time between clients. To run this project, you can run the Server project. Cd into the Server directory and run dotnet run, and it will launch the project. Navigate to localhost:5000 (or wherever you configure it to run kestrel) in your browser, and you will see our little message program.

Wrapping Up

Naturally, this was a simple example that explicitly shows how simple it is to use these frameworks together. But these are the building blocks of how Blazor can be used to wipe out the need for javascript when interacting with our models.

Resources

The source code from this demo can be found in GitHub

How to Receive an SMS With Blazor and SignalR

Steve Lorello — Tue, 14 Jul 2020 13:39:13 +0000

When it comes to managing SMS messages with the Vonage Messaging API, receiving inbound SMS messages is paramount. In this tutorial, we’re going to explore receiving SMS messages into our app and pushing them out to our front end in real-time using Blazor and SignalR Core.

Jump Right to the Code

If you just want to jump right to the code, just visit this demo’s repository in GitHub.

Prerequisites

You’ll need a Vonage API account. You can sign up here
You’ll need the latest version of the .NET Core 3.1 SDK
You’ll need either Visual Studio 2019, Visual Studio for Mac, or Visual Studio Code, I will be using VS Code for this demo

Vonage API Account

Create the App

Navigate to a directory where you want to put the project folder and run the following command in your terminal.

dotnet new blazorserver -o ReceiveSmsBlazor

After that’s done, cd into the ReceiveSmsBlazor folder that we created and run code . to launch VS Code. Alternatively, you can open the ReceiveSmsBlazor.csproj file in Visual Studio.

Install NuGet Packages

There are two NuGet Packages that we are going to need for this demo.

Go back to your console and run:

dotnet add package Microsoft.AspNetCore.SignalR.Client
dotnet add package Nexmo.Csharp.Client

Create the SMS Hub

SignalR disperses all messages through central “Hubs.” A hub will notify all clients connected to it when a particular event occurs; in this case, the events we are going to be receiving are inbound SMS messages.

Create a folder called Hubs. In that folder, create a file called SmsHub.cs and import SignalR with using Microsoft.AspNetCore.SignalR; within it. Then, create a SmsHub class within the ReceiveSmsBlazor.Hubs namespace like so:

namespace ReceiveSmsBlazor.Hubs{ public class SmsHub : Hub { }}

You don’t need to add any code in here; we’ll be driving this from outside of this class, it just needs to be here so that we can talk to all the clients of the Hub.

Build our Controller

We are going to need to create an API controller. This controller is where we are going to be receiving our inbound SMS webhooks from Vonage.

Create a new folder at the top level of our project called Controllers, and add a new file SmsController.cs to this folder.

Open up SmsController.cs and add the following using statements to it.

using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.SignalR;
using Newtonsoft.Json;
using Nexmo.Api.Messaging;
using System.IO;
using System.Threading.Tasks;
using ReceiveSmsBlazor.Hubs;

Next, create a SmsController class in the ReceiveSmsBlazor.Controllers namespace extending Controller and annotate it with a Route to api/[controller] and an ApiController attribute like so:

namespace ReceiveSmsBlazor.Controllers
{
    [Route("api/[controller]")]
    [ApiController]
    public class SmsController : Controller
    {
    }
}

Inject the SmsHub Context

To access the SmsHub, we’ll dependency inject its context. Create an IHubContext<SmsHub> property called HubContext in your SmsController class, then add a constructor taking an IHubContex as an argument, and assign our HubContext property to that value.

IHubContext<SmsHub> HubContext { get; set; }
public SmsController(IHubContext<SmsHub> hubContext)
{
    HubContext = hubContext;
}

Add the Inbound SMS Webhook Action

Now that we have our Hub available, we just need to add a method to handle the inbound SMS and send it to our client.

Add a new async method called InboundSms that returns a Task<IActionResult>. In this method we are going to read the SMS in from the Request’s body, then we are going to send a message out to all of the clients connected to our SmsHub containing the inbound message’s Msisdn (the number the message originated from) and Text.

[HttpPost("[action]")]
public async Task<IActionResult> InboundSms()
{
    using (var reader = new StreamReader(Request.Body))
    {
        var json = await reader.ReadToEndAsync();
        var inbound = JsonConvert.DeserializeObject<InboundSms>(json);
        await HubContext.Clients.All.SendAsync("ReceiveMessage", inbound.Msisdn, inbound.Text);
    }
    return NoContent();
}

If you’ve been following along, the route will look like api/sms/inboundsms on our server when it launches. Keep this in mind for later because this is going to be where we are aiming our webhooks when we are configuring our webhooks.

Configure Middleware in Startup

Since we are using Controllers and SignalR, we need to make sure that we configure the middleware. Open up Startup.cs and add using Microsoft.AspNetCore.ResponseCompression; to the import section. Then drop into the ConfigureServices method and add the following.

services.AddSignalR();
services.AddResponseCompression(opts => {
    opts.MimeTypes = ResponseCompressionDefaults.MimeTypes
        .Concat(new []{"application/octet-stream"});
});

This snippet will add SignalR and response compression for SignalR to your application.

Add Controller and SmsHub

The next thing we need to do is to tell our application to use our controllers and our SmsHub. Drop into the Configure method in Startup.cs and add the line app.UseResponseCompression(); at the beginning of the method. Then, in the UseEndpoints delegate, add endpoints.MapControllers(); and endpoints.MapHub<Hubs.SmsHub>("/smshub");. When it’s all said and done your app.UseEndpoints should look something like this:

app.UseEndpoints(endpoints =>
{
    endpoints.MapControllers();
    endpoints.MapBlazorHub();
    endpoints.MapHub<Hubs.SmsHub>("/smshub");
    endpoints.MapFallbackToPage("/_Host");
});

Add a Frontend

Now that we have all the internal stuff working for handling the inbound SMS and we have all of our services and hubs stood up, the last thing we need to do is to create a frontend.

If you ran dotnet run in your console and opened the app on localhost:5001 you’d see the generic blazor starter page.

If you want to remove the navigation bar on the side just go into Shared/MinLayout.razor and remove the sidebar div.

Everything else we need to do is in Pages/index.razor so go ahead and open that file now.

Pull in Dependencies

Delete everything below line 2 in index.razor as it’s just generic hello world code. With that done, let’s import our SignalR client, inject a navigation manager, and declare that we will implement IDisposable to clean up the SignalR hub when it winds down.

@using Microsoft.AspNetCore.SignalR.Client
@inject NavigationManager NavigationManager
@implements IDisposable

Add our Messages Table

We’re going to display inbound messages in a Table. Let’s go ahead and add a simple table into our index.razor file. Add the following razor code.

<h1>Messages</h1>

<table class="table" id="messageList">
    <thead>
        <tr>
            <th>From Number</th>
            <th>Message</th>
        </tr>
        @foreach (var message in _messages)
        {
            <tr>
                <td>@message.FromNumber</td>
                <td>@message.Text</td>
            </tr>
        }
    </thead>

</table>

The foreach will loop through our page’s _messages collection and create a new row with each message’s FromNumber and Text.

Handle Inbound Messages

Back in our controller, we used the call await HubContext.Clients.All.SendAsync("ReceiveMessage", inbound.Msisdn, inbound.Text); to send the inbound message’s Msisdn and Text down to all clients connected to the SMS hub. Now it’s time to connect to that Hub. I’m going to go ahead and show you the whole @code blob and then walk you through how each part operates.

@code {
    private HubConnection _hubConnection;
    private List<Message> _messages = new List<Message>();
    private class Message
    {
        public string FromNumber { get; set; }
        public string Text { get; set; }
    }
    protected override async Task OnInitializedAsync()
    {
        _hubConnection = new HubConnectionBuilder()
            .WithUrl(NavigationManager.ToAbsoluteUri("/SmsHub"))
            .Build();
        _hubConnection.On<string, string>("ReceiveMessage", (from, text) =>
        {
            var message = new Message { FromNumber = from, Text = text };
            _messages.Add(message);
            StateHasChanged();
        });
        await _hubConnection.StartAsync();
    }
    public bool IsConnected => _hubConnection.State == HubConnectionState.Connected;
    public void Dispose()
    {
        _ = _hubConnection.DisposeAsync();
    }
}

Declare Private Fields and Message Class

The following bit of code declares the private fields of the component. That _messages list is where we are going to be pulling messages.

private HubConnection _hubConnection;
private List<Message> _messages = new List<Message>();
private class Message
{
    public string FromNumber { get; set; }
    public string Text { get; set; }
}

OnInitializedAsync

We override the OnInitializedAsync method; this is the method that is invoked when the component is initialized. This method initializes the _hubConnection (the connection to our SmsHub). It then registers a handler for the ReceiveMessage callback that we are invoking with our SmsController. Thus whenever that event occurs, this method will fire, we’ll add the inbound message to our _messages collection, and then we’ll call the StateHasChanged function to tell the component that it needs to re-render, this will make our messages reload live. Lastly, we start _hubConnection.

Testing with Ngrok

Now that we have everything built, we can go ahead and get testing with ngrok. Ngrok allows us to create a tunnel to our server from our local machine. If you are using ngrok with IIS Express, I will encourage you to check our explainer on the subject as there are special considerations. For this demo, since we are using the dotnet CLI, we don’t need to worry about this. Open up your Properties/launchSettings.json file in the profiles object, the profile named after your app is going to be used when you startup. Check the applicationUrl; it will typically point to https://localhost:5001 and http://localhost:5000. Ensure that you delete the non-SSL one of these and then run the following command in another command prompt window.

ngrok http 5000

Replace 5000 with whatever port number your app is going to be running without SSL.

This command will build a tunnel to that port. You can now run your application by using the dotnet run command. Check back at your ngrok console; it will tell you the publicly accessible URL of your app.

In my case, it’s pointing to http://09c1cd61e26e.ngrok.io/. By navigating to that URL, I can see my application’s frontend.

Configure your Webhooks

The route for inbound sms webhooks is /api/sms/inboundsms with our ngrok URL as the base path. This means that the full route is going to be something along the lines of http://09c1cd61e26e.ngrok.io/api/sms/inboundsms. All we need to do now is navigate to our settings page and set the inbound messages URL to our route, and set the HTTP method to POST-JSON. Click the Save Changes button at the bottom, and we’re good to go.

Test

To test, all we need to do is send a text message to a Nexmo Number associated with this account. That can be found on the dashboard under numbers->Your Number.

It will look something like this after you receive a message.

Wrapping Up

That’s all that’s needed to allow us to watch SMS messages come into an app in real-time. It’s clear that by combining SignalR, Blazor, and the Vonage APIs, we can build some cool stuff!

Resources

The code for this demo can be found in GitHub
You can learn more about the Vonage APIs on our Developer Website

The post How to Receive an SMS With Blazor and SignalR appeared first on Vonage Developer Blog.

How to Send an SMS With Blazor

Steve Lorello — Wed, 08 Jul 2020 14:26:14 +0000

Blazor is the latest in a series of what I’d call “magnificent” developer-friendly web frameworks that .NET has built. In this tutorial, we’ll be reviewing how to send an SMS using Blazor and the Vonage SMS API.

Jump Right to the Code

All of the code from this tutorial is located in GitHub.

Prerequisites

You’ll need a Vonage API account. You can sign up here
You’ll need the latest version of the .NET Core 3.1 SDK
You’ll need either Visual Studio 2019, Visual Studio for Mac, or Visual Studio Code⁠—I will be using VS Code for this demo

Create the App

Navigate to wherever you want to build the app and run the following command in your terminal:

dotnet new blazorserver -o SendSmsBlazor

This will create a blazor server app for you called SendSmsBlazor. cd into this directory and enter the command code . to Launch VS Code. For Visual Studio users, you can just open the sln file.

Add Nexmo Csharp Nuget Package

Fire up a terminal in VSCode and run:

dotnet add package Nexmo.Csharp.Client --version 5.0.0

This will install the Nexmo.Csharp.Client package to the project.

Create Your SmsService

We will have to inject an SMS service into our razor page, so let’s create a SmsService.

Add a new file under the Data folder called SmsService.cs. If you’re using VS Code, this is just going to create a blank file, so add the following to it.

using Microsoft.Extensions.Configuration;
using Nexmo.Api.Messaging;
using Nexmo.Api.Request;
namespace SendSmsBlazor.Data
{
    public class SmsService
    {
    }
}

Add a Constructor

Inside the SmsService class, we must inject a configuration object. The config will contain our API key and API secret, which we’ll configure a bit later. For the moment, all you need to do is add a new property inside the SmsService class called Configuration of type IConfiguraiton and add a Constructor taking an IConfiguration object, which will simply assign our Configuration property to that object.

public IConfiguration Configuration { get; set; }
public SmsService(IConfiguration config)
{
    Configuration = config;
}

Write Your SendSms Method

Inside the SmsService, we’re going to add a SendSms method. That method will take three strings: to, from, and text which will contain the number the message is going to, the Vonage API number the message is coming from, and the text of the message.

All that’s left to do from this service’s perspective is:

Pull the API key and secret out of the configuration
Create a SmsClient
Send the SMS

All of this can be accomplished with the following:

public SendSmsResponse SendSms(string to, string from, string text)
{
    var apiKey = Configuration["VONAGE_API_KEY"];
    var apiSecret = Configuration["VONAGE_API_SECRET"];
    var creds = Credentials.FromApiKeyAndSecret(apiKey,apiSecret);
    var client = new SmsClient(creds);
    var request = new SendSmsRequest
    {
        To= to,
        From = from,
        Text = text
    };
    return client.SendAnSms(request);
}

Configure SmsService as Injectable

Now that we have the service built, we need to make sure that we can inject it into our razor page. To do this, we need to go into Startup.cs and find the ConfigureServices function. Add the following line to the end of this function, and the service will be injectable:

services.AddSingleton<SmsService>();

Add Frontend

We’re going to use the Pages/Index.razor for our frontend, so just open it up and delete everything below line 2.

Dependency Inject SmsService

The first thing we need to do here is pull in our SmsService. To that end, add a using and an inject statement, like so:

@using SendSmsBlazor.Data@inject SmsService SmsService

Add C# Code to Send the Message

One of the really neat things about Blazor is that it allows you to run C# code in the browser—all we need is an @code{} block, and we’re good to go. By doing this we are making an anonymous class in-line, so we will add a To, From, Text, and MessageId to this anonymous class and add a method called SendSms which will actually call our SmsService. This is going to look like this:

@code{
    private string To;
    private string From;
    private string Text;
    private string MessageId;
    private void SendSms()
    {
        var response = SmsService.SendSms(To, From, Text);
        MessageId = response.Messages[0].MessageId;
    }
}

Add Input Fields and Send Button

Now that we have all this out of the way, we’re going to add a few input fields. The To, From, and Text fields will be populated by binding them to these input fields with the @bind attribute. At the bottom, just above the button, we will display the sent MessageId by referencing it in a paragraph tag. Finally, we’ll add a button to the bottom that will call the SendSms button in our anonymous class when clicked. Add the following between the @code block and the @inject block:

<h1>Send an SMS!</h1>

Welcome to your new app Fill out the below form to send an SMS.
<br />
to:
<input id="to" @bind="@To" class="input-group-text" />
from:
<input id="from" @bind="From" class="input-group-text" />
text:
<input id="text" @bind="Text" class="input-group-text" />
<p>@MessageId</p>
<button class="btn btn-primary" @onclick="SendSms">Send SMS</button>

Configure the App

The last thing we must do before running our server is to configure it. If you’ll recall, you set an IConfiguration object in the SmsService. All you need to do is open appsettings.json and add two properties to the configuration VONAGE_API_KEY and VONAGE_API_SECRET. Set those to the API key and API secret values in the Dashboard.

Running our app

With all this done, just return to your terminal and run the following command.

dotnet run

Your application will tell you what port it’s listening on—for me it’s port 5001, so I’d navigate to localhost:5001, fill out the form, and hit SendSms. You’ll see the SMS on the number you sent to, with the Message-ID from the SMS appearing just below the text field.

Resources

The code for this demo can be found in GitHub.

The post How to Send an SMS With Blazor appeared first on Vonage Developer Blog.

Validating Inbound Messages From the Vonage Messages API

Steve Lorello — Mon, 06 Jul 2020 14:34:54 +0000

An Introduction to Webhooks

The Vonage Messages API is phenomenal. I know as advocates we aren’t meant to play favorites, but it is actually my favorite of the Vonage APIs. It enables you to send messages over WhatsApp, Facebook Messenger, Viber, SMS, and MMS very easily. And at other end, it allows you to receive messages over most of those channels (SMS messages are sent back to your account level endpoints).

For your application to receive an inbound message (or the status of an outbound message) from Vonage, your application must have a publicly accessible HTTP endpoint that Vonage can send the message to. This message is called a webhook. We tend to see lots of questions around security and webhooks, so I’m going to show you how you can secure your Messages webhooks. We’re going to accomplish this with a combination of bearer auth and payload validation.

Concerns Around Webhook Security

The biggest question we get surrounding webhooks, beyond what they are, is how to secure webhooks to make sure bad actors aren’t sending malicious webhooks. What can an attacker do if they gain access to our webhook endpoints and have a critical mass of user data to throw at us? It’s a valid concern.

Think about it like this: Alice is an application developer, and she needs to receive a WhatsApp message from Bob. Bob will send a WhatsApp message to Alice’s application. When that WhatsApp message is received, Vonage will send a message to Alice’s HTTP endpoint to notify her application about the inbound message. That endpoint must be publicly available. If Chuck, a malicious hacker, finds Alice’s webhook endpoint, he can now impersonate Bob for incoming messages or falsify statuses about outbound messages.

Authenticate Inbound Webhooks

Vonage uses JSON Web Token (JWT) Bearer Authorization for webhooks sent from the Messages API to allow you to easily authenticate the webhook. The bearer token is an HMAC-SHA256 token, meaning verifying the JWT’s validity is as simple as decoding the token with its signing secret. The secret you need to use is the same secret shown in the settings page in the dashboard. It is recommended that this signing secret be at least 32 bits to make it difficult to brute-force attack. Your account’s signature secret is a shared secret between you and Vonage.

_ Note: This feature is not yet available for Messenger webhooks._

Validate the Payload of an Inbound Webhook

In addition to authorizing the token, it’s a good idea to check that the payload of the webhook matches what the token says it should be. JWTs, once decoded, have their own JSON payload—the fields in this JSON are referred to as claims. To guard against an attacker potentially stealing one of your tokens and replaying it, you can use one of these claims, the payload_hash. The payload_hash is an SHA-256 hash of the payload of the webhook. Just by running the payload of the incoming message through an SHA-256 hash and comparing it to the payload_hash claim in the webhook, you can be sure that the token that you are receiving is not a replay.

Check the Time a Token was Generated

Another important claim is the iat—this stands for “issued at,” and it is the UTC Unix timestamp of when the token was generated. You can compare the iat to the current UTC Unix timestamp to check how old the time stamp is in order to guard against potentially stale tokens.

Translate to Code

Let’s take these concepts and convert them to code. I’m going to show you how to do this in Node.js, but these techniques are available in virtually every programming language.

Vonage API Account

Gather Dependencies

Create a new directory called signed_webhooks and cd into it. In this directory, run npm install dotenv jsonwebtoken js-sha256 express body-parser.

Create Files and Add Configuration

In our signed_webhooks directory, we’re going to create a server.js and a .env file. The server.js file is where our server code is going to go and our .env file is where our configuration is going to live. In the .env file, add just one field, NEXMO_API_SIGNATURE_SECRET, and set that to the signature secret from your dashboard settings page.

Initialize Dependencies

Now that we’ve gathered all of our dependencies and configured our server, we need to add the server code. Let’s start by initializing our dependencies. Add the following to server.js:

require('dotenv').config();
const jwt = require("jsonwebtoken");
const sha256 = require('js-sha256');
const app = require('express')();
const bodyParser = require('body-parser');
const NEXMO_API_SIGNATURE_SECRET = process.env.NEXMO_API_SIGNATURE_SECRET;
if(!NEXMO_API_SIGNATURE_SECRET){
    throw "Missing Signature Secret";
}

This code will bring in all of our dependencies and pull in the signature secret from our environment.

Add Inbound Message Route

Next, we need to set up the route for inbound-message and status. We’ll assume the webhooks we’re receiving are going to be POST requests, so we will add a route to /webhooks/inbound-message and /webhooks/status and and set up POST requests to be routed through our handleWebhook function.

app.use(bodyParser.json())
app.use(bodyParser.urlencoded({
  extended: true
}))
app
    .route('/webhooks/inbound-message')
    .post(handleWebhook);
app
    .route('webhooks/status')
    .post(handleWebhook)

Handle Inbound Messages

When we get an inbound message, we’ll pull the body out and add it to the payload. Then we’ll split the authorization header on whitespace (the authorization header will be of the form “Bearer Token”, so splitting on the white space and taking the token portion will give us the JWT).

With the token retrieved, we can decode the JWT using our signature secret. As we discussed earlier, this decoding action is tantamount to validating the authenticity of the token. If the JWT is not valid or the auth header is malformed, an exception will be raised by the decoding operation, and we will return a 401. If we’re able to decode the token, we have verified the token’s authenticity—thus, if you’re behind TLS and don’t care to validate the payload, you can safely return a 200 at this point. If, however you choose to verify the payload, it’s as simple as running a JSON.stringify on the payload and comparing it to the payload_hash claim of the decoded JWT. If you detect tampering, you can return a 401 from the endpoint to tell folks they aren’t authorized. Finally, we are going to tell our app to listen on a specified port or on port 3000.

All of this is accomplished in the following handleWebhook request:

function handleWebhook(request, response){
    const payload = Object.assign(request.query, request.body)
    try{
        let token = request.headers.authorization.split(" ")[1]
        var decoded = jwt.verify(token, NEXMO_API_SIGNATURE_SECRET, {algorithms:['HS256']});
        if(sha256(JSON.stringify(payload))!=decoded["payload_hash"]){
            console.log("tampering detected");
            response.status(401).send();
        }
        else{
            console.log("Success");
            response.status(204).send();
        }
    }
    catch(err){
        console.log('Bad token detected')
        response.status(401).send()
    }
}
app.listen(process.env.PORT || 3000)

Testing

For testing purposes, we are just going to run locally. Starting the server is simple: run node server.js, and the server will boot up.

Set Up ngrok

To route webhooks to our server, we are going to use ngrok. Ngrok lets us create a tunnel for our local server. Run the following command.

ngrok http 3000

That will bring up an ngrok session that will look like http://random.ngrok.io—swap out random with whatever the random hash is at the beginning of the URL, then add the route to /webhooks/inbound-message and you will have the URL for your webhooks.

Configure Webhooks

Now that we have a tunnel to our server, the last thing we need to do before we receive messages is to configure our webhooks. For testing purposes, you may want to use the Messages API sandbox—instructions can be found in Martyn’s blog post on the subject or the Messages API Sandbox docs.

For production, you will need to configure your application’s webhooks. You can do this at https://dashboard.nexmo.com/applications/:appid/edit, replacing :appid with your application id. You can also set them with the Nexmo CLI or the Application API.

After editing, your application’s webhook configuration for messages should look like this:

Now that everything is configured, we can test—send a message to either your WhatsApp, Viber, or Facebook Messenger number, and your server will validate the inbound webhooks!

Validating Inbound SMS

Validating inbound SMS is outside of the scope of this post, but we do have a similar methodology for validating inbound SMS messages. You can read about how in our Developer Documentation.

Resources

The code from this post is available on GitHub.
A more detailed explainer on how JWT Authentication works is available in our developer docs.
If you have a JWT you want to manually decode, you can easily do that with jwt.io’s decoder.

The post Validating Inbound Messages From the Vonage Messages API appeared first on Vonage Developer Blog.

Create a Basic Video Chat App with ASP.NET and Angular

Steve Lorello — Fri, 08 May 2020 10:38:00 +0000

Angular is by far the most popular single-page application (SPA) framework used by .NET developers. Until this project, I hadn't used Angular since before it dropped the JS from its name. Consequentially, I was excited to try my hat at it again, this time using it to show off Vonage's Video API. You can follow along in this tutorial, where we'll be creating a basic video chat application using Angular (though it'll always have the JS in my ❤).

Prerequisites

Visual Studio (I’m using 2019, though older versions ought to work)
.NET Core 3.1 developer kit
A Vonage Video API account
A Vonage Video API project, which can be created from your account page

Straight to the Code

If you just want to pull the code for this walk-through down, visit the GitHub page for this blog post, follow the instructions, and you'll be all set.

First Things First

Let's start by opening Visual Studio. Click Create a new project -> ASP.NET Core Web Application -> give it a name (I'm calling mine BasicVideoChatAngular) -> Create -> Angular.

Doing this is going to build you a shell ASP.NET application with all of your client-side code under the ClientApp folder.

Import Nuget Packages

Import the following NuGet packages for this project:

OpenTok
Microsoft.EntityFrameworkCore.SqlServer (I'm using 3.1.3)

Create the Entity Model

We're going to use some very basic Entity Framework here. Add a Model.cs file to the project. Delete the Class declaration and add the following code to it:

public class OpentokContext : DbContext
{
    public DbSet<Room> Rooms { get; set; }
    protected override void OnConfiguring(DbContextOptionsBuilder options)
        => options.UseSqlite("Data Source=VonageVideo.db");
}
public class Room
{
    public int RoomId { get; set; }
    public string SessionId { get; set; }
    public string RoomName { get; set; }
    public string Token { get; set; }
}

You'll also need to add the following to your using section:

using Microsoft.EntityFrameworkCore;

Create the Database

With that added, let's create the database. Navigate to your project folder and execute the following:

dotnet tool install --global dotnet-ef
dotnet add package Microsoft.EntityFrameworkCore.Design
dotnet ef migrations add InitialCreate
dotnet ef database update

This will create a database file that will hold your rooms and sessionIds.

Create a Session Controller

Right click the Controllers folder -> Add -> Controller - MVC Controller - Empty -> name it SessionController.

In the SessionController, dependency inject an IConfiguration object, and create an elementary form class to hold our room name called RoomForm:

private IConfiguration _Configuration;
public SessionController(IConfiguration config)
{
    _Configuration = config;
}
public class RoomForm
{
    public string RoomName { get; set; }
}

After this, add a HttpPost request called GetSession that takes a RoomForm as an argument:

[HttpPost]
public IActionResult GetSession([FromBody]RoomForm roomForm)
{
    var apiKey = int.Parse(_Configuration["ApiKey"]);
    var apiSecret = _Configuration["ApiSecret"];
    var opentok = new OpenTok(apiKey, apiSecret);
    var roomName = roomForm.RoomName;
    string sessionId;
    string token;
    using (var db = new OpentokContext())
    {
        var room = db.Rooms.Where(r => r.RoomName == roomName).FirstOrDefault();
        if (room != null)
        {
            sessionId = room.SessionId;
            token = opentok.GenerateToken(sessionId);
            room.Token = token;
            db.SaveChanges();
        }
        else
        {
            var session = opentok.CreateSession();
            sessionId = session.Id;
            token = opentok.GenerateToken(sessionId);
            var roomInsert = new Room
            {
                SessionId = sessionId,
                Token = token,
                RoomName = roomName
            };
            db.Add(roomInsert);
            db.SaveChanges();
        }
    }
    return Json(new { sessionId = sessionId, token = token, apiKey = _Configuration["ApiKey"] });
}

This method checks the database to see if the roomName already has a sessionId. If it does, it generates a token for that sessionId. If not, it makes a new session and token. Then, it creates a new row in the database for that room. In both cases, it returns a sessionId, token, and ApiKey as JSON.

Build the Client

With the back end out of the way, let's get down to building the client. We're going to have two primary views—our Join view, where the user will input the room name they would like to join:

And a Video view that will contain the video call:

Install npm Dependencies

First things first, navigate to the ClientApp directory in your terminal and run:

npm install --save @opentok/client

Clean Out Demo Views

When you create an Angular project in Visual Studio, a bunch of demo components are auto-populated under ClientApp\src\app, including counter, fetch-data, home, and nav-menu. We aren't going to need any of these, so let's just delete them all from the jump.

Add Needed Files

Create the following folders/files:

Under ClientApp\src add config.ts
Under ClientApp\src\app add stateService.ts
Under ClientApp\src\app create directories: join, subscriber, video
Under ClientApp\src\join create join.component.css, join.component.html, join.component.ts
Under ClientApp\src\subscriber create subscriber.component.html, subscriber.component.ts, subscriber.component.css
Under ClientApp\src\video create video.component.css, video.component.html, video.component.ts

Build Out the Config

In ClientApp\src\config.ts, we are going to set up our configuration, which contains one field, SAMPLE_SERVER_BASE_URL. Set this to the base URL you end up using for IIS—the file should look like:

export default {
    SAMPLE_SERVER_BASE_URL: 'https://localhost:44340'
}

If you are using IIS Express to debug, find the base_url by right-clicking on your project file -> Properties -> Debug, and at the bottom you'll see the IIS URLs.

Build Out the StateService

We are going to have a transition between components after we click the Join button. We'll need to carry the token, sessionId, and ApiKey between the Join component and the Video component so that the Video component can join the call. To solve this problem, we're going to share this state using a state service—we'll inject the state service into the next component as we transition between them. We just need an Injectable to accomplish this with some observable fields:

import { Injectable } from "@angular/core";
@Injectable({providedIn:'root'})
export class StateService {
    public token$: string;
    public sessionId$: string;
    public apiKey$: string;
    constructor() {}
}

Note: At this stage, you might get an IntelliSense error "Experimental support for decorators is a feature that is subject to change in a future release. Set the 'experimentalDecorators' option to remove this warning." To resolve this, you need to set the build action of ClientApp\tsconfig.json file to Content, and you may need to restart Visual Studio.

Build the Subscriber Component

The Subscriber component will be the component responsible for holding the incoming video stream. To build this, remove all the pre-added HTML from subscriber.component.html and add this line:

<div class="subscriber-div" #subscriberDiv></div>

It will only hold a div, which will serve as the target for the incoming stream.

Now in subscriber.component.css, add a couple styles:

.subscriber-div {
  height: 100%;
  width: 100%;
  position: fixed;
  top:50px;
  bottom: 0;
  left: 0;
  z-index: 0;
}
.container {

  background: black;
  color: white;
  height: 100%;
}

This CSS will make the component take up the full screen and will push it to the bottom of the z-index, which will prevent it from overtaking the publisher's video, which will appear as a PIP in the bottom.

In the subscriber.component.ts file, we're going to create a component with a session and stream input. It also needs an element reference to the SubscriberDiv from the HTML template, as well as a session and stream that we'll be getting from the video component. Finally, it needs a subscribe method to subscribe to a session stream when the onStreamCreate event fires. Add the following code to the file:

import { Component, ElementRef, ViewChild, Input } from '@angular/core';
import *  as OT from '@opentok/client';
@Component({
  selector: 'app-subscriber',
  templateUrl: './subscriber.component.html',
  styleUrls: ['./subscriber.component.css']
})
export class SubscriberComponent {
  @ViewChild('subscriberDiv', { static: true }) subscriberDiv: ElementRef;
  @Input() session: OT.Session;
  @Input() stream: OT.Stream;
  constructor() { }
  subscribe(): void {
    const subscriber = this.session.subscribe(this.stream, this.subscriberDiv.nativeElement, {
      insertMode: "append",
      width: "100%",
      height: "100%"
    }, (err) => {
      if (err) {
        alert(err.message);
      }
    });
  }
}

Build the Video Component

Let's start with the video.component.html file. First delete any auto-generated html added to this file. Then add the template:

<div class="publishingDiv" [ngClass]="{'publishing': publishing}" #publisherDiv></div>
<div>  
  <ng-template #subscriberHost></ng-template>
</div>

The publishingDiv will be the anchor in the DOM that we are going to be using for our publisher's video feed. The subscriberHost template is going to be where our subscriber is added when a subscriber joins a call. In the CSS file, let's drop any auto-generated CSS. Add styles that will set the publishingDiv to the bottom left-hand corner of the screen in a fixed position, take up 25% of the the height and width of the window, and sit at a z-index of 1 (immediately above where we put our subscriberDiv). Add the following to the video.component.css file:

.publishingDiv {
  height: 25%;
  width: 25%;
  left: 0;
  bottom: 0;
  position: fixed;
  z-index: 1;
}

Finally, we need to set up the component itself. Remember the StateService from earlier? We are going to be injecting it; from it, we'll be getting the sessionId, token, and ApiKey from the SessionController we created earlier.

Imports and Dressing the Component

First, import all the stuff we're going to need and build the VideoComponent class.

import { ViewContainerRef, Component, ElementRef, AfterViewInit, ViewChild, ComponentFactoryResolver, OnInit } from '@angular/core';
import * as OT from '@opentok/client';
import { SubscriberComponent } from '../subscriber/subscriber.component';
import { StateService } from '../stateService';
import { Router } from '@angular/router';
@Component({
  selector: 'app-video',
  templateUrl: './video.component.html',
  styleUrls: ['./video.component.css']
})
export class VideoComponent implements AfterViewInit, OnInit {
}

Component Fields and Constructors

Next, set up some fields for the VideoComponent class and constructor. In the constructor, we inject a ComponentFactoryResolver, which we use to grab the subscriberHost's native reference later, and the StateService, which is where we're going to pull our apiKey, token, and sessionId. The Router will help us route between components in our project; specifically, you'll need it to navigate back to the join controller if the state service doesn't contain an apiKey, token, or sessionId.

Inside the VideoComponent class add the following:

@ViewChild('publisherDiv', { static: false }) publisherDiv: ElementRef;
@ViewChild('subscriberHost', { read: ViewContainerRef, static: true }) subscriberHost: ViewContainerRef;
session: OT.Session;
publisher: OT.Publisher;
publishing;
apiKey: string;
token: string;
sessionId: string;
constructor(
  private componentFactoryResolver: ComponentFactoryResolver,
  private stateService: StateService,
  private router: Router
) { }

On Init Logic

Next, we'll set up the ngOnInit function. The StateService is injected immediately upon init, so that's where we're going to grab the apiKey, token, and sessionId. This function is going to store those items. If any of them don't exist, we're going to reroute to the Join page.

ngOnInit(): void {
  if (!this.stateService.apiKey$ || !this.stateService.token$ || !this.stateService.sessionId$) {
    this.router.navigate(['/']);
  }
  this.apiKey = this.stateService.apiKey$;
  this.token = this.stateService.token$;
  this.sessionId = this.stateService.sessionId$;
}

Publish the User's Stream

Next, we'll set up the publish method. We're going to call this after the view finishes initializing. This function will call the session's publish method, passing in the publisher element. It will transition the publishing field to true when the callback resolves. Add the following after ngOnInit:

publish() {
    this.session.publish(this.publisher, (err) => {
      if (err) {
        console.log(err)
      }
      else {
        this.publishing = true;
      }
    });
  }

Handle a Stream's Creation

Upon stream creation, we'll need to subscribe to it. The way we'll manage this is by grabbing the reference to that subscriber template we created in the HTML, initializing a Subscriber component for it, assigning the stream and session Id to it, and telling it to subscribe. Add the following after the publish method:

onStreamCreated(stream) {
  const componentFactory = this.componentFactoryResolver.resolveComponentFactory(SubscriberComponent);
  const viewContainerRef = this.subscriberHost;
  const componentRef = viewContainerRef.createComponent(componentFactory);
  (<SubscriberComponent>componentRef.instance).stream = stream;
  (<SubscriberComponent>componentRef.instance).session = this.session;
  (<SubscriberComponent>componentRef.instance).subscribe();
}

Set Up the Publisher

After the view has been initialized, ngAfterViewInit fires. At this point in the controller's life cycle, we have everything we need to get us into the video call. We're going to initialize the publisher, initialize the session, connect to the session, and in the callback after we connect to the session we're going to tell our stream to publish. We're also going to subscribe to the streamCreated event, which is going to call the onStreamCreated function that we made earlier. Add the following ngAfterViewInit function:

ngAfterViewInit(): void {
  this.publisher = OT.initPublisher
    (
      this.publisherDiv.nativeElement, {
      height: "100%",
      width: "100%",
      insertMode: 'append'
    });
  this.session = OT.initSession(this.apiKey, this.sessionId);
  this.session.connect(this.token, (err) => {
    if (err) {
      console.log(err);
    }
    else {
      console.log("connected");
      this.publish()
      let that = this;
      this.session.on("streamCreated", function (event) {
        that.onStreamCreated(event.stream);
      });
    }
  })
}

Build the Join Component

With the video component built, we just need to set up the join component and the app module.

Setup the Html

In the join.component.html file we're going to create a joinForm, which will only have one input, a roomName, which we are going to use to grab/generate the sessionId's and tokens. The template for the component is going to look like this:

<form class="joinForm" [formGroup]="joinRoomForm" (ngSubmit)="onSubmit(joinRoomForm.value)">
  <div>
    <input placeholder="room name" id="roomName" type="text" formControlName="roomName" align="center">
  </div>
  <button align="center" class="button" type="submit">Join</button>
</form>

Add Some Styles

We're not going to do anything too fancy with the styles here—we're just going to make sure that button and the input are centered and are the same size. Add the following to join.component.css:

form {
  display: normal;
  text-align: center;
  margin: auto;
}
input {
  display: inline-block;
  font-size: inherit;
  padding: .5em;
  margin-bottom: .2em;
  width: 300px;
}
button {
  display: inline-block;
  font-size: inherit;
  padding: .5em;
  width: 300px;
}

Build the Component

The join component is going to have a submission function for the join form, which is going to grab the session data from our back end and route the session data over to the video component via the state service. To do this, it will bring in the HttpClient, FormBuilder, StateService, and Router services through dependency injection, then build the room form. Next it will wait for an onSubmit from joinRoomForm, at which point it will post the roomName to the session controller, and use that response to build the Video component.

import { Component } from '@angular/core';
import { Router } from '@angular/router';
import { FormBuilder } from '@angular/forms';
import { HttpClient } from '@angular/common/http';
import config from '../../config';
import { StateService } from '../stateService';
@Component({
  selector: 'app-join',
  templateUrl: '/join.component.html',
  styleUrls: ['/join.component.css']
})
export class JoinComponent {
  joinRoomForm;
  constructor(
    private http: HttpClient,
    private formBuilder: FormBuilder,
    private stateService: StateService,
    private router: Router) {
    this.joinRoomForm = this.formBuilder.group({
      roomName: ''
    });
  }
  onSubmit(roomData) {
    let get_session_url = config.SAMPLE_SERVER_BASE_URL + '/session/getSession'
    this.http.post(get_session_url, roomData).subscribe(
      (res) => {
        this.stateService.token$ = res['token'];
        this.stateService.sessionId$ = res['sessionId'];
        this.stateService.apiKey$ = res['apiKey'];
        this.router.navigate(['/video'])
      }
    )
  }
}

Set Up the App

Before any of our Angular will work, we're going to have to set up the whole app module. We'll start by setting up the base HTML. In ClientApp\src\app\app.component.html, I added a title above the router-outlet, which guarantees that the title will display on our child pages. Also make sure you remove the <app-nav-menu></app-nav-menu>, as that pre-exists from the originally built template:

<body>
  <div class="container">
    <b><p style="font-size: 34px; text-align:center">Basic Angular Video Chat</p></b>
    <router-outlet></router-outlet>
  </div>
</body>

Next, in ClientApp\src\app\app.module.ts, we need to define our module, which means adding the new components that we created, removing the components that we removed at the very beginning, and establishing the routes that we are going to want to use. Add the components as imports, and then in the declarations field make sure you have the HttpClientModule, FormsModule, ReactiveFormsModule, and RouterModule in your import section. SubscriberComponent will be an entry component. The routes will look as follows: '' -> JoinComponent, video -> VideoComponent, subscriber -> SubscriberComponent.

Configure your App.

You have to set up configuration in two places, config.ts and appsettings.json. You should have set up config.ts earlier, so I won't go over that again. For appsettings.ts, just add apiKey and apiSecret as fields and populate with the ApiKey and ApiSecret from your Vonage Video API account. The file will look something like this:

{
  "Logging": {
    "LogLevel": {
      "Default": "Warning"
    }
  },
  "AllowedHosts": "*",
  "ApiKey": "",
  "ApiSecret": ""
}

With that, you should be all set! I did run into some issues with Angular versioning when I built the demo app the first time—feel free to borrow my package.json file from GitHub.

Testing

All you need to do to test is fire it up in IIS Express—hit the Debug button or press f5 in Visual Studio. Doing this launches the Join page. Enter a room name, and you'll join a new session associated with that room. You can have another endpoint navigate to that same endpoint and join the same room, and they will join with you in the room.

Wrapping up

Now that you have a basic shell of a video chat application in Angular, you can explore doing so much more with the Vonage Video APIs. You can record sessions, share your media, stream your video calls, and much more!

Resources

Check out our documentation for the Vonage Video Api here
The code for this blog post is on GitHub

Real-Time Face Detection in .NET with OpenTok and OpenCV

Steve Lorello — Wed, 18 Mar 2020 20:49:00 +0000

Computer Vision is my favorite field in computer science. It combines my four favorite subjects—Programming, Linear Algebra, Probabilities, and Calculus—into something practical and powerful. In this article, we’re going to look at one cool application of Computer Vision, face detection, and integrate this feature into an OpenTok Windows Presentation Framework(WPF) App.

Baseline

To help us get started, we’ll be working off of the CustomVideoRender OpenTok sample. Right now this sample adds a shade of blue to your video frame when you toggle the filter on. We are going to remove that blue shading and add face detection to the renderer instead. And if you believe it, that facial detection feature is going to be about 30 times faster than the blue filter. To accomplish this feat we are going to apply the Viola-Jones method for feature detection using Emgu CV.

Just Give Me the Code

If you don’t feel like running through this whole tutorial you can find a working sample in GitHub. Just make sure you swap out the parameters as instructed in the Quickstart Guide from the main samples repo

A Brief Overview of Viola-Jones

I won’t dive too deeply into how the Viola-Jones method works, but for those interested, here’s some brief context. The crux of the Viola-Jones algorithm is three-fold. First, it uses something called Haar-like features, which might look like silly black and white shapes.

But in reality, they are actually detectors for very simple features that can tell us a lot about the relative shading of an image:

When overlaid onto an image the sum of the white region is subtracted from the sum of the black region, effectively telling us the shading difference between the regions. Those calculations, when cascaded over many features, can give us a good idea of where in an image a face might be. As these features are so simple, they are scale-invariant meaning they can find faces in an image regardless of how big or small.

This method does an excellent job detecting faces in an image, but if not for the paper’s last major innovation, this method would be cripplingly slow, rather than lighting fast. They introduced the concept of an integral image—an integral image is an image where each pixel is set to the sum of the region above and to the left of the pixel. By computing this on an input image we are able to perform calculations on Haar-like features with a time complexity of O(1) rather than O(N*M) where N & M are the height and width respectively of the Haar-like feature. This makes the combinatorics not only work but work well in our favor as we’re trying to build a face detector that operates rapidly.

Prerequisites

Visual Studio – I’m using 2019, though older versions ought to work
Minimum .NET Framework 4.6.1 – you can use as far back as 4.5.2, but you’ll have to use EmguCV instead of Emgu.CV for your OpenCV NuGet package.
CustomVideoRenderer Sample – this is the sample we will be adapting.
An OpenTok account – if you don’t have one sign up here.
An API Key, Session ID, and Token from your OpenTok account – see the Quickstart guide in the repo for details.

Getting Started

Upgrade to 4.6.1

First, let’s open up the CustomVideoRenderer solution file. In MainWindow.xaml.cs put your credentials in if you haven’t already. Then upgrade the csproj to target the .NET Framework 4.6.1.

To do this open the solution in Visual Studio, right-click on the project file, and click ‘properties’. Then in the Application tab change the target framework to 4.6.1.

Add NuGet Packages

Next, add the following NuGet packages on top of what’s already in the app:

Emgu.CV.runtime.windows – I’m using 4.2.0.3662
WriteableBitmapEx – I’m using 1.6.5

Grab the Haar-like Features

Grab the following two files from OpenCV:

haarcascade_frontalface_default.xml
haarcascade_profileface.xml

Put these files alongside your project and set them to be copied down to your build directory when it’s built. This may involve setting a post-build event if your Visual Studio instance is as uncooperative as mine:

copy $(ProjectDir)\haarcascade\_profileface.xml $(ProjectDir)$(OutDir)
copy $(ProjectDir)\haarcascade\_frontalface\_default.xml $(ProjectDir)$(OutDir)

At this point, you should be able to fire the app up and connect to a call. Since Windows stops you from having your camera accessed by more than one application at the same time you may need to join the call from another computer using the OpenTok Playground

Now if we connect our call it should look something like this in the Windows App:

And if we toggle the filter button on it’ll look more like:

What’s Happening So Far

So far all that’s happening is if you click the ‘toggle filter’ button the app will apply a tint of blue to every frame that comes into the renderer.

How Does This Happen

Rather than using the standard VideoRenderer, we are creating our own custom renderer, SampleVideoRenderer, which extends Control and implements OpenTok’s IVideoRenderer. That interface is fairly simple: it has one method, RenderFrame, which we are taking the frame from and drawing onto a bitmap in the control. This allows us to intervene whenever a frame appears, apply what we want to it, and have it render.

Adding Computer Vision

So with this Custom Renderer, we have all we need to get started with adding the CV to our app. Let’s open SampleVideoRenderer.cs and before we do anything else add the following imports:

using Emgu.CV;
using Emgu.CV.Structure;
using System.Diagnostics;
using System.Drawing;
using System.Collections.Concurrent;
using System.IO;
using System.Threading;

While you’re here, rename EnableBlueFilter to DetectingFaces (make sure you use your IDE’s rename feature) and make it a public get, private set property rather than a public field like so:

public bool DetectingFaces { get; private set; }

This will break some things, but it should become apparent soon how to fix them. For now, we’re going to press onwards.

Constants

Add the following constants to your Renderer:

private const double SCALE_FACTOR = 4;
private const int INTERVAL = 33;
private const double PIXEL_POINT_CONVERSION = (72.0 / 96.0);

The SCALE_FACTOR is the scale we are going to scale the images down to for processing—4 means we will be resizing the images to a quarter of the size before running detection. The INTERVAL is the number of milliseconds between images we’ll attempt to capture from the stream. 33 is approximately the number of milliseconds between frames in a 30FPS stream, so the parameter as-is means it is running at full speed. The PIXEL_POINT_CONVERSION is the ratio of pixels per point on a 96 DPI screen (which is what I’m using). Naturally, this can be better calculated when we’re factoring for DPI awareness, but we are going to use that ratio as gospel for now. We only need this because for whatever reason the Bitmap Extensions library we’re using seems to like to draw X in points and Y in pixels 🤷‍♂️.

Create Our Classifiers

I briefly discussed how Haar-like features worked earlier, but for a more in-depth look at them feel free to check out the Viola-Jones paper. The great thing about OpenCV (and EmguCV by extension) is just how much of this is abstracted away from us.

Now continuing on with our SampleVideoRenderer. Go down and add two static CascadeClassifiers as fields:

static CascadeClassifier _faceClassifier;
static CascadeClassifier _profileClassifier;

Then in the constructor initialize them with their respective files:

_faceClassifier = new CascadeClassifier(@"haarcascade_frontalface_default.xml");
_profileClassifier = new CascadeClassifier(@"haarcascade_profileface.xml");

These XML files describe the Haar’s Features to the classifier well enough to train it. So at this point, we have trained the classifier!

Now Lets Classify

Some Necessary Structures

While we are classifying, we are not going to want to block the main thread. So we are going to be implementing the producer-consumer pattern. We’re going to use BlockingCollections. Specifically, we’re going to be using a ConcurrentStack, because the most relevant and most recent frames are one and the same. Add the following fields to our class:

private System.Drawing.Rectangle[] _faces = new System.Drawing.Rectangle[0];
private BlockingCollection<Image<Bgr, byte>> _images = new BlockingCollection<Image<Bgr, byte>>(new ConcurrentStack<Image<Bgr, byte>>());
private CancellationTokenSource _source;private Stopwatch _watch = Stopwatch.StartNew();

The _faces array is going to contain the faces we’ve detected with our classifier, whereas the _images collection, initialized with a ConcurrentStack, is going to be the LIFO collection of images we are going to be processing. The CancellationTokenSource is what we are going to use to pull ourselves out of the processing loop when the time comes. The Stopwatch is going to serve as our timekeeper gating us from trying to detect on frames too rapidly.

Processing Loop

Now let’s implement our processing loop. Add the following method to your code:

private void DetectFaces(CancellationToken token)
{
    System.Threading.ThreadPool.QueueUserWorkItem(delegate
    {
        try
        {
            while (true)
            {
                var image = _images.Take(token);
                _faces = _faceClassifier.DetectMultiScale(image);
                if(_faces.Length == 0)
                {
                    _faces = _profileClassifier.DetectMultiScale(image);
                }
                if (_images.Count > 25)
                {
                    _images = new BlockingCollection<Image<Bgr, byte>>(new ConcurrentStack<Image<Bgr, byte>>());
                    GC.Collect();
                }
            }
        }
        catch (OperationCanceledException)
        {
            //exit gracefully
        }
    }, null);
}

A lot is going on in this method. First, we are going to run the operation on one of the ThreadPool’s available Daemons. Then, we’re going to process in a tight loop. We call Take on the blocking collection to pull an image off the stack. This Take call will block if there is nothing in the collection, and when we signal the cancel it will throw an OperationCanceledException, which we catch below, breaking us out of the loop gracefully. With the image, it will assign the _faces collection to the result of DetectMultiScale, which is the face detection method. If that doesn’t find anything will try again with the profile face classifier.

When all this is done we check the images collection to see if it’s over some limit (we’re just using 25 as an example here). If it exceeded that, because the classifier has fallen behind, we are going to clear out the collection by re-instantiating it, and then we are going to tell the Garbage Collector to come through and collect those images. Why call the garbage collector? Well, that’s the topic of a different blog post, but essentially if your objects are too large (above 85,000 bytes), it’s pushed off onto the Large Object Heap, which is assigned a lower priority by the garbage collector than other objects (since it’s fairly computationally expensive to release the memory). What this means in practice is if you are dealing with large objects relatively rapidly you may want to make sure they’re cleaned up or you’ll get a hefty memory usage.

Now if you follow my performance guidelines below, you’ll never need to hit that code, but I’m leaving it in just so when folks are tuning they don’t see massive spikes in memory usage.

Toggling the Detection Loop

Now add the following code to your Renderer:

public void ToggleFaceDetection(bool detectFaces)
{
    DetectingFaces = detectFaces;
    if (!detectFaces)
    {
        _source?.Cancel();
    }
    else
    {
        _source?.Dispose();
        _source = new CancellationTokenSource();
        var token = _source.Token;
        DetectFaces(token);
    }
}

This is going to manage the toggling of the face detector for your renderer. If you’re setting it to stop, it will tell the token source to cancel, breaking you out of the loop gracefully. If you are telling it to start, it will dispose of the old CancellationTokenSource, reinitialize it, grab a token, and start the processing loop with that token.

Let’s also add a finalizer to make sure the face detection task is canceled when the renderer is winding down:

~SampleVideoRenderer()
{
    _source?.Cancel();
}

Putting It All Together

Up to now, we’ve laid all the groundwork that we are going to need to do the face detection. From here it’s just a matter of getting our renderer to perform facial detection on each frame. Now go into the RenderFrame method in the SampleVideoRenderer. Delete the two nested for loops and replace that code with:

using (var image = new Image<Bgr, byte>(frame.Width, frame.Height, stride[0], buffer[0]))
{
    if (_watch.ElapsedMilliseconds > INTERVAL)
    {
        var reduced = image.Resize(1.0 / SCALE_FACTOR, Emgu.CV.CvEnum.Inter.Linear);
        _watch.Restart();
        _images.Add(reduced);
    }
}
DrawRectanglesOnBitmap(VideoBitmap,_faces);

This is going to pull the image directly from the buffer our previous filter was copying too, then push the new image onto our blocking stack, and then it will draw the rectangles on the faces detected. Below the RenderFrame method add the DrawRectanglesOnBitmap method which will look like:

public static void DrawRectanglesOnBitmap(WriteableBitmap bitmap, Rectangle[] rectangles)
{
    foreach (var rect in rectangles)
    {
        var x1 = (int)((rect.X * (int)SCALE_FACTOR) * PIXEL_POINT_CONVERSION);
        var x2 = (int)(x1 + (((int)SCALE_FACTOR * rect.Width) * PIXEL_POINT_CONVERSION));
        var y1 = rect.Y * (int)SCALE_FACTOR;
        var y2 = y1 + ((int)SCALE_FACTOR * rect.Height);
        bitmap.DrawLineAa(x1, y1, x2, y1, strokeThickness: 5, color: Colors.Blue);
        bitmap.DrawLineAa(x1, y1, x1, y2, strokeThickness: 5, color: Colors.Blue);
        bitmap.DrawLineAa(x1, y2, x2, y2, strokeThickness: 5, color: Colors.Blue);
        bitmap.DrawLineAa(x2, y1, x2, y2, strokeThickness: 5, color: Colors.Blue);
    }
}

That will draw the rectangle as 4 separate lines onto the bitmap and display it—note how we are using the PIXEL_POINT_CONVERSION on the x only.

One Last Thing Before We Test

I noticed the PublisherVideo element in the MainWindow is a bit small for me to make out what’s going on in it. So for my testing purposes, I doubled or quadrupled the size of the window. To do that just adjust the Height and Width on line 12 of MainWindow.xaml.

Ready, Set, Test

Now we’re ready—fire up the app and hit the Toggle Filter button on the upper left-hand corner of the screen. That will activate the filter. You should see it on your preview, and if you connect to a call you’ll be able to see it the facial detection working on the remote participants as well.

You’ll see this means of feature detection is both accurate and quick. The filter runs in about 10ms, compared to the ~30ms for the blue filter that was modified. And since the main processing runs on a worker thread, and the actual drawing takes less than a millisecond, this is actually about thirty times faster, meaning adding facial detection is virtually free from a UX perspective.

Parameter Tuning

No Computer Vision discussion would be complete without a little blurb about parametric tuning. There are all sorts of parameters you could potentially tune here, but I’m only going to focus on two:

Interval between frames
Scale Factor

As mentioned earlier, the 33 milliseconds between frames worked for me especially if I set the scale factor appropriately. The scale factor was the most important piece for performance. If you set the scale factor to 1—in other words, try to take a full image (in my case 1280×720)—that’s 921,000 pixels to process every 33 milliseconds, which has a substantial performance cost. On my machine, it would run at about 200ms per frame, redline my CPU, and without adding the explicit call to the garbage collector, would cause the memory usage to explode. Remember the scale factor is quadratic, so setting the scale factor to 4 results in the number of pixels decreasing by a factor of 16. From my testing, I did not see any drop-off in accuracy when resizing.

Pushing Further

We are going to leave this here for now, but I’m hoping this post inspires the reader to recognize the immense potential that OpenCV has in .NET. Some neat applications you could use this for, off the top of my head:

Adding filters and integrating AR into your apps. Check out some articles on Homographies and feature tracking algorithms. I personally like ORB (if for no other reason than it’s much freer than other feature tracking algorithms!).
You could integrate Far End Camera Control (FECC) into your app and have the camera motions set to track your face!
Once you’ve found the face ROI in your image you can much more efficiently run things like sentiment analysis.
As one might imagine, it’s the first step of facial recognition.

Resources

You can find a working sample from this tutorial in GitHub here
For anything you could ever want to know about OpenTok check out our site
For anything you could ever want to know about OpenCV Check out their docs
Check out Emgu’s wiki page to learn more about using Emgu in particular. If you’re an OpenCv Python fan like I am, you’ll have no problem using Emgu

The post Real-Time Face Detection in .NET with OpenTok and OpenCV appeared first on Nexmo Developer Blog.