microsoft / cppwin32

A modern C++ projection for the Win32 SDK

The C++ Windows SDK projection

C++/Win32 (cppwin32) is a standard C++ language projection for Windows SDK APIs. True, the Windows SDK already releases headers that can be consumed from C++, but those headers have some severe historical and compatiblity constraints that hamper C++ developers that wish to enjoy modern language features. Goals include:

• Better compliance with C++ standards, particularly C++17 and newer.
• Eliminating the use of macros for constants, enumerations, and functions, and instead using C++ language constructs that participate in the type system and respect scope.
• Paving the way towards a Windows SDK that can be used with C++ modules.

Another goal under investigation and discussion is to converge this projection with the C++/WinRT projection.

How it works

This projection is similar to C++/WinRT in that it generates projection header files from metadata. Instead of using Windows Runtime metadata, it uses metadata produced by the Win32 Metadata Project.

This project is still in the early stages and will continue to grow and evolve. Watch for a Nuget package soon.

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.

When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.

Trademarks

This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft's Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies.

cppwin32's Issues

Need to work out how to resolve WinRT types.

In the current metadata, we are seeing references to some WinRT types:

• Windows.Foundation.IPropertyValue
• Windows.System.DispatcherQueueController
• Windows.UI.Composition.IGraphicsEffectSource
• Windows.UI.Composition.CompositionGraphicsDevice
• Windows.UI.Composition.CompositionCapabilities
• Windows.UI.Composition.Desktop.DesktopWindowTarget

In order to generate the correct code to deal with these types as parameters (e.g. CreateDispatcherQueueController), we need to be able to resolve those types. At the moment, these types are all interfaces or runtimeclasses, so we can work around the lack of a definition for now, and use other definitions

What's worse, is that for these APIs to be truly usable, the calling code needs to have some notion of a type definition. Right now, there is no such thing as win32::Windows::Foundation::IPropertyValue, and it seems unlikely to ever change - we already have a first-class projection of WinRT types in C++/WinRT.

So, we have three alternatives as I see it:

1. Interop with C++/WinRT, and perhaps even converge/merge with that projection. The lightest version would be when we encounter those types to generate the #include statements for the C++/WinRT headers - but this doesn't seem like a great user experience if the user doesn't know about nor wish to use C++/WinRT. So, this path strongly leads towards some sort of merge in our future.
2. Generate a minimal "Win32" version (i.e. pared-down) of the needed WinRT types, sort of how the official SDK refers to types in the ABI namespace.
3. Don't do much of anything at all, and leave these WinRT types as forward declarations only.

This library and WIL

In many ways the Windows Implementation Libraries already provides many modern C++ APIs for Win32.

How does the two play out in the future? Merge/converge?

Failed to include win32/Windows.Win32.Dxgi.h

Build started...
1>------ Build started: Project: SampleD3DApp, Configuration: Release x64 ------
1>pch.cpp
1>D:\p\cppwin32\test\SampleD3DApp\SampleD3DApp\pch.h(3,10): fatal error C1083: Cannot open include file: 'win32/Windows.Win32.Dxgi.h': No such file or directory
1>Done building project "SampleD3DApp.vcxproj" -- FAILED.
========== Build: 0 succeeded, 1 failed, 0 up-to-date, 0 skipped ==========

My Visual Studio (2019) setup:

Microsoft Visual Studio Professional 2019
Version 16.8.4
VisualStudio.16.Release/16.8.4+30907.101
Microsoft .NET Framework
Version 4.8.04084

Installed Version: Professional

Visual C++ 2019   00435-60000-00000-AA173
Microsoft Visual C++ 2019

.NET Portability Analyzer   1.1.10808.0
Evaluates portability of assemblies across .NET platforms.

ADL Tools Service Provider   1.0
This package contains services used by Data Lake tools

ASA Service Provider   1.0

ASP.NET and Web Tools 2019   16.8.557.25636
ASP.NET and Web Tools 2019

