.Net Foundation On .NET, 10 Sep 2019

Previous Meeting Next Meeting

⏯

youtube image

►

From YouTube: Creating custom bindings for Azure Functions

Description

Walkthrough and code samples
https://github.com/ealsur/functions-extension-101

Azure Functions triggers and bindings concepts
https://docs.microsoft.com/en-us/azure/azure-functions/functions-triggers-bindings

In this episode, Matías Quaranta takes us step by step through the fundamentals of creating a custom binding, and also how to incorporate it in an Azure Functions project.

[03:44] - Step 1 Defining the attribute for the binding
[05:38] - Step 2 Creating a service connector
[06:37] - Step 3 Creating the collector and binding context
[08:52] - Step 4 Gluing everything together
[13:21] - Step 5 Activating the custom extension
[14:28] - Using the custom binding
[19:24] - Where to get the code

#dotnet #dotnetcore #dotnetdeveloper

A

In this episode of the on.net show,, we're going to learn all about creating custom bindings for azure functions with my good buddy mathias. make sure you check it. Out.

A

Welcome to another episode of the on.net show., my name is celso philip, and with me I have mathias.. How are you doing,, mathias?.

A

Pretty good. thanks for the invite,, it's a pleasure to be here.

A

So for our folks that are watching,, why don't you tell us a little bit about who you are, and what exactly it is that you do. I'm a software engineer in the azure cosmos db team, but I also work with the functions team in the azure cosmos db, bindings.

A

Got you. so azure functions happens to be probably one of my most favorite services in azure.. I use it all. The time.

A

I'm particularly a fan of like triggers, and bindings,. They do a lot of cool stuff..

A

I think what you're going to talk to us about today is how we can create custom bindings with azure functions?.

B

Exactly., the idea of today's show is to actually help any developer that wants to create their own custom binding..

B

That might sound like a really complex thing,.

B

But if we take a look at it, and see the details,, it's going to be really easy. yeah.. So what I did is,, I'm sure you are familiar with the azure cosmos db, bindings.

C

B

They use the cosmos db, v2 sdk.

B

We're releasing the new v3 sdk.

C

So what I did is I created from scratch, a new azure functions, binding using.

C

The v3 sdk in order to understand what are the key components that.

B

Any developers should be implementing in order to create.

B

A new binding for whatever scenario they want to use.

B

Right. so right now, we have a bunch of custom, or we have our own bindings that we provide., so cosmos db is one,.

C

Azure service bus, different types of bindings.

C

So what you're to show us now is not just how we could use these bindings, you're going to show us specifically how we can create our own ones. exactly., like a target,, whatever our particular data, source, right?

C

exactly., so by creating a binding from scratch,. What we're trying to do is,!

C

I took this base a minimum components,, and then I grouped them into five steps..

C

So the idea is to show you a github repo that any developer right now can clone, and going from step 1 to step 5,.

C

They will be able to create their own custom binding for their own customer scenario..

C

What I love about this is that, because you have this repo,.

C

After folks have watched this video,, they can go, and check out the repo,.

B

And they could follow instructions, and they could create your same binding, or you can create their own? exactly.. So basically,, the repo has five projects,.

B

One for each step.

B

obviously,, the first one references the previous one.

B

Yeah., so when you were customizing each step,, then the binding itn on step 5 will be completed,.

C

And you will be able to use that binding in your own azure functions, project.

C

awesome., so the idea is to start with step 1.

C

in step 1,. What we need to do is define our attributes.

C

The attributes is the way that we expose any configuration,.

C

Or setting that we want the end user to be able to sit in our binding.

B

Yeah., so what azure functions today,? What I'm used to doing is I'll put an attribute next to a parameter of some sort.

B

exactly.. Then inside of that attribute like let's say,, it's again like a cosmos db attribute,, I might give it a connection. String,.

C

Or the name of the collection,, or something like that.

C

exactly. in this case,. What I'm doing is I define these cosmos db attributes, and then I just have a bunch of properties.

C

for example, the database name,, the container name,, the connection string,, and there are a couple of interesting decorators.

C

That we can add to our custom bindings, the autoresolve one will make it. So if the user uses one of.

