Azure Remote Rendering-Clientbibliothek für .NET – Version 1.1.0

Artikel
04/27/2023

Azure Remote Rendering (ARR) ist ein Dienst, mit dem Sie interaktive 3D-Inhalte in der Cloud in hoher Qualität rendern und in Echtzeit an Geräte streamen können, z. B. HoloLens 2.

Dieses SDK bietet Funktionen zum Konvertieren von Ressourcen in das von der Runtime erwartete Format und zum Verwalten der Lebensdauer von Remoterenderingsitzungen.

HINWEIS: Sobald eine Sitzung ausgeführt wird, stellt eine Clientanwendung mithilfe eines der "Runtime-SDKs" eine Verbindung mit ihr her. Diese SDKs sind so konzipiert, dass sie die Anforderungen einer interaktiven Anwendung mit 3D-Rendering optimal unterstützen. Sie sind in (.net oder (C++) verfügbar.

Produktdokumentation

Erste Schritte

Installieren des Pakets

Installieren Sie die Azure Mixed Reality ARR-Clientbibliothek für .NET mithilfe einer der folgenden Methoden.

Über den Visual Studio-Paket-Manager:

Install-Package Azure.MixedReality.RemoteRendering

Über die .NET CLI

dotnet add package Azure.MixedReality.RemoteRendering

Fügen Sie einen Paketverweis hinzu:

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

Voraussetzungen

Sie benötigen ein Azure-Abonnement und ein Azure Remote Rendering-Konto, um dieses Paket verwenden zu können.

Authentifizieren des Clients

Das Erstellen eines Remoterenderingclients erfordert ein authentifiziertes Konto und einen Remoterenderingendpunkt. Für ein Konto, das in der Region eastus erstellt wurde, hat die Kontodomäne das Formular "eastus.mixedreality.azure.com". Es gibt verschiedene Arten der Authentifizierung:

Kontoschlüsselauthentifizierung
- Mit Kontoschlüsseln können Sie schnell mit der Verwendung von Azure Remote Rendering beginnen. Aber bevor Sie Ihre Anwendung in der Produktionsumgebung bereitstellen, empfiehlt es sich, dass Sie Ihre App für die Verwendung von Azure AD-Authentifizierung aktualisieren.
Azure Active Directory(AD)-Tokenauthentifizierung
- Wenn Sie eine Unternehmensanwendung entwickeln und Ihr Unternehmen Azure AD als Identitätssystem verwendet, können Sie die benutzerbasierte Azure AD-Authentifizierung in Ihrer App verwenden. Anschließend gewähren Sie Mithilfe Ihrer vorhandenen Azure AD-Sicherheitsgruppen Zugriff auf Ihre Azure Remote Rendering-Konten. Sie können Benutzern in Ihrer Organisation Zugriff auch direkt gewähren.
- Andernfalls empfiehlt es sich, Azure AD-Token von einem Webdienst abzurufen, der Ihre App unterstützt. Wir empfehlen diese Methode für Produktionsanwendungen, weil diese es Ihnen ermöglicht, die Einbettung der Anmeldeinformationen für den Zugriff auf Azure Spatial Anchors in Ihre Clientanwendung zu vermeiden.

Ausführliche Anweisungen und Informationen finden Sie hier .

In allen folgenden Beispielen wird der Client mit einem remoteRenderingEndpoint URI-Objekt erstellt. Die verfügbaren Endpunkte entsprechen Regionen, und die Auswahl des Endpunkts bestimmt die Region, in der der Dienst seine Arbeit ausführt. z. B. https://remoterendering.eastus2.mixedreality.azure.com.

HINWEIS: Zum Konvertieren von Ressourcen empfiehlt es sich, eine Region in der Nähe des Speichers zu wählen, der die Ressourcen enthält.

HINWEIS: Zum Rendern wird dringend empfohlen, dass Sie die region auswählen, die den Geräten, die den Dienst verwenden, am nächsten liegt. Die Für die Kommunikation mit dem Server benötigte Zeit wirkt sich auf die Qualität der Benutzeroberfläche aus.

Authentifizieren mit Kontoschlüsselauthentifizierung

Verwenden Sie das AccountKeyCredential -Objekt, um einen Kontobezeichner und einen Kontoschlüssel zur Authentifizierung zu verwenden:

AzureKeyCredential accountKeyCredential = new AzureKeyCredential(accountKey);

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

Authentifizieren mit einem AAD-Clientgeheimnis

Verwenden Sie das ClientSecretCredential -Objekt, um die geheime Clientauthentifizierung durchzuführen.

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);

