Harmonization of CreateBucket Task

Frends.AmazonS3.CreateBucket/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## [2.0.0] - 2025-06-23
+### Changed
+- Made Task Harmonization changes
+	- Moved Connection.BucketName to Input
+	- Renamed ACL to Acl inside Connection
+	- Moved Connection.ObjectLockEnabledForBucket to Options and renamed to ObjectLockEnabled
+	- Refactored CreateBucket.cs to function with Harmonization changes/additions
+	- Made change to target .NET 8 in main and unit test projects instead of .NET 6
+### Added
+- Made Task Harmonization additions
+	- Created Input definition file
+	- Created Options definition file
+	- Added ThrowErrorOnFailure to Options 
+	- Added ErrorMessageOnFailure to Options
+	- Added BucketName to Result
+	- Added Error to Result
+	- Added migrations file
+
 ## [1.0.0] - 2023-07-28
 ### Added
 - Initial implementation

Frends.AmazonS3.CreateBucket/Frends.AmazonS3.CreateBucket.Test/AWSCredsUnitTests.cs

@@ -16,6 +16,8 @@ public class AWSCredsUnitTests
     private readonly string? _accessKey = Environment.GetEnvironmentVariable("HiQ_AWSS3Test_AccessKey");
     private readonly string? _secretAccessKey = Environment.GetEnvironmentVariable("HiQ_AWSS3Test_SecretAccessKey");
     private Connection _connection = new();
+    private Options _options = new();
+    private Input _input = new();
     private string? _bucketName;
 
     [TestInitialize]
@@ -26,7 +28,11 @@ public void Init()
             AwsAccessKeyId = _accessKey,
             AwsSecretAccessKey = _secretAccessKey,
             Region = Region.EuCentral1,
-            ObjectLockEnabledForBucket = false
+        };
+
+        _options = new Options
+        {
+            ObjectLockEnabled = false
         };
     }
 
@@ -59,42 +65,42 @@ public async Task CleanUp()
     [TestMethod]
     public async Task CreateBucket_SuccessTest()
     {
-        var acl = ACLs.Private;
+        var acl = Acls.Private;
         _bucketName = $"ritteambuckettest{acl.ToString().ToLower()}";
-        _connection.BucketName = _bucketName;
-        _connection.ACL = acl;
+        _input.BucketName = _bucketName;
+        _connection.Acl = acl;
 
-        var result = await AmazonS3.CreateBucket(_connection, default);
+        var result = await AmazonS3.CreateBucket(_input, _connection, _options, default);
         Assert.IsTrue(result.Success);
         Assert.AreEqual("eu-central-1", result.BucketLocation);
     }
 
     [TestMethod]
     public async Task CreateBucket_BucketAlreadyExistsTest()
     {
-        var acl = ACLs.Private;
+        var acl = Acls.Private;
         _bucketName = $"ritteambuckettest{acl.ToString().ToLower()}";
-        _connection.BucketName = _bucketName;
-        _connection.ACL = acl;
+        _input.BucketName = _bucketName;
+        _connection.Acl = acl;
 
-        var result = await AmazonS3.CreateBucket(_connection, default);
+        var result = await AmazonS3.CreateBucket(_input, _connection, _options, default);
         Assert.IsTrue(result.Success);
         Assert.AreEqual("eu-central-1", result.BucketLocation);
 
-        var result2 = await AmazonS3.CreateBucket(_connection, default);
+        var result2 = await AmazonS3.CreateBucket(_input, _connection, _options, default);
         Assert.IsTrue(result2.Success);
         Assert.AreEqual("Bucket already exists.", result2.BucketLocation);
     }
 
     [TestMethod]
     public async Task CreateBucket_ExceptionHandlingTest()
     {
-        var acl = ACLs.PublicRead;
+        var acl = Acls.PublicRead;
         _bucketName = $"ritteambuckettest{acl.ToString().ToLower()}";
-        _connection.BucketName = _bucketName;
-        _connection.ACL = acl;
+        _input.BucketName = _bucketName;
+        _connection.Acl = acl;
 
-        var ex = await Assert.ThrowsExceptionAsync<AmazonS3Exception>(() => AmazonS3.CreateBucket(_connection, default));
+        var ex = await Assert.ThrowsExceptionAsync<AmazonS3Exception>(() => AmazonS3.CreateBucket(_input, _connection, _options, default));
         Assert.IsNotNull(ex.InnerException);
         Assert.AreEqual("Access Denied", ex.InnerException.Message);
     }

