Use case: Manage asset to asset references

You can use the Unity Cloud Assets package to:

Query the references of an asset.
Create and delete references between assets.

The SDK supports different workflows for users with different roles.

Organization or Asset Manager Project role	List an asset's references	Add/remove asset references
`Asset Management Viewer`	yes	no
`Asset Management Consumer`	yes	no
`Asset Management Contributor`	yes	yes
`Organization Owner`	yes	yes

Before you start

Before you start, you need 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 the references of an asset

To list the references of an asset, do the following:

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


public Dictionary<string, List<IAssetReference>> References { get; } = new();

public async Task ListReferencesAsync(AssetId assetId, string version, string id)
{
    References.Remove(id);

    var filter = new AssetReferenceSearchFilter();
    if (!string.IsNullOrEmpty(version))
    {
        filter.AssetVersion.WhereEquals(new AssetVersion(version));
    }

    try
    {
        var references = CurrentProject.QueryAssetReferences(assetId)
            .SelectWhereMatchesFilter(filter)
            .ExecuteAsync(default);

        var referencesList = new List<IAssetReference>();
        References.Add(id, referencesList);
        await foreach (var reference in references)
        {
            referencesList.Add(reference);
        }
    }
    catch (Exception e)
    {
        Debug.LogError(e);
    }
}

The code snippet populates a list of the references of the specified asset.

Add a reference between assets

To add a reference between assets, do the following:

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


public async Task CreateReferenceAsync(IAsset asset, AssetId referencedAssetId, string version, string label)
{
    IAssetReference assetReference = null;

    try
    {
        if (!string.IsNullOrEmpty(version))
        {
            assetReference = await asset.AddReferenceAsync(referencedAssetId, new AssetVersion(version), default);
        }
        else
        {
            assetReference = await asset.AddReferenceAsync(referencedAssetId, label, default);
        }
    }
    catch (Exception e)
    {
        Debug.LogError(e);
    }

    if (assetReference != null)
    {
        References["Source"].Add(assetReference);
        References["Target"].Add(assetReference);
        Debug.Log($"Reference created: {assetReference.ReferenceId}");
    }
}

The code snippet creates a new reference between a source asset and a target asset and prints a message to the console on success.

Remove a reference between assets

To remove a reference between assets, do the following:

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


public async Task RemoveReferenceAsync(IAsset asset, string referenceId)
{
    try
    {
        await asset.RemoveReferenceAsync(referenceId, default);
        References["Source"].RemoveAll(reference => reference.ReferenceId == referenceId);
        References["Target"].RemoveAll(reference => reference.ReferenceId == referenceId);
    }
    catch (Exception e)
    {
        Debug.LogError(e);
    }
}

The code snippet removes the reference between the source asset and the target asset and prints a message to the console on success.

Add the UI for viewing and creating references

To create UI for displaying asset references, 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 UseCaseManageAssetReferencesExampleUI.
Open the UseCaseManageAssetReferencesExampleUI script you created and replace the contents of the file with the following code sample:


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

public class UseCaseManageAssetReferencesExampleUI : IAssetManagementUI
{
    readonly AssetManagementBehaviour m_Behaviour;

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

    public void OnGUI() { }
}

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


enum SelectionMode
{
    Source,
    Target,
}

IAsset m_SelectedAsset;

SelectionMode m_SelectionMode;
Vector2 m_SourceScrollPosition;
Vector2 m_TargetScrollPosition;

IAsset m_SourceAsset;
string m_SourceVersion;

IAsset m_TargetAsset;
string m_TargetVersion;
string m_TargetLabel;

public void OnGUI()
{
    if (!m_Behaviour.IsProjectSelected)
    {
        m_SelectedAsset = null;
        m_SourceAsset = null;
        m_TargetAsset = null;
        return;
    }

    if (m_SelectedAsset != m_Behaviour.CurrentAsset)
    {
        m_SelectedAsset = m_Behaviour.CurrentAsset;

        OnCurrentAssetChanged();
    }

    GUILayout.BeginVertical();

    m_SelectionMode = (SelectionMode) GUILayout.SelectionGrid((int) m_SelectionMode, new[] {"Source", "Target"}, 2);

    switch (m_SelectionMode)
    {
        case SelectionMode.Source:
            m_Behaviour.CurrentAsset = m_SourceAsset;
            break;

        case SelectionMode.Target:
            m_Behaviour.CurrentAsset = m_TargetAsset;
            break;
    }

    if (GUILayout.Button("Create Reference"))
    {
        _ = m_Behaviour.CreateReferenceAsync(m_SourceAsset, m_TargetAsset.Descriptor.AssetId, m_TargetVersion, m_TargetLabel);
    }

    GUILayout.BeginHorizontal(GUILayout.ExpandWidth(true));

    var dummyString = string.Empty;
    DisplayAssetReference(m_SourceAsset, ref m_SourceVersion, ref dummyString, SelectionMode.Source);
    DisplayAssetReference(m_TargetAsset, ref m_TargetVersion, ref m_TargetLabel, SelectionMode.Target);

    GUILayout.EndHorizontal();

    GUILayout.EndVertical();
}

