RedisOM 用于 .NET

学习如何使用Redis Stack和.NET进行构建

Redis OM .NET 是一个专门用于处理 Redis Stack 中文档的库。在本教程中，我们将构建一个简单的 ASP.NET Core Web-API 应用程序，用于对简单的 Person 和 Address 模型执行 CRUD 操作，并且我们将使用 Redis OM .NET 完成所有这些操作。

先决条件

.NET 6 SDK
任何用于编写 .NET 的 IDE（Visual Studio、Rider、Visual Studio Code）。
RediSearch 必须作为 Redis Stack 配置的一部分进行安装。
可选：Docker Desktop 用于在 docker 中运行 redis-stack 以进行本地测试。

如果你想跳过本教程直接进入代码，所有源代码都可以在GitHub上找到

运行 Redis Stack

有多种方式可以运行Redis Stack。一种方式是使用docker镜像：

docker run -d -p 6379:6379 -p 8001:8001 redis/redis-stack

创建项目

要创建项目，只需运行：

dotnet new webapi -n Redis.OM.Skeleton --no-https --kestrelHttpPort 5000

然后在您选择的IDE中打开Redis.OM.Skeleton.csproj文件。

配置应用程序

在您的appsettings.json文件中添加一个REDIS_CONNECTION_STRING字段来配置应用程序。将该连接字符串设置为您的Redis实例的URI。如果使用前面提到的docker命令，您的连接字符串将是redis://localhost:6379。

连接字符串规范

Redis URI的规范位于这里。您可以使用:password@host:port或default:password@host:port作为不包含username的连接字符串。

创建模型

确保将Redis.OM包添加到您的项目中。这个包使得创建模型和查询您的Redis领域对象变得容易。

dotnet add package Redis.OM

现在是时候创建应用程序将用于存储/检索人员的Person/Address模型了。创建一个名为Model的新目录，并将文件Address.cs和Person.cs添加到其中。在Address.cs中，添加以下内容：

using Redis.OM.Modeling;

namespace Redis.OM.Skeleton.Model;

public class Address
{
    [Indexed]
    public int? StreetNumber { get; set; }
    
    [Indexed]
    public string? Unit { get; set; }
    
    [Searchable]
    public string? StreetName { get; set; }
    
    [Indexed]
    public string? City { get; set; }
    
    [Indexed]
    public string? State { get; set; }
    
    [Indexed]
    public string? PostalCode { get; set; }
    
    [Indexed]
    public string? Country { get; set; }
    
    [Indexed]
    public GeoLoc Location { get; set; }
}

在这里，你会注意到除了StreetName被标记为Searchable之外，所有字段都用Indexed属性装饰。这些属性（Searchable和Indexed）告诉Redis OM，你希望在Redis Stack中查询文档时能够使用这些字段。Address本身不会是一个文档，因此顶级类没有用任何东西装饰；相反，Address模型将嵌入到我们的Person模型中。

为此，请将以下内容添加到 Person.cs

using Redis.OM.Modeling;

namespace Redis.OM.Skeleton.Model;

[Document(StorageType = StorageType.Json, Prefixes = new []{"Person"})]
public class Person
{    
    [RedisIdField] [Indexed]public string? Id { get; set; }
    
    [Indexed] public string? FirstName { get; set; }

    [Indexed] public string? LastName { get; set; }
    
    [Indexed] public int Age { get; set; }
    
    [Searchable] public string? PersonalStatement { get; set; }
    
    [Indexed] public string[] Skills { get; set; } = Array.Empty<string>();    
    
    [Indexed(CascadeDepth = 1)] public Address? Address { get; set; }
    
}

这里有几件事情需要注意：

[Document(StorageType = StorageType.Json, Prefixes = new []{"Person"})] 表示Redis OM将使用JSON来存储文档，并且Person类的键前缀将是Person。
[Indexed(CascadeDepth = 1)] Address? Address { get; set; } 是使用 Redis OM 索引嵌入对象的两种方法之一。这种方式指示索引级联到对象图中的对象，CascadeDepth 为 1 意味着它只会遍历一个级别，像从头开始构建索引一样索引对象。另一种方法使用您要搜索的各个索引字段的 JsonPath 属性。这种更精确的方法限制了索引的大小。
Id 属性被标记为 RedisIdField。这表示该字段将用于在存储到 Redis 时生成文档的键名。