Frends.AmazonS3.CreateBucket/Frends.AmazonS3.CreateBucket.Test/Frends.AmazonS3.CreateBucket.Tests.csproj

@@ -1,7 +1,7 @@
 <Project Sdk="Microsoft.NET.Sdk">
 
   <PropertyGroup>
-    <TargetFramework>net6.0</TargetFramework>
+    <TargetFramework>net8.0</TargetFramework>
     <Nullable>enable</Nullable>
 
     <IsPackable>false</IsPackable>

Frends.AmazonS3.CreateBucket/Frends.AmazonS3.CreateBucket/CreateBucket.cs

@@ -16,27 +16,49 @@ namespace Frends.AmazonS3.CreateBucket;
 /// </summary>
 public class AmazonS3
 {
+    /// <summary>
+    /// Error handling
+    /// </summary>
+    private static class ErrorHandler
+    {
+        internal static Result Handle(Exception ex, bool throwError, string customMessage)
+        {
+            var error = new Error
+            {
+                Message = $"{customMessage} {ex.Message}",
+                AdditionalInfo = ex
+            };
+
+            if (throwError)
+                throw new Exception(error.Message, ex);
+
+            return new Result(false, null, null, error);
+        }
+    }
+
     /// <summary>
     /// Create AWS S3 Bucket.
     /// [Documentation](https://tasks.frends.com/tasks/frends-tasks/Frends.AmazonS3.CreateBucket)
     /// </summary>
+    /// <param name="input">Input parameters.</param>
     /// <param name="connection">Connection parameters</param>
+    /// <param name="options">Options regarding object lock and error handling.</param>
     /// <param name="cancellationToken">Token generated by Frends to stop this Task.</param>
-    /// <returns>Object { bool success, string BucketLocation } </returns>
-    public static async Task<Result> CreateBucket([PropertyTab] Connection connection, CancellationToken cancellationToken)
+    /// <returns>Object { bool success, string BucketLocation, string BucketName, Error Error { string Message, Exception AdditionalInfo } } </returns>
+    public static async Task<Result> CreateBucket([PropertyTab] Input input, [PropertyTab] Connection connection, [PropertyTab] Options options, CancellationToken cancellationToken)
     {
         try
         {
             using IAmazonS3 s3Client = new AmazonS3Client(connection.AwsAccessKeyId, connection.AwsSecretAccessKey, RegionSelection(connection.Region));
-            var bucketName = connection.BucketName;
+            var bucketName = input.BucketName;
             if (!await AmazonS3Util.DoesS3BucketExistV2Async(s3Client, bucketName))
             {
                 var putBucketRequest = new PutBucketRequest
                 {
                     BucketName = bucketName,
                     UseClientRegion = true,
-                    CannedACL = GetS3CannedACL(connection.ACL),
-                    ObjectLockEnabledForBucket = connection.ObjectLockEnabledForBucket,
+                    CannedACL = GetS3CannedACL(connection.Acl),
+                    ObjectLockEnabledForBucket = options.ObjectLockEnabled,
                 };
 
                 PutBucketResponse putBucketResponse = await s3Client.PutBucketAsync(putBucketRequest, cancellationToken);
@@ -46,20 +68,20 @@ public static async Task<Result> CreateBucket([PropertyTab] Connection connectio
                     BucketName = bucketName
                 };
                 var response = await s3Client.GetBucketLocationAsync(getBucketLocationRequest, cancellationToken);
-                return new Result(true, response.Location.ToString());
+                return new Result(true, response.Location.ToString(), bucketName);
             }
             else
             {
-                return new Result(true, $"Bucket already exists.");
+                return new Result(true, $"Bucket already exists.", bucketName);
             }
         }
         catch (AmazonS3Exception e)
         {
-            throw new AmazonS3Exception("Failed to create the bucket.", e);
+            return ErrorHandler.Handle(e, options.ThrowErrorOnFailure, options.ErrorMessageOnFailure);
         }
         catch (Exception e)
         {
-            throw new Exception("Unexpected error occurred while creating the bucket.", e);
+            return ErrorHandler.Handle(e, options.ThrowErrorOnFailure, options.ErrorMessageOnFailure);
         }
     }
 
@@ -96,17 +118,17 @@ private static RegionEndpoint RegionSelection(Region region)
     }
 
     [ExcludeFromCodeCoverage(Justification = "can only test S3CannedACL.Private")]