Authentifizieren eines Benutzers mithilfe der Gerätecodeauthentifizierung

Verwenden Sie das DeviceCodeCredential -Objekt, um die Gerätecodeauthentifizierung durchzuführen.

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);

Weitere Informationen zur Verwendung des Authentifizierungsflows für Gerätecode finden Sie hier .

Interaktive Authentifizierung mit DefaultAzureCredential

Verwenden Sie das DefaultAzureCredential -Objekt mit includeInteractiveCredentials: true , um den standardmäßigen interaktiven Authentifizierungsflow zu verwenden:

TokenCredential credential = new DefaultAzureCredential(includeInteractiveCredentials: true);

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

Authentifizieren mit einem statischen Zugriffstoken

Sie können ein Mixed Reality-Zugriffstoken als zuvor AccessToken aus dem Mixed Reality STS-Dienst abgerufenen übergeben, um mit einer Mixed Reality Clientbibliothek verwendet zu werden:

// 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);

Wichtige Begriffe

RemoteRenderingClient

Der RemoteRenderingClient ist die Clientbibliothek, die für den Zugriff auf den RemoteRenderingService verwendet wird. Es bietet Methoden zum Erstellen und Verwalten von Ressourcenkonvertierungen und Renderingsitzungen.

Beispiele

Konvertieren einer einfachen Ressource
Konvertieren einer komplexeren Ressource
Abrufen der Ausgabe, wenn eine Ressourcenkonvertierung abgeschlossen ist
Listenkonvertierungen
Erstellen einer Sitzung
Verlängern der Leasezeit einer Sitzung
Listensitzungen
Beenden einer Sitzung

Konvertieren einer einfachen Ressource

Wir gehen davon aus, dass ein RemoteRenderingClient wie im Abschnitt Authentifizieren des Clients beschrieben erstellt wurde. Der folgende Codeausschnitt beschreibt, wie Sie anfordern, dass "box.fbx", das sich am Stamm des Blobcontainers am angegebenen URI befindet, konvertiert wird.

    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);

Die Ausgabedateien werden neben dem Eingabeobjekt platziert.

Konvertieren einer komplexeren Ressource

Ressourcen können auf andere Dateien verweisen, und Blobcontainer können Dateien enthalten, die zu vielen verschiedenen Ressourcen gehören. In diesem Beispiel wird gezeigt, wie Präfixe verwendet werden können, um Ihre Blobs zu organisieren und ein Asset zu konvertieren, um diese organization zu berücksichtigen. Angenommen, der Blobcontainer bei inputStorageUri enthält viele Dateien, darunter "Bicycle/bicycle.gltf", "Bicycle/bicycle.bin" und "Bicycle/saddleTexture.jpg". (Das Präfix "Bicycle" verhält sich also sehr wie ein Ordner.) Wir möchten den gltf konvertieren, sodass er Zugriff auf die anderen Dateien hat, die das Präfix teilen, ohne dass der Konvertierungsdienst auf andere Dateien zugreifen muss. Zur Übersichtlichkeit möchten wir auch, dass die Ausgabedateien in einen anderen Speichercontainer geschrieben werden und ein gemeinsames Präfix erhalten: "ConvertedBicycle". Der Code lautet wie folgt:

    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);

HINWEIS: Wenn in den Eingabeoptionen ein Präfix angegeben wird, wird davon ausgegangen, dass der Parameter der Eingabedatei relativ zu diesem Präfix ist. Gleiches gilt für den Ausgabedateiparameter in den Ausgabeoptionen.

Abrufen der Ausgabe, wenn eine Ressourcenkonvertierung abgeschlossen ist

Das Konvertieren eines Assets kann zwischen Sekunden und Stunden dauern. Dieser Code verwendet eine vorhandene konvertierungOperation und ruft regelmäßig ab, bis die Konvertierung abgeschlossen oder fehlgeschlagen ist. Der Standardabfragezeitraum beträgt 10 Sekunden. Beachten Sie, dass eine conversionOperation aus der conversionId einer vorhandenen Konvertierung und eines Clients erstellt werden kann.

    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}");
    }

