How to: Create a Classic COM Component Using WRL

Article
01/31/2013

You can use the Windows Runtime C++ Template Library (WRL) to create basic classic COM components for use in desktop apps, in addition to using it for Windows Store apps. For the creation of COM components, the WRL may require less code than the ATL. For information about the subset of COM that the WRL supports, see Windows Runtime C++ Template Library (WRL).

This document shows how to use the WRL to create a basic COM component. Although you can use the deployment mechanism that best fits your needs, this document also shows a basic way to register and consume the COM component from a desktop app.

To use the WRL to create a basic classic COM component

In Visual Studio, create a Blank Solution project. Name the project, for example, WRLClassicCOM.
Add a Win32 Project to the solution. Name the project, for example, CalculatorComponent. On the Application Settings tab, select DLL.
Add a Midl File (.idl) file to the project. Name the file, for example, CalculatorComponent.idl.

Add this code to CalculatorComponent.idl:

import "ocidl.idl";

[uuid(0DBABB94-CE99-42F7-ACBD-E698B2332C60), version(1.0)] 
interface ICalculatorComponent : IUnknown
{
    HRESULT Add([in] int a, [in] int b, [out, retval] int* value);
}

[uuid(9D3E6826-CB8E-4D86-8B14-89F0D7EFCD01), version(1.0)]
library CalculatorComponentLib
{
    [uuid(E68F5EDD-6257-4E72-A10B-4067ED8E85F2), version(1.0)]
    coclass CalculatorComponent
    {
        [default] interface ICalculatorComponent;
    }
};

In CalculatorComponent.cpp, define the CalculatorComponent class. The CalculatorComponent class inherits from Microsoft::WRL::RuntimeClass. Microsoft::WRL::RuntimeClassFlags<ClassicCom> specifies that the class derives from IUnknown and not IInspectable. (IInspectable is available only to Store app components.) CoCreatableClass creates a factory for the class that can be used with functions such as CoCreateInstance.

#include "stdafx.h"

#include "CalculatorComponent_h.h"
#include <wrl.h>

using namespace Microsoft::WRL;

class CalculatorComponent: public RuntimeClass<RuntimeClassFlags<ClassicCom>, ICalculatorComponent>
{
public:
    CalculatorComponent()
    {
    }

    STDMETHODIMP Add(_In_ int a, _In_ int b, _Out_ int* value)
    {
        *value = a + b;
        return S_OK;
    }
};

CoCreatableClass(CalculatorComponent);

Use the following code to replace the code in dllmain.cpp. This file defines the DLL export functions. These functions use the Microsoft::WRL::Module class to manage the class factories for the module.

#include "stdafx.h"
#include <wrl\module.h>

using namespace Microsoft::WRL;

#if !defined(__WRL_CLASSIC_COM__)
STDAPI DllGetActivationFactory(_In_ HSTRING activatibleClassId, _COM_Outptr_ IActivationFactory** factory)
{
    return Module<InProc>::GetModule().GetActivationFactory(activatibleClassId, factory);
}
#endif

#if !defined(__WRL_WINRT_STRICT__)
STDAPI DllGetClassObject(REFCLSID rclsid, REFIID riid, _COM_Outptr_ void** ppv)
{
    return Module<InProc>::GetModule().GetClassObject(rclsid, riid, ppv);
}
#endif

STDAPI DllCanUnloadNow()
{
    return Module<InProc>::GetModule().Terminate() ? S_OK : S_FALSE;
}

STDAPI_(BOOL) DllMain(_In_opt_ HINSTANCE hinst, DWORD reason, _In_opt_ void*)
{
    if (reason == DLL_PROCESS_ATTACH)
    {
        DisableThreadLibraryCalls(hinst);
    }
    return TRUE;
}

Add a Module-Definition File (.def) file to the project. Name the file, for example, CalculatorComponent.def. This file gives the linker the names of the functions to be exported.

Add this code to CalculatorComponent.def:

LIBRARY

EXPORTS
    DllGetActivationFactory PRIVATE
    DllGetClassObject       PRIVATE
    DllCanUnloadNow         PRIVATE

Add runtimeobject.lib to the linker line. To learn how, see .Lib Files as Linker Input.

To consume the COM component from a desktop app

Register the COM component with the Windows Registry. To do so, create a registration entries file, name it RegScript.reg, and add the following text. Replace <dll-path> with the path of your DLL—for example, C:\\temp\\WRLClassicCOM\\Debug\\CalculatorComponent.dll.

Windows Registry Editor Version 5.00

[HKEY_CLASSES_ROOT\Wow6432Node\CLSID\{E68F5EDD-6257-4E72-A10B-4067ED8E85F2}]
@="CalculatorComponent Class"

[HKEY_CLASSES_ROOT\Wow6432Node\CLSID\{E68F5EDD-6257-4E72-A10B-4067ED8E85F2}\InprocServer32]
@="<dll-path>"
"ThreadingModel"="Apartment"

[HKEY_CLASSES_ROOT\Wow6432Node\CLSID\{E68F5EDD-6257-4E72-A10B-4067ED8E85F2}\Programmable]

[HKEY_CLASSES_ROOT\Wow6432Node\CLSID\{E68F5EDD-6257-4E72-A10B-4067ED8E85F2}\TypeLib]
@="{9D3E6826-CB8E-4D86-8B14-89F0D7EFCD01}"

