You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@opendal.apache.org by er...@apache.org on 2026/09/23 13:59:22 UTC

(opendal) branch main updated: feat(bindings/dotnet): add Exists and Check (#8337)

This is an automated email from the ASF dual-hosted git repository.

erickguan pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/opendal.git


The following commit(s) were added to refs/heads/main by this push:
     new 23c466f5a5 feat(bindings/dotnet): add Exists and Check (#8337)
23c466f5a5 is described below

commit 23c466f5a52e1231236b10be483affa622b04255
Author: Fatorin <sk...@gmail.com>
AuthorDate: Wed Sep 23 21:59:12 2026 +0800

    feat(bindings/dotnet): add Exists and Check (#8337)
    
    * feat(bindings/dotnet): add Exists and ExistsAsync
    
    * feat(bindings/dotnet): add Check and CheckAsync
---
 .../OpenDAL.Tests/Behavior/ListBehaviorTest.cs     |  22 +++
 .../OpenDAL.Tests/Behavior/StatBehaviorTest.cs     |  34 +++++
 .../OpenDAL/Interop/Result/OpenDALBoolResult.cs    |  46 +++++++
 bindings/dotnet/OpenDAL/NativeMethods.cs           |  36 +++++
 bindings/dotnet/OpenDAL/Operator.cs                | 110 +++++++++++++++
 bindings/dotnet/src/operator.rs                    | 152 ++++++++++++++++++++-
 bindings/dotnet/src/result.rs                      |  14 ++
 website/docs/20-bindings/dotnet/03-connecting.md   |  10 ++
 website/docs/20-bindings/dotnet/04-tasks.md        |  11 ++
 9 files changed, 432 insertions(+), 3 deletions(-)

diff --git a/bindings/dotnet/OpenDAL.Tests/Behavior/ListBehaviorTest.cs b/bindings/dotnet/OpenDAL.Tests/Behavior/ListBehaviorTest.cs
index 4e1a441e92..f901090ea1 100644
--- a/bindings/dotnet/OpenDAL.Tests/Behavior/ListBehaviorTest.cs
+++ b/bindings/dotnet/OpenDAL.Tests/Behavior/ListBehaviorTest.cs
@@ -31,6 +31,28 @@ public sealed class ListBehaviorTest : BehaviorTestBase
     {
     }
 
+    [Fact]
+    public void ListBehavior_Check_Succeeds()
+    {
+        if (!Supports(c => c.Read && c.Write && c.List))
+        {
+            return;
+        }
+
+        Op.Check();
+    }
+
+    [Fact]
+    public async Task ListBehavior_Check_SucceedsAsync()
+    {
+        if (!Supports(c => c.Read && c.Write && c.List))
+        {
+            return;
+        }
+
+        await Op.CheckAsync(CT);
+    }
+
     [Fact]
     public void ListBehavior_ListsEntriesUnderPrefix()
     {
diff --git a/bindings/dotnet/OpenDAL.Tests/Behavior/StatBehaviorTest.cs b/bindings/dotnet/OpenDAL.Tests/Behavior/StatBehaviorTest.cs
index 45661062f1..791a1a8037 100644
--- a/bindings/dotnet/OpenDAL.Tests/Behavior/StatBehaviorTest.cs
+++ b/bindings/dotnet/OpenDAL.Tests/Behavior/StatBehaviorTest.cs
@@ -91,6 +91,40 @@ public sealed class StatBehaviorTest : BehaviorTestBase
         Assert.True(IsMissingError(ex));
     }
 
+    [Fact]
+    public void StatBehavior_Exists_ReportsPresence()
+    {
+        if (!Supports(c => c.Stat && c.Write))
+        {
+            return;
+        }
+
+        var path = NewPath("exists");
+
+        Assert.False(Op.Exists(path));
+
+        Op.Write(path, RandomBytes(16));
+
+        Assert.True(Op.Exists(path));
+    }
+
+    [Fact]
+    public async Task StatBehavior_Exists_ReportsPresenceAsync()
+    {
+        if (!Supports(c => c.Stat && c.Write))
+        {
+            return;
+        }
+
+        var path = NewPath("exists-async");
+
+        Assert.False(await Op.ExistsAsync(path, CT));
+
+        await Op.WriteAsync(path, RandomBytes(16), cancellationToken: CT);
+
+        Assert.True(await Op.ExistsAsync(path, CT));
+    }
+
     [Fact]
     public void StatBehavior_WithIfModifiedSince_AppliesCondition()
     {
diff --git a/bindings/dotnet/OpenDAL/Interop/Result/OpenDALBoolResult.cs b/bindings/dotnet/OpenDAL/Interop/Result/OpenDALBoolResult.cs
new file mode 100644
index 0000000000..114b2fc2b8
--- /dev/null
+++ b/bindings/dotnet/OpenDAL/Interop/Result/OpenDALBoolResult.cs
@@ -0,0 +1,46 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+using System.Runtime.InteropServices;
+using OpenDAL.Interop.Result.Abstractions;
+
+namespace OpenDAL.Interop.Result;
+
+[StructLayout(LayoutKind.Sequential)]
+internal struct OpenDALBoolResult : INativeValueResult<bool>
+{
+    public byte Value;
+
+    public OpenDALError Error;
+
+    public readonly void Release()
+    {
+        NativeMethods.opendal_error_release(Error);
+    }
+
+    public readonly OpenDALError GetError()
+    {
+        return Error;
+    }
+
+    public readonly bool ToValue()
+    {
+        return Value != 0;
+    }
+}
diff --git a/bindings/dotnet/OpenDAL/NativeMethods.cs b/bindings/dotnet/OpenDAL/NativeMethods.cs
index cdadba2c6f..2126192003 100644
--- a/bindings/dotnet/OpenDAL/NativeMethods.cs
+++ b/bindings/dotnet/OpenDAL/NativeMethods.cs
@@ -332,6 +332,42 @@ internal partial class NativeMethods
 
     #endregion
 
+    #region Exists
+
+    [LibraryImport(__DllName, EntryPoint = "operator_exists", StringMarshalling = StringMarshalling.Utf8)]
+    [UnmanagedCallConv(CallConvs = [typeof(CallConvCdecl)])]
+    internal static partial OpenDALBoolResult operator_exists(
+        Operator op,
+        string path
+    );
+
+    [LibraryImport(__DllName, EntryPoint = "operator_exists_async", StringMarshalling = StringMarshalling.Utf8)]
+    [UnmanagedCallConv(CallConvs = [typeof(CallConvCdecl)])]
+    internal static unsafe partial OpenDALResult operator_exists_async(
+        Operator op,
+        string path,
+        delegate* unmanaged[Cdecl]<long, OpenDALBoolResult, void> callback,
+        long context
+    );
+
+    #endregion
+
+    #region Check
+
+    [LibraryImport(__DllName, EntryPoint = "operator_check")]
+    [UnmanagedCallConv(CallConvs = [typeof(CallConvCdecl)])]
+    internal static partial OpenDALResult operator_check(Operator op);
+
+    [LibraryImport(__DllName, EntryPoint = "operator_check_async")]
+    [UnmanagedCallConv(CallConvs = [typeof(CallConvCdecl)])]
+    internal static unsafe partial OpenDALResult operator_check_async(
+        Operator op,
+        delegate* unmanaged[Cdecl]<long, OpenDALResult, void> callback,
+        long context
+    );
+
+    #endregion
+
     #region List
 
     [LibraryImport(__DllName, EntryPoint = "operator_list_with_options", StringMarshalling = StringMarshalling.Utf8)]
diff --git a/bindings/dotnet/OpenDAL/Operator.cs b/bindings/dotnet/OpenDAL/Operator.cs
index 1421c2542f..0dc8278c58 100644
--- a/bindings/dotnet/OpenDAL/Operator.cs
+++ b/bindings/dotnet/OpenDAL/Operator.cs
@@ -656,6 +656,94 @@ public partial class Operator : SafeHandle
         }
     }
 
+    /// <summary>
+    /// Checks whether the specified path exists.
+    /// </summary>
+    /// <remarks>
+    /// A <c>NotFound</c> error from the backend yields <see langword="false"/>;
+    /// any other error is thrown.
+    /// </remarks>
+    /// <param name="path">Target path in the configured backend.</param>
+    /// <returns><see langword="true"/> when the path exists.</returns>
+    public bool Exists(string path)
+    {
+        ObjectDisposedException.ThrowIf(IsInvalid, this);
+        var result = NativeMethods.operator_exists(this, path);
+        return ToValueOrThrowAndRelease<bool, OpenDALBoolResult>(result);
+    }
+
+    /// <summary>
+    /// Checks whether the specified path exists asynchronously.
+    /// </summary>
+    /// <remarks>
+    /// A <c>NotFound</c> error from the backend yields <see langword="false"/>;
+    /// any other error is thrown.
+    /// </remarks>
+    /// <param name="path">Target path in the configured backend.</param>
+    /// <param name="cancellationToken">Cancellation token for the managed task.</param>
+    /// <returns>A task that resolves with <see langword="true"/> when the path exists.</returns>
+    public Task<bool> ExistsAsync(string path, CancellationToken cancellationToken = default)
+    {
+        ObjectDisposedException.ThrowIf(IsInvalid, this);
+
+        return SubmitAsyncOperation<bool>(SubmitExistsAsync, cancellationToken);
+
+        OpenDALResult SubmitExistsAsync(long context)
+        {
+            unsafe
+            {
+                return NativeMethods.operator_exists_async(
+                    this,
+                    path,
+                    &OnExistsCompleted,
+                    context
+                );
+            }
+        }
+    }
+
+    /// <summary>
+    /// Checks whether the operator can reach its service.
+    /// </summary>
+    /// <remarks>
+    /// Lists the root with a limit of one entry. A <c>NotFound</c> error is
+    /// treated as success; any other error is thrown.
+    /// </remarks>
+    public void Check()
+    {
+        ObjectDisposedException.ThrowIf(IsInvalid, this);
+        var result = NativeMethods.operator_check(this);
+        ThrowIfErrorAndRelease(result);
+    }
+
+    /// <summary>
+    /// Checks whether the operator can reach its service asynchronously.
+    /// </summary>
+    /// <remarks>
+    /// Lists the root with a limit of one entry. A <c>NotFound</c> error is
+    /// treated as success; any other error is thrown.
+    /// </remarks>
+    /// <param name="cancellationToken">Cancellation token for the managed task.</param>
+    /// <returns>A task that completes when the native callback reports completion.</returns>
+    public Task CheckAsync(CancellationToken cancellationToken = default)
+    {
+        ObjectDisposedException.ThrowIf(IsInvalid, this);
+
+        return SubmitAsyncOperation(SubmitCheckAsync, cancellationToken);
+
+        OpenDALResult SubmitCheckAsync(long context)
+        {
+            unsafe
+            {
+                return NativeMethods.operator_check_async(
+                    this,
+                    &OnCheckCompleted,
+                    context
+                );
+            }
+        }
+    }
+
     /// <summary>
     /// Lists entries under the specified path.
     /// </summary>
@@ -1470,6 +1558,28 @@ public partial class Operator : SafeHandle
         CompleteAsyncCallback<Metadata, OpenDALMetadataResult>(context, result);
     }
 
+    /// <summary>
+    /// Native callback invoked when an asynchronous exists operation finishes.
+    /// </summary>
+    /// <param name="context">Opaque async state context previously registered by <see cref="AsyncStateRegistry"/>.</param>
+    /// <param name="result">Exists completion result returned by the native layer.</param>
+    [UnmanagedCallersOnly(CallConvs = [typeof(CallConvCdecl)])]
+    private static void OnExistsCompleted(long context, OpenDALBoolResult result)
+    {
+        CompleteAsyncCallback<bool, OpenDALBoolResult>(context, result);
+    }
+
+    /// <summary>
+    /// Native callback invoked when an asynchronous check operation finishes.
+    /// </summary>
+    /// <param name="context">Opaque async state context previously registered by <see cref="AsyncStateRegistry"/>.</param>
+    /// <param name="result">Check completion result returned by the native layer.</param>
+    [UnmanagedCallersOnly(CallConvs = [typeof(CallConvCdecl)])]
+    private static void OnCheckCompleted(long context, OpenDALResult result)
+    {
+        CompleteAsyncCallback(context, result);
+    }
+
     /// <summary>
     /// Native callback invoked when an asynchronous list operation finishes.
     /// </summary>
diff --git a/bindings/dotnet/src/operator.rs b/bindings/dotnet/src/operator.rs
index a143ae7412..001052512f 100644
--- a/bindings/dotnet/src/operator.rs
+++ b/bindings/dotnet/src/operator.rs
@@ -28,9 +28,9 @@ use crate::{
     },
     presign::into_presigned_request_ptr,
     result::{
-        OpendalEntryListResult, OpendalMetadataResult, OpendalOperatorInfoResult,
-        OpendalOperatorResult, OpendalOptionsResult, OpendalPresignedRequestResult,
-        OpendalReadResult, OpendalResult,
+        OpendalBoolResult, OpendalEntryListResult, OpendalMetadataResult,
+        OpendalOperatorInfoResult, OpendalOperatorResult, OpendalOptionsResult,
+        OpendalPresignedRequestResult, OpendalReadResult, OpendalResult,
     },
     utils::{collect_options, require_callback, require_cstr, require_data_ptr, require_op_handle},
     validators::prelude::{
@@ -94,6 +94,7 @@ impl std::ops::Deref for OperatorHandle {
 /// invoked by Rust. `VoidCallback` reports success or failure only, while
 /// `MetadataCallback` carries the metadata that write, copy, and stat return.
 type VoidCallback = extern "C" fn(context: i64, result: OpendalResult);
+type BoolCallback = extern "C" fn(context: i64, result: OpendalBoolResult);
 type ReadCallback = extern "C" fn(context: i64, result: OpendalReadResult);
 type MetadataCallback = extern "C" fn(context: i64, result: OpendalMetadataResult);
 type ListCallback = extern "C" fn(context: i64, result: OpendalEntryListResult);
@@ -2230,6 +2231,151 @@ fn operator_stat_with_options_async_inner(
     Ok(())
 }
 
+/// Check whether `path` exists synchronously.
+/// # Safety
+///
+/// - `op_handle` must be a valid operator pointer from `operator_construct`.
+/// - `path` must be a valid null-terminated UTF-8 string.
+#[unsafe(no_mangle)]
+pub extern "C" fn operator_exists(
+    op_handle: *const OperatorHandle,
+    path: *const c_char,
+) -> OpendalBoolResult {
+    match operator_exists_inner(op_handle, path) {
+        Ok(value) => OpendalBoolResult::ok(value as u8),
+        Err(error) => OpendalBoolResult::from_error(error),
+    }
+}
+
+fn operator_exists_inner(
+    op_handle: *const OperatorHandle,
+    path: *const c_char,
+) -> Result<bool, OpenDALError> {
+    let handle = require_op_handle(op_handle)?;
+    let executor = handle.executor.clone();
+    let path = require_cstr(path, "path")?;
+
+    executor
+        .block_on(handle.exists(path))
+        .map_err(OpenDALError::from_opendal_error)
+}
+
+/// Check whether `path` exists asynchronously.
+///
+/// The callback is invoked exactly once with the final result.
+/// # Safety
+///
+/// - `op_handle` must be a valid operator pointer from `operator_construct`.
+/// - `path` must be a valid null-terminated UTF-8 string.
+/// - `callback` must be a valid function pointer and remain callable until invoked.
+#[unsafe(no_mangle)]
+pub extern "C" fn operator_exists_async(
+    op_handle: *const OperatorHandle,
+    path: *const c_char,
+    callback: Option<BoolCallback>,
+    context: i64,
+) -> OpendalResult {
+    match operator_exists_async_inner(op_handle, path, callback, context) {
+        Ok(()) => OpendalResult::ok(),
+        Err(error) => OpendalResult::from_error(error),
+    }
+}
+
+fn operator_exists_async_inner(
+    op_handle: *const OperatorHandle,
+    path: *const c_char,
+    callback: Option<BoolCallback>,
+    context: i64,
+) -> Result<(), OpenDALError> {
+    let handle = require_op_handle(op_handle)?;
+    let executor = handle.executor.clone();
+    let path = require_cstr(path, "path")?.to_string();
+    let callback = require_callback(callback)?;
+
+    let op = handle.operator();
+    executor.spawn(async move {
+        let result = op
+            .exists(&path)
+            .await
+            .map_err(OpenDALError::from_opendal_error);
+
+        callback(
+            context,
+            match result {
+                Ok(value) => OpendalBoolResult::ok(value as u8),
+                Err(error) => OpendalBoolResult::from_error(error),
+            },
+        );
+    });
+
+    Ok(())
+}
+
+/// Check whether the operator can reach its service.
+/// # Safety
+///
+/// - `op_handle` must be a valid operator pointer from `operator_construct`.
+#[unsafe(no_mangle)]
+pub extern "C" fn operator_check(op_handle: *const OperatorHandle) -> OpendalResult {
+    match operator_check_inner(op_handle) {
+        Ok(()) => OpendalResult::ok(),
+        Err(error) => OpendalResult::from_error(error),
+    }
+}
+
+fn operator_check_inner(op_handle: *const OperatorHandle) -> Result<(), OpenDALError> {
+    let handle = require_op_handle(op_handle)?;
+    let executor = handle.executor.clone();
+
+    executor
+        .block_on(handle.check())
+        .map_err(OpenDALError::from_opendal_error)
+}
+
+/// Check whether the operator can reach its service asynchronously.
+///
+/// The callback is invoked exactly once with the final result.
+/// # Safety
+///
+/// - `op_handle` must be a valid operator pointer from `operator_construct`.
+/// - `callback` must be a valid function pointer and remain callable until invoked.
+#[unsafe(no_mangle)]
+pub extern "C" fn operator_check_async(
+    op_handle: *const OperatorHandle,
+    callback: Option<VoidCallback>,
+    context: i64,
+) -> OpendalResult {
+    match operator_check_async_inner(op_handle, callback, context) {
+        Ok(()) => OpendalResult::ok(),
+        Err(error) => OpendalResult::from_error(error),
+    }
+}
+
+fn operator_check_async_inner(
+    op_handle: *const OperatorHandle,
+    callback: Option<VoidCallback>,
+    context: i64,
+) -> Result<(), OpenDALError> {
+    let handle = require_op_handle(op_handle)?;
+    let executor = handle.executor.clone();
+    let callback = require_callback(callback)?;
+
+    let op = handle.operator();
+    executor.spawn(async move {
+        let result = op.check().await.map_err(OpenDALError::from_opendal_error);
+
+        callback(
+            context,
+            match result {
+                Ok(()) => OpendalResult::ok(),
+                Err(error) => OpendalResult::from_error(error),
+            },
+        );
+    });
+
+    Ok(())
+}
+
 /// List entries from `path` synchronously with options.
 ///
 /// On success, returned payload must be released with `opendal_entry_list_result_release`.
diff --git a/bindings/dotnet/src/result.rs b/bindings/dotnet/src/result.rs
index 617fea7ab9..519eeb140e 100644
--- a/bindings/dotnet/src/result.rs
+++ b/bindings/dotnet/src/result.rs
@@ -48,6 +48,14 @@ pub struct OpendalResult {
     pub error: OpenDALError,
 }
 
+#[repr(C)]
+/// Result for operations returning a boolean value.
+pub struct OpendalBoolResult {
+    /// `1` for true, `0` for false.
+    pub value: u8,
+    pub error: OpenDALError,
+}
+
 #[repr(C)]
 /// Result for operations returning an operator handle pointer.
 pub struct OpendalOperatorResult {
@@ -155,6 +163,12 @@ macro_rules! define_result {
 
 define_result!(OpendalResult);
 
+define_result!(
+    OpendalBoolResult,
+    field = value: u8,
+    error_value = 0
+);
+
 define_result!(
     OpendalOperatorResult,
     field = ptr: *mut c_void,
diff --git a/website/docs/20-bindings/dotnet/03-connecting.md b/website/docs/20-bindings/dotnet/03-connecting.md
index 5f4d06c96e..ec96f9b69a 100644
--- a/website/docs/20-bindings/dotnet/03-connecting.md
+++ b/website/docs/20-bindings/dotnet/03-connecting.md
@@ -94,6 +94,16 @@ page under [Services](/services) for the exact keys and credential behavior.
 Avoid hard-coding secrets in source. Read them from the environment or a secret
 manager and pass them in when you build the operator.
 
+## Verify the connection
+
+`Check` lists the service root and throws `OpenDALException` when the service
+is unreachable or rejects the request. Call it at startup so wrong credentials
+or endpoints fail there instead of on the first real operation:
+
+```csharp
+await op.CheckAsync();
+```
+
 ## One operator per service and root
 
 An operator maps to one service, one root path, and one executor. To work with
diff --git a/website/docs/20-bindings/dotnet/04-tasks.md b/website/docs/20-bindings/dotnet/04-tasks.md
index 451c3d31e0..a52a380b31 100644
--- a/website/docs/20-bindings/dotnet/04-tasks.md
+++ b/website/docs/20-bindings/dotnet/04-tasks.md
@@ -128,6 +128,17 @@ buffered before flushing to the backend.
 
 ## Check existence and metadata
 
+`Exists` returns `false` instead of throwing when the path is missing:
+
+```csharp
+if (op.Exists("path/to/file"))
+{
+    Console.WriteLine("found");
+}
+```
+
+`Stat` returns the metadata:
+
 ```csharp
 var meta = op.Stat("path/to/file");
 Console.WriteLine($"{meta.ContentLength} bytes, dir = {meta.IsDir}");