Class WorkspaceStack

WorkspaceStack is an isolated, independently configurable instance of a Pulumi program. WorkspaceStack exposes methods for the full pulumi lifecycle (up/preview/refresh/destroy), as well as managing configuration.

Multiple stacks are commonly used to denote different phases of development (such as development, staging, and production) or feature branches (such as feature-x-dev, jane-feature-x-dev).

Will dispose the Workspace on Dispose().

Inheritance

object

WorkspaceStack

Implements

IDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Namespace: Pulumi.Automation

Assembly: Pulumi.Automation.dll

Syntax

public sealed class WorkspaceStack : IDisposable

Properties

Name

The name identifying the Stack.

Declaration

public string Name { get; }

Property Value

Type	Description
string

State

A module for editing the Stack's state.

Declaration

public WorkspaceStackState State { get; }

Property Value

Type	Description
WorkspaceStackState

Workspace

The Workspace the Stack was created from.

Declaration

public Workspace Workspace { get; }

Property Value

Type	Description
Workspace

Methods

AddEnvironmentsAsync(IEnumerable<string>, CancellationToken)

Adds environments to the end of a stack's import list. Imported environments are merged in order per the ESC merge rules. The list of environments behaves as if it were the import list in an anonymous environment.

Declaration

public Task AddEnvironmentsAsync(IEnumerable<string> environments, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
IEnumerable<string>	environments	List of environments to add to the end of the stack's import list.
CancellationToken	cancellationToken	A cancellation token.

Returns

Type	Description
Task

CancelAsync(CancellationToken)

Cancel stops a stack's currently running update. It throws an exception if no update is currently running. Note that this operation is very dangerous, and may leave the stack in an inconsistent state if a resource operation was pending when the update was canceled. This command is not supported for local backends.

Declaration

public Task CancelAsync(CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
CancellationToken	cancellationToken

Returns

Type	Description
Task

ChangeSecretsProviderAsync(string, SecretsProviderOptions?, CancellationToken)

Declaration

public Task ChangeSecretsProviderAsync(string newSecretsProvider, SecretsProviderOptions? secretsProviderOptions = null, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	newSecretsProvider
SecretsProviderOptions	secretsProviderOptions
CancellationToken	cancellationToken

Returns

Type	Description
Task

CreateAsync(string, Workspace, CancellationToken)

Creates a new stack using the given workspace, and stack name. It fails if a stack with that name already exists.

Declaration

public static Task<WorkspaceStack> CreateAsync(string name, Workspace workspace, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	name	The name identifying the stack.
Workspace	workspace	The Workspace the Stack was created from.
CancellationToken	cancellationToken	A cancellation token.

Returns

Type	Description
Task<WorkspaceStack>

Exceptions

Type	Condition
StackAlreadyExistsException	If a stack with the provided name already exists.

CreateOrSelectAsync(string, Workspace, CancellationToken)

Tries to create a new Stack using the given workspace, and stack name if the stack does not already exist, or falls back to selecting an existing stack. If the stack does not exist, it will be created and selected.

Declaration

public static Task<WorkspaceStack> CreateOrSelectAsync(string name, Workspace workspace, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	name	The name of the identifying stack.
Workspace	workspace	The Workspace the Stack was created from.
CancellationToken	cancellationToken	A cancellation token.

Returns

Type	Description
Task<WorkspaceStack>

DestroyAsync(DestroyOptions?, CancellationToken)

Destroy deletes all resources in a stack, leaving all history and configuration intact.

Declaration

public Task<UpdateResult> DestroyAsync(DestroyOptions? options = null, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
DestroyOptions	options	Options to customize the behavior of the destroy.
CancellationToken	cancellationToken	A cancellation token.

Returns

Type	Description
Task<UpdateResult>

Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

Declaration

public void Dispose()

ExportStackAsync(CancellationToken)

Exports the deployment state of the stack.

This can be combined with ImportStackAsync to edit a stack's state (such as recovery from failed deployments).

Declaration

public Task<StackDeployment> ExportStackAsync(CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
CancellationToken	cancellationToken

Returns

Type	Description
Task<StackDeployment>

GetAllConfigAsync(CancellationToken)

Returns the full config map associated with the stack in the Workspace.

Declaration

public Task<ImmutableDictionary<string, ConfigValue>> GetAllConfigAsync(CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
CancellationToken	cancellationToken	A cancellation token.

Returns

Type	Description
Task<ImmutableDictionary<string, ConfigValue>>

GetConfigAsync(string, bool, CancellationToken)

Returns the config value associated with the specified key.

Declaration

public Task<ConfigValue> GetConfigAsync(string key, bool path, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	key	The key to use for the config lookup.
bool	path	The key contains a path to a property in a map or list to get.
CancellationToken	cancellationToken	A cancellation token.

Returns

Type	Description
Task<ConfigValue>

GetConfigAsync(string, CancellationToken)

Returns the config value associated with the specified key.

Declaration

public Task<ConfigValue> GetConfigAsync(string key, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	key	The key to use for the config lookup.
CancellationToken	cancellationToken	A cancellation token.

Returns

Type	Description
Task<ConfigValue>

GetHistoryAsync(HistoryOptions?, CancellationToken)

Returns a list summarizing all previews and current results from Stack lifecycle operations (up/preview/refresh/destroy).

Declaration

public Task<ImmutableList<UpdateSummary>> GetHistoryAsync(HistoryOptions? options = null, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
HistoryOptions	options	Options to customize the behavior of the fetch history action.
CancellationToken	cancellationToken	A cancellation token.

Returns

Type	Description
Task<ImmutableList<UpdateSummary>>

GetInfoAsync(CancellationToken)

Declaration

public Task<UpdateSummary?> GetInfoAsync(CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
CancellationToken	cancellationToken

Returns

Type	Description
Task<UpdateSummary>

GetOutputsAsync(CancellationToken)

Gets the current set of Stack outputs from the last UpAsync(UpOptions?, CancellationToken).

Declaration

public Task<ImmutableDictionary<string, OutputValue>> GetOutputsAsync(CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
CancellationToken	cancellationToken

Returns

Type	Description
Task<ImmutableDictionary<string, OutputValue>>

GetTagAsync(string, CancellationToken)

Returns the value associated with the stack and key, scoped to the Workspace.

Declaration

public Task<string> GetTagAsync(string key, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	key	The key to use for the tag lookup.
CancellationToken	cancellationToken	A cancellation token.

Returns

Type	Description
Task<string>

ImportAsync(ImportOptions, CancellationToken)

Import resources into a stack.

Declaration

public Task<ImportResult> ImportAsync(ImportOptions options, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
ImportOptions	options	Import options to customize the behaviour of the import operation
CancellationToken	cancellationToken	A cancellation token.

Returns

Type	Description
Task<ImportResult>	The output of the import command, including the generated code, if any.

ImportStackAsync(StackDeployment, CancellationToken)

Imports the specified deployment state into a pre-existing stack.

This can be combined with ExportStackAsync to edit a stack's state (such as recovery from failed deployments).

Declaration

public Task ImportStackAsync(StackDeployment state, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
StackDeployment	state
CancellationToken	cancellationToken

Returns

Type	Description
Task

ListTagsAsync(CancellationToken)

Returns the tag map for the stack, scoped to the current Workspace.

Declaration

public Task<Dictionary<string, string>> ListTagsAsync(CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
CancellationToken	cancellationToken	A cancellation token.

Returns

Type	Description
Task<Dictionary<string, string>>

PreviewAsync(PreviewOptions?, CancellationToken)

Performs a dry-run update to a stack, returning pending changes.

https://www.pulumi.com/docs/reference/cli/pulumi_preview/

Declaration

public Task<PreviewResult> PreviewAsync(PreviewOptions? options = null, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
PreviewOptions	options	Options to customize the behavior of the update.
CancellationToken	cancellationToken	A cancellation token.

Returns

Type	Description
Task<PreviewResult>

RefreshAsync(RefreshOptions?, CancellationToken)

Compares the current stack’s resource state with the state known to exist in the actual cloud provider. Any such changes are adopted into the current stack.

Declaration

public Task<UpdateResult> RefreshAsync(RefreshOptions? options = null, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
RefreshOptions	options	Options to customize the behavior of the refresh.
CancellationToken	cancellationToken	A cancellation token.

Returns

Type	Description
Task<UpdateResult>

RefreshConfigAsync(CancellationToken)

Gets and sets the config map used with the last update.

Declaration

public Task<ImmutableDictionary<string, ConfigValue>> RefreshConfigAsync(CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
CancellationToken	cancellationToken	A cancellation token.

Returns

Type	Description
Task<ImmutableDictionary<string, ConfigValue>>

RemoveAllConfigAsync(IEnumerable<string>, bool, CancellationToken)

Removes the specified config keys from the Stack in the associated Workspace.

Declaration

public Task RemoveAllConfigAsync(IEnumerable<string> keys, bool path, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
IEnumerable<string>	keys	The config keys to remove.
bool	path	The keys contain a path to a property in a map or list to remove.
CancellationToken	cancellationToken	A cancellation token.

Returns

Type	Description
Task

RemoveAllConfigAsync(IEnumerable<string>, CancellationToken)

Removes the specified config keys from the Stack in the associated Workspace.

Declaration

public Task RemoveAllConfigAsync(IEnumerable<string> keys, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
IEnumerable<string>	keys	The config keys to remove.
CancellationToken	cancellationToken	A cancellation token.

Returns

Type	Description
Task

RemoveConfigAsync(string, bool, CancellationToken)

Removes the specified config key from the Stack in the associated Workspace.

Declaration

public Task RemoveConfigAsync(string key, bool path, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	key	The config key to remove.
bool	path	The key contains a path to a property in a map or list to remove.
CancellationToken	cancellationToken	A cancellation token.

Returns

Type	Description
Task

RemoveConfigAsync(string, CancellationToken)

Removes the specified config key from the Stack in the associated Workspace.

Declaration

public Task RemoveConfigAsync(string key, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	key	The config key to remove.
CancellationToken	cancellationToken	A cancellation token.

Returns

Type	Description
Task

RemoveEnvironmentAsync(string, CancellationToken)

Removes environments from a stack's import list.

Declaration

public Task RemoveEnvironmentAsync(string environment, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	environment	The name of the environment to remove from the stack's configuration.
CancellationToken	cancellationToken	A cancellation token.

Returns

Type	Description
Task

RemoveTagAsync(string, CancellationToken)

Sets the specified key-value pair on the stack.

Declaration

public Task RemoveTagAsync(string key, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	key	The tag key to set.
CancellationToken	cancellationToken	A cancellation token.

Returns

Type	Description
Task

SelectAsync(string, Workspace, CancellationToken)

Selects stack using the given workspace, and stack name. It returns an error if the given Stack does not exist.

Declaration

public static Task<WorkspaceStack> SelectAsync(string name, Workspace workspace, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	name	The name identifying the stack.
Workspace	workspace	The Workspace the Stack was created from.
CancellationToken	cancellationToken	A cancellation token.

Returns

Type	Description
Task<WorkspaceStack>

Exceptions

Type	Condition
StackNotFoundException	If a stack with the provided name does not exists.

SetAllConfigAsync(IDictionary<string, ConfigValue>, bool, CancellationToken)

Sets all specified config values on the stack in the associated Workspace.

Declaration

public Task SetAllConfigAsync(IDictionary<string, ConfigValue> configMap, bool path, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
IDictionary<string, ConfigValue>	configMap	The map of config key-value pairs to set.
bool	path	The keys contain a path to a property in a map or list to set.
CancellationToken	cancellationToken	A cancellation token.

Returns

Type	Description
Task

SetAllConfigAsync(IDictionary<string, ConfigValue>, CancellationToken)

Sets all specified config values on the stack in the associated Workspace.

Declaration

public Task SetAllConfigAsync(IDictionary<string, ConfigValue> configMap, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
IDictionary<string, ConfigValue>	configMap	The map of config key-value pairs to set.
CancellationToken	cancellationToken	A cancellation token.

Returns

Type	Description
Task

SetConfigAsync(string, ConfigValue, bool, CancellationToken)

Sets the config key-value pair on the Stack in the associated Workspace.

Declaration

public Task SetConfigAsync(string key, ConfigValue value, bool path, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	key	The key to set.
ConfigValue	value	The config value to set.
bool	path	The key contains a path to a property in a map or list to set.
CancellationToken	cancellationToken	A cancellation token.

Returns

Type	Description
Task

SetConfigAsync(string, ConfigValue, CancellationToken)

Sets the config key-value pair on the Stack in the associated Workspace.

Declaration

public Task SetConfigAsync(string key, ConfigValue value, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	key	The key to set.
ConfigValue	value	The config value to set.
CancellationToken	cancellationToken	A cancellation token.

Returns

Type	Description
Task

SetTagAsync(string, string, CancellationToken)

Sets the specified key-value pair on the stack.

Declaration

public Task SetTagAsync(string key, string value, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	key	The tag key to set.
string	value	The tag value to set.
CancellationToken	cancellationToken	A cancellation token.

Returns

Type	Description
Task

UpAsync(UpOptions?, CancellationToken)

Creates or updates the resources in a stack by executing the program in the Workspace.

https://www.pulumi.com/docs/reference/cli/pulumi_up/

Declaration

public Task<UpResult> UpAsync(UpOptions? options = null, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
UpOptions	options	Options to customize the behavior of the update.
CancellationToken	cancellationToken	A cancellation token.

Returns

Type	Description
Task<UpResult>

Implements

IDisposable