ASP.NET Core Razor Language Services   16.1.0.2052803+84e121f1403378489b842e1797df2f3f5a49ac3c
Provides languages services for ASP.NET Core Razor.

ASP.NET Web Frameworks and Tools 2012   16.8.557.25636
For additional information, visit https://www.asp.net/

ASP.NET Web Frameworks and Tools 2019   16.8.557.25636
For additional information, visit https://www.asp.net/

Azure App Service Tools v3.0.0   16.8.557.25636
Azure App Service Tools v3.0.0

Azure Data Lake Node   1.0
This package contains the Data Lake integration nodes for Server Explorer.

Azure Data Lake Tools for Visual Studio   2.6.3000.0
Microsoft Azure Data Lake Tools for Visual Studio

Azure Functions and Web Jobs Tools   16.8.557.25636
Azure Functions and Web Jobs Tools

Azure Stream Analytics Tools for Visual Studio   2.6.3000.0
Microsoft Azure Stream Analytics Tools for Visual Studio

BenchmarkTreeWindow Extension   1.0
BenchmarkTreeWindow Visual Studio Extension Detailed Info

C# Tools   3.8.0-5.20604.10+9ed4b774d20940880de8df1ca8b07508aa01c8cd
C# components used in the IDE. Depending on your project type and settings, a different version of the compiler may be used.

Child Process Debugging Power Tool   1.0
Power tool to add child process debugging to Visual Studio.

Common Azure Tools   1.10
Provides common services for use by Azure Mobile Services and Microsoft Azure Tools.

Cookiecutter   16.8.20241.2
Provides tools for finding, instantiating and customizing templates in cookiecutter format.

Dotfuscator Community Edition   5.42.0.9514-e0e25f754
PreEmptive Protection - Dotfuscator CE

Extensibility Message Bus   1.2.6 (master@34d6af2)
Provides common messaging-based MEF services for loosely coupled Visual Studio extension components communication and integration.

Fabric.DiagnosticEvents   1.0
Fabric Diagnostic Events

IntelliCode Extension   1.0
IntelliCode Visual Studio Extension Detailed Info

JetBrains ReSharper 2020.3.2   Build 203.0.20201229.111204
JetBrains ReSharper package for Microsoft Visual Studio. For more information about ReSharper, visit http://www.jetbrains.com/resharper. Copyright © 2021 JetBrains, Inc.

Markdown Editor   1.12.253
A full featured Markdown editor with live preview and syntax highlighting. Supports GitHub flavored Markdown.

Microsoft Azure HDInsight Azure Node   2.6.3000.0
HDInsight Node under Azure Node

Microsoft Azure Hive Query Language Service   2.6.3000.0
Language service for Hive query

Microsoft Azure Service Fabric Tools for Visual Studio   16.0
Microsoft Azure Service Fabric Tools for Visual Studio

Microsoft Azure Stream Analytics Language Service   2.6.3000.0
Language service for Azure Stream Analytics

Microsoft Azure Stream Analytics Node   1.0
Azure Stream Analytics Node under Azure Node

Microsoft Azure Tools   2.9
Microsoft Azure Tools for Microsoft Visual Studio 2019 - v2.9.30924.1

Microsoft Continuous Delivery Tools for Visual Studio   0.4
Simplifying the configuration of Azure DevOps pipelines from within the Visual Studio IDE.

Microsoft JVM Debugger   1.0
Provides support for connecting the Visual Studio debugger to JDWP compatible Java Virtual Machines

Microsoft MI-Based Debugger   1.0
Provides support for connecting Visual Studio to MI compatible debuggers

Microsoft Visual C++ Wizards   1.0
Microsoft Visual C++ Wizards

Microsoft Visual Studio Tools for Containers   1.1
Develop, run, validate your ASP.NET Core applications in the target environment. F5 your application directly into a container with debugging, or CTRL + F5 to edit & refresh your app without having to rebuild the container.

Microsoft Visual Studio VC Package   1.0
Microsoft Visual Studio VC Package

