示例：扩展助手卡类型（自定义卡）

项目
09/13/2023

了解如何下载以及有哪些资源可用于创建自定义操作或了解如何扩展助手操作卡。

许可证和角色要求

要求类型	您必须具有
许可证	Dynamics 365 Sales Premium 详细信息：Dynamics 365 Sales 定价
安全角色	系统定制员详细信息：预定义的 Sales 安全角色

创建自定义操作卡

以下过程介绍如何创建自定义卡：

步骤 1：下载扩展助手卡类型示例解决方案
步骤 2：构建解决方案 (ExtPkgDeployer.sln)
步骤 3：使用 Package Deployer 工具导入程序包
步骤 4：验证新卡类型
步骤 5：使用 Web API 创建新卡类型的操作卡。
步骤 6：验证新自定义卡

必备条件

在您的组织中创建自定义卡之前请先查看必备条件：

您必须有 Package Deployer 工具 (packagedeployer.exe) 才能部署程序包。若要下载 Package Deployer，请参阅从 NuGet 下载工具
若要使用此功能，必须购买 Dynamics 365 Sales Insights 许可证或开始试用才能使用 Sales Insights 功能。

步骤 1：下载扩展助手卡类型示例解决方案

下载示例自定义卡解决方案。

示例演示如何在助手中以编程方式创建自定义卡。

转到路径 ExtPkgDeployer\PkgFolder\extensibility_example_sol\WebResources。在 WebResources 文件夹下，您可以看到创建自定义卡所需要的三个文件。

架构定义 (new_cardtype_schemaxml9dd7e039-33a1-4778-9972-66536dc5e829)
命令 (new_commands8db43275-0291-401d-923a-90a6c373cc18)
图标 (new_msicon6aa7c568-4830-4da6-89f9-18a8fd9c2285)

架构定义 (new_cardtype_schemaxml9dd7e039-33a1-4778-9972-66536dc5e829)

包含新卡类型的架构定义。

备注

确保卡类型 ID 值大于 10000。

<?xml version="1.0" encoding="utf-8" ?>
<entity name="cardtype" displayname="Action Card Type">
  <cardname>Extensibility Example</cardname>
  <cardtypeid>2183dfc0-3c1c-45b7-a331-1943880c25c6</cardtypeid>
  <cardtype>11000</cardtype>
  <cardtypeicon>webresources/new_msicon</cardtypeicon>
  <softtitle>Extensibility Example</softtitle>
  <summarytext>RA Card Extensibility Example</summarytext> 
  <actions>{"WebClient":{"Actions":{"Open":"Mscrm.HomepageGrid.actioncard.CardCommand"},"Default":{"Open":"Mscrm.HomepageGrid.actioncard.CardCommand"}}, "Mobile":{"Actions":{"Open":"Mscrm.HomepageGrid.actioncard.CardCommand"}}}</actions>
</entity>

命令 (new_commands8db43275-0291-401d-923a-90a6c373cc18)

此文件包含操作卡的命令。

function CardCommand() {
	window.open("https://aka.ms/salesai-raext");
}

当您执行命令时，通过在 ActionCard 实体的 customization.xml 中定义的 RibbonDiff 调用命令。

