Connect to an SFTP server with Aspire

Questi contenuti non sono ancora disponibili nella tua lingua.

⭐ Community Toolkit

The Community Toolkit SFTP client registers SSH.NET’s SftpClient in dependency injection. Reference an SFTP resource from your consuming app to provide its connection string. For server configuration, see Set up SFTP with the Aspire integration.

Install the client integration

Install the 📦 CommunityToolkit.Aspire.Sftp package in the consuming project:

dotnet add package CommunityToolkit.Aspire.Sftp

#:package CommunityToolkit.Aspire.Sftp@*

<PackageReference Include="CommunityToolkit.Aspire.Sftp" Version="*" />

Add the SFTP client

Call AddSftpClient with the name of the connection from the AppHost. Provide a username and one authentication method:

builder.AddSftpClient(
    "sftp",
    settings =>
    {
        settings.Username = "fileuser";
        settings.Password = builder.Configuration["Sftp:Password"];
    });

The connection name must match the SFTP resource name in the AppHost. Inject SftpClient into a service to transfer files:

using Renci.SshNet;

public sealed class FileTransferService(SftpClient client)
{
    public void Upload(string localPath, string remotePath)
    {
        if (!client.IsConnected)
        {
            client.Connect();
        }

        using var stream = File.OpenRead(localPath);
        client.UploadFile(stream, remotePath);
    }
}

The integration registers SftpClient as a singleton. Dependency injection disposes it when the application shuts down.

Add keyed SFTP clients

builder.AddKeyedSftpClient(
    "archive",
    settings =>
    {
        settings.Username = "archive-user";
        settings.PrivateKeyFile = builder.Configuration["Sftp:ArchivePrivateKeyFile"];
    });

Although SftpSettings includes PrivateKeyPassphrase, the client factory creates PrivateKeyFile with only the path. Use an unencrypted private key for SftpClient. The health check uses the passphrase, so it can succeed with an encrypted key even though client creation fails.

Resolve a keyed client using dependency injection:

using Renci.SshNet;

public sealed class ArchiveService([FromKeyedServices("archive")] SftpClient client)
{
}

For more information, see .NET dependency injection: Keyed services.

Configure the client

Connection strings

The AppHost resource exposes the connection URI sftp://host:port. For a standalone app, set the connection string named sftp:

{
  "ConnectionStrings": {
    "sftp": "sftp://localhost:22"
  }
}

Configuration providers

The client loads SftpSettings from the Aspire:Sftp:Client section. Provide a password or private key path through a secret or deployment configuration provider:

{
  "Aspire": {
    "Sftp": {
      "Client": {
        "ConnectionString": "sftp://localhost:22",
        "Username": "fileuser",
        "PrivateKeyFile": "/path/to/private/key",
        "DisableHealthChecks": false,
        "DisableTracing": false
      }
    }
  }
}

The client requires a connection string and username, and it requires either a password or a private key. The health check is enabled by default and verifies that the SFTP server accepts a connection. Set DisableHealthChecks to true to opt out.

Inline delegates

Pass an Action<SftpSettings> to configure settings in code:

builder.AddSftpClient(
    "sftp",
    settings =>
    {
        settings.Username = "fileuser";
        settings.PrivateKeyFile = builder.Configuration["Sftp:PrivateKeyFile"];
        settings.DisableTracing = true;
    });