Tài liệu

Request Options và RequestOutcome

Thời gian đọc 3 phút Gói: Nalix.SDK
Trên trang này

Không gian tên: Nalix.SDK.Options
Assembly: Nalix.SDK

RequestOptions (public sealed record RequestOptions) cấu hình timeout, retry và hành vi mã hóa khung cho từng lệnh gọi RequestAsync<TResponse>, TryRequestAsync<TResponse>, StreamAsync, RequestWithStreamAsync và CreateRpcClient<T>. RequestOutcome<T> (public readonly struct RequestOutcome<T>) và RequestOutcomeKind biểu diễn kết quả không ném ngoại lệ được trả về bởi TryRequestAsync<TResponse>.

Ánh xạ mã nguồn

  • src/Nalix.SDK/Options/RequestOptions.cs
  • src/Nalix.SDK/Options/RequestOutcome.cs
  • src/Nalix.SDK/Transport/Extensions/RequestExtensions.cs

1. Tham chiếu RequestOptions

namespace Nalix.SDK.Options;

public sealed record RequestOptions
{
    public const int DefaultTimeoutMs = 5_000;
    public static RequestOptions Default { get; } = new();

    public int TimeoutMs { get; init; } = DefaultTimeoutMs;
    public int RetryCount { get; init; }
    public bool Encrypt { get; init; }

    public void Validate();

    public RequestOptions WithTimeout(int ms);
    public RequestOptions WithRetry(int count);
    public RequestOptions WithEncrypt(bool encrypt = true);
}

Thuộc tính và giá trị mặc định

Thuộc tínhKiểuMặc địnhKiểm tra hợp lệTác động khi chạy
TimeoutMsint5_000 (5s)>= 0 (ArgumentOutOfRangeException)Số mili giây chờ phản hồi cho mỗi lần thử (0 chờ vô thời hạn).
RetryCountint0>= 0 (ArgumentOutOfRangeException)Số lần thử bổ sung ngay sau một TimeoutException (0 = một lần thử duy nhất; tổng thời gian tối đa là TimeoutMs * (RetryCount + 1)).
Encryptboolfalse—Khi true, bắt buộc mã hóa khung gửi đi (client.SendAsync(request, encrypt: true, ct)) trên mọi ITransportSession (TcpSession, UdpSession hoặc WebSocketSession).

2. Tham chiếu RequestOutcome<T> và RequestOutcomeKind

namespace Nalix.SDK.Options;

public enum RequestOutcomeKind
{
    Ok,
    NotConnected,
    TimedOut,
    Failed
}

public readonly struct RequestOutcome<T>
{
    public RequestOutcomeKind Kind { get; }
    public T? Value { get; }
    public Exception? Error { get; }

    public static RequestOutcome<T> Ok(T value);
    public static RequestOutcome<T> Fail(RequestOutcomeKind kind, Exception error);
}
RequestOutcomeKindValueErrorĐiều kiện kích hoạt trong TryRequestAsync<T>
OkInstance phản hồi TnullGói tin TResponse tương ứng đã đến và vượt qua predicate tùy chọn (nếu có).
NotConnecteddefaultNetworkExceptionPhiên đã bị ngắt (!client.IsConnected) khi yêu cầu thất bại.
TimedOutdefaultTimeoutExceptionTất cả RetryCount + 1 lần thử đều hết thời gian chờ mà không có phản hồi khớp.
FaileddefaultNetworkExceptionViệc gửi khung hoặc thao tác giao thức thất bại trong khi vẫn đang kết nối.

Ví dụ sử dụng

using System;
using Nalix.SDK.Options;
using Nalix.SDK.Transport.Extensions;

RequestOptions options = RequestOptions.Default
    .WithTimeout(3_000)
    .WithRetry(2)
    .WithEncrypt();

RequestOutcome<PingReplyPacket> result = await session.TryRequestAsync<PingReplyPacket>(
    new PingRequestPacket(),
    options);

if (result.Kind == RequestOutcomeKind.Ok)
{
    Console.WriteLine($"Reply received: {result.Value}");
}
else
{
    Console.WriteLine($"Failed ({result.Kind}): {result.Error?.Message}");
}

API liên quan