Environment preparation

Windows .NET SDK

The SDK for .NET is a managed wrapper built on top of the C++ version of the ApsaraMQ for RocketMQ client. This design ensures that the SDK operates independently of the standard Windows .NET public libraries. Internally, it uses C++ multithreaded concurrent processing to ensure high performance and stability.

When you develop .NET applications and class libraries in Visual Studio (VS), the default target platform is "Any CPU". This setting allows the application to run on either x86 or x64 platforms, depending on the processor architecture. At runtime, the Just-In-Time (JIT) compiler of the Common Language Runtime (CLR) converts the Intermediate Language (IL) code into native x86 or x64 machine code. In contrast, a DLL generated by a C/C++ compiler is already machine code, with the target platform determined at compile time. By setting the appropriate compilation options, the C/C++ project is compiled into an x64 DLL. Therefore, this SDK provides a 64-bit DLL in release mode, compiled with Visual Studio 2015 and .NET Framework 4.5.2. This DLL is also compatible with other versions of Visual Studio.

Download the Windows .NET SDK

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

Configure the .NET SDK in Visual Studio 2015

1. Create a project in Visual Studio 2015. Open Visual Studio 2015 and click New Project.... In the New Project dialog box, navigate to Installed > Templates > Visual C# > Windows. Select Console Application, set the target framework to .NET Framework 4.5.2, specify a project name, and then click OK.

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

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

4. Write your test program and compile it. To run the program, place the SDK's DLL files in the same directory as the executable or in a system directory. After compilation, you can find the required runtime files, such as ONSClient4CPP.dll, in the output directory, which is typically bin\x64\Release.

   Note

   The SDK includes a pre-configured demo project. You can open and compile this project directly. Before running the application, copy the required DLL files to the same directory as the executable.

   The files to copy are ONSClient4CPP.dll, ONSClient4CPP.lib, and ONSClient4CPP.pdb. The destination directory, such as bin\Debug or bin\Release, depends on your build configuration and target platform.

Configure ASP.NET in Visual Studio 2015 to use the ApsaraMQ for RocketMQ SDK

1. Create an ASP.NET Web Forms project in Visual Studio 2015. In Visual Studio 2015, click New Project. In the template tree on the left, select Installed > Templates > Visual C#. From the template list, select ASP.NET Web Application, specify the project name (for example, WebApplication1), set the framework version to .NET Framework 4.5.2, and then click OK.

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

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

   For more information, see Step 2 in the "Configure the SDK for .NET in Visual Studio 2015" section.

4. Add the code to start and shut down the SDK in the Global.asax.cs file.

   Important

   Wrap the SDK code in a singleton class. This prevents the garbage collector from prematurely collecting the object when it goes out of scope. The example directory in the SDK package includes Example.cs, which provides a simple singleton implementation. You must 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;    // The namespace where the SDK is located.
   using test;   // The namespace for a simple wrapper class for the SDK. See Example.cs in the SDK example 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
              {
                  // Code to start the SDK. The following code uses a simple wrapper.
                  OnscSharp.CreateProducer();
                  OnscSharp.StartProducer();
              }
              catch (Exception ex)
              {
              // Handle exceptions.
              }
          }
          protected void Application_End(object sender, EventArgs e)
          {
              try
              {
                 // Code to shut down the SDK.
                OnscSharp.ShutdownProducer();
              }
              catch (Exception ex)
              { 
              // Handle exceptions.
              }
          }
     }
   }                  

5. Write your test program and compile it.

6. To run the program, place the SDK's DLL files in the project's bin directory. After compilation, verify that the project's output bin directory, such as Projects\WebApplication4\WebApplication4\bin, contains the ONSClient4CPP.pdb, ONSClient4CPP.dll, and ONSClient4CPP.lib files.

7. Navigate to Tools > Options > Projects and Solutions > Web Projects, and then select the Use the 64-bit version of IIS Express for websites and projects checkbox.