Shell Libraries - Managedaz12722.vo.msecnd.net/windows7trainingcourse1-0/Labs/Shell... · language...
Transcript of Shell Libraries - Managedaz12722.vo.msecnd.net/windows7trainingcourse1-0/Labs/Shell... · language...
-
Hands-On Lab
Shell Libraries - .NET
Lab version: 1.0.0
Last updated: 10/9/2009
-
Shell Libraries Hands-On Lab
2
CONTENTS
OVERVIEW ............................................................................................................................................. 3
EXERCISE 1: DEVELOPING THE SLUTIL ............................................................................................. 6 Task 1 Creating the SLUtil Project .................................................................................................. 6
Task 2 Adding the Create Command .............................................................................................. 8
Task 3 Adding the AddFolder and RemoveFolder Commands ...................................................... 12
Task 4 Adding the Delete and Rename Commands ...................................................................... 16
Task 5 Adding SaveFolder, NavPanePinnedState, Icon, and FolderType Commands ..................... 18
Task 6 Adding the ShowInfo Command ....................................................................................... 24
Task 7 Adding the ManageUI Command ...................................................................................... 28
SUMMARY ............................................................................................................................................ 33
-
Shell Libraries Hands-On Lab
3
Overview
Windows 7 introduces a new concept of Libraries as the new entry point for users data. Where users
can find and organize their data as collections of items that may span multiple locations across
computers. Libraries supersede the functionality of previous Windows versions' known folders (for
example, Documents, Pictures, Music) and replace them as the main storage destination. The Library
API gives applications a straightforward method for interacting with libraries programmatically.
Applications can create, interact with, and support libraries as first-class items in their environments.
With Windows 7, the concept of Libraries tries to address the problem of users storing content all over
their PC by allowing them to have full control over their Documents Library folder structure. In other
words, in Windows 7 users can define which folders to include in the Documents Library. We can say
that Libraries are user-defined collections of folders that are logical representations of user content. By
including folders in Libraries, the user is telling Windows where his or her important data is located. The
system will index these folders, enabling faster searching and much richer viewing arrangement
capabilities in Windows Explorer based on the file properties and metadata.
In previous versions of Windows, each application had its own proprietary library. For example,
Windows Media Player had a different set of scopes than iTunes, and neither was consistent with the
Music folder. With the Library API, applications can define and consume a consistent set of user-defined
scopes.
-
Shell Libraries Hands-On Lab
4
Figure 1
Libraries integration with Windows Shell
Libraries may also contain network folders. This enables a better user experience at work and at home.
Whenever users open a common file dialog, they get an aggregated view of all of the library locations
that are available.
Note: For more information, see Inside Windows 7: Introducing Libraries.
Objectives
In this Hands-On Lab, you will learn how to manage libraries programmatically; specifically:
Create a new library
Open an existing library
Add and remove folders from a library
Get the librarys folder list
http://msdn.microsoft.com/en-us/magazine/dd861346.aspx
-
Shell Libraries Hands-On Lab
5
Delete a library
Rename a library
Set the default save folder of a library
Set library properties such as Folder Type, Icon, and its Pinned To Navigation Pane state
Show the Shell "manage user interface" dialog
Setup
For convenience, much of the code you will be managing along this hands-on lab is available as Visual
Studio code snippets. The setup needed for this lab consist on installing these snippets. To do this:
1. Run the ShellLibrariesLab.vsi installer located under the lab's Setup folder.
2. Follow the wizard instructions to install the snippets.
System Requirements
You must have the following items to complete this lab:
Microsoft Visual Studio 2008
Windows 7
The Windows API Code Pack library
Note: For simplicity, you can find these assemblies under the Assets folder of this lab. If you
want to dig deeper in Windows API Code Pack library source code, just download it from the
link sited above.
http://code.msdn.microsoft.com/WindowsAPICodePack/Release/ProjectReleases.aspx?ReleaseId=2821
-
Shell Libraries Hands-On Lab
6
Exercise 1: Developing the SLUtil
The Shell Library Utility (SLUtil) is a command line tool that enables you to manage libraries under the
default library directory.
The SLUtil commands are:
Command Prompt
SLUtil Create LibraryName
SLUtil Delete LibraryName
SLUtil Rename OldName NewName
SLUtil AddFolder LibraryName FolderPath
SLUtil RemoveFolder LibraryName FolderPath
SLUtil ShowInfo [LibraryName]
SLUtil FolderType LibraryName [Documents|Pictures|Music|Videos]
SLUtil SaveFolder LibraryName [FolderPath]
SLUtil NavPanePinnedState LibraryName [TRUE|FALSE]
SLUtil Icon LibraryName [Icon]
SLUtil ManageUI Videos
SLUtil ? [CommandName]
Task 1 Creating the SLUtil Project
1. Start Visual Studio 2008 and select the Console Application project template, choosing the
language of your preference (Visual C# or Visual Basic). Enter SLUtil as the name of the new
project.
2. Add a reference to the Microsoft.WindowsApiCodePack.dll and
Microsoft.WindowsApiCodePack.shell.dll. You can find those assemblies under the Asset
folder of this lab.
3. (For C# users only) Also add references to the following assemblies:
PresentationCore
PresentationFramework
WindowsBase
System.Windows.Forms
4. Add the CommandLineInterpreter.cs (C#) or CommandLineInterpreter.vb (Visual Basic) file.
You can find it under Asset\SLUtil folder, choosing the language of your preference.
Note: The Command Line Interpreter is a utility class that knows how to interpret command
line arguments and execute static methods that include the CommandAttribute attribute.
-
Shell Libraries Hands-On Lab
7
5. To activate the Command Line Interpreter, change the Main method to this code:
(Code Snippet Shell Libraries Main CSharp)
C#
class Program
{
static int Main(string[] args)
{
CommandLineInterpreter cli = new CommandLineInterpreter(args);
return cli.Execute();
}
}
(Code Snippet Shell Libraries Main VB)
Visual Basic
Module Module1
Function Main() As Integer
Dim cli As New
CommandLineInterpreter(My.Application.CommandLineArgs.ToArray())
Return cli.Execute()
End Function
End Module
6. Compile the solution.
7. To test the current state of the application, add a command line argument in the Debug pane of
the project properties.
-
Shell Libraries Hands-On Lab
8
Figure 2
Adding a command line argument
8. Execute the application by pressing CTRL+F5. You should get the following output:
Command
SLUtil ? [CommandName]
Press any key to continue . . .
Task 2 Adding the Create Command
The Windows API Pack ShellLibrary managed wrapper has several constructors that let you create new
libraries:
C#
// Summary:
// Creates a shell library in the Libraries Known Folder,
// using the given IKnownFolder
//
// Parameters:
// kf: KnownFolder from which to create the new Shell Library
// isReadOnly:
public ShellLibrary(IKnownFolder kf, bool isReadOnly);
//
// Summary:
// Creates a shell library in the Libraries Known Folder,
// using the given shell library name.
//
// Parameters:
// libraryName: The name of this library
-
Shell Libraries Hands-On Lab
9
// overwrite: Override an existing library with the same name
public ShellLibrary(string libraryName, bool overwrite);
// Summary:
// Creates a shell library in a given Known Folder, using the given shell
// library name.
// Parameters:
// libraryName: The name of this library
// kf: The known folder
// overwrite: Override an existing library with the same name
public ShellLibrary(string libraryName, IKnownFolder kf, bool overwrite);
// Summary:
// Creates a shell library in a given local folder, using the given shell
// library name.
// Parameters:
// libraryName: The name of this library
// folderPath: The path to the local folder
// overwrite: Override an existing library with the same name
public ShellLibrary(string libraryName, string folderPath, bool overwrite);
Visual Basic
' Summary:
' Creates a shell library in the Libraries Known Folder,
' using the given IKnownFolder
'
' Parameters:
' kf: KnownFolder from which to create the new Shell Library
' isReadOnly:
Public Sub New(ByVal kf As Microsoft.WindowsAPICodePack.Shell.IKnownFolder, ByVal
isReadOnly As Boolean)
' Summary:
' Creates a shell library in the Libraries Known Folder,
' using the given shell library name.
'
' Parameters:
' libraryName: The name of this library
' overwrite: Override an existing library with the same name
Public Sub New(ByVal libraryName As String, ByVal overwrite As Boolean)
' Summary:
' Creates a shell library in a given Known Folder, using the given shell
' library name.
' Parameters:
' libraryName: The name of this library
' kf: The known folder
' overwrite: Override an existing library with the same name
-
Shell Libraries Hands-On Lab
10
Public Sub New(ByVal libraryName As String, ByVal kf As
Microsoft.WindowsAPICodePack.Shell.IKnownFolder, ByVal overwrite As Boolean)
' Summary:
' Creates a shell library in a given local folder, using the given shell
' library name.
' Parameters:
' libraryName: The name of this library
' folderPath: The path to the local folder
' overwrite: Override an existing library with the same name
Public Sub New(ByVal libraryName As String, ByVal folderPath As String, ByVal
overwrite As Boolean)
The ShellLibrary implements the IDispose interface. It is important to call the Dispose() function to free
the underlying Shell Library COM object. Utilization of the using statement facilitates that Dispose call.
The pattern to use a library object is:
C#
using (ShellLibrary library = new ShellLibray("Library Name", true))
{
//Use the library instance here
}
Visual Basic
Using library As New ShellLibray("Library Name", True)
'Use the lib instance here
End Using
1. Create a Static class (C#) or a module (Visual Basic) named ShellCommands.
2. Add the following namespace directive:
C#
using Microsoft.WindowsAPICodePack.Shell;
Visual Basic
Imports Microsoft.WindowsAPICodePack.Shell
3. Create a new Command named Create. To do this, add the following code to ShellCommands:
(Code Snippet Shell Libraries CreateCommand CSharp)
C#
[Command(
-
Shell Libraries Hands-On Lab
11
Name = "Create",
Usage = "SLUtil Create LibraryName",
Info = "Create a new library",
Example = "SLUtil Create MyLib")]
public static void CreateLibrary(string name)
{
using (ShellLibrary library = new ShellLibrary(name, true))
{
}
}
(Code Snippet Shell Libraries CreateCommand VB)
Visual Basic
_
Public Sub CreateLibrary(ByVal name As String)
Using library As New ShellLibrary(name, True)
End Using
End Sub
4. Compile the solution.
5. Change the command line argument to: Create MyLib
Figure 3
Modifying the command line arguments
6. Run the application by pressing CTRL+F5. Then open Windows Explorer to verify that you
created a new library.
-
Shell Libraries Hands-On Lab
12
Figure 4
Creating my first library via Shell API
Task 3 Adding the AddFolder and RemoveFolder Commands
1. To use an existing library, we need to create a ShellLibrary instance by loading that library. The
ShellLibrary provides two load methods:
C#
// Summary:
// Load the library using a number of options
// Parameters:
// sourceKnownFolder: the Knowfolder
// isReadOnly:
// Returns: A ShellLibrary Object
public static ShellLibrary Load(IKnownFolder sourceKnownFolder, bool
isReadOnly);
// Summary:
// Load the library using a number of options
// Returns: A ShellLibrary Object
public static ShellLibrary Load(string libraryName, bool isReadOnly);
// Summary:
// Load the library using a number of options
// Returns: A ShellLibrary Object
public static ShellLibrary Load(string libraryName, string folderPath,
bool isReadOnly);
Visual Basic
-
Shell Libraries Hands-On Lab
13
' Summary:
' Load the library using a number of options
' Parameters:
' sourceKnownFolder: the Knowfolder
' isReadOnly:
' Returns: A ShellLibrary Object
Public Shared Function Load(ByVal sourceKnownFolder As
Microsoft.WindowsAPICodePack.Shell.IKnownFolder, ByVal isReadOnly As Boolean)
As Microsoft.WindowsAPICodePack.Shell.ShellLibrary
' Summary:
' Load the library using a number of options
' Returns: A ShellLibrary Object
Public Shared Function Load(ByVal libraryName As String, ByVal isReadOnly As
Boolean) As Microsoft.WindowsAPICodePack.Shell.ShellLibrary
' Summary:
' Load the library using a number of options
' Returns: A ShellLibrary Object
Public Shared Function Load(ByVal libraryName As String, ByVal folderPath As
String, ByVal isReadOnly As Boolean) As
Microsoft.WindowsAPICodePack.Shell.ShellLibrary
2. To add or remove a folder, you need to use two of these methods:
C#
// Summary:
// Add a new FileSystemFolder or SearchConnector
public void Add(FileSystemFolder item);
//
// Summary:
// Add an existing folder to this library
public void Add(string folderPath);
// Summary:
// Remove a folder or search connector
public bool Remove(FileSystemFolder item);
//
// Summary:
// Remove a folder or search connector
public bool Remove(string folderPath);
Visual Basic
' Summary:
' Add a new FileSystemFolder or SearchConnector
Public Sub Add(ByVal item As FileSystemFolder)
'
-
Shell Libraries Hands-On Lab
14
' Summary:
' Add an existing folder to this library
Public Sub Add(ByVal folderPath As String)
' Summary:
' Remove a folder or search connector
Public Function Remove(ByVal item As FileSystemFolder) As Boolean
'
' Summary:
' Remove a folder or search connector
Public Function Remove(ByVal folderPath As String) As Boolean
3. Now that we know how to open (load) an existing library, and how to add and remove folders,
we can implement the AddFolder and RemoveFolder commands in our SLUtil application. Add
the following code to ShellCommands:
(Code Snippet Shell Libraries AddAndRemoveFolderCommands CSharp)
C#
[Command(
Name = "AddFolder",
Usage = "SLUtil AddFolder LibraryName FolderPath",
Info = "Add a folder to a library",
Example = @"SLUtil AddFolder Documents C:\Docs")]
public static void AddFolder(string name, string folderPath)
{
using (ShellLibrary library = ShellLibrary.Load(name, false))
{
library.Add(folderPath);
}
}
[Command(
Name = "RemoveFolder",
Usage = "SLUtil RemoveFolder LibraryName FolderPath",
Info = "Remove a folder from a library",
Example = @"SLUtil RemoveFolder Documents C:\Docs")]
public static void RemoveFolder(string name, string folderPath)
{
using (ShellLibrary library = ShellLibrary.Load(name, false))
{
library.Remove(folderPath);
}
}
(Code Snippet Shell Libraries AddAndRemoveFolderCommands VB)
-
Shell Libraries Hands-On Lab
15
Visual Basic
_
Public Sub AddFolder(ByVal name As String, ByVal folderPath As String)
Using library = ShellLibrary.Load(name, False)
library.Add(folderPath)
End Using
End Sub
_
Public Sub RemoveFolder(ByVal name As String, ByVal folderPath As String)
Using library = ShellLibrary.Load(name, False)
library.Remove(folderPath)
End Using
End Sub
4. Build the solution (CTRL+SHIFT+B), and follow these steps to verify the result:
a. Clear the command line arguments from the Debug pane of the project properties
pages.
b. Open a Command Prompt window and change the directory (cd) to the location of
the SLUtil.exe (\bin\debug\SLUtil.exe).
c. Open the Libraries Shell Folder next to the Command Prompt Window, so you will
be able to see the changes you make with the SLUtil tool.
-
Shell Libraries Hands-On Lab
16
Figure 5
Setting the environment to execute SLUtil.exe
d. Execute the SLUtil from command line:
Command Line
SLUtil ?
SLUtil Create NewLibrary
SLUtil AddFolder NewLibrary C:\Users
SLUtil RemoveFolder NewLibrary C:\Users
Note: Since the interpreter finds the best match command, you can use SLUtil Cr Lib
to create a library and SLUtil Add Lib C:\ to add a folder. Try it.
Task 4 Adding the Delete and Rename Commands
Deleting a library is not an operation of the IShellLibrary; it is a regular file system operation. However,
for the purpose of completeness we will implement it. Renaming can be achieved by copying the library
to a new library and deleting the old one. The ShellLibrary wrapper provides these methods:
C#
// Summary:
// Creates a copy of a ShellLibrary, using a new name and known folder
public static ShellLibrary Copy(ShellLibrary library, string name,
IKnownFolder destinationKnownFolder, bool
overrideExisting);
// Summary:
// Creates a copy of a ShellLibrary, using a new name and path
public static ShellLibrary Copy(ShellLibrary library, string name,
string path, bool overrideExisting);
Visual Basic
' Summary:
' Creates a copy of a ShellLibrary, using a new name and known folder
Public Shared Function Copy(ByVal library As ShellLibrary, ByVal name As String,
ByVal destinationKnownFolder As IKnownFolder, ByVal overrideExisting As Boolean) As
ShellLibrary
' Summary:
' Creates a copy of a ShellLibrary, using a new name and path
Public Shared Function Copy(ByVal library As ShellLibrary, ByVal name As String,
ByVal path As String, ByVal overrideExisting As Boolean) As ShellLibrary
-
Shell Libraries Hands-On Lab
17
1. Add the following namespace directive to ShellCommands.cs (C#) or ShellCommands.vb (Visual
Basic).
C#
using System.IO;
Visual Basic
Imports System.IO
2. Add the following code to ShellCommands:
(Code Snippet Shell Libraries DeleteAndRenameLibraryCommands CSharp)
C#
[Command(
Name = "Delete",
Usage = "SLUtil Delete LibraryName",
Info = "Delete a library",
Example = "SLUtil Delete MyLib")]
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);
}
[Command(
Name = "Rename",
Usage = "SLUtil Rename OldName NewName",
Info = "Rename a library",
Example = "SLUtil Rename MyLib MyLibNewName")]
public static void RenameLibrary(string oldName, string newName)
{
using (ShellLibrary library = ShellLibrary.Load(oldName, true))
{
ShellLibrary.Copy(library, newName, ShellLibrary.LibrariesKnownFolder,
false);
}
DeleteLibrary(oldName);
}
-
Shell Libraries Hands-On Lab
18
(Code Snippet Shell Libraries DeleteAndRenameLibraryCommands VB)
Visual Basic
_
Public Sub DeleteLibrary(ByVal name As String)
Dim librariesPath =
Path.Combine(Environment.GetFolderPath(Environment.SpecialFolder.ApplicationDa
ta), ShellLibrary.LibrariesKnownFolder.RelativePath)
Dim libraryPath = Path.Combine(librariesPath, name)
Dim libraryFullPath = Path.ChangeExtension(libraryPath, "library-ms")
File.Delete(libraryFullPath)
End Sub
_
Public Sub RenameLibrary(ByVal oldName As String, ByVal newName As String)
Using library = ShellLibrary.Load(oldName, True)
ShellLibrary.Copy(library, newName, ShellLibrary.LibrariesKnownFolder,
False)
End Using
DeleteLibrary(oldName)
End Sub
3. Build the solution (CTRL+SHIFT+B), and follow these steps to verify the result:
a. Open a Command Prompt window and change the directory (cd) to the location of the
SLUtil.exe (\bin\debug\SLUtil.exe).
b. Open the Libraries Shell Folder next to the Command Prompt Window, so you will be
able to see the changes you make with the SLUtil tool.
c. Test the SLUtil from command line:
Command Line
SLUtil.exe Rename MyLib MyLib2
Task 5 Adding SaveFolder, NavPanePinnedState, Icon, and FolderType Commands
These four commands share common behaviors. First, the user can use these commands to query the
state of the library by supplying just the Library name. Second, to implement these commands, the
Windows API exposes them in the ShellLibrary as properties.
C#
-
Shell Libraries Hands-On Lab
19
// Summary:
// By default, this folder is the first location added to the library.
// The default save folder is both the default folder where files can be
// saved, and also where the library XML file will be saved, if no other
// path is specified
public string DefaultSaveFolder { get; set; }
public IconReference IconResourceId { get; set; }
// Summary:
// Whether the library will be pinned to the Explorer Navigation Pane
public bool IsPinnedToNavigationPane { get; set; }
// Summary:
// One of predefined Library types
//
// Exceptions:
// System.Runtime.InteropServices.COMException:
// Will throw if no Library Type is set
public LibraryFolderType LibraryType { get; set; }
Visual Basic
' Summary:
' By default, this folder is the first location added to the library.
' The default save folder is both the default folder where files can be
' saved, and also where the library XML file will be saved, if no other
' path is specified
Public Property DefaultSaveFolder() As String
Public Property IconResourceId() As IconReference
' Summary:
' Whether the library will be pinned to the Explorer Navigation Pane
Public Property IsPinnedToNavigationPane() As Boolean
' Summary:
' One of predefined Library types
'
' Exceptions:
' System.Runtime.InteropServices.COMException:
' Will throw if no Library Type is set
Public Property LibraryType() As LibraryFolderType
1. Add the following code to ShellCommands:
a. SaveFolder -- Lets you query and set the current default save folder. Bear in mind that
this value may be empty if the folder list of the library is empty.
-
Shell Libraries Hands-On Lab
20
b. NavPanePinnedState -- Lets you query and set whether the library name will appear in
the Explorer navigation pane.
c. Icon -- Lets you query or set the icon resource name; this property may be empty.
d. FolderType -- Lets you query and set the Library shell folder template. This template tells
the Shell how to display the library window.
(Code Snippet Shell Libraries LibraryPropertiesCommands CSharp)
C#
[Command(
Name = "SaveFolder",
Usage = "SLUtil SaveFolder LibraryName [FolderPath]",
Info = "Set or get the library's save folder path",
Example = @"SLUtil SaveFolder Documents C:\Docs")]
public static void SaveFolder(string name, string folderPath)
{
bool isReadOperation = string.IsNullOrEmpty(folderPath);
using (ShellLibrary library = ShellLibrary.Load(name, isReadOperation))
{
if (isReadOperation)
{
Console.WriteLine("Save folder: {0}", library.DefaultSaveFolder);
}
else
{
library.DefaultSaveFolder = folderPath;
}
}
}
[Command(
Name = "NavPanePinnedState",
Usage = "SLUtil NavPanePinnedState LibraryName [TRUE|FALSE]",
Info = "Set or get the library's Pinned to navigation pane state",
Example = @"SLUtil NavPanePinnedState MyLib TRUE")]
public static void NavPanePinnedState(string name, string stateText)
{
bool isReadOperation = string.IsNullOrEmpty(stateText);
using (ShellLibrary library = ShellLibrary.Load(name, isReadOperation))
{
if (isReadOperation)
{
Console.WriteLine("The library {0} is{1}pinned to the" +
"navigation pane.",
name, library.IsPinnedToNavigationPane ? " " : " not ");
-
Shell Libraries Hands-On Lab
21
}
else
{
bool state = bool.Parse(stateText);
library.IsPinnedToNavigationPane = state;
}
}
}
[Command(
Name = "Icon",
Usage = "SLUtil Icon LibraryName [Icon]",
Info = "Set or get the library's icon",
Example = @"SLUtil Icon MyLib imageres.dll,-1005")]
public static void Icon(string name, string icon)
{
bool isReadOperation = string.IsNullOrEmpty(icon);
using (ShellLibrary library = ShellLibrary.Load(name, isReadOperation))
{
if (isReadOperation)
{
Console.WriteLine("Icon: {0}",
library.IconResourceId.ReferencePath);
}
else
{
library.IconResourceId = new IconReference(icon);
}
}
}
[Command(
Name = "FolderType",
Usage = "SLUtil FolderType LibraryName " +
"[Generic|Documents|Pictures|Music|Videos]",
Info = "Set or get the library's folder template",
Example = @"SLUtil FolderType MyLib Documents")]
public static void FolderType(string name, string folderType)
{
bool isReadOperation = string.IsNullOrEmpty(folderType);
using (ShellLibrary library = ShellLibrary.Load(name, isReadOperation))
{
if (isReadOperation)
{
Console.WriteLine("Folder type: {0}", library.LibraryType);
}
-
Shell Libraries Hands-On Lab
22
else
{
library.LibraryType =
(LibraryFolderType)Enum.Parse(typeof(LibraryFolderType), folderType);
}
}
}
(Code Snippet Shell Libraries LibraryPropertiesCommands VB)
Visual Basic
_
Public Sub SaveFolder(ByVal name As String, ByVal folderPath As String)
Dim isReadOperation = String.IsNullOrEmpty(folderPath)
Using library = ShellLibrary.Load(name, isReadOperation)
If isReadOperation Then
Console.WriteLine("Save folder: {0}", library.DefaultSaveFolder)
Else
library.DefaultSaveFolder = folderPath
End If
End Using
End Sub
_
Public Sub NavPanePinnedState(ByVal name As String, ByVal stateText As String)
Dim isReadOperation = String.IsNullOrEmpty(icon)
Using library = ShellLibrary.Load(name, isReadOperation)
If isReadOperation Then
Console.WriteLine("The library {0} is{1}pinned to the navigation
pane.", _
name, If(library.IsPinnedToNavigationPane, " ",
" not "))
Else
Dim state = CBool(stateText)
library.IsPinnedToNavigationPane = state
End If
End Using
End Sub
_
-
Shell Libraries Hands-On Lab
23
Public Sub Icon(ByVal name As String, ByVal icon As String)
Dim isReadOperation As Boolean = String.IsNullOrEmpty(icon)
Using library = ShellLibrary.Load(name, isReadOperation)
If isReadOperation Then
Console.WriteLine("Icon: {0}",
library.IconResourceId.ReferencePath)
Else
library.IconResourceId = New IconReference(icon)
End If
End Using
End Sub
_
Public Sub FolderType(ByVal name As String, ByVal folderType As String)
Dim isReadOperation = String.IsNullOrEmpty(folderType)
Using library = ShellLibrary.Load(name, isReadOperation)
If isReadOperation Then
Console.WriteLine("Folder type: {0}", library.LibraryType)
Else
library.LibraryType =
CType(System.Enum.Parse(GetType(LibraryFolderType), folderType),
LibraryFolderType)
End If
End Using
End Sub
2. Build the solution (CTRL+SHIFT+B), and follow these steps to verify the result:
a. Open a Command Prompt window and change the directory (cd) to the location of the
SLUtil.exe (\bin\debug\SLUtil.exe).
b. Open the Libraries Shell Folder next to the Command Prompt Window, so you will be
able to see the changes you make with the SLUtil tool.
c. Test the SLUtil from the command line:
Command Line
SLUtil.exe SaveFolder Documents
SLUtil.exe NavPanePinnedState NewLibrary TRUE
SLUtil.exe Icon NewLibrary imageres.dll,-1005
SLUtil.exe FolderType NewLibrary Documents
-
Shell Libraries Hands-On Lab
24
Figure 6
New Library settings changed
Task 6 Adding the ShowInfo Command
The ShowInfo command displays everything about a Library. If ShowInfo receives no input parameters,
it shows the information of all the libraries under the main library folder. In the previous task, you
learned how to use ShellLibrary properties to get information about the library's state. With the
ShowInfo command, we also need to know how to get the librarys folder list. The Windows API Pack
ShellLibrary is a ShellContainer, hence implementing the IList (C#) or IList(Of
FileSystemFolder) (Visual Basic). You can iterate through all the folders in the library using regular
iterator.
1. Add the following code to ShellCommands:
(Code Snippet Shell Libraries ShowInfoCommand CSharp)
C#
[Command(
Name = "ShowInfo",
Usage = "SLUtil ShowInfo [LibraryName]",
Info = "Show Library information. If the LibraryName parameter is" +
"missing, show information of all libraries under the Libraries folder",
Example = @"SLUtil ShowInfo Documents")]
public static void ShowInfo(string name)
{
if (string.IsNullOrEmpty(name))
{
foreach (ShellObject shellObject in ShellLibrary.LibrariesKnownFolder)
-
Shell Libraries Hands-On Lab
25
{
ShellLibrary shellLibrary = shellObject as ShellLibrary;
if (shellLibrary == null)
continue;
try //try to get the maximum information
{
ShowInformation(shellLibrary);
}
catch (Exception ex)
{
System.Diagnostics.Trace.WriteLine("Error: " + ex.Message);
}
shellLibrary.Dispose();
}
}
else
{
using (ShellLibrary library = ShellLibrary.Load(name, true))
{
ShowInformation(library);
}
}
}
private static void ShowInformation(ShellLibrary library)
{
string defaultSaveFolder = string.Empty;
Console.WriteLine("\nShowing information of {0} library", library.Name);
Console.WriteLine("\tIs pinned to navigation pane: {0}",
library.IsPinnedToNavigationPane);
try
{
defaultSaveFolder = library.DefaultSaveFolder;
}
catch
{
}
Console.WriteLine("\tSave folder: {0}", defaultSaveFolder);
try
{
Console.WriteLine("\tIcon: {0}", library.IconResourceId.ReferencePath);
}
catch
{
-
Shell Libraries Hands-On Lab
26
}
try
{
Console.WriteLine("\tFolder type: {0}", library.LibraryType);
}
catch
{
}
Console.WriteLine("\tFolder list:");
foreach (ShellFolder folder in library)
{
Console.WriteLine("\t\t{0} {1}", folder.Name, defaultSaveFolder ==
folder.Name ? "*" : "");
}
}
(Code Snippet Shell Libraries ShowInfoCommand VB)
Visual Basic
_
Public Sub ShowInfo(ByVal name As String)
If String.IsNullOrEmpty(name) Then
For Each shellObject In shellLibrary.LibrariesKnownFolder
Dim shellLibrary = TryCast(shellObject, ShellLibrary)
If shellLibrary Is Nothing Then Continue For
Try 'try to get the maximum information
ShowInformation(shellLibrary)
Catch ex As Exception
System.Diagnostics.Trace.WriteLine("Error: " & ex.Message)
End Try
shellLibrary.Dispose()
Next shellObject
Else
Using library = ShellLibrary.Load(name, True)
ShowInformation(library)
End Using
End If
End Sub
Private Sub ShowInformation(ByVal library As ShellLibrary)
-
Shell Libraries Hands-On Lab
27
Dim defaultSaveFolder = String.Empty
Console.WriteLine(Constants.vbLf & "Showing information of {0} library",
library.Name)
Console.WriteLine(Constants.vbTab & "Is pinned to navigation pane: {0}",
library.IsPinnedToNavigationPane)
Try
defaultSaveFolder = library.DefaultSaveFolder
Catch
End Try
Console.WriteLine(Constants.vbTab & "Save folder: {0}", defaultSaveFolder)
Try
Console.WriteLine(Constants.vbTab & "Icon: {0}",
library.IconResourceId.ReferencePath)
Catch
End Try
Try
Console.WriteLine(Constants.vbTab & "Folder type: {0}",
library.LibraryType)
Catch
End Try
Console.WriteLine(Constants.vbTab & "Folder list:")
For Each folder In library
Console.WriteLine(Constants.vbTab & Constants.vbTab & "{0} {1}",
folder.Name, If(defaultSaveFolder = folder.Name, "*", ""))
Next folder
End Sub
2. Build the solution (CTRL+SHIFT+B), and follow these steps to verify the result:
a. Open a Command Prompt window to change the directory (cd) to the location of the
SLUtil.exe (\bin\debug\SLUtil.exe).
b. Open the Libraries Shell Folder next to the Command Prompt Window, so you will be
able to see the changes you make with the SLUtil tool.
c. Test the SLUtil from the command line:
Command Line
SLUtil.exe ShowInfo
-
Shell Libraries Hands-On Lab
28
Figure 7
Using the ShowInfo command
Task 7 Adding the ManageUI Command
The final command that complete the SLUtil, is the ManageUI command. This command shows the
librarys shell management window:
Figure 8
Library's shell management window
C#
-
Shell Libraries Hands-On Lab
29
// Summary:
// Shows the library management dialog which enables users to mange
// the library folders and default save location.
//
// Parameters:
// windowHandle:
// The parent window,or IntPtr.Zero for no parent
//
// title:
// A title for the library management dialog, or null to use the library
// name as the title
//
// instruction:
// An optional help string to display for the library management dialog
//
// allowAllLocations:
// If true, do not show warning dialogs about locations that cannot be
// indexed
//
// Returns:
// true if the user cliked O.K, false if the user clicked Cancel
public bool ShowManageLibraryUI(IntPtr windowHandle, string title,
string instruction, bool allowAllLocations);
//
// Summary:
// Shows the library management dialog which enables users to mange the
// library folders and default save location.
//
// Parameters:
// form:
// A windows form (WinForm)
//
// title:
// A title for the library management dialog, or null to use the library
// name as the title
//
// instruction:
// An optional help string to display for the library management dialog
//
// allowAllLocations:
// If true, do not show warning dialogs about locations that cannot be
// indexed
//
// Returns:
// true if the user cliked O.K, false if the user clicked Cancel
public bool ShowManageLibraryUI(System.Windows.Forms.Form form, string title,
string instruction, bool allowAllLocations);
//
-
Shell Libraries Hands-On Lab
30
// Summary:
// Shows the library management dialog which enables users to mange the
// library folders and default save location.
//
// Parameters:
// mainWindow:
// The parent window for a WPF app
//
// title:
// A title for the library management dialog, or null to use the library
// name as the title
//
// instruction:
// An optional help string to display for the library management dialog
//
// allowAllLocations:
// If true, do not show warning dialogs about locations that cannot be
// indexed
//
// Returns:
// true if the user cliked O.K, false if the user clicked Cancel
public bool ShowManageLibraryUI(System.Windows.Window mainWindow,
string title, string instruction, bool allowAllLocations);
Visual Basic
' Summary:
' Shows the library management dialog which enables users to mange
' the library folders and default save location.
'
' Parameters:
' windowHandle:
' The parent window,or IntPtr.Zero for no parent
'
' title:
' A title for the library management dialog, or null to use the library
' name as the title
'
' instruction:
' An optional help string to display for the library management dialog
'
' allowAllLocations:
' If true, do not show warning dialogs about locations that cannot be
' indexed
'
' Returns:
' true if the user cliked O.K, false if the user clicked Cancel
-
Shell Libraries Hands-On Lab
31
Public Function ShowManageLibraryUI(ByVal windowHandle As System.IntPtr, ByVal title
As String, ByVal instruction As String, ByVal allowAllLocations As Boolean) As
Boolean
'
' Summary:
' Shows the library management dialog which enables users to mange the
' library folders and default save location.
'
' Parameters:
' form:
' A windows form (WinForm)
'
' title:
' A title for the library management dialog, or null to use the library
' name as the title
'
' instruction:
' An optional help string to display for the library management dialog
'
' allowAllLocations:
' If true, do not show warning dialogs about locations that cannot be
' indexed
'
' Returns:
' true if the user cliked O.K, false if the user clicked Cancel
Public Function ShowManageLibraryUI(ByVal form As Form, ByVal title As String, ByVal
instruction As String, ByVal allowAllLocations As Boolean) As Boolean
'
' Summary:
' Shows the library management dialog which enables users to mange the
' library folders and default save location.
'
' Parameters:
' mainWindow:
' The parent window for a WPF app
'
' title:
' A title for the library management dialog, or null to use the library
' name as the title
'
' instruction:
' An optional help string to display for the library management dialog
'
' allowAllLocations:
' If true, do not show warning dialogs about locations that cannot be
' indexed
'
' Returns:
-
Shell Libraries Hands-On Lab
32
' true if the user cliked O.K, false if the user clicked Cancel
Public Function ShowManageLibraryUI(ByVal mainWindow As Window, ByVal title As
String, ByVal instruction As String, ByVal allowAllLocations As Boolean) As Boolean
1. Add the following code to ShellCommands:
(Code Snippet Shell Libraries ManageUICommand CSharp)
C#
[Command(
Name = "ManageUI",
Usage = "SLUtil ManageUI LibraryName",
Info = "Show the Shell Library management UI",
Example = @"SLUtil ManageUI Documents")]
public static void ManageUI(string name)
{
using (ShellLibrary library = ShellLibrary.Load(name, false))
{
library.ShowManageLibraryUI(IntPtr.Zero, "SLUtil", "Manage Library",
true);
}
}
(Code Snippet Shell Libraries ManageUICommand VB)
Visual Basic
_
Public Sub ManageUI(ByVal name As String)
Using library = ShellLibrary.Load(name, False)
library.ShowManageLibraryUI(IntPtr.Zero, "SLUtil", "Manage Library",
True)
End Using
End Sub
2. Build the solution (CTRL+SHIFT+B), and follow these steps to verify the result:
a. Open a Command Prompt window to change the directory (cd) to the location of the
SLUtil.exe (\bin\debug\SLUtil.exe).
b. Test the SLUtil from the command line:
Command Line
SLUtil.exe ManageUI Documents
-
Shell Libraries Hands-On Lab
33
Summary
In this lab, you used the ShellLibrary managed wrapper to manage the Windows Shell libraries under the
default Libraries directory. We encourage you to review the LibraryManagerDemo, which is part of the
Windows 7 Taskbar and Libraries .NET Interop Sample Library, to learn more about libraries and how to
use them.
http://code.msdn.microsoft.com/Windows7Taskbar