Send and receive normal messages using the TCP client SDK for .NET - ApsaraMQ for RocketMQ

Normal messages are the basic message type in ApsaraMQ for RocketMQ. Unlike scheduled, delayed, ordered, and transactional messages, normal messages have no special delivery or ordering semantics. Use normal messages for reliable asynchronous communication that does not require timing or sequencing constraints.

The examples on this page use the TCP client SDK for .NET.

Prerequisites

Before you begin, ensure that you have:

The SDK for .NET installed. For more information, see Release notes
A prepared development environment. For more information, see Prepare the environment
ApsaraMQ for RocketMQ resources (instances, topics, and consumer groups) created in the console. For more information, see Create resources
An AccessKey pair for your Alibaba Cloud account. For more information, see Create an AccessKey pair

Send normal messages

Note

For the complete sample project, see the ApsaraMQ for RocketMQ code repository.

The following example sends normal messages by using the TCP client SDK for .NET. Replace the placeholders with your actual values.

using System;
using ons;

public class ProducerExampleForEx
{
    public ProducerExampleForEx()
    {
    }

    static void Main(string[] args) {
        // Configure the producer properties.
        ONSFactoryProperty factoryInfo = new ONSFactoryProperty();

        // Load credentials from environment variables.
        // Set ALIBABA_CLOUD_ACCESS_KEY_ID and ALIBABA_CLOUD_ACCESS_KEY_SECRET
        // before running this example.
        factoryInfo.setFactoryProperty(ONSFactoryProperty::AccessKey, getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"));
        factoryInfo.setFactoryProperty(ONSFactoryProperty::SecretKey, getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));

        // Specify the Group ID created in the ApsaraMQ for RocketMQ console.
        factoryInfo.setFactoryProperty(ONSFactoryProperty.ProducerId, "<GROUP_ID>");

        // Specify the topic created in the ApsaraMQ for RocketMQ console.
        factoryInfo.setFactoryProperty(ONSFactoryProperty.PublishTopics, "<TOPIC>");

        // Specify the TCP endpoint from the Instance Details page
        // in the ApsaraMQ for RocketMQ console.
        factoryInfo.setFactoryProperty(ONSFactoryProperty.NAMESRV_ADDR, "<TCP_ENDPOINT>");

        // Specify the log file path.
        factoryInfo.setFactoryProperty(ONSFactoryProperty.LogPath, "C://log");

        // Create a producer instance.
        // Producer instances are thread-safe. A single instance can send
        // messages to multiple topics. In most cases, one instance per thread is sufficient.
        Producer producer = ONSFactory.getInstance().createProducer(factoryInfo);

        // Start the producer.
        producer.start();

        // Build a message with a topic, tag, and body.
        Message msg = new Message(factoryInfo.getPublishTopics(), "tagA", "Example message body");
        msg.setKey(Guid.NewGuid().ToString());

        // Send 32 messages in a loop.
        for (int i = 0; i < 32; i++) {
            try
            {
                SendResultONS sendResult = producer.send(msg);
                Console.WriteLine("send success {0}", sendResult.getMessageId());
            }
            catch (Exception ex)
            {
                Console.WriteLine("send failure{0}", ex.ToString());
            }
        }

        // Shut down the producer before exiting the thread.
        producer.shutdown();
    }
}

Replace the following placeholders with your actual values:

Placeholder	Description	Example
`<GROUP_ID>`	The Group ID that you created in the ApsaraMQ for RocketMQ console	`GID_example`
`<TOPIC>`	The topic that you created in the ApsaraMQ for RocketMQ console	`T_example_topic_name`
`<TCP_ENDPOINT>`	The TCP endpoint from the TCP Endpoint section of the Instance Details page	--

Code walkthrough

Configure properties -- Set credentials, Group ID, topic, TCP endpoint, and log path through ONSFactoryProperty. Load AccessKey ID and AccessKey Secret from the ALIBABA_CLOUD_ACCESS_KEY_ID and ALIBABA_CLOUD_ACCESS_KEY_SECRET environment variables.
Create and start the producer -- ONSFactory.getInstance().createProducer(factoryInfo) returns a thread-safe producer instance. In most cases, one instance per thread is sufficient, even when sending to multiple topics.
Build and send messages -- Construct a Message with a topic, tag, and body. Assign a unique key with Guid.NewGuid() for message tracking. producer.send(msg) returns a SendResultONS containing the message ID on success.
Shut down -- Call producer.shutdown() before the thread exits to terminate the producer instance.

Subscribe to normal messages

For instructions and sample code on subscribing to normal messages with the TCP client SDK for .NET, see Subscribe to messages.

What's next

Subscribe to messages -- Set up a consumer to receive messages by using the TCP client SDK for .NET
Explore other message types in the Developer Reference: scheduled messages, delayed messages, ordered messages, and transactional messages each support different delivery semantics