<ImportExportXml xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <Entities>
    <Entity>
      <Name LocalizedName="ActionCard" OriginalName="ActionCard">ActionCard</Name>
      <ObjectTypeCode>9962</ObjectTypeCode>
      <RibbonDiffXml>
        <CustomActions>
          <CustomAction Id="Mscrm.HomepageGrid.actioncard.CardCommand.CustomAction" Location="Mscrm.HomepageGrid.actioncard.MainTab.Actions.Controls._children" Sequence="12">
            <CommandUIDefinition>
              <Button Id="Mscrm.HomepageGrid.actioncard.CardCommand" ToolTipTitle="Open" ToolTipDescription="Open" Command="Mscrm.HomepageGrid.actioncard.CardCommand" Sequence="12" LabelText="Open" Alt="Open" Image16by16="/WebResources/new_msicon" Image32by32="/WebResources/new_msicon" TemplateAlias="o1" ModernImage="new_msicon" />
            </CommandUIDefinition>
          </CustomAction>
          <CustomAction Id="Mscrm.SubGrid.actioncard.CardCommand.CustomAction" Location="Mscrm.SubGrid.actioncard.MainTab.Actions.Controls._children" Sequence="57">
            <CommandUIDefinition>
              <Button Id="Mscrm.HomepageGrid.actioncard.CardCommand" ToolTipTitle="Open" ToolTipDescription="Open" Command="Mscrm.HomepageGrid.actioncard.CardCommand" Sequence="29" LabelText="Open" Alt="Open" Image16by16="/WebResources/new_msicon" Image32by32="/WebResources/new_msicon" TemplateAlias="o1" ModernImage="new_msicon" />
            </CommandUIDefinition>
          </CustomAction>
        </CustomActions>
        <CommandDefinitions>
          <CommandDefinition Id="Mscrm.HomepageGrid.actioncard.CardCommand">
            <EnableRules >
              <EnableRule Id="Mscrm.SelectionCountExactlyOne" />
              <EnableRule Id="Mscrm.NotOffline" />
            </EnableRules>
            <DisplayRules>
            </DisplayRules>
            <Actions>
              <JavaScriptFunction FunctionName="CardCommand" Library="$webresource:new_commands">
                <CrmParameter Value="SelectedControl" />
                <CrmParameter Value="SelectedControlSelectedItemReferences" />
              </JavaScriptFunction>
            </Actions>
          </CommandDefinition>
        </CommandDefinitions>
        <RuleDefinitions>
          <TabDisplayRules />
          <DisplayRules>
          </DisplayRules>
          <EnableRules/>
        </RuleDefinitions>    
      </RibbonDiffXml>       
    </Entity>
  </Entities>
  <Roles></Roles>
  <Workflows></Workflows>
  <FieldSecurityProfiles></FieldSecurityProfiles>
  <Templates />
  <EntityMaps />
  <EntityRelationships />
  <OrganizationSettings />
  <optionsets />
  <WebResources>
	<WebResource>
      <WebResourceId>{6aa7c568-4830-4da6-89f9-18a8fd9c2285}</WebResourceId>
      <Name>new_msicon</Name>
      <DisplayName>new_msicon</DisplayName>
      <WebResourceType>5</WebResourceType>
      <IntroducedVersion>1.0</IntroducedVersion>
      <IsEnabledForMobileClient>0</IsEnabledForMobileClient>
      <IsAvailableForMobileOffline>0</IsAvailableForMobileOffline>
      <DependencyXml>&lt;Dependencies&gt;&lt;Dependency componentType="WebResource"/&gt;&lt;/Dependencies&gt;</DependencyXml>
      <IsCustomizable>1</IsCustomizable>
      <CanBeDeleted>1</CanBeDeleted>
      <IsHidden>0</IsHidden>
      <FileName>/WebResources/new_msicon6aa7c568-4830-4da6-89f9-18a8fd9c2285</FileName>
    </WebResource>
    <WebResource>
      <WebResourceId>{8db43275-0291-401d-923a-90a6c373cc18}</WebResourceId>
      <Name>new_commands</Name>
      <DisplayName>new_commands</DisplayName>
      <WebResourceType>3</WebResourceType>
      <IntroducedVersion>1.0</IntroducedVersion>
      <IsEnabledForMobileClient>0</IsEnabledForMobileClient>
      <IsAvailableForMobileOffline>0</IsAvailableForMobileOffline>
      <DependencyXml>&lt;Dependencies&gt;&lt;Dependency componentType="WebResource"/&gt;&lt;/Dependencies&gt;</DependencyXml>
      <IsCustomizable>1</IsCustomizable>
      <CanBeDeleted>1</CanBeDeleted>
      <IsHidden>0</IsHidden>
      <FileName>/WebResources/new_commands8db43275-0291-401d-923a-90a6c373cc18</FileName>
    </WebResource>
	<WebResource>
      <WebResourceId>{9dd7e039-33a1-4778-9972-66536dc5e829}</WebResourceId>
      <Name>new_cardtype_schema</Name>
      <DisplayName>cardtype_schema</DisplayName>
      <WebResourceType>4</WebResourceType>
      <IntroducedVersion>1.0</IntroducedVersion>
      <IsEnabledForMobileClient>0</IsEnabledForMobileClient>
      <IsAvailableForMobileOffline>0</IsAvailableForMobileOffline>
      <DependencyXml>&lt;Dependencies&gt;&lt;Dependency componentType="WebResource"/&gt;&lt;/Dependencies&gt;</DependencyXml>
      <IsCustomizable>1</IsCustomizable>
      <CanBeDeleted>1</CanBeDeleted>
      <IsHidden>0</IsHidden>
      <FileName>/WebResources/new_cardtype_schemaxml9dd7e039-33a1-4778-9972-66536dc5e829</FileName>
    </WebResource>
  </WebResources>
  <Languages>
    <Language>1033</Language>
  </Languages>
