dgPay-Core-sdk 2.5.7

DgPaySdk - 斗拱支付 C# SDK

概述

DgPaySdk 是斗拱支付的官方 C# SDK，完全独立的类库，支持 .NET 5.0/6.0/7.0/8.0，可在任何 .NET 项目中使用。

✨ 特性

• ✅ 多框架支持 - .NET 5.0/6.0/7.0/8.0，跨平台（Windows/Linux/macOS）
• ✅ 完全独立 - 无外部依赖，可在任何 .NET 项目中使用
• ✅ DI 集成 - 提供 AddDgPaySdk() 扩展方法，一行代码配置
• ✅ 全异步 API - 基于 async/await，性能优异
• ✅ HttpClient 连接池 - 自动管理连接，高并发支持
• ✅ 线程安全 - 配置和请求完全线程安全
• ✅ 类型安全 - 完整的泛型和可空引用支持

📦 安装

NuGet Package Manager

Install-Package dgPay-Core-sdk

.NET CLI

dotnet add package dgPay-Core-sdk --version 2.5.6

⚙️ 配置项说明

DgPayOptions 配置项

🚀 快速开始

方式一：使用 DI 扩展（推荐）

// Program.cs
using Microsoft.Extensions.DependencyInjection;

var builder = WebApplication.CreateBuilder(args);

// 一行代码配置 SDK
builder.Services.AddDgPaySdk(options =>
{
    // 基础配置
    options.SysId = "your_sys_id";
    options.ProductId = "your_product_id";
    options.RsaPrivateKey = "your_rsa_private_key";
    options.RsaPublicKey = "your_rsa_public_key";  // 可选，用于验签
    options.UpperHuifuId = "your_upper_huifu_id";  // 可选，默认等于 SysId
    
    // 环境配置
    options.EnableDebug = false;  // 是否启用调试模式
    options.IsProduction = true;  // 是否为生产环境
    
    // 异步通知配置（可选）
    options.NotifyUrl = "https://yourdomain.com/api/notify/default";  // 默认回调地址
    options.PayNotifyUrl = "https://yourdomain.com/api/notify/payment";  // 支付回调地址
    options.TransferNotifyUrl = "https://yourdomain.com/api/notify/transfer";  // 大额充值回调地址
});

// 或从配置文件读取
// builder.Services.AddDgPaySdk(builder.Configuration);

var app = builder.Build();
app.Run();

配置文件示例（appsettings.json）

{
  "DgPaySdk": {
    // 基础配置（必填）
    "SysId": "your_sys_id",
    "ProductId": "your_product_id",
    "RsaPrivateKey": "your_rsa_private_key",
    
    // 可选配置
    "RsaPublicKey": "your_rsa_public_key",
    "UpperHuifuId": "your_upper_huifu_id",
    "EnableDebug": false,
    "IsProduction": true,
    
    // 异步通知配置（可选）
    "NotifyUrl": "https://yourdomain.com/api/notify/default",
    "PayNotifyUrl": "https://yourdomain.com/api/notify/payment",
    "TransferNotifyUrl": "https://yourdomain.com/api/notify/transfer"
  }
}

方式二：直接初始化

using DgPaySdk;

var config = new MerConfig
{
    SysId = "your_sys_id",
    ProductId = "your_product_id",
    RsaPrivateKey = "your_private_key"
};

DgPay.InitWithMerConfig(config);

2. 发送请求

using DgPaySdk.Request;

var request = new V2TradePaymentMicropayRequest
{
    ReqDate = DateTime.Now.ToString("yyyyMMdd"),
    ReqSeqId = DateTime.Now.ToString("yyyyMMddHHmmssfff"),
    HuifuId = "6666000123456789",
    TransAmt = "100.00",
    GoodsDesc = "测试商品",
    AuthCode = "130000000000000000"
};

var response = await DgPayClient.PostRequestAsync(request);

💡 在不同框架中使用

DgPaySdk 是完全独立的类库，可以在任何 .NET 项目中使用。

示例 1: ASP.NET Core Web API

// Program.cs
var builder = WebApplication.CreateBuilder(args);

