Use case: Manage the versions of an asset

You can use the Unity Cloud Assets package to:

search the versions of an asset.
freeze a version.
create an editable version from a frozen version.

The SDK supports several workflows for users with different roles.

Organization or Asset Manager Project role	List versions	Freeze versions	Create unfrozen versions
`Asset Management Viewer`	no	no	no
`Asset Management Consumer`	yes	no	no
`Asset Management Contributor`	yes	yes	yes
`Organization Owner`	yes	yes	yes

Before you start

Before you start, you must:

Set up a Unity scene in the Unity Editor with an Organization and Project browser. See Get started with Assets for more information.
Have some assets in the cloud. There are several ways to do so:
- You can create assets through the Get started with Assets.
- You can create assets through the dashboard; see the Managing assets on the dashboard documentation.

How do I...?

List an asset's versions

To list version, open the AssetManagementBehaviour script you created and add the following code to the end of the class:


public List<IAsset> AssetVersions { get; private set; }

VersionQueryBuilder m_CurrentQuery;

public async Task SearchVersions(string sortingField, SortingOrder sortingOrder)
{
    m_CurrentQuery = CurrentAsset.QueryVersions()
        .OrderBy(sortingField, sortingOrder);

    await PopulateVersions(m_CurrentQuery);
}

async Task PopulateVersions(VersionQueryBuilder query)
{
    if (query == null) return;

    var results = query.ExecuteAsync(CancellationToken.None);

    AssetVersions = new List<IAsset>();
    await foreach (var asset in results)
    {
        AssetVersions ??= new List<IAsset>();
        AssetVersions.Add(asset);
    }
}

The code snippet does the following:

Creates a query to search the versions of an asset.
Populates a list of versions.

Freeze a version

To freeze the editable version of an asset, follow these steps:

Open the AssetManagementBehaviour script you created.
Add the following code to the end of the class:


public async Task FreezeVersion(IAsset asset)
{
    var sequenceNumber = await asset.FreezeAsync("Use case coding example submission.", CancellationToken.None);

    var tasks = AssetVersions.Select(version => version.RefreshAsync(CancellationToken.None)).ToList();
    await Task.WhenAll(tasks);

    Debug.Log($"Version frozen with sequence number: {sequenceNumber}");
}

The code snippet does the following:

Freezes the provided asset.
Refreshes each listed versions.
Prints a message to the console on success.

Create a new version

To create a new version of an asset, follow these steps:

Open the AssetManagementBehaviour script you created.
Add the following code to the end of the class:


public async Task CreateVersion(IAsset asset)
{
    var version = await asset.CreateUnfrozenVersionAsync(CancellationToken.None);
    await PopulateVersions(m_CurrentQuery);

    Debug.Log($"New version created with version: {version.Descriptor.AssetVersion}");
}

The code snippet does the following:

Creates a new version of the asset from the provided frozen version.
Prints a message to the console on success.

Add the UI for managing versions

To create UI for managing the versions of an asset, follow these steps:

In your Unity Project window, go to Assets > Scripts.
Select and hold the Assets/Scripts folder.
Go to Create > C# Script. Name your script UseCaseVersionSearchExampleUI.
Open the UseCaseVersionSearchExampleUI script you created and replace the contents of the file with the following code sample:


using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading;
using System.Threading.Tasks;
using Unity.Cloud.Assets;
using Unity.Cloud.Common;
using UnityEngine;

public class UseCaseVersionSearchExampleUI : IAssetManagementUI
{
    readonly AssetManagementBehaviour m_Behaviour;

    public UseCaseVersionSearchExampleUI(AssetManagementBehaviour behaviour)
    {
        m_Behaviour = behaviour;
    }

    public void OnGUI() { }
}

In the same script, replace the OnGUI function with the following code:


string m_SortingField = "versionNumber";
SortingOrder m_SortingOrder = SortingOrder.Descending;
AssetId m_CurrentAssetId;
IAsset m_CurrentVersion;

