Class Project

A representation of a CodeBuild Project.

Inheritance

object

Resource

Project

PipelineProject

Implements

IProject

IResource

IConstruct

IDependable

IEnvironmentAware

IGrantable

IConnectable

INotificationRuleSource

Inherited Members

Resource.IsOwnedResource(IConstruct)

Resource.IsResource(IConstruct)

Resource.ApplyRemovalPolicy(RemovalPolicy)

Resource.GeneratePhysicalName()

Resource.GetResourceArnAttribute(string, IArnComponents)

Resource.GetResourceNameAttribute(string)

Resource.Env

Resource.PhysicalName

Resource.Stack

Namespace: Amazon.CDK.AWS.CodeBuild

Assembly: Amazon.CDK.Lib.dll

Syntax (csharp)

public class Project : Resource, IProject, IResource, IConstruct, IDependable, IEnvironmentAware, IGrantable, IConnectable, INotificationRuleSource

Syntax (vb)

Public Class Project Inherits Resource Implements IProject, IResource, IConstruct, IDependable, IEnvironmentAware, IGrantable, IConnectable, INotificationRuleSource

Remarks

ExampleMetadata: infused

Examples

Repository ecrRepository;


            new Project(this, "Project", new ProjectProps {
                Environment = new BuildEnvironment {
                    BuildImage = WindowsBuildImage.FromEcrRepository(ecrRepository, "v1.0", WindowsImageType.SERVER_2019),
                    // optional certificate to include in the build image
                    Certificate = new BuildEnvironmentCertificate {
                        Bucket = Bucket.FromBucketName(this, "Bucket", "amzn-s3-demo-bucket"),
                        ObjectKey = "path/to/cert.pem"
                    }
                }
            });

Synopsis

Constructors

Project(Construct, string, IProjectProps)

A representation of a CodeBuild Project.

Properties

Connections	Access the Connections object.
GrantPrincipal	The principal to grant permissions to.
PROPERTY_INJECTION_ID	Uniquely identifies this class.
ProjectArn	The ARN of the project.
ProjectName	The name of the project.
Role	The IAM role for this project.

Methods

AddFileSystemLocation(IFileSystemLocation)	Adds a fileSystemLocation to the Project.
AddSecondaryArtifact(IArtifacts)	Adds a secondary artifact to the Project.
AddSecondarySource(ISource)	Adds a secondary source to the Project.
AddToRolePolicy(PolicyStatement)	Add a permission only if there's a policy attached.
BindAsNotificationRuleSource(Construct)	Returns a source configuration for notification rule.
BindToCodePipeline(Construct, IBindToCodePipelineOptions)	A callback invoked when the given project is added to a CodePipeline.
EnableBatchBuilds()	Enable batch builds.
FromProjectArn(Construct, string, string)	A representation of a CodeBuild Project.
FromProjectName(Construct, string, string)	Import a Project defined either outside the CDK, or in a different CDK Stack (and exported using the `export` method).
Metric(string, IMetricOptions?)	A representation of a CodeBuild Project.
MetricBuilds(IMetricOptions?)	Measures the number of builds triggered.
MetricDuration(IMetricOptions?)	Measures the duration of all builds over time.
MetricFailedBuilds(IMetricOptions?)	Measures the number of builds that failed because of client error or because of a timeout.
MetricSucceededBuilds(IMetricOptions?)	Measures the number of successful builds.
NotifyOn(string, INotificationRuleTarget, IProjectNotifyOnOptions)	Defines a CodeStar Notification rule triggered when the project events emitted by you specified, it very similar to `onEvent` API.
NotifyOnBuildFailed(string, INotificationRuleTarget, INotificationRuleOptions?)	Defines a CodeStar notification rule which triggers when a build fails.
NotifyOnBuildSucceeded(string, INotificationRuleTarget, INotificationRuleOptions?)	Defines a CodeStar notification rule which triggers when a build completes successfully.
OnBuildFailed(string, IOnEventOptions?)	Defines an event rule which triggers when a build fails.
OnBuildStarted(string, IOnEventOptions?)	Defines an event rule which triggers when a build starts.
OnBuildSucceeded(string, IOnEventOptions?)	Defines an event rule which triggers when a build completes successfully.
OnEvent(string, IOnEventOptions?)	Defines a CloudWatch event rule triggered when something happens with this project.
OnPhaseChange(string, IOnEventOptions?)	Defines a CloudWatch event rule that triggers upon phase change of this build project.
OnStateChange(string, IOnEventOptions?)	Defines a CloudWatch event rule triggered when the build project state changes.
SerializeEnvVariables(IDictionary<string, IBuildEnvironmentVariable>, bool?, IGrantable?)	Convert the environment variables map of string to `BuildEnvironmentVariable`, which is the customer-facing type, to a list of `CfnProject.EnvironmentVariableProperty`, which is the representation of environment variables in CloudFormation.