Mono Debugging for Visual Studio   16.8.43 (00471f8)
Support for debugging Mono processes with Visual Studio.

Node.js Tools   1.5.20902.1 Commit Hash:b474efcb6f92db52a8f8e2e6a8cb9648476885cc
Adds support for developing and debugging Node.js apps in Visual Studio

NuGet Package Manager   5.8.1
NuGet Package Manager in Visual Studio. For more information about NuGet, visit https://docs.nuget.org/

Office Developer Tools for Visual Studio   16.0.30502.00
Microsoft Office Developer Tools for Visual Studio

PlayStation® Visual Studio Integration   3.0.3.6
PlayStation® Visual Studio Integration
Copyright © 2019 Sony Interactive Entertainment Inc. All rights reserved.

Project System Tools   1.0
Tools for working with C#, VisualBasic, and F# projects.

ProjectServicesPackage Extension   1.0
ProjectServicesPackage Visual Studio Extension Detailed Info

Python   16.8.20241.2
Provides IntelliSense, projects, templates, debugging, interactive windows, and other support for Python developers.

Python - Conda support   16.8.20241.2
Conda support for Python projects.

Python - Django support   16.8.20241.2
Provides templates and integration for the Django web framework.

Python - IronPython support   16.8.20241.2
Provides templates and integration for IronPython-based projects.

Python - Profiling support   16.8.20241.2
Profiling support for Python projects.

SN-DBS VC Extension 2019   1.1.4.0
Allows you to distribute native VS 2019 C/C++ builds for Windows with SN-DBS.

Source Server Browser Power Tool   1.0
Power tool to allow browsing of Source Server information in a module.

SQL Server Data Tools   16.0.62012.31170
Microsoft SQL Server Data Tools

Syntax Visualizer   1.0
An extension for visualizing Roslyn SyntaxTrees.

Test Adapter for Boost.Test   1.0
Enables Visual Studio's testing tools with unit tests written for Boost.Test.  The use terms and Third Party Notices are available in the extension installation directory.

Test Adapter for Google Test   1.0
Enables Visual Studio's testing tools with unit tests written for Google Test.  The use terms and Third Party Notices are available in the extension installation directory.

ToolWindowHostedEditor   1.0
Hosting json editor into a tool window

TypeScript Tools   16.0.21016.2001
TypeScript Tools for Microsoft Visual Studio

Visual Basic Tools   3.8.0-5.20604.10+9ed4b774d20940880de8df1ca8b07508aa01c8cd
Visual Basic components used in the IDE. Depending on your project type and settings, a different version of the compiler may be used.

Visual C++ for Cross Platform Mobile Development (Android)   16.0.30608.117
Visual C++ for Cross Platform Mobile Development (Android)

Visual C++ for Cross Platform Mobile Development (iOS)   16.0.30608.117
Visual C++ for Cross Platform Mobile Development (iOS)

Visual C++ for Linux Development   1.0.9.30608
Visual C++ for Linux Development

Visual F# Tools   16.8.0-beta.20507.4+da6be68280c89131cdba2045525b80890401defd
Microsoft Visual F# Tools

Visual Studio Code Debug Adapter Host Package   1.0
Interop layer for hosting Visual Studio Code debug adapters in Visual Studio

Visual Studio Container Tools Extensions   1.0
View, manage, and diagnose containers within Visual Studio.

Visual Studio Tools for CMake   1.0
Visual Studio Tools for CMake

Visual Studio Tools for Containers   1.0
Visual Studio Tools for Containers

Visual Studio Tools for Kubernetes   1.0
Visual Studio Tools for Kubernetes

VisualStudio.DeviceLog   1.0
Information about my package

VisualStudio.Foo   1.0
Information about my package

VisualStudio.Mac   1.0
Mac Extension for Visual Studio

Workflow Manager Tools 1.0   1.0
This package contains the necessary Visual Studio integration components for Workflow Manager.