创建索引

模型构建完成后，下一步是在Redis中创建索引。最正确的管理方法是将索引创建过程放入一个托管服务中，该服务将在应用程序启动时运行。创建一个HostedServices目录，并在其中添加IndexCreationService.cs文件。在该文件中，添加以下内容，这将在启动时创建索引。

using Redis.OM.Skeleton.Model;

namespace Redis.OM.Skeleton.HostedServices;

public class IndexCreationService : IHostedService
{
    private readonly RedisConnectionProvider _provider;
    public IndexCreationService(RedisConnectionProvider provider)
    {
        _provider = provider;
    }
    
    public async Task StartAsync(CancellationToken cancellationToken)
    {
        await _provider.Connection.CreateIndexAsync(typeof(Person));
    }

    public Task StopAsync(CancellationToken cancellationToken)
    {
        return Task.CompletedTask;
    }
}

接下来，将以下内容添加到 Program.cs 以在启动时注册服务：

builder.Services.AddHostedService<IndexCreationService>();

注入RedisConnectionProvider

Redis OM 使用 RedisConnectionProvider 类来处理与 Redis 的连接，并提供了可用于与 Redis 交互的类。要使用它，只需将 RedisConnectionProvider 的实例注入到您的应用程序中。在您的 Program.cs 文件中，添加：

builder.Services.AddSingleton(new RedisConnectionProvider(builder.Configuration["REDIS_CONNECTION_STRING"]));

这将从配置中提取您的连接字符串并初始化提供程序。现在，提供程序将在您的控制器/服务中可用以供使用。

创建PeopleController

最后的拼图是为我们的People API编写实际的API控制器。在controllers目录中，添加文件PeopleController.cs，PeopleController类的骨架将是：

using Microsoft.AspNetCore.Mvc;
using Redis.OM.Searching;
using Redis.OM.Skeleton.Model;

namespace Redis.OM.Skeleton.Controllers;

[ApiController]
[Route("[controller]")]
public class PeopleController : ControllerBase
{

}

注入RedisConnectionProvider

要与Redis交互，请注入RedisConnectionProvider。在此依赖注入过程中，提取一个RedisCollection实例，这将允许使用流畅的接口来查询Redis中的文档。

private readonly RedisCollection<Person> _people;
private readonly RedisConnectionProvider _provider;
public PeopleController(RedisConnectionProvider provider)
{
    _provider = provider;
    _people = (RedisCollection<Person>)provider.RedisCollection<Person>();
}

添加创建人员的路由

添加到API的第一个路由是一个用于创建人的POST请求，使用RedisCollection，只需调用InsertAsync，并传入person对象：

[HttpPost]
public async Task<Person> AddPerson([FromBody] Person person)
{
    await _people.InsertAsync(person);
    return person;
}

添加按年龄筛选的路由

添加到API的第一个过滤路由将允许用户按最小和最大年龄进行过滤。使用RedisCollection可用的LINQ接口，这是一个简单的操作：

[HttpGet("filterAge")]
public IList<Person> FilterByAge([FromQuery] int minAge, [FromQuery] int maxAge)
{        
    return _people.Where(x => x.Age >= minAge && x.Age <= maxAge).ToList();
}

按地理位置筛选

Redis OM 有一个 GeoLoc 数据结构，它的一个实例由 Address 模型索引，使用 RedisCollection，可以通过 GeoFilter 方法以及你想要过滤的字段来查找特定位置半径内的所有对象：

[HttpGet("filterGeo")]
public IList<Person> FilterByGeo([FromQuery] double lon, [FromQuery] double lat, [FromQuery] double radius, [FromQuery] string unit)
{
    return _people.GeoFilter(x => x.Address!.Location, lon, lat, radius, Enum.Parse<GeoLocDistanceUnit>(unit)).ToList();
}

