Consuming libraries and components
C++ projects often need to call functions or access data in a binary file such as static library (LIB files), DLL, Windows Runtime component, COM component, or .NET assembly. In these cases, you have to configure the project so that it can find that binary at build time. The specific steps depend on the type of your project, the type of the binary, and whether the binary gets built in the same solution as your project.
Consuming libraries downloaded via vcpkg
To consume a library that you have downloaded by using the vcpkg package manager, you can ignore the instructions below. See vcpkg: A C++ package manager for Windows, Linux, and macOS for more information.
Consuming static libraries
If your static library project gets built in the same solution:
- #include the header file(s) for the static library using quotation marks. In a typical solution, the path starts with
../<library project name>. IntelliSense will help you find it.
- Add a reference to the static library project. Right-click on References under the application project node in Solution Explorer and choose Add Reference.
If the static library isn't part of the solution:
- Right-click on the application project node in Solution Explorer and then choose Properties.
- In the VC++ Directories property page, add the path to the directory that contains the LIB file to Library Paths. Then, add the path to the library header file(s) to Include Directories.
- In the Linker > Input property page, add the name of the LIB file to Additional Dependencies.
Dynamic link libraries
If the DLL gets built as part of the same solution as the application, follow the same steps as for a static library.
If the DLL isn't part of the application solution, you need: the DLL file, the header(s) with prototypes for the exported functions and classes, and a LIB file that provides the necessary linking information.
- Copy the DLL to the output folder of your project, or to another folder in the standard Windows search path for DLLs. See Dynamic-Link Library Search Order.
- Follow steps 1-3 for static libraries to provide the paths to the headers and LIB file.
If your native C++ application needs to consume a COM object, and that object is registered, then all you have to do is call CoCreateInstance and pass in the CLSID of the object. The system will find it in the Windows Registry and load it. A C++/CLI project can consume a COM object in the same way. Or, it can consume it by adding a reference to it from the Add References > COM list and consuming it through its Runtime callable wrapper.
.NET assemblies and Windows Runtime Components
In UWP or C++/CLI projects, you consume .NET assemblies or Windows Runtime Components by adding a reference to the assembly or component. Under the References node in a UWP or C++/CLI project, you see references to commonly used components. Right-click on the References node in Solution Explorer to bring up the Reference Manager and browse through the components available on the system. Choose the Browse button to navigate to any folder that contains a custom component. Because .NET assemblies and Windows Runtime components contain built-in type information, you can view their methods and classes by right-clicking and choosing View in Object Browser.
Each kind of reference has properties. You can view the properties by selecting the reference in Solution Explorer and pressing Alt + Enter, or else right-clicking and choosing Properties. Some properties are read-only and some are modifiable. However, typically you don't have to manually modify these properties.
ActiveX reference properties
ActiveX reference properties are available only for references to COM components. These properties get displayed only when you select a COM component in the References pane. The properties aren't modifiable.
Control Full Path
Displays the directory path of the referenced control.
Displays the GUID for the ActiveX control.
Displays the version of the referenced ActiveX control.
Type Library Name
Displays the name of the referenced type library.
Displays the tool that's used to build the interop assembly from the referenced COM library or ActiveX control.
Assembly reference properties (C++/CLI)
Assembly reference properties are available only for references to .NET Framework assemblies in C++/CLI projects. These properties get displayed only when you select a .NET Framework assembly in the References pane. The properties aren't modifiable.
Displays the relative path from the project directory to the referenced assembly.
The following properties are available on various kinds of references. They enable you to specify how to build with references.
Specifies whether to automatically copy the referenced assembly to the target location during a build.
Copy Local Satellite Assemblies (C++/CLI)
Specifies whether to automatically copy the satellite assemblies of the referenced assembly to the target location during a build. Only used if Copy Local is
Reference Assembly Output
Specifies that this assembly gets used in the build process. If
true, the assembly gets used on the compiler command line during the build.
Project-to-project reference properties
The following properties define a project-to-project reference from the project that's selected in the References pane to another project in the same solution. For more information, see Managing references in a project.
Link Library Dependencies
When this property is True, the project system links the LIB files that the independent project produces into the dependent project. Typically, you'll specify True.
Uniquely identifies the independent project. The property value is an internal system GUID that isn't modifiable.
Use Library Dependency Inputs
When this property is False, the project system won't link the OBJ files for the library that the independent project produces into the dependent project. That's why this value disables incremental linking. Typically, you'll specify False because building the application can take a long time if there are many independent projects.
Read-only reference properties (COM & .NET)
The following properties exist on COM and .NET assembly references, and aren't modifiable.
Displays the assembly name for the referenced assembly.
Displays the culture of the selected reference.
Displays the description of the selected reference.
Displays the directory path of the referenced assembly.
For the .NET Framework assemblies, displays the full path. For COM components, displays the GUID.
Displays the label of the reference.
Displays the name of the reference.
Public Key Token
Displays the public key token used to identify the referenced assembly.
trueif the referenced assembly has a strong name. A strong named assembly has a unique version.
Displays the version of the referenced assembly.