You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/porting/how-to-use-existing-cpp-code-in-a-universal-windows-platform-app.md
+30-33Lines changed: 30 additions & 33 deletions
Original file line number
Diff line number
Diff line change
@@ -1,7 +1,7 @@
1
1
---
2
2
title: "How to: Use Existing C++ Code in a Universal Windows Platform App | Microsoft Docs"
3
3
ms.custom: ""
4
-
ms.date: "11/04/2016"
4
+
ms.date: "08/21/2018"
5
5
ms.technology: ["cpp-language"]
6
6
ms.topic: "conceptual"
7
7
dev_langs: ["C++"]
@@ -11,21 +11,22 @@ ms.author: "mblome"
11
11
ms.workload: ["cplusplus"]
12
12
---
13
13
# How to: Use Existing C++ Code in a Universal Windows Platform App
14
-
Perhaps the easiest way to get your desktop program running in the UWP environment is to use the Desktop Bridge technologies. These include the Desktop App Converter, which will package your existing application as a UWP app with no code changes required. For more information, see [Bring your desktop app to the Universal Windows Platform (UWP) with the Desktop Bridge](https://msdn.microsoft.com/windows/uwp/porting/desktop-to-uwp-root).
14
+
15
+
Perhaps the easiest way to get your desktop program running in the UWP environment is to use the Desktop Bridge technologies. These include the Desktop App Converter, which will package your existing application as a UWP app with no code changes required. For more information, see [Desktop Bridge](/windows/uwp/porting/desktop-to-uwp-root).
15
16
16
17
The rest of this topic discusses how to port C++ libraries (DLLs and static libraries) to the Universal Windows Platform (UWP). You might want to do this so that your core C++ logic can be used with multiple UWP apps.
17
18
18
-
UWP Apps run in a protected environment, and as a result, many Win32, COM, and CRT API calls that might compromise the security of the platform are not allowed. The compiler can detect such calls and generate an error, if the `/ZW` option is used. You can use the App Certification Kit on your application to detect code that calls forbidden APIs. See [Using the App Certification Kit](https://msdn.microsoft.com/library/windows/apps/hh694081.aspx).
19
+
UWP Apps run in a protected environment, and as a result, many Win32, COM, and CRT API calls that might compromise the security of the platform are not allowed. The compiler can detect such calls and generate an error, if the `/ZW` option is used. You can use the App Certification Kit on your application to detect code that calls forbidden APIs. For more information, see [Windows App Certification Kit](/windows/uwp/debug-test-perf/windows-app-certification-kit).
19
20
20
-
If source code is available for the library, you might be able to eliminate the forbidden API calls. For details including a list of APIs that are allowed or forbidden, see [Win32 and COM for Windows Runtime Apps and Universal Windows platform (UWP) Apps](https://msdn.microsoft.com/library/windows/apps/br205762.aspx) and [CRT functions not supported in Universal Windows Platform apps](../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). Some alternatives can be found at [Alternatives to Windows APIs in UWP apps](/uwp/win32-and-com/alternatives-to-windows-apis-uwp).
21
+
If source code is available for the library, you might be able to eliminate the forbidden API calls. For details including a list of APIs that are allowed or forbidden, see [Win32 and COM APIs for UWP apps](/uwp/win32-and-com/win32-and-com-for-uwp-apps) and [CRT functions not supported in Universal Windows Platform apps](../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). Some alternatives can be found at [Alternatives to Windows APIs in UWP apps](/uwp/win32-and-com/alternatives-to-windows-apis-uwp).
21
22
22
-
If you just try to add a reference from a Universal Windows Project to a classic desktop library, you get an error message that says the library is not compatible. In the case of a static library, you can link to your library simply by adding the library (.lib file) to your linker input, just as you would in a classic Win32 application. For libraries where only a binary is available, this is the only option. A static library is linked into your app's executable, but a Win32 DLL that you consume in a UWP app must be packaged into the app by including it in the project and marking it as Content. To load a Win32 DLL in a UWP app, you also have to call [LoadPackagedLibrary](/windows/desktop/api/winbase/nf-winbase-loadpackagedlibrary) instead of LoadLibrary or LoadLibraryEx.
23
+
If you just try to add a reference from a Universal Windows Project to a classic desktop library, you get an error message that says the library is not compatible. In the case of a static library, you can link to your library simply by adding the library (.lib file) to your linker input, just as you would in a classic Win32 application. For libraries where only a binary is available, this is the only option. A static library is linked into your app's executable, but a Win32 DLL that you consume in a UWP app must be packaged into the app by including it in the project and marking it as Content. To load a Win32 DLL in a UWP app, you also have to call [LoadPackagedLibrary](/windows/desktop/api/winbase/nf-winbase-loadpackagedlibrary) instead of `LoadLibrary` or `LoadLibraryEx`.
23
24
24
25
If you have source code for the DLL or static library, you can recompile with `/ZW` as a UWP project. If you do that, you can add a reference using the **Solution Explorer**, and use it in C++ UWP apps. In the case of a DLL, you link with the export library.
25
26
26
27
To expose functionality to callers in other languages, you can convert the library into a Windows Runtime Component. Windows Runtime Components differ from ordinary DLLs in that they include metadata in the form of .winmd files which describe the contents in a way that .NET and JavaScript consumers require. To expose API elements to other languages, you can add C++/CX constructs, such as ref classes, and make them public, or use the [Windows Runtime C++ Template Library (WRL)](../windows/windows-runtime-cpp-template-library-wrl.md). In Windows 10 and later, you can use the [C++/WinRT library](https://github.com/microsoft/cppwinrt) instead of C++/CX.
27
28
28
-
The preceding discussion doesn't apply to the case of COM components, which must be handled differently. If you have a COM server in an EXE or DLL, you can use it in a Universal Windows Project as long as you package it as a [registration-free COM component](/windows/desktop/SbsCs/isolated-applications-and-side-by-side-assemblies-portal), add it to your project as a Content file, and instantiate it using [CoCreateInstanceFromApp](/windows/desktop/api/combaseapi/nf-combaseapi-cocreateinstancefromapp). See [Using Free-COM DLL in Windows Store C++ Project](http://blogs.msdn.com/b/win8devsupport/archive/2013/05/20/using-free-com-dll-in-windows-store-c-project.aspx).
29
+
The preceding discussion doesn't apply to the case of COM components, which must be handled differently. If you have a COM server in an EXE or DLL, you can use it in a Universal Windows Project as long as you package it as a [registration-free COM component](/windows/desktop/sbscs/creating-registration-free-com-objects), add it to your project as a Content file, and instantiate it using [CoCreateInstanceFromApp](/windows/desktop/api/combaseapi/nf-combaseapi-cocreateinstancefromapp). For more information, see [Using Free-COM DLL in Windows Store C++ Project](https://blogs.msdn.microsoft.com/win8devsupport/2013/05/19/using-free-com-dll-in-windows-store-c-project/).
29
30
30
31
If you have an existing COM library that you want to port to the UWP, you might be able to convert it into a Windows Runtime Component by using the [Windows Runtime C++ Template Library (WRL)](../windows/windows-runtime-cpp-template-library-wrl.md). The WRL does not support all the features of ATL and OLE, so whether such a port is feasible depends on how much your COM code depends on what features of COM, ATL, and OLE your component requires.
31
32
@@ -52,7 +53,7 @@ This topic contains the following procedures:
52
53
53
54
## <a name="BK_Win32DLL"></a> Using a Win32 DLL in a UWP App
54
55
55
-
For better security and reliability, Universal Windows Apps run in a restricted runtime environment, so you can't just use any native DLL the way you would in a classic Windows desktop application. If you have source code for a DLL, you can port the code so that it runs on the UWP. You start by changing a few project settings and project file metadata to identify the project as a UWP project. You need to compile the library code using the `/ZW` option, which enables C++/CX. Certain API calls are not allowed in UWP apps due to stricter controls associated with that environment. See [Win32 and COM for Windows Runtime apps and Universal Windows Platform (UWP) apps](/uwp/win32-and-com/win32-and-com-for-uwp-apps).
56
+
For better security and reliability, Universal Windows Apps run in a restricted runtime environment, so you can't just use any native DLL the way you would in a classic Windows desktop application. If you have source code for a DLL, you can port the code so that it runs on the UWP. You start by changing a few project settings and project file metadata to identify the project as a UWP project. You need to compile the library code using the `/ZW` option, which enables C++/CX. Certain API calls are not allowed in UWP apps due to stricter controls associated with that environment. See [Win32 and COM APIs for UWP apps](/uwp/win32-and-com/win32-and-com-for-uwp-apps).
56
57
57
58
The following procedure applies to the case where you have a native DLL that exposes functions using **__declspec(dllexport)**.
58
59
@@ -90,10 +91,10 @@ The following procedure applies to the case where you have a native DLL that exp
90
91
GIRAFFE_API GiraffeFactory();
91
92
GIRAFFE_API static int GetNextID();
92
93
GIRAFFE_API static Giraffe* Create();
93
-
};
94
+
};
94
95
```
95
-
96
-
And the following code file:
96
+
97
+
And the following code file:
97
98
98
99
```cpp
99
100
// giraffe.cpp
@@ -129,9 +130,9 @@ The following procedure applies to the case where you have a native DLL that exp
129
130
int giraffeFunction();
130
131
```
131
132
132
-
Everything else in the project (stdafx.h, dllmain.cpp) is part of the standard Win32 project template. If you want to follow along, but don't want to use your own DLL yet with these steps, try creating a Win32 project, select DLL in the project wizard, and then add a header file giraffe.h and code file giraffe.cpp, and copy the contents from the code in this step into the appropriate files.
133
-
134
-
The code defines the macro `GIRAFFE_API` which resolves to **__declspec(dllexport)** when `_DLL` is defined (that is, when the project is built as a DLL).
133
+
Everything else in the project (stdafx.h, dllmain.cpp) is part of the standard Win32 project template. If you want to follow along, but don't want to use your own DLL yet with these steps, try creating a Win32 project, select DLL in the project wizard, and then add a header file giraffe.h and code file giraffe.cpp, and copy the contents from the code in this step into the appropriate files.
134
+
135
+
The code defines the macro `GIRAFFE_API` which resolves to **__declspec(dllexport)** when `_DLL` is defined (that is, when the project is built as a DLL).
135
136
136
137
2. Open the **Project Properties** for the DLL project, and set the **Configuration** to **All Configurations**.
137
138
@@ -147,35 +148,33 @@ The following procedure applies to the case where you have a native DLL that exp
Close the .vcxproj file, open the shortcut menu again and choose **Reload Project**.
151
+
Close the .vcxproj file, open the shortcut menu again and choose **Reload Project**.
151
152
152
-
**Solution Explorer** now identifies the project as a Universal Windows project.
153
+
**Solution Explorer** now identifies the project as a Universal Windows project.
153
154
154
155
5. Make sure your precompiled header file name is correct. In the **Precompiled Headers** section, change **Precompiled Header File** from pch.h to stdafx.h. If you don't do this, you see the following error.
155
156
156
-
```Output
157
-
error C2857: '#include' statement specified with the /Ycpch.h command-line option was not found in the source file
158
-
```
157
+
> error C2857: '#include' statement specified with the /Ycpch.h command-line option was not found in the source file
159
158
160
-
The issue is that the Universal Windows projects use a different naming convention for the precompiled header file.
159
+
The issue is that the Universal Windows projects use a different naming convention for the precompiled header file.
161
160
162
161
6. Build the project. You might get some errors about incompatible command line options. For example, the frequently used option **Enable Minimal Rebuild (/Gm)** is set by default in many C++ projects, and is incompatible with `/ZW`.
163
162
164
-
Some functions are not available when you compile for the Universal Windows Platform. You will see compiler errors about any problems. Address these until you have a clean build.
163
+
Some functions are not available when you compile for the Universal Windows Platform. You will see compiler errors about any problems. Address these until you have a clean build.
165
164
166
165
7. To use the DLL in a UWP app in the same solution, open the shortcut menu for the UWP project node, and choose **Add** > **Reference**.
167
166
168
-
Under **Projects** > **Solution**, select the checkbox next to the DLL project, and choose the **OK** button.
167
+
Under **Projects** > **Solution**, select the checkbox next to the DLL project, and choose the **OK** button.
169
168
170
169
8. Include the library's header file(s) in your UWP app's pch.h file.
171
170
172
-
```
171
+
```cpp
173
172
#include "..\MyNativeDLL\giraffe.h"
174
173
```
175
174
176
175
9. Add code as usual in the UWP project to invoke functions and create types from the DLL.
177
176
178
-
```
177
+
```cpp
179
178
MainPage::MainPage()
180
179
{
181
180
InitializeComponent();
@@ -187,11 +186,9 @@ The following procedure applies to the case where you have a native DLL that exp
187
186
188
187
## <a name="BK_StaticLib"></a> Using a native C++ static library in a UWP App
189
188
190
-
You can use a native C++ static library in a UWP project, but there are some restrictions and limitations to be aware of. Start by reading this [topic](https://msdn.microsoft.com/library/hh771041.aspx) about static libraries in C++/CX. You can access the native code in your static library from your UWP app, but it's not recommended to create public ref types in such a static library. If you compile a static library with the `/ZW` option, the librarian (actually the linker in disguise) warns:
189
+
You can use a native C++ static library in a UWP project, but there are some restrictions and limitations to be aware of. Start by reading about [static libraries in C++/CX](../cppcx/static-libraries-c-cx.md). You can access the native code in your static library from your UWP app, but it's not recommended to create public ref types in such a static library. If you compile a static library with the `/ZW` option, the librarian (actually the linker in disguise) warns:
191
190
192
-
```
193
-
LNK4264: archiving object file compiled with /ZW into a static library; note that when authoring Windows Runtime types it is not recommended to link with a static library that contains Windows Runtime metadata
194
-
```
191
+
> LNK4264: archiving object file compiled with /ZW into a static library; note that when authoring Windows Runtime types it is not recommended to link with a static library that contains Windows Runtime metadata
195
192
196
193
However, you can use a static library in a UWP without recompiling it with `/ZW`. You won't be able to declare any ref types or use C++/CX constructs, but if your purpose is to simply use library of native code, then you can do so by following these steps.
197
194
@@ -201,11 +198,11 @@ However, you can use a static library in a UWP without recompiling it with `/ZW`
201
198
202
199
2. Add an include statement to reference the header file to your pch.h in the UWP project and start adding code that uses the library.
203
200
204
-
```
205
-
#include "..\MyNativeLibrary\giraffe.h"
206
-
```
201
+
```cpp
202
+
#include "..\MyNativeLibrary\giraffe.h"
203
+
```
207
204
208
-
Do not add a reference in the **References** node in **Solution Explorer**. That mechanism only works for Windows Runtime Components.
205
+
Do not add a reference in the **References** node in **Solution Explorer**. That mechanism only works for Windows Runtime Components.
209
206
210
207
## <aname="BK_WinRTComponent"></a> Porting a C++ Library to a Windows Runtime Component
211
208
@@ -225,7 +222,7 @@ If you want to consume native APIs in a static library from a UWP app, and you h
225
222
226
223
6. You might now have some duplicated code. If you have more than one precompiled header (say stdafx.h and pch.h), choose one to keep. Copy any required code, such as include statements, into the one you're keeping. Then, delete the other, and in the project properties, under **Precompiled Headers**, make sure that the name of the header file is correct.
227
224
228
-
If you changed the file to use as the precompiled header, make sure that the precompiled header options are correct for each file. Select each .cpp file in turn, open its properties window, and make sure that all are set to **Use (/Yu)**, except for the desired precompiled header, which should be set to **Create (/Yc)**.
225
+
If you changed the file to use as the precompiled header, make sure that the precompiled header options are correct for each file. Select each .cpp file in turn, open its properties window, and make sure that all are set to **Use (/Yu)**, except for the desired precompiled header, which should be set to **Create (/Yc)**.
229
226
230
227
7. Build the project and resolve any errors. These errors could be caused by using the `/ZW` option, or they could be caused by a new version of the Windows SDK, or they might reflect dependencies such as header files that your library depends on, or differences in project settings between your old project and the new one.
231
228
@@ -235,4 +232,4 @@ If you want to consume native APIs in a static library from a UWP app, and you h
235
232
236
233
## See Also
237
234
238
-
[Porting to the Universal Windows Platform](../porting/porting-to-the-universal-windows-platform-cpp.md)
235
+
[Porting to the Universal Windows Platform](../porting/porting-to-the-universal-windows-platform-cpp.md)
0 commit comments