XFEExtension.NetCore.ServerInteractive

📖 English | 简体中文

Description

ServerInteractive is a C# DLL library built on the CyberComm network architecture provided by XFEExtension.NetCore. It enables developers to rapidly build server-side and client-side network frameworks. It supports route-based request dispatch, incremental code generation (Source Generator), user login system, data table management, IP banning, and other out-of-the-box standard features.

Table of Contents

• Quick Start
• Server Side
  • Setting Up the Server
  • Defining Standard Core Services (Route Handling)
  • Wildcard Routes
  • Using the XFE Standard Server Core
  • Manual Service Composition
  • Original Services and Verify Services
  • Server Core Configuration Options
  • Responding to Clients in Service Methods
• Client Side
  • Setting Up a Requester
  • Inline Request Registration
  • Defining Standard Request Services (Source Generator)
  • Using XFE Standard Requests
  • TableRequester (Data Table Requester)
• Source Generator
  • Server Side: EntryPoint Generator
  • Client Side: ClientRequest Generator
  • Diagnostic Rules
• Common Errors and Solutions

Quick Start

Before using, add the XFEExtension.NetCore.ServerInteractive NuGet package to your project.

Simplest server example (an echo service bound to local port 3300):

Service definition (EchoService.cs)

using XFEExtension.NetCore.ServerInteractive.Attributes;
using XFEExtension.NetCore.ServerInteractive.Implements.CoreService;

// The class must be partial so the Source Generator can automatically generate the route dictionary
public partial class EchoService : ServerCoreStandardServiceBase
{
    [EntryPoint("echo")]         // Route path: /echo
    public async Task Echo()
    {
        var message = Json?["message"]?.GetValue<string>() ?? string.Empty;
        await Close(message);    // Reply to the client and end the request
    }
}

Program entry point (Program.cs)

using XFEExtension.NetCore.ServerInteractive.Utilities.Extensions;
using XFEExtension.NetCore.ServerInteractive.Utilities.Server;

var server = XFEServerBuilder.CreateBuilder()
    .UseXFEServer()                               // Register logger, exception handler, and core processor
    .AddServerCore(
        XFEServerCoreBuilder.CreateBuilder()
            .AddService<EchoService>()            // Register EchoService (routes are automatically obtained from [EntryPoint])
            .Build(options =>
            {
                options.BindIP("http://localhost:3300/");
            }))
    .Build();

using var shutdown = new CancellationTokenSource();
Console.CancelKeyPress += (_, e) => { e.Cancel = true; shutdown.Cancel(); };
await server.RunAsync(shutdown.Token);

Cross-platform console EXE

XFEExtension.NetCore.ServerInteractive.TServer is the production console-host template. It does not register a Windows Service or depend on ASP.NET Core. HTTP/1.1, HTTPS, WebSocket, and WSS are provided exclusively by CyberComm, with graceful shutdown on Windows Ctrl+C and Linux SIGINT/SIGTERM.

dotnet publish XFEExtension.NetCore.ServerInteractive.TServer/XFEExtension.NetCore.ServerInteractive.TServer.csproj -p:PublishProfile=win-x64-single-file
dotnet publish XFEExtension.NetCore.ServerInteractive.TServer/XFEExtension.NetCore.ServerInteractive.TServer.csproj -p:PublishProfile=linux-x64-single-file

Both profiles are self-contained single-file publications with trimming disabled. All runtime configuration and structured server data are persisted by AutoConfig under data/: ServerProfile.xpf, DataProfile.xpf, and UserProfile.xpf. The first start materializes ServerProfile.xpf with safe defaults. The run directory also contains certificates/, logs/, and temp/; inject a PFX password with XFE_TLS_PFX_PASSWORD, --tls-password, or --tls-password-stdin, never in a profile.

Server Side

Setting Up the Server

Use XFEServerBuilder to assemble the server.

var server = XFEServerBuilder.CreateBuilder()
    .UseXFEServer()                   // Use XFE standard server (includes log initialization, exception handling, core processor)
    .AddServerCore(serverCore)        // Add an XFEServerCore instance
    .Build();                         // Build the XFEServer instance

await server.RunAsync();              // Start and run; production hosts should pass a shutdown CancellationToken

