Use the Azure Frontend APIs for authentication
In this section, we will describe how to use the API for authentication and session management.
Caution
The functions described in this chapter issue REST calls on the server internally. As for all REST calls, sending these commands too frequently will cause the server to throttle and return failure eventually. The value of the SessionGeneralContext.HttpResponseCode member in this case is 429 ("too many requests"). As a rule of thumb, there should be a delay of 5-10 seconds between subsequent calls.
Some functions also return information when it is save to retry. For example RenderingSessionPropertiesResult.MinimumRetryDelay specifies how many seconds to wait before attempting another check. When available, using such a returned value is best, as it allows you to do checks as often as possible, without getting throttled.
SessionConfiguration
SessionConfiguration is used to set up the authentication information for an RemoteRenderingClient instance in the SDK.
The important fields are:
public class SessionConfiguration
{
// Domain that will be used for account authentication for the Azure Remote Rendering service, in the form [region].mixedreality.azure.com.
// [region] should be set to the domain of the Azure Remote Rendering account.
public string AccountDomain;
// Domain that will be used to generate sessions for the Azure Remote Rendering service, in the form [region].mixedreality.azure.com.
// [region] should be selected based on the region closest to the user. For example, westus2.mixedreality.azure.com or westeurope.mixedreality.azure.com.
public string RemoteRenderingDomain;
// Can use one of:
// 1) ID and Key.
// 2) ID and AuthenticationToken.
// 3) ID and AccessToken.
public string AccountId = Guid.Empty.ToString();
public string AccountKey = string.Empty;
public string AuthenticationToken = string.Empty;
public string AccessToken = string.Empty;
}
The C++ counterpart looks like this:
struct SessionConfiguration
{
std::string AccountDomain{};
std::string RemoteRenderingDomain{};
std::string AccountId{};
std::string AccountKey{};
std::string AuthenticationToken{};
std::string AccessToken{};
};
For the region part in the domain, use a region near you.
The account information can be obtained from the portal as described in the retrieve account information paragraph.
Azure Frontend
The relevant classes are RemoteRenderingClient and RenderingSession. RemoteRenderingClient is used for account management and account level functionality, which includes: asset conversion and rendering session creation. RenderingSession is used for session level functionality and it includes: session update, queries, renewing, and decommissioning.
Each opened/created RenderingSession will keep a reference to the frontend that's created it. To cleanly shut down, all sessions must be deallocated before the frontend will be deallocated.
Deallocating a session will not stop the server on Azure, RenderingSession.StopAsync must be called explicitly.
Once a session has been created and its state has been marked as ready, it can connect to the remote rendering runtime with RenderingSession.ConnectAsync.
Threading
All RenderingSession and RemoteRenderingClient async calls are completed in a background thread, not the main application thread.
Conversion APIs
For more information about the conversion service, see the model conversion REST API.
Start asset conversion
async void StartAssetConversion(RemoteRenderingClient client, string storageContainer, string blobinputpath, string bloboutpath, string modelName, string outputName)
{
var result = await client.StartAssetConversionAsync(
new AssetConversionInputOptions(storageContainer, blobinputpath, "", modelName),
new AssetConversionOutputOptions(storageContainer, bloboutpath, "", outputName)
);
}
void StartAssetConversion(ApiHandle<RemoteRenderingClient> client, std::string storageContainer, std::string blobinputpath, std::string bloboutpath, std::string modelName, std::string outputName)
{
AssetConversionInputOptions input;
input.BlobContainerInformation.BlobContainerName = blobinputpath;
input.BlobContainerInformation.StorageAccountName = storageContainer;
input.BlobContainerInformation.FolderPath = "";
input.InputAssetPath = modelName;
AssetConversionOutputOptions output;
output.BlobContainerInformation.BlobContainerName = blobinputpath;
output.BlobContainerInformation.StorageAccountName = storageContainer;
output.BlobContainerInformation.FolderPath = "";
output.OutputAssetPath = outputName;
client->StartAssetConversionAsync(input, output, [](Status status, ApiHandle<AssetConversionResult> result) {
if (status == Status::OK)
{
//use result
}
else
{
printf("Failed to start asset conversion!");
}
});
}
Get conversion status
async void GetConversionStatus(RemoteRenderingClient client, string assetId)
{
AssetConversionStatusResult status = await client.GetAssetConversionStatusAsync(assetId);
// do something with status (e.g. check current status etc.)
}
void GetConversionStatus(ApiHandle<RemoteRenderingClient> client, std::string assetId)
{
client->GetAssetConversionStatusAsync(assetId, [](Status status, ApiHandle<AssetConversionStatusResult> result) {
if (status == Status::OK)
{
// do something with result (e.g. check current status etc.)
}
else
{
printf("Failed to get status of asset conversion!");
}
});
}
Rendering APIs
See the session management REST API for details about session management.
A rendering session can either be created dynamically on the service or an already existing session ID can be 'opened' into an RenderingSession object.
Create rendering session
async void CreateRenderingSession(RemoteRenderingClient client, RenderingSessionVmSize vmSize, int maxLeaseInMinutes)
{
CreateRenderingSessionResult result = await client.CreateNewRenderingSessionAsync(
new RenderingSessionCreationOptions(vmSize, maxLeaseInMinutes / 60, maxLeaseInMinutes % 60));
// if the call was successful, result.Session holds a valid session reference, otherwise check result.Context for error information
}
void CreateRenderingSession(ApiHandle<RemoteRenderingClient> client, RenderingSessionVmSize vmSize, int maxLeaseInMinutes)
{
RenderingSessionCreationOptions params;
params.MaxLeaseInMinutes = maxLeaseInMinutes;
params.Size = vmSize;
client->CreateNewRenderingSessionAsync(params, [](Status status, ApiHandle<CreateRenderingSessionResult> result) {
if (status == Status::OK && result->GetErrorCode() == Result::Success)
{
result->GetSession();
//use res->Result
}
else
{
printf("Failed to create session!");
}
});
}
Open an existing rendering session
Opening an existing session is a synchronous call.
async void CreateRenderingSession(RemoteRenderingClient client, string sessionId)
{
CreateRenderingSessionResult result = await client.OpenRenderingSessionAsync(sessionId);
if (result.ErrorCode == Result.Success)
{
RenderingSession session = result.Session;
// Query session status, etc.
}
}
void CreateRenderingSession(ApiHandle<RemoteRenderingClient> client, std::string sessionId)
{
client->OpenRenderingSessionAsync(sessionId, [](Status status, ApiHandle<CreateRenderingSessionResult> result) {
if (status == Status::OK && result->GetErrorCode()==Result::Success)
{
ApiHandle<RenderingSession> session = result->GetSession();
// Query session status, etc.
}
});
}
Get current rendering sessions
async void GetCurrentRenderingSessions(RemoteRenderingClient client)
{
RenderingSessionPropertiesArrayResult result = await client.GetCurrentRenderingSessionsAsync();
if (result.ErrorCode == Result.Success)
{
RenderingSessionProperties[] properties = result.SessionProperties;
// Query session status, etc.
}
}
void GetCurrentRenderingSessions(ApiHandle<RemoteRenderingClient> client)
{
client->GetCurrentRenderingSessionsAsync([](Status status, ApiHandle<RenderingSessionPropertiesArrayResult> result) {
if (status == Status::OK && result->GetErrorCode() == Result::Success)
{
std::vector<RenderingSessionProperties> properties;
result->GetSessionProperties(properties);
}
else
{
printf("Failed to get current rendering sessions!");
}
});
}
Session APIs
Get rendering session properties
async void GetRenderingSessionProperties(RenderingSession session)
{
RenderingSessionPropertiesResult result = await session.GetPropertiesAsync();
if (result.ErrorCode == Result.Success)
{
RenderingSessionProperties properties = result.SessionProperties;
}
else
{
Console.WriteLine("Failed to get properties of session!");
}
}
void GetRenderingSessionProperties(ApiHandle<RenderingSession> session)
{
session->GetPropertiesAsync([](Status status, ApiHandle<RenderingSessionPropertiesResult> result) {
if (status == Status::OK && result->GetErrorCode() == Result::Success)
{
RenderingSessionProperties properties = result->GetSessionProperties();
}
else
{
printf("Failed to get properties of session!");
}
});
}
Update rendering session
async void UpdateRenderingSession(RenderingSession session, int updatedLeaseInMinutes)
{
SessionContextResult result = await session.RenewAsync(
new RenderingSessionUpdateOptions(updatedLeaseInMinutes / 60, updatedLeaseInMinutes % 60));
if (result.ErrorCode == Result.Success)
{
Console.WriteLine("Rendering session renewed succeeded!");
}
else
{
Console.WriteLine("Failed to renew rendering session!");
}
}
void UpdateRenderingSession(ApiHandle<RenderingSession> session, int updatedLeaseInMinutes)
{
RenderingSessionUpdateOptions params;
params.MaxLeaseInMinutes = updatedLeaseInMinutes;
session->RenewAsync(params, [](Status status, ApiHandle<SessionContextResult> result) {
if (status == Status::OK && result->GetErrorCode() == Result::Success)
{
printf("Rendering session renewed succeeded!");
}
else
{
printf("Failed to renew rendering session!");
}
});
}
Stop rendering session
async void StopRenderingSession(RenderingSession session)
{
SessionContextResult result = await session.StopAsync();
if (result.ErrorCode == Result.Success)
{
Console.WriteLine("Rendering session stopped successfully!");
}
else
{
Console.WriteLine("Failed to stop rendering session!");
}
}
void StopRenderingSession(ApiHandle<RenderingSession> session)
{
session->StopAsync([](Status status, ApiHandle<SessionContextResult> result) {
if (status == Status::OK && result->GetErrorCode() == Result::Success)
{
printf("Rendering session stopped successfully!");
}
else
{
printf("Failed to stop rendering session!");
}
});
}
Connect to ARR inspector
async void ConnectToArrInspector(RenderingSession session)
{
string htmlPath = await session.ConnectToArrInspectorAsync();
#if WINDOWS_UWP
UnityEngine.WSA.Application.InvokeOnUIThread(async () =>
{
var file = await Windows.Storage.StorageFile.GetFileFromPathAsync(htmlPath);
await Windows.System.Launcher.LaunchFileAsync(file);
}, true);
#else
InvokeOnAppThreadAsync(() =>
{
System.Diagnostics.Process.Start("file:///" + htmlPath);
});
#endif
}
void ConnectToArrInspector(ApiHandle<RenderingSession> session)
{
session->ConnectToArrInspectorAsync([](Status status, std::string result) {
if (status == Status::OK)
{
// Launch the html file with default browser
std::string htmlPath = "file:///" + result;
ShellExecuteA(NULL, "open", htmlPath.c_str(), NULL, NULL, SW_SHOWDEFAULT);
}
else
{
printf("Failed to connect to ARR inspector!");
}
});
}
Next steps
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for