</ImportExportXml>

图标 (new_msicon6aa7c568-4830-4da6-89f9-18a8fd9c2285)

此文件包含用于卡的图标。

步骤 2：构建解决方案 (ExtPkgDeployer.sln)

打开命令提示符 (cmd)。
转至 root 文件夹。 C:\<directory>\RACards Extensibility Example\RACards Extensibility Example\ExtPkgDeployer\PkgFolder
执行命令以构建解决方案。 msbuild ExtPkgDeployer.sln

构建成功，您可以看到在 <folder>\ExtPkgDeployer\bin\Debug 下，PkgFolder 和 ExtPkgDeployer.dll 已生成。

步骤 3：使用 Package Deployer 工具导入程序包

从 <folder>\ExtPkgDeployer\bin\Debug 文件夹复制 PkgFolder 和 ExtPkgDeployer.dll，并粘贴到 <PackageDeployerToolLocation>\tools 位置。
从保存 Package Deployer 工具的文件夹双击 PackageDeployer.exe 来运行工具。
在 Package Deployer 工具的介绍屏幕上，单击继续。
在身份验证屏幕中，提供身份验证详细信息以连接至您要在其中部署程序包的 Dynamics 365 Sales 实例。如果您有多个组织，并且想要选择您要部署 Unified Service Desk 包的组织，请选中显示可用组织的列表复选框。选择登录。
下一屏幕将显示有关所选程序包的详细信息和要安装在您的 Dynamics 365 Sales 实例上的项目。查看该信息，然后选择下一步。
准备安装屏幕显示用于部署和命名 Dynamics 365 Sales 组织的所选程序包，其中该组织就是要部署程序包的地方。查看该信息，然后选择下一步。
下一屏幕显示所选的用于部署的程序包的验证状态。成功验证完成后，选择下一步。
下一页显示程序包部署状态。单击下一步。
下一屏幕显示您刚刚部署的程序包的名称和相关信息。查看该信息，然后选择完成退出 Package Deployer 工具。

在部署程序包后，新卡类型将使用 ID - 2183dfc0-3c1c-45b7-a331-1943880c25c6 创建，此 ID 在架构 (new_cardtype_schemaxml9dd7e039-33a1-4778-9972-66536dc5e829) 中定义。

步骤 4：验证新卡类型

验证 ID 为“2183dfc0-3c1c-45b7-a331-1943880c25c6”的卡类型。发送 GET 方法请求。

请求

GET [Organization URI]/api/data/v9.0/cardtype(2183dfc0-3c1c-45b7-a331-1943880c25c6) HTTP/1.1  
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0

响应

{
"@odata.context":"https://[Organization URI]/api/data/v9.0/$metadata#cardtype/$entity",
"@odata.etag":"W/"662120\"",
"boolcardoption":false,
"clientavailability":3,
"ispreviewcard":true,
"cardname":"ExtExample",
"cardtypeid":"2183dfc0-3c1c-45b7-a331-943880c25c6",
"cardtypeicon":"webresources/new_msicon",
"intcardoption":0,
"isenabled":true,
"hassnoozedismiss":true,
"softtitle":"Extensibility Example",
"cardtype":11000,
"isliveonly":false,
"_modifiedby_value":"50673658-c5d6-e811-a98c-000d3a1df431",
"versionnumber":662120,
"isbasecard":false,
"actions":"{\"WebClient\":{\"Actions\":{\"Open\":\"Mscrm.HomepageGrid.actioncard.CardCommand\"},\"Default\":{\"Open\":\"Mscrm.HomepageGrid.actioncard.CardCommand\"}}, \"Mobile\":{\"Actions\":{\"Open\":\"Mscrm.HomepageGrid.actioncard.CardCommand\"}}}",
"publishername":"adminsocial",
"modifiedon":"2018-10-26T12:26:14Z",
"summarytext":"RA Card Extensibility Example",
"_transactioncurrencyid_value":null,
"importsequencenumber":null,
"createdon":null,
"overriddencreatedon":null,
"_modifiedonbehalfby_value":null,
"_createdonbehalfby_value":null,
"_createdby_value":null,
"scheduletime":null,
"exchangerate":null,
"grouptype":null,
"stringcardoption":null,
"lastsynctime":null
}

