Migration Guide

Migrating from FluentStorage v7 to v8+

Major API behavioral changes

1. All extension-method factory API has been removed: For example StorageFactory.Blobs and StorageFactory.Messages no longer exist.
2. Factory classes have been introduced on a per-provided basis.
3. Factory classes can be accessed directly to construct new IStore objects: For example StorageFactory.Blobs.AwsS3 is now AwsS3Storage.FromCredentials.
4. All methods are async and the "Async" suffix has been dropped. The old goal of supporting sync and async makes no sense since all cloud transfer APIs are async and the handful of edge cases like local memory storage and local disk storage do not matter.
5. At initialization, S3-compatible stores will no longer create the bucket if the specified bucket does not exist. FluentStorage is not an IaC framework and this "feature" has been troublesome for many cloud storage providers and is best removed.
6. WriteAsync() is renamed to SetObject() and will compute the object's MIME type (Content-Type) if it is not supplied.
7. CreateDirectory() will no longer create a "dummy file" in a cloud storage bucket.
8. RenameAsync() is renamed to MoveObject() and will no longer perform a recursive copy and delete, instead it will efficiently move the object/file from the old path to the new path only if it exists.
9. ExistsAsync() is renamed to ObjectExists() and will consistently return true/false if the file or folder exists on the bucket/server.
10. DeleteAsync() is renamed to DeleteObject() and will consistently delete a single file or folder from the bucket/server.
11. DeleteObjects() will consistently delete multiple files or folders from the bucket/server.
12. GetClient() will consistently return the internal cloud SDK client for all types of cloud storage. (Replaces NativeBlobClient)
13. Collections returned by APIs will always be List instead of IReadOnlyCollection.
14. Exceptions are moved into the FluentStorage.Exceptions namespace
15. Enums are moved into the FluentStorage.Enums namespace
16. FTP and SFTP server stores now support directory and server API in addition to the object manipulation API
17. We no longer support Databricks, ServiceFabric, EventHub, Virtual storage and ZIP archives

Major new API

New factory classes per provider

• AwsS3Storage
• AwsSqsStorage
• BackblazeB2Storage
• CloudflareR2Storage
• DigitalOceanSpacesStorage
• HetznerStorage
• MinlOStorage
• VultrStorage
• WasabiStorage
• AzureBlobStore
• AzureDataLakeStore
• AzureFilesStore
• AzureKeyVaultStorage
• AzureQueueStorage
• AzureServiceBus
• GoogleCloudStorage
• FtpStorage
• SftpStorage

New FTP/SFTP API

• Server info
  • GetServer
• Directory manipulation
  • CreateDirectory
  • DeleteDirectory
  • DirectoryExists
  • MoveDirectory
  • GetFilePermissions
  • SetFilePermissions
• File manipulation
  • MoveObject
  • DownloadObject
  • UploadObject
  • GetBytes
  • SetBytes

New bucket API

• GetClient
• GetUploadUrl
• GetDownloadUrl
• GetPresignedUrl
• MoveObject
• DownloadObject
• UploadObject

Renamed API

The entire FluentStorage API surface was redesigned from scratch to keep it meaningful, simple and consistent.

Old Class	New Class	Notes
Blob	StoreObject	"Object" is the most common terminology across all providers
IBlobStorage	IStore	"Bucket" is the most common terminology across all providers
IHierarchicalBlobStorage	IStore
IExtendedBlobStorage	IStore
IMessenger	IQueue	"Queue" is the most common terminology across all providers
IMessageReceiver	IQueueReceiver
IMessageProcessor	IQueueProcessor
IAzureServiceBusMessenger	IAzureServiceBus
StorageConnectionString	ConnectionString	For consistency
KnownPrefix	ConnectionStringPrefix	For consistency
KnownParameter	ConnectionStringParam	For consistency
RecursionMode	StorageRecursion	For consistency
BlobItemKind	StorageObjectType	For consistency
ErrorCode	StorageErrorCode	For consistency
ListOptions	StorageListOptions	For consistency