-    private static S3CannedACL GetS3CannedACL(ACLs acl)
+    private static S3CannedACL GetS3CannedACL(Acls acl)
     {
         return acl switch
         {
-            ACLs.Private => S3CannedACL.Private,
-            ACLs.PublicRead => S3CannedACL.PublicRead,
-            ACLs.PublicReadWrite => S3CannedACL.PublicReadWrite,
-            ACLs.AuthenticatedRead => S3CannedACL.AuthenticatedRead,
-            ACLs.BucketOwnerRead => S3CannedACL.BucketOwnerRead,
-            ACLs.BucketOwnerFullControl => S3CannedACL.BucketOwnerFullControl,
-            ACLs.LogDeliveryWrite => S3CannedACL.LogDeliveryWrite,
+            Acls.Private => S3CannedACL.Private,
+            Acls.PublicRead => S3CannedACL.PublicRead,
+            Acls.PublicReadWrite => S3CannedACL.PublicReadWrite,
+            Acls.AuthenticatedRead => S3CannedACL.AuthenticatedRead,
+            Acls.BucketOwnerRead => S3CannedACL.BucketOwnerRead,
+            Acls.BucketOwnerFullControl => S3CannedACL.BucketOwnerFullControl,
+            Acls.LogDeliveryWrite => S3CannedACL.LogDeliveryWrite,
             _ => S3CannedACL.NoACL,
         };
     }

Frends.AmazonS3.CreateBucket/Frends.AmazonS3.CreateBucket/Definitions/Connection.cs

@@ -24,14 +24,6 @@ public class Connection
     [PasswordPropertyText]
     public string AwsSecretAccessKey { get; set; }
 
-    /// <summary>
-    /// AWS S3 bucket's name.
-    /// See https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-s3-bucket-naming-requirements.html
-    /// </summary>
-    /// <example>bucket</example>
-    [DisplayFormat(DataFormatString = "Text")]
-    public string BucketName { get; set; }
-
     /// <summary>
     /// AWS S3 bucket's region.
     /// </summary>
@@ -41,14 +33,7 @@ public class Connection
     /// <summary>
     /// Access control list.
     /// </summary>
-    /// <example>ACL.Private</example>
-    [DefaultValue(ACLs.Private)]
-    public ACLs ACL { get; set; }
-
-    /// <summary>
-    /// Specifies whether you want S3 Object Lock to be enabled for the new bucket.
-    /// </summary>
-    /// <example>false</example>
-    [DefaultValue(false)]
-    public bool ObjectLockEnabledForBucket { get; set; }
+    /// <example>Acl.Private</example>
+    [DefaultValue(Acls.Private)]
+    public Acls Acl { get; set; }
 }

Frends.AmazonS3.CreateBucket/Frends.AmazonS3.CreateBucket/Definitions/Enums.cs

@@ -35,7 +35,7 @@ public enum Region
 /// <summary>
 /// Access control list.
 /// </summary>