Multiple server cores can bind to the same port as long as their MainEntryPoint values differ. The framework starts one underlying listener for the shared port and dispatches HTTP and WebSocket events by the combination of port and main entry point:

var apiCore = XFEServerCoreBuilder.CreateBuilder().Build(options =>
{
    options.ServerCoreName = "ApiServer";
    options.MainEntryPoint = "api";
    options.BindIP("http://localhost:3300/");
});

var backendCore = XFEServerCoreBuilder.CreateBuilder().Build(options =>
{
    options.ServerCoreName = "BackendServer";
    options.MainEntryPoint = "backend";
    options.BindIP("http://localhost:3300/"); // Shares the port with apiCore
});

var server = XFEServerBuilder.CreateBuilder()
    .UseXFEServer()
    .AddServerCore(apiCore)       // /api/{sub-route}
    .AddServerCore(backendCore)   // /backend/{sub-route}
    .Build();

MainEntryPoint must be unique on each port; otherwise, server startup throws XFEServerBuilderException. Leading, trailing, and duplicate / separators are normalized automatically. When nested entry points both match, the longer, more specific entry point wins; an empty entry point acts as the fallback core for that port.

UseXFEServer() is equivalent to:

.AddInitializer<ServerLogInitializer>()      // Log initializer
.AddService<ServerExceptionProcessService>() // Global exception handler
.AddCoreProcessor<XFEServerCoreProcessService>() // Core request processor

You can also register only custom services without using the standard suite:

var server = XFEServerBuilder.CreateBuilder()
    .AddInitializer<MyInitializerService>()  // Custom initializer service (runs once before the server starts)
    .AddService<MyService>()                 // Custom synchronous service (runs when the server starts)
    .AddAsyncService<MyAsyncService>()       // Custom asynchronous service (runs asynchronously when the server starts)
    .AddCoreProcessor<MyCoreProcessor>()     // A core processor must be added
    .Build();

Defining Standard Core Services (Route Handling)

Inherit ServerCoreStandardServiceBase and mark methods with [EntryPoint("route path")].
The class must be declared as partial for the Source Generator to automatically generate the route dictionary.

using XFEExtension.NetCore.ServerInteractive.Attributes;
using XFEExtension.NetCore.ServerInteractive.Implements.CoreService;

public partial class MathService : ServerCoreStandardServiceBase
{
    [EntryPoint("math/add")]
    public async Task Add()
    {
        var a = Json?["a"]?.GetValue<double>() ?? 0;
        var b = Json?["b"]?.GetValue<double>() ?? 0;
        await Close(a + b);     // Return result and close the request
    }

    [EntryPoint("math/subtract")]
    public void Subtract()
    {
        var a = Json?["a"]?.GetValue<double>() ?? 0;
        var b = Json?["b"]?.GetValue<double>() ?? 0;
        OK();                   // Mark as handled
        // Synchronous methods are also supported; the return type is void
    }
}

Register in XFEServerCoreBuilder:

XFEServerCoreBuilder.CreateBuilder()
    .AddService<MathService>()   // Automatically reads route paths from [EntryPoint] and registers
    .Build(options => { options.BindIP("http://localhost:3300/"); });

Add [NoLog] to a high-frequency entry point when its routine request logs are not needed:

[EntryPoint("health")]
[NoLog]
public async Task Health() => await Close("OK");

This suppresses the framework's request-received, validation, route, and elapsed-time messages. Exception logs are still emitted, and business logs explicitly written inside the method through Console.Write* or another logger are unaffected.

Commonly accessible properties in service methods:

Wildcard Routes

An independent * in a route segment can match any single path segment, and multi-level wildcards are supported.
The framework prioritizes patterns with more literal segments (most-specific-first principle), regardless of registration order.

public partial class DynamicService : ServerCoreStandardServiceBase
{
    // Matches v1/anything/info, e.g., v1/users/info or v1/orders/info
    [EntryPoint("v1/*/info")]
    public async Task DynamicInfo()
    {
        // The Route property contains the actual request path, e.g., v1/users/info
        await Close($"Your route is: {Route}, your IP is: {ClientIP}");
    }

    // Matches paths under v1/test/* (* only matches a single path segment), e.g., v1/test/a, v1/test/hello
    [EntryPoint("v1/test/*")]
    public async Task TestAny()
    {
        await Close($"Server: {XFEServerCore.ServerCoreName}, Route: {Route}");
    }
}