C

The binding patterns- that's like using the percentage.

C

The autoresolve will make it so when the functions runtime picks up our custom binding,, it will try to look in the settings in the environment, settings,.

B

Or in the settings file, and will automatically replace whatever the users.

B

Set in that place, holder with the real value in the environment.

B

Oh, awesome., but then we don't have to really write any code.. We just- no. to put that attribute. There? exactly., you just add the outer resource decorator, to wherever attribute.

C

In your binding that you want to resolve automatically,.

C

And it will do it magically for you., that's awesome.. There is another one called connectionstring., it works similarly,, but it also looks for in.

C

The connection string settings in your function, app.

C

But the idea is that it works seamlessly., so basically,. This is all what you need to do in your first step..

C

You need to think what are the configuration settings for the options that you want, your end user to use for your binding, and that's it.

C

now, we go to step 2.

C

step. 2 will have what we call our collector factory,.

C

Or our service factory., the ada instinctually, is we want our binding to connect to some service, in this case,. They went into a link to the cosmos db, database.

C

But it could be a api,, it could be any other azure service.

B

Yeah., so the idea of step 2 is you need.

C

To create these factory that will create instances of whatever client you want to provide to your end, users.

C

sure. in this case,. It's taking some of the attributes that are defined in step, 1, for example,, the connectionstring, and the currentregion,, and then internally, it's just creating an instance of the cosmos db, v3 client.

C

Then the other thing that we need to do is we need to expose an interface. we'll see why we need to expose an interface in step. 5.

C

But we also need to know that in step, 2.

C

Okay. then it will go to step 3.. The idea in this step is to actually create what the binding will do when it's broken.

C

So I have my attributes that define in this case the connectionstring in the database, I have my client, or the client that my binding will create, and in step 3. What I do is I create the collector,.

C

We take the whatever the user wants to save in my database.

C

It uses the client that I'm providing with.

C

The attribute to them that the user set, and that's something.

C

Whatever I want to do in this case,, I want to save the item that the user.

C

Is passing to the collection,.

C

Or container in the cosmos db account., but if I'm implementing my own custom bindings, for example,.

C

Sending data to my api,: this is the point where I will check the http client taking the data from the user, and then send the payload. right.. The azure functions bindings.

C

Provide a couple of very generic interfaces that we can implement.

C

In this case, I'm implementing the iasynccollector, that is mostly used in output bindings,, but you could create your own things. Here.

C

You could expose a custom class,, you could expose a custom interface,.

C

There is no real limitation., I'm just using the iasynccollector, because it's like.

C

A common interface for people using output, bindings.

C

Sure. then, the other thing that I do in step 3 is: I create a binding, context., so basically, and we'll see in the last step how everything comes together.

C

What I have in the context is the value of the current attribute,.

C

And the client that the factory in step 2 is passing me.

C

This is the context that I will be using in my collector.

C

I will receive in the context, and using that information, for example,, I'm using in this case, a boolean that will tell me if the user.

C

Wants me to create the collection for them or not,, and then I'm using part of the information in the context to save the documents in the database.

C

Got it. then step 4 is what I call the glue that binds everything together.

C

so in step 4,. What we define is actually.

C

An implementation of this iextensionconfigprovider interface.

C

The iextensionconfigprovider is, the interface, has only one method called initialize..

C

This is where we cannot make the magic happen.

C

We create what we define as rules..

C

Each rule will tell, which is the type of attributes that we want it to wire..

C

We can add some validators..

C

The validators will make it solid.. Let's quickly show what this guy does.

C

It's actually validating that one of the parameters is.

C

There, because we really need the connection string.

C

For example,, if we are doing our own custom, binding,.

C

This is the point where we can add validations for any required parameter that we give the user the possibility to have,.

C

But they might have a null value, or a value that we cannot support..

C

This is something that you have to implement. Yourself?.

C

Let's say you have your specific validation rule for your attribute.

C

exactly. for your output, binding, or input binding. exactly.. How do you implement that?? It's an optimal state when you define the rule, because you don't really need to add the validation., but if you want,, you can define it calling this addvalidator method in the rule.

C

