Walkthrough: Creating and Using a Dynamic Link Library (C++)

This step-by-step walkthrough shows how to create a dynamic link library (DLL) for use with a C++ app. Using a library is a great way to reuse code. Rather than re-implementing the same routines in every program that you create, you write them one time and then reference them from apps that require the functionality. By putting code in the DLL, you save space in every app that references it, and you can update the DLL without recompiling all of the apps. For more information about DLLs, see DLLs in Visual C++.

This walkthrough covers these tasks:

• Creating a DLL project.

• Adding a class to the DLL.

• Creating a console app that uses load-time dynamic linking to reference the DLL.

• Using the functionality from the class in the app.

• Running the app.

This walkthrough creates a DLL that can only be called from apps that use C++ calling conventions. For information about how to create DLLs for use with other languages, see Calling DLL Functions from Visual Basic Applications.

Prerequisites

This topic assumes that you understand the fundamentals of the C++ language.

To create a dynamic link library (DLL) project

1. On the menu bar, choose File, New, Project.

2. In the left pane of the New Project dialog box, expand Installed, Templates, Visual C++, and then select Win32.

3. In the center pane, select Win32 Console Application.

4. Specify a name for the project—for example, MathFuncsDll—in the Name box. Specify a name for the solution—for example, DynamicLibrary—in the Solution name box. Choose the OK button.

5. On the Overview page of the Win32 Application Wizard dialog box, choose the Next button.

6. On the Application Settings page, under Application type, select DLL.

7. Choose the Finish button to create the project.

To add a class to the dynamic link library

1. To create a header file for a new class, on the menu bar, choose Project, Add New Item. In the Add New Item dialog box, in the left pane, under Visual C++, select Code. In the center pane, select Header File (.h). Specify a name for the header file—for example, MathFuncsDll.h—and then choose the Add button. A blank header file is displayed.

2. Add the following code to the beginning of the header file:

   // MathFuncsDll.h
   
   #ifdef MATHFUNCSDLL_EXPORTS
   #define MATHFUNCSDLL_API __declspec(dllexport) 
   #else
   #define MATHFUNCSDLL_API __declspec(dllimport) 
   #endif
   

3. Add a basic class named MyMathFuncs to perform common mathematical operations such as addition, subtraction, multiplication, and division. The code should resemble this:

   namespace MathFuncs
   {
       // This class is exported from the MathFuncsDll.dll
       class MyMathFuncs
       {
       public: 
           // Returns a + b
           static MATHFUNCSDLL_API double Add(double a, double b); 
   
           // Returns a - b
           static MATHFUNCSDLL_API double Subtract(double a, double b); 
   
           // Returns a * b
           static MATHFUNCSDLL_API double Multiply(double a, double b); 
   
           // Returns a / b
           // Throws const std::invalid_argument& if b is 0
           static MATHFUNCSDLL_API double Divide(double a, double b); 
       };
   }
   

   When the MATHFUNCSDLL_EXPORTS symbol is defined, the MATHFUNCSDLL_API symbol will set the __declspec(dllexport) modifier in the member function declarations in this code. This modifier enables the function to be exported by the DLL so that it can be used by other applications. When MATHFUNCSDLL_EXPORTS is undefined—for example, when the header file is included by an application—MATHFUNCSDLL_API defines the __declspec(dllimport) modifier in the member function declarations. This modifier optimizes the import of the function in an application. By default, the New Project template for a DLL adds PROJECTNAME_EXPORTS to the defined symbols for the DLL project. In this example, MATHFUNCSDLL_EXPORTS is defined when your MathFuncsDll project is built. For more information, see dllexport, dllimport.

   Note

   If you are building the DLL project on the command line, use the /D compiler option to define the MATHFUNCSDLL_EXPORTS symbol.

4. In the MathFuncsDll project in Solution Explorer, in the Source Files folder, open MathFuncsDll.cpp.

5. Implement the functionality for MyMathFuncs in the source file. The code should resemble this:

   // MathFuncsDll.cpp : Defines the exported functions for the DLL application. 
   //
   
   #include "stdafx.h"
   #include "MathFuncsDll.h"
   #include <stdexcept>
   
   using namespace std;
   
   namespace MathFuncs
   {
       double MyMathFuncs::Add(double a, double b)
       {
           return a + b;
       }
   
       double MyMathFuncs::Subtract(double a, double b)
       {
           return a - b;
       }
   
       double MyMathFuncs::Multiply(double a, double b)
       {
           return a * b;
       }
   
       double MyMathFuncs::Divide(double a, double b)
       {
           if (b == 0)
           {
               throw invalid_argument("b cannot be zero!");
           }
   
           return a / b;
       }
   }
   