Note: The wildcard * must be a complete path segment and cannot be mixed with other characters (e.g., a*b is invalid).

Using the XFE Standard Server Core

The UseXFEStandardServerCore<T>() extension method provides a complete standardized server core with built-in:

• User login (server route user/login, client can call using alias login), auto relogin (route user/relogin, alias relogin)
• Data table CRUD management (table/get/{tableName}, table/add/{tableName}, table/change/{tableName}, table/remove/{tableName})
• IP banning (ip/banned/get, ip/banned/add, ip/banned/remove), daily counting
• Connection check (check_connect), server logging (route log/get, alias get_log; route log/clear, alias clear_log)

var serverCore = XFEServerCoreBuilder.CreateBuilder()
    .UseXFEStandardServerCore<IUserFaceInfo>(options =>
    {
        // Provide user data source
        options.GetUserFunction = () => UserProfile.UserTable;
        options.AddUserFunction = user => UserProfile.UserTable.Add((User)user);
        options.UpdateUserFunction = _ => UserProfile.SaveProfile();
        options.GetEncryptedUserLoginModelFunction = () => UserProfile.EncryptedUserLoginModelTable;
        options.AddEncryptedUserLoginModelFunction = UserProfile.EncryptedUserLoginModelTable.Add;
        options.RemoveEncryptedUserLoginModelFunction = model => UserProfile.EncryptedUserLoginModelTable.Remove(model);
        options.GetLoginKeepDays = () => 7;  // Number of days to keep the login session

        // Convert the User object to the interface type returned to the client after a successful login
        options.LoginResultConvertFunction = user => UserPublicDto.From((IUserInfo)user);

        // Configure the data table manager
        options.DataTableManagerBuilder = XFEDataTableManagerBuilder.CreateBuilder()
            // Parameters: display name, add permission, remove permission, change permission, get permission
            .AddTable<Order, DataProfile>("Orders", addPermissionLevel: 1, removePermissionLevel: 2, changePermissionLevel: 1, getPermissionLevel: 1)
            .AddTable<User, UserProfile>("Users", addPermissionLevel: 2, removePermissionLevel: 2, changePermissionLevel: 2, getPermissionLevel: 1);
    })
    .AddService<MyCustomService>()   // Append custom business services
    .Build(options =>
    {
        options.MainEntryPoint = "api";     // Route prefix; the full path for a login request would be /api/user/login
        options.AcceptPost = true;
        options.AcceptGet = true;
        options.BindIP("http://localhost:3300/")
               .BindIP("https://localhost:3301/");
    });

Complete server example (with TServer reference implementation):

var server = XFEServerBuilder.CreateBuilder()
    .UseXFEServer()
    .AddServerCore(
        XFEServerCoreBuilder.CreateBuilder()
            .UseXFEStandardServerCore<IUserFaceInfo>(options =>
            {
                options.GetUserFunction = () => UserProfile.UserTable;
                options.AddUserFunction = user => UserProfile.UserTable.Add((User)user);
                options.GetEncryptedUserLoginModelFunction = () => UserProfile.EncryptedUserLoginModelTable;
                options.AddEncryptedUserLoginModelFunction = UserProfile.EncryptedUserLoginModelTable.Add;
                options.RemoveEncryptedUserLoginModelFunction = model => UserProfile.EncryptedUserLoginModelTable.Remove(model);
                options.GetLoginKeepDays = () => 7;
                options.UpdateUserFunction = _ => UserProfile.SaveProfile();
                options.LoginResultConvertFunction = user => UserPublicDto.From((IUserInfo)user);
                options.DataTableManagerBuilder = XFEDataTableManagerBuilder.CreateBuilder()
                    .AddTable<Order, DataProfile>("Orders", 1, 2, 1, 1)
                    .AddTable<Person, DataProfile>("Persons", 1, 2, 1, 1)
                    .AddTable<User, UserProfile>("Users", 2, 2, 2, 1);
            })
            .AddService<TestCoreService>()
            .AddService<EchoCoreService>()
            .Build(options =>
            {
                options.MainEntryPoint = "api";
                options.AcceptPost = true;
                options.AcceptGet = true;
                options.BindIP("http://localhost:3305/")
                       .BindIP("https://localhost:3306/");
            }))
    .Build();