Finally,, what I do is, I call this bindtocollector method.

C

I pass in an open, type.

C

This opentype is,, let me quickly show you.

C

So basically,, what we can do is we can filter which c# types,.

C

Or custom classes we allow our-.

C

Attributes to work with? exactly. got it.. There is a base, one called opentype.poco,.

C

But we can inherit from that one, and have our own custom validations.

B

In this case, I don't want users to be able to pass any enumerable.

B

C

But if you don't have any filtering,, you could just use the opentype.poco implementation.

C

okay. got it.. Then going back to my bindtocollector,.

C

So the bindtocollector will say, "hey, expose this cosmos db. Attribute,.

C

And give the user an iasynccollector,.

C

But in order to do it, use this converter.".

C

Now the converter in step 4,, what it takes is it takes an attribute, and it creates a context.. So the context we were using in the previous steps,.

C

It creates one based on the value of our current attributes,.

C

And when it creates it,, it's also getting an instance of a service..

C

So let me go back a couple of steps.

C

so that get service, is that, like a di thing, that's going on there?

C

no. right now is just a customer implementation,.

C

And what I do is I create.

B

An internal cache to avoid having.

C

Multiple instances of my cosmos db, clients.

C

Right., because, in the case of cosmos db,, we want to follow in the best. Practices, have one.

C

Sorry, one instance. one instance? right. per connection string,, and that's because to create the instances is relatively expensive.

C

exactly. because you have to open sockets and things of that. exactly.. So from a resource management perspective,. We want to make sure that we officially have ours. yeah.. This applies to all types of clients like the http client.

C

yeah.. So if you're not connected to api,, you might want to have your own custom cache of.

C

These clients, instead of creating one in your execution.

C

B

So basically, the great context will get a service instance either.

C

From the cache would be able to create one, and then return this context to the collector.

C

Finally, this,, let me go back here.

C

Finally,, what we do is this converter will.

C

Just create one asynccollector instance,.

C

Sorry, passing the context we just saw.

B

This is where the magic happens.

B

Because we are just taking one attribute,.

C

We are creating the context,.

B

We are creating a client if we really need to,.

C

Or picking up one from our internal cache,.

C

And then creating this implementation of the collector that we saw in the previous step..

C

This is the collector. We will get exposed to the end user,.

C

And whenever they call item this is the guy that will do the work for them.

C

Awesome. the final step that it's,, it's really small,, but you really needed to.

C

It's you need an implementation of the iwebjobsstartup.

C

So basically, this make it so when the user is referencing, the custom binding,.

C

These iwebjobsstartup implementation will just hook into.

C

The initialization pipeline of the functional extension and call a method.

C

This method in this case is adding my extension, my implementation of the conflict, provider.

C

Sure. then, I'm using the ai to have.

C

One instance of the original collector factory that we have in step two., so there isn't really more than this.

C

It's just having a conflict. Provider, wiring up the converter with the attribute,.

C

Having a contexts, and just having these extensions, so the user.

C

Doesn't have to do anything other than referencing the package.

C

The package., wherever the case is. either I look at the package or I brush it., that's like the whole year.

C

finally,. What I have to share with you is: I have sample this code. Sample shows you,.

C

It's actually in the repo., so they can even use it. but you're, showing us exactly how to use it, now,, right?

C

exactly., so what it is,. This is the cosmo of the cosmos of the attribute that I defined in step one..

C

This is using these outros soil properties that.

C

Is picking up from my local settings json file.

C

yeah. here is the asynccollector implementation.

C

So I'm getting this asynccollector instance in.

C

Sine wave function's code,.

C

And I'm just calling this addasync method that if we remember from.

C

Step three: its just pumping that data into the database.

B

Right., if I press "f5",.

C

I want to show you how each of the steps comes into play when.

C

The functions run-time starts with my custom, binding implementation.

C

So we will wait a couple of seconds.

B

You can see in the logs that it's.

C

Combining each step individually, and each step preferences a previous one.

C

right. okay., that's interesting.! Then the host will stop. split up the function. Host. exactly., I'm guessing because you did that iwebjobsstartup,.

C

Now that the host is going to wire up. there, you go.

