Extend Setup, Quick Status, and Help

  • Article

 

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

You can use the procedures in this section to add tasks to the Setup Tasks list, the Quick Status tasks list, and the Help links in the home page of the Dashboard. Generally speaking, a Setup task is defined as a general task you may want your user to perform during setup. A Quick Status task is a task designed to give a quick response to a simple, common query. A Help link is a link to a community or company site that contains information for debugging or finding solutions to common problems.

Note

In Windows Server Essentials 2012, these features were known as the Common Tasks and Community links, and have been reorganized on the Dashboard for Windows Server Essentials 2012 R2.

You can add tasks to the Setup and Quick Status list, and you can add links to the Help section, by using XML to define the tasks and links. You may optionally create an embedded resource file and associated assembly, and install the files on the server. If the XML file is being installed on the server without a resource file, it must have a .home extension. If an assembly is being used to install both an XML file and a resource file, the .dll file must contain both the .home file and the .home.resx file.

You can use a text editor such as Notepad to create the .home 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.

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

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

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

  4. Delete the Class1.cs file.

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

  6. In the Templates pane, click XML File, type HomePageContent.home in the Name box, and then click Add.

  7. Add the following XML code to the HomePageContent.home file:

    <Tasks>  
   <CommonTasks>  
      <Task name="My Common Task"  
         description="My Common Task Description"  
         id="GUID"  
         image="Image Name"  
         type="Task Type"  
         exelocation="Application Location" />  
   </CommonTasks>  
   <Links>  
      <Link  
         Title="Displayed text of the link"  
         Description="A very short description"  
         ShellExecPath="Path to the application or URL"/>  
   </Links>  
   <GetQuickStatusTasks>  
      <Task name="My Quick Status Task"  
         description="My Quick Status Description"  
         id="QUID"  
         assembly="Assembly Name"   
         class="Class Name" />  
   </GetQuickStatusTasks>  

</Tasks>

    where:

    Attribute Description
    task name The name that is displayed for the task in the list. If you create an embedded resource file, the value of this attribute is the string resource.
    description The description of the task. If you create an embedded resource file, the value of this attribute is the string resource.
    id The identifier of the task. This identifier must be a GUID. You create a new GUID for an exe task, but for a global task, you use the GUID that you created when you defined the task for the task pane of the sub-tab. For more information about creating a GUID, see Create Guid (guidgen.exe) (https://go.microsoft.com/fwlink/?LinkId=116098).
    image When using an embedded resource file, this attribute defines the resource identifier for the image; otherwise, the value is the full path to the 16 X 16 .png image that is displayed for the task.
    type The type of task. The task can be either a global task or an exe task. A global task is the same global task that you created when defining the tasks for the task pane in the sub-tab. An exe task can be used to run applications from the Common Tasks list.
    exelocation The path to the application that is associated with the task. This attribute is only used for exe tasks.
    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. Note: Environment variables are supported in the ShellExecPath attribute.
    assembly The name of the assembly.
    class The name of the class.

    The following code example shows how to define a link to an application:

    <Links>  
   <Link Title="Calc" Description="Launches Calc" ShellExecPath="%windir%\system32\calc.exe" />  
</Links>

    The following code example shows how to define a link to a Web page:

    <Links>  
   <Link Title="Browser" Description="Open browser" ShellExecPath="http://www.adventureworks.com/" />  
</Links>

    The following code example shows how to define a quick status link:

    <GetQuickStatusTasks>  
   <Task name="Synchronous Quick Status" description="Demo to show query status synchronously." id="FE8FB8CD-C7AA-4798-839C-A3D82985C0F5" assembly="SyncQuickStatus" class="WSSHomepageQuickStatus.SyncQuickStatus" />

  8. Change the attribute values to represent your task or link.

  9. Save the HomePageContent.home file.

(Optional) Create the Quick Status assembly

If you want to create a task associated with the Quick Status list, you can use the classes in Microsoft.WindowsServerSolutions.Dashboard.Addins.Home, such as TaskQuickStatus, to create small assemblies that can quickly query and return information to the Dashboard.

To create a Quick Status task

  1. Use the TaskQuickStatus class to define a synchronized quick status task. The Mark member is designed to allow you to display a simple piece of information, such as the status of an internal database field. The following code describes how to define the UI elements of the Quick Status list, and uses the Mark member to display the current date and time. Note this sample code uses a resource file, as described in the procedure below.

    protected override TaskQuickStatus QueryTaskStatus()  
{  
      return new TaskQuickStatus(){  

   Title = Resources.SyncStatusTitle,  
         Details = Resources.SyncStatusDetails,  
         Mark = DateTime.Now.ToString(CultureInfo.CurrentUICulture),  
   StatusTips = String.Empty  
   };  
      }

  2. You can use other members of the Microsoft.WindowsServerSolutions.Dashboard.Addins.Home namespace to create asynchronous calls. For more information, see the WssHomepageQuickStatus sample in the …\Windows Server 2012 Essentials\samples\Dashboard\ directory.

(Optional) Create the resource file

If you want to localize the text in the tasks that you add to Common Tasks and the links that you add to Community Links, you must create an assembly that contains the .home file and a .home.resx file that defines the text strings.

To create the resource file

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

  2. In the Templates pane, click Resources File, type HomePageContent.home.resx in the Name box, and then click Add.

    Note

    The resource file can be given any name as long as it has a .home.resx extension.

  3. For each task or link that you add, you must add strings and values to the HomePageContent.home.resx file that match the Task and Link elements that are defined in the HomePageContent.home file. The following code example shows an XML file that is structured for the resource file:

    <Tasks>  
   <CommonTasks>  
      <Task name="CommonTask"  
         description="CommonTaskDescription"  
         id="GUID"  
         image="CommonImageName"  
         type="Task Type"  
         exelocation="Application Location"  
   </CommonTasks>     
   <Links>  
      <Link  
         Title="LinkTitle"  
         Description="LinkDescription"  
         ShellExecPath="Path to the application or URL"/>  
   </Links>  
</Tasks>

    Note

    Identifiers in attributes that are used for localization cannot contain spaces.

  4. Add the CommonTask, CommonTaskDescription, CommonImageName, LinkTitle, and LinkDescription resource names to the .home.resx file with the appropriate values.

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

  6. Save the HomePageContent.home.resx file, and then build the solution.

Install the task files

After you create the .home and .home.resx files, you must install them on the server.

To install the task files

  1. Ensure that your solution builds without errors.

  2. If you did not create an embedded resource file, copy the HomePageContent.home file to %ProgramFiles%\Windows Server\Bin\Addins\Home on the server. If you created an embedded resource file, copy the HomePageContent.dll file to %ProgramFiles%\Windows Server\Bin\Addins\Home on the server.

  3. If you created an assembly, you may install it as you would any other Windows Server Essentials add-in assembly. However, it is recommended that you install the assembly under the windows\system32\essentials\ directory. For more information, see Creating and Deploying an Add-In Package.