Skip to main content

Quick Start

This guide shows how to create a simple MagicOnion server and client. The server provides a simple service that adds two numbers, and the client calls the service to get the result.

MagicOnion provides RPC services like Web API and StreamingHub for real-time communication. This section implements an RPC service like Web API.

Server-side: Defining and Implementing a Service

At first, create a MagicOnion server project and define and implement a service interface.

1. Setting up a gRPC server project for MagicOnion

To start with a Minimal API project (see: Tutorial: Create a minimal web API with ASP.NET Core), create a project from the ASP.NET Core Empty template. Add the NuGet package MagicOnion.Server to the project. If you are using the .NET CLI tool to add it, run the following command:

dotnet add package MagicOnion.Server

Open Program.cs and add some method calls to Services and app.

using MagicOnion;
using MagicOnion.Server;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddMagicOnion(); // Add this line(MagicOnion.Server)

var app = builder.Build();

app.MapMagicOnionService(); // Add this line

app.Run();

At this point, you are ready to use MagicOnion in your server project.

2. Implementing a Unary Service

Add the IMyFirstService interface to share it between the server and the client. In this case, the namespace that contains the shared interface is MyApp.Shared.

The return type must be UnaryResult<T> or UnaryResult, which is treated as an asynchronous method like Task or ValueTask.

using System;
using MagicOnion;

namespace MyApp.Shared
{
// Defines .NET interface as a Server/Client IDL.
// The interface is shared between server and client.
public interface IMyFirstService : IService<IMyFirstService>
{
// The return type must be `UnaryResult<T>` or `UnaryResult`.
UnaryResult<int> SumAsync(int x, int y);
}
}

Add a class that implements the IMyFirstService interface. The client calls this class to process the request.

using MagicOnion;
using MagicOnion.Server;
using MyApp.Shared;

namespace MyApp.Services;

// Implements RPC service in the server project.
// The implementation class must inherit `ServiceBase<IMyFirstService>` and `IMyFirstService`
public class MyFirstService : ServiceBase<IMyFirstService>, IMyFirstService
{
// `UnaryResult<T>` allows the method to be treated as `async` method.
public async UnaryResult<int> SumAsync(int x, int y)
{
Console.WriteLine($"Received:{x}, {y}");
return x + y;
}
}

The service definition and implementation are now complete.

It is now ready to start the MagicOnion server. You can start the MagicOnion server by pressing the F5 key or using the dotnet run command. At this time, note the URL displayed when the server starts, as it will be the connection destination for the client.

Client-side: Calling a Unary Service

Create a Console Application project and add the NuGet package MagicOnion.Client.

Share the IMyFirstService interface and use it in the client. You can share the interface in various ways, such as file links, shared libraries, or copy & paste...

In the client code, create a client proxy using MagicOnionClient based on the shared interface and call the service transparently.

At first, create a gRPC channel. The gRPC channel abstracts the connection, and you can create it using the GrpcChannel.ForAddress method. Then, create a MagicOnion client proxy using the created channel.

using Grpc.Net.Client;
using MagicOnion.Client;
using MyApp.Shared;

// Connect to the server using gRPC channel.
var channel = GrpcChannel.ForAddress("https://localhost:5001");

// Create a proxy to call the server transparently.
var client = MagicOnionClient.Create<IMyFirstService>(channel);

// Call the server-side method using the proxy.
var result = await client.SumAsync(123, 456);
Console.WriteLine($"Result: {result}");
tip

When using MagicOnion client in Unity applications, see also Works with Unity.