aws / aws-sdk-net

The official AWS SDK for .NET. For more information on the AWS SDK for .NET, see our web site:
http://aws.amazon.com/sdkfornet/
Apache License 2.0
2.02k stars 849 forks source link

AWS SDK for .NET Gitter

The AWS SDK for .NET enables .NET developers to easily work with Amazon Web Services and build scalable solutions with Amazon S3, Amazon DynamoDB, Amazon Glacier, and more.

Getting Help

Please use these community resources for getting help. We use the GitHub issues for tracking bugs and feature requests and have limited bandwidth to address them.

Opening Issues

If you encounter a bug with AWS SDK for .NET we would like to hear about it. Search the existing issues and try to make sure your problem doesn’t already exist before opening a new issue. It’s helpful if you include the version of AWS SDK .NET and the OS you’re using. Please include a stack trace and reduced repro case when appropriate, too.

The GitHub issues are intended for bug reports and feature requests. For help and questions with using AWS SDK for .NET please make use of the resources listed in the Getting Help section. There are limited resources available for handling issues and by keeping the list of open issues clean we can respond in a timely manner.

SDK Change Log

The change log for the SDK can be found in the SDK.CHANGELOG.ALL.md file. Change logs divided up by year can be found in the changelogs folder.

Maintenance and support for SDK major versions

For information about maintenance and support for SDK major versions and their underlying dependencies, see the following in the AWS SDKs and Tools Shared Configuration and Credentials Reference Guide:

Modularization

With version 3 of the AWS SDK for .NET the SDK has been modularized. This means a separate NuGet package is created for each service as well as a core project. To use this branch compile the solution in the sdk folder that matches the desired platform and then include the assemblies for the services needed as well as the core assembly.

Versioning

The AWS SDK for .NET uses a 4 part versioning scheme following the pattern of w.x.y.z.

The SDK assemblies are strongly named which requires consumers of the SDK to recompile every time the AssemblyVersion attribute is incremented. To avoid forced recompilations the AssemblyVersion only contains the w.x portion of the version. The full w.x.y.z version number is set in the AssemblyFileVersion attribute which is not part of the strong name.

Internal Namespace

Classes and interfaces with Internal in the namespace name are logically internal to the SDK but are often marked with a public access modifier, generally to allow the service-specific packages to use shared functionality in the Core package. Classes and interfaces in these namespaces are subject to modification or removal outside of versioning scheme described above. If you find yourself relying on Internal functionality directly, consider opening a Feature Request for your use case if one does not already exist.

Code Analyzers

Each service package includes a code analyzer that's automatically included when installing from NuGet. These analyzers are created based on the rules from the service model, and will generate a warning if you use a property value that's not valid (for example, shorter than the minimum length expected by the service).

Starting with the 3.7.200 versions of the AWS SDK for .NET NuGet packages, the analyzers target .NET Standard 2.0 and support Visual Studio 2019 RTM and later (announcement: https://github.com/aws/aws-sdk-net/issues/2998).

Users on Visual Studio 2017 (or earlier) can still use new versions of the SDK, but there'll be a new warning (CS8032) about analyzers failing to run. If the build system is configured to treat warnings as errors, this new warning will need to be suppressed or ignored (using WarningsNotAsErrors).

Unity Support

Starting with version 3.5 of the AWS SDK for .NET, projects using Unity 2018.1 or later should target the .NET Standard 2.0 release of the SDK. You can find additional information in the developer guide: Unity support and Migrating your Unity application.

You can find the archive for legacy Unity support at https://github.com/aws/aws-sdk-unity-net.

Functionality requiring AWS Common Runtime (CRT)

This SDK has optional functionality that requires the AWS Common Runtime (CRT) bindings to be included as a dependency with your application. This functionality includes:

If the required AWS Common Runtime components are not installed you will receive an error like Attempting to make a request that requires an implementation of AWS Signature V4a. Add a reference to the AWSSDK.Extensions.CrtIntegration NuGet package to your project to include the AWS Signature V4a signer., indicating that the required dependency is missing to use the associated functionality. To install this dependency follow the provided instructions.

Installing the AWS Common Runtime (CRT) Dependency

Add a reference to the NuGet package AWSSDK.Extensions.CrtIntegration to your project.

Tests

Important: Do not run the integration tests on a production account.

Integration tests can be found in the AWSSDK.IntegrationTests project. These test assume that a default profile has been configured for credentials. For information about setting up a default profile read the Developer Guide.

The tests are designed to create and delete the resources needed for testing but it is important to keep your data safe. Do not run these tests on accounts that contain production data or resources. Since AWS resources are created and deleted during the running of these tests, charges can occur. To reduce charges occurred by running the tests the test focus on AWS resources that have minimal cost.

Unit tests can be found in the AWSSDK.UnitTests project.

Protocol tests can be found in the sdk/test/ProtocolTests directory. Protocol tests ensure that each AWS protocol is working as expected. Each supported protocol is listed here. These tests are safe to run as they do not call real AWS services. You can run these tests by either opening the solution file and running the tests or via the dotnet cli by invoking dotnet test AWSSDK.ProtocolTests.NetStandard.csproj. The structure for the protocol test cases can be found here in the smithy docs.

NuGet Packages

Code Generator

All low-level service clients are created using the code generator found in the generator folder. The code generator uses the service models defined in the generator\ServiceModels folder.