Xamarin   16.8.000.261 (d16-8@bb99248)
Visual Studio extension to enable development for Xamarin.iOS and Xamarin.Android.

Xamarin Designer   16.8.0.507 (remotes/origin/d16-8@e87b24884)
Visual Studio extension to enable Xamarin Designer tools in Visual Studio.

Xamarin Templates   16.8.112 (86385a3)
Templates for building iOS, Android, and Windows apps with Xamarin and Xamarin.Forms.

Xamarin.Android SDK   11.1.0.26 (d16-8/a36ce73)
Xamarin.Android Reference Assemblies and MSBuild support.
    Mono: 5e9cb6d
    Java.Interop: xamarin/java.interop/d16-8@79d9533
    ProGuard: Guardsquare/proguard/proguard6.2.2@ebe9000
    SQLite: xamarin/sqlite/3.32.1@1a3276b
    Xamarin.Android Tools: xamarin/xamarin-android-tools/d16-8@2fb1cbc


Xamarin.iOS and Xamarin.Mac SDK   14.8.0.3 (c51fabee8)
Xamarin.iOS and Xamarin.Mac Reference Assemblies and MSBuild support.

Modern Windows API C++ wrapper?

Am I understanding correctly that this project aims to finally provide a sensible modern C++ wrapper around the old Windows C API similar to the following open source projects/guides?
https://github.com/GiovanniDicanio/WinReg
https://github.com/alamaison/washer
https://github.com/Graham--M/winapi-wrapper
https://www.enlyze.com/blog/writing-win32-apps-like-its-2020/part-2

Sadly none of these projects are complete and actively maintained.

So far there is a severe lack in the area of modern C++ Windows API wrappers how it seems since working with outdated constructs suchs as error codes, handles, etc. is not appropriate for modern C++. Writing your own clean wrappers every time is very time consuming. So, it would be great if Microsoft could close this gap in the near future to also make development with the Windows API nicer now with the release of Windows 11. It seems like the community cannot accomplish this without Microsoft's help. Like vcpkg, this project could become a great success and the community can contribute a lot so Microsoft won't have to do all the work either besides the coordination of the open source development.

Wrong Win32 Metadata link in README

The How it works section in the README file mentions the Win32 Metadata Project, but wrongly points to C++/WinRT. Please fix the link.

ACTION REQUIRED: Microsoft needs this private repository to complete compliance info

There are open compliance tasks that need to be reviewed for your cppwin32 repo.

Action required: 4 compliance tasks

To bring this repository to the standard required for 2021, we require administrators of this and all Microsoft GitHub repositories to complete a small set of tasks within the next 60 days. This is critical work to ensure the compliance and security of your microsoft GitHub organization.

Please take a few minutes to complete the tasks at: https://repos.opensource.microsoft.com/orgs/microsoft/repos/cppwin32/compliance

• The GitHub AE (GitHub inside Microsoft) migration survey has not been completed for this private repository
• No Service Tree mapping has been set for this repo. If this team does not use Service Tree, they can also opt-out of providing Service Tree data in the Compliance tab.
• No repository maintainers are set. The Open Source Maintainers are the decision-makers and actionable owners of the repository, irrespective of administrator permission grants on GitHub.
• Classification of the repository as production/non-production is missing in the Compliance tab.

You can close this work item once you have completed the compliance tasks, or it will automatically close within a day of taking action.

If you no longer need this repository, it might be quickest to delete the repo, too.

GitHub inside Microsoft program information

More information about GitHub inside Microsoft and the new GitHub AE product can be found at https://aka.ms/gim or by contacting [email protected]

FYI: current admins at Microsoft include @manodasanW, @BenJKuhn, @DefaultRyan, @dunhor, @Scottj1s, @kennykerr

Regarding that NuGet package

