User Manual Table of Contents Introduction ............................................................................................................................................. 2

Core Pillars of Spike-Engine ..................................................................................................................... 2

Duplex Communication ....................................................................................................................... 2

Performance. ....................................................................................................................................... 2

Code Generation ................................................................................................................................. 2

Installing Spike-Engine ............................................................................................................................. 3

Extensions for Visual Studio ................................................................................................................ 4

Building a Service .................................................................................................................................... 5

Defining the Protocol .......................................................................................................................... 6

Building a Client ....................................................................................................................................... 9

Introduction Back in 2009, we've noticed that the modern software and web was becoming more and more

interactive. Being independent video game developers and a passion for online, massively

multiplayer games pushed us to create a technology that would suit all our needs. We wanted to

build reliable web services without sacrificing any productivity or performance. Moreover, we

wanted a single server to handle thousands of concurrent clients at the same time. This ambition led

us to create Spike-Engine.

Spike-Engine is a software platform that facilitates building client-server applications for .NET

developers. In particular, it focuses on real-time and duplex communication, performance and

productivity.

Core Pillars of Spike-Engine The core idea behind Spike-Engine is quite simple. There are 3 core principles underpinning the

architecture, duplex communication, performance and code generation.

Duplex Communication

We needed duplex communication, and a connected, stateful mode. Duplex communication

simply means that client and the server can both initiate the communication and exchange

messages easily, at any time (unlike HTTP). After all, we wanted to build games and

interactive applications!

Performance.

We wanted our technology to be performant and handle thousands of clients, and hundreds of

thousands of packets per second. This proved to be very challenging to achieve and took 3

years to polish and to find a balance between flexibility, API and performance. Even better,

good performance also saves cost, since we did not need to buy large servers with massive

amount of bandwith and we could cut our costs.

Code Generation

As most of you, we are a small and agile team. This means we needed to do things smart and be able

to stay productive while building high quality, heteregeneous software. From the very beginning, we

designed our technology to help us by generating automatically most of the networking code, while

we could concentrate on actually implementing the business logic.

Installing Spike-Engine Before you start, make sure that Microsoft Visual Studio 2010 or later is installed on the machine

where you plan to develop Spike-Engine powered services. You will also need Microsoft .NET

Framework 4.0 or Mono Framework installed on the machines where you plan to deploy Spike-

Engine powered services.

Start by visiting http://www.spike-engine.com/download and downloading a free version of Spike-

Engine library. Alternatively, you can download it by signing-in and going to "My Cloud" section,

"Download" tab.

The download button is impossible to miss. However, it will ask you to sign in via your Google, Yahoo,

Facebook, Microsoft or other account first.

Next, once you've downloaded the .MSI file, double click on it to run the Setup Wizard. Standard

routine, just specify the destination folder you want. When the installer finishes, you can start your

Visual Studio and start playing with Spike-Engine. Please note that if you had Visual Studio open

while installing, you will need to restart it, as Spike-Engine installes a couple of new features to your

favourite IDE.

The installer does a couple of things. It sets up Spike.Runtime.dll into the GAC and sets up the

extensions for Visual Studio 2010 or 2012, depending on which one you've got installed.

The installation process is quick and easy.

Extensions for Visual Studio

As mentioned previously, the installer setup some extensions in your IDE. You can see them by going

in your Visual Studio, 'Tools' menu and clicking on 'Extensions and Updates...' option.

Visual Studio 2012 screenshot, tools menu.

You should have 'Spike-Engine Extensions for Visual Studio' listed there, as shown in the following

screenshot.

Here you can see that in 'extensions and updates' section, Spike-Engine tools have been successfully installed.

Building a Service In this section we will start building our HelloSpike service. This service will consist of a single echo

operation. This operation is sent from the client to the server, the client sends a string message to

the server and the server will write the same message back.

For our sample service, we are going to use Framework 4.0. Please make sure to select it in the 'New

Project' dialog.

First, we need to create a new C# project for our Spike-Powered service. In Visual Studio, we do it by

going to File -> New -> Project... and selecting 'Spike-Engine Console Application' in the list of

available projects.

Notice that the project is in a separate 'Spike Engine' category.

The 'Spike-Engine Console Application' we just created is just a C# Console Application with

Spike.Runtime.dll as a reference and a couple of handy lines of code in the Main method. You can

easily create it yourself, there's no dark magic.

The Program.cs file contains the Main method, which simply begins to listen on ports 8002 and 80

when the program starts.

By pressing F5 or clicking play, you can build and run the project and it will host your service in the

console. Don't mind if it says that it couldn't find some XML files, this is totally normal behavior for

first run.

See this red line? This means that it couldn't bind on port 80. Why? I have Skype or IIS running on this machine,

already blocking my port 80. But that's okay, Spike-Engine was still able to bind itself to the port 8002.

Defining the Protocol

Now that we have a project, we need to define a protocol. In Spike-Engine, we have a formal way of

defining a protocol, via a .SPML file. This file is essentially an XML file with a strongly-defined XML

Schema. We can add a new protocol by simply going to Add Item and selecting 'Spike-Engine

Protocol Definition File'.

