Windows API Code Pack v1.1 Release
+Notes
Release Overview
+ +The major changes v1.1 of the Windows API Code Pack includes:
+ ++Code clean-up
+ +o +Addressed many +FxCop violations and PREfast warnings
+ +o +Various spot-fixes for improved stability
+ +o +Added String localization preparation
+ ++Bug Fixes within the Code Pack and Samples
+ ++New Features
+ +o +PropVariant (Re-designed)
+ +o +Thumbnail Handlers
+ +o +Preview Handlers
+ +o +ShellObjectWatcher
+ ++New Demos and Sample Applications
+ ++Visual Studio 2010 Compliance
+ ++xUnit test coverage
+ ++Signed assemblies
+ +Release Changes
+ +Code Clean-up
+ +This release the code underwent a review process to assess +how well the project adhered to Microsofts design guidelines for class +libraries. To address the discovered issues +we have corrected a large number of outstanding FxCop and PREfast warnings in the +codebase. Many of these corrections have +resulted in API changes that may prevent existing applications from using the +new code base without upgrading. A +complete list of these changes can be found in the API Changes documents.
+ +FxCop
+is an application that analyzes managed code assemblies for potential design,
+localization, performance, and security improvements. We addressed all of the
+FxCop violations in the release.
PREfast
+is a static analysis tool that identifies defects in C/C++ code that
+can detect certain kinds of source code errors that are not easily found by the
+typical compiler or by conventional testing. PREfast can be used to detect
+access to misused memory allocations, compliment with specifications, possible
+argument-type mismatches, and more. In this release we addressed all of the
+PREfast warnings in our DirectX Project.
Bugs Fixed
+ +This release contains many bug fixes. Below are some of the +more significant ones.
+ +ALL
+ ++Properties should not be write-only
+ +Core
+ ++BatteryState.EstimatedTimeRemaining returns an +unexpected value when the device is plugged in.
+ ++BatteryState.DischargeRate is named incorrectly +and returns an unexpected negative value.
+ ++PropVariant should not be a struct
+ ++PropVariant should support float[] and decimal[] +datatypes
+ ++PropVariant. +CreatePropVariantFromVectorElement copies data twice (fixed with the re-design)
+ ++PowerManager should expose a way to set the +threads execution-state and inform the system that an app is in use
+ ++TaskDialogCommandLink.ToString() returns extra +line breaks
+ ++TaskDialog doesnt Dispose correctly and throws +a NullReferenceException
+ +Shell
+ ++ExplorerBrowser throws an unwrapped COM +Exception when navigating quickly
+ ++ProgressBarStateSettings class is never used +(removed).
+ ++TabbedThumbnail leaks memory
+ ++WinForms ExplorerBrowserthrows an unwrapped COM +Exception when canceling the first navigation
+ ++ShellObjectCollection throws a +NullReferenceException when using IEnumberable extensions and the content +variable is null or the Count is zero.
+ ++IJumpListTask should not be an empty interface
+ ++ShellFile from a NonFileSystemFolder does not +have the same properties as a ShellFileSystemFolder
+ +Direct X
+ +
+OpenSharedResource
+functions should support DirectUnknown
+CreateTexture
+functions should have a variable-length arguments
+DeviceContext.Map
+function should return a MappedSubresource instead of accepting one as an
+argument
+BitmapSource.CopyPixels crashes if the bitmaps
+width is greater than its height
+Improve support for the creation of D3D10
+StateBlocks
SAMPLES
+ +All of the samples have been reviewed many have undergone +stability and performance improvements.
+ +Features Added
+ +ALL Projects
+ +This release has been released such that it will build in +Visual Studio 2008 and will succeed in converting to run in Visual Studio +2010. The exception to this is the +ShellExtensions project and Handler Samples project which require .NET 4 +features and can only be built in Visual Studio 2010.
+ +Core
+ +Redesigned PROPVARIANT
+ +The PropVariant has been completely redesigned. Issues that +you experienced in the past may no longer be a problem please see the new +implementation in the source code. The redesign included changing it from a +struct to a class, making it immutable and disposable, improving the +performance of setting and retrieving values, +and greatly increasing its maintainability and flexibility.
+ +Shell Extensions
+ +The Shell Extensions project has been added to contain the +new Shell Extensions added to the API Code Pack. This project only targets .NET +4.0 and contains features that are designed to facilitate extending the shell.
+ +File Thumbnail handlers
+ +The Microsoft.WindowsAPICodePack.ShellExtensions namespace +now contains APIs to support the development of managed thumbnail handlers. Thumbnail handlers are shell extensions that allow +one to specify how the Windows Shell will display a thumbnail for a custom file +type. The Shell does this by calling your handler with a reference to file whose +thumbnail is being requested. Thumbnail handlers +can be designed to include adornments (i.e.: drop shadows or photo +borders), overlays (i.e.: icons), and transparency. Below are a few examples of thumbnails +generated from a custom file type using managed thumbnail handlers:
+ +To build a custom thumbnail handler:
+ ++Derive your handler from ThumbnailProvider and implement +at least one of the following initialization interfaces: IThumbnailFromStream, +IThumbnailFromShellObject, IThumbnailFromFile. IThumbnailFromStream is highly +encouraged if possible - initializing with a Steam is explicitly suggested on MSDN.
+ +o +Implement the ConstructBitmap functions for the +initialization interfaces you chose and return a Bitmap based on the provided +shell item and thumbnail size.
+ ++Add the required class attributes
+ +o +ThumbnailProvider Attribute - specifies how the handler should be +registered
+ ++Specify a unique name for the handler, +semicolon-delimited list of supported extensions, adornment, overlay, and cutoff size.
+ +o
+[Guid("XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")] The GUID under which your
+assembly is registered. This GUID must be unique.
o
+[ComVisible(true)]
+- Ensures that your shell extension can
+be registered and is visible by the Shell.
o
+[ClassInterface(ClassInterfaceType.None)] Required for interoperability
o
+[ProgId("YourHandlers.YourXYZThumbnailHandler")]
+ Another ID used to register your handler
A managed thumbnail handler can be compiled for AnyCPU but +must target .NET 4. As with all managed +COM objects, thumbnail handlers must be registered with regasm.exe. +For more information on thumbnail handlers and the available features, see the +thumbnail handler samples included with this release and the MSDN +page for thumbnail handlers.
+ +Implementation Notes: +Only 32bpp bitmaps (for thumbnails) support adornments. Additional guidelines for +development can be found on MSDN +.
+ +Compilation Notes: +This feature was designed for .NET 4.0 as the new version of the CLR allows +multiple runtimes in the same process. Information on why using previous +versions of .NET is highly discouraged can be found here. +For more information on why .NET 4 is a safer alternative see this MSDN article. The What Does In-Process Side-by-Side Mean +To You? section discusses shell extensions. This feature cannot be compiled for earlier +versions of .NET as it uses features specific to .NET 4.
+ +Test Notes: When +registering & unregistering thumbnail handlers for testing purposes certain +actions should be taken to ensure that you are observing the actual behavior of +the thumbnail handler.
+ ++Terminate instances of DllHost.exe (the +surrogate host for your handler) or Explorer.exe (if opting out of process +isolation).
+ ++Delete the thumbnail cache files with the Disk +Cleanup utility included with Windows. See this article +for instructions.
+ ++Generated thumbnails are cached by Windows. To +cause a new thumbnail to be generated you can increase the size of the viewed +thumbnail to a previously unviewed size, manually modify the file such that the +last modified time is updated on the file, or create a new instance of the +file. Our developers found it extremely +helpful to write a script which on build-complete would automatically update +the test files.
+ +If all three initialization interfaces are implemented, only +one will be used according to the circumstances and Shells own preset +priorities for the native interfaces. The prioritized order of access is as +follows: IThumbnailFromStream, +IThumbnailFromShellObject, IThumbnailFromFile.
+ +File Preview Handlers
+ +The Microsoft.WindowsAPICodePack.ShellExtensions namespace +now contains APIs to support the development of managed preview handlers. Preview handlers are shell extensions that +allows one to specify how the Windows Shell or Microsoft Outlook will display a +preview for a custom file type . The Shell does this by calling your handler +and providing access to the file whose preview is being requested. Previews can be displayed in explorers +preview pane or Microsoft Outlook.
+ +The APIs for implementing a preview handler require that a +native window handle is supplied to shell. +In this release we provide abstracted implementations for both WPF and +Winforms as well as providing access to the base class if a more custom +approach is required. Below are a few examples of previews generated from a +custom file type using managed preview handlers (WPF on top, WinForms on the +bottom):
+ +To build a custom preview handler:
+ ++Derive your handler from either +WPFPreviewHandler or WinFormsPreviewHandler and implement at least one of following +initialization interfaces: IPreviewFromStream, IPreviewFromShellObject, +IPreviewFromFile. IPreviewFromStream is highly encouraged if possible +(initializing with a Steam is explicitly suggested on MSDN).
+ +o +Implement the Load functions for the initialization +interfaces. Based on the shell item provided to +the called Load function, populate the Control property inherited from WPFPreviewHandler or +WinFormsPreviewHandler.
+ ++Add the required class attributes
+ +o +PreviewHandler Attribute - specifies how the handler should be +registered
+ ++Specify the name of the handler, a +semicolon-delimited list of supported extensions, and a unique AppID (GUID) for +the dedicated +surrogate host process (prevhost.exe).
+ +o
+[Guid("XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")] The GUID under which your assembly is registered. This GUID must be unique.
o
+[ComVisible(true)] - Ensures that your handler can be registered and is visible by the Shell.
o
+[ClassInterface(ClassInterfaceType.None)] Required for
+interoperability
o
+[ProgId("YourHandlers.YourXYZThumbnailHandler")]
+ Another ID used to register your handler
A managed preview handler can be compiled for AnyCPU but must target .NET 4. As with all managed COM objects they must be +registered with regasm.exe.
+ +Implementation Notes: +Additional guidelines for development can be found on MSDN +.
+ +Compilation Notes: +This feature was designed for .NET 4.0 as the new version of the CLR allows +multiple runtimes in the same process. Information +on why using previous versions of .NET can be found here. +For more information on why .NET 4 is a safer alternative see this MSDN article. The What Does In-Process Side-by-Side Mean +To You? section discusses shell extensions. This feature cannot be compiled +for earlier versions of .NET as it uses features specific to .NET 4.
+ +Test Notes: When +registering & unregistering preview handlers for testing purposes certain +actions should be taken to ensure that you are observing the actual behavior of +the preview handler.
+ ++Terminate instances of Prevhost.exe (the +surrogate host for your provider) or Explorer.exe (if opting out of process +isolation).
+ +If the file-type is associated with a particular +application, the adornment specified in your thumbnail handler may be +overridden and not be shown. If all three initialization interfaces are +implemented, only one will be used according to the circumstances under which +the thumbnail is requested and Shells own preset priorities for the native interfaces. +The prioritized order of access is as follows: +IPreviewFromStream, IPreviewFromShellObject, IPreviewFromFile.
+ +Shell Object Watcher
+ +The +Microsoft.WindowsAPICodePack.Shell namespace now contains APIs to watch +items within the Shell Namespace and receive notifications +when theyre modified. The ShellObjectWatcher class allows an application
+ +to subscribe to individual ShellFiles or ShellContainers (including +virtual folders like network shares and Libraries). The complete list of +supported notifications can be found here. +
+ +To register for change notifications on a specified shell +item:
+ ++Create a new instance of ShellObjectWatcher and +provide an instance of a ShellObject
+ ++Subscribe to the desired events
+ ++Call the Start() method on the +ShellObjectWatcher instance
+ +To unsubscribe to notifications call the Stop() method. You +cannot change which events youre subscribed +to while the watcher is running. To alter the list of subscribed +notifications, call the Stop() method, unsubscribe/subscribe to events, then +call the Start() method.
+ +Behavioral Notes: +Change notifications are initially +raised on a separate thread and use the current or default +SynchronizaionContext to raise events. In +the case of WPF and Windows Forms, these events are marshaled over to the +thread containing the ShellObjectWatcher. +Console applications and other +types of applications that do not provide a default implementations of a +SynchronizationContext are treated as free threaded.
+ +Shell items are watched according to their PIDL (pointer +to ID list) which is constructed similarly to an items fully qualified +path. If a shell item is renamed its +PIDL will change but the ShellObjectWatcher will continue to watch the original +PIDL. This behavior must be taken into account as future changes to the renamed +shell item will not raise notifications. To receive notifications on a renamed +shell item, create a new ShellObjectWatcher withthe renamed shell item and Stop +the ShellObjectWatcher created with the shell item prior to the rename. If the +ShellObjectWatcher created with the shell item (prior to the rename) is not Stopped and the file is reverted to +its original name, notifications will continue to be raised from that +ShellObjectWatcher. Similarly, if a another shell item is renamed to match the +fully qualified path of a watched shell item, the ShellObjectWatcher will raise +notifications on that renamed shell item despite the fact that the +ShellObjectWatcher was created with a different shell item. In summary, the change notification for a +shell item is solely based on PIDLs and persists to do so regardless of the +actual shell it is associated with a given PIDL.
+ +SAMPLES ADDED
+ +Shell
+ +ShellObjectWatcher +Sample
+ +This sample allows the user to select an item from the +Windows Shell and watch it for change notifications. This sample supports +files, folders, and virtual folders (i.e.: network shares & libraries).
+ +Shell Extensions
+ +Thumbnail Handler +Samples
+ +Two samples have been created to demonstrate how to generate +thumbnails for an .xyz file-type and .xyz2 file type. The samples demonstrate +how to use the various initialization interfaces and parse a sample file to +generate a thumbnail with adornments and overlays.
+ +Preview Handler +Samples
+ +Two samples have been created to demonstrate how to generate +a preview from an .xyz and .xyz2 file-type. One sample illustrates how to +generate a WPF control and the other +demonstrates how to generate a Windows Forms control within the preview pane of +explorer.
+ +API Changes
+ +A complete list of these changes can be found in the API +Changes documents. Changes are organized by namespace and class and are +structured as follows:
+ +<Kind Of Member Modified> : +<Identifier of Member Modified> : <Type/Return-type of Member +Modified>
+ +<Changes Made to Member>
+<Members Removed from this Member>
<Members
+Added to this Member>
Below are a few examples of actual entries from the DirectX +changes document:
+ +Class: SwitchToRef
Removed
+methods: GetUseRef() : System.Boolean, SetUseRef(System.Boolean) :
+System.Boolean
+Added
+properties: UseRef : System.Boolean
In this entry, the SwitchToRef class has been modified. The GetUseRef (returning a +Boolean) and SetUseRef (accepting a Boolean) have been removed in favor of +adding a Property called UseRef.
+ +Method: GetClusterMetrics() :
+Microsoft.WindowsAPICodePack.DirectX.DirectWrite.ClusterMetrics[]
Renamed to
+"ClusterMetrics"
+Kind changed to "Property"
+Added methods: get_ClusterMetrics() :
+System.Collections.Generic.IEnumerable<Microsoft.WindowsAPICodePack.DirectX.DirectWrite.ClusterMetrics>
In this entry the GetClusterMetrics() method was removed in +favor of a readonly ClusterMetrics Property. The return type has also been +changed from an array to an IEnumerable
+ +