void DisplayAssetReference(IAsset asset, ref string version, ref string label, SelectionMode selectionMode)
{
    if (asset == null)
    {
        GUILayout.Label("No asset selected");
        return;
    }

    GUILayout.BeginVertical();

    GUILayout.Label($"{selectionMode} - {asset.Name}");

    GUILayout.Space(5);

    GUILayout.Label("Id: " + asset.Descriptor.AssetId);

    GUILayout.BeginHorizontal();
    GUILayout.Label("Ver.", GUILayout.Width(40));
    version = GUILayout.TextField(version);
    GUILayout.EndHorizontal();

    if (selectionMode == SelectionMode.Target)
    {
        GUILayout.BeginHorizontal();
        GUILayout.Label("Label", GUILayout.Width(40));
        label = GUILayout.TextField(label);
        GUILayout.EndHorizontal();
    }

    GUILayout.BeginHorizontal();

    if (GUILayout.Button("Refresh Ver.", GUILayout.Width(100)))
    {
        _ = m_Behaviour.ListReferencesAsync(asset.Descriptor.AssetId, version, selectionMode.ToString());
    }

    if (GUILayout.Button("Show All", GUILayout.Width(100)))
    {
        _ = m_Behaviour.ListReferencesAsync(asset.Descriptor.AssetId, string.Empty, selectionMode.ToString());
    }

    GUILayout.EndHorizontal();

    DisplayReferences(selectionMode, asset);

    GUILayout.EndVertical();
}

void DisplayReferences(SelectionMode selectionMode, IAsset asset)
{
    GUILayout.Label("References:");
    if (m_Behaviour.References.TryGetValue(selectionMode.ToString(), out var references))
    {
        switch (selectionMode)
        {
            case SelectionMode.Source:
                m_SourceScrollPosition = GUILayout.BeginScrollView(m_SourceScrollPosition);
                break;
            case SelectionMode.Target:
                m_TargetScrollPosition = GUILayout.BeginScrollView(m_TargetScrollPosition);
                break;
        }

        foreach (var reference in references)
        {
            GUILayout.Space(5);

            GUILayout.BeginHorizontal();
            GUILayout.Label($"Ref. {reference.ReferenceId}");
            if (GUILayout.Button("Remove", GUILayout.Width(80)))
            {
                _ = m_Behaviour.RemoveReferenceAsync(asset, reference.ReferenceId);
            }

            GUILayout.EndHorizontal();

            var isSource = reference.SourceAssetId == asset.Descriptor.AssetId;
            string assetVersion;
            string referencedId;
            string referencedVersion;
            if (isSource)
            {
                assetVersion = reference.SourceAssetVersion.ToString();
                referencedId = reference.TargetAssetId.ToString();
                referencedVersion = reference.TargetLabel ?? reference.TargetAssetVersion.ToString();
            }
            else
            {
                assetVersion = reference.TargetLabel ?? reference.TargetAssetVersion.ToString();
                referencedId = reference.SourceAssetId.ToString();
                referencedVersion = reference.SourceAssetVersion.ToString();
            }

            GUILayout.Label($"    Ver. {assetVersion}");
            GUILayout.Label($"     {(isSource ? "Depends on" : "Referenced by")}");
            GUILayout.Label($"    - id: {referencedId}");
            GUILayout.Label($"    - ver: {referencedVersion}");
        }

        GUILayout.EndScrollView();
    }
    else
    {
        GUILayout.Label("Loading...");
    }
}

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

    switch (m_SelectionMode)
    {
        case SelectionMode.Source:
            if (m_Behaviour.CurrentAsset == null)
            {
                m_SourceAsset = null;
                m_SourceVersion = string.Empty;
            }
            else
            {
                m_SourceAsset = m_Behaviour.CurrentAsset;
                m_SourceVersion = m_SourceAsset.Descriptor.AssetVersion.ToString();
                _ = m_Behaviour.ListReferencesAsync(m_SourceAsset.Descriptor.AssetId, m_SourceVersion, SelectionMode.Source.ToString());
            }

            break;

        case SelectionMode.Target:
            if (m_Behaviour.CurrentAsset == null)
            {
                m_TargetAsset = null;
                m_TargetVersion = string.Empty;
                m_TargetLabel = string.Empty;
            }
            else
            {
                m_TargetAsset = m_Behaviour.CurrentAsset;
                m_TargetVersion = string.IsNullOrEmpty(m_TargetLabel) ? m_TargetAsset.Descriptor.AssetVersion.ToString() : string.Empty;
                _ = m_Behaviour.ListReferencesAsync(m_TargetAsset.Descriptor.AssetId, m_TargetVersion, SelectionMode.Target.ToString());
            }

            break;
    }
}

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 UseCaseManageAssetReferencesExampleUI(m_Behaviour));

The code snippet displays the following UI elements:

A selection grid to specify which entry to update on asset selection; the Source or Target.
A list of references for the selected Source asset.
A list of references for the selected Target asset.
UI buttons beside each reference to remove the reference.
A UI button to create a reference between the selected Source and Target assets.