按精确字符串过滤

当模型中的字符串属性被标记为Indexed时，例如FirstName和LastName，Redis OM 可以对它们执行精确的文本匹配。例如，以下两条路由通过PostalCode和名称进行过滤，展示了精确的字符串匹配。

[HttpGet("filterName")]
public IList<Person> FilterByName([FromQuery] string firstName, [FromQuery] string lastName)
{
    return _people.Where(x => x.FirstName == firstName && x.LastName == lastName).ToList();
}

[HttpGet("postalCode")]
public IList<Person> FilterByPostalCode([FromQuery] string postalCode)
{
    return _people.Where(x => x.Address!.PostalCode == postalCode).ToList();
}

使用全文搜索进行过滤

当模型中的属性被标记为Searchable时，例如StreetAddress和PersonalStatement，您可以执行全文搜索，查看PersonalStatement和StreetAddress的过滤器：

[HttpGet("fullText")]
public IList<Person> FilterByPersonalStatement([FromQuery] string text){
    return _people.Where(x => x.PersonalStatement == text).ToList();
}

[HttpGet("streetName")]
public IList<Person> FilterByStreetName([FromQuery] string streetName)
{
    return _people.Where(x => x.Address!.StreetName == streetName).ToList();
}

按数组成员过滤

当一个字符串数组或列表被标记为Indexed时，Redis OM 可以使用数组或列表的Contains方法来过滤所有包含给定字符串的记录。例如，我们的Person模型有一个技能列表，您可以通过添加以下路由来查询。

[HttpGet("skill")]
public IList<Person> FilterBySkill([FromQuery] string skill)
{
    return _people.Where(x => x.Skills.Contains(skill)).ToList();
}

更新人员信息

在Redis Stack中使用Redis OM更新文档可以通过首先实例化person对象，进行所需的更改，然后在集合上调用Save来完成。集合负责跟踪在其中实例化的实体的更新；因此，它将跟踪并应用您在其中进行的任何更新。例如，添加以下路由以根据ID更新Person的年龄：

[HttpPatch("updateAge/{id}")]
public IActionResult UpdateAge([FromRoute] string id, [FromBody] int newAge)
{
    foreach (var person in _people.Where(x => x.Id == id))
    {
        person.Age = newAge;
    }
    _people.Save();
    return Accepted();
}

删除一个人

从Redis中删除文档可以使用Unlink。只需要调用Unlink，传入键名即可。给定一个id，我们可以使用前缀和id来重构键名：

[HttpDelete("{id}")]
public IActionResult DeletePerson([FromRoute] string id)
{
    _provider.Connection.Unlink($"Person:{id}");
    return NoContent();
}

运行应用程序

现在剩下的就是运行应用程序并进行测试。你可以通过运行dotnet run来做到这一点，应用程序现在暴露在5000端口上，并且应该有一个Swagger UI，你可以在http://localhost:5000/swagger上使用它来测试API。在GitHub repo中有几个脚本，以及一些数据文件，用于通过API将一些人插入到Redis中。

使用Redis Insight查看数据

您可以安装Redis Insight GUI或使用运行在http://localhost:8001/上的Redis Insight GUI。

您可以按照以下步骤查看数据：

接受最终用户许可协议

Accept EULA

点击添加Redis数据库按钮

Add Redis Database Button

输入您的Redis服务器的主机名和端口名。如果您使用的是docker镜像，这是localhost和6379，并为您的数据库设置一个别名

Configure Redis Insight Database

点击 Add Redis Database.

资源

本教程的源代码可以在GitHub上找到。

RedisOM 用于 .NET

先决条件

跳转到代码

运行 Redis Stack

创建项目

配置应用程序

连接字符串规范

创建模型

创建索引

注入RedisConnectionProvider

创建PeopleController

注入RedisConnectionProvider

添加创建人员的路由

添加按年龄筛选的路由

按地理位置筛选

按精确字符串过滤

使用全文搜索进行过滤

按数组成员过滤

更新人员信息

删除一个人

运行应用程序

使用Redis Insight查看数据

资源

本页内容