CloudQueue.UpdateMessage Method

Storage Client Library NET API

[This topic is part of the Microsoft Azure Storage Client Library 1.7, which has been deprecated. See Storage Client Library for the latest version.]

Updates the visibility timeout of a message, and optionally the contents of a message.

Namespace: Microsoft.WindowsAzure.StorageClient
Assembly: Microsoft.WindowsAzure.StorageClient (in Microsoft.WindowsAzure.StorageClient.dll)

Usage

Visual Basic
Dim instance As CloudQueue
Dim message As CloudQueueMessage
Dim visibilityTimeout As TimeSpan
Dim updateFields As MessageUpdateFields

instance.UpdateMessage(message, visibilityTimeout, updateFields)

Syntax

Visual Basic
Public Sub UpdateMessage ( _
	message As CloudQueueMessage, _
	visibilityTimeout As TimeSpan, _
	updateFields As MessageUpdateFields _
)
C#
public void UpdateMessage (
	CloudQueueMessage message,
	TimeSpan visibilityTimeout,
	MessageUpdateFields updateFields
)
C++
public:
void UpdateMessage (
	CloudQueueMessage^ message, 
	TimeSpan visibilityTimeout, 
	MessageUpdateFields updateFields
)
J#
JScript

Parameters

message

A queue message.

visibilityTimeout

The visibility timeout for the message.

updateFields

Indicates whether to update the visibility delay, message contents, or both.

Remarks

The UpdateMessage method must specify the visibility delay of a message.

A message can be up to 64 KB in size for SDK version 1.6 or newer, or 8 KB in size for older SDK versions. The storage client library encodes the message content using Base64 when EncodeMessage is set to true, its default. Encode messages if message content can contain characters that are invalid in XML.

Note
Encoding with Base64 adds overhead to the message size. You can use Convert.ToBase64String() to verify content encoded with Base64 fits within the 64 KB message size limit.

After a client retrieves a message by calling the GetMessage or GetMessages(Int32) method, the client is expected to process and update the message. When a message is retrieved, its PopReceipt property is set to an opaque value that indicates the message has been read. The value of the message’s pop receipt is used to verify that the message being updated is the same message that was read.

A pop receipt remains valid until one of the following events occurs:

  • The message has expired.

  • The message has been deleted using the last pop receipt received either from GetMessages(Int32) or UpdateMessage.

  • The invisibility time has elapsed and the message has been dequeued by a GetMessages(Int32) request. When the invisibility time elapses, the message becomes visible again. If it is retrieved by another GetMessages(Int32) request, the returned pop receipt can be used to delete or update the message.

  • The message has been updated with a new visibility timeout. When the message is updated, a new pop receipt will be returned.

The UpdateMessage operation can be used to continually extend the invisibility of a queue message. This functionality can be useful if you want a worker role to “lease” a queue message. For example, if a worker role calls GetMessages(Int32) and recognizes that it needs more time to process a message, it can continually extend the message’s invisibility until it is processed. If the worker role were to fail during processing, eventually the message would become visible again and another worker role could process it.


Thread Safety

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

Platforms

Development Platforms

Windows Vista, Windows 7, Windows Server 2008, Windows 8.1, Windows Server 2012 R2, Windows 8 and Windows Server 2012

Change History

See Also