Silverlight (XAP) web resources

Article
04/07/2023

Important

Microsoft Silverlight web resources are deprecated in Dynamics 365 for Customer Engagement apps version 9.0. HTML5 is the preferred client technology for the web, over web plug-ins like Silverlight and Flash. HTML5 can be consumed from any device (PC, tablet, smartphone, and more) and heavily uses JavaScript (and many powerful JavaScript libraries, such as jQuery) and CSS.

Microsoft Silverlight web resources remain supported in Dynamics 365 for Customer Engagement for backwards compatibility in the web application only. Microsoft Silverlight will not work for Unified Interface. For components that will be able to be presented on all clients, we recommend using HTML web resources with HTML5 instead of Silverlight.

Dynamics 365 for Customer Engagement support adding Silverlight 4.0 web resources to entity forms. You can display Silverlight 5.0 web resources within an HTML web resource using a hosting <object> element that is configured for that version.

Note

Microsoft Silverlight web resources can't be viewed in the 64-bit version of Office Outlook.
- To display a Silverlight web resource outside an entity form or chart, create an HTML web resource to be the host page for the Silverlight web resource. Then use the $webresource: directive to open the HTML web resource.

Creating Silverlight web resources

Silverlight web resources are easily created using the web resource form by entering a name, a display name, selecting Silverlight (XAP) as the type, and uploading the .xap file. The web resource must be published before you can use it. However, because Silverlight web resources typically provide some interaction with contextual data in Dynamics 365 Customer Engagement (on-premises), you should plan how you create your web resources.

Accessing context data

When you use the Preview button in the web resources form or just browse to the URL provided, the Silverlight application is hosted in a generic HTML page without context information. If your Silverlight application does not require contextual information, you can use this URL to view your Silverlight web resource.

If you do require contextual information, you must either:

Add your Silverlight web resource to an entity form.
View your Silverlight web resource using an HTML web resource configured to provide context information.

If your Silverlight web resource is designed to be viewed in an entity form, the form has an Xrm.Page.context object you can use to access contextual information. For more information, see Client-side context (client-side reference)

If you need your Silverlight application to appear outside the context of the form you must configure an HTML web resource to provide this context information by adding a reference to the ClientGlobalContext.js.aspx.md#BKMK_ClientGlobalContext_js_aspx) page. After this reference is added, your Silverlight application can access contextual information in the same way it can in an entity form. The following sample shows how to call the getClientUrl function.

private string clientUrl = "";  
ScriptObject xrm = (ScriptObject)HtmlPage.Window.GetProperty("Xrm");  
ScriptObject page = (ScriptObject)xrm.GetProperty("Page");  
ScriptObject pageContext = (ScriptObject)page.GetProperty("context");  
clientUrl = (string)pageContext.Invoke("getClientUrl");

Passing data from a form to an embedded Silverlight web resource

When you add a Silverlight web resource to a form you can select the Pass record object-type code and unique identifier as parameters option. You also have the option to enter text as a custom parameter.

These values are passed to the Silverlight control as a InitParams, a dictionary of key/value pairs.

The values passed are described in the following table.

Key	Description
id	The unique identifier of the record.
type	The entity type code. For custom entities this can vary between organizations.
typename	The logical name of the entity.
orgname	The name of the organization.
userlcid	The language code representing the user’s language preference.
orglcid	The language code representing the organization’s base language.
data	The value of the text entered as a custom parameter.

These values can be accessed at run time using the syntax in the following example:

string entityTypeName = App.Current.Host.InitParams["typename"];

Writing and testing Silverlight web resources

If your Silverlight web resource is independent of any contextual data from Dynamics 365 Customer Engagement (on-premises), you can write and test your Silverlight application as you typically would. After you create a new web resource by uploading your .xap file, you can test it by using the Preview button in the web resource form after you've saved and published the web resource.

However, it's more likely that your Silverlight application has contextual data dependencies that can't be fully simulated outside of Dynamics 365 Customer Engagement (on-premises).

The process of creating a Silverlight web resource that includes form or context dependencies is as follows:

Create your Silverlight application project.

You should select to create a web application with your project.
Write and test as much of the application as you can without requiring contextual data from Dynamics 365 Customer Engagement (on-premises).
Create web resources by uploading the .xap and .htm files as Silverlight and HTML web resources.
Write code in your Silverlight application project.
Build your Silverlight application project.
Upload the built version of the .xap file from the web application project ClientBin folder to update the Silverlight web resource you created in step 3.
Test your Silverlight web resource by either:
- Viewing it using the Preview button of the host HTML web resource you created.
- Viewing it in the context of an entity form that you've added it to.
  
  Use this option is your Silverlight application has dependencies on Form elements or context information.
Repeat steps 4 through 7 until you're finished.

Note

When you want to show a Silverlight web resource outside of an entity form, for example in the application main frame by editing the Site Map, you must provide a webpage (HTML) web resource to act as the host for the Silverlight web resource.

Important

Never edit the HTML source code for a page hosting a Silverlight web resource using the text editor provided in the application. The text editor changes the HTML and breaks <object> element definition necessary to host the SilverlightXAP web resource. For more information, see Using the Text Editor for HTML Web Resources.

If you must use the text editor, omit the data="data:application/x-silverlight-2," parameter in the <object> element. Although this should prevent breaking the Silverlight web resource, the text editor may still introduce other undesirable changes.

Debugging Silverlight web resources

Silverlight web resources that don't rely on contextual data from Dynamics 365 Customer Engagement (on-premises) can be debugged in Visual Studio. However, if the Silverlight web resource requires contextual data to perform the functions, you'll have to use a different procedure.

Build your Silverlight application.
Upload the built version of the .xap file from the web application project ClientBin folder.
View your Silverlight application in the context it's designed to be used in.
In your Silverlight application project, from the Visual Studio menu, select Debug and then Attach To Process.
In the Attach to Process dialog box, find an iexplore.exe process where the Type column value is Silverlight, x86.
Select that process and press Attach to close the dialog box and start debugging.
In your Silverlight application project, set a breakpoint.
Refresh the browser window or, in the Silverlight application, perform the action that you need to test your code.

Silverlight (XAP) web resources

Creating Silverlight web resources

Accessing context data

Passing data from a form to an embedded Silverlight web resource

Writing and testing Silverlight web resources

Debugging Silverlight web resources

See also

Feedback

Additional resources