Skip to content

Tidy README #6

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
dmytro-khmara merged 1 commit into from
Apr 25, 2026
Merged

Tidy README #6

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 21 additions & 19 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,22 +1,22 @@
# StrEnum.AspNetCore

Allows to use [StrEnum](https://github.com/StrEnum/StrEnum/) string enums with ASP.NET Core.
Lets you use [StrEnum](https://github.com/StrEnum/StrEnum/) string enums with ASP.NET Core.

Supports ASP.NET Core 6-10.

ASP.NET Core 5 supported in v2.0.0.
Supports ASP.NET Core 6 – 10. For ASP.NET Core 5, use v2.0.0.

## Installation

You can install [StrEnum.AspNetCore](https://www.nuget.org/packages/StrEnum.AspNetCore/) using the .NET CLI:
Install [StrEnum.AspNetCore](https://www.nuget.org/packages/StrEnum.AspNetCore/) via the .NET CLI:

```
dotnet add package StrEnum.AspNetCore
```

## Usage

If you're using `WebApplicationBuilder`, add the call to `AddStringEnums()` into your `Program.cs`:
### Registering the binder

If you're using `WebApplicationBuilder`, call `AddStringEnums()` in `Program.cs`:

```csharp
var builder = WebApplication.CreateBuilder(args);
Expand All @@ -26,18 +26,18 @@ builder.Services
.AddStringEnums();
```

If you're using the ASP.NET Core 3.1-5 `IWebHostBuilder`, call `AddStringEnums()` in the `ConfigureServices` method of your `Startup.cs`:
For the ASP.NET Core 3.1–5 `IWebHostBuilder`, call `AddStringEnums()` in `ConfigureServices` in `Startup.cs`:

```csharp
public void ConfigureServices(IServiceCollection services)
{
services
.AddControllers()
.AddStringEnums();
services
.AddControllers()
.AddStringEnums();
}
```

All set. Let's now create a string enum and a model that contains it:
### Defining a string enum and a model

```csharp
public class Sport : StringEnum<Sport>
Expand All @@ -53,39 +53,41 @@ public class Race
}
```

You can bind string enums to the request body and return them in the response. In your controller, add the following:
### Binding string enums in controllers

Bind from the request body and serialize them back in the response:

```csharp
[HttpPost]
public ActionResult<Race> BodyPost([FromBody] Race race) // race.Sport is correctly deserialized
public ActionResult<Race> BodyPost([FromBody] Race race) // race.Sport is deserialized correctly
{
return Ok(race); // race.Sport is serialized back
}
```

You can also bind string enums to a URL:
Bind from a route parameter:

```csharp
[HttpGet]
[Route("{sport}")]
public ActionResult<ResponseWithStrEnum> GetFromRoute(Sport sport) {...}
public ActionResult<ResponseWithStrEnum> GetFromRoute(Sport sport) { ... }
```

To a query string parameter:
Bind from a query string parameter:

```csharp
[HttpGet]
[Route("get")]
public ActionResult<ResponseWithStrEnum> GetFromQuery([FromQuery]Sport sport) {...}
public ActionResult<ResponseWithStrEnum> GetFromQuery([FromQuery] Sport sport) { ... }
// `get?sport=trail_running` binds to Sport.TrailRunning
```

And to an array of query string parameters:
Bind to an array of query string parameters:

```csharp
[HttpGet]
[Route("get")]
public ActionResult<ResponseWithStrEnum> GetFromQuery([FromQuery] Sport[] sports) {...}
public ActionResult<ResponseWithStrEnum> GetFromQuery([FromQuery] Sport[] sports) { ... }
// `get?sports=trail_running&sports=road_cycling` binds to [Sport.TrailRunning, Sport.RoadCycling]
```

Expand Down
Loading