Listenkonvertierungen

Mit der getConversions -Methode können Sie Informationen zu Ihren Konvertierungen abrufen. Diese Methode kann Konvertierungen zurückgeben, die noch gestartet werden müssen, Konvertierungen, die ausgeführt werden, und Konvertierungen, die abgeschlossen sind. In diesem Beispiel werden nur die Ausgabe-URIs der erfolgreichen Konvertierungen aufgelistet, die am letzten Tag gestartet wurden.

    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}");
        }
    }

Erstellen einer Sitzung

    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}");
    }

Verlängern der Leasezeit einer Sitzung

Wenn sich eine Sitzung ihrer maximalen Leasezeit nähert, sie aber am Leben erhalten soll, müssen Sie einen Aufruf tätigen, um die maximale Leasezeit zu erhöhen. In diesem Beispiel wird gezeigt, wie Sie die aktuellen Eigenschaften abfragen und die Lease dann erweitern, wenn sie bald abläuft.

HINWEIS: Die Laufzeit-SDKs bieten auch diese Funktionalität, und in vielen typischen Szenarien würden Sie sie verwenden, um die Sitzungsleases zu erweitern.

    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);
    }

Listensitzungen

Mit der getSessions -Methode können Sie Informationen zu Ihren Sitzungen abrufen. Diese Methode gibt möglicherweise Sitzungen zurück, die noch gestartet werden müssen, und Sitzungen, die bereit sind.

    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}");
        }
    }

Beenden einer Sitzung

Der folgende Code beendet eine ausgeführte Sitzung mit der angegebenen ID.

    client.StopSession(sessionId);

Problembehandlung

Allgemeine Hinweise zur Problembehandlung in Bezug auf Azure Remote Rendering finden Sie auf der Seite Problembehandlung für Remoterendering auf docs.microsoft.com.

Die Clientmethoden lösen Ausnahmen aus, wenn die Anforderung nicht gestellt werden kann. Bei Konvertierungen und Sitzungen können die Anforderungen jedoch erfolgreich sein, aber der angeforderte Vorgang ist möglicherweise nicht erfolgreich. In diesem Fall wird keine Ausnahme ausgelöst, aber die zurückgegebenen Objekte können überprüft werden, um zu verstehen, was passiert ist.

Wenn das Objekt in einer Konvertierung ungültig ist, gibt der Konvertierungsvorgang ein AssetConversion-Objekt mit einem Failed status zurück, das einen RemoteRenderingServiceError mit Details enthält. Sobald der Konvertierungsdienst die Datei verarbeiten kann, wird eine <datei assetName.result.json> in den Ausgabecontainer geschrieben. Wenn das Eingabeobjekt ungültig ist, enthält diese Datei eine ausführlichere Beschreibung des Problems.

Auf ähnliche Weise endet die Sitzung manchmal in einem Fehlerzustand, wenn eine Sitzung angefordert wird. Die startSessionOperation-Methode gibt ein RenderingSession-Objekt zurück, aber dieses Objekt verfügt über eine Error-status und enthält einen RemoteRenderingServiceError mit Details.

Nächste Schritte

Lesen Sie die Produktdokumentation
Erfahren Sie mehr über die Laufzeit-SDKs:
- .NET: https://docs.microsoft.com/dotnet/api/microsoft.azure.remoterendering
- C++: https://docs.microsoft.com/cpp/api/remote-rendering/

Mitwirken

Beiträge und Vorschläge für dieses Projekt sind willkommen. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. Ausführliche Informationen finden Sie unter https://cla.microsoft.com.

Wenn Sie einen Pull Request (PR) übermitteln, überprüft ein CLA-Bot automatisch, ob Sie eine Lizenzvereinbarung bereitstellen und den PR entsprechend ergänzen müssen (z.B. mit einer Bezeichnung oder einem Kommentar). Führen Sie einfach die Anweisungen des Bots aus. Sie müssen dies nur einmal für alle Repositorys ausführen, die unsere CLA verwenden.

Für dieses Projekt gelten die Microsoft-Verhaltensregeln für Open Source (Microsoft Open Source Code of Conduct). Weitere Informationen finden Sie in den häufig gestellten Fragen zum Verhaltenskodex. Sie können sich auch an opencode@microsoft.com wenden, wenn Sie weitere Fragen oder Anmerkungen haben.

Freigeben über