Is there any way to distribute this code (the code generator, its inputs, and its support headers) other than via a NuGet package? NuGet packages in C++ projects still require the use of packages.config, an ancient technique that breaks CI and annoys the heck out of everyone, because it was fixed for all other project types years ago. Microsoft has repeatedly refused requests to add PackageReference support to vcxproj, to the annoyance of everyone in the Windows C++ developer community. The suggested replacement, vcpkg, is no answer, as it only supports headers and libraries, not code generators or their binary input files. And people who don’t use vcxproj cannot use these libraries at all, since you cannot download the code except via a NuGet package, and you cannot use a NuGet package unless you are building using vcxproj. I don’t mind using NuGet or vcxproj; what I do mind is that our repeated requests for PackageReference, in the forum you explicitly tell us we should post on, are continually ignored.

Bottom line: I don’t care if PackageReference for C++ is something you are interested in or not. But if you are going to be shipping all this wonderful code via NuGet only, that makes it impossible for me to integrate it into my project. There must be some other way you can come up with to allow me to integrate these features into my code. Thank you, and my apologies in advance if I sounded demanding.

Too long namespaces and file names

Please consider making namespaces and file names shorter. There are too many duplicated parts. We know that it is for Windows, no any good reasons to mention it three times in every place.

For example:

using namespace win32;
using namespace win32::Windows::Win32;
using namespace win32::Windows::Win32::Direct3D12;
using namespace win32::Windows::Win32::SystemServices;
using namespace win32::Windows::Win32::Dxgi;
using namespace win32::Windows::Win32::Direct3D11;

It could look just like this:

using namespace Win32;
using namespace Win32::Direct3D12;
using namespace Win32::SystemServices;
using namespace Win32::DXGI;
using namespace Win32::Direct3D11;

Or this example:

#include <win32/Windows.Win32.Dxgi.h>
#include <win32/Windows.Win32.Direct3D12.h>
#include <win32/Windows.Win32.Direct3D11.h>
#include <win32/Windows.Win32.DisplayDevices.h>
#include <win32/Windows.Win32.MenusAndResources.h>
#include <win32/Windows.Win32.SystemServices.h>
#include <win32/Windows.Win32.WindowsAndMessaging.h>

It could look like this:

#include <Win32/DXGI.h>
#include <Win32/Direct3D12.h>
#include <Win32/Direct3D11.h>
#include <Win32/DisplayDevices.h>
#include <Win32/MenusAndResources.h>
#include <Win32/SystemServices.h>
#include <Win32/WindowsAndMessaging.h>

Performance?

What are the performance costs here? Wouldn't accessing Win32 API over winmd take a noticeable performance hit? The beauty of C++17 is that it's near-zero cost abstractions.

Feedback

1. Too many static in header files. They should be "inline", instead of static. The inline means the compiler should discard duplicated symbols. If you use static, it bloats the functions for every translation unit.
   https://devblogs.microsoft.com/oldnewthing/20200521-00/?p=103777
2. It looks like some functions are no marks in headers. That violates ODR and makes compilation impossible.
3. We cannot use anything that relates to iostream, including filesystem. iostream introduces dead virtual functions in the binary that bloats a lot of binary size.
4. include<windows.h>. Windows.h is a large header file. It is extremely slow. The correct way is of course to declare functions by yourself and then use linker comments to link against them.
5. Even std::string, std::array need to be used carefully because they bloat compilation time. Particularly std::string

Should handle types be integer types or pointer types

There's a debate over whether win32 handle types should be defined as integer types or pointer types in the metadata. I wanted to see if there was any cppwin32 maintainers who had an opinion on it. Please let us know at microsoft/win32metadata#395

struct HRESULT incompatible with int HRESULT across ABI boundary

The current code is using the metadata struct HRESULT out of the box across the ABI. Unfortunately, unlike function params, structs are not handled the same way at the ABI as integers, so frame/register corruption is occurring.

For a short-term fix, replace the HRESULT struct with the integral value at the ABI.

Long-term, we'll need to figure out what the projected types vs ABI types look like. The type system for Win32 is far less constrained than the WinRT type system, and the lack of conventions and rules presents some additional challenges for just how much we can encapsulate projection logic.