Skip to content

Commit

Permalink
[Messaging] Doc Updates (Azure#29597)
Browse files Browse the repository at this point in the history 
The focus of these changes is to document the set of types supported in
the application properties collection of the event/message when serializing
to AMQP format.
  • Loading branch information
@jsquire @sofiar-msft
jsquire authored and sofiar-msft committed Dec 7, 2022
1 parent a70ce8e commit ca778d3
Show file tree
Hide file tree
Showing 6 changed files with 93 additions and 4 deletions.
28 changes: 28 additions & 0 deletions sdk/eventhub/Azure.Messaging.EventHubs/src/EventData.cs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -220,8 +220,36 @@ public string CorrelationId
/// A common use case for <see cref="EventData.Properties" /> is to associate serialization hints
/// for the <see cref="EventData.EventBody" /> as an aid to consumers who wish to deserialize the binary data
/// when the <see cref="ContentType" /> alone does not offer sufficient context.
///
/// <list type="bullet">
/// <listheader><description>The following types are supported:</description></listheader>
/// <item><description>string</description></item>
/// <item><description>bool</description></item>
/// <item><description>byte</description></item>
/// <item><description>sbyte</description></item>
/// <item><description>short</description></item>
/// <item><description>ushort</description></item>
/// <item><description>int</description></item>
/// <item><description>uint</description></item>
/// <item><description>long</description></item>
/// <item><description>ulong</description></item>
/// <item><description>float</description></item>
/// <item><description>decimal</description></item>
/// <item><description>double</description></item>
/// <item><description>char</description></item>
/// <item><description>Guid</description></item>
/// <item><description>DateTime</description></item>
/// <item><description>DateTimeOffset</description></item>
/// <item><description>Stream</description></item>
/// <item><description>Uri</description></item>
/// <item><description>TimeSpan</description></item>
/// </list>
/// </remarks>
///
/// <exception cref="System.Runtime.Serialization.SerializationException">
/// Occurs when the <see cref="EventData" /> is serialized for transport when an unsupported type is used as a property.
/// </exception>
///
/// <example>
/// <code>
/// var eventData = new EventData(serializedTelemetryData);
Expand Down
5 changes: 5 additions & 0 deletions sdk/eventhub/Azure.Messaging.EventHubs/src/Producer/EventDataBatch.cs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -157,6 +157,11 @@ internal EventDataBatch(TransportEventBatch transportBatch,
/// result in an <see cref="InvalidOperationException" /> until publishing has completed.
/// </exception>
///
/// <exception cref="System.Runtime.Serialization.SerializationException">
/// Occurs when the <paramref name="eventData"/> has a member in its <see cref="EventData.Properties"/> collection that is an
/// unsupported type for serialization. See the <see cref="EventData.Properties"/> remarks for details.
/// </exception>
///
public bool TryAdd(EventData eventData)
{
lock (SyncGuard)
Expand Down
10 changes: 10 additions & 0 deletions sdk/eventhub/Azure.Messaging.EventHubs/src/Producer/EventHubProducerClient.cs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -511,6 +511,11 @@ public virtual async Task<PartitionProperties> GetPartitionPropertiesAsync(strin
/// <see cref="EventHubsException.FailureReason.MessageSizeExceeded"/> in this case.
/// </exception>
///
/// <exception cref="System.Runtime.Serialization.SerializationException">
/// Occurs when one of the events in the <paramref name="eventBatch"/> has a member in the <see cref="EventData.Properties" /> collection that is an
/// unsupported type for serialization. See the <see cref="EventData.Properties"/> remarks for details.
/// </exception>
///
/// <seealso cref="SendAsync(IEnumerable{EventData}, SendEventOptions, CancellationToken)" />
/// <seealso cref="SendAsync(EventDataBatch, CancellationToken)" />
/// <seealso cref="CreateBatchAsync(CancellationToken)" />
Expand Down Expand Up @@ -548,6 +553,11 @@ public virtual async Task SendAsync(IEnumerable<EventData> eventBatch,
/// <see cref="EventHubsException.FailureReason.MessageSizeExceeded"/> in this case.
/// </exception>
///
/// <exception cref="System.Runtime.Serialization.SerializationException">
/// Occurs when one of the events in the <paramref name="eventBatch"/> has a member in the <see cref="EventData.Properties" /> collection that is an
/// unsupported type for serialization. See the <see cref="EventData.Properties"/> remarks for details.
/// </exception>
///
/// <seealso cref="SendAsync(IEnumerable{EventData}, CancellationToken)" />
/// <seealso cref="SendAsync(EventDataBatch, CancellationToken)" />
/// <seealso cref="CreateBatchAsync(CreateBatchOptions, CancellationToken)" />
Expand Down
31 changes: 27 additions & 4 deletions sdk/servicebus/Azure.Messaging.ServiceBus/src/Primitives/ServiceBusMessage.cs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -426,10 +426,33 @@ public DateTimeOffset ScheduledEnqueueTime
/// Gets the application properties bag, which can be used for custom message metadata.
/// </summary>
/// <remarks>
/// Only following value types are supported:
/// byte, sbyte, char, short, ushort, int, uint, long, ulong, float, double, decimal,
/// bool, Guid, string, Uri, DateTime, DateTimeOffset, TimeSpan
/// <list type="bullet">
/// <listheader><description>The following types are supported:</description></listheader>
/// <item><description>string</description></item>
/// <item><description>bool</description></item>
/// <item><description>byte</description></item>
/// <item><description>sbyte</description></item>
/// <item><description>short</description></item>
/// <item><description>ushort</description></item>
/// <item><description>int</description></item>
/// <item><description>uint</description></item>
/// <item><description>long</description></item>
/// <item><description>ulong</description></item>
/// <item><description>float</description></item>
/// <item><description>decimal</description></item>
/// <item><description>double</description></item>
/// <item><description>char</description></item>
/// <item><description>Guid</description></item>
/// <item><description>DateTime</description></item>
/// <item><description>DateTimeOffset</description></item>
/// <item><description>Stream</description></item>
/// <item><description>Uri</description></item>
/// <item><description>TimeSpan</description></item>
/// </list>
/// </remarks>
/// <exception cref="System.Runtime.Serialization.SerializationException">
/// Occurs when the <see cref="ServiceBusMessage" /> is serialized for transport when an unsupported type is used as a property.
/// </exception>
public IDictionary<string, object> ApplicationProperties
{
get
Expand All @@ -445,4 +468,4 @@ public override string ToString()
return string.Format(CultureInfo.CurrentCulture, "{{MessageId:{0}}}", MessageId);
}
}
}
}
5 changes: 5 additions & 0 deletions sdk/servicebus/Azure.Messaging.ServiceBus/src/Sender/ServiceBusMessageBatch.cs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -94,6 +94,11 @@ internal ServiceBusMessageBatch(TransportMessageBatch transportBatch, EntityScop
/// result in an <see cref="InvalidOperationException" /> until the send has completed.
/// </exception>
///
/// <exception cref="System.Runtime.Serialization.SerializationException">
/// Occurs when the <paramref name="message"/> has a member in its <see cref="ServiceBusMessage.ApplicationProperties"/> collection that is an
/// unsupported type for serialization. See the <see cref="ServiceBusMessage.ApplicationProperties"/> remarks for details.
/// </exception>
///
public bool TryAddMessage(ServiceBusMessage message)
{
lock (_syncGuard)
Expand Down
18 changes: 18 additions & 0 deletions sdk/servicebus/Azure.Messaging.ServiceBus/src/Sender/ServiceBusSender.cs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -155,6 +155,10 @@ protected ServiceBusSender(ServiceBusClient client, string queueOrTopicName) :
/// For more information on service limits, see
/// <see href="https://docs.microsoft.com/en-us/azure/service-bus-messaging/service-bus-quotas#messaging-quotas"/>.
/// </exception>
/// <exception cref="System.Runtime.Serialization.SerializationException">
/// Occurs when the <paramref name="message"/> has a member in its <see cref="ServiceBusMessage.ApplicationProperties"/> collection that is an
/// unsupported type for serialization. See the <see cref="ServiceBusMessage.ApplicationProperties"/> remarks for details.
/// </exception>
public virtual async Task SendMessageAsync(
ServiceBusMessage message,
CancellationToken cancellationToken = default)
Expand Down Expand Up @@ -182,6 +186,10 @@ await SendMessagesAsync(
/// For more information on service limits, see
/// <see href="https://docs.microsoft.com/en-us/azure/service-bus-messaging/service-bus-quotas#messaging-quotas"/>.
/// </exception>
/// <exception cref="System.Runtime.Serialization.SerializationException">
/// Occurs when one of the <paramref name="messages"/> has a member in its <see cref="ServiceBusMessage.ApplicationProperties"/> collection that is an
/// unsupported type for serialization. See the <see cref="ServiceBusMessage.ApplicationProperties"/> remarks for details.
/// </exception>
public virtual async Task SendMessagesAsync(
IEnumerable<ServiceBusMessage> messages,
CancellationToken cancellationToken = default)
Expand Down Expand Up @@ -364,6 +372,11 @@ public virtual async Task SendMessagesAsync(
/// <see cref="SendMessagesAsync(ServiceBusMessageBatch, CancellationToken)"/>.</remarks>
///
/// <returns>The sequence number of the message that was scheduled.</returns>
///
/// <exception cref="System.Runtime.Serialization.SerializationException">
/// Occurs when the <paramref name="message"/> has a member in its <see cref="ServiceBusMessage.ApplicationProperties"/> collection that is an
/// unsupported type for serialization. See the <see cref="ServiceBusMessage.ApplicationProperties"/> remarks for details.
/// </exception>
public virtual async Task<long> ScheduleMessageAsync(
ServiceBusMessage message,
DateTimeOffset scheduledEnqueueTime,
Expand Down Expand Up @@ -395,6 +408,11 @@ public virtual async Task<long> ScheduleMessageAsync(
/// <see cref="SendMessagesAsync(ServiceBusMessageBatch, CancellationToken)"/>.</remarks>
///
/// <returns>The sequence number of the message that was scheduled.</returns>
///
/// <exception cref="System.Runtime.Serialization.SerializationException">
/// Occurs when one of the <paramref name="messages"/> has a member in its <see cref="ServiceBusMessage.ApplicationProperties"/> collection that is an
/// unsupported type for serialization. See the <see cref="ServiceBusMessage.ApplicationProperties"/> remarks for details.
/// </exception>
public virtual async Task<IReadOnlyList<long>> ScheduleMessagesAsync(
IEnumerable<ServiceBusMessage> messages,
DateTimeOffset scheduledEnqueueTime,
Expand Down

0 comments on commit ca778d3

Please sign in to comment.