Constructors

Project(Construct, string, IProjectProps)

A representation of a CodeBuild Project.

public Project(Construct scope, string id, IProjectProps props)

Parameters

scope Construct
id string
props IProjectProps

Remarks

ExampleMetadata: infused

Examples

Repository ecrRepository;


            new Project(this, "Project", new ProjectProps {
                Environment = new BuildEnvironment {
                    BuildImage = WindowsBuildImage.FromEcrRepository(ecrRepository, "v1.0", WindowsImageType.SERVER_2019),
                    // optional certificate to include in the build image
                    Certificate = new BuildEnvironmentCertificate {
                        Bucket = Bucket.FromBucketName(this, "Bucket", "amzn-s3-demo-bucket"),
                        ObjectKey = "path/to/cert.pem"
                    }
                }
            });

Properties

Connections

Access the Connections object.

public virtual Connections_ Connections { get; }

Property Value

Connections_

Remarks

Will fail if this Project does not have a VPC set.

GrantPrincipal

The principal to grant permissions to.

public virtual IPrincipal GrantPrincipal { get; }

Property Value

IPrincipal

Remarks

ExampleMetadata: infused

PROPERTY_INJECTION_ID

Uniquely identifies this class.

public static string PROPERTY_INJECTION_ID { get; }

Property Value

string

Remarks

ExampleMetadata: infused

ProjectArn

The ARN of the project.

public virtual string ProjectArn { get; }

Property Value

string

Remarks

ExampleMetadata: infused

ProjectName

The name of the project.

public virtual string ProjectName { get; }

Property Value

string

Remarks

ExampleMetadata: infused

Role

The IAM role for this project.

public virtual IRole? Role { get; }

Property Value

IRole

Remarks

ExampleMetadata: infused

Methods

AddFileSystemLocation(IFileSystemLocation)

Adds a fileSystemLocation to the Project.

public virtual void AddFileSystemLocation(IFileSystemLocation fileSystemLocation)

Parameters

fileSystemLocation IFileSystemLocation: the fileSystemLocation to add.

Remarks

ExampleMetadata: infused

AddSecondaryArtifact(IArtifacts)

Adds a secondary artifact to the Project.

public virtual void AddSecondaryArtifact(IArtifacts secondaryArtifact)

Parameters

secondaryArtifact IArtifacts: the artifact to add as a secondary artifact.

Remarks

See: https://docs.aws.amazon.com/codebuild/latest/userguide/sample-multi-in-out.html

AddSecondarySource(ISource)

Adds a secondary source to the Project.

public virtual void AddSecondarySource(ISource secondarySource)

Parameters

secondarySource ISource: the source to add as a secondary source.

Remarks

See: https://docs.aws.amazon.com/codebuild/latest/userguide/sample-multi-in-out.html

AddToRolePolicy(PolicyStatement)

Add a permission only if there's a policy attached.

public virtual void AddToRolePolicy(PolicyStatement statement)

Parameters

statement PolicyStatement: The permissions statement to add.

Remarks

ExampleMetadata: infused

BindAsNotificationRuleSource(Construct)

Returns a source configuration for notification rule.

public virtual INotificationRuleSourceConfig BindAsNotificationRuleSource(Construct scope)

Parameters

scope Construct

Returns

INotificationRuleSourceConfig

Remarks

ExampleMetadata: infused

BindToCodePipeline(Construct, IBindToCodePipelineOptions)

A callback invoked when the given project is added to a CodePipeline.

public virtual void BindToCodePipeline(Construct scope, IBindToCodePipelineOptions options)

Parameters