public static void Main(string[] args) {

// Run the server on the specified endpoints

Service.Listen(

new DefaultSpikeTcpBinding(IPAddress.Any, 8002), // Listen on port 8002

new DefaultSpikeTcpBinding(IPAddress.Any, 80) // .. and the port 80 );

}

Once again, there's a special category for Spike Engine.

The XML Schema can be found here: http://www.spike-engine.com/2011/spml. The installer also

sets up a code completion for you, you should be able to explore it while playing with spml file.

Once added, if we double-click on the Protocol1.spml file within the Solution Explorer, it will show

the contents of the file. As you can see, it's simply an XML file.

Now, we need to define our Echo operation. An operation in a SPML file must have a Name and

either an Incoming or Outgoing packet. In turn, an Incoming or Outgoing packet, should have one or

more Members. Finally, each Member should have at least a Name and a Type. The Type of a

member is actually a .NET primitive type. There's also a way to create more complex and even

dynamic types, but that will be explained later on.

In our case, for our Echo operation we have both, Incoming and Outgoing packets and only one

member in each, of type String.

<?xml version="1.0" encoding="UTF-8"?>

<Protocol Name="Protocol1" xmlns="http://www.spike-

engine.com/2011/spml" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <Operations>

<!-- Define Operations here -->

</Operations>

</Protocol>

While we were modifying the protocol definition xml, Spike-Engine have generated a code-behind C#

file for us. This code-behind file contains the necessary plumbing for server-side implementation.

Feel free to take a look, it's well commented and clean code.

If you're having issues, make sure you installed Spike-Engine properly and then run 'devenv /setup' to purge

Visual Studio cache.

It generated for us a couple of things, let's examine them one by one.

Protocol1 static class. This class represents our protocol and contains an Echo event. We can

subcribe to this event in order to get notified when client sends us a message.

EchoInform class. This represents an Outgoing packet, a packet which is sent Server to Client. By

convention, every packet which is sent from Server to Client has 'Inform' suffix.

EchoRequest class. This represents an Incoming packet, a packet which is sent from Client to Server.

By convention, every packet which is sent from Client to Server has 'Request' suffix.

Protocol1Extensions static class. This class contains a coupe of extension methods,

extending IClient interface. It addsSendEnchoInform method, allowing the server to send some

information to the client.

Now, we need to implement our Echo operation. We first need to hook the Echo event in

our Protocol1 static class. We need to do it before Service.Listen, as this method never exits. Next,

we simply invoke client.SendEchoInform and pass back the text we received.

<?xml version="1.0" encoding="UTF-8"?>

<Protocol Name="Protocol1" xmlns="http://www.spike-

engine.com/2011/spml" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <Operations>

<Operation Name="Echo" SuppressSecurity="true"> <Incoming>

<Member Name="Text" Type="String" /> </Incoming>

<Outgoing>

<Member Name="Text" Type="String" /> </Outgoing>

</Operation>

</Operations>

</Protocol>

That's it, we have now written our first Spike-Powered service. In the next section of this tutorial we

are going to build a C# client for our service.

Building a Client In this section we will build a C# client for our HelloSpike service we built in the previous section.

We start by creating a new project, called HelloSpikeClient in our solution. This is going to be an

ordinary C# console project.

Here, we simply create a normal console project. No fancy dependencies.

Not that we have two projects, we need to be able to debug them easily and we need to launch both

projects at the same time. We do that, by right clicking on the Solution in the Solution Explorer, and

selecting properties.

public static void Main(string[] args) {

// Hook the echo event

Protocol1.Echo += OnEcho;

// Run the server on the specified endpoints

Service.Listen(

new DefaultSpikeTcpBinding(IPAddress.Any, 8002), // Listen on port 8002

new DefaultSpikeTcpBinding(IPAddress.Any, 80) // .. and the port 80 );

}

static void OnEcho(IClient client, EchoRequest packet) {

// Simply send back the text we received.

client.SendEchoInform(packet.Text);

}

Make sure to select 'Multiple Startup Projects' option and enable both projects.

Now, we need to generate the code in order to build our client. In order to accomplish this, we

navigate to the installation directory, in our case we kept the default path and installed Spike-Engine

into Program Files folder. The Build subfolder contains libraries and a command line tool that allows

us to generate client code.

Make sure your HelloSpike service is running before generating code for the service. This is needed

because Spike-Engine exposes it's own protocols on HTTP, similarly to Asp.Net WSDL.

The easy way is simply to double click on QuickBuild.bat file, which will generate the proxies for the

local server.

Just double-click on QuickBuild.bat or run Spike.Build.exe via command line.

Then, we simply grab the proxy we want. In our case, we just copy-paste ServerProxy.cs file from

Client.CSharp.Script folder.

We add the ServerProxy.cs to our client project. Now, we are ready to actually start implementing

the business logic for our C# client.

Below is the code for our sample client. It is quite straightforward as we create a TcpChannel which

represents a communication channel between client and a server. Next, we connect the channel and

once connected we simply invoke our Echo method. Everything is strongly-typed with full intellisense

support.

Finally, we can run the project and voila!

class Program {

// A flag which can be set to stop the program

static bool Running = true;

// A channel which represents a connection to the server

static TcpChannel Channel = new TcpChannel();

static void Main(string[] args) {

// Wait a bit while our server starts...

Thread.Sleep(5000);

// Hook our Echo event

Channel.EchoInform += OnEcho;

// Connect to the server

Channel.Connected += OnConnected;

Channel.Connect("127.0.0.1", 8002);

// Reception loop, can be in a separate thread

Channel.ReceiveLoop(15, ref Running); }

static void OnConnected(object sender, ConnectionEventArgs e) {

Console.WriteLine("Connected!");

// Send a message

Channel.Echo("Hello, Spike World!");

}

static void OnEcho(object sender, PacketReceiveEventArgs<EchoInform> e) {

Console.WriteLine("Received: " + e.Data.Text); }

}

Congratulations on completing getting started tutorial! Plese give us your feedback