步骤 5：使用 Web API 创建新卡类型的操作卡

为使用 Package Deployer 创建的新卡类型创建操作卡。发送 POST 方法请求。

Request

POST http://[Organization URI]/api/data/v9.0/actioncards HTTP/1.1
Content-Type: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0  
{
"cardtypeid@odata.bind": "/cardtype(2183dfc0-3c1c-45
b7-a331-1943880c25c6)",
"startdate": "2018-10-20T01:01:01Z",
"expirydate": "2018-10-25T01:01:01Z",
"visibility": true,
"priority": 2000,
"description": "This card should be visible between
start and end date mentioned above",
"title" : "Extensibility Example",
"cardtype": 11000,
"ownerid@odata.bind" : "/systemusers({USER_ID})"
}

Response

HTTP/1.1 204 No Content  
OData-Version: 4.0  
OData-EntityId: http://[Organization URI]/api/data/v9.0/actioncard(2183dfc0-3c1c-45b7-a331-1943880c25c6)

备注

打开浏览器控制台并运行命令 sessionStorage.clear(); 来清除会话缓存。

步骤 6：验证新自定义卡

您可以作为最终用户和管理员验证是否在您的组织中创建了自定义卡。

作为最终用户

登录 Dynamics 365 Sales。
在助手部分下，您可以查看已创建的操作卡。

作为管理员

登录到 Dynamics 365 Sales 并转到销售中心应用。
转到更改区域并选择 Sales Insights 设置。
在站点地图上，选择助手下面的见解卡以转到管理见解卡页。
在管理见解卡页上，您将看到在您的组织中启用创建的自定义操作卡的选项。

要了解有关如何启用卡的更多信息，请参阅打开或关闭见解卡.

在应用中找不到选项？

有三种可能的原因：

您没有必要的许可证或角色。请查看本页顶部的“许可证和角色要求”部分。
您的管理员未打开此功能。
您的组织正在使用自定义应用。请联系管理员获取确切步骤。本文章中说明的步骤仅针对现成可用的销售中心和 Sales Professional 应用。

在助手中创建自定义卡

配置助手

使用助手指导客户通信

通过

示例：扩展助手卡类型（自定义卡）

许可证和角色要求

创建自定义操作卡

必备条件

步骤 1：下载扩展助手卡类型示例解决方案

架构定义 (new_cardtype_schemaxml9dd7e039-33a1-4778-9972-66536dc5e829)

命令 (new_commands8db43275-0291-401d-923a-90a6c373cc18)

图标 (new_msicon6aa7c568-4830-4da6-89f9-18a8fd9c2285)

步骤 2：构建解决方案 (ExtPkgDeployer.sln)

步骤 3：使用 Package Deployer 工具导入程序包

步骤 4：验证新卡类型

请求

响应

步骤 5：使用 Web API 创建新卡类型的操作卡

Request

Response

步骤 6：验证新自定义卡

在应用中找不到选项？

反馈

其他资源

通过

示例：扩展助手卡类型（自定义卡）

许可证和角色要求

创建自定义操作卡

必备条件

步骤 1：下载扩展助手卡类型示例解决方案

架构定义 (new_cardtype_schemaxml9dd7e039-33a1-4778-9972-66536dc5e829)

命令 (new_commands8db43275-0291-401d-923a-90a6c373cc18)

图标 (new_msicon6aa7c568-4830-4da6-89f9-18a8fd9c2285)

步骤 2：构建解决方案 (ExtPkgDeployer.sln)

步骤 3：使用 Package Deployer 工具导入程序包

步骤 4：验证新卡类型

请求

响应

步骤 5：使用 Web API 创建新卡类型的操作卡

Request

Response

步骤 6：验证新自定义卡

在应用中找不到选项？

相关信息

反馈

其他资源