We are wrapping up our comprehensive drilldown into the Windows 7 Libraries API and architecture with one final post about the managed API for working with Windows 7 Libraries. Previously we talked about: Understanding Windows 7 Libraries, Libraries Under the Hood, Light Up with Windows 7 Libraries, Consuming the Contents of Windows 7 Libraries, Stay in Sync with Windows 7 Libraries, Windows 7 Libraries Helpers

In this post we focus on the managed API for working with Windows 7 Libraries. The Windows API Code Pack for the Microsoft .NET Framework Library (Windows API Code Pack) provides a .NET interface into the Windows native API, thereby enabling the 7 key Windows Light-Up features as well as tapping into more advanced shell integration, as we described in the Windows 7 Managed Code APIs post. You can download the Windows Code Pack API

The Windows API Code Pack has a very good managed interface to the Windows Shell, and particularly to the Windows 7 Libraries API. ShellLibrary (a part of the Microsoft.WindowsAPICodePack.Shell dll that you need to add as a reference to your .NET application in order to work with Windows 7 libraries), is the only object that represents Libraries. The image to the left displays the ShellLibrary class.

Now you can start working with Libraries. First, you need to create a Library object using one of the four available constructors. You might want to use the constructor that takes a Known Folder as a parameter. This is to allow developers easy maintenance while developing. Note, however, that most constructors receive an overwrite Boolean. Make sure you don’t overwrite your own existing Documents library (or any other library), since the creation of a new

image
ShellLibrary object saves the library’s XML detention file to the Library’s Known Folder, as we described in Libraries Under the Hood. The following single line of code creates a new ShellLibrary object, thus creating a new Library.
ShellLibrary library = new ShellLibrary(“new test lib1”, true);
 
If you don’t have to create a new library, you can load an existing library to obtain the required ShellLibrary object. Keep in mind that all load functions are static functions that don’t require an already existing ShellLibrary instance. Every load function’s last parameter is a isReadOnly Boolean that you may use when you just need to read a library's contents and without changing it. For example, an application that backs up all your libraries has no need to change the library. The following code snippet is all that is needed to load an existing library:
ShellLibrary library = ShellLibrary.Load("My Pictures", true);
 
OK, you have a ShellLibrary object -- what can you do with it? Well there are few things ways to have fun with libraries. First, you can add or remove specific folders from the library. Remember that libraries are just abstract containers and don’t really hold files, but just point to the actually folders that do hold the files, as explained in the Understanding Windows 7 Libraries post. To add a folder just call the Add function, in a similar way, call the remove function to remove a folder. You can add or remove folders by either using a specific path represented by a string or using a FileSystemFolder object as shown in the following code snippet:
public void Add(FileSystemFolder item);
public void Add(string folderPath);
public bool Remove(FileSystemFolder item);
public bool Remove(string folderPath);
 
Besides managing folders in your library, you can also set the default save location of the library by using the DefaultSaveFolder property. Assuming the library is a ShellLibrary object, the following code snippet returns the default save location of the Library:
String dsfStr = library.DefaultSaveFolder

Note that when setting the default save folder, you need to provide a valid system folder for which you have write and read permission. If this folder is not already part of the library, it will be added to the library and will become the default save location. As a developer, you can also add unsupported folder locations that are not indexed and can’t be indexed.

Another very cool feature is control of the library icon. This one of those features that end users don’t have access to, and it is SO easy to use, as shown in the following code snippet:

library.IconResourceId = new IconReference(icon);

You will have to obtain an IconReference object, but after doing so you get to change the library’s Icon and set your own special icons. This is a really fun feature to play with, as you can see from the following picture:

 image

Another important feature of the ShellLibrary object is the capability to list all the items and folders in a library. The ShellLibrary object implements the IList<FileSystemFolder> interface. This supports enumeration of the folders in the library by calling the GetEnumerator function or by using the foreach statement as shown in the following code snippet that prints the folder’s name and default save location:

foreach (ShellFolder folder in library)
{
    Console.WriteLine(
            "\t\t{0} {1}", 
            folder.Name, 
            defaultSaveFolder == folder.Name ? "*" : "")
}

You can control the library type by using the LibraryType property, and you can elect to pin the library listing to the left navigation pane of Windows Explorer using the IsPinnedToNavigationPane property.

Last, I want to talk about displaying the Library Manager window. It is important to display this window if you wish to create a consistent user experience for managing libraries in Windows Explorer and your application. Since displaying the Library Manager window displays a new dialog window in an existing application, you need to take into account the technology used by the application. The function ShowManageLibraryUI can receive either a Win32 window handle (whnd) that will work great with WinForms, or a WPF windows object for WPF applications.

library.ShowManageLibraryUI(IntPtr.Zero, “title of dialog”, "help text…", true);
 
The last thing we are going to talk about is deleting a library. The ShellLibrary object doesn’t have a self destruct mechanism and therefore you can’t delete a library using the ShellLibrary object. To delete a library you need to delete the library XML definition file. The code snippet below gets a string representing the library name that correlates to same library definition file. See Understanding Windows 7 Libraries for more information. 
public static void DeleteLibrary(string name)
{
    string librariesPath = Path.Combine(
        Environment.GetFolderPath(
            Environment.SpecialFolder.ApplicationData),
            ShellLibrary.LibrariesKnownFolder.RelativePath);

    string libraryPath = Path.Combine(librariesPath, name);
    string libraryFullPath = Path.ChangeExtension(libraryPath, "library-ms");

    File.Delete(libraryFullPath);
}
As you can see, we first use a combination of the Environment.SpecialFolder.ApplicationData and the ShellLibrary ShellLibrary.LibrariesKnownFolder.RelativePath to assemble the folder in which all the libraries definition files are stored. Then we append the library-ms file extension, and finally we delete the file. Remember, by deleting the file, we delete the library; so again, be careful not to delete any important libraries.

We have covered all the important functionality of the Libraries managed code API and, together with the previous posts; you now should have a very good sense of how Windows 7 Libraries work and how to use them in your applications.

In addition, you can get first-hand coding experience with Windows 7 by going through the Windows 7 Libraries Hands-On-Lab (HOL) that is part of the Windows 7 RC Training Kit for Developers. The Library HOL includes the code used in this post, so go ahead and download the training kit.

Tags: , , , , ,