await server.RunAsync();

Manual Service Composition

If you don't need the standard suite, you can add individual services as needed:

XFEServerCoreBuilder.CreateBuilder()
    // Register a standard service (routes are automatically read from [EntryPoint])
    .AddService<MyRouteService>()
    // Explicitly specify a route (useful for dynamic routes or when not using a Source Generator)
    .AddServiceWithRoute<MyDynamicService>("dynamic/*/process")
    // Original service (listens for server start events and all raw requests)
    .AddOriginalService<MyRawRequestHandler>()
    // Verify service (validates each request before route dispatch; returning false intercepts the request)
    .AddVerifyService<MyAuthVerifyService>()
    // Add user base parameters (used by login-related services)
    .AddUserParameterBase(getUserFn, addUserFn, getEncryptedModelFn, addEncryptedModelFn, removeEncryptedModelFn, getKeepDaysFn, convertFn)
    // Add a data table manager
    .AddDataTableManager(tableManagerBuilder, getUserFn, getEncryptedModelFn)
    // Add individual built-in services
    .AddEntryPointVerify()          // Entry point validation service
    .AddDailyCounterService()       // Daily request statistics
    .AddXFEErrorProcessService()    // Exception handling service
    .AddConnectService()            // Connection check service (check_connect route)
    .AddStandardLoginService<IUserFaceInfo>()  // Standard login service (login, relogin routes)
    .AddServerLogService()          // Server log query (get_log route)
    .AddIPBannerService()           // IP banning service (get_bannedIPList, add_bannedIP, remove_bannedIP routes)
    .Build(options =>
    {
        options.BindIP("http://localhost:3300/");
    });

Original Services and Verify Services

Original Service (IServerCoreOriginalService): Inherit ServerCoreOriginalServiceBase to listen for server start events and every raw request (before route dispatch).

using XFEExtension.NetCore.CyberComm;
using XFEExtension.NetCore.ServerInteractive.Implements.CoreService;

public class MyRawService : ServerCoreOriginalServiceBase
{
    public override void ServerStarted(object? sender, EventArgs e)
    {
        Console.WriteLine("Server has started!");
    }

    public override void RequestReceived(object? sender, CyberCommRequestEventArgs e)
    {
        Console.WriteLine($"Raw request received: {e.Request.Url}");
    }
}

Verify Service (IServerCoreVerifyService): Inherit ServerCoreVerifyServiceBase. Every request is validated before route dispatch. Returning false from VerifyRequest or returning a Task<bool> that resolves to false from VerifyRequestAsync interrupts further processing.

using XFEExtension.NetCore.ServerInteractive.Implements.CoreService;

public class MyAuthService : ServerCoreVerifyServiceBase
{
    public override bool VerifyRequest()
    {
        // Synchronous validation; returning false intercepts the request
        var token = Args.Request.Headers["X-Token"];
        return !string.IsNullOrEmpty(token);
    }

    public override async Task<bool> VerifyRequestAsync()
    {
        // Asynchronous validation; returns true by default (does not intercept)
        return true;
    }
}

Server Core Configuration Options

XFEServerCoreBuilder.Build(options => { ... }) accepts XFEServerCoreOptions:

.Build(options =>
{
    options.ServerCoreName = "MainServer";
    options.MainEntryPoint = "api";    // Request path format: /api/{sub-route}
    options.AcceptGet = true;
    options.AcceptPost = true;
    options.GetIPFunction = args => args.Request.Headers["X-Forwarded-For"] ?? args.ClientIP;
    options.BindIP("http://localhost:3300/")
           .BindIP("https://localhost:3301/");
});

Responding to Clients in Service Methods

In subclasses of ServerCoreStandardServiceBase, the following methods are available for responding:

// Send data (without closing the connection)
await Send("message text");
await Send(new { code = 0, data = "ok" }); // Automatically serialized to JSON

// Send data and close the request (most common)
await Close("response content");
await Close(new { result = 42 });

// Mark the request as handled (for synchronous methods, sends no response body)
OK();

// Return an error message (throw to send the error and stop further processing)
throw Error("Missing parameters", HttpStatusCode.BadRequest);
await CloseWithError("Unauthorized", HttpStatusCode.Unauthorized);

Client Side

