PointerToolkit.TerraFX.Interop.Windows 10.0.22621-preview2

This is a prerelease version of PointerToolkit.TerraFX.Interop.Windows.
There is a newer version of this package available.
See the version list below for details.
dotnet add package PointerToolkit.TerraFX.Interop.Windows --version 10.0.22621-preview2                
NuGet\Install-Package PointerToolkit.TerraFX.Interop.Windows -Version 10.0.22621-preview2                
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="PointerToolkit.TerraFX.Interop.Windows" Version="10.0.22621-preview2" />                
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add PointerToolkit.TerraFX.Interop.Windows --version 10.0.22621-preview2                
#r "nuget: PointerToolkit.TerraFX.Interop.Windows, 10.0.22621-preview2"                
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install PointerToolkit.TerraFX.Interop.Windows as a Cake Addin
#addin nuget:?package=PointerToolkit.TerraFX.Interop.Windows&version=10.0.22621-preview2&prerelease

// Install PointerToolkit.TerraFX.Interop.Windows as a Cake Tool
#tool nuget:?package=PointerToolkit.TerraFX.Interop.Windows&version=10.0.22621-preview2&prerelease                

PointerToolkit.TerraFX.Interop.Windows

Provides methods ("operators") that enable compile-time type-safety when casting COM interface pointers from the TerraFX.Interop.Windows package.

C# and .NET do not have struct inheritance. The COM interface structs defined in TerraFX.Interop.Windows project the native COM interfaces defined in the Windows SDK. These COM interfaces have inheritance, but this cannot be expressed in .NET, and the C# compiler knows nothing about it. This gives us the problem where you may have a pointer to a COM object that should be implicitly castable to its base interface, but C# won't let you do it without an explicit cast.

For example, let's say you're doing some drawing with Direct2D and you want to fill a rectangle with a solid color brush:

ID2D1SolidColorBrush* pBrush;
HRESULT hr = pFactory->CreateSolidColorBrush(..., &pBrush); // creates a brush
...
pRenderTarget->FillRectangle(..., pBrush); // error: ID2D1SolidColorBrush* isn't an ID2D1Brush*

To fix this you can of course insert a cast to ID2D1Brush*:

ID2D1SolidColorBrush* pBrush;
HRESULT hr = pFactory->CreateSolidColorBrush(..., &pBrush); // creates a brush
...
pRenderTarget->FillRectangle(..., (ID2D1Brush*)pBrush); // works fine, but error prone

In a large code base, this is error-prone. If you cast to the wrong type you will get errors at runtime -- hopefully. In the worst case you'll have heap corruption, smashed stacks, crashes, and security vulnerabilities. We developers are imperfect beings, and we need the compiler's help at every step along the way.

PointerToolkit, among other things, introduces a suite of ref structs called CastPtr<T, TBase1, ..., TBaseN>. They wrap a pointer and provide implicit casting operators to the provided "base" types.

This package then defines a suite of generated __cast() methods ("operators") that take pointers to these COM objects and return CastPtr<...> to permit you to use a derived pointer type when a base pointer type is needed.

For example:

ID2D1SolidColorBrush* pBrush;
HRESULT hr = pFactory->CreateSolidColorBrush(..., &pBrush); // creates a brush
...
pRenderTarget->FillRectangle(..., __cast(pBrush)); // works great, not error prone!

When using this package, I highly recommend adding global using statics for the various Pointers classes from this package:

global using static TerraFX.Interop.DirectX.Pointers;
global using static TerraFX.Interop.Gdiplus.Pointers;
global using static TerraFX.Interop.Windows.Pointers;
global using static TerraFX.Interop.WinRT.Pointers;

You can then use __cast(p) as if it were one of those ugly-but-useful vendor-specific extensions that C++ compilers have loads of.

Oh, I also recommend using trimming. I use illink in a custom post-build event rather than relying on the built-in facilities that MSBuild and Visual Studio provide. This way I can trim only the DLLs I need trimmed, such as TerraFX.Interop.Windows.dll and PointerToolkit.TerraFX.Interop.Windows.dll.

Product Compatible and additional computed target framework versions.
.NET net6.0-windows7.0 is compatible.  net7.0-windows was computed.  net8.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
10.0.26100 112 7/23/2024
10.0.22621.6 121 5/7/2024
10.0.22621.5 173 12/30/2023
10.0.22621.2 204 7/21/2023
10.0.22621 378 11/29/2022
10.0.22621-preview2 152 11/10/2022
10.0.20348-preview1 200 5/11/2022