Understanding Versioning in HPC Services for Excel

Applies To: Windows HPC Server 2008 R2

HPC Services for Excel includes service-oriented architecture (SOA) clients and services that help offload workbook calculations to a cluster, and the HPC Macro framework that helps developers define how VBA workbook functions can run in parallel. The service, client, and HPC Macro (workbook) features are defined and installed in separate places, and each have separate version identifiers. The versions do not need to match. What version of a feature is available depends on what version of Microsoft HPC Pack is installed on the cluster or on the client computer, or what HPC Macro version was used to define the workbook.

Excel workbook and UDF offloading to a Windows HPC cluster supports clients, services, and workbooks of different versions as follows:

  • Services are backwards compatible. Operations are only added, so older versions of the client can call newer versions of the service.

  • By default, clients use the newest version of the service that is installed on the cluster

  • Newer clients can communicate with older versions of a service, but cannot invoke operations that were not implemented by the older service. If the client invokes an operation that is not available, the user will see an error message. The client can use SessionBase.ServiceVersion to derive whether the service implements a newer operation and if not, handle it accordingly.

  • For workbook offloading, developers should implement the HPC_GetVersion macro to communicate which version of the framework they implemented in the workbook. The ExcelClient uses HPC_GetVersion to determine the version of the macro framework. This will allow future versions of the ExcelClient to provide expected behavior even if features change and new versions of the macro framework become available.

The following describes versioning for the workbook offloading features:

Feature Description HPC 2008 R2 SP1 SP2

On the cluster

ExcelService is the cluster-side feature for workbook offloading. The service name is in the format:

Microsoft.Hpc.Excel.ExcelService_<majorVersion>.<minorVersion>

The available versions of ExcelService are determined by what version of Microsoft HPC Pack is installed on the cluster.

1.0

1.0

1.0

On the client

ExcelClient is the client-side feature for workbook offloading. The version of ExcelClient is determined by which version of the Microsoft HPC Pack client utilities are installed on the client computer.

Changes

Version 1.1 added the MacroResource property, which can be specified to change the resource that contains the HPC_* macros. This allows users to use a separate workbook or add-in that defines the hpc_* macros.

1.0

1.1

1.1

On the workbook

The workbook version refers to which version of the HPC Macro framework is implemented in the workbook. This value is specified in HPC_GetVersion.

There is currently only one version of the HPC Macro framework, so only version 1.0 is a supported value for this property.

1.0

1.0

1.0

The following describes versioning for the UDF offloading features:

Feature Description HPC 2008 R2 SP1 SP2

On the cluster

The XLL container services are the cluster-side features for UDF offloading. The service name is in the format:

Microsoft.Hpc.Excel.XLLContainer32_<majorVersion>.<minorVersion>

Microsoft.Hpc.Excel.XLLContainer64_<majorVersion>.<minorVersion>

The available versions of the XLL container services are determined by what version of Microsoft HPC Pack is installed on the cluster.

Changes

Version 1.1 includes some minor changes to support UDF offloading on Azure Nodes.

1.0

1.0

1.1

1.0

1.1

On the client

The Excel Cluster Connector is the client-side feature for UDF offloading. The version of the connector is determined by which version of the Microsoft HPC Pack client utilities are installed on the client computer.

1.0

1.0

1.0

Additional versioning considerations for cluster-Excel developers

The COM interface, IExcelClient, will be strictly versioned so that code written targeting the current interface will not be broken. For each revision of this interface, IExcelClient will be assigned a new GUID and an IExcelClientVx will be created with the previously assigned GUIDwhere x is the previous version. So in the next revision of this interface, we will provide both an IExcelClient and IExcelClientV1 interface.

Developers are encouraged only to use the IExcelClient interface, as Excel's VBA environment uses name-based type resolution. The IExcelClient interface will better allow workbooks written with newer versionsof the interface to work on computers that have older version. The IExcelClientV1 interface will be included to allow other COM clients which cache GUIDs to be compiled with the current binaries and continue to work on future versions without recompilation.

If VBA developers would like to design their workbooks such that they make use of new APIs in the IExcelClient interface, but would like to Mayntain backward compatibility on client with an older version of ExcelClient installed, they can check the IExcelClient.Version property at runtime and only call APIs provided in version X when version X or higher is returned.This allows developers to explicitly fall back into a compatibility mode where only APIs provided in an older release are used, or produce a useful message to the user statingthe requirements to run the workbook.

If a newer version of a client connects to an older version of the service on a cluster and tries to call a feature which is not available on the older version, the user will receive an error at runtime which explains any incompatibility.

Additional references

General

For developers