Setting Up a Requester

Use XFEClientRequesterBuilder to build an XFEClientRequester:

using XFEExtension.NetCore.ServerInteractive.Utilities.Requester;

var requester = XFEClientRequesterBuilder.CreateBuilder()
    .AddRequest("echo", (session, deviceInfo, parameters) => new
    {
        execute = "echo",
        message = parameters.Length > 0 ? parameters[0] : string.Empty
    }, response => response)
    .Build(options =>
    {
        options.RequestAddress = "http://localhost:3300";  // Server address
        options.Session = string.Empty;                    // User session (updated after login)
        options.DeviceInfo = DeviceHelper.GetUniqueHardwareId(); // Unique device identifier
    });

// Make a request
var result = await requester.Request<string>("echo", "Hello, World!");
if (result.StatusCode == HttpStatusCode.OK)
    Console.WriteLine(result.Result);  // Output: Hello, World!
else
    Console.WriteLine($"Failed: {result.StatusCode} {result.Message}");

XFEClientRequesterOptions properties:

Inline Request Registration

AddRequest(route, constructBody, processResponse) is suitable for simple one-off requests:

var requester = XFEClientRequesterBuilder.CreateBuilder()
    // Request with no parameters
    .AddRequest("status", (_, _, _) => new { execute = "status" }, response => response)
    // Request with parameters
    .AddRequest("math/add", (_, _, parameters) => new
    {
        execute = "math/add",
        a = parameters.Length > 0 ? parameters[0] : 0,
        b = parameters.Length > 1 ? parameters[1] : 0
    }, response => response)
    // Login request example with session and deviceInfo
    .AddRequest("login", (session, deviceInfo, parameters) => new
    {
        execute = "login",
        account = parameters[0],
        password = parameters[1],
        deviceInfo
    }, response => JsonSerializer.Deserialize<UserLoginResult<UserFaceInfo>>(response)!)
    .Build(options =>
    {
        options.RequestAddress = "http://localhost:3300";
    });

• constructBody: (string session, string deviceInfo, object[] parameters) => object — returns the request body object (automatically JSON-serialized).
• processResponse: (string response) => object — parses the response string; can be null (no processing).

Defining Standard Request Services (Source Generator)

Inherit StandardRequestServiceBase and use the [Request]/[Response] attributes.
The class must be declared as partial.

using XFEExtension.NetCore.ServerInteractive.Attributes;
using XFEExtension.NetCore.ServerInteractive.Implements.Requester;

public partial class MathRequestService : StandardRequestServiceBase
{
    // [Request] marks the method that constructs the request body; Path is the route path, Name is an optional call alias
    [Request("math/add", Name = "add")]
    public object BuildAddRequest() => new
    {
        execute = "math/add",
        a = Parameters.Length > 0 ? Parameters[0] : 0,
        b = Parameters.Length > 1 ? Parameters[1] : 0
    };

    // [Response] marks the method that parses the response; Path and Name correspond to those in [Request]
    [Response("math/add", Name = "add")]
    public object ParseAddResponse() => double.Parse(UnescapedResponse);

    [Request("math/multiply")]
    public object BuildMultiplyRequest() => new
    {
        execute = "math/multiply",
        a = Parameters.Length > 0 ? Parameters[0] : 0,
        b = Parameters.Length > 1 ? Parameters[1] : 0
    };

    [Response("math/multiply")]
    public object ParseMultiplyResponse() => double.Parse(UnescapedResponse);
}

Properties accessible in [Request]/[Response] methods:

Register with the requester:

var requester = XFEClientRequesterBuilder.CreateBuilder()
    .AddRequest<MathRequestService>()   // Automatically reads routes from [Request]/[Response] and registers
    .Build(options =>
    {
        options.RequestAddress = "http://localhost:3300";
    });

// Call using the route path
var result1 = await requester.Request<double>("math/add", 3.0, 5.0);
// Call using the Name alias (equivalent)
var result2 = await requester.Request<double>("add", 3.0, 5.0);

Using XFE Standard Requests

The UseXFEStandardRequest<T>() extension method registers all standard service requests in one call (login, re-login, IP banning, logging, connection check):

using XFEExtension.NetCore.ServerInteractive.Utilities.Extensions;
using XFEExtension.NetCore.ServerInteractive.Utilities.Requester;

