Xray.Sdk 0.0.14-beta

Xray.Sdk - xray-cshare C-share compatible

Xray.Sdk is a .NET 9 solution for building, running, and controlling xray-core from managed code. Native-library hosting is built to work with the C-share library from xray-cshare.

The solution is split into three focused libraries:

• Xray.Config: strongly typed configuration models, JSON serialization, and share-link helpers.
• Xray.Api: gRPC client wrappers and convenience methods for runtime management.
• Xray.Core: process-based and native-library-based runtime hosting helpers.

Compatibility changes are recorded in CHANGELOG.md.

Language

• English project docs are the primary reference.
• Russian translations are provided next to each project guide.

Documentation

Solution Overview

• This file: README.md
• Example app: Program.cs
• Tests: Xray.Sdk.Tests

Project Guides

• Xray.Api
  • English: API_README.md
  • Russian: RU_API_README.md
• Xray.Config
  • English: CONFIG_README.md
  • Russian: RU_CONFIG_README.md
• Xray.Core
  • English: CORE_README.md
  • Russian: RU_CORE_README.md

Repository Layout

Xray.Sdk/
|- Xray.Api/
|- Xray.Config/
|- Xray.Core/
|- Xray.Sdk.Example/
|- Xray.Sdk.Tests/
|- Fetch-XrayProtos.ps1
`- Xray.Sdk.sln

What Each Library Does

Xray.Config

Use this package when you need to:

• build Xray configuration files in C#
• deserialize existing Xray JSON
• round-trip supported config formats
• convert supported share links into typed outbound models

Xray.Api

Use this package when you need to:

• call Xray gRPC services
• query runtime stats
• manage inbounds and outbounds
• add and remove users without manually building protobuf payloads

Xray.Core

Use this package when you need to:

• start xray-core as an external process
• host the native Xray library in-process
• generate keys and certificates through native helpers
• run lightweight health or ping-style checks against a config

Quick Start

Build the solution:

dotnet build Xray.Sdk.sln -c Release

Run tests:

dotnet test Xray.Sdk.Tests/Xray.Sdk.Tests.csproj -c Release

Add one of the projects as a reference:

dotnet add <YourProject>.csproj reference Xray.Config/Xray.Config.csproj
dotnet add <YourProject>.csproj reference Xray.Api/Xray.Api.csproj
dotnet add <YourProject>.csproj reference Xray.Core/Xray.Core.csproj

Minimal Example

using Xray.Config.Enums;
using Xray.Config.Models;

var config = new XrayConfig
{
    Log = new LogConfig
    {
        LogLevel = LogLevel.Warning,
    },
    Inbounds =
    [
        new SocksInbound
        {
            Tag = "socks-in",
            Listen = "127.0.0.1",
            Port = new Port(10808),
            Settings = new Inbound.SocksSettings
            {
                Udp = true,
            }
        }
    ],
    Outbounds =
    [
        new FreedomOutbound
        {
            Tag = "direct",
        }
    ]
};

var json = config.ToJson();

For runtime hosting and API usage, see the project-specific guides and the example app in Program.cs.

Compatibility Notes

• The solution targets .NET 9.0.
• Xray.Api depends on generated protobuf clients from the Xray-Protos folder.
• Xray.Api/Xray-Protos is verified against xray-core v26.3.27.
• Xray.Config.SupportedCoreVersionRange returns the SDK-audited xray-core range. This is not the same as the Xray config file version runtime gate.
• Xray.Core supports both process-hosted and native-library-hosted execution, but native integration still depends on matching platform binaries.
• Xray.Config focuses on typed support for known Xray formats; unsupported or newly added upstream fields may require updates in the SDK.

Development

Useful commands:

dotnet build Xray.Sdk.sln -c Release
dotnet test Xray.Sdk.Tests/Xray.Sdk.Tests.csproj -c Release
dotnet pack Xray.Sdk/Xray.Sdk.csproj -c Release

Packages are written to artifacts/packages.

The publishable NuGet package is Xray.Sdk. It contains the API, Config, and Core assemblies in one package.

Publish the package to NuGet:

dotnet nuget push artifacts/packages/Xray.Sdk.0.0.12-beta.nupkg --api-key <NUGET_API_KEY> --source https://api.nuget.org/v3/index.json

GitHub Actions NuGet Publishing

The repository includes a GitHub Actions workflow that builds, tests, packs, and publishes Xray.Sdk.

Required repository secret:

• NUGET_API_KEY: NuGet API key with permission to publish the Xray.Sdk package.

Pull requests and pushes to main build, test, pack, and upload package artifacts. Publishing to NuGet runs only when a version tag is pushed:

git tag v0.0.12-beta
git push origin v0.0.12-beta

The package version is resolved from the tag name without the leading v, so v0.0.12-beta publishes package version 0.0.12-beta.

License

This repository is distributed under the MIT license.

Package metadata also declares MIT:

• Directory.Build.props
• Xray.Sdk.csproj

Contributing

• keep public APIs typed and explicit
• add or update tests in Xray.Sdk.Tests
• document behavioral changes in the relevant project guide
• record user-visible changes in CHANGELOG.md
• preserve compatibility with xray-core formats where possible