Ctrlk
RoadmapFrends
For the complete documentation index, see llms.txt. This page is also available as Markdown.

UploadBlob

Frends Task to upload blobs to Azure Blob Storage.

Task version: 4.3.0

Required Frends version: 5.7+

Required .NET version: 8.0

Compatible Agents: Crossplatform

Source code: https://github.com/FrendsPlatform/Frends.AzureBlobStorage/tree/main/Frends.AzureBlobStorage.UploadBlob

Task Parameters

Name
Description

ContainerName : String

Name of the Azure Blob Storage container.

Task will convert all letters to lowercase.

Default: - Example: examplecontainer

SourceType : UploadSourceType

Source type.

Possible values:

  • File: Source type.

  • Directory: Source type.

Default: File Example: UploadSourceType.File

SourceDirectory : String

Upload all files from the given directory.

Default: - Example: c:\temp

SearchPattern : String

The search string is used to match against the names of files in the path.

This parameter can contain a combination of valid literal path and wildcard (* and ?) characters, but it doesn't support regular expressions

Default: - Example: ., Search*.*, *.xml

SourceFile : String

This file will be uploaded as a new blob or appended into the target blob in the Append process.

Default: - Example: c:\temp\testfile.txt

BlobName : String

Name of the blob. If left empty, the blob's name will be the same as the source file.

Default: - Example: Renamed.txt

BlobFolderName : String

Name of the blob folder. If left empty, blob folder's name will be the same as source directory (e.g., 'Example' in C:\temp\Example).

Default: - Example: ExampleDir

ContentsOnly : Boolean

Use a stream to read the file's content

Default: False Example: false

Compress : Boolean

Gzip compression only works when transferring stream content (see Input.ContentsOnly).

Note that it could be a good idea to rename the blob using Destination.BlobName (e.g., renaming 'examplefile.txt' to 'examplefile.gz') so that the blob won't be named as 'examplefile.txt.gz

Default: False Example: false

ActionOnExistingFile : OnExistingFile

How the existing blob will be handled.

Append: Append the blob with Input.SourceFile. Block and Page blobs will be downloaded as a temp file which will be deleted after local append and upload processes are complete. No downloading needed for Append Blob.

Overwrite: The original blob will be deleted before uploading the new one.

Throw: Depending on Options.ThrowErrorOnFailure, throw an exception or Result will contain an error message instead of the blob's URL.

Possible values:

  • Throw: Throw an error.

  • Overwrite: Overwrite with source file.

  • Append: Append blob with 'Source File'. Block and Page blob will be downloaded as temp file which will be deleted after local append and reupload processes are complete. No downloading needed for Append Blob.

Default: Throw Example: OnExistingFile.Throw

Tags : Tag[]

Tags for the block or append blob.

NOTE: Minimum access right to work with OAuth2 is 'Storage Blob Data Owner'

Default: - Example: {name, value}

Name
Description

AuthenticationMethod : ConnectionMethod

Defines which connection method should be used for connecting to Azure Blob Storage.

Possible values:

  • ConnectionString: Defines which connection method should be used for connecting to Azure Blob Storage.

  • OAuth2: Defines which connection method should be used for connecting to Azure Blob Storage.

  • SasToken: Defines which connection method should be used for connecting to Azure Blob Storage.

  • ArcManagedIdentity: Defines which connection method should be used for connecting to Azure Blob Storage.

  • ArcManagedIdentityCrossTenant: Defines which connection method should be used for connecting to Azure Blob Storage.

Default: ConnectionString Example: ConnectionMethod.ConnectionString

🗝ConnectionString : String

Connection string to Azure storage.

Default: - Example: DefaultEndpointsProtocol=https;AccountName=account-name;AccountKey=abc==;EndpointSuffix=core.windows.net

ApplicationId : String

Application (Client) ID of Azure AD Application.

Default: - Example: Y6b1hf2a-80e2-xyz2-abc33h-3a7c3a8as4b7f

TenantId : String

Tenant ID of Azure Tenant.

Default: - Example: Y6b1hf2a-80e2-xyz2-abc33h-3a7c3a8as4b7f

🗝ClientSecret : String

Client Secret of Azure AD Application.

Default: - Example: Password!

🗝SasToken : String

A shared access signature to use when connecting to an Azure storage container.

Grants restricted access rights to Azure Storage resources when combined with URI.

Default: - Example: sv=2021-04-10&se=2022-04-10T10%3A431Z&sr=c&sp=l&sig=ZJg983RovE%23ZXI

StorageAccountName : String

Name of the Azure storage account.

Default: - Example: TestStorage

Scopes : String[]

Scopes used when authenticating with Arc Managed Identity Cross Tenant.

