在软件开发中，结合不同编程语言的优势往往可以提升项目的性能与可维护性。

CSnakes 是一个.NET源生成器和运行时，旨在将Python代码和库高效嵌入到C#.NET解决方案中。

它的最大优势在于无需REST、HTTP或微服务的架构设计，能够实现快速的代码调用。

项目地址：https://github.com/tonybaloney/CSnakes

系统架构图

特性

• 支持.NET 8和9
• 支持Python 3.9~3.13
• 支持虚拟环境和C扩展
• 兼容Windows、macOS和Linux
• 紧密集成NumPy的ndarrays与Spans、2D Spans和TensorSpans（.NET 9）
• 采用Python的C-API快速调用Python代码
• 使用Python类型提示生成与.NET本地类型的函数签名
• 支持CPython 3.13的“自由线程”模式
• 支持嵌套序列和映射类型（tuple、dict、list）

优势

• 使用原生的 Python 类型提示标准，生成干净、可读的 C# 代码，且代码冗余最小。
• NET 与 Python 的集成通过 C-API 实现，这意味着 Python 版本 3.8-3.13 与 .NET 8-9 之间具有良好的兼容性。
• 集成为低级且高性能。
• CSnakes 使用 CPython C-API，兼容所有 Python 扩展。
• Python 代码和库的调用与 .NET 在同一进程中进行。

入门指南

1. 安装Python

CSnakes需要在你的机器上安装Python，支持版本为3.9-3.13。

嵌入Python的过程需要指定三条路径，而不仅仅是Python可执行文件的路径：

• Python库路径（通常为python3.dll或libpython3.so）
• Python标准库路径（包含标准库的目录）
• Python代码路径
• 可选：虚拟环境路径

为了简化配置，CSnakes提供了常见安装路径的Python定位器作为扩展方法。

2. 配置C#项目

要在C#项目中配置CSnakes，我们需要：

1. 创建一个新的C#项目或打开现有项目。
2. 将Python文件添加到项目中。
3. 在项目文件中将Python文件标记为“附加文件”。
4. 安装CSnakes.Runtime NuGet包。
5. 创建一个Python环境并实例化Python模块。

3. 安装NuGet包

CSnakes包含在一个名为CSnakes.Runtime的NuGet包中。该包包括源生成器和运行时库。

强烈建议使用源生成器以获得最佳体验，但你也可以直接使用运行时库。

4. 添加Python文件

CSnakes使用Python的类型注解生成C#代码。

需要将Python文件添加到项目中，并为想要从C#调用的函数添加类型注解。

例如，我们可以创建一个名为demo.py的文件，其内容如下：

def hello_world(name: str) -> str:
    return f"Hello, {name}!"

5. 标记文件以供生成

要使CSnakes对Python文件运行源生成器，需要在CSProj文件的XML中将其标记为“附加文件”：

<ItemGroup>
    <AdditionalFiles Include="demo.py">
        <CopyToOutputDirectory>Always</CopyToOutputDirectory>
    </AdditionalFiles>
</ItemGroup>

或者在Visual Studio中更改文件的属性，将“生成操作”设置为“Csharp分析器附加文件”。

6. 构建项目

添加Python文件、安装NuGet包并标记文件后，可以使用以下命令构建项目：

dotnet build

7. 从C#构建Python环境

CSnakes创建的Python环境是进程级单例，我们可以在整个进程生命周期中使用它。

CSnakes提供了一个主机生成器，便于在C#代码中创建Python环境。

以下是创建Python环境的示例代码：

using CSnakes.Runtime;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using System;
using System.IO;

var builder = Host.CreateDefaultBuilder(args)
    .ConfigureServices(services =>
    {
        var home = Path.Join(Environment.CurrentDirectory, "."); // Python模块路径
        services
            .WithPython()
            .WithHome(home)
            .FromNuGet("3.12.4"); // 添加一个或多个Python定位器
    });

var app = builder.Build();
var env = app.Services.GetRequiredService<IPythonEnvironment>();

8. 使用虚拟环境

CSnakes支持在Python虚拟环境和Conda环境中执行，因为大多数Python项目需要外部依赖。

我们可以使用.WithVirtualEnvironment()方法指定虚拟环境的路径。

如果需要，我们还可以使用.WithPipInstaller()方法在虚拟环境中安装requirements.txt文件中列出的包。

示例代码如下：

services
    .WithPython()
    .WithVirtualEnvironment(Path.Join(home, ".venv"))
    .WithPipInstaller(); // 可选 - 启动时安装requirements.txt中的包

9. 从C#.NET调用CSnakes代码

一旦创建了Python环境，我们就可以使用IPythonEnvironment接口从C#调用任何Python函数。

以下是调用demo.py文件中hello_world函数的示例代码：

var env = app.Services.GetRequiredService<IPythonEnvironment>();
var module = env.Demo();
var result = module.HelloWorld("DHub");
Console.WriteLine(result); 

// 输出：Hello, DHub!

结语

CSnakes为.NET开发者提供了强大且灵活的工具，可以在项目中无缝集成Python代码，提升应用的功能与性能。

通过简化Python与.NET的交互过程，CSnakes为开发者创造了更高效的开发体验，值得在未来的项目中深入探索与应用。