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++ application. 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 reference them from applications that need 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.

This walkthrough covers these tasks:

  • Creating a DLL project.

  • Adding a class to the DLL.

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

  • Using the functionality from the class in the application.

  • Running the application.

This walkthrough creates a DLL that can only be called from applications 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.

  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.

  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 do 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, MATHFUNCSDLL_API defines the __declspec(dllimport) modifier in the member function declarations. This modifier enables the compiler to optimize the importing of the function from the DLL for use in other applications. By default, 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 from the command line, use the /LD compiler option to specify that the output file should 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).

  1. To create a C++ application 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 of the Win32 Application Wizard, 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 console application

  1. After you create a new console application, 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 your application 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 select 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 Projects tab lists the projects in the current solution and any libraries they contain. On the Projects tab, select 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\.) Choose the OK button.

  5. You can now use the MyMathFuncs class in this application. Use the following code to replace the contents of MyExecRefsDll.cpp.

    // 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 selecting 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!

Next Steps

Previous: Creating Reusable Code (C++) | Next: Walkthrough: Creating and Using a Static Library (C++)

See Also

Tasks

Visual C++ Guided Tour

Walkthrough: Deploying Your Program (C++)

Concepts

DLLs

Other Resources

Visual C++ Programming Methodologies

Deployment (Visual C++)