Using the Fluid Framework

Key Takeaways

welcome to this next video in the building a real-time collaborative app series my name is dan wallin i'm a cloud developer advocate at microsoft and in the previous video aicha and i introduced the sample application that's a real-time map that has real-time data it has real-time presence and some other features in it and we showed an overview of that app now in this video we're going to dive into the fluid framework part of that and i'm going to walk you through the azure fluid relay service how we can get that set up how we can connect to that and then some of the fluid code that allows for this real-time data collaboration so as a quick review in the previous video we talked about how when it comes to collaboration we might have anna and kevin they want to collaborate on a document a application whatever it may be and the difference between what we're going to talk about using the fluid framework and something with just real-time data with websockets is really sending messages versus true collaboration you can use websockets to send messages and that works great in real time but to get those all in the proper order across all the clients that are involved in the collaboration session that's a little bit challenging that's where fluid really stands out it's all about collaboration not just sending messages so we talked about last time how the way it works and the way it keeps things in order is through something called total order broadcast and eventual consistency so as i type and then you delete something i typed it'll automatically resolve that and i described it in the last video is kind of like a git merge on the clients and so yeah it's not merging files or something like that like git would do but it is doing a similar type of concept as data is sent that data is going to get stamped by the server basically with an ordering number and then as that flows into the clients it'll re-arrange things and reorder things do what's called eventual consistency as it gets this data and that's the collaboration aspect so it's much more than just sending messages over the wire so we looked at this application where we have these messages we can type for brainstorming and i can type it in you'll see that ich on the right she also sees the same data and then of course she can go in and add messages and change colors and there's all kinds of fun stuff we can do here but the whole point of this app is that we're able to actually do all this in real time in fact this app doesn't do it but we could even type into the same text box and resolve that appropriately much like you do in google docs or word online or something like that so with that let's go ahead and jump on into a little bit more details here about the code we're going to look at so this is going to be a react app although you could use this with angular view plain old javascript typescript stuff like that but this was created with create react app so it has an index tsx we did typescript and the way this is going to work is we're going to have a brainstorm model and the model is where fluid comes into the picture so i went through this particular kind of slide here actually with dan roney from the fluid team in our learn together collaboration event we had a talk on this we're going to dive a little bit deeper this time into some of the different aspects so the reason we put all the fluid code in the brainstorm model here is because we don't want to you know litter that through the entire react app instead we want to have it in one place so that we can just reference that as needed in the different react components same would go for angular and vue and others out there now what will happen then as live data as it's typed by some other client eventually it gets stamped with an ordering number the server then sends it out to all the other connected clients and if it was this client that data then can flow in from this brainstorm model that can go down into a brainstorm view and really this is where the data comes in and then that's where the notes come into play so we have a note space that's kind of the big area where the notes are almost like a white board if you will and then the no space can have one or more notes now to get all this going though we need the server piece and i mentioned in the last video that that's not something you have to write it's what we call a reference server implementation basically you set it up in azure or there's a local one for development or you can even run your own production one although that requires quite a bit more work but we need to hook into that and so we're going to have a utels.ts that does several different things in the app we kind of consolidated those things into this utels file and we'll basically import that module and that's going to help us with our connection to the server so we're going to look at that piece coming up here so with that let's go ahead and jump into the demo code and i'll show you how this works so i have the brainstorm application cloned on my local machine here and it's open obviously in vs code so we're going to walk through some of these files and kind of dive into some of the different features that you need to know about at least to get started with fluid so first off in package json i won't open that because we're all used to it but you're going to see fluid frameworks in there as well as several other packages that are used in the app itself we're using fluent ui for example and we're using some microsoft 365 microsoft graph type packages as well but when it comes to getting started with fluid and the overall fluid framework one of the things we have to do is create a server resource so i'm going to be showing you that in just a moment but let me scroll on down here a little bit and i'm going to skip past some of the things that aisha is going to cover she's going to go into the microsoft 365 and microsoft graph aspects that are in this for the real time presence but you're going to notice that we have this async start function and one of the key things it does is right here get fluid container now the way fluid works is you want to create a collaboration session and the way we do that is we get a container and then we can add in some things to the container and i'm going to show you that so if i right click on get fluid container this will take us over to our utils module and this is a file where we threw in several utility functions but this is one of them and one of the things you'll notice we're going to do here is create a new azure client now if we scroll down up here to the top of this you're going to notice that azure client and azure container services come from this fluid framework azure client and then we're also going to have this eye fluid container interface and that's from fluid framework so let's go on back down now and the first thing we do is we're going to give it a connection string now the connection string ultimately is going to pull from an environment file that react has access to you'll notice i have a primary key here and then i have an endpoint and a storage endpoint and things like that those are going to be used to create this connection so one of the things we're going to do first is say hey is this a new container or is this an existing one because if a collaboration session already exists that would be an existing container we can pull and fluid will handle the storage of that container for you on the server side so you don't really have to deal with that at all now when we first loaded this up though it would be a new container in other words we're just starting to collaborate so we need to actually create a new container for this so the azure client has a create container and you can give it what's called a container schema now i want to go into this just a little bit because this gets really important you'll notice this is just an object literal so nothing really magical javascript wise but it has a name and then it has initial objects and notice that we have this map shared map now a shared map is something we're going to look at in just a little bit you'll notice you'll see it right up top here it's part of the fluid framework open source library and what the shared map will allow us to do is to send key value pairs in real time across multiple clients and then merge all that data in in the proper order again that's that total order broadcast and eventual consistency i keep mentioning a few times now if we move on down here if we're hooking up to azure in what i'm going to show you in just a moment then we're going to use this connection right here you'll notice we have this little use azure and this is just an environment variable that we can set to run the app you'll find all this in the readme of the project but this will pull what i just showed you earlier from the environment file and we have a tenant id a primary key an endpoint for the ordering and the storage and this is all part of this azure fluid relay that we're going to hook up to now you can also run this locally and you'll see some instructions in the readme for that as well in this case you'll notice they're both using an insecure token provider and i just want to mention that because we're trying to keep it easy here but in a real life app you'd probably want to uh pull this from azure key vault so that you don't even have to store this locally at all and so there is some demo code out there for fluid some sample where you can get more details about using a more secure method where you store all this type of data up in azure key vault but in this case we're going to keep it pretty simple just pull it from this local environment file all right so that's kind of the first part we're defining the connection and we're defining what is going to be in the container the name and then we're going to use this thing called a shared map that we're going to be talking about quite a bit here all right so going back to utils what we do then is we either create a container or if there's an existing session we're going to get the container from the server now that will allow us to then use the shared map to collaborate and i'll show you that aspect in just a moment there's a little bit more going on here we're not going to dive into that aspect but just kind of know that we either create a container or we get a container to start things off now things start to get a little more interesting so in our index tsx if i scroll down to the jsx you're going to notice that we have a brainstorm view and we pass in the container that we either created or we got and we're going to pass that into here so let's jump on in let me close this up and you'll notice if we go right up towards the top we have a use states we're using react hooks here but it's going to store this brainstorm model so the way we're going to do that is we have this crate brainstorm model and if we jump to that what that's going to do is basically extract the shared map out so we have the fluid container initial objects and we have that map property that you saw back in the utils we're going to cast that to a shared map now the reason we're doing that is this shared map can then be used when we get back to here it's returned and we now have access to the brainstorm model we're going to look at that right up top you'll see i already have that open we'll look at that in just a moment now that is going to have the wrapper of the container but inside of the container what we're doing is kind of reaching in the box we're getting this thing called a shared map out ultimately that's what we're after in just a moment now moving on down you're going to notice for the header of the web page here we're going to pass that model and then also for the note space this is where the kind of whiteboard area is for the notes that's also going to get the model it's also going to get the user information as well in fact microsoft 365 data and azure active directory is being used to pass that user information now the brainstorm model this is where all the work kind of happens then so you already saw this create brainstorm model function but if we come on down a little bit lower here you'll notice that we can move notes we can set a note we can like a note we can delete a note and all of these are using this shared map object okay so the model is actually this module here and inside of that model we have access to the shared map that's part of the schema for the container so again think of a box you reach in the box and in there there's this thing called a shared map and we can get access to that because we would have created the connection that i showed earlier to the server this shared map here can now be used to send data to the server and the way that works is we just call it just like you would do with a regular map so if i did something like you know const my map equals new map and then we did my map dot set you could set a key in a value normal javascript object this works the same way except it's a shared map it will automatically communicate with the fluid runtime send that off to the server the server stamps it and then all the clients get it and then they merge it in and then we have this eventual consistency so it gets everything in the right order for our collaboration session now in this case we're kind of coming up with some different keys so we have a position prefix of the note and the note id and the new position okay that's kind of the x y coordinates or left and top type coordinates uh in the note space when we set a note though notice that we're setting things like the card data position the author uh text for the note and then we're also setting things like the color of the note you saw in the demo earlier you know there's different colors you can pick for whatever your favorite color is for the note now likewise when we like a note we can work with that as well so we're basically saying hey does the current shared map vote string and the vote string is consistent of the authority user id if it equals the author then don't worry about it but if it doesn't we need to pass the author because if you're working on your own note we already know you're the author but if someone else is giving this they need to know you authored that note and so we could send that author information which you can see is a user object here now there's a lot more i could go through here but hopefully you get the idea that this is really just a key value pair that the fluid runtime sends to the server it stamps it with an ordering number and then sends it out to all the connected clients they then merge that in now the last little piece here is now that you've seen the brainstorm view in the model notice it has a note space and it actually passes the model into the note space well this is where all the work actually happens if we go down to the bottom of this this actually renders our different notes and you'll see it passes quite a few properties but what i want to show you here and this is something in the session i did with dan roney from the fluid team we covered this as well but i'll go through it again notice that we have a use effect here and if you're not familiar with that basically what we're saying if you look here at the bottom of the function is that if the model or the props for author change we want to run this code which calls this sync local and fluid state now technically these only change the kind of first time the app loads for each client so what this does is it calls this function it iterates through the notes and then sets those but notice right here on line 33 model dot set change listener and it passes this function well we might have 50 clients connected when another client note comes in from the server to us how do we know about that that's this set change listener so if we jump to this in the model in fact i'll have to that's the interface we'll have to jump down towards the bottom here there it is and notice we have this shared map on value changed so in other words when a value comes in from the server what do we do with it well we're going to call whatever listener was passed in well this is our listener this is the listener right here this function notice that we pass it in right there so now every time data flows in from the server this will get called it'll recreate and re-render the notes as the comment says here so it basically iterates through those and calls a create note function on the model and then pushes those into an array and then sets that array sets those notes which renders them this is kind of the magic to subscribe to changes that are occurring across one too many collaboration clients really really easy and then you can even remove change listeners as you can see here and there's other types of events you can subscribe to in fluid this is just one of the main ones you'll see now there's a lot more we could go into but i hope this gets you started with at least kind of how the code kicks things off the one piece that's missing though is we probably need to talk about the server piece so i'm going to wrap up with that just really quick so to create an azure fluid relay server and to get that tenant id and connection string and order url and storage url and stuff like that that i showed earlier we can just come in to create a resource in the azure portal and we can type fluid notice fluid relay comes up so it's called azure fluid relay we can go ahead and click on that hit create and this is one of the easiest ones you'll ever create basically you pick your subscription you pick your resource group you give it a name let's just call this test fluid server or service whatever and then pick your region here now these regions will likely change into the future but as of now that's what they are and then you would review and create let's go ahead and do that and let's go ahead and create all right so our deployment's in progress we'll go ahead and let this finish up it's already done we'll go to the resource and now we can go in and we can get some information about this let's go to access key all right and here we go mine's masked right now due to this plugin i have but or extension but notice there's my tenant id my primary key my order endpoint my storage now if we go back to my environment file for this demo that's what you see right in here and that's now what's being read when we go into the utils and it creates the connection so that's how easy it is to set up the ordering service if you will the azure fluid relay service technically and that's really all you have to do there is no code to write there now everything you do as a developer is all on you on the client side i hope that helps you get started with the fluid framework and the azure fluid relay service we've looked at some of the code how we can get this real-time data going back and forth across clients and you can see that really it's as simple as key value pairs in some cases now there's certainly more you can do more advanced scenarios of course but this is a great starting point so you can definitely check this one out now in the next video i just going to walk you through setting up resources for real-time microsoft graph notifications now this is going to involve several different azure resources you can take advantage of so definitely would encourage you to check out that video and we'll see in the next one you