var requester = XFEClientRequesterBuilder.CreateBuilder()
    .UseXFEStandardRequest<UserFaceInfo>()   // T is the implementing class of the user info interface returned on login
    .Build(options =>
    {
        options.RequestAddress = "http://localhost:3300";
    });

// Login
var loginResult = await requester.Request<UserLoginResult<UserFaceInfo>>("login", "your-account", "your-password");
if (loginResult.StatusCode == HttpStatusCode.OK)
{
    Console.WriteLine($"Session: {loginResult.Result.Session}");
    Console.WriteLine($"Expiry: {loginResult.Result.ExpireDate}");
    Console.WriteLine($"Nickname: {loginResult.Result.UserInfo.NickName}");
    requester.Session = loginResult.Result.Session;  // Save session for subsequent requests
}

// Re-login (automatically verified using Session + device info)
var reloginResult = await requester.Request<UserFaceInfo>("relogin");

// Check connection
var checkResult = await requester.Request<DateTime>("check_connect");

// Get logs
var logResult = await requester.Request<string>("get_log", DateTime.MinValue, DateTime.MaxValue);

// IP ban management
// Note: AddBannedIPRequest() registers call names get_bannedIPList / add_bannedIP / remove_bannedIP
// which correspond to server routes ip/banned/get / ip/banned/add / ip/banned/remove
var bannedIPs = await requester.Request<List<IPAddressInfo>>("get_bannedIPList");
await requester.Request<string>("add_bannedIP", "192.168.1.100", "Malicious request");
await requester.Request<bool>("remove_bannedIP", "192.168.1.100");

UseXFEStandardRequest<T>() is equivalent to:

.AddLoginRequest<T>()        // Register login (→ user/login) and relogin (→ user/relogin) requests
.AddBannedIPRequest()        // Register get_bannedIPList, add_bannedIP, remove_bannedIP requests
                             //   corresponding to server routes: ip/banned/get, ip/banned/add, ip/banned/remove
.AddLogRequest()             // Register get_log (→ log/get) and clear_log (→ log/clear) requests
.AddCheckConnectRequest()    // Register check_connect request

TableRequester (Data Table Requester)

TableRequester is specifically designed for CRUD interactions with the server-side data table manager:

var tableRequester = new TableRequester
{
    RequestAddress = "http://localhost:3300",
    Session = "your-session-here",
    DeviceInfo = DeviceHelper.GetUniqueHardwareId()
};

// Get all orders (no pagination)
var result = await tableRequester.Get<Order>();
foreach (var order in result.DataList)
    Console.WriteLine($"ID:{order.Id}\tName:{order.Name}");

// Paginated get (10 per page, page 1)
var paged = await tableRequester.Get<Order>(pageSize: 10, page: 1);

// Add data
bool success = await tableRequester.Add(new Order { Name = "New Order", Description = "Description" });

// Change data (matched by Id)
var order = result.DataList[0];
order.Name = "Updated Name";
await tableRequester.Change(order);

// Remove data
await tableRequester.Remove<Order>(order.Id);

The table name is inferred from the type name by default: the type name with its first letter lowercased is used as the request table name (TableNameInRequest). For example, Order → order.
This is the name actually used by TableRequester when communicating with the server, which differs from the tableShowName (display name, e.g., "Orders") specified in AddTable.

// Default: Order type → request table name is automatically inferred as "order" (type name with first letter lowercased)
await tableRequester.Get<Order>();

// Manually specify the request table name (must match the server-side TableNameInRequest, i.e., the type name with first letter lowercased)
// Note: This is the table name used in the request path, not the tableShowName specified in AddTable
await tableRequester.Get<Order>("order", pageSize: 10, page: 1);

Data models must implement the IIdModel interface (which includes a string Id property):

public class Order : IIdModel
{
    public string Id { get; set; } = Guid.NewGuid().ToString();
    public string Name { get; set; } = string.Empty;
    public string Description { get; set; } = string.Empty;
}

Source Generator

This library provides two incremental source generators that automatically generate route dictionaries for service classes and request classes at compile time, eliminating the need for manual maintenance.

Server Side: EntryPoint Generator

Automatically generates SyncEntryPoints and AsyncEntryPoints dictionaries for partial classes that inherit ServerCoreStandardServiceBase.

