Skip to content

Commit ab12fb5

Browse files
ElderJamesElderJames
committed
add docs
1 parent 139dd7b commit ab12fb5

8 files changed

+540
-12
lines changed

‎README.md

+38-12
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,44 @@
1-
# NCaptcha
2-
3-
Captcha in .NET Core
1+
<p align="right">
2+
<span>English</span> |
3+
<a href="./README_CN.md">中文</a>
4+
</p>
5+
<h1 align="center">NCaptcha
6+
<sup style="font-size:10px;">Captcha in .NET Core</sup>
7+
</h1>
48

59
[![Build Status](https://dev.azure.com/elderjames/NCaptcha-Pipelines/_apis/build/status/ElderJames.NCaptcha?branchName=master)](https://dev.azure.com/elderjames/NCaptcha-Pipelines/_build/latest?definitionId=1&branchName=master)
610

11+
## What is NCaptcha?
12+
13+
NCaptcha is the componentized captcha integration scheme in .NET Core that base on .NET Standard 2.0 and easy to expand.
14+
It can help you implement security mechanism based on captcha with many out-of-the-box solutions or integrate your own implementation very easily.Because its implementation is componentized that allows you to easily implement what needs to be modified or replaced.
15+
16+
Components in NCaptcha are divided into "Generator","Validator","Target" and "State".
17+
So far, session-based images, emails, and SMS solutions have been implement.
718

819
## Nuget Packages
920

10-
| Package | NuGet Stable | Downloads |
11-
| ------- | -------- | ------- |
12-
| [NCaptcha](https://www.nuget.org/packages/NCaptcha/) | [![NCaptcha](https://img.shields.io/nuget/v/NCaptcha.svg)](https://www.nuget.org/packages/NCaptcha/) | [![NCaptcha](https://img.shields.io/nuget/dt/NCaptcha.svg)](https://www.nuget.org/packages/NCaptcha/) |
13-
| [NCaptcha.State.Session](https://www.nuget.org/packages/NCaptcha.State.Session/) | [![NCaptcha.State.Session](https://img.shields.io/nuget/v/NCaptcha.State.Session.svg)](https://www.nuget.org/packages/NCaptcha.State.Session/) | [![NCaptcha.State.Session](https://img.shields.io/nuget/dt/NCaptcha.State.Session.svg)](https://www.nuget.org/packages/NCaptcha.State.Session/) |
14-
| [NCaptcha.Targets.Images](https://www.nuget.org/packages/NCaptcha.Targets.Images/) | [![NCaptcha.Targets.Images](https://img.shields.io/nuget/v/NCaptcha.Targets.Images.svg)](https://www.nuget.org/packages/NCaptcha.Targets.Images/) | [![NCaptcha.Targets.Images](https://img.shields.io/nuget/dt/NCaptcha.Targets.Images.svg)](https://www.nuget.org/packages/NCaptcha.Targets.Images/) |
15-
| [NCaptcha.Targets.Email](https://www.nuget.org/packages/NCaptcha.Targets.Email/) | [![NCaptcha.Targets.Email](https://img.shields.io/nuget/v/NCaptcha.Targets.Email.svg)](https://www.nuget.org/packages/NCaptcha.Targets.Email/) | [![NCaptcha.Targets.Email](https://img.shields.io/nuget/dt/NCaptcha.Targets.Email.svg)](https://www.nuget.org/packages/NCaptcha.Targets.Email/) |
16-
| [NCaptcha.AspNetCore](https://www.nuget.org/packages/NCaptcha.AspNetCore/) | [![NCaptcha.AspNetCore](https://img.shields.io/nuget/v/NCaptcha.AspNetCore.svg)](https://www.nuget.org/packages/NCaptcha.AspNetCore/) | [![NCaptcha.AspNetCore](https://img.shields.io/nuget/dt/NCaptcha.AspNetCore.svg)](https://www.nuget.org/packages/NCaptcha.AspNetCore/) |
17-
| [NCaptcha.AspNetCore.SessionImages](https://www.nuget.org/packages/NCaptcha.AspNetCore.SessionImages/) | [![NCaptcha.AspNetCore.SessionImages](https://img.shields.io/nuget/v/NCaptcha.AspNetCore.SessionImages.svg)](https://www.nuget.org/packages/NCaptcha.AspNetCore.SessionImages/) | [![NCaptcha.AspNetCore.SessionImages](https://img.shields.io/nuget/dt/NCaptcha.AspNetCore.SessionImages.svg)](https://www.nuget.org/packages/NCaptcha.AspNetCore.SessionImages/) |
18-
| [NCaptcha.AspNetCore.SessionEmail](https://www.nuget.org/packages/NCaptcha.AspNetCore.SessionEmail/) | [![NCaptcha.AspNetCore.SessionEmail](https://img.shields.io/nuget/v/NCaptcha.AspNetCore.SessionEmail.svg)](https://www.nuget.org/packages/NCaptcha.AspNetCore.SessionEmail/) | [![NCaptcha.AspNetCore.SessionEmail](https://img.shields.io/nuget/dt/NCaptcha.AspNetCore.SessionEmail.svg)](https://www.nuget.org/packages/NCaptcha.AspNetCore.SessionEmail/) |
21+
| Package | NuGet Stable | Downloads |
22+
| ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
23+
| [NCaptcha](https://www.nuget.org/packages/NCaptcha/) | [![NCaptcha](https://img.shields.io/nuget/v/NCaptcha.svg)](https://www.nuget.org/packages/NCaptcha/) | [![NCaptcha](https://img.shields.io/nuget/dt/NCaptcha.svg)](https://www.nuget.org/packages/NCaptcha/) |
24+
| [NCaptcha.State.Session](https://www.nuget.org/packages/NCaptcha.State.Session/) | [![NCaptcha.State.Session](https://img.shields.io/nuget/v/NCaptcha.State.Session.svg)](https://www.nuget.org/packages/NCaptcha.State.Session/) | [![NCaptcha.State.Session](https://img.shields.io/nuget/dt/NCaptcha.State.Session.svg)](https://www.nuget.org/packages/NCaptcha.State.Session/) |
25+
| [NCaptcha.Targets.Images](https://www.nuget.org/packages/NCaptcha.Targets.Images/) | [![NCaptcha.Targets.Images](https://img.shields.io/nuget/v/NCaptcha.Targets.Images.svg)](https://www.nuget.org/packages/NCaptcha.Targets.Images/) | [![NCaptcha.Targets.Images](https://img.shields.io/nuget/dt/NCaptcha.Targets.Images.svg)](https://www.nuget.org/packages/NCaptcha.Targets.Images/) |
26+
| [NCaptcha.Targets.Email](https://www.nuget.org/packages/NCaptcha.Targets.Email/) | [![NCaptcha.Targets.Email](https://img.shields.io/nuget/v/NCaptcha.Targets.Email.svg)](https://www.nuget.org/packages/NCaptcha.Targets.Email/) | [![NCaptcha.Targets.Email](https://img.shields.io/nuget/dt/NCaptcha.Targets.Email.svg)](https://www.nuget.org/packages/NCaptcha.Targets.Email/) |
27+
| [NCaptcha.Targets.Sms](https://www.nuget.org/packages/NCaptcha.Targets.Sms/) | [![NCaptcha.Targets.Sms](https://img.shields.io/nuget/v/NCaptcha.Targets.Sms.svg)](https://www.nuget.org/packages/NCaptcha.Targets.Sms/) | [![NCaptcha.Targets.Sms](https://img.shields.io/nuget/dt/NCaptcha.Targets.Sms.svg)](https://www.nuget.org/packages/NCaptcha.Targets.Sms/) |
28+
| [NCaptcha.Targets.Sms.Aliyun](https://www.nuget.org/packages/NCaptcha.Targets.Sms.Aliyun/) | [![NCaptcha.Targets.Sms.Aliyun](https://img.shields.io/nuget/v/NCaptcha.Targets.Sms.Aliyun.svg)](https://www.nuget.org/packages/NCaptcha.Targets.Sms.Aliyun/) | [![NCaptcha.Targets.Sms.Aliyun](https://img.shields.io/nuget/dt/NCaptcha.Targets.Sms.Aliyun.svg)](https://www.nuget.org/packages/NCaptcha.Targets.Sms.Aliyun/) |
29+
| [NCaptcha.AspNetCore](https://www.nuget.org/packages/NCaptcha.AspNetCore/) | [![NCaptcha.AspNetCore](https://img.shields.io/nuget/v/NCaptcha.AspNetCore.svg)](https://www.nuget.org/packages/NCaptcha.AspNetCore/) | [![NCaptcha.AspNetCore](https://img.shields.io/nuget/dt/NCaptcha.AspNetCore.svg)](https://www.nuget.org/packages/NCaptcha.AspNetCore/) |
30+
| [NCaptcha.AspNetCore.SessionImages](https://www.nuget.org/packages/NCaptcha.AspNetCore.SessionImages/) | [![NCaptcha.AspNetCore.SessionImages](https://img.shields.io/nuget/v/NCaptcha.AspNetCore.SessionImages.svg)](https://www.nuget.org/packages/NCaptcha.AspNetCore.SessionImages/) | [![NCaptcha.AspNetCore.SessionImages](https://img.shields.io/nuget/dt/NCaptcha.AspNetCore.SessionImages.svg)](https://www.nuget.org/packages/NCaptcha.AspNetCore.SessionImages/) |
31+
| [NCaptcha.AspNetCore.SessionEmail](https://www.nuget.org/packages/NCaptcha.AspNetCore.SessionEmail/) | [![NCaptcha.AspNetCore.SessionEmail](https://img.shields.io/nuget/v/NCaptcha.AspNetCore.SessionEmail.svg)](https://www.nuget.org/packages/NCaptcha.AspNetCore.SessionEmail/) | [![NCaptcha.AspNetCore.SessionEmail](https://img.shields.io/nuget/dt/NCaptcha.AspNetCore.SessionEmail.svg)](https://www.nuget.org/packages/NCaptcha.AspNetCore.SessionEmail/) |
32+
| [NCaptcha.AspNetCore.SessionSms](https://www.nuget.org/packages/NCaptcha.AspNetCore.SessionSms/) | [![NCaptcha.AspNetCore.SessionSms](https://img.shields.io/nuget/v/NCaptcha.AspNetCore.SessionSms.svg)](https://www.nuget.org/packages/NCaptcha.AspNetCore.SessionSms/) | [![NCaptcha.AspNetCore.SessionSms](https://img.shields.io/nuget/dt/NCaptcha.AspNetCore.SessionSms.svg)](https://www.nuget.org/packages/NCaptcha.AspNetCore.SessionSms/) |
33+
34+
## Usage
35+
36+
### Use out-of-the-box solutions
37+
38+
- [Images captcha base on session](./docs/en/session-image.md)
39+
- [Email captcha base on session](./docs/en/session-email.md)
40+
- [Sms captcha base on session](./docs/en/session-sms.md),
41+
42+
At present, the following SMS service providers have been implemented:
43+
44+
- aliyun

‎README_CN.md

+44
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
<p align="right">
2+
<a href="./README.md">English</a> |
3+
<span>中文</a>
4+
</p>
5+
<h1 align="center">NCaptcha
6+
<sup style="font-size:10px;">.NET Core 验证码组件库</sup>
7+
</h1>
8+
9+
[![Build Status](https://dev.azure.com/elderjames/NCaptcha-Pipelines/_apis/build/status/ElderJames.NCaptcha?branchName=master)](https://dev.azure.com/elderjames/NCaptcha-Pipelines/_build/latest?definitionId=1&branchName=master)
10+
11+
## 什么是 NCaptcha?
12+
13+
NCaptcha 是面向 .NET Core 的组件化的验证码集成方案，基于.NET Standard 2.0，并且非常易于扩展。
14+
15+
它通过许多开箱即用的解决方案帮助您实现基于验证码的安全机制，也可以让您非常方便地集成您自己的实现。因为它的实现是组件化的，允许您方便地实现需要修改或替换的部分。
16+
17+
NCaptcha 中的组件分为“生成器”、“验证器”、“目标实现” 和“状态维持”四部分。目前为止，已经实现了基于 Session 的图片、邮件和短信方案。
18+
19+
## Nuget 包
20+
21+
| Package | NuGet Stable | Downloads |
22+
| ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
23+
| [NCaptcha](https://www.nuget.org/packages/NCaptcha/) | [![NCaptcha](https://img.shields.io/nuget/v/NCaptcha.svg)](https://www.nuget.org/packages/NCaptcha/) | [![NCaptcha](https://img.shields.io/nuget/dt/NCaptcha.svg)](https://www.nuget.org/packages/NCaptcha/) |
24+
| [NCaptcha.State.Session](https://www.nuget.org/packages/NCaptcha.State.Session/) | [![NCaptcha.State.Session](https://img.shields.io/nuget/v/NCaptcha.State.Session.svg)](https://www.nuget.org/packages/NCaptcha.State.Session/) | [![NCaptcha.State.Session](https://img.shields.io/nuget/dt/NCaptcha.State.Session.svg)](https://www.nuget.org/packages/NCaptcha.State.Session/) |
25+
| [NCaptcha.Targets.Images](https://www.nuget.org/packages/NCaptcha.Targets.Images/) | [![NCaptcha.Targets.Images](https://img.shields.io/nuget/v/NCaptcha.Targets.Images.svg)](https://www.nuget.org/packages/NCaptcha.Targets.Images/) | [![NCaptcha.Targets.Images](https://img.shields.io/nuget/dt/NCaptcha.Targets.Images.svg)](https://www.nuget.org/packages/NCaptcha.Targets.Images/) |
26+
| [NCaptcha.Targets.Email](https://www.nuget.org/packages/NCaptcha.Targets.Email/) | [![NCaptcha.Targets.Email](https://img.shields.io/nuget/v/NCaptcha.Targets.Email.svg)](https://www.nuget.org/packages/NCaptcha.Targets.Email/) | [![NCaptcha.Targets.Email](https://img.shields.io/nuget/dt/NCaptcha.Targets.Email.svg)](https://www.nuget.org/packages/NCaptcha.Targets.Email/) |
27+
| [NCaptcha.Targets.Sms](https://www.nuget.org/packages/NCaptcha.Targets.Sms/) | [![NCaptcha.Targets.Sms](https://img.shields.io/nuget/v/NCaptcha.Targets.Sms.svg)](https://www.nuget.org/packages/NCaptcha.Targets.Sms/) | [![NCaptcha.Targets.Sms](https://img.shields.io/nuget/dt/NCaptcha.Targets.Sms.svg)](https://www.nuget.org/packages/NCaptcha.Targets.Sms/) |
28+
| [NCaptcha.Targets.Sms.Aliyun](https://www.nuget.org/packages/NCaptcha.Targets.Sms.Aliyun/) | [![NCaptcha.Targets.Sms.Aliyun](https://img.shields.io/nuget/v/NCaptcha.Targets.Sms.Aliyun.svg)](https://www.nuget.org/packages/NCaptcha.Targets.Sms.Aliyun/) | [![NCaptcha.Targets.Sms.Aliyun](https://img.shields.io/nuget/dt/NCaptcha.Targets.Sms.Aliyun.svg)](https://www.nuget.org/packages/NCaptcha.Targets.Sms.Aliyun/) |
29+
| [NCaptcha.AspNetCore](https://www.nuget.org/packages/NCaptcha.AspNetCore/) | [![NCaptcha.AspNetCore](https://img.shields.io/nuget/v/NCaptcha.AspNetCore.svg)](https://www.nuget.org/packages/NCaptcha.AspNetCore/) | [![NCaptcha.AspNetCore](https://img.shields.io/nuget/dt/NCaptcha.AspNetCore.svg)](https://www.nuget.org/packages/NCaptcha.AspNetCore/) |
30+
| [NCaptcha.AspNetCore.SessionImages](https://www.nuget.org/packages/NCaptcha.AspNetCore.SessionImages/) | [![NCaptcha.AspNetCore.SessionImages](https://img.shields.io/nuget/v/NCaptcha.AspNetCore.SessionImages.svg)](https://www.nuget.org/packages/NCaptcha.AspNetCore.SessionImages/) | [![NCaptcha.AspNetCore.SessionImages](https://img.shields.io/nuget/dt/NCaptcha.AspNetCore.SessionImages.svg)](https://www.nuget.org/packages/NCaptcha.AspNetCore.SessionImages/) |
31+
| [NCaptcha.AspNetCore.SessionEmail](https://www.nuget.org/packages/NCaptcha.AspNetCore.SessionEmail/) | [![NCaptcha.AspNetCore.SessionEmail](https://img.shields.io/nuget/v/NCaptcha.AspNetCore.SessionEmail.svg)](https://www.nuget.org/packages/NCaptcha.AspNetCore.SessionEmail/) | [![NCaptcha.AspNetCore.SessionEmail](https://img.shields.io/nuget/dt/NCaptcha.AspNetCore.SessionEmail.svg)](https://www.nuget.org/packages/NCaptcha.AspNetCore.SessionEmail/) |
32+
| [NCaptcha.AspNetCore.SessionSms](https://www.nuget.org/packages/NCaptcha.AspNetCore.SessionSms/) | [![NCaptcha.AspNetCore.SessionSms](https://img.shields.io/nuget/v/NCaptcha.AspNetCore.SessionSms.svg)](https://www.nuget.org/packages/NCaptcha.AspNetCore.SessionSms/) | [![NCaptcha.AspNetCore.SessionSms](https://img.shields.io/nuget/dt/NCaptcha.AspNetCore.SessionSms.svg)](https://www.nuget.org/packages/NCaptcha.AspNetCore.SessionSms/) |
33+
34+
## 使用方法
35+
36+
### 使用开箱即用方案
37+
38+
- [基于 Session 的图片验证码](./docs/cn/session-image.md)
39+
- [基于 Session 的邮件验证码](./docs/cn/session-email.md)
40+
- [基于 Session 的短信验证码](./docs/cn/session-sms.md)
41+
42+
目前已实现以下短信服务商：
43+
44+
- 阿里云

‎docs/cn/session-email.md

+81
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
# 基于 Session 的邮件验证码
2+
3+
0. 安装需要的 Nuget 包
4+
5+
```ps
6+
Install-Package NCaptcha.AspNetCore.SessionEmail
7+
```
8+
9+
1. 在 `appsettings.json` 文件中添加配置.
10+
11+
```json
12+
"CaptchaEmail": {
13+
"UserName": "",
14+
"Password": "",
15+
"MailFromName": "",
16+
"MailFromAddress": "",
17+
"ServerHost": "",
18+
"ServerPort": 0,
19+
"UseSsl": false
20+
}
21+
```
22+
23+
2. 注册依赖注入服务
24+
25+
```cs
26+
public void ConfigureServices(IServiceCollection services)
27+
{
28+
services.AddSession();
29+
services.AddSessionBasedEmailCaptcha(Configuration.GetSection("CaptchaEmail").Bind);
30+
}
31+
```
32+
33+
3. 配置 Session
34+
35+
```cs
36+
public void Configure(IApplicationBuilder app)
37+
{
38+
app.UseSession();
39+
}
40+
```
41+
42+
4. 添加一个发送验证码的 Api
43+
44+
```cs
45+
public class LoginModel : PageModel
46+
{
47+
private readonly ICaptchaGenerator _captchaGenerator;
48+
49+
public LoginModel(ICaptchaGenerator captchaGenerator)
50+
{
51+
_captchaGenerator = captchaGenerator;
52+
}
53+
54+
public async Task OnPostSendCaptchaAsync() => await _captchaGenerator.GenerateCaptchaAsync();
55+
}
56+
57+
```
58+
59+
5. 验证码验证
60+
61+
```cs
62+
public class LoginModel : PageModel
63+
{
64+
private readonly ICaptchaValidator _captchaValidator;
65+
66+
public LoginModel(ICaptchaValidator captchaValidator)
67+
{
68+
_captchaValidator = captchaValidator;
69+
}
70+
71+
public async Task<IActionResult> OnPostAsync()
72+
{
73+
if (!await _captchaValidator.ValidateAsync(Input.Captcha))
74+
{
75+
ModelState.AddModelError(nameof(InputModel.Captcha), "Invalid captcha.");
76+
return Page();
77+
}
78+
}
79+
}
80+
81+
```

‎docs/cn/session-image.md

+67
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
# 基于 Session 的图片验证码
2+
3+
0. 安装需要的 Nuget 包
4+
5+
```ps
6+
Install-Package NCaptcha.AspNetCore.SessionImages
7+
```
8+
9+
1. 注册依赖注入服务
10+
11+
```cs
12+
public void ConfigureServices(IServiceCollection services)
13+
{
14+
services.AddSession();
15+
services.AddSessionBasedImageCaptcha();
16+
}
17+
```
18+
19+
2. 配置 Session
20+
21+
```cs
22+
public void Configure(IApplicationBuilder app)
23+
{
24+
app.UseSession();
25+
}
26+
```
27+
28+
3. 添加一个生成图片的 Api
29+
30+
```cs
31+
public class LoginModel : PageModel
32+
{
33+
private readonly ICaptchaGenerator _captchaGenerator;
34+
35+
public LoginModel(ICaptchaGenerator captchaGenerator)
36+
{
37+
_captchaGenerator = captchaGenerator;
38+
}
39+
40+
public async Task<IActionResult> OnGetCaptchaAsync() => await _captchaGenerator.GetCaptchaFileResultAsync();
41+
}
42+
43+
```
44+
45+
4. 验证码验证
46+
47+
```cs
48+
public class LoginModel : PageModel
49+
{
50+
private readonly ICaptchaValidator _captchaValidator;
51+
52+
public LoginModel(ICaptchaValidator captchaValidator)
53+
{
54+
_captchaValidator = captchaValidator;
55+
}
56+
57+
public async Task<IActionResult> OnPostAsync()
58+
{
59+
if (!await _captchaValidator.ValidateAsync(Input.Captcha))
60+
{
61+
ModelState.AddModelError(nameof(InputModel.Captcha), "Invalid captcha.");
62+
return Page();
63+
}
64+
}
65+
}
66+
67+
```

0 commit comments

Comments
 (0)