[HKEY_CLASSES_ROOT\Wow6432Node\CLSID\{E68F5EDD-6257-4E72-A10B-4067ED8E85F2}\Version]
@="1.0"

Run RegScript.reg or add it to your project’s Post-Build Event. For more information, see Pre-build Event/Post-build Event Command Line Dialog Box.
Add a Win32 Console Application project to the solution. Name the project, for example, Calculator.

Use this code to replace the contents of Calculator.cpp:

#include "stdafx.h"

#include "..\CalculatorComponent\CalculatorComponent_h.h" 

const IID IID_ICalculatorComponent = {0x0DBABB94,0xCE99,0x42F7,0xAC,0xBD,0xE6,0x98,0xB2,0x33,0x2C,0x60};
const CLSID CLSID_CalculatorComponent = {0xE68F5EDD,0x6257,0x4E72,0xA1,0x0B,0x40,0x67,0xED,0x8E,0x85,0xF2};

// Prints an error string for the provided source code line and HRESULT 
// value and returns the HRESULT value as an int. 
int PrintError(unsigned int line, HRESULT hr)
{
    wprintf_s(L"ERROR: Line:%d HRESULT: 0x%X\n", line, hr);
    return hr;
}

int wmain()
{
    HRESULT hr;

    // Initialize the COM library.
    hr = CoInitializeEx(nullptr, COINIT_APARTMENTTHREADED);
    if (FAILED(hr))
    {
        return PrintError(__LINE__, hr);
    }

    ICalculatorComponent* calc = nullptr; // Interface to COM component. 

    // Create the CalculatorComponent object.
    hr = CoCreateInstance(CLSID_CalculatorComponent, nullptr, CLSCTX_INPROC_SERVER, IID_PPV_ARGS(&calc));
    if (SUCCEEDED(hr))
    {
        // Test the component by adding two numbers. 
        int result;
        hr = calc->Add(4, 5, &result);
        if (FAILED(hr))
        {
            PrintError(__LINE__, hr);
        }
        else
        {
            wprintf_s(L"result = %d\n", result);
        }

        // Free the CalculatorComponent object.
        calc->Release();
    }
    else
    {
        // Object creation failed. Print a message.
        PrintError(__LINE__, hr);
    }

    // Free the COM library.
    CoUninitialize();

    return hr;
}
/* Output:
result = 9
*/

Robust Programming

This document uses standard COM functions to demonstrate that you can use the WRL to author a COM component and make it available to any COM-enabled technology. You can also use WRL types such as Microsoft::WRL::ComPtr in your desktop app to manage the lifetime of COM and other objects. The following code uses the WRL to manage the lifetime of the ICalculatorComponent pointer. The CoInitializeWrapper class is an RAII wrapper that guarantees that the COM library is freed and also guarantees that the lifetime of the COM library outlives the ComPtr smart pointer object.

#include "stdafx.h"
#include <wrl.h>

#include "..\CalculatorComponent\CalculatorComponent_h.h" 

using namespace Microsoft::WRL;

const IID IID_ICalculatorComponent = {0x0DBABB94,0xCE99,0x42F7,0xAC,0xBD,0xE6,0x98,0xB2,0x33,0x2C,0x60};
const CLSID CLSID_CalculatorComponent = {0xE68F5EDD,0x6257,0x4E72,0xA1,0x0B,0x40,0x67,0xED,0x8E,0x85,0xF2};

// Prints an error string for the provided source code line and HRESULT 
// value and returns the HRESULT value as an int. 
int PrintError(unsigned int line, HRESULT hr)
{
    wprintf_s(L"ERROR: Line:%d HRESULT: 0x%X\n", line, hr);
    return hr;
}

int wmain()
{
    HRESULT hr;

    // RAII wrapper for managing the lifetime of the COM library. 
    class CoInitializeWrapper
    {
        HRESULT _hr;
    public:
        CoInitializeWrapper(DWORD flags)
        {
            _hr = CoInitializeEx(nullptr, flags);
        }
        ~CoInitializeWrapper()
        {
            if (SUCCEEDED(_hr))
            {
                CoUninitialize();
            }
        }
        operator HRESULT()
        {
            return _hr;
        }

    };

    // Initialize the COM library.
    CoInitializeWrapper initialize(COINIT_APARTMENTTHREADED);
    if (FAILED(initialize))
    {
        return PrintError(__LINE__, initialize);
    }

    ComPtr<ICalculatorComponent> calc; // Interface to COM component. 

    // Create the CalculatorComponent object.
    hr = CoCreateInstance(CLSID_CalculatorComponent, nullptr, CLSCTX_INPROC_SERVER, IID_PPV_ARGS(calc.GetAddressOf()));
    if (SUCCEEDED(hr))
    {
        // Test the component by adding two numbers. 
        int result;
        hr = calc->Add(4, 5, &result);
        if (FAILED(hr))
        {
            return PrintError(__LINE__, hr);
        }
        wprintf_s(L"result = %d\n", result);
    }
    else
    {
        // Object creation failed. Print a message. 
        return PrintError(__LINE__, hr);
    }

    return 0;
}

How to: Create a Classic COM Component Using WRL

To use the WRL to create a basic classic COM component

To consume the COM component from a desktop app

Robust Programming

See Also

Concepts

Additional resources