Versi 4 (V4) dari AWS SDK untuk .NET telah dirilis\$1 Untuk informasi tentang melanggar perubahan dan memigrasi aplikasi Anda, lihat [topik migrasi](https://docs.aws.amazon.com/sdk-for-net/v4/developer-guide/net-dg-v4.html). [https://docs.aws.amazon.com/sdk-for-net/v4/developer-guide/net-dg-v4.html](https://docs.aws.amazon.com/sdk-for-net/v4/developer-guide/net-dg-v4.html) Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris. # Menggunakan AWS SDK untuk .NET Bagian ini memberikan informasi tentang fitur AWS SDK untuk .NET yang mungkin perlu Anda pertimbangkan saat membuat aplikasi Anda. Sebelum Anda mulai, pastikan Anda telah [mengatur lingkungan Anda](net-dg-config.md) dan [mengkonfigurasi proyek Anda](configuring-the-sdk.md). Untuk informasi tentang mengembangkan perangkat lunak untuk AWS layanan tertentu bersama dengan contoh kode, lihat[ AWS Layanan panggilan](working-with-aws-services.md). Untuk contoh kode tambahan, lihat[SDK untuk .NET (v4) contoh kode](csharp_code_examples.md). **Topics** + [Pemrograman asinkron](sdk-net-async-api.md) + [Paginasi](paginators.md) + [Support untuk HTTP 2](http2-support.md) + [Alat tambahan](sdk-features-additional-tools.md) # Pemrograman secara asinkron menggunakan AWS SDK untuk .NET AWS SDK untuk .NET Menggunakan *Task-based Asynchronous Pattern (TAP) untuk implementasi asinkron*. Untuk mempelajari TAP selengkapnya, lihat [Pola Asinkron Berbasis Tugas (TAP](https://learn.microsoft.com/en-us/dotnet/standard/asynchronous-programming-patterns/task-based-asynchronous-pattern-tap)) di docs.microsoft.com. Topik ini memberi Anda gambaran umum tentang cara menggunakan TAP dalam panggilan Anda ke klien AWS layanan. Metode asinkron dalam AWS SDK untuk .NET API adalah operasi berdasarkan `Task` kelas atau kelas. `Task` [Lihat docs.microsoft.com untuk informasi tentang kelas-kelas ini: Kelas tugas, [Tugas < > kelas](https://learn.microsoft.com/en-us/dotnet/api/system.threading.tasks.task). TResult](https://learn.microsoft.com/en-us/dotnet/api/system.threading.tasks.task-1) Ketika metode API ini dipanggil dalam kode Anda, mereka harus dipanggil dalam fungsi yang dideklarasikan dengan `async` kata kunci, seperti yang ditunjukkan pada contoh berikut. ``` static async Task Main(string[] args) { ... // Call the function that contains the asynchronous API method. // Could also call the asynchronous API method directly from Main // because Main is declared async var response = await ListBucketsAsync(); Console.WriteLine($"Number of buckets: {response.Buckets.Count}"); ... } // Async method to get a list of Amazon S3 buckets. private static async Task ListBucketsAsync() { ... var response = await s3Client.ListBucketsAsync(); return response; } ``` Seperti yang ditunjukkan pada cuplikan kode sebelumnya, ruang lingkup yang lebih disukai untuk `async` deklarasi adalah fungsinya. `Main` Menyetel `async` cakupan ini memastikan bahwa semua panggilan ke klien AWS layanan harus asinkron. Jika Anda tidak dapat mendeklarasikan `Main` asinkron karena alasan tertentu, Anda dapat menggunakan `async` kata kunci pada fungsi selain `Main` dan kemudian memanggil metode API dari sana, seperti yang ditunjukkan pada contoh berikut. ``` static void Main(string[] args) { ... Task response = ListBucketsAsync(); Console.WriteLine($"Number of buckets: {response.Result.Buckets.Count}"); ... } // Async method to get a list of Amazon S3 buckets. private static async Task ListBucketsAsync() { ... var response = await s3Client.ListBucketsAsync(); return response; } ``` Perhatikan `Task<>` sintaks khusus yang diperlukan `Main` saat Anda menggunakan pola ini. Selain itu, Anda harus menggunakan **`Result`**anggota respons untuk mendapatkan data. Anda dapat melihat contoh lengkap panggilan asinkron ke klien AWS layanan di [Membuat aplikasi sederhana](quick-start.md) bagian ([Aplikasi lintas platform sederhana](quick-start-s3-1-cross.md)dan[Aplikasi berbasis Windows sederhana](quick-start-s3-1-winvs.md)) dan di. [Contoh kode terpanduPustaka dan kerangka kerja tingkat tinggi](tutorials-examples.md) # Menggunakan hasil paginasi di AWS SDK untuk .NET Beberapa AWS layanan mengumpulkan dan menyimpan sejumlah besar data, yang dapat Anda ambil dengan menggunakan panggilan API. AWS SDK untuk .NET*Jika jumlah data yang ingin Anda ambil menjadi terlalu besar untuk satu panggilan API, Anda dapat memecah hasilnya menjadi potongan-potongan yang lebih mudah dikelola melalui penggunaan pagination.* Untuk memungkinkan Anda melakukan pagination, objek permintaan dan respons untuk banyak klien layanan di SDK menyediakan *token lanjutan* (biasanya bernama). `NextToken` Beberapa klien layanan ini juga menyediakan **paginator**. Paginator memungkinkan Anda menghindari overhead token lanjutan, yang mungkin melibatkan loop, variabel status, beberapa panggilan API, dan sebagainya. Bila Anda menggunakan paginator, Anda dapat mengambil data dari AWS layanan melalui satu baris kode, deklarasi `foreach` loop. Jika beberapa panggilan API diperlukan untuk mengambil data, paginator menangani ini untuk Anda. ## Di mana saya menemukan paginator? Tidak semua layanan menyediakan paginator. Salah satu cara untuk menentukan apakah layanan menyediakan paginator untuk API tertentu adalah dengan melihat definisi kelas klien layanan di Referensi [AWS SDK untuk .NET API](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/). Misalnya, jika Anda memeriksa definisi untuk [AmazonCloudWatchLogsClient](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/CloudWatchLogs/TCloudWatchLogsClient.html)kelas, Anda melihat `Paginators` properti. Ini adalah properti yang menyediakan paginator untuk Amazon CloudWatch Logs. ## Apa yang diberikan paginator kepada saya? Paginator berisi properti yang memungkinkan Anda melihat respons lengkap. Mereka juga biasanya berisi satu atau lebih properti yang memungkinkan Anda mengakses bagian paling menarik dari tanggapan, yang akan kami sebut *hasil utama*. Misalnya, dalam yang `AmazonCloudWatchLogsClient` disebutkan sebelumnya, `Paginator` objek berisi `Responses` properti dengan [DescribeLogGroupsResponse](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/CloudWatchLogs/TDescribeLogGroupsResponse.html)objek lengkap dari panggilan API. `Responses`Properti ini berisi, antara lain, kumpulan grup log. Objek Paginator juga berisi satu hasil kunci bernama. `LogGroups` Properti ini hanya menyimpan bagian log grup dari respons. Memiliki hasil kunci ini memungkinkan Anda untuk mengurangi dan menyederhanakan kode Anda dalam banyak keadaan. ## Pagination sinkron vs asinkron Paginator menyediakan mekanisme sinkron dan asinkron untuk pagination. Pagination sinkron tersedia dalam proyek .NET Framework 4.7.2 (atau yang lebih baru). Pagination asinkron tersedia di proyek .NET Core (.NET Core 3.1, .NET 5, dan seterusnya). Karena operasi asinkron dan .NET Core direkomendasikan, contoh yang muncul berikutnya menunjukkan pagination asinkron. Informasi tentang cara melakukan tugas yang sama menggunakan pagination sinkron dan .NET Framework 4.7.2 (atau yang lebih baru) ditampilkan setelah contoh di. [Pertimbangan tambahan untuk paginator](#paginators-additional) ## Contoh Contoh berikut menunjukkan cara menggunakan AWS SDK untuk .NET untuk menampilkan daftar grup log. Sebagai kontras, contoh menunjukkan bagaimana melakukan ini baik dengan maupun tanpa paginator. Sebelum melihat kode lengkap, ditampilkan nanti, pertimbangkan cuplikan berikut. **Mendapatkan grup CloudWatch log tanpa paginator** ``` // Loop as many times as needed to get all the log groups var request = new DescribeLogGroupsRequest{Limit = LogGroupLimit}; do { Console.WriteLine($"Getting up to {LogGroupLimit} log groups..."); var response = await cwClient.DescribeLogGroupsAsync(request); foreach(var logGroup in response.LogGroups) { Console.WriteLine($"{logGroup.LogGroupName}"); } request.NextToken = response.NextToken; } while(!string.IsNullOrEmpty(request.NextToken)); ``` **Mendapatkan grup CloudWatch log dengan menggunakan paginator** ``` // No need to loop to get all the log groups--the SDK does it for us behind the scenes var paginatorForLogGroups = cwClient.Paginators.DescribeLogGroups(new DescribeLogGroupsRequest()); await foreach(var logGroup in paginatorForLogGroups.LogGroups) { Console.WriteLine(logGroup.LogGroupName); } ``` Hasil dari kedua cuplikan ini persis sama, sehingga keuntungan dalam menggunakan paginator dapat dilihat dengan jelas. **catatan** Sebelum Anda mencoba membangun dan menjalankan kode lengkap, pastikan Anda telah [menyiapkan lingkungan dan proyek Anda](net-dg-config.md). Anda mungkin juga membutuhkan [Microsoft.Bcl. AsyncInterfaces](https://www.nuget.org/packages/Microsoft.Bcl.AsyncInterfaces/) NuGet paket karena paginator asinkron menggunakan antarmuka. `IAsyncEnumerable` ### Kode lengkap Bagian ini menunjukkan referensi yang relevan dan kode lengkap untuk contoh ini. #### Referensi SDK NuGet paket: + [AWSSDK.CloudWatch](https://www.nuget.org/packages/AWSSDK.CloudWatch) Elemen pemrograman: + [Namespace Amazon. CloudWatch](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/CloudWatch/NCloudWatch.html) Kelas [AmazonCloudWatchLogsClient](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/CloudWatchLogs/TCloudWatchLogsClient.html) + [Namespace Amazon. CloudWatchLogs.Model](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/CloudWatchLogs/NCloudWatchLogsModel.html) Kelas [DescribeLogGroupsRequest](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/CloudWatchLogs/TDescribeLogGroupsRequest.html) Kelas [DescribeLogGroupsResponse](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/CloudWatchLogs/TDescribeLogGroupsResponse.html) Kelas [LogGroup](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/CloudWatchLogs/TLogGroup.html) #### Kode lengkap ``` using System; using System.Threading.Tasks; using Amazon.CloudWatchLogs; using Amazon.CloudWatchLogs.Model; namespace CWGetLogGroups { class Program { // A small limit for demonstration purposes private const int LogGroupLimit = 3; // // Main method static async Task Main(string[] args) { var cwClient = new AmazonCloudWatchLogsClient(); await DisplayLogGroupsWithoutPaginators(cwClient); await DisplayLogGroupsWithPaginators(cwClient); } // // Method to get CloudWatch log groups without paginators private static async Task DisplayLogGroupsWithoutPaginators(IAmazonCloudWatchLogs cwClient) { Console.WriteLine("\nGetting list of CloudWatch log groups without using paginators..."); Console.WriteLine("------------------------------------------------------------------"); // Loop as many times as needed to get all the log groups var request = new DescribeLogGroupsRequest{Limit = LogGroupLimit}; do { Console.WriteLine($"Getting up to {LogGroupLimit} log groups..."); DescribeLogGroupsResponse response = await cwClient.DescribeLogGroupsAsync(request); foreach(LogGroup logGroup in response.LogGroups) { Console.WriteLine($"{logGroup.LogGroupName}"); } request.NextToken = response.NextToken; } while(!string.IsNullOrEmpty(request.NextToken)); } // // Method to get CloudWatch log groups by using paginators private static async Task DisplayLogGroupsWithPaginators(IAmazonCloudWatchLogs cwClient) { Console.WriteLine("\nGetting list of CloudWatch log groups by using paginators..."); Console.WriteLine("-------------------------------------------------------------"); // Access the key results; i.e., the log groups // No need to loop to get all the log groups--the SDK does it for us behind the scenes Console.WriteLine("\nFrom the key results..."); Console.WriteLine("------------------------"); IDescribeLogGroupsPaginator paginatorForLogGroups = cwClient.Paginators.DescribeLogGroups(new DescribeLogGroupsRequest()); await foreach(LogGroup logGroup in paginatorForLogGroups.LogGroups) { Console.WriteLine(logGroup.LogGroupName); } // Access the full response // Create a new paginator, do NOT reuse the one from above Console.WriteLine("\nFrom the full response..."); Console.WriteLine("--------------------------"); IDescribeLogGroupsPaginator paginatorForResponses = cwClient.Paginators.DescribeLogGroups(new DescribeLogGroupsRequest()); await foreach(DescribeLogGroupsResponse response in paginatorForResponses.Responses) { Console.WriteLine($"Content length: {response.ContentLength}"); Console.WriteLine($"HTTP result: {response.HttpStatusCode}"); Console.WriteLine($"Metadata: {response.ResponseMetadata}"); Console.WriteLine("Log groups:"); foreach(LogGroup logGroup in response.LogGroups) { Console.WriteLine($"\t{logGroup.LogGroupName}"); } } } } } ``` ## Pertimbangan tambahan untuk paginator + **Paginator tidak dapat digunakan lebih dari sekali** Jika Anda membutuhkan hasil AWS paginator tertentu di beberapa lokasi dalam kode Anda, Anda tidak boleh menggunakan objek paginator lebih dari sekali. Sebagai gantinya, buat paginator baru setiap kali Anda membutuhkannya. Konsep ini ditunjukkan dalam contoh kode sebelumnya dalam metode. `DisplayLogGroupsWithPaginators` + **pagination sinkron** Pagination sinkron tersedia untuk proyek-proyek .NET Framework 4.7.2 (atau yang lebih baru). Untuk melihat ini, buat proyek .NET Framework 4.7.2 (atau yang lebih baru) dan salin kode sebelumnya ke sana. Kemudian cukup hapus `await` kata kunci dari dua panggilan `foreach` paginator, seperti yang ditunjukkan pada contoh berikut. ``` /*await*/ foreach(var logGroup in paginatorForLogGroups.LogGroups) { Console.WriteLine(logGroup.LogGroupName); } ``` Bangun dan jalankan proyek untuk melihat hasil yang sama yang Anda lihat dengan pagination asinkron. # Support untuk HTTP 2 di AWS SDK untuk .NET Beberapa AWS layanan dan operasi memerlukan HTTP 2. Misalnya, streaming dua arah di Amazon Transcribe Streaming tidak dimungkinkan melalui HTTP 1.1 sehingga memerlukan HTTP 2 sebagai gantinya. Versi 4 dari dukungan AWS SDK untuk .NET tambahan untuk HTTP 2 sehingga Anda dapat menggunakan operasi ini dalam aplikasi Anda. Untuk operasi HTTP 2 dua arah, perilaku SDK saat menerima aliran mirip dengan HTTP 1.1. Artinya, ketika aplikasi yang menggunakan SDK mengirim peristiwa ke layanan, permintaan memiliki penerbit yang ditetapkan oleh pengembang. Untuk melihat perilaku ini beraksi, pertimbangkan contoh berikut untuk Amazon Transcribe Streaming. Ini menggunakan [Amazon. TranscribeStreaming](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/TranscribeStreaming/NTranscribeStreaming.html)dan [Amazon. TranscribeStreamingRuang nama .Model](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/TranscribeStreaming/NTranscribeStreamingModel.html). Dalam contoh ini, pengembang mendefinisikan `StartStreamTranscriptionRequest.AudioStreamPublisher` properti dengan fungsi callback, yang merupakan .NET. `Func` SDK menggunakan `Func` definisi for `AudioStreamPublisher` untuk menarik peristiwa dari kode pengguna untuk streaming ke pengguna. SDK memanggil `Func` sampai mengembalikan null. Kode menunjukkan bagaimana audio dari file dapat dialirkan ke Amazon Transcribe Streaming untuk diproses. ``` using Amazon; using Amazon.TranscribeStreaming; using Amazon.TranscribeStreaming.Model; CancellationTokenSource cancelSource = new CancellationTokenSource(); var client = new AmazonTranscribeStreamingClient(RegionEndpoint.USEast1); var startRequest = new StartStreamTranscriptionRequest { LanguageCode = LanguageCode.EnUS, MediaEncoding = MediaEncoding.Flac, MediaSampleRateHertz = 44100, NumberOfChannels = 2, EnableChannelIdentification = true }; Stream fileStream = File.OpenRead("hello-world.flac"); var buffer = new byte[1024 * 10]; startRequest.AudioStreamPublisher += async () => { var bytesRead = await fileStream.ReadAsync(buffer, 0, buffer.Length); if (bytesRead == 0) return null; var audioEvent = new AudioEvent { AudioChunk = new MemoryStream(buffer, 0, bytesRead) }; return audioEvent; }; using var response = await client.StartStreamTranscriptionAsync(startRequest); Console.WriteLine(response.HttpStatusCode); response.TranscriptResultStream.ExceptionReceived += TranscriptResultStream_ExceptionReceived; response.TranscriptResultStream.TranscriptEventReceived += TranscriptResultStream_TranscriptEventReceived; void TranscriptResultStream_ExceptionReceived(object? sender, Amazon.Runtime.EventStreams.EventStreamExceptionReceivedArgs e) { Console.WriteLine(e.EventStreamException.Message); cancelSource.Cancel(); } void TranscriptResultStream_TranscriptEventReceived(object? sender, Amazon.Runtime.EventStreams.EventStreamEventReceivedArgs e) { foreach (var result in e.EventStreamEvent.Transcript.Results) { if (!string.Equals("ch_0", result.ChannelId, StringComparison.OrdinalIgnoreCase)) continue; var text = result.Alternatives[0].Transcript; if (!string.IsNullOrEmpty(text)) { Console.WriteLine(text); } } } _ = response.TranscriptResultStream.StartProcessingAsync(); try { await Task.Delay(10000, cancelSource.Token); } catch (TaskCanceledException) { } ``` **Awas** [Beberapa operasi HTTP 2 dua arah, seperti metode `InvokeModelWithBidirectionalStreamAsync` dari Amazon Bedrock, Amazon. BedrockRuntime](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/BedrockRuntime/NBedrockRuntime.html)namespace, jangan mengembalikan respons dari pemanggilan awal pada klien layanan sampai beberapa peristiwa telah diterbitkan. Perilaku ini dapat menyebabkan aplikasi Anda diblokir. Untuk menghindari situasi ini, pisahkan kode aplikasi yang menyediakan peristiwa ke penerbit, dan jalankan pada utas yang berbeda dari utas yang memanggil operasi pada klien layanan. ## Pertimbangan tambahan + AWS SDK untuk .NET dukungan untuk HTTP 2 hanya tersedia dalam versi yang menargetkan .NET 8 dan di atasnya. Ini tidak tersedia dalam versi yang menargetkan .NET Framework. + Untuk informasi lebih rinci, lihat [PR 3730](https://github.com/aws/aws-sdk-net/pull/3730) di [aws-sdk-net](https://github.com/aws/aws-sdk-net) GitHubrepositori. # Alat tambahan Berikut ini adalah beberapa alat tambahan yang dapat Anda gunakan untuk memudahkan pekerjaan mengembangkan, menyebarkan, dan memelihara aplikasi.NET Anda. ## AWS Menyebarkan Alat Setelah Anda mengembangkan aplikasi .NET Core cloud-native Anda pada mesin pengembangan, Anda dapat menggunakan Alat AWS Deploy untuk.NET CLI agar lebih mudah menyebarkan aplikasi Anda. AWS Untuk informasi selengkapnya, lihat [Menyebarkan aplikasi ke AWS](deploying.md). ## AWS Kerangka Pemrosesan Pesan untuk.NET Jika Anda menggunakan layanan seperti Amazon SQS, Amazon SNS atau EventBridge Amazon, Anda mungkin dapat memanfaatkan Kerangka Pemrosesan Pesan AWS untuk.NET. Untuk informasi selengkapnya, lihat [AWS Kerangka Pemrosesan Pesan untuk.NET](msg-proc-fw.md). ## Integrasi dengan .NET Aspire Anda dapat memanfaatkan integrasi dengan.NET Aspire untuk meningkatkan loop dev dalam. Lihat informasi yang lebih lengkap di [Integrasi AWS dengan .NET Aspire di AWS SDK untuk .NET](aspire-integrations.md).