👁 Image
Dosaic.Plugins.Persistence.Smb 1.2.35

Dosaic.Plugins.Persistence.Smb

Dosaic.Plugins.Persistence.Smb is a plugin that provides SMB/CIFS (Samba) file storage for Dosaic applications. It exposes an ISmbStorage abstraction for reading, writing, deleting, and managing files and folders on SMB-compatible network shares, with support for drive mappings, share mappings, and automatic path resolution.

Installation

dotnet add package Dosaic.Plugins.Persistence.Smb

Or add as a package reference to your .csproj:

<PackageReference Include="Dosaic.Plugins.Persistence.Smb" Version="" />

Configuration

The plugin binds its configuration from the smb section (via [Configuration("smb")]).

appsettings.yml

smb:
 server: example.com
 domain: mydomain.com
 username: smbuser
 password: s3cr3t
 defaultShare: myshare
 driveMappings:
 - drive: 'J:'
 share: docs
 - drive: 'K:'
 share: archive
 shareMappings:
 - folder: Reports
 share: reports-share
 - folder: Uploads
 share: uploads-share

Configuration Properties

Path resolution order

1. Drive mappings — if the path starts with a mapped drive letter (e.g. J:\Reports\file.pdf), the drive is replaced with the corresponding share.
2. Share mappings — if the path starts with a mapped folder prefix (e.g. Reports\file.pdf), that prefix is replaced with the corresponding share.
3. Default share — if neither mapping matches and the first path segment cannot be resolved as an existing SMB node, defaultShare is used.

Usage

Registering the plugin

SmbStoragePlugin implements IPluginServiceConfiguration and is discovered automatically by the Dosaic source generator. It registers ISmbStorage as a singleton in the DI container. Ensure the configuration section is present in your appsettings.yml.

Injecting ISmbStorage

public class DocumentService(ISmbStorage smbStorage)
{
 private readonly ISmbStorage _smbStorage = smbStorage;
}

Writing files

// Write raw bytes
byte[] pdfBytes = File.ReadAllBytes("local.pdf");
await _smbStorage.WriteAsync("Reports/Q1/report.pdf", pdfBytes, cancellationToken);

// Write a UTF-8 string (extension method)
await _smbStorage.WriteStringAsync("Logs/app.log", "Application started", cancellationToken);

// Write a stream (extension method)
await using var fileStream = File.OpenRead("photo.jpg");
await _smbStorage.WriteStreamAsync("Photos/photo.jpg", fileStream, cancellationToken);

Reading files

// Read as a Stream
await using var stream = await _smbStorage.ReadStreamAsync("Reports/Q1/report.pdf", cancellationToken);

// Read as a string (extension method)
string logContent = await _smbStorage.ReadStringAsync("Logs/app.log", cancellationToken);

// Read as a byte array (extension method)
byte[] data = await _smbStorage.ReadBytesAsync("Reports/Q1/report.pdf", cancellationToken);

Ensuring a directory path exists

EnsurePathAsync traverses each segment of the path and creates any missing folders recursively.

await _smbStorage.EnsurePathAsync("Reports/2025/Q1/", cancellationToken);

Deleting files

DeleteIfExists silently ignores the case where the file does not exist. It throws a DosaicException if the file is found but cannot be deleted.

await _smbStorage.DeleteIfExists("Reports/Q1/old-report.pdf", cancellationToken);

Using drive and share mappings

// With a drive mapping: J: -> docs-share
await _smbStorage.WriteAsync(@"J:\Invoices\2025\inv001.pdf", data, cancellationToken);
// Resolves to: \\example.com\docs-share\Invoices\2025\inv001.pdf

// With a share mapping: Uploads -> uploads-share
await _smbStorage.WriteAsync("Uploads/avatars/user42.png", data, cancellationToken);
// Resolves to: \\example.com\uploads-share\avatars\user42.png

Features

• ISmbStorage abstraction — decouples application code from the concrete SMB implementation; easy to mock in tests
• Flexible path resolution — drive mappings, share mappings, and a configurable default share with automatic fallback
• Slash normalisation — forward slashes (/) and backslashes (\) are interchangeable in all path arguments
• EnsurePathAsync — recursively creates missing folders on the SMB share
• DeleteIfExists — idempotent deletion; no error when the target is already absent
• Extension methods — WriteStringAsync, WriteStreamAsync, ReadStringAsync, ReadBytesAsync available on any ISmbStorage instance
• OpenTelemetry metrics — built-in counters for observability:
  • dosaic_persistence_smb_writes_total
  • dosaic_persistence_smb_reads_total
  • dosaic_persistence_smb_deletes_total
• Powered by EzSmb — pure-managed SMB client requiring no OS-level mounts