scope Construct: the construct the binding is taking place in.
options IBindToCodePipelineOptions: additional options for the binding.

Remarks

ExampleMetadata: infused

EnableBatchBuilds()

Enable batch builds.

public virtual IBatchBuildConfig? EnableBatchBuilds()

Returns

IBatchBuildConfig

Remarks

Returns an object contining the batch service role if batch builds could be enabled.

FromProjectArn(Construct, string, string)

A representation of a CodeBuild Project.

public static IProject FromProjectArn(Construct scope, string id, string projectArn)

Parameters

scope Construct
id string
projectArn string

Returns

IProject

Remarks

ExampleMetadata: infused

Examples

Repository ecrRepository;


            new Project(this, "Project", new ProjectProps {
                Environment = new BuildEnvironment {
                    BuildImage = WindowsBuildImage.FromEcrRepository(ecrRepository, "v1.0", WindowsImageType.SERVER_2019),
                    // optional certificate to include in the build image
                    Certificate = new BuildEnvironmentCertificate {
                        Bucket = Bucket.FromBucketName(this, "Bucket", "amzn-s3-demo-bucket"),
                        ObjectKey = "path/to/cert.pem"
                    }
                }
            });

FromProjectName(Construct, string, string)

Import a Project defined either outside the CDK, or in a different CDK Stack (and exported using the export method).

public static IProject FromProjectName(Construct scope, string id, string projectName)

Parameters

scope Construct: the parent Construct for this Construct.
id string: the logical name of this Construct.
projectName string: the name of the project to import.

Returns

IProject

a reference to the existing Project

Remarks

Note: if you're importing a CodeBuild Project for use in a CodePipeline, make sure the existing Project has permissions to access the S3 Bucket of that Pipeline - otherwise, builds in that Pipeline will always fail.

Metric(string, IMetricOptions?)

A representation of a CodeBuild Project.

public virtual Metric Metric(string metricName, IMetricOptions? props = null)

Parameters

metricName string: The name of the metric.
props IMetricOptions: Customization properties.

Returns

Metric

a CloudWatch metric associated with this build project.

Remarks

ExampleMetadata: infused

MetricBuilds(IMetricOptions?)

Measures the number of builds triggered.

public virtual Metric MetricBuilds(IMetricOptions? props = null)

Parameters

props IMetricOptions

Returns

Metric

Remarks

Units: Count

Valid CloudWatch statistics: Sum

Default: sum over 5 minutes

MetricDuration(IMetricOptions?)

Measures the duration of all builds over time.

public virtual Metric MetricDuration(IMetricOptions? props = null)

Parameters

props IMetricOptions

Returns

Metric

Remarks

Units: Seconds

Valid CloudWatch statistics: Average (recommended), Maximum, Minimum

Default: average over 5 minutes

MetricFailedBuilds(IMetricOptions?)

Measures the number of builds that failed because of client error or because of a timeout.

public virtual Metric MetricFailedBuilds(IMetricOptions? props = null)

Parameters

props IMetricOptions

Returns

Metric

Remarks

Units: Count

Valid CloudWatch statistics: Sum

Default: sum over 5 minutes

MetricSucceededBuilds(IMetricOptions?)

Measures the number of successful builds.

public virtual Metric MetricSucceededBuilds(IMetricOptions? props = null)

Parameters

props IMetricOptions

Returns

Metric

Remarks

Units: Count

Valid CloudWatch statistics: Sum

Default: sum over 5 minutes

NotifyOn(string, INotificationRuleTarget, IProjectNotifyOnOptions)

Defines a CodeStar Notification rule triggered when the project events emitted by you specified, it very similar to onEvent API.

public virtual INotificationRule NotifyOn(string id, INotificationRuleTarget target, IProjectNotifyOnOptions options)

Parameters

id string
target INotificationRuleTarget
options IProjectNotifyOnOptions

Returns

INotificationRule

Remarks

You can also use the methods notifyOnBuildSucceeded and notifyOnBuildFailed to define rules for these specific event emitted.

NotifyOnBuildFailed(string, INotificationRuleTarget, INotificationRuleOptions?)

Defines a CodeStar notification rule which triggers when a build fails.

public virtual INotificationRule NotifyOnBuildFailed(string id, INotificationRuleTarget target, INotificationRuleOptions? options = null)

