Extend Wizards and Property Pages

 

Applies To: Windows Server 2012 Essentials, Windows Home Server 2011, Windows Storage Server 2008 R2 Essentials, Windows Small Business Server 2011 Essentials

You can add links to the Add User Wizard, User Property page, and Add a Shared Folder Wizard. Links are added by using an XML file with a specific extension or by using an embedded resource file with a .dll extension. The files are placed in one of the following locations:

• For the Add User Wizard and User Property page:

  %ProgramFiles%\Windows Server\Bin\Addins\Users

• For the Add a Shared Folder Wizard:

  %ProgramFiles%\Windows Server\Bin\Addins\Storage

Note

The link that is added to the wizards is displayed on the last page.

The following table lists the attributes that define the link.

Attribute	Description
Image	The path to the 16 X 16 .png image that is displayed for the link. If you create an embedded resource file, the value of this attribute is the string resource.
Title	The text that is displayed for the link. If you create an embedded resource file, the value of this attribute is the string resource.
Description	The description of the link destination. If you create an embedded resource file, the value of this attribute is the string resource.
ShellExecPath	The path to the application or the URL. Environment variables are supported in this attribute value.
ArgumentFormatString	Enables add-ins to pass a context string to the link, such as an LDAP path, so that when ShellExecPath is executed, it contains a string with your ArgumentFormatString and the {0} value replaced with the context specified by the add-in.

You can use a text editor such as Notepad to create the .wizlink or .proplink file, or if you are also creating an embedded resource file you can use Visual Studio 2010 to define the files. The following procedure shows how to use Visual Studio 2010 to create the files.

To define the links

1. Open Visual Studio 2010 as an administrator by right-clicking the program in the Start menu and selecting Run as administrator.

   Note

   You can also complete this procedure by using a text editor, such as Notepad.

2. Click File, click New, and then click Project.

3. In the Templates pane, click Class Library, type CustomLinksAddUserWizard in the Name box, and then click OK.

4. Delete the Class1.cs file.

5. Right-click the CustomLinksAddUserWizard project, click Add, and then click New Item.

6. In the Templates pane, click XML File, type CustomLinksAddUserWizard.wizlink in the Name box, and then click Add. You can provide any name, but the file must have a .wizlink extension. If you were creating links for the property page, you would provide a name with a .proplink extension.

7. Add the following XML code:

   <Links>  
      <Link   
         Title="Displayed text of the link"   
         Description="A very short description"   
         Image="Path to your 16x16 image"  
         ShellExecPath="Path to the application or url"  
         ArgumentFormatString="/yourContextParam:’{0}’" />  
   </Links>  
   

   Note

   Environment variables are supported in the ShellExecPath and Image attributes.

   Change the attribute values for your link.

8. Save the file.

If you want to localize the text in the links that you add, you must create an embedded resource file that contains the .wizlink or .proplink files and contains a .resx file that defines the text strings.

(Optional) To create the resource file

1. Right-click the CustomLinksAddUserWizard project, click Add, and then click New Item.

2. In the Templates pane, click Resources File, type CustomLinksAddUserWizard.wizlink.resx in the Name box, and then click Add. You can provide any name, but the file must have a .wizlink.resx extension. If you are creating a .resx file for a property page, the name must have a .proplink.resx extension.

3. For each link that you add, you must add strings and values to the CustomLinksAddUserWizard.wizlink.resx file that match the title, description, and image for the Link elements that are defined in the CustomLinksAddUserWizard.wizlink file. The following code example shows the changes that are made in the XML to support the resource file:

   <Links>  
      <Link   
         Title="LinkTitle"   
         Description="LinkDescription"   
         Image="LinkImage"  
         ShellExecPath="Path to the application or url"  
         ArgumentFormatString="/yourContextParam:’{0}’" />  
   </Links>  
   

   Note

   When referring to resource strings, the title, description, and image attributes cannot contain spaces.

4. Add the LinkTitle, LinkDescription, and LinkImage resource names to the .resx file with the appropriate string values.

5. In Solution Explorer, right-click CustomLinksAddUserWizard.wizlink, and then click Properties. In the Properties pane, under Build Action, select Embedded Resource.

6. Save the CustomLinksAddUserWizard.wizlink.resx file, and then build the solution.

Install the files

1. Ensure that your solution builds without errors.

2. If you did not create an embedded resource file, copy the CustomLinksAddUserWizard.wizlink file to %ProgramFiles%\Windows Server\Bin\Addins\Users on the server. If you created an embedded resource file, copy the CustomLinksAddUserWizard.dll file to %ProgramFiles%\Windows Server\Bin\Addins\Users on the server. If you created links for the User Property page, you would copy the files to the same location. If you created links for the Add a Shared Folder Wizard, you would copy the files to %ProgramFiles%\Windows Server\Bin\Addins\Storage.

Examples

You can create an executable file that can be called from the link. For example, you can provision e-mail accounts by extending the Add User Wizard or you can change the e-mail configuration for accounts by using the User property page. To do this, you create an executable, which takes the unique identifier for the user account (user name) as a parameter, for example, ConfigureEmailForUser.exe /UserName: <user name>. This executable contains the logic to perform the necessary steps to provision the e-mail account for the specified user account. The following code example shows how to define the link:

  
<Links>  
   <Link  
      Title="Configure an e-mail account"  
      Description="Provision an e-mail account for the user"  
      Image="ConfigureEmail.PNG"  
      ShellExecPath="%programfiles%\EmailProvisioning\ConfigureEmailForUser.exe"  
      ArgumentFormatString="/UserName:’{0}’" />  
</Links>  

You can perform the same type of operation with the Add a Shared Folder Wizard. The ID parameter is used in the ArgumentFormatString to obtain the identifier of the last shared folder that was created. The following code example shows how to define the link for the Add a Shared Folder Wizard:

  
<Links>  
  <Link  
    Title="Configure a shared folder"  
    Description="Configure the shared folder for the user"  
    Image="%ProgramFiles%\Windows Server\Bin\Addins\Storage\configicon.ico"  
    ShellExecPath="%ProgramFiles%\Utilities\Bin\ConfigureStorage.exe"  
    ArgumentFormatString="Id:{0}"/>  
</Links>  

The following example shows two tasks that will be added to the Add User Wizard and the User property page. The first link shows how to open the Calc program. The second link shows how to open a browser that points to a specific URL:

  
<Links>  
   <Link Title="Calc" Description="Launches Calc" Image="" ShellExecPath="%windir%\system32\calc.exe" />  
  
   <Link Title="Browser" Description="Opens browser" Image="c:\Windows_update_icon.png" ShellExecPath="http://www.adentureworks.com/" />  
</Links>