Share via

Understanding the Windows Server Essentials SDK

  • Article

 

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

The Windows Server Essentials Software Development Kit (SDK) helps you understand the concepts of creating add-ins that extend the functionality of features in Windows Server 2012 R2 Essentials. These features are also included in the Windows Server Essentials role in Windows Server 2012 R2.

Target Platforms for the Windows Server Essentials SDK

The Windows Server 2012 R2 Essentials SDK targets two platforms: the stand-alone Windows Server 2012 R2 Essentials, and the Windows Server Essentials Experience role in Windows Server 2012 R2.

  1. Windows 2012 R2 Essentials is built upon both on-premises and online technologies to deliver a best-in-class solution for small businesses. Out of the box, Windows 2012 R2 Essentials provides small businesses with simple file sharing, remote access, and an end-to-end view of the health of the network. Windows 2012 R2 Essentials also contains application add-in management and a product-wide extensibility model so that new services, such as e-mail, collaboration, and communication can be seamlessly and easily added to the solution.

  2. Windows Server Essentials Experience is a role built into Windows Server 2012 R2. The Windows Server Essentials role allows you to create a server that duplicates all of the functionality of Windows 2012 R2 Essentials. Generally, this role is used by a 3rd party hosting service to lease out a virtual server to a small business customer, who needs only one server for their entire business.

Windows Server Essentials SDK

The SDK provides the following content:

  • How-to information that helps you understand how to build add-ins

  • Templates that provide a strong base for building add-ins

  • Samples that provide examples of complete add-ins, including an end-to-end sample that demonstrates how all of the extensible features of the servers can be connected

  • API references that help you understand how to use the elements to extend and manage Windows Server 2012 Essentials

The Windows Server Essentials 2012R2 SDK is not a single downloadable package. Instead, it exists as a set of downloadable code samples and add-ins for Visual Studio, the documentation you are currently reading, as well as several assemblies on your system. For more information, see the relevant setup documentation, such as the “Setting up a Development Environment” task in Creating a Provider.

Initialization and the GAC (Global Asembly Cache)

Some assemblies in previous versions, as well as potentially some dependencies of the SDK assemblies, are not put in the GAC. This can cause a problem for applications that are running in directories other than the directory that the assemblies are running in.

To solve this issue, an application must initialize the Windows Server Essentials environment. This will allow the application to correctly resolve any dependencies on non-GACed assemblies. The call to do this is as follows.

Microsoft.WindowsServerSolutions.Common.WindowsServerSolutionsEnvironment.Initialize();

This call must be made before any other calls into Windows Server Essentials SDK binaries are made. Additionally, it must be made in a method that does not, itself, call into other Windows Server Essentials SDK assemblies. If your initialization routine also initializes other Windows Server Essentials SDK components, move their initialization into a separate method. For example:

public void Initialize()  
{  
  WindowsServerSolutionsEnvironment.Initialize();  
  OtherInitialization();  
}  
  
private void OtherInitialization()  
{  
  NetworkHealthEngine engine = new NetworkHealthEngine();  
}

Extending features

The following table lists the features can be extended by using the concepts described in the SDK:

Feature Description
Dashboard The Dashboard has been known by other names, such as “Console,” but for Windows Server Essentials, the Dashboard is a common user interface that is used to manage information. You can add top-level tabs and sub-tabs to the Dashboard. Each sub-tab can provide list, detail, and task information, or can provide custom control content. Creating a Dashboard Add-In shows you how to create your own top-level tabs and sub-tabs and to extend existing tabs in the Dashboard. Note: Top-level tabs and sub-tabs can be bound to and display data from an Object Model. You can define an Object Model by creating a provider.

The following namespaces under the Windows Server Essentials API Reference provide API details:

- Microsoft.WindowsServerSolutions.Administration.ObjectModel
- Microsoft.WindowsServerSolutions.Administration.ObjectModel.Adorners
- Microsoft.WindowsServerSolutions.Administration.ObjectModel.ComponentServices
Remote Web Access You can use a web browser to remotely access the files. Creating a Remote Web Access Add-In shows you how to create an add-in that can extend the home page of Remote Web Access in the following ways:

- Creating a new link in the Online Services section of the home page
- Creating a new item in the menu bar at the top of the home page
- Creating a new gadget for the home page
- Creating a new content page that can be accessed from the home page
- Creating a mobile version of a content page
- Adding navigational elements to a content page

The following namespaces under Windows Server Essentials API Reference provide API details:

- Microsoft.WindowsServerSolutions.Web
- Microsoft.WindowsServerSolutions.Web.Controls
- Microsoft.WindowsServerSolutions.Web.Extensibility
- Microsoft.WindowsServerSolutions.Web.Security
- Microsoft.WindowsServerSolutions.Web.Storage
- [Microsoft.WindowsServerSolutions.WebApi.Management Namespace](assetId:///Microsoft.WindowsServerSolutions.WebApi.Management Namespace?qualifyHint=False&autoUpgrade=True)
Launchpad You can add custom entries to the Launchpad on client computers. The Launchpad is an application that displays a list of tasks that are organized in categories. You can extend the functionality of the Launchpad by adding your own tasks and categories. A task is represented by a Web page or an application. A category represents a collection of related tasks. A category button on the Launchpad displays an arrow that indicates the presence of tasks in the category. Creating a Launchpad Add-In shows you how to create an add-in that adds an entry on the Launchpad.
System Health You can add definitions for alerts, health checks, and repairs for problems. A health add-in contains XML files that annotate code or data that is used to evaluate health information for a specific feature. The code that is included in a health add-in can be a PowerShell script or managed code.Creating a Health Add-In shows you how to create your own health definitions that can generate alerts, check for specific health conditions, and provide repair actions for problems.

The following namespaces under Windows Server Essentials API Reference provide API details:

- Microsoft.WindowsServerSolutions.NetworkHealth.AlertFramework
- Microsoft.WindowsServerSolutions.NetworkHealth.Engine
- Microsoft.WindowsServerSolutions.NetworkHealth.RealTime
Provider Framework The Provider Framework is the “engine” behind the products and it is the layer that performs business logic tasks. By creating providers that work with the Provider Framework, you can manage both on-premises workloads and online workloads. The Provider Framework provides the flexibility that you need when you integrate workloads and features into the product. The Provider Framework also provides the layer that supports features with workload management, communication, and the discovery of interfaces. Creating a Provider shows you how to create your own provider and the associated components that can use the operations of the Provider Framework.

The following namespaces under Windows Server Essentials API Reference provide API details:

- Microsoft.WindowsServerSolutions.Common.ProviderFramework
- Microsoft.WindowsServerSolutions.Common.ProviderFramework.Notifications
- Microsoft.WindowsServerSolutions.Common.ProviderFramework.public
- Microsoft.WindowsServerSolutions.Settings

Managing features

You can manage features by using a set of API elements that are included in the SDK. The following namespaces can be used to manage features:

Feature Description
Users See the following namespaces under the Windows Server Essentials API reference section for API details:

- Microsoft.WindowsServerSolutions.Users
Storage (hard drives and folders) See the following namespaces under the Windows Server Essentials API reference section for API details:

- Microsoft.WindowsServerSolutions.Storage
Computers See the following namespaces under the Windows Server Essentials API reference section for API details:

- Microsoft.WindowsServerSolutions.Devices.Identity
Groups See the following namespaces under the Windows Server Essentials API Reference for API details:

- Microsoft.WindowsServerSolutions.Groups
Azure Active Directory See the following namespaces under the Windows Server Essentials API reference section for API details:

- Microsoft.WindowsServerSolutions.AzureADIntegration

Creating and deploying an add-in package

After you build your add in, you can package it, so that the operating system will recognize its file name extension and content, which enables the add-in to be deployed. To distribute your add-in, you must create an add-in package that is a cabinet (CAB) file, which contains Windows Installer packages, an Addin.xml file for metadata, and an optional .rtf or text file for an End-User License Agreement. The CAB file must use a .wssx extension. For more information about packaging an add-in, see Creating and Deploying an Add-In Package.

Connecting extensible features

The following steps describe how the extensible features work together to manage user information:

  • In the Dashboard, an add-in is used to display user data and tasks in a Users tab. The add-in does not provide business logic or state information, but it does enable the administrator to manage the Users feature through a user interface.

  • The Dashboard add-in communicates with the object model of the Users Provider. The object model in the provider layer enables the Users feature to be managed by using or not using a user interface. The Users feature can be managed directly by using API elements.

  • The object model makes communication with the Users Provider easier. For example, requests through the object model can initiate communication with Active Directory Domain Services or other services to provision and manage users on the native sub-system. The provider can also communicate with online services and can communicate with other providers that contain user specific data for a specific workload or application.

  • A user alerts file is created that lists the events or alerts that the Alerts Provider will identify. The Alerts Provider uses this information to raise user specific alerts if they are encountered on the system.

Using templates and samples

To help you develop an add-in, templates are provided for the following features:

  • Dashboard

  • Health and alerts

  • Provider Framework

  • Remote Web Access

  • Web API

To help you understand how to develop an add-in, code examples are provided in the how-to sections and stand-alone samples that use the provided templates are provided. Samples are provided for the following features:

  • Dashboard and Dashboard Homepage

  • Dashboard home page

  • Launchpad

  • Provider

  • Hosted Email Add-in

Using the Windows 2008 R2 SDK

You can also take advantage of the Microsoft Windows SDK for Windows Server 2008 and the .NET Framework 4. For more information, see Windows SDK (https://go.microsoft.com/fwlink/p/?LinkId=182502).

Development Environment

To develop and build add-ins, you should have the following:

  • Development computer that should be running a 64-bit version of Windows Vista, Windows 7, or Windows 8

  • Visual Studio 2010 or Visual Studio 2012

  • The downloaded and installed SDK

  • A server that is running Windows 2012 Essentials

  • A client computer for connecting to the server

Getting the Current Version Information

The manner in which version information is obtained depends on whether the code is being executed on a server or client.

  • Server Installation - On a server installation, the server name and SKU can be obtained by calling the GetProductInfo Windows API function. This function updates a pointer to a DWORD with the product type information. The following table lists the possible values in the context of this topic.

    Value SKU
    0x00000032 Windows Server 2012 Essentials

  • Client Installation - On a client installation, the caller must examine the Windows Registry key located at HKLM\SOFTWARE\Microsoft\WindowsServer. This key contains a value called ServerSku, which is a DWORD and represents the SKU. The following table lists the possible values in the context of this topic.

    ServerSku Value SKU
    0x32 (50) Windows Server 2012 Essentials

Identifying the Server Name

On the client, developers can view the HKLM\SOFTWARE\Microsoft\Windows Server registry key.That key contains a registry value called ServerName that identifies the server name.