Creating and Using a Dynamic Link Library (C+)

The first type of library we will create is a dynamic link library (DLL). Using DLLs 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.

This walkthrough covers the following:

• Creating a new dynamic link library (DLL) project.

• Adding a class to the dynamic link library.

• Creating an application that references the dynamic link library.

• Using the functionality from the class library in the console application.

• Running the application.

Prerequisites

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

To create a new dynamic link library (DLL) project

1. From the File menu, select New and then Project….

2. On the Project types pane, under Visual C++, select Win32.

3. On the Templates pane, select Win32 Console Application.

4. Choose a name for the project, such as MathFuncsDll, and type it in the Name field. Choose a name for the solution, such as DynamicLibrary, and type it in the Solution Name field.

5. Click OK to start the Win32 application wizard. On the Overview page of the Win32 Application Wizard dialog box, click Next.

6. On the Application Settings page of the Win32 Application Wizard, under Application type, select DLL if it is available or Console application if DLL is not available. Some versions of Visual Studio do not support creating a DLL project by using wizards. You can change this later to make your project compile into a DLL.

7. On the Application Settings page of the Win32 Application Wizard, under Additional options, select Empty project.

8. Click Finish to create the project.

To add a class to the dynamic link library

1. To create a header file for a new class, from the Project menu, select Add New Item…. The Add New Item dialog box will be displayed. On the Categories pane, under Visual C++, select Code. On the Templates pane, select Header File (.h). Choose a name for the header file, such as MathFuncsDll.h, and click Add. A blank file will be displayed.

2. Add a simple class named MyMathFuncs to do common mathematical operations, such as addition, subtraction, multiplication, and division. The code should resemble the following:

   // MathFuncsDll.h
   
   namespace MathFuncs
   {
       class MyMathFuncs
       {
       public:
           // Returns a + b
           static __declspec(dllexport) double Add(double a, double b);
   
           // Returns a - b
           static __declspec(dllexport) double Subtract(double a, double b);
   
           // Returns a * b
           static __declspec(dllexport) double Multiply(double a, double b);
   
           // Returns a / b
           // Throws DivideByZeroException if b is 0
           static __declspec(dllexport) double Divide(double a, double b);
       };
   }
   

3. Note the __declspec(dllexport) modifier in the method declarations in this code. These modifiers enable the method to be exported by the DLL so that it can be used by other applications. For more information, see dllexport, dllimport.

4. To create a source file for a new class, from the Project menu, select Add New Item…. The Add New Item dialog box will be displayed. On the Categories pane, under Visual C++, select Code. On the Templates pane, select C++ File (.cpp). Choose a name for the source file, such as MathFuncsDll.cpp, and click Add. A blank file will be displayed.

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

   // MathFuncsDll.cpp
   // compile with: /EHsc /LD
   
   #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 new invalid_argument("b cannot be zero!");
           }
   
           return a / b;
       }
   }
   

6. To build the project into a DLL, from the Project menu, select MathFuncsDllProperties…. On the left pane, under Configuration Properties, select General. On the right pane, change the Configuration Type to Dynamic Library (.dll). Click OK to save the changes.

   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).

7. Compile the dynamic link library by selecting Build Solution from the Build menu. This creates a DLL that can be used by other programs. For more information about DLLs, see DLLs.

To create an application that references the dynamic link library

1. To create an application that will reference and use the dynamic link library that you just created, from the File menu, select New and then Project….

2. On the Project types pane, under Visual C++, select Win32.

3. On the Templates pane, select Win32 Console Application.

4. Choose a name for the project, such as MyExecRefsDll, and type it in the Name field. Next to Solution, select Add to Solution from the drop down list. This will add the new project to the same solution as the dynamic link library.

5. Click OK to start the Win32 Application Wizard. On the Overview page of the Win32 Application Wizard dialog box, click Next.

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

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

8. Press Finish 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 for the project earlier. In this example, it is named MyExecRefsDll.cpp.

2. To use the math routines that were created in the dynamic link library, you must reference the library. To do this, select References… from the Project menu. On the Property Pages dialog box, expand the Common Properties node, select References, and then select 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 is displayed. This dialog lists all the libraries that you can reference. The Project tab lists all the projects in the current solution and any libraries they contain. On the Projects tab, select MathFuncsDll. Then click OK. For more information about the Add Reference dialog box, see Add Reference Dialog Box.

4. To reference the header files of the dynamic link library, you must modify the include directories path. To do this, on the Property Pages dialog box, expand the Configuration Properties node, expand the C/C++ node, and then select General. Next to Additional Include Directories, type the path of the location of the MathFuncsDll.h header file.

5. The executable does not load dynamic link libraries until runtime. You must tell the system where to locate MathFuncsDll.dll. You do so by using the PATH environment variable. To do this, on the Property Pages dialog box, expand the Configuration Properties node and select Debugging. Next to Environment, type the following: PATH=<path of MathFuncsDll.dll file>, where <path of MathFuncsDll.dll file> is replaced with the actual location of MathFuncsDll.dll. Click OK to save all the changes.

   Note

   If you want to run the executable from the command line instead of from Visual Studio, you must manually update the PATH environment variable from the command prompt as follows: set PATH=%PATH%;<path of MathFuncsDll.dll file>, where <path of MathFuncsDll.dll file> is replaced with the actual location of MathFuncsDll.dll.

6. 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;
   
       return 0;
   }
   

7. Build the executable by selecting Build Solution from the Build menu.

To run the application

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

2. To run the project, select Start Without Debugging from the Debug menu. The output should resemble this:

   a + b = 106.4
   a - b = -91.6
   a * b = 732.6
   a / b = 0.0747475
   

Next Steps

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

See Also

Tasks

Visual C++ Guided Tour

Deploying Your Program (C+)

Concepts

DLLs

Other Resources

Common Programming Methodologies

Deployment (C+)