sdk/StackReference: Add GetOutputDetailsAsync (#103)

This is the C# equivalent of StackReference.GetOutputDetails
that was added to:

- Go SDK in pulumi/pulumi#12034
- Python SDK in pulumi/pulumi#12071
- Node SDK in pulumi/pulumi#12072

It introduces a GetOutputDetailsAsync method
that returns a StackReferenceOutputDetails promise,
allowing looking at the results without going through an Output type.

**Testing**: As with Node (pulumi/pulumi#12072), C# appears to promote
the entire dictionary to secret if one of the values is secret.
Therefore, this needed separate tests for each case.

Refs pulumi/pulumi#10839, pulumi/pulumi#5035

Author: abhinav

CHANGELOG_PENDING.md

@@ -4,4 +4,7 @@
   - [sdk/providers] Updated names of "Olds" and "News" to make it clear if they are old/new inputs or state. Also removed the GetPluginInfo overload, version should now be passed into the main Serve method (defaults to the assembly version).
     [#99](https://github.com/pulumi/pulumi-dotnet/pull/99)
 
+  - [sdk] Added `StackReference.GetOutputDetailsAsync` to retrieve output values from stack references directly.
+    [#103](https://github.com/pulumi/pulumi-dotnet/pull/103)
+
 ### Bug Fixes

sdk/Pulumi.Tests/Resources/StackReferenceOutputDetailsTests.cs

@@ -0,0 +1,107 @@
+// Copyright 2016-2023, Pulumi Corporation
+
+using System;
+using System.Collections.Generic;
+using System.Threading.Tasks;
+using Pulumi.Testing;
+using Xunit;
+
+namespace Pulumi.Tests.Resources
+{
+    public class StackReferenceOutputDetailsTests
+    {
+        [Fact]
+        public async void SupportsPlainText()
+        {
+            var mocks = new FakeStackOutputMocks("bucket", "my-bucket");
+            var options = new TestOptions();
+
+            var (resources, outputs) = await Deployment.TestAsync(mocks, options, () =>
+            {
+                var stackReference = new StackReference("my-stack");
+                return new Dictionary<string, object?>()
+                {
+                    ["bucket"] = stackReference.GetOutputDetailsAsync("bucket"),
+                };
+            });
+
+            var bucket = await (outputs["bucket"] as Task<StackReferenceOutputDetails>);
+            Assert.Equal("my-bucket", bucket.Value);
+            Assert.Null(bucket.SecretValue);
+        }
+
+        [Fact]
+        public async void SupportsSecrets()
+        {
+            var mocks = new FakeStackOutputMocks("secret", Output.CreateSecret("my-bucket"));
+            var options = new TestOptions();
+
+            var (resouces, outputs) = await Deployment.TestAsync(mocks, options, () =>
+            {
+                var stackReference = new StackReference("my-stack");
+                return new Dictionary<string, object?>()
+                {
+                    ["secret"] = stackReference.GetOutputDetailsAsync("secret"),
+                };
+            });
+
+            var secret = await (outputs["secret"] as Task<StackReferenceOutputDetails>);
+            Assert.Null(secret.Value);
+            Assert.Equal("my-bucket", secret.SecretValue);
+        }
+
+        [Fact]
+        public async void Unknowns()
+        {
+            var mocks = new FakeStackOutputMocks("something", "foo");
+            var options = new TestOptions();
+
+            var (resources, outputs) = await Deployment.TestAsync(mocks, options, () =>
+            {
+                var stackReference = new StackReference("my-stack");
+                return new Dictionary<string, object?>()
+                {
+                    ["unknown"] = stackReference.GetOutputDetailsAsync("unknown"),
+                };
+            });
+
+            var unknown = await (outputs["unknown"] as Task<StackReferenceOutputDetails>);
+            Assert.Null(unknown.Value);
+            Assert.Null(unknown.SecretValue);
+        }
+    }
+
+    class FakeStackOutputMocks : IMocks
+    {
+        private string key;
+        private object val;
+        public FakeStackOutputMocks(string key, object val)
+        {
+            this.key = key;
+            this.val = val;
+        }
+
+        public Task<object> CallAsync(MockCallArgs args)
+        {
+            return Task.FromResult<object>(args);
+        }
+
+        public async Task<(string? id, object state)> NewResourceAsync(
+            MockResourceArgs args)
+        {
+            if (args.Type == "pulumi:pulumi:StackReference")
+            {
+                var outputs = new Dictionary<string, object>();
+                outputs[this.key] = this.val;
+
+                var props = new Dictionary<string, object>();
+                props["outputs"] = outputs;
+                return (args.Name + "-id", props);
+            }
+            else
+            {
+                throw new Exception($"Unknown resource {args.Type}");
+            }
+        }
+    }
+}

sdk/Pulumi/Pulumi.xml

@@ -81,6 +81,32 @@ public Output<object> RequireOutput(Input<string> name)
             return value.WithIsSecret(IsSecretOutputName(name));
         }
 
+        /// <summary>
+        /// Fetches the value of the named stack output
+        /// and builds a <see ref="StackReferenceOutputDetails"/> object from it.
+        /// <para />
+        /// The returned object has its Value or SecretValue field set
+        /// depending on whether the output is a secret.
+        /// Neither field is set if the output is not found.
+        /// </summary>
+        /// <param name="name">The name of the stack output to fetch.</param>
+        /// <returns>StackReferenceOutputDetails object containing the output.</returns>
+        public async Task<StackReferenceOutputDetails> GetOutputDetailsAsync(string name)
+        {
+            var output = this.GetOutput(name);
+            var data = await output.DataTask.ConfigureAwait(false);
+            var details = new StackReferenceOutputDetails { };
+            if (data.IsSecret)
+            {
+                details.SecretValue = data.Value;
+            }
+            else
+            {
+                details.Value = data.Value;
+            }
+            return details;
+        }
+
         /// <summary>
         /// Fetches the value of the named stack output. May return null if the value is
         /// not known for some reason.

sdk/Pulumi/Resources/StackReference.cs

@@ -0,0 +1,25 @@
+// Copyright 2016-2023, Pulumi Corporation
+
+using System.Collections.Generic;
+
+namespace Pulumi
+{
+    /// <summary>
+    /// Holds a StackReference's output value.
+    /// At most one of Value and SecretValue will be set.
+    /// </summary>
+    public sealed class StackReferenceOutputDetails
+    {
+        /// <summary>
+        /// Output value returned by the <see cref="StackReference"/>.
+        /// This field is only set if the output is not a secret.
+        /// </summary>
+        public object? Value { get; set; }
+
+        /// <summary>
+        /// Secret output value returned by the <see cref="StackReference"/>.
+        /// This field is only set if the output is a secret.
+        /// </summary>
+        public object? SecretValue { get; set; }
+    }
+}