// 在应用启动时初始化一次
var config = new MerConfig
{
    SysId = builder.Configuration["DgPay:SysId"],
    ProductId = builder.Configuration["DgPay:ProductId"],
    RsaPrivateKey = builder.Configuration["DgPay:RsaPrivateKey"]
};
DgPay.InitWithMerConfig(config);

var app = builder.Build();
app.Run();

// Controllers/PaymentController.cs
[ApiController]
[Route("api/[controller]")]
public class PaymentController : ControllerBase
{
    [HttpPost("pay")]
    public async Task<IActionResult> Pay([FromBody] PaymentRequest request)
    {
        var payRequest = new V2TradeAcctpaymentPayRequest
        {
            ReqSeqId = Guid.NewGuid().ToString("N"),
            ReqDate = DateTime.Now.ToString("yyyyMMdd"),
            HuifuId = request.HuifuId,
            TransAmt = request.Amount.ToString("F2"),
            GoodsDesc = request.ProductName
        };
        
        var response = await DgPayClient.PostRequestAsync(payRequest);
        return Ok(response);
    }
}

示例 2: ABP vNext

// YourModule.cs
public class YourModule : AbpModule
{
    public override void ConfigureServices(ServiceConfigurationContext context)
    {
        var configuration = context.Services.GetConfiguration();
        
        // 初始化 SDK
        var config = new MerConfig
        {
            SysId = configuration["DgPay:SysId"],
            ProductId = configuration["DgPay:ProductId"],
            RsaPrivateKey = configuration["DgPay:RsaPrivateKey"]
        };
        DgPay.InitWithMerConfig(config);
    }
}

// YourAppService.cs
public class PaymentAppService : ApplicationService
{
    public async Task<PaymentResultDto> PayAsync(PaymentDto input)
    {
        var request = new V2TradeAcctpaymentPayRequest
        {
            ReqSeqId = Guid.NewGuid().ToString("N"),
            ReqDate = DateTime.Now.ToString("yyyyMMdd"),
            HuifuId = input.HuifuId,
            TransAmt = input.Amount.ToString("F2"),
            GoodsDesc = input.ProductName
        };
        
        var response = await DgPayClient.PostRequestAsync(request);
        return MapToDto(response);
    }
}

提示: 如果您希望更优雅的 DI 集成，可以参考 DgPaySdk.Application 项目的实现。

示例 3: Console Application

// Program.cs
using DgPaySdk;
using DgPaySdk.Request;

// 初始化配置
var config = new MerConfig
{
    SysId = "your_sys_id",
    ProductId = "your_product_id",
    RsaPrivateKey = "your_private_key"
};
DgPay.InitWithMerConfig(config);

// 直接使用
var request = new V2TradeAcctpaymentPayRequest
{
    ReqSeqId = DateTime.Now.ToString("yyyyMMddHHmmssfff"),
    ReqDate = DateTime.Now.ToString("yyyyMMdd"),
    HuifuId = "6666000123456789",
    TransAmt = "100.00",
    GoodsDesc = "测试商品"
};

var response = await DgPayClient.PostRequestAsync(request);
Console.WriteLine($"支付结果: {response.RespCode} - {response.RespDesc}");

示例 4: Blazor Server

// Program.cs
var builder = WebApplication.CreateBuilder(args);

// 初始化 SDK
var config = new MerConfig
{
    SysId = builder.Configuration["DgPay:SysId"],
    ProductId = builder.Configuration["DgPay:ProductId"],
    RsaPrivateKey = builder.Configuration["DgPay:RsaPrivateKey"]
};
DgPay.InitWithMerConfig(config);

builder.Services.AddRazorComponents()
    .AddInteractiveServerComponents();

var app = builder.Build();
app.Run();

// Components/Pages/Payment.razor
@using DgPaySdk
@using DgPaySdk.Request
@inject NavigationManager Navigation

<h3>支付页面</h3>

<button @onclick="MakePayment" class="btn btn-primary">立即支付</button>

@if (!string.IsNullOrEmpty(result))
{
    <div class="alert alert-info">@result</div>
}