6. Compile the dynamic link library by choosing Build, Build Solution on the menu bar.

   Note

   If you are using an Express edition that does not display a Build menu, on the menu bar, choose Tools, Settings, Expert Settings to enable it, and then choose Build, Build Solution.

   Note

   If you are building a project on the command line, use the /LD compiler option to specify that the output file is to be a DLL. For more information, see /MD, /MT, /LD (Use Run-Time Library). Use the /EHsc compiler option to enable C++ exception handling. For more information, see /EH (Exception Handling Model).

To create an app that references the DLL

1. To create a C++ app that will reference and use the DLL that you just created, on the menu bar, choose File, New, Project.

2. In the left pane, under Visual C++, select Win32.

3. In the center pane, select Win32 Console Application.

4. Specify a name for the project—for example, MyExecRefsDll—in the Name box. Next to Solution, select Add to Solution from the drop-down list. This adds the new project to the same solution that contains the DLL. Choose the OK button.

5. On the Overview page of the Win32 Application Wizard dialog box, choose the Next button.

6. On the Application Settings page, under Application type, select Console application.

7. On the Application Settings page, under Additional options, clear the Precompiled header check box.

8. Choose the Finish button to create the project.

To use the functionality from the class library in the app

1. After you create a console app, an empty program is created for you. The name for the source file is the same as the name that you chose earlier. In this example, it is named MyExecRefsDll.cpp.

2. To use in the app the math routines that you created in the DLL, you must reference it. To do this, select the MyExecRefsDll project in Solution Explorer, and then on the menu bar, choose Project, References. In the Property Pages dialog box, expand the Common Properties node, select Framework and References, and then choose the Add New Reference button. For more information about the References dialog box, see Framework and References, Common Properties, <Projectname> Property Pages Dialog Box.

3. The Add Reference dialog box lists the libraries that you can reference. The Project tab lists the projects in the current solution and any libraries that they contain. On the Projects tab, select the check box next to MathFuncsDll, and then choose the OK button.

4. To reference the header files of the DLL, you must modify the included directories path. To do this, in the Property Pages dialog box, expand the Configuration Properties node, expand the C/C++ node, and then select General. Next to Additional Include Directories, specify the path of the location of the MathFuncsDll.h header file. You can use a relative path—for example, ..\MathFuncsDll\—then choose the OK button.

5. You can now use the MyMathFuncs class in this application. Replace the contents of MyExecRefsDll.cpp with the following code:

   // MyExecRefsDll.cpp 
   // compile with: /EHsc /link MathFuncsDll.lib
   
   #include <iostream>
   
   #include "MathFuncsDll.h" 
   
   using namespace std;
   
   int main()
   {
       double a = 7.4;
       int b = 99;
   
       cout << "a + b = " <<
           MathFuncs::MyMathFuncs::Add(a, b) << endl;
       cout << "a - b = " <<
           MathFuncs::MyMathFuncs::Subtract(a, b) << endl;
       cout << "a * b = " <<
           MathFuncs::MyMathFuncs::Multiply(a, b) << endl;
       cout << "a / b = " <<
           MathFuncs::MyMathFuncs::Divide(a, b) << endl;
   
       try
       {
           cout << "a / 0 = " <<
               MathFuncs::MyMathFuncs::Divide(a, 0) << endl; 
       }
       catch (const invalid_argument &e) 
       {
           cout << "Caught exception: " << e.what() << endl; 
       }
   
       return 0;
   }
   

6. Build the executable by choosing Build, Build Solution on the menu bar.

To run the application

1. Make sure that MyExecRefsDll is selected as the default project. In Solution Explorer, select MyExecRefsDll, and then on the menu bar, choose Project, Set As StartUp Project.

2. To run the project, on the menu bar, choose Debug, Start Without Debugging. The output should resemble this:

   a + b = 106.4
   

a - b = -91.6 a * b = 732.6 a / b = 0.0747475 Caught exception: b cannot be zero!

See Also

Tasks

Visual C++ Guided Tour

Walkthrough: Deploying Your Program (C++)

Concepts

DLLs in Visual C++

Calling DLL Functions from Visual Basic Applications

Other Resources

Deploying Native Desktop Applications (Visual C++)