This topic describes the preparations for accessing Message Queue for Apache RocketMQ through the .NET SDK so that the SDK can be used to send and subscribe to messages.

Notice
  • The topic and group ID in the code must have been created in the Message Queue for Apache RocketMQ console first. The message tag can be specified by application users. For more information about the creation process, see Step 2: Create resources in Quick start for Alibaba Cloud accounts.
  • An application that uses Message Queue for Apache RocketMQ must have been deployed on an Elastic Compute Service (ECS) instance of Alibaba Cloud.

Download the SDK

Windows .NET SDK

The .NET SDK we provide is a hosted encapsulation based on the Message Queue for Apache RocketMQ C++ SDK. In this way, the .NET SDK is independent of Windows .NET SDK public libraries. C++ multi-thread concurrent processing is used to ensure the efficiency and stability of the .NET SDK.

When Visual Studio is used to develop .NET applications and class libraries, the default target platform is "Any CPU", that is, X86 or X64 is automatically selected according to the CPU type when the application runs. When running, CLR transmits its JIT as the machine code X86 or X64. The C or C++ compiled DLL is the machine code. Accordingly, the policies of the platform are determined when the application is compiled. When the compilation options are set, the C/C++ project is compiled as an X64 64-bit DLL. Therefore, the 64-bit DLL in release mode compiled using Visual Studio 2015 and .NET Framework 4.5.2 is provided. Other Visual Studio versions can also be used.

Download earlier versions of Windows .NET SDK

Notice
  • The hosted encapsulation-based SDK has many defects and cannot work stably on ASP.NET. Therefore, a new version of the SDK was launched on December 29, 2016.
  • The new SDK calls underlying DLLs based on C# PInvoke and uses the open-source software SWIG to generate the PInvoke encapsulation code. Compared with the hosted version, the new version of the SDK is more stable and easier to deploy and install.
  • The hosted version of the SDK is no longer maintained, and only the last stable version is provided.

We recommend that both new and old users download the new SDK.

For the download link of the latest .NET SDK version, see Release notes.

Download and decompress the package of the .NET SDK. The package contains the following directories and files:

  • example/
  • lib/
  • demo/
  • interface/
  • SDK_GUIDE.pdf
  • changelog

The preceding directories and files serve the following purposes:

  • example: This folder contains examples for sending and consuming normal messages and ordered messages, and examples for sending messages in one-way mode.
  • lib: This folder contains the C++ DLL files and the runtime installation package for Virtual C++ 2015.
      64/
          NSClient4CPP.lib
          ONSClient4CPP.dll
          ONSClient4CPP.pdb
        vc_redist.x64.exe                    
  • SDK_GUIDE.pdf: This file describes how to prepare the SDK environment and contains FAQ.
  • changelog: This file lists the problems that have been fixed and the new features of the latest version.
  • interface: This folder contains code that is called to encapsulate PInvoke, which needs to be used in the user project code.

Configure .NET SDK

Configuration for using .NET SDK in Visual Studio 2015

  1. Use Visual Studio 2015 to create your project.
  2. Right-click the project and choose Add > Existing Item to add all files in the interface directory extracted from the downloaded SDK package.
  3. Right-click the project and choose Properties. In the window that appears, click Configuration Manager. Set Active solution configuration to Release and Active solution platform to x64.
  4. Write and compile the test program, save the DLL file of the SDK to the directory of the executable file or to the system directory, and run the program.
    Note

    The SDK provides a preconfigured demo, so that you can directly open the project for compilation. When running the program, copy the relevant DLL file to the directory of the executable file, as shown in the following figure:

Configuration in ASP.NET of Visual Studio 2015 for using the Message Queue for Apache RocketMQ SDK

  1. Use Visual Studio 2015 to create a Web Forms project in ASP.NET.
  2. Right-click the project and choose Properties. In the window that appears, click Configuration Manager. Set Active solution configuration to Release and Active solution platform to x64.
  3. Right-click the project and choose Add > Existing Item to add all files in the interface directory extracted from the downloaded SDK package.

    See step 2 for how to configure a common .NET project.

  4. Add the code for starting and stopping the SDK to the Global.asax.cs file.
    Notice We recommend that you encapsulate the SDK code as a singleton class so that the code is not recycled by the garbage collector due to the action scope. The example directory of the SDK contains the Example.cs file for implementing a simple singleton class. To use Example.cs, you need to include it in your own project.
    sing System;
    using System.Collections.Generic;
    using System.Linq;
    using System.Web;
    using System.Web.Optimization;
    using System.Web.Routing;
    using System.Web.Security;
    using System.Web.SessionState;
    using ons; // The namespace where the SDK is located.
    using test; // The namespace where the class with the simply-encapsulated SDK is located. See the Example.cs file in the example directory of the SDK.
    namespace WebApplication4
    {
      public class Global : HttpApplication
      {
           void Application_Start(object sender, EventArgs e)
           {
               // The code that runs on application startup.
               RouteConfig.RegisterRoutes(RouteTable.Routes);
               BundleConfig.RegisterBundles(BundleTable.Bundles);
               try
               {
                   // The code for starting the SDK. The following is the code after the SDK is roughly encapsulated.
                   OnscSharp.CreateProducer();
                   OnscSharp.StartProducer();
               }
               catch (Exception ex)
               {
                           // Handle exceptions.
               }
           }
           protected void Application_End(object sender, EventArgs e)
           {
               try
               {
                  // The code for stopping the SDK.
                 OnscSharp.ShutdownProducer();
               }
               catch (Exception ex)
               { 
                     // Handle exceptions.
               }
           }
      }
    }                  
  5. Write and compile the test program.
  6. Save the DLL file of the SDK to the directory of the executable file or to the system directory and run the program.
  7. Choose Tools > Options. In the window that appears, choose Projects and Solutions > Web Projects and select the Use the 64 bit version of IIS Express for web sites and projects check box.