Requirements:

• The class must be declared as partial
• Method return types must be void (synchronous) or Task (asynchronous)
• Methods must not have parameters
• Route paths must not contain quotes (") or backslashes (\)
• The wildcard * must be a complete path segment (cannot be mixed with other characters)
• A single class cannot have more than one handler for the same route path

Example:

public partial class ApiService : ServerCoreStandardServiceBase
{
    [EntryPoint("user/profile")]
    [NoLog]
    public async Task GetProfile()
    {
        // ...
    }

    [EntryPoint("user/update")]
    public void UpdateUser()
    {
        // ...
    }

    // Wildcard route: matches resource/anything/details
    [EntryPoint("resource/*/details")]
    public async Task ResourceDetails()
    {
        // Route contains the actual matched path
        await Close($"Resource detail for {Route}");
    }
}

The generator automatically produces (no manual writing required):

// ApiService.EntryPoints.g.cs (auto-generated, shown for illustration only)
public override Dictionary<string, Action> SyncEntryPoints => new()
{
    { "user/update", UpdateUser },
};

public override Dictionary<string, Func<Task>> AsyncEntryPoints => new()
{
    { "user/profile", GetProfile },
    { "resource/*/details", ResourceDetails },
};

public override HashSet<string> NoLogEntryPoints => new()
{
    "user/profile",
};

Client Side: ClientRequest Generator

Automatically generates RequestPoints, ResponsePoints, and RequestRouteMap dictionaries for partial classes that inherit StandardRequestServiceBase.

Requirements:

• The class must be declared as partial
• Method return types must be object
• Methods must not have parameters
• The same path or name (within [Request] or [Response]) cannot be registered more than once within a single class

Example:

public partial class UserRequestService<T> : StandardRequestServiceBase where T : IUserFaceInfo
{
    // Path is the route path; Name is an optional request alias (you can call using either Path or Name)
    [Request("login", Name = "login")]
    public object LoginRequest() => new
    {
        execute = "login",
        account = Parameters[0],
        password = Parameters[1],
        deviceInfo = DeviceInfo
    };

    [Response("login", Name = "login")]
    public object LoginResponse() => JsonSerializer.Deserialize<UserLoginResult<T>>(UnescapedResponse)!;

    [Request("relogin", Name = "relogin")]
    public object ReloginRequest() => new
    {
        execute = "relogin",
        session = Session,
        deviceInfo = DeviceInfo
    };

    [Response("relogin", Name = "relogin")]
    public object ReloginResponse() => JsonSerializer.Deserialize<T>(UnescapedResponse)!;
}

Diagnostic Rules

The incremental generators check code at compile time and report diagnostics:

All diagnostics have corresponding online documentation at: https://docs.xfegzs.com/View/Errors/ServerInteractive/XFE{code} (e.g., https://docs.xfegzs.com/View/Errors/ServerInteractive/XFE0003)

Common Errors and Solutions

Q: The service is not receiving requests and there is no console output

• Confirm that the correct address is bound in XFEServerCoreBuilder.Build(options => { options.BindIP("..."); })
• If MainEntryPoint is set, request paths must include that prefix — for example, if api is set, request /api/echo

Q: InvalidOperationException: EntryPointList for type MyService is empty

• Confirm that MyService inherits ServerCoreStandardServiceBase
• Confirm that the class is declared with the partial keyword
• Confirm that the method has a [EntryPoint("path")] attribute with a non-empty path

Q: XFEServerBuilderException: No core processor has been added

• Before calling XFEServerBuilder.Build(), you must call AddCoreProcessor<T>(), or use the UseXFEServer() extension method

Q: A route is matching an unexpected service

• The framework uses the "most-specific-first" principle: route patterns with more literal segments have higher priority, regardless of registration order
• Exact routes (without wildcards) always take priority over wildcard routes

Q: The return type of a [Request]/[Response] method is causing an error

• The method must declare object as its return type (it cannot be string, int, or any other specific type)

Q: Client requests always return 500

• Ensure options.RequestAddress does not have a trailing slash — the requester builds URLs as RequestAddress + "/" + route, so a trailing slash would create a double slash (e.g., use "http://localhost:3300" not "http://localhost:3300/")
• Confirm that the server-side route exactly matches the request name (case-sensitive)