-public enum ACLs
+public enum Acls
 {
     /// <summary>
     /// Owner gets FULL_CONTROL. No one else has access rights (default).
@@ -63,7 +63,7 @@ public enum ACLs
     BucketOwnerRead,
 
     /// <summary>
-    /// Both the object owner and the bucket owner get FULL_CONTROL over the object. If you specify this canned ACL when creating a bucket, Amazon S3 ignores it.
+    /// Both the object owner and the bucket owner get FULL_CONTROL over the object. If you specify this canned Acl when creating a bucket, Amazon S3 ignores it.
     /// </summary>
     BucketOwnerFullControl,
 

Frends.AmazonS3.CreateBucket/Frends.AmazonS3.CreateBucket/Definitions/Input.cs

@@ -0,0 +1,18 @@
+using System.ComponentModel.DataAnnotations;
+
+namespace Frends.AmazonS3.CreateBucket.Definitions
+{
+    /// <summary>
+    /// Input parameters.
+    /// </summary>
+    public class Input
+    {
+        /// <summary>
+        /// AWS S3 bucket's name.
+        /// See https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-s3-bucket-naming-requirements.html
+        /// </summary>
+        /// <example>bucket</example>
+        [DisplayFormat(DataFormatString = "Text")]
+        public string BucketName { get; set; }
+    }
+}

Frends.AmazonS3.CreateBucket/Frends.AmazonS3.CreateBucket/Definitions/Options.cs

@@ -0,0 +1,35 @@
+using System.ComponentModel;
+using System.ComponentModel.DataAnnotations;
+
+namespace Frends.AmazonS3.CreateBucket.Definitions
+{
+    /// <summary>
+    /// Option parameters.
+    /// </summary>
+    public class Options
+    {
+        /// <summary>
+        /// Specifies whether you want S3 Object Lock to be enabled for the new bucket.
+        /// </summary>
+        /// <example>false</example>
+        [DefaultValue(false)]
+        public bool ObjectLockEnabled { get; set; }
+
+        /// <summary>
+        /// Gets or sets a value indicating whether an error should stop the Task and throw an exception.
+        /// If set to true, an exception will be thrown when an error occurs. If set to false, Task will try to continue and the error message will be added into Result.ErrorMessage and Result.Success will be set to false.
+        /// </summary>
+        /// <example>true</example>
+        [DefaultValue(true)]
+        public bool ThrowErrorOnFailure { get; set; }
+
+        /// <summary>
+        /// Gets or sets a custom error message that will be used when an error occurs and ThrowErrorOnFailure is true.
+        /// When ThrowErrorOnFailure is false, this message will be combined with the task's own error message.
+        /// </summary>
+        /// <example>Custom error message for bucket creation failure.</example>
+        [DisplayFormat(DataFormatString = "Text")]
+        [DefaultValue("Failed to create Amazon S3 bucket.")]
+        public string ErrorMessageOnFailure { get; set; } = "Failed to create Amazon S3 bucket.";
+    }
+}

Frends.AmazonS3.CreateBucket/Frends.AmazonS3.CreateBucket/Definitions/Result.cs

@@ -1,4 +1,24 @@
-namespace Frends.AmazonS3.CreateBucket.Definitions;
+using System.ComponentModel.DataAnnotations;
+
+namespace Frends.AmazonS3.CreateBucket.Definitions;
+
+/// <summary>
+/// Error that occurred during the task.
+/// </summary>
+public class Error
+{
+    /// <summary>
+    /// Summary of the error.
+    /// </summary>
+    /// <example>Unable to join strings.</example>
+    public string Message { get; set; }
+
+    /// <summary>
+    /// Additional information about the error.
+    /// </summary>
+    /// <example>object { Exception Exception }</example>
+    public object AdditionalInfo { get; set; }
+}
 
 /// <summary>
 /// Task's result.
@@ -18,9 +38,26 @@ public class Result
     /// <example>eu-central-1</example>
     public string BucketLocation { get; private set; }
 
-    internal Result(bool success, string bucketLocation)
+    /// <summary>
+    /// AWS S3 bucket's name.
+    /// See https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-s3-bucket-naming-requirements.html
+    /// </summary>
+    /// <example>bucket</example>
+    [DisplayFormat(DataFormatString = "Text")]
+    public string BucketName { get; private set; }
+
+    /// <summary>
+    /// Error that occurred during task execution.
+    /// </summary>
+    /// <example>object { string Message, object { Exception Exception } AdditionalInfo }</example>
+    public Error Error { get; private set; }
+
+    internal Result(bool success, string bucketLocation, string bucketName, Error error = null)
     {
         Success = success;
         BucketLocation = bucketLocation;
+        BucketName = bucketName;
+        Error = error;
+
     }
 }

Frends.AmazonS3.CreateBucket/Frends.AmazonS3.CreateBucket/Frends.AmazonS3.CreateBucket.csproj

@@ -1,8 +1,8 @@
 <Project Sdk="Microsoft.NET.Sdk">
 
   <PropertyGroup>
-	<TargetFrameworks>net6.0</TargetFrameworks>
-	<Version>1.0.0</Version>
+	<TargetFrameworks>net8.0</TargetFrameworks>
+	<Version>2.0.0</Version>
 	<Authors>Frends</Authors>
 	<Copyright>Frends</Copyright>
 	<Company>Frends</Company>