练习 - 创建新的 Retail Server 扩展

20 分钟

Retail Server 扩展充当公开 Commerce Runtime 逻辑的服务。要创建 Retail Server 扩展，请按照以下步骤操作：

创建 Retail Server 扩展之前，要先创建 CRT 扩展。 Retail Server API 不应包含除使用参数调用 CRT 以外的任何逻辑。
创建一个使用 Microsoft .NET Framework 版本 4.6.1 的全新 C# 类库项目，或将 Commerce SDK 中的任一 Retail Server 示例用作模板。
在 Retail Server 扩展项目中，添加 CRT 扩展库或项目的引用。本引用允许您调用 CRT 请求、响应和实体。
在 Retail Server 扩展项目中，使用 NuGet 包管理器添加 Microsoft.Dynamics.Commerce.Hosting.Contracts 包。 NuGet 包位于 RetailSDK\pkgs 文件夹中。
创建新 controller 类，然后从 IController 扩展。本 controller 类包含必须由 Retail Server API 公开的方法。在 controller 类内，添加调用 CRT 请求的方法。请勿从现有控制器类（例如，CustomerController 和 ProductController）扩展新控制器类。扩展类必须仅扩展 IController 类。
在 controller 类上添加 RoutePrefix 属性，将其绑定到实体。如果没有将其绑定到实体，则不需要提供本属性。如果要创建新控制器并公开实体，则需要为 controller 类添加 BindEntity 属性。

以下示例代码用于创建一个简单的 Retail Server API，可返回一个实体、一个字符串和一个布尔值。本示例中不包含示例使用的 CRT 请求和响应。有关 CRT 请求和响应的示例，请参阅 Commerce Runtime (CRT) 可扩展性和触发器。

```csharp
/// <summary>
    /// New extended controller.
    /// </summary>
    [RoutePrefix("SimpleExtension")]  
    [BindEntity(typeof(SimpleEntity))]

    public class SimpleExtensionController : IController
    {
        /// <summary>
        /// The action to get the string value.
        /// </summary>
        /// <param name="context">The context parameters.</param>
        /// <param name="stringValue">The string value parameters.</param>
        /// <returns>The string value.</returns>
        [HttpPost]
        [Authorization(CommerceRoles.Customer, CommerceRoles.Employee)]
        public async Task<string> GetStringValue(IEndpointContext context, string stringValue)
        {
            GetStringValueResponse resp = await     context.ExecuteAsync<GetStringValueResponse>
            (new GetStringValueRequest(stringValue)).ConfigureAwait(false);
            return resp.StringValue;
        }

        /// <summary>
        /// The action to get the bool value.
        /// </summary>
        /// <param name="context">The context parameters.</param>
        /// <param name="boolValue">The string value parameters.</param>
        /// <returns>The bool value.</returns>
        [HttpPost]
        [Authorization(CommerceRoles.Customer, CommerceRoles.Employee)]
        public async Task<bool> GetBoolValue(IEndpointContext context, string boolValue)
        {
        GetBoolValueResponse resp = await context.ExecuteAsync<GetBoolValueResponse>
        (new GetBoolValueRequest(boolValue)).ConfigureAwait(false);
        return resp.BoolValue;
    }

        /// <summary>
        /// The action to get the simple entity.
        /// </summary>
        /// <param name="context">The context parameters.</param>
        /// <param name="name">The name parameters.</param>
        /// <returns>The simple entity.</returns>
        [HttpPost]
        [Authorization(CommerceRoles.Customer, CommerceRoles.Employee)]
        public async Task<SimpleEntity> GetSimpleEntity(IEndpointContext context, string name)
        {
            GetSimpleEntityResponse resp = await context.ExecuteAsync<GetSimpleEntityResponse>
            (new GetSimpleEntityRequest(name)).ConfigureAwait(false);
            return resp.SimpleEntityObj;
        }
```

构建扩展项目并将二进制文件复制到 \RetailServer\webroot\bin\Ext 文件夹。

通过在 extensionComposition 部分添加新扩展库名称，更新 \RetailServer\webroot 文件夹中的 Commerce Scale Unit web.config 文件。

<extensionComposition>
<!-- Use fully qualified assembly names for ALL if you need to support loading from the Global Assembly Cache.
If you host in an application with a bin folder, this is not required. -->
<add source="assembly" value="SimpleExtensionSample" >
</extensionComposition>

在 Microsoft Internet Information Services (IIS) 中，重新启动 Commerce Scale Unit，加载新扩展。
要验证扩展是否成功加载，可以浏览 Retail Server 元数据。确认您的实体和方法是否已显示在列表中。要浏览元数据，请在 Web 浏览器中打开以下格式的 URL：https://RS-URL/Commerce/$metadata
要在客户端中调用 Retail Server 扩展，必须生成客户端 TypeScript 代理。然后，您可以使用该代理从客户端调用新的 Retail Server API。使用 Retail Server 扩展 API 时，无需在扩展中添加或包含 EdmModelExtender 文件。仅当使用 Commerce SDK 版本 10.0.10 或更早版本时才需要添加这些文件。使用本新 Microsoft.Dynamics.Commerce.Hosting.Contracts API 构建的 Retail Server 扩展可用于脱机实现。无需生成单独的 C# 代理库。复制 \Microsoft Dynamics 365\70\Retail Modern POS\ClientBroker\ext 文件夹中的 Retail Server 扩展库，然后更新 RetailProxy.MPOSOffline.ext 配置文件，以添加本新库。扩展必须仅生成 TypeScript 代理。 SDK 示例位于 \RetailSDK\SampleExtensions\TypeScriptProxy 文件夹中。以下示例显示了如何更新 RetailProxy.MPOSOffline.ext 配置文件中的 add 元素。
```
<?xml version="1.0" encoding="utf-8"?> 
<retailProxyExtensions> 
    <composition> 
        <add source="assembly" value="Contoso.RetailServer.StoreHoursSample" /> 
    </composition> 
</retailProxyExtensions> 
```

练习 - 创建新的 Retail Server 扩展

反馈