@code {
    private string result = "";

    private async Task MakePayment()
    {
        var request = new V2TradeAcctpaymentPayRequest
        {
            ReqSeqId = Guid.NewGuid().ToString("N"),
            ReqDate = DateTime.Now.ToString("yyyyMMdd"),
            HuifuId = "6666000123456789",
            TransAmt = "100.00",
            GoodsDesc = "测试商品"
        };
        
        var response = await DgPayClient.PostRequestAsync(request);
        result = $"{response.RespCode}: {response.RespDesc}";
    }
}

示例 5: MAUI

// MauiProgram.cs
public static class MauiProgram
{
    public static MauiApp CreateMauiApp()
    {
        var builder = MauiApp.CreateBuilder();
        
        // 初始化 SDK
        var config = new MerConfig
        {
            SysId = Preferences.Get("SysId", ""),
            ProductId = Preferences.Get("ProductId", ""),
            RsaPrivateKey = Preferences.Get("RsaPrivateKey", "")
        };
        DgPay.InitWithMerConfig(config);
        
        builder.UseMauiApp<App>();
        return builder.Build();
    }
}

// PaymentPage.xaml.cs
public partial class PaymentPage : ContentPage
{
    private async void OnPayClicked(object sender, EventArgs e)
    {
        var request = new V2TradeAcctpaymentPayRequest
        {
            ReqSeqId = Guid.NewGuid().ToString("N"),
            ReqDate = DateTime.Now.ToString("yyyyMMdd"),
            HuifuId = huifuIdEntry.Text,
            TransAmt = amountEntry.Text,
            GoodsDesc = "MAUI 支付测试"
        };
        
        var response = await DgPayClient.PostRequestAsync(request);
        await DisplayAlert("支付结果", $"{response.RespCode}: {response.RespDesc}", "确定");
    }
}

📚 相关项目

DgPaySdk.Application (ABP vNext 示例)

DgPaySdk.Application 和 DgPaySdk.Domain 是参考实现，展示如何在 ABP vNext 框架中优雅地集成 DgPaySdk。

• 不是必须的 - 您可以直接使用 DgPaySdk 核心库
• 仅供参考 - 您可以根据自己的框架自行封装
• DI 集成示例 - 展示了如何通过 DI 容器管理服务

如果您使用 ABP vNext，可以参考该项目的实现；如果使用其他框架，可以直接使用 DgPaySdk 核心库。

❓ 常见问题

Q1: 必须在应用启动时初始化吗？

A: 是的，建议在应用启动时调用一次 DgPay.InitWithMerConfig()。之后可以在任何地方使用 DgPayClient.PostRequestAsync()。

Q2: 线程安全吗？

A: 完全线程安全。DgPayClient 内部使用 HttpClient 连接池，支持高并发。

Q3: 可以动态切换配置吗？

A: 可以。随时调用 DgPay.InitWithMerConfig() 会覆盖之前的配置：

// 切换到另一个商户配置
var newConfig = new MerConfig { ... };
DgPay.InitWithMerConfig(newConfig);

Q4: 支持哪些 .NET 版本？

A:

• DgPaySdk 核心库: .NET 5.0/6.0/7.0/8.0
• Application/Domain 示例: .NET 8.0 (仅用于 ABP vNext 演示)

Q5: 需要安装 Application 和 Domain 包吗？

A: 不需要。只需安装 dgPay-Core-sdk 即可。Application 和 Domain 只是参考实现，您可以根据需要自行封装或直接使用核心库。

🎯 总结

✅ 完全独立 - DgPaySdk 核心库无任何外部依赖
✅ 多框架支持 - ASP.NET Core, ABP vNext, Blazor, MAUI, Console 等
✅ 简单易用 - 一行代码初始化，随处使用
✅ 高性能 - HttpClient 连接池，全异步 API
✅ 灵活封装 - 可根据自己的框架需求自行封装

版本: 2.5.6
最后更新: 2026-04-27
适用框架: .NET 5.0+, ASP.NET Core, ABP vNext, Blazor, MAUI, WPF, WinForms