Dynamics CRM: 查询字符串参数(Query String Parameters)的使用方法

查询字符串参数(Query String Parameters)通常被用来传递自定义参数给表单上下文, 我使用它是用来判断用户是从哪里点击的这条记录, 但其实它的用处很多, 需要大家自己来发掘.下面我就来说下它的用法:

1. 创建Query String Parameters

a. Settings -> Customizations -> Customize the System

b.  Entities -> <实体名> -> Forms -> <表单名> 

 c. 进入Form Properties -> 选择Parameters

 你可以传递下面几种类型的值:

• Boolean

• DateTime

• Double

• EntityType

• Integer

• Long

• PositiveInteger(包括0)

• SafeString

• UniqueId

• UnsignedInt

2. 传递参数值给表单

链接示例:

[Organization Url]/main.aspx?etn=account&pagetype=entityrecord&id=%7B91330924-802A-4B0D-A900-34FD9D790829%7D&extraqs=parameter_0%3D0

 这个链接的作用是打开指定的Account实体记录, 我们重点说一下最后的这一块&extraqs=parameter_0%3D0

extraqs这个参数是用来传递查询字符串的, 后面接等号, 等号后面到下一个&之前的这部分(如果有)为查询字符串的参数和值, 那我上面例子中的parameter_0%3D0就是URL encode的参数和值, 里面的%3D就是等号(=), 相当于parameter_0=0. 

多个参数之间用&分隔, 也就是%26, 例如未编码前为:parameter_0=0&parameter_1=1, 那么编码后就是parameter_0%3D0%26parameter_1%3D1

接着来说一下使用extraqs来传递参数的一些注意事项:

• 必须对在 extraqs 参数中传递的参数进行编码(encodeURIComponent), 就像上面那样
• 查询字符串参数的名称必须匹配或包含实体的属性名称
• 传递的值必须有效, 不能你参数类型是一个布尔,结果你给了一个abc这样的字符串值.
• 该值不能是脚本
• 任何传递无效参数或值的尝试都将导致错误
• 对于布尔字段，可以使用0或1的整数值，或者使用 true 或 false 的文本值来设置该值
• 对于 DateTime 字段，使用日期的文本值

Note: 其实还可以这种传递参数的方式来设置字段值, 具体可以参考这个链接:

Set field values using parameters passed to a form (Developer Guide for Dynamics 365 Customer Engagement) | Microsoft Docshttps://docs.microsoft.com/en-us/dynamics365/customerengagement/on-premises/developer/set-field-values-using-parameters-passed-form?view=op-9-1

3. 读取查询字符串

第一种方法:

1. 首先我们需要在页面进行一些设置, 进入Form中的Form Properties, 选择或者创建一个事件

 进入这个事件后, 选中'Pass executiuon context as first parameter', 这样就可以把上下文信息通过参数传给这个Test函数

 然后我们就可以在代码中使用了

Test: function (executionContext) {

	var objFormContext = executionContext.getFormContext();
	var para0 = objFormContext.data.attributes.get("parameter_0").getValue();

}

第二种方法(建议不用):

Test: function () {

	var params = Xrm.Utility.getGlobalContext().getQueryStringParameters();
	var para0 = params["parameter_0"];
	
}

Note:

1. 第二种方法不需要像第一种方法那样传递上下文给Test函数, 而且在我测试的过程中,我发现我连第一步创建Query String Parameters都不需要,只要在第二步中将参数添加到链接中,然后当有人点击这些链接后来触发事件函数,比如Onload,就可以直接使用Xrm.Utility.getGlobalContext().getQueryStringParameters();来获取所有的参数了

2. 重点来了,就是这种方法在新版的Dynamics CRM已经被废弃了, 所以尽量使用第一种方法来读取查询字符串参数的值, 虽然麻烦点...

Important changes (deprecations) coming in Power Apps and Power Automate - Power Platform | Microsoft DocsImportant changes (deprecations) coming in Power Apps and Power Automatehttps://docs.microsoft.com/en-us/power-platform/important-changes-coming#some-client-apis-are-deprecated3. 我在测试的时候使用的是Dynamics CRM OP v9.0, 第二种方法还是可以正常使用的, 如果你使用的是9.1,或者online版本,估计第二种方法就不行了.

参考链接:

Configure a form to accept custom querystring parameters (Developer Guide for Dynamics 365 Customer Engagement) | Microsoft Docshttps://docs.microsoft.com/en-us/dynamics365/customerengagement/on-premises/developer/configure-form-accept-custom-querystring-parameters?view=op-9-1Manage form properties in Dynamics 365 Customer Engagement (on-premises) | Microsoft Docshttps://docs.microsoft.com/en-us/dynamics365/customerengagement/on-premises/customize/form-properties-legacy?view=op-9-1Open forms, views, dialogs, and reports with a URL (Developer Guide for Dynamics 365 Customer Engagement (on-premises)) | Microsoft Docshttps://docs.microsoft.com/zh-cn/dynamics365/customerengagement/on-premises/developer/open-forms-views-dialogs-reports-url?view=op-9-1