public void OnGUI()
{
    if (m_Behaviour.CurrentAsset == null) return;

    if (m_Behaviour.CurrentAsset.Descriptor.AssetId != m_CurrentAssetId)
    {
        m_CurrentAssetId = m_Behaviour.CurrentAsset.Descriptor.AssetId;
        m_CurrentVersion = null;
        SearchAssetVersions();
    }

    GUILayout.Space(15f);

    GUILayout.BeginVertical();

    GUILayout.Label("Sorting Field:");
    m_SortingField = GUILayout.TextField(m_SortingField);

    GUILayout.Label("Sorting Order:");
    m_SortingOrder = (SortingOrder) GUILayout.SelectionGrid((int) m_SortingOrder, new[] {"Ascending", "Descending"}, 2);

    if (GUILayout.Button("Search"))
    {
        SearchAssetVersions();
    }

    GUILayout.Space(15f);

    GUILayout.Label("Versions: ");

    if (m_Behaviour.AssetVersions == null)
    {
        GUILayout.Label("Loading...");
    }
    else if (m_Behaviour.AssetVersions.Count == 0)
    {
        GUILayout.Label("No versions found.");
    }
    else
    {
        foreach (var asset in m_Behaviour.AssetVersions)
        {
            DisplayVersion(asset);
        }
    }

    GUILayout.EndVertical();

    DisplayCurrentVersion();
}

void SearchAssetVersions()
{
    if (string.IsNullOrEmpty(m_SortingField)) return;

    _ = m_Behaviour.SearchVersions(m_SortingField, m_SortingOrder);
}

void DisplayVersion(IAsset asset)
{
    var version = asset.IsFrozen ? $"Ver. {asset.FrozenSequenceNumber}" : $"WIP from Ver. {asset.ParentFrozenSequenceNumber}";

    var labels = asset.Labels.Select(x => x.LabelName).ToArray();
    if (labels.Length > 0)
    {
        version += $" ({string.Join(", ", labels)})";
    }

    GUILayout.BeginHorizontal();

    GUILayout.Label(version, GUILayout.ExpandWidth(true));

    if (GUILayout.Button("Select", GUILayout.Width(60)))
    {
        m_CurrentVersion = asset;
    }

    GUILayout.EndHorizontal();
}

void DisplayCurrentVersion()
{
    if (m_CurrentVersion == null)
    {
        GUILayout.Label("! No version selected. !");
        return;
    }

    GUILayout.BeginVertical();

    GUILayout.Label($"Version: {m_CurrentVersion.Descriptor.AssetVersion}");
    if (m_CurrentVersion.ParentFrozenSequenceNumber > 0)
    {
        GUILayout.Label($"Parent Sequence Number: {m_CurrentVersion.ParentFrozenSequenceNumber}");
    }

    GUILayout.Label($"Frozen: {m_CurrentVersion.IsFrozen}");

    if (m_CurrentVersion.IsFrozen)
    {
        GUILayout.Label($"Frozen Sequence Number: {m_CurrentVersion.FrozenSequenceNumber}");

        if (GUILayout.Button("Create new version"))
        {
            _ = m_Behaviour.CreateVersion(m_CurrentVersion);
        }
    }
    else
    {
        if (GUILayout.Button("Freeze version"))
        {
            _ = m_Behaviour.FreezeVersion(m_CurrentVersion);
        }
    }

    GUILayout.EndVertical();
}

Open the AssetManagementUI script you created and replace the contents of the Awake function with the following code:


m_UI.Add(new OrganizationSelectionExampleUI(m_Behaviour));
m_UI.Add(new ProjectSelectionExampleUI(m_Behaviour));
m_UI.Add(new AssetSelectionExampleUI(m_Behaviour));
m_UI.Add(new UseCaseVersionSearchExampleUI(m_Behaviour));

The code snippet does the following:

Provides fields to specify the sorting field and order for the list of versions.
Provides a UI button to refresh the list of versions.
Displays the list of versions with buttons to select a version.
When a version is selected, the UI displays information on this version and provides buttons to freeze or create a new version based on the frozen state of the selected version.

Going further

For a further examples of managing versions, see the Asset Management sample.