Old Static API	New Static API	Notes
StorageFactory.Modules.UseAwsStorage	AwsStorage.Use	For connection strings
StorageFactory.Modules.UseAzureBlobStorage	AzureBlobStorage.Use	For connection strings
StorageFactory.Modules.UseAzureFilesStorage	AzureFilesStorage.Use	For connection strings
StorageFactory.Modules.UseAzureKeyVault	AzureKeyVaultStorage.Use	For connection strings
StorageFactory.Modules.UseAzureQueues	AzureQueueStorage.Use	For connection strings
StorageFactory.Modules.UseFtpStorage	FtpStorage.Use	For connection strings
StorageFactory.Modules.UseSftpStorage	SftpStorage.Use	For connection strings
StorageFactory.Modules.UseGoogleCloudStorage	GoogleCloudStorage.Use	For connection strings
StorageFactory.Blobs.AzureBlob*	AzureBlobStorage.From...
StorageFactory.Blobs.AzureFiles*	AzureFilesStorage.From...
StorageFactory.Blobs.AzureDataLake*	AzureDataLakeStorage.From...
StorageFactory.Blobs.AzureKeyVault*	AzureKeyVaultStorage.From...
StorageFactory.Messages.AzureStorageQueue*	AzureQueueStorage.From...
StorageFactory.Messages.AzureServiceBus*	AzureServiceBus.From...
StorageFactory.Blobs.GoogleCloud*	GoogleCloudStorage.From...
StorageFactory.Blobs.AwsS3*	AwsS3Storage.From...
StorageFactory.Messages.AwsSQS*	AwsSqsStorage.From...
StorageFactory.Blobs.MinIO	MinIOStorage.From...
StorageFactory.Blobs.Wasabi	WasabiStorage.From...
StorageFactory.Blobs.DigitalOceanSpaces	DigitalOceanSpacesStorage.From...
StorageFactory.Blobs.BackblazeB2	BackblazeB2Storage.From...
StorageFactory.Blobs.CloudflareR2	CloudflareR2Storage.From...
StorageFactory.Blobs.Vultr	VultrStorage.From...
StorageFactory.Blobs.Hetzner	HetznerStorage.From...
StorageFactory.Blobs.Ftp	FtpStorage.From...
StorageFactory.Blobs.Sftp	SftpStorage.From...
StorageFactory.Blobs.FromConnectionString	StorageFactory.FromConnectionString
StorageFactory.Blobs.DirectoryFiles	StorageFactory.DirectoryFiles
StorageFactory.Blobs.InMemory	StorageFactory.InMemory
StorageFactory.Messages.MessengerFromConnectionString	QueueFactory.FromConnectionString
StorageFactory.Messages.Disk	QueueFactory.Disk
StorageFactory.Messages.InMemory	QueueFactory.InMemory

Old Dynamic API	New Dynamic API	Notes
Blob.Kind	StorageObject.Type	Improved term
Blob.CreatedTime	StorageObject.DateCreated	"Time" is a misnomer
Blob.LastModificationTime	StorageObject.DateModified	"Time" is a misnomer
IBlobStorage.ListAsync	IStore.ListObjects	"Async" suffix removed
IBlobStorage.ListDirectoryAsync	IStore.ListDirectory
IBlobStorage.ListFilesAsync	IStore.ListFiles
IBlobStorage.ExistsAsync	IStore.ObjectExists
IBlobStorage.GetBlobAsync	IStore.GetObjectInfo
IBlobStorage.GetBlobsAsync	IStore.GetObjectsInfo
IBlobStorage.SetBlobAsync	IStore.SetObjectInfo
IBlobStorage.SetBlobsAsync	IStore.SetObjectsInfo
IBlobStorage.GetMD5HashAsync	IStore.GetObjectMD5
IBlobStorage.OpenReadAsync	IStore.OpenRead
IBlobStorage.ReadToStreamAsync	IStore.GetObject
IBlobStorage.ReadBytesAsync	IStore.GetBytes
IBlobStorage.ReadTextAsync	IStore.GetText
IBlobStorage.ReadJsonAsync	IStore.GetJson
IBlobStorage.ReadToFileAsync	IStore.DownloadObject
IBlobStorage.WriteAsync	IStore.SetObject / IStore.SetBytes
IBlobStorage.WriteTextAsync	IStore.SetText
IBlobStorage.WriteJsonAsync	IStore.SetJson
IBlobStorage.WriteFileAsync	IStore.UploadObject
IBlobStorage.CopyToAsync	IStore.CopyObjectToBucket
IBlobStorage.RenameAsync	IStore.RenameObject
IBlobStorage.DeleteAsync	IStore.DeleteObject / IStore.DeleteObjects
IBlobStorage.CreateFolderAsync	IStore.CreateDirectory
IQueue.CreateChannelsAsync2	IQueue.CreateChannels
IQueue.ListChannelsAsync	IQueue.ListChannels
IQueue.DeleteChannelsAsync	IQueue.DeleteChannels
IQueue.GetMessageCountAsync	IQueue.GetMessageCount
IQueue.SendAsync	IQueue.SendMessages
IQueue.ReceiveAsync	IQueue.ReceiveMessages
IQueue.PeekAsync	IQueue.PeekMessages
IQueue.DeleteAsync	IQueue.DeleteMessages
IQueue.StartMessageProcessorAsync	IQueue.StartMessageProcessor
IAzureBlobStorage.AcquireLeaseAsync	IAzureBlobStorage.AcquireLease
IAzureBlobStorage.BreakLeaseAsync	IAzureBlobStorage.BreakLease
IAzureBlobStorage.GetContainerPublicAccessAsync	IAzureBlobStorage.GetContainerPublicAccess
IAzureBlobStorage.SetContainerPublicAccessAsync	IAzureBlobStorage.SetContainerPublicAccess
IAzureBlobStorage.GetStorageSasAsync	IAzureBlobStorage.GetStorageSas
IAzureBlobStorage.GetContainerSasAsync	IAzureBlobStorage.GetContainerSas
IAzureBlobStorage.GetBlobSasAsync	IAzureBlobStorage.GetBlobSas
IAzureServiceBusMessenger.SendToQueueAsync	IAzureServiceBus.SendToQueue
IAzureServiceBusMessenger.SendToTopicAsync	IAzureServiceBus.SendToTopic
IAzureServiceBusMessenger.SendToSubscriptionAsync	IAzureServiceBus.SendToSubscription
IAzureServiceBusMessenger.CreateQueueAsync	IAzureServiceBus.CreateQueue
IAzureServiceBusMessenger.CreateTopicAsync	IAzureServiceBus.CreateTopic
IAzureServiceBusMessenger.CreateSubScriptionAsync	IAzureServiceBus.CreateSubscription
IAzureServiceBusMessenger.DeleteQueueAsync	IAzureServiceBus.DeleteQueue
IAzureServiceBusMessenger.DeleteSubScriptionAsync	IAzureServiceBus.DeleteSubscription
IAzureServiceBusMessenger.DeleteTopicAsync	IAzureServiceBus.DeleteTopic
IAzureServiceBusMessenger.CountQueueAsync	IAzureServiceBus.CountQueue
IAzureServiceBusMessenger.CountSubScriptionAsync	IAzureServiceBus.CountSubscription
IAzureServiceBusMessenger.CountTopicAsync	IAzureServiceBus.CountTopic

Old Namespace	New Namespace
FluentStorage.AWS.Blobs	FluentStorage.AWS.Storage
FluentStorage.Azure.Blobs.Gen2.Model	FluentStorage.Azure.Blobs.DataLake.Model
FluentStorage.Gcp.CloudStorage	FluentStorage.GCP

Deleted API

We have deleted less used functionality to reduce bloat and help focus on our priority offering.

Deleted classes	Reason
ITransaction	Transactions were never implemented so this was dead API
EmptyTransaction	Transactions were never implemented so this was dead API
VirtualStorage	Virtual storage is out of scope and removed
IVirtualStorage	Virtual storage is out of scope and removed
StorageFactory.Blobs.Virtual()	Virtual storage is out of scope and removed
ZipStore	ZIP Archive support is out of scope and removed
StorageFactory.Blobs.ZipFile()	ZIP Archive support is out of scope and removed

Deleted libraries

The following libraries have been deprecated and deleted from our codebase, reducing the maintenance effort and helping us focus on the important parts of our offering.

	Package	Reason
	FluentStorage.Databricks	We will no longer maintain this package because DBFS is not a mainstream storage backend for a storage abstraction library.
	FluentStorage.Azure.EventHub	Due to low community usage, we will no longer maintain this library.
	FluentStorage.Azure.DataLake	We are no longer maintaining this package as it only caters to DataLake Gen 1, which has been superseded by DataLake Gen2. Gen1 is considered a legacy service and is no longer the direction Microsoft recommends for new development.
	FluentStorage.Azure.ServiceFabric	We will no longer maintain this package because ServiceFabric is not a first-class object storage or messaging service, which is outside our current scope, and it also has extremely low community usage.

Migrating from Storage.NET

Packaging changes

Change your NuGet packages and your imports using this mapping:

Old name	New name
Storage.Net	FluentStorage
Storage.Net.Amazon.Aws	FluentStorage.AWS
Storage.Net.Gcp.CloudStorage	FluentStorage.GCP
Storage.Net.Databricks	No longer supported
Storage.Net.Ftp	FluentStorage.FTP
Storage.Net.Microsoft.Azure.Storage.Blobs	FluentStorage.Azure.Blobs
Storage.Net.Microsoft.Azure.Storage.Files	FluentStorage.Azure.Files
Storage.Net.Microsoft.Azure.EventHub	No longer supported
Storage.Net.Microsoft.Azure.ServiceBus	FluentStorage.Azure.ServiceBus
Storage.Net.Microsoft.Azure.KeyVault	FluentStorage.Azure.KeyVault
Storage.Net.Microsoft.Azure.ServiceFabric	No longer supported
Storage.Net.Microsoft.Azure.Queues	FluentStorage.Azure.Queues
Storage.Net.Microsoft.Azure.DataLake.Storage.Gen1	No longer supported