Skip to content

Commit

Permalink
Update readme for OfX-gRPC
Browse files Browse the repository at this point in the history
  • Loading branch information
quyvu01 committed Dec 26, 2024
1 parent 7ea5276 commit 169c412
Showing 1 changed file with 21 additions and 49 deletions.
70 changes: 21 additions & 49 deletions src/OfX.Grpc/README.md
Original file line number Diff line number Diff line change
@@ -1,16 +1,14 @@
# OfX.Grpc
# OfX.gRPC

OfX.Grpc is an extension package for OfX that uses gRPC to transport data.
OfX.gRPC is an extension package for OfX that leverages gRPC for efficient data transportation. This package provides a high-performance, strongly-typed communication layer for OfX’s Attribute-based Data Mapping, enabling streamlined data retrieval across distributed systems.

[Demo Project!](https://github.com/quyvu01/TestOfX-Demo)

---

## Introduction

OfX.Grpc extends the core OfX library by providing seamless integration with Entity Framework Core. This enables developers to automatically map and retrieve data directly from a database, leveraging the power of EF Core along with attribute-based data mapping.

For example, suppose you have a `UserId` property in your model, and you want to fetch the corresponding `UserName` and `Email` fields from the database. By using OfX.EntityFrameworkCore, you can annotate your model with attributes, and the library will handle data fetching for you.
gRPC-based Transport: Implements gRPC to handle data communication between services, providing a fast, secure, and scalable solution.

---

Expand All @@ -19,74 +17,48 @@ For example, suppose you have a `UserId` property in your model, and you want to
To install the OfX.EntityFrameworkCore package, use the following NuGet command:

```bash
dotnet add package OfX-EFCore
dotnet add package OfX-gRPC
```

Or via the NuGet Package Manager:

```bash
Install-Package OfX-EFCore
Install-Package OfX-gRPC
```

---

## How to Use

### 1. Register OfX.EntityFrameworkCore
### 1. Register OfX-gRPC

Add OfX-gRPC to your service configuration during application startup:

Add OfX.EntityFrameworkCore to your service configuration during application startup:
For Client:

```csharp
builder.Services.AddOfXEntityFrameworkCore(cfg =>
{
cfg.RegisterContractsContainsAssemblies(typeof(SomeContractAssemblyMarker).Assembly);
cfg.RegisterHandlersContainsAssembly<SomeHandlerAssemblyMarker>();
})
.AddOfXEFCore<ServiceDbContext>()
.AddOfXHandlers<IHandlerAssemblyMarker>();
```

After installing the package OfX-EFCore, you can use the extension method `RegisterOfXEntityFramework()`, which takes two arguments: the `DbContext` and the handlers assembly.
cfg.RegisterClientsAsGrpc(config => config.RegisterForAssembly<SomeContractAssemblyMarker>("http://localhost:5001")); //gRPC server host
### 2. Write a Handler Using EF Core

Implement a request handler to fetch the required data using Entity Framework Core. For example:

```csharp
public sealed class UserOfXHandler(IServiceProvider serviceProvider)
: EfQueryOfXHandler<User, GetUserOfXQuery>(serviceProvider)
{
protected override Func<GetUserOfXQuery, Expression<Func<User, bool>>> SetFilter() =>
q => u => q.SelectorIds.Contains(u.Id);

protected override Expression<Func<User, OfXDataResponse>> SetHowToGetDefaultData() =>
u => new OfXDataResponse { Id = u.Id, Value = u.Name };
}
});
```

### Function Details

#### `SetFilter`
This function is used to define the filter for querying data. It takes the query (`GetUserOfXQuery`) as an argument and returns an `Expression<Func<TModel, bool>>`, where `TModel` is your EF Core entity.
For Server:

Example:
```csharp
protected override Func<GetUserOfXQuery, Expression<Func<User, bool>>> SetFilter() =>
q => u => q.SelectorIds.Contains(u.Id);
var builder = WebApplication.CreateBuilder(args);
...
var app = builder.Build();
...
app.MapOfXGrpcService();
...
```
Here, `SetFilter` ensures that only entities matching the provided `SelectorIds` in the query are retrieved.

#### `SetHowToGetDefaultData`
This function specifies how to map the retrieved entity to the default data format. It returns an `Expression<Func<TModel, OfXDataResponse>>`, where `TModel` is your EF Core entity and `OfXDataResponse` is the mapped data structure.
After installing the package OfX-gRPC, you can use the extension method `RegisterClientsAsGrpc()` for client and `MapOfXGrpcService()` for server. Look up at `RegisterClientsAsGrpc` function, we have to defind the contract assembly with server host, on this example above, all the queries are inclued in `SomeContractAssemblyMarker` assembly.

Example:
```csharp
protected override Expression<Func<User, OfXDataResponse>> SetHowToGetDefaultData() =>
u => new OfXDataResponse { Id = u.Id, Value = u.Name };
```
Here, `SetHowToGetDefaultData` maps the `Id` and `Name` of the `User` entity to the `OfXDataResponse` format.

By overriding these functions, you can customize the filtering logic and data mapping behavior to suit your application's requirements.

---
That All, enjoy your moment!

---

0 comments on commit 169c412

Please sign in to comment.