Getting started

The guide is aimed at experienced administrators and software developers who have programming skills and are familiar with using SDKs. Using the Store Customization SDK requires moderate programming skills, preferably in C#.

This page explains how to apply customizations using the Store Customization SDK. A list of minimum requirements is provided, and an overview of the main steps you must perform.

All the customizations follow a similar pattern: you must create an assembly and class with specified names and namespace. This class must implement one or more interfaces that allow it to customize specific StoreFront actions. These interfaces contain methods with names of the form ModifyXXX, which allow a specific value used by StoreFront to be customized. The method provides the value that StoreFront would use if no customization were defined; you must return the result that you want StoreFront to use instead.

The customization code is also provided with a customization context data object, containing information specific to the client request being processed. This object contains data such as device information, HttpContext, user identity, access conditions, delivery controllers, and user access preferences. You can use this object to guide customization logic. See Store_Customization_API.chm in the SDK for details about this type.

The implementing assemblies must target .NET Framework 4.5.

Typical customization examples and template files are supplied with the SDK (see the Solution folder). These are simple files you can use as a starting point and add your own logic to. Simply populate the template files with your own code to implement your customizations, as described in the following steps. See the sample solution for more information about the template files.

Before you begin, review the Known issues section at the end of this guide.

Minimum system requirements

• Windows 7
• Visual Studio 2012
• .NET Framework 4.5
• StoreFront 3.0 or higher. Note that customizations produced using the version of the SDK that shipped with StoreFront 2.5 are also compatible with StoreFront 3.x.

Overview of the steps

This section provides an overview of the main steps you perform when using the Store Customization SDK. Each step is then described in detail in a subsequent section of the guide. The steps are:

1. Identify the customization point you want to use; for example “Resources customization”. See Customization interfaces for the list of interfaces.
2. Create a new project by copying the appropriate template from the Solution folder of the SDK.
3. Open the project in Visual Studio
4. Add your custom logic to the code files.
5. Build the solution.
6. Deploy your customization.
7. Restart services.
8. Test and debug your customizations.

Deploying customizations

Ensure that customization classes are contained within their respective assemblies.

Step 1 Back up the original assemblies

Citrix recommends you back up the original assemblies before replacing them with the new customized assemblies. Original assemblies are required for restoring the default behavior. Ensure you back up the following:

StoreCustomization_Enumeration.dll
StoreCustomization_Input.dll
StoreCustomization_Launch.dll
StoreCustomization_SessionEnumeration.dll
<!--NeedCopy-->

Step 2 Deploy customizations

To deploy customizations, manually copy the new customized assemblies to the Store’s bin folder on the appropriate StoreFront server. This replaces the existing assemblies. If the StoreFront server is part of a cluster deployment, perform the propagation action to push the new assemblies to other members of the cluster.

Note: Only these files, and accompanying pdbs, are propagated using the propagation action. If there are additional files, these must be placed in the StoreCustomizationCustomLibraries folder, which can be found under the Store’s bin folder. You must place additional files in this folder to ensure that the propagation service propagates these to the other members of the cluster.

Step 3 Restart services

After deploying your customizations, restart the following services. Restarting forces the services to clear any cached data from previous implementations of the assemblies.

Note: Services should restart automatically when customizations are deployed, but Citrix recommends you check that this has occurred.

• Internet Information Service — this is the IIS service running on the StoreFront server.
• CitrixSubscriptionsStore — this is a Windows service running on the StoreFront server.

Test and debug

This section explains how to test and debug your customizations. It explains how to enable tracing, and attach the debugger so that you can debug within Visual Studio.

To troubleshoot your implementation, first look in the event log. You can also consult the trace, which provides more information than the event log. During testing, set the trace level to Verbose and in production, set it to Error or Warning. For more information, see the Enable tracing in the Test and debug section for details of how to enable tracing.

For information on debugging your implementation within Visual Studio, see the section below.

You can also configure StoreFront to run “extended validation” against returned values during development and testing. To do this, set RunExtendedValidation to true; for more information see the Customization Interfaces section. However, because there is a performance impact when running extended validation, ensure you set this to false in the production environment.

Enable tracing

The tracing feature writes detailed information to the trace. The default location for trace dumps is C:\Program Files\Citrix\Receiver StoreFront\Admin\trace.

To enable tracing and set the trace level, use the PowerShell script SetDSStoreCustomizationTraceLevel.ps1, which is supplied with the SDK. This script takes the following parameters:

Citrix recommends you set the trace level to Verbose during development, and to Error or Warning in the production environment.

Tip:

If you do not know the SiteId and VirtualPath of the Store, run the following PowerShell commands:

cd 'c:\program files\Citrix\Receiver Storefront\Scripts'.

.\ImportModules.ps1

Get-DSStoreFeatureInstances
<!--NeedCopy-->

Write to the trace

The Store Customization SDK includes a tracing class named Tracer. This class has the following methods, which allow you to output to the trace from the Store Customization SDK:

Debugging

This section explains how to attach the debugger so that you can debug your implementation line-by-line within Visual Studio, and specify breakpoints where execution of the code pauses.

1. Write your customized solution in Visual Studio 2012.
2. Attach to process w3wp.exe, which has the user name IIS APPPOOL\Citrix Delivery Services Resources.

Subsequent requests for resources using the preferred client will hit a breakpoint in Visual Studio.

To set up remote debugging, see here. You need to do this if the development machine running Visual Studio is different from the StoreFront deployment machine running your customizations.

Upgrading StoreFront

Note that customizations are not persisted during an upgrade. After upgrading, you must redeploy your customized assembles and test these before rolling out to the production environment.

Removing customizations

Provided you backed-up the original assemblies, as described in Deploying Customizations, you can restore the original behavior of StoreFront as follows:

1. Copy the backed-up assembles in the Store’s bin folder onto one of the StoreFront servers.
2. Perform the propagation action on the StoreFront server on which the assemblies were copied. This pushes the original assemblies onto other members of the StoreFront cluster.

Tip:

You can also remove customizations by removing the dlls and performing the propagation action; the dlls are removed from all machines in the server group.

Known issues

Review this section carefully before using the SDK.

• When a user logs on to StoreFront using credentials in User Principal Name (UPN) format, the AuthenticationType field of the UserIdentity object stored in CustomizationContextData is set to an empty string and Name is set to the UPN name used when logging on.