ApsaraMQ for RocketMQ:Prepare the .NET SDK environment

Prerequisites

Before you begin, make sure that you have:

• A Windows 64-bit operating system

• Visual Studio 2015 or later with x64 build support

• .NET Framework 4.5.2 or later

• The Visual C++ 2015 runtime (if not installed, run the vc_redist.x64.exe installer bundled in the SDK package)

How the .NET SDK works

The .NET SDK is a managed wrapper built on the ApsaraMQ for RocketMQ C++ client. It operates independently from the Windows .NET public library and uses C++ multithreaded processing internally for performance and stability.

The underlying C++ DLL is compiled as a 64-bit binary in release mode, built with Visual Studio 2015 and .NET Framework 4.5.2. Your .NET project must target the x64 platform. The default AnyCPU target in Visual Studio does not work with this SDK.

Download the SDK

Download the latest SDK package from the Release notes page. Decompress the package to get the following directory structure:

Set up a .NET project in Visual Studio

1. Create a project in Visual Studio.

2. Right-click the project and choose Add > Add Existing Item to add all files from the interface directory of the SDK package.

3. Right-click the project and choose Properties > Configuration Manager. Set Active solution configuration to Release and Active solution platform to x64.

4. Write and compile your program. Copy the SDK DLL files to the output directory of the executable, then run the program.

   Note

   The SDK includes a preconfigured demo project. Open it, compile, and copy the DLL files to the executable directory to run it directly.

Set up an ASP.NET project in Visual Studio

ASP.NET Web Forms projects require additional lifecycle configuration to start and stop the SDK correctly.

1. Create a Web Forms project for ASP.NET in Visual Studio.

2. Right-click the project and choose Properties > Configuration Manager. Set Active solution configuration to Release and Active solution platform to x64.

3. Right-click the project and choose Add > Add Existing Item to add all files from the interface directory of the SDK package.

4. Add SDK startup and shutdown code to Global.asax.cs.

   Important

   Wrap the SDK code in a singleton class to prevent the garbage collector from reclaiming it due to scope issues. The SDK demo directory includes an Example.cs file that implements a basic singleton pattern. Include Example.cs in your project to use it.

   using 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;    // SDK namespace
   using test;   // Namespace for the singleton wrapper. See Example.cs in the SDK demo directory.
   
   namespace WebApplication4
   {
       public class Global : HttpApplication
       {
           void Application_Start(object sender, EventArgs e)
           {
               // Code that runs on application startup
               RouteConfig.RegisterRoutes(RouteTable.Routes);
               BundleConfig.RegisterBundles(BundleTable.Bundles);
               try
               {
                   // Initialize and start the SDK producer
                   OnscSharp.CreateProducer();
                   OnscSharp.StartProducer();
               }
               catch (Exception ex)
               {
                   // Handle errors
               }
           }
   
           protected void Application_End(object sender, EventArgs e)
           {
               try
               {
                   // Shut down the SDK producer
                   OnscSharp.ShutdownProducer();
               }
               catch (Exception ex)
               {
                   // Handle errors
               }
           }
       }
   }

5. Write and compile your program.

6. Copy the SDK DLL files to the output directory of the executable or to a system directory, then run the program.

7. In Visual Studio, choose Tools > Options > Projects and Solutions > Web Projects. Select the Use the 64 bit version of IIS Express for websites and projects check box.