.NET Cloud Formation example, updated PR. (awsdocs#6134)

max-webster · Mar 15, 2024 · d900e7d · d900e7d
1 parent 0672205
commit d900e7d
Show file tree

Hide file tree

Showing 10 changed files with 408 additions and 63 deletions.
diff --git a/.doc_gen/metadata/cloudformation_metadata.yaml b/.doc_gen/metadata/cloudformation_metadata.yaml
@@ -0,0 +1,16 @@
+cloudformation_Hello:
+  title: Hello &CFN;
+  title_abbrev: Hello &CFN;
+  synopsis: get started using &CFN;.
+  category: Hello
+  languages:
+    .NET:
+      versions:
+        - sdk_version: 3
+          github: dotnetv3/CloudFormation
+          excerpts:
+            - description:
+              snippet_tags:
+                - CloudFormation.dotnetv3.CloudFormationActions.HelloCloudFormation
+  services:
+    cloudformation: {DescribeStackResources}
diff --git a/dotnetv3/CloudFormation/Actions/CloudFormationActions.csproj b/dotnetv3/CloudFormation/Actions/CloudFormationActions.csproj
@@ -0,0 +1,19 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net6.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="AWSSDK.CloudFormation" Version="3.7.303.5" />
+    <PackageReference Include="AWSSDK.Extensions.NETCore.Setup" Version="3.7.2" />
+    <PackageReference Include="AWSSDK.SSO" Version="3.7.300.49" />
+    <PackageReference Include="AWSSDK.SSOOIDC" Version="3.7.301.44" />
+    <PackageReference Include="Microsoft.Extensions.DependencyInjection" Version="6.0.0" />
+    <PackageReference Include="Microsoft.Extensions.Hosting" Version="6.0.1" />
+  </ItemGroup>
+
+</Project>
diff --git a/dotnetv3/CloudFormation/Actions/HelloCloudFormation.cs b/dotnetv3/CloudFormation/Actions/HelloCloudFormation.cs
@@ -0,0 +1,111 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. 
+// SPDX-License-Identifier: Apache-2.0
+
+// snippet-start:[CloudFormation.dotnetv3.CloudFormationActions.HelloCloudFormation]
+using Amazon.CloudFormation;
+using Amazon.CloudFormation.Model;
+using Amazon.Runtime;
+
+namespace CloudFormationActions;
+
+public static class HelloCloudFormation
+{
+    public static IAmazonCloudFormation _amazonCloudFormation;
+
+    static async Task Main(string[] args)
+    {
+        // Create the CloudFormation client
+        _amazonCloudFormation = new AmazonCloudFormationClient();
+        Console.WriteLine($"\nIn Region: {_amazonCloudFormation.Config.RegionEndpoint}");
+
+        // List the resources for each stack
+        await ListResources();
+    }
+
+    /// <summary>
+    /// Method to list stack resources and other information.
+    /// </summary>
+    /// <returns>True if successful.</returns>
+    public static async Task<bool> ListResources()
+    {
+        try
+        {
+            Console.WriteLine("Getting CloudFormation stack information...");
+
+            // Get all stacks using the stack paginator.
+            var paginatorForDescribeStacks =
+                _amazonCloudFormation.Paginators.DescribeStacks(
+                    new DescribeStacksRequest());
+            await foreach (Stack stack in paginatorForDescribeStacks.Stacks)
+            {
+                // Basic information for each stack
+                Console.WriteLine("\n------------------------------------------------");
+                Console.WriteLine($"\nStack: {stack.StackName}");
+                Console.WriteLine($"  Status: {stack.StackStatus.Value}");
+                Console.WriteLine($"  Created: {stack.CreationTime}");
+
+                // The tags of each stack (etc.)
+                if (stack.Tags.Count > 0)
+                {
+                    Console.WriteLine("  Tags:");
+                    foreach (Tag tag in stack.Tags)
+                        Console.WriteLine($"    {tag.Key}, {tag.Value}");
+                }
+
+                // The resources of each stack
+                DescribeStackResourcesResponse responseDescribeResources =
+                    await _amazonCloudFormation.DescribeStackResourcesAsync(
+                        new DescribeStackResourcesRequest
+                        {
+                            StackName = stack.StackName
+                        });
+                if (responseDescribeResources.StackResources.Count > 0)
+                {
+                    Console.WriteLine("  Resources:");
+                    foreach (StackResource resource in responseDescribeResources
+                                 .StackResources)
+                        Console.WriteLine(
+                            $"    {resource.LogicalResourceId}: {resource.ResourceStatus}");
+                }
+            }
+
+            Console.WriteLine("\n------------------------------------------------");
+            return true;
+        }
+        catch (AmazonCloudFormationException ex)
+        {
+            Console.WriteLine("Unable to get stack information:\n" + ex.Message);
+            return false;
+        }
+        catch (AmazonServiceException ex)
+        {
+            if (ex.Message.Contains("Unable to get IAM security credentials"))
+            {
+                Console.WriteLine(ex.Message);
+                Console.WriteLine("If you are usnig SSO, be sure to install" +
+                    " the AWSSDK.SSO and AWSSDK.SSOOIDC packages.");
+            }
+            else
+            {
+                Console.WriteLine(ex.Message);
+                Console.WriteLine(ex.StackTrace);
+            }
+            return false;
+        }
+        catch (ArgumentNullException ex)
+        {
+            if (ex.Message.Contains("Options property cannot be empty: ClientName"))
+            {
+                Console.WriteLine(ex.Message);
+                Console.WriteLine("If you are using SSO, have you logged in?");
+            }
+            else
+            {
+                Console.WriteLine(ex.Message);
+                Console.WriteLine(ex.StackTrace);
+            }
+            return false;
+        }
+    }
+}
+// snippet-end:[CloudFormation.dotnetv3.CloudFormationActions.HelloCloudFormation]
diff --git a/dotnetv3/CloudFormation/CloudFormationExamples.sln b/dotnetv3/CloudFormation/CloudFormationExamples.sln
@@ -0,0 +1,39 @@
+
+Microsoft Visual Studio Solution File, Format Version 12.00
+# Visual Studio Version 17
+VisualStudioVersion = 17.2.32630.192
+MinimumVisualStudioVersion = 10.0.40219.1
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Actions", "Actions", "{7907FB6A-1353-4735-95DC-EEC5DF8C0649}"
+EndProject
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Tests", "Tests", "{5455D423-2AFC-4BC6-B79D-9DC4270D8F7D}"
+EndProject
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "CloudFormationActions", "Actions\CloudFormationActions.csproj", "{796910FA-6E94-460B-8CB4-97DF01B9ADC8}"
+EndProject
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "CloudFormationTests", "Tests\CloudFormationTests.csproj", "{6046A2FC-6A39-4C2D-8DD9-AA3740B17B88}"
+EndProject
+Global
+	GlobalSection(SolutionConfigurationPlatforms) = preSolution
+		Debug|Any CPU = Debug|Any CPU
+		Release|Any CPU = Release|Any CPU
+	EndGlobalSection
+	GlobalSection(ProjectConfigurationPlatforms) = postSolution
+		{796910FA-6E94-460B-8CB4-97DF01B9ADC8}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{796910FA-6E94-460B-8CB4-97DF01B9ADC8}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{796910FA-6E94-460B-8CB4-97DF01B9ADC8}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{796910FA-6E94-460B-8CB4-97DF01B9ADC8}.Release|Any CPU.Build.0 = Release|Any CPU
+		{6046A2FC-6A39-4C2D-8DD9-AA3740B17B88}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{6046A2FC-6A39-4C2D-8DD9-AA3740B17B88}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{6046A2FC-6A39-4C2D-8DD9-AA3740B17B88}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{6046A2FC-6A39-4C2D-8DD9-AA3740B17B88}.Release|Any CPU.Build.0 = Release|Any CPU
+	EndGlobalSection
+	GlobalSection(SolutionProperties) = preSolution
+		HideSolutionNode = FALSE
+	EndGlobalSection
+	GlobalSection(NestedProjects) = preSolution
+		{796910FA-6E94-460B-8CB4-97DF01B9ADC8} = {7907FB6A-1353-4735-95DC-EEC5DF8C0649}
+		{6046A2FC-6A39-4C2D-8DD9-AA3740B17B88} = {5455D423-2AFC-4BC6-B79D-9DC4270D8F7D}
+	EndGlobalSection
+	GlobalSection(ExtensibilityGlobals) = postSolution
+		SolutionGuid = {870D888D-5C8B-4057-8722-F73ECF38E513}
+	EndGlobalSection
+EndGlobal
diff --git a/dotnetv3/CloudFormation/README.md b/dotnetv3/CloudFormation/README.md
@@ -0,0 +1,97 @@
+# CloudFormation code examples for the SDK for .NET
+
+## Overview
+
+Shows how to use the AWS SDK for .NET to work with AWS CloudFormation.
+
+<!--custom.overview.start-->
+<!--custom.overview.end-->
+
+_CloudFormation enables you to create and provision AWS infrastructure deployments predictably and repeatedly._
+
+## ⚠ Important
+
+* Running this code might result in charges to your AWS account. For more details, see [AWS Pricing](https://aws.amazon.com/pricing/) and [Free Tier](https://aws.amazon.com/free/).
+* Running the tests might result in charges to your AWS account.
+* We recommend that you grant your code least privilege. At most, grant only the minimum permissions required to perform the task. For more information, see [Grant least privilege](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#grant-least-privilege).
+* This code is not tested in every AWS Region. For more information, see [AWS Regional Services](https://aws.amazon.com/about-aws/global-infrastructure/regional-product-services).
+
+<!--custom.important.start-->
+<!--custom.important.end-->
+
+## Code examples
+
+### Prerequisites
+
+For prerequisites, see the [README](../README.md#Prerequisites) in the `dotnetv3` folder.
+
+
+<!--custom.prerequisites.start-->
+<!--custom.prerequisites.end-->
+
+### Get started
+
+- [Hello CloudFormation](Actions/HelloCloudFormation.cs#L4) (`DescribeStackResources`)
+
+
+<!--custom.examples.start-->
+<!--custom.examples.end-->
+
+## Run the examples
+
+### Instructions
+
+For general instructions to run the examples, see the
+[README](../README.md#building-and-running-the-code-examples) in the `dotnetv3` folder.
+
+Some projects might include a settings.json file. Before compiling the project,
+you can change these values to match your own account and resources. Alternatively,
+add a settings.local.json file with your local settings, which will be loaded automatically
+when the application runs.
+
+After the example compiles, you can run it from the command line. To do so, navigate to
+the folder that contains the .csproj file and run the following command:
+
+```
+dotnet run
+```
+
+Alternatively, you can run the example from within your IDE.
+
+
+<!--custom.instructions.start-->
+<!--custom.instructions.end-->
+
+#### Hello CloudFormation
+
+This example shows you how to Get started using CloudFormation.
+
+
+
+### Tests
+
+⚠ Running tests might result in charges to your AWS account.
+
+
+To find instructions for running these tests, see the [README](../README.md#Tests)
+in the `dotnetv3` folder.
+
+
+
+<!--custom.tests.start-->
+<!--custom.tests.end-->
+
+## Additional resources
+
+- [CloudFormation User Guide](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html)
+- [CloudFormation API Reference](https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/Welcome.html)
+- [SDK for .NET CloudFormation reference](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/CloudFormation/NCloudFormation.html)
+
+<!--custom.resources.start-->
+<!--custom.resources.end-->
+
+---
+
+Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+
+SPDX-License-Identifier: Apache-2.0
diff --git a/dotnetv3/CloudFormation/Tests/CloudFormationTests.cs b/dotnetv3/CloudFormation/Tests/CloudFormationTests.cs
@@ -0,0 +1,29 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. 
+// SPDX-License-Identifier: Apache-2.0
+
+using Amazon.CloudFormation;
+using CloudFormationActions;
+
+namespace CloudFormationTests;
+
+public class CloudFormationTests
+{
+    /// <summary>
+    /// Run the list resources action. Should return true.
+    /// </summary>
+    /// <returns></returns>
+    [Fact]
+    [Order(1)]
+    [Trait("Category", "Integration")]
+    public async Task TestListResources()
+    {
+        // Arrange.
+        HelloCloudFormation._amazonCloudFormation = new AmazonCloudFormationClient();
+
+        // Act.
+        var success = await HelloCloudFormation.ListResources();
+
+        // Assert.
+        Assert.True(success);
+    }
+}
diff --git a/dotnetv3/CloudFormation/Tests/CloudFormationTests.csproj b/dotnetv3/CloudFormation/Tests/CloudFormationTests.csproj
@@ -0,0 +1,40 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>net6.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+
+    <IsPackable>false</IsPackable>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="AWSSDK.CloudFormation" Version="3.7.303.5" />
+    <PackageReference Include="AWSSDK.SSO" Version="3.7.300.49" />
+    <PackageReference Include="AWSSDK.SSOOIDC" Version="3.7.301.44" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.Json" Version="6.0.0" />
+    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.1.0" />
+    <PackageReference Include="xunit" Version="2.4.1" />
+    <PackageReference Include="Xunit.Extensions.Ordering" Version="1.4.5" />
+    <PackageReference Include="xunit.runner.visualstudio" Version="2.4.3">
+      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
+      <PrivateAssets>all</PrivateAssets>
+    </PackageReference>
+    <PackageReference Include="coverlet.collector" Version="3.1.2">
+      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
+      <PrivateAssets>all</PrivateAssets>
+    </PackageReference>
+  </ItemGroup>
+
+	<ItemGroup>
+		<Content Include="testsettings.*.json">
+			<CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
+			<DependentUpon>testsettings.json</DependentUpon>
+		</Content>
+	</ItemGroup>
+
+	<ItemGroup>
+		<ProjectReference Include="..\Actions\CloudFormationActions.csproj" />
+	</ItemGroup>
+
+</Project>
diff --git a/dotnetv3/CloudFormation/Tests/Usings.cs b/dotnetv3/CloudFormation/Tests/Usings.cs
@@ -0,0 +1,12 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. 
+// SPDX-License-Identifier: Apache-2.0
+
+global using Xunit;
+global using Xunit.Extensions.Ordering;
+
+// Optional.
+[assembly: CollectionBehavior(DisableTestParallelization = true)]
+// Optional.
+[assembly: TestCaseOrderer("Xunit.Extensions.Ordering.TestCaseOrderer", "Xunit.Extensions.Ordering")]
+// Optional.
+[assembly: TestCollectionOrderer("Xunit.Extensions.Ordering.CollectionOrderer", "Xunit.Extensions.Ordering")]
diff --git a/dotnetv3/README.md b/dotnetv3/README.md
@@ -34,7 +34,7 @@ Developer Guide](https://docs.aws.amazon.com/sdk-for-net/latest/developer-guide/
 
 - AWS credentials, either configured in a local AWS credentials file, or by
 setting the AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables.
-For more information, see the [AWS Tools and SDKs Shared Configuration and Credentials Reference Guide](https://docs.aws.amazon.com/credref/latest/refdocs/overview.html).
+For more information, see the authentication topics in the [AWS SDK for .NET Developer Guide](https://docs.aws.amazon.com/sdk-for-net/v3/developer-guide/creds-idc.html) and the [AWS Tools and SDKs Shared Configuration and Credentials Reference Guide](https://docs.aws.amazon.com/sdkref/latest/guide/access.html).
 
 ## Building and running the code examples