Parameters

id string
target INotificationRuleTarget
options INotificationRuleOptions

Returns

INotificationRule

Remarks

ExampleMetadata: infused

NotifyOnBuildSucceeded(string, INotificationRuleTarget, INotificationRuleOptions?)

Defines a CodeStar notification rule which triggers when a build completes successfully.

public virtual INotificationRule NotifyOnBuildSucceeded(string id, INotificationRuleTarget target, INotificationRuleOptions? options = null)

Parameters

id string
target INotificationRuleTarget
options INotificationRuleOptions

Returns

INotificationRule

Remarks

ExampleMetadata: infused

OnBuildFailed(string, IOnEventOptions?)

Defines an event rule which triggers when a build fails.

public virtual Rule OnBuildFailed(string id, IOnEventOptions? options = null)

Parameters

id string
options IOnEventOptions

Returns

Rule

Remarks

To access fields from the event in the event target input, use the static fields on the StateChangeEvent class.

OnBuildStarted(string, IOnEventOptions?)

Defines an event rule which triggers when a build starts.

public virtual Rule OnBuildStarted(string id, IOnEventOptions? options = null)

Parameters

id string
options IOnEventOptions

Returns

Rule

Remarks

To access fields from the event in the event target input, use the static fields on the StateChangeEvent class.

OnBuildSucceeded(string, IOnEventOptions?)

Defines an event rule which triggers when a build completes successfully.

public virtual Rule OnBuildSucceeded(string id, IOnEventOptions? options = null)

Parameters

id string
options IOnEventOptions

Returns

Rule

Remarks

To access fields from the event in the event target input, use the static fields on the StateChangeEvent class.

OnEvent(string, IOnEventOptions?)

Defines a CloudWatch event rule triggered when something happens with this project.

public virtual Rule OnEvent(string id, IOnEventOptions? options = null)

OnPhaseChange(string, IOnEventOptions?)

Defines a CloudWatch event rule that triggers upon phase change of this build project.

public virtual Rule OnPhaseChange(string id, IOnEventOptions? options = null)

Parameters

id string
options IOnEventOptions

Returns

Rule

Remarks

See: https://docs.aws.amazon.com/codebuild/latest/userguide/sample-build-notifications.html

OnStateChange(string, IOnEventOptions?)

Defines a CloudWatch event rule triggered when the build project state changes.

public virtual Rule OnStateChange(string id, IOnEventOptions? options = null)

Parameters

id string
options IOnEventOptions

Returns

Rule

Remarks

You can filter specific build status events using an event pattern filter on the build-status detail field:

const rule = project.onStateChange('OnBuildStarted', { target }); rule.addEventPattern({ detail: { 'build-status': [ "IN_PROGRESS", "SUCCEEDED", "FAILED", "STOPPED" ] } });

You can also use the methods onBuildFailed and onBuildSucceeded to define rules for these specific state changes.

To access fields from the event in the event target input, use the static fields on the StateChangeEvent class.

See: https://docs.aws.amazon.com/codebuild/latest/userguide/sample-build-notifications.html

SerializeEnvVariables(IDictionary<string, IBuildEnvironmentVariable>, bool?, IGrantable?)

Convert the environment variables map of string to BuildEnvironmentVariable, which is the customer-facing type, to a list of CfnProject.EnvironmentVariableProperty, which is the representation of environment variables in CloudFormation.

public static CfnProject.IEnvironmentVariableProperty[] SerializeEnvVariables(IDictionary<string, IBuildEnvironmentVariable> environmentVariables, bool? validateNoPlainTextSecrets = null, IGrantable? principal = null)

Parameters

environmentVariables IDictionary<string, IBuildEnvironmentVariable>: the map of string to environment variables.
validateNoPlainTextSecrets bool?: whether to throw an exception if any of the plain text environment variables contain secrets, defaults to 'false'.
principal IGrantable: the map of string to environment variables.

Returns

IEnvironmentVariableProperty[]

an array of CfnProject.EnvironmentVariableProperty instances

Remarks

ExampleMetadata: infused

Implements

IProject

IResource

Constructs.IConstruct

Constructs.IDependable

IEnvironmentAware

IGrantable

IConnectable

INotificationRuleSource