Skip to content

Commit 583c580

Browse files
willysoftwillysoft
committed
docs: update README with detailed usage and features for AutoQuery
- Enhanced the README to include comprehensive documentation for AutoQuery and AutoQuery.AspNetCore. - Added sections for features, installation, and usage examples in .NET and ASP.NET Core applications. - Included code samples for query options, filter logic, and controller integration.
1 parent 27ddf00 commit 583c580

File tree

2 files changed

+180
-3
lines changed

2 files changed

+180
-3
lines changed

‎README.md‎

Lines changed: 175 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,18 +2,191 @@
22

33
[![GitHub Actions](https://github.com/willysoft/AutoQuery/workflows/build-debug/badge.svg)](https://github.com/willysoft/AutoQuery/actions) [![GitHub Actions](https://github.com/willysoft/AutoQuery/workflows/build-release/badge.svg)](https://github.com/willysoft/AutoQuery/actions) [![Releases](https://img.shields.io/github/v/release/willysoft/AutoQuery.svg)](https://github.com/willysoft/AutoQuery/releases) [![NuGet](https://img.shields.io/nuget/vpre/AutoQuery.svg)](https://www.nuget.org/packages/AutoQuery/) [![NuGet](https://img.shields.io/nuget/vpre/AutoQuery.AspNetCore.svg)](https://www.nuget.org/packages/AutoQuery.AspNetCore/)
44

5-
`AutoQuery` is a middleware and toolset for ASP.NET Core that enables filtering HTTP requests based on the local port. This package is ideal for scenarios where certain operations must be restricted to specific ports, enhancing application security and traffic control.
5+
`AutoQuery` is a powerful library for .NET that simplifies dynamic query building, filtering, and pagination using expression trees. It provides a flexible and extensible way to handle complex query scenarios. The `AutoQuery.AspNetCore` package extends this functionality with seamless integration into ASP.NET Core applications, offering middleware support and field projection capabilities.
6+
7+
## Features
8+
9+
- **Dynamic Query Building**: Generate queries dynamically using expression trees.
10+
- **Filtering**: Apply flexible filtering logic to refine query results.
11+
- **Field Projection**: Return only the specified fields to optimize API responses.
12+
- **Pagination and Sorting**: Built-in support for pagination and sorting.
13+
- **ASP.NET Core Integration**: Middleware support for easy integration into ASP.NET Core projects.
614

715
## Installation
816

9-
Install the package via NuGet:
17+
### AutoQuery
18+
19+
Install the core library via NuGet:
1020

1121
```bash
1222
dotnet add package AutoQuery
1323
```
1424

25+
### AutoQuery.AspNetCore
26+
27+
For ASP.NET Core integration, install the extension package:
28+
29+
```bash
30+
dotnet add package AutoQuery.AspNetCore
31+
```
32+
1533
## Getting Started
1634

35+
### Using AutoQuery in .NET Applications
36+
37+
1. Define a query options class implementing the `IQueryOptions` interface:
38+
```csharp
39+
public class UserQueryOptions : IQueryPagedOptions
40+
{
41+
public int[]? FilterIds { get; set; }
42+
public string? FilterName { get; set; }
43+
public string? Fields { get; set; }
44+
public string? Sort { get; set; }
45+
public int? Page { get; set; }
46+
public int? PageSize { get; set; }
47+
}
48+
```
49+
2. Configure the filter logic by implementing `IFilterQueryConfiguration`:
50+
```csharp
51+
public class UserQueryConfiguration : IFilterQueryConfiguration<UserQueryOptions, User>
52+
{
53+
public void Configure(FilterQueryBuilder<UserQueryOptions, User> builder)
54+
{
55+
builder.Property(q => q.FilterIds, d => d.Id)
56+
.HasCollectionContains();
57+
builder.Property(q => q.FilterName, d => d.Name)
58+
.HasEqual();
59+
}
60+
}
61+
```
62+
3. Use `AutoQuery` to process queries:
63+
```csharp
64+
var queryProcessor = new QueryProcessor();
65+
queryProcessor.ApplyConfigurationsFromAssembly(Assembly.GetExecutingAssembly());
66+
67+
var users = new List<User>
68+
{
69+
new User(4, "Bob Brown", "[email protected]", new DateTime(1988, 12, 30)),
70+
new User(1, "John Doe", "[email protected]", new DateTime(1990, 1, 1)),
71+
new User(3, "Alice Johnson", "[email protected]", new DateTime(1992, 8, 23)),
72+
new User(5, "Charlie Davis", "[email protected]", new DateTime(1995, 3, 10)),
73+
new User(2, "Jane Smith", "[email protected]", new DateTime(1985, 5, 15)),
74+
};
75+
76+
var result = users.AsQueryable().ApplyQuery(queryProcessor, new UserQueryOptions()
77+
{
78+
Fields = "Id,Name",
79+
Sort = "-Id",
80+
FilterIds = new[] { 3, 4 },
81+
FilterName = "Alice Johnson"
82+
}).ToArray();
83+
84+
Console.WriteLine("Filtered Users:");
85+
foreach (var user in result)
86+
{
87+
Console.WriteLine($"{user.Id}: {user.Name}");
88+
}
89+
```
90+
4. Example Output:
91+
```plaintext
92+
Filtered Users:
93+
4: Bob Brown
94+
3: Alice Johnson
95+
```
96+
97+
### Using AutoQuery.AspNetCore in ASP.NET Core Applications
98+
99+
1. Define a query options class implementing the `IQueryOptions` interface:
100+
```csharp
101+
public class UserQueryOptions : IQueryPagedOptions
102+
{
103+
[FromQuery(Name = "filter[ids]")]
104+
public int[]? FilterIds { get; set; }
105+
[FromQuery(Name = "filter[name]")]
106+
public string? FilterName { get; set; }
107+
[FromQuery(Name = "fields")]
108+
public string? Fields { get; set; }
109+
[FromQuery(Name = "sort")]
110+
public string? Sort { get; set; }
111+
[FromQuery(Name = "page")]
112+
public int? Page { get; set; }
113+
[FromQuery(Name = "pageSize")]
114+
public int? PageSize { get; set; }
115+
}
116+
```
117+
2. Configure the filter logic by implementing `IFilterQueryConfiguration`:
118+
```csharp
119+
public class UserQueryConfiguration : IFilterQueryConfiguration<UserQueryOptions, User>
120+
{
121+
public void Configure(FilterQueryBuilder<UserQueryOptions, User> builder)
122+
{
123+
builder.Property(q => q.FilterIds, d => d.Id)
124+
.HasCollectionContains();
125+
builder.Property(q => q.FilterName, d => d.Name)
126+
.HasEqual();
127+
}
128+
}
129+
```
130+
3. Register the required services in `Program.cs`:
131+
```csharp
132+
// Add AutoQuery services
133+
builder.Services.AddAutoQuery(Assembly.GetEntryAssembly());
134+
```
135+
4. Create a controller to handle queries:
136+
```csharp
137+
[ApiController]
138+
[Route("[controller]")]
139+
public class UsersController : ControllerBase
140+
{
141+
private readonly IQueryProcessor _queryProcessor;
142+
143+
private List<User> users = new List<User>
144+
{
145+
new User(4, "Bob Brown", "[email protected]", new DateTime(1988, 12, 30)),
146+
new User(1, "John Doe", "[email protected]", new DateTime(1990, 1, 1)),
147+
new User(3, "Alice Johnson", "[email protected]", new DateTime(1992, 8, 23)),
148+
new User(5, "Charlie Davis", "[email protected]", new DateTime(1995, 3, 10)),
149+
new User(2, "Jane Smith", "[email protected]", new DateTime(1985, 5, 15)),
150+
};
151+
152+
public UsersController(IQueryProcessor queryProcessor)
153+
{
154+
_queryProcessor = queryProcessor;
155+
}
156+
157+
[HttpGet]
158+
[EnableFieldProjection]
159+
public IActionResult Get(UserQueryOptions queryOptions)
160+
{
161+
var result = users.AsQueryable()
162+
.ApplyQueryPaged(_queryProcessor, queryOptions);
163+
return Ok(result);
164+
}
165+
}
166+
```
167+
5. Example Request:
168+
```http
169+
GET /Users?filter[ids]=1&filter[ids]=3&fields=Id,Name&sort=-Id&page=1&pageSize=2
170+
```
171+
6. Example Response:
172+
```json
173+
{
174+
"datas": [
175+
{
176+
"id": 3,
177+
"name": "Alice Johnson"
178+
},
179+
{
180+
"id": 1,
181+
"name": "John Doe"
182+
}
183+
],
184+
"count": 2,
185+
"totalPages": 1,
186+
"page": 1
187+
}
188+
```
189+
17190
## Contribution
18191

19192
Contributions are welcome! Feel free to submit issues or pull requests to improve the project.

‎sample/AutoQueryDemo/Program.cs‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,4 +20,8 @@
2020
FilterIds = [3, 4],
2121
}).ToArray();
2222

23-
Console.WriteLine("All Users:");
23+
Console.WriteLine("Filtered Users:");
24+
foreach (var user in result)
25+
{
26+
Console.WriteLine($"{user.Id}: {user.Name}");
27+
}

0 commit comments

Comments
 (0)