Azure.MixedReality.RemoteRendering 1.1.0

Azure Remote Rendering .NET 客户端库

Azure Remote Rendering (ARR) 是一项服务，可让您在云中渲染高质量、交互式 3D 内容，并将其实时传输到设备，例如 HoloLens 2。

此 SDK 提供将资产转换为运行时所需格式的功能，并管理远程渲染会话的生命周期。

注意：会话一旦运行，客户端应用程序将连接到其中一个“运行时 SDK”。这些 SDK 旨在最好地支持交互式应用程序进行 3D 渲染的需求。它们以 (.net 或 (C++) 的形式提供。

产品文档

入门指南

安装包

使用以下任一方法使用 Azure Mixed Reality ARR 客户端库 .NET 安装包。

从 Visual Studio 包管理器安装

Install-Package Azure.MixedReality.RemoteRendering

从 .NET CLI 安装

dotnet add package Azure.MixedReality.RemoteRendering

添加包引用

<PackageReference Include="Azure.MixedReality.RemoteRendering" Version="1.0.0" />

先决条件

您需要 Azure 订阅链接和 Azure 远程渲染账户链接才能使用此软件包。

客户端认证

构建远程渲染客户端需要认证账户和远程渲染端点。在 eastus 区域创建的账户，账户域名形式为 "eastus.mixedreality.azure.com"。存在几种不同的认证方式

• 账户密钥认证
  • 账户密钥能帮助您快速开始使用 Azure 远程渲染。但在将应用程序部署到生产之前，我们建议您更新应用程序以使用 Azure AD 认证。
• Azure Active Directory (AD) 令牌认证
  • 如果您正在构建企业应用程序，并且您的公司使用 Azure AD 作为其身份系统，您可以在应用程序中使用基于用户的 Azure AD 认证。然后，您可以通过现有 Azure AD 安全组授权对 Azure 远程渲染账户的访问。您也可以直接授权组织中用户的访问。
  • 否则，我们建议您从支持您的应用程序的 Web 服务中获取 Azure AD 令牌。我们推荐此方法用于生产应用程序，因为它允许您避免在客户端应用程序中嵌入访问 Azure 空间锚点的凭证。

有关详细说明和信息，请参阅此处。

在所有以下示例中，客户端都是通过 remoteRenderingEndpoint Uri 对象构建的。可用的端点对应于地区，端点的选择决定了服务执行工作所在地区。例如，https://remoterendering.eastus2.mixedreality.azure.com。

注意：对于转换资产，建议选择靠近包含资产的存储区域的地区。

注意：对于渲染，强烈建议选择离使用该服务的设备最近的地区。与服务器通信的时间会影响体验的质量。

使用账户密钥进行认证

使用 AccountKeyCredential 对象使用账户标识符和账户密钥进行认证。

AzureKeyCredential accountKeyCredential = new AzureKeyCredential(accountKey);

RemoteRenderingClient client = new RemoteRenderingClient(remoteRenderingEndpoint, accountId, accountDomain, accountKeyCredential);

使用 AAD 客户端密钥进行认证

使用 ClientSecretCredential 对象执行客户端密钥认证。

TokenCredential credential = new ClientSecretCredential(tenantId, clientId, clientSecret, new TokenCredentialOptions
{
    AuthorityHost = new Uri($"https://login.microsoftonline.com/{tenantId}")
});

RemoteRenderingClient client = new RemoteRenderingClient(remoteRenderingEndpoint, accountId, accountDomain, credential);

使用设备代码进行用户认证

使用 DeviceCodeCredential 对象执行设备代码认证。

Task deviceCodeCallback(DeviceCodeInfo deviceCodeInfo, CancellationToken cancellationToken)
{
    Debug.WriteLine(deviceCodeInfo.Message);
    Console.WriteLine(deviceCodeInfo.Message);
    return Task.FromResult(0);
}

TokenCredential credential = new DeviceCodeCredential(deviceCodeCallback, tenantId, clientId, new TokenCredentialOptions
{
    AuthorityHost = new Uri($"https://login.microsoftonline.com/{tenantId}"),
});

RemoteRenderingClient client = new RemoteRenderingClient(remoteRenderingEndpoint, accountId, accountDomain, credential);

有关使用设备代码认证流的更多信息，请参阅此处。

使用 DefaultAzureCredential 进行动态交互式认证

使用 DefaultAzureCredential 对象并设置 includeInteractiveCredentials: true 来使用默认交互式认证流。

TokenCredential credential = new DefaultAzureCredential(includeInteractiveCredentials: true);

RemoteRenderingClient client = new RemoteRenderingClient(remoteRenderingEndpoint, accountId, accountDomain, credential);

使用静态访问令牌进行认证

您可以将从 Mixed Reality STS 服务中之前检索到的 Mixed Reality 访问令牌作为 AccessToken 传递，以与 Mixed Reality 客户端库一起使用。

// GetMixedRealityAccessTokenFromWebService is a hypothetical method that retrieves
// a Mixed Reality access token from a web service. The web service would use the
// MixedRealityStsClient and credentials to obtain an access token to be returned
// to the client.
AccessToken accessToken = GetMixedRealityAccessTokenFromWebService();

RemoteRenderingClient client = new RemoteRenderingClient(remoteRenderingEndpoint, accountId, accountDomain, accessToken);

关键概念

RemoteRenderingClient

RemoteRenderingClient 是用于访问远程渲染服务的客户端库。它提供了创建和管理资产转换和渲染会话的方法。

示例

• 转换简单资产
• 转换更复杂资产
• 获取资产转换完成后的输出
• 列出转换
• 创建会话
• 扩展会话的租期
• 列出会话
• 停止会话

转换简单资产

我们假设一个RemoteRenderingClient已经按照《客户端认证》部分所述构建。下面的代码片段描述了如何请求将“box.fbx”转换为格式，该文件位于给定URI的blob容器的根目录下。

    AssetConversionInputOptions inputOptions = new AssetConversionInputOptions(storageUri, "box.fbx");
    AssetConversionOutputOptions outputOptions = new AssetConversionOutputOptions(storageUri);
    AssetConversionOptions conversionOptions = new AssetConversionOptions(inputOptions, outputOptions);

    // A randomly generated GUID is a good choice for a conversionId.
    string conversionId = Guid.NewGuid().ToString();

    AssetConversionOperation conversionOperation = client.StartConversion(conversionId, conversionOptions);

输出文件将放置在输入资产旁边。

转换更复杂资产

资产可以引用其他文件，blob容器可以包含属于许多不同资产的文件。在本例中，我们展示了如何使用前缀来组织您的blob，以及如何将资产转换为考虑到这种组织。假设位于inputStorageUri的blob容器包含许多文件，包括“Bicycle/bicycle.gltf”、“Bicycle/bicycle.bin”和“Bicycle/saddleTexture.jpg”。（因此，前缀“Bicycle”非常类似于一个文件夹。）我们想要转换gltf文件，以便它能够访问具有相同前缀的其他文件，而无需转换服务访问任何其他文件。为了保持整洁，我们还想将输出文件写入不同的存储容器，并给予一个共同的前缀：“ConvertedBicycle”。代码示例如下

    AssetConversionInputOptions input = new AssetConversionInputOptions(inputStorageUri, "bicycle.gltf")
    {
        BlobPrefix = "Bicycle"
    };
    AssetConversionOutputOptions output = new AssetConversionOutputOptions(outputStorageUri)
    {
        BlobPrefix = "ConvertedBicycle"
    };
    AssetConversionOptions conversionOptions = new AssetConversionOptions(inputOptions, outputOptions);

    string conversionId = Guid.NewGuid().ToString();

    AssetConversionOperation conversionOperation = client.StartConversion(conversionId, conversionOptions);

注意：当在输入选项中给出了前缀，则输入文件参数假定相对于该前缀。同样的，适用于输出文件参数在输出选项中。

获取资产转换完成后的输出

转换资产可能需要几秒到几小时的时间。此代码使用现有的转换操作并定期轮询，直到完成或失败。默认轮询周期为10秒。请注意，可以通过现有转换的转换ID和一个客户端构建转换操作。

    AssetConversion conversion = conversionOperation.WaitForCompletionAsync().Result;
    if (conversion.Status == AssetConversionStatus.Succeeded)
    {
        Console.WriteLine($"Conversion succeeded: Output written to {conversion.Output.OutputAssetUri}");
    }
    else if (conversion.Status == AssetConversionStatus.Failed)
    {
        Console.WriteLine($"Conversion failed: {conversion.Error.Code} {conversion.Error.Message}");
    }

列出转换

您可以使用getConversions方法获取关于您的转换信息。此方法可能返回尚未开始的、正在运行的以及已经完成的转换。在此示例中，我们只列出最后一天开始的成功转换的输出URI。

    foreach (var conversion in client.GetConversions())
    {
        if ((conversion.Status == AssetConversionStatus.Succeeded) && (conversion.CreatedOn > DateTimeOffset.Now.AddDays(-1)))
        {
            Console.WriteLine($"output asset URI: {conversion.Output.OutputAssetUri}");
        }
    }

创建会话

我们假设一个RemoteRenderingClient已经按照《客户端认证》部分的说明构建。以下代码片段描述了如何请求开始一个新的渲染会话。

    RenderingSessionOptions options = new RenderingSessionOptions(TimeSpan.FromMinutes(30), RenderingServerSize.Standard);

    // A randomly generated GUID is a good choice for a sessionId.
    string sessionId = Guid.NewGuid().ToString();

    StartRenderingSessionOperation startSessionOperation = client.StartSession(sessionId, options);

    RenderingSession newSession = startSessionOperation.WaitForCompletionAsync().Result;
    if (newSession.Status == RenderingSessionStatus.Ready)
    {
        Console.WriteLine($"Session {sessionId} is ready.");
    }
    else if (newSession.Status == RenderingSessionStatus.Error)
    {
        Console.WriteLine($"Session {sessionId} encountered an error: {newSession.Error.Code} {newSession.Error.Message}");
    }

扩展会话的租期

如果会话接近其最大租约时间，但您希望保持其活跃状态，您需要调用以增加其最大租约时间。下面这个例子展示了如何查询当前属性，然后适时延长租约。

注意：运行时SDKs也提供此功能，在许多典型场景中，您会使用它们来延长会话租约。

    RenderingSession currentSession = client.GetSession(sessionId);

    if (currentSession.MaxLeaseTime - DateTimeOffset.Now.Subtract(currentSession.CreatedOn.Value) < TimeSpan.FromMinutes(2))
    {
        TimeSpan newLeaseTime = currentSession.MaxLeaseTime.Value.Add(TimeSpan.FromMinutes(30));

        UpdateSessionOptions longerLeaseSettings = new UpdateSessionOptions(newLeaseTime);

        client.UpdateSession(sessionId, longerLeaseSettings);
    }

列出会话

您可以使用getSessions方法获取有关会话的信息。此方法可能返回尚未开始的和准备就绪的会话。

    foreach (var properties in client.GetSessions())
    {
        if (properties.Status == RenderingSessionStatus.Starting)
        {
            Console.WriteLine($"Session \"{properties.SessionId}\" is starting.");
        }
        else if (properties.Status == RenderingSessionStatus.Ready)
        {
            Console.WriteLine($"Session \"{properties.SessionId}\" is ready at host {properties.Host}");
        }
    }

停止会话

以下代码将停止具有给定id的正在运行的会话。

    client.StopSession(sessionId);

故障排除

有关Azure远程渲染的一般性故障排除建议，请参阅docs.microsoft.com远程渲染故障排除页面。

如果无法提出请求，客户端方法将抛出异常。然而，对于转换和会话来说，请求可以成功，但请求的操作可能不成功。在这种情况下，不会抛出异常，但可以通过检查返回的对象来了解发生了什么。

如果转换中的资产无效，转换操作将返回具有Failed状态的AssetConversion对象并携带详细信息。一旦转换服务能够处理该文件，将在输出容器中写入一个assetName.result.json文件。如果输入资产无效，那么该文件将包含更详细的错误描述。

同样，有时候在请求会话时，会话最终会进入错误状态。startSessionOperation方法会返回一个RenderingSession对象，但该对象将具有错误状态，并携带详细的RemoteRenderingServiceError。

下一步

• 阅读产品文档
• 了解运行时SDK
  • .NET: https://docs.microsoft.com/dotnet/api/microsoft.azure.remoterendering
  • C++: https://docs.microsoft.com/cpp/api/remote-rendering/

贡献

本项目欢迎贡献和建议。大多数贡献都需要你同意一份贡献者许可协议（CLA），阐明你有权、实际上也确实授权我们使用你的贡献。有关详情，请访问https://cla.microsoft.com。

当你提交拉取请求时，一个CLA机器人会自动判断你是否需要提供CLA，并适当装饰PR（例如，标签，注释）。只需遵循机器人的说明。你只需在整个使用我们的CLA的仓库中做一次。

本项目已采用微软开源代码行为准则。有关更多信息，请参阅行为准则FAQ或联系[email protected]提出任何额外的问题或评论。