C

exactly. somebody is going to wire up this thing. Here. exactly.. The first thing that happens is that it's wired.

C

Up and fires, my articles, mostly bb3 implementation,,.

C

But it's actually adding the extension and adding the collateral factory., so this small sample will fire every 30 seconds.

C

This is how it's utilizing the contexts from step: four;.

C

It's defining the binding rule and the finding the binding collector.. When I press "f5" it will fire the first time.

C

So when it fires the first time it gets the context,.

C

This context will, in this case, get a service,.

C

And because I don't have anything in.

B

My cache it will create one analogy to the cache.

B

It will create one.. This is where I'm calling createclient in my collector factory,.

B

And I'm just taking data from the attribute,.

C

In this case, the accountendpoint, and just creating the clients., then the function's called we'll call "aliasing".

C

And here's how my collector implementation gets called,.

C

Receives the item from the user, and then eventually calls upsertdocuments and stores it in the database.

C

right. so from the user perspective or from the developer perspective anyway,. So we got an instance of ai async, collector.

C

yeah.. But now what we just saw is that,, because you created your own and you wired up and extension, right? yeah.. We were able to essentially, we're using your version of that., my version of that. yeah, exactly., very all right.. This is another function, trigger., so every time the function trigger,, the converter will get called;.

C

It will try to build a context.

C

But in this case instead I already have a cosmosclient instance,.

C

It will just use the one that I have in the cache..

C

It will give the context to the collector implementation,.

C

And they add async method, get called again,.

C

And then I get another app's upsert invocation and then so on and so forth..

C

So for every invocation, the converter creates the context,.

C

And passes down the context to the collector, so the user can call.

B

The other async method or the async implementation.

B

It's not really hard once you.

B

Understand the basic components that you require,.

C

And the idea is that,, like you said, any developer can now fork this repo, clone it, and then start from step. One,.

C

And implement their own attributes, and their own collectors and everything. right.. Can I go with what you were talking about a little while ago??

C

I think it'd be interesting to have one for the redis service for doing caching, right?, because there's not one today.. So maybe that might be something that one of you might want to. Try out, is to create implementation using redis and create a custom input or output. Maybe.

C

I mean it's really easy once you understand the basic components, and then you can start taking those basic components, and build on top of them.

C

right.. I know this is also running on functions. V2, and I know the other day we released dependency, injection, support, and they're two.

C

So I'm guessing. That means that all of your classes and all of your components can be involved in that di space,.

C

And I could pull on a logger, or app insights, or whatever the case is and use it inside of.

C

Basically, if we take a look at step, five,, I'm using part of.

B

Avi to other singlets, on instance, of the collective factory.

B

So you could even define your own,, like you, mentioned,.

B

Your own components that use the ai,.

B

And then reusing across the function, extinction implementation.

C

Great. awesome. well,- this is great man., so tell me know.. So after I've watched this video,, where can I go exactly to learn a little bit more about this?.

C

Is the repo already online, and published,? Can we check it?.

B

Yeah., actually, let me zoom in.

B

All right. here is the url.. You can show us the url., so this is on your github repo, right? yeah.

C

All right., you can just fork it,.

B

And if we check the repo here are all the five steps,.

B

And if you go to each step, and you click on "data",, you will have a readme explaining which.

C

This step actually does and what are the actions for each step.

C

So, basically, once you clone the repo,, you go to each step,, you do whatever is in the actions on this step,, and you will eventually come to a step. Five with your custom functions implementation..

C

This is like a little mini workshop.

B

Yeah. so again I can go in here, and go through the steps, and create my own version of whatever my input or output binding happens to be..

B

Each step will explain the same thing that I mentioned. Before.

C

For example, the step, four explain how the extinctionconfigprovider works, and how some snippets that point to the source files.

B

Sure., you will still have the actions in the system.

C

Okay., we'll just make sure that we have this inside of the show notes so that everybody that's watching, can check it. Out.

C

awesome., all right. well,. Thank you so much for coming on man, and I really appreciated it.. It's been my pleasure. thank you-all for watching.. This has been another episode of the on.net show and we learned all about creating custom bindings for azure functions.