Default: - Example: [api://AzureADTokenExchange/.default]

TargetTenantId : String

Target Tenant ID of Azure Tenant.

Default: - Example: Y6b1hf2a-80e2-xyz2-abc33h-3a7c3a8as4b7f

TargetClientId : String

Target Client ID of Azure Tenant.

Default: - Example: Y6b1hf2a-80e2-xyz2-abc33h-3a7c3a8as4b7f

Name
Description

ThrowErrorOnFailure : Boolean

True: Throw an exception.

False: If the error is ignorable, such as when a Blob already exists, the error will be added to the Result.ErrorMessages list instead of stopping the Task.

Default: True Example: true

ErrorMessageOnFailure : String

Overrides the error message on failure.

Default: - Example: Upload failed: check container name and connection string

BlobType : AzureBlobType

Azure blob type to upload.

Append: Made up of blocks like block blobs, but are optimized for append operations. Append blobs are ideal for scenarios such as logging data from virtual machines.

Block: Store text and binary data. Block blobs are made up of blocks of data that can be managed individually. Block blobs can store up to about 190.7 TiB.

Page: Store random access files up to 8 TiB in size. Page blobs store virtual hard drive (VHD) files and serve as disks for Azure virtual machines.

Possible values:

  • Append: Made up of blocks like block blobs, but are optimized for append operations. Append blobs are ideal for scenarios such as logging data from virtual machines.

  • Block: Store text and binary data. Block blobs are made up of blocks of data that can be managed individually. Block blobs can store up to about 190.7 TiB.

  • Page: Store random access files up to 8 TiB in size. Page blobs store virtual hard drive (VHD) files and serve as disks for Azure virtual machines.

Default: Block Example: Block

CreateContainerIfItDoesNotExist : Boolean

Determines if the container should be created if it does not exist.

See https://docs.microsoft.com/en-us/rest/api/storageservices/naming-and-referencing-containers--blobs--and-metadata for naming rules.

Default: False Example: false

ResizeFile : Boolean

Page blob size must be a multiple of 512.

If set to true, this Task will attempt to fill the file with empty bytes until it meets the requirements. When appending to an existing blob, the Task will download the original blob, append the new file to it, and then fill the required bytes.

Default: False Example: false

PageMaxSize : Int64

Specifies the maximum size for a new Page blob, up to 8 TB.

The size must be a multiple of 512 (512, 1024, 1536...).

If the given value is less than what is required for the upload, the Task will calculate the minimum value.

Default: - Example: 1024

PageOffset : Int64

Specifies the starting offset for the content to be written as a Page.

If set to -1 and Input.ActionOnExistingFile = Append, offset will be calculated from original blob's size (before append process).

Default: - Example: 0

ContentType : String

Set desired content-type.

If empty, the Task tries to guess from mime-type.

Default: - Example: text/xml

Encoding : FileEncoding

Set desired content-encoding.

Defaults to UTF8 BOM.

Possible values:

  • UTF8: Set desired content-encoding.

Defaults to UTF8 BOM.

  • Default: Set desired content-encoding.

Defaults to UTF8 BOM.

  • ASCII: Set desired content-encoding.

Defaults to UTF8 BOM.

  • Windows1252: Set desired content-encoding.

Defaults to UTF8 BOM.

  • Other: Other enables users to add other encoding options as string.

Default: UTF8 Example: utf8

EnableBom : Boolean

Enables BOM for UTF-8.

Default: True Example: true

FileEncodingString : String

Content encoding as string. A partial list of possible encodings: https://en.wikipedia.org/wiki/Windows_code_page#List.

Default: - Example: windows-1252

ParallelOperations : Int32

How many work items to process concurrently.

Default: 64 Example: 64

PreserveDirectoryStructure : Boolean

When uploading a directory, preserve the source directory structure in the destination.

True: Creates subdirectories in blob storage to match the source structure.

False: Uploads all files with only their parent directory name (legacy behavior).

Default: False Example: false

Task Result

Name
Description

Success : Boolean

Operation complete. Operation is seens as completed if an ignorable error has occured and Options.ThrowErrorOnFailure is set to false. Example: true

Data : Dictionary<String, String>

This object contains the source file path and the URL of the blob. If an ignorable error occurs, such as when a blob already exists and Options.ThrowErrorOnFailure is set to false, the URL will be replaced with the corresponding error message.age. Example: { { c:\temp\examplefile.txt, https://storage.blob.core.windows.net/container/examplefile.txt }, { c:\temp\examplefile2.txt, Blob examplefile2 already exists. } }

Error : Error

Error details. Null when Success is true. Example: null

Error.Message : String

Error message. Example: The specified container does not exist.

Error.AdditionalInfo : Exception

The exception that caused the failure. Example: ValidationException.

Task Changelog

Changelog for Task Frends.AzureBlobStorage.UploadBlob.

[4.3.0] - 2026-08-17

Added

  • Added ErrorMessageOnFailure option to customize the error message when the Task fails and ThrowErrorOnFailure is false.

  • The result now includes an Error property with details when the Task fails and ThrowErrorOnFailure is false.

[4.2.0] - 2026-05-26

Added

  • New option to preserve directory structure when uploading a directory to Azure Blob Storage.

[4.1.0] - 2026-05-07

Fix

  • Clean up temp files.

[4.0.0] - 2026-04-26

Changed

  • Standardized parameter names and validation across all Azure Blob Storage tasks for consistency.

[3.6.0] - 2026-01-23

Added

  • Add options to support Arc Managed Identity authentication.

[3.5.0] - 2026-01-15

Changed

  • Updated Azure packages to the latest versions:

  • Azure.Storage.Blobs 12.27.0

  • Azure.Identity 1.17.1

[3.4.0] - 2025-11-12

  • Added note about OAuth2 requiring Storage Blob Data Owner role for Tags property

[3.3.0] - 2025-11-12

Changed

  • Updated stream handling in to improve performance and reduce memory usage during large file uploads.

[3.2.0] - 2025-11-01

Changed

  • Performance improvements

[3.1.0] - 2025-08-26

Changed

  • Updated the UploadBlob task to use a streaming approach (GetStream) instead of reading the entire file into memory ( GetBytes), added unit tests to verify integrity for small and 200MB files.

[3.0.0] - 2025-04-16

Changed

  • [Breaking] Reorganized and renamed parameters for clarity and consistency

    • To upgrade to the new version you can select the new parameters matching the old ones. You can find a list of the changes to parameter locations and names below:

      • Renamed Source parameter tab to Input

      • Renamed Destination parameter tab to Connection

      • Destination.HandleExistingFile renamed and moved to Input.ActionOnExistingFile

      • HandleExistingFile.Error renamed to OnExistingFile.Throw

      • ConnectionMethod.SASToken renamed to ConnectionMethod.SasToken

      • Destination.ApplicationID renamed and moved to Connection.ApplicationId

      • Destination.TenantID renamed and moved to Connection.TenantId

      • Destination.SASToken renamed and moved to Connection.SasToken

      • Destination.BlobType moved to Options.BlobType

      • Destination.ResizeFile moved to Options.ResizeFile

      • Destination.PageMaxSize moved to Options.PageMaxSize

      • Destination.PageOffset moved to Options.PageOffset

      • Destination.ContentType moved to Options.ContentType

      • Destination.Encoding moved to Options.Encoding

      • FileEncoding.WINDOWS1252 renamed to Windows1252

      • Destination.EnableBOM renamed and moved to Options.EnableBom

      • Destination.FileEncodingString moved to Options.FileEncodingString

      • Destination.ParallelOperations moved to Options.ParallelOperations

[2.4.0] - 2025-01-27

Added

  • Added SAS Token authentication method.

[2.3.0] - 2024-12-11

Updated

  • Removed progress handler

[2.2.0] - 2024-12-05

Updated

  • Fixed GZip compression

[2.1.0] - 2024-08-21

Updated

  • Updated Azure.Identity to version 1.12.0.

[2.0.1] - 2024-01-29

Updated

  • Azure.Identity to version 1.10.4

  • Azure.Storage.Blobs to version 12.19.1

[2.0.0] - 2023-04-06

Added

Option to choose whether to upload a directory or just a single blob. New parameters: Destination.ResizeFile, Source.SourceType, Source.SourceDirectory, Source.SearchPattern, Source.BlobName, Source.BlobFolderName.

Changed

Destination.BlobName and Destination.RenameTo parameters have been replaced by Source.BlobName or Source.BlobFolderName depending on Source.SourceType. Result.SourceFile and Result.Uri have been replaced by Result.Data.

[1.2.0] - 2023-01-27

Added

  • New feature to add index tags to uploaded blobs (Block and Append).

[1.1.0] - 2023-01-03

Added

  • OAuth2 as a new additional authentication method.

[1.0.2] - 2022-07-29

Added

  • Append any type of blob. Fixes for Page and Append blob upload.

[1.0.1] - 2022-02-28

Changed

  • Support for .NET Standard 2.0 removed.

[1.0.0] - 2022-02-09

Added

  • Initial implementation of Frends.AzureBlobStorage.UploadBlob.

PreviousReadBlob
NextWriteBlob

Last updated

Was this helpful?