Skip to content

Commit a63ff3c

Browse files
rlhagermrlhagerm
committed
Add separate dotnet tech docs.
1 parent 0ae135e commit a63ff3c

File tree

7 files changed

+1813
-0
lines changed

7 files changed

+1813
-0
lines changed

‎steering_docs/dotnet-tech/basics.md‎

Lines changed: 393 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,393 @@
1+
# .NET Interactive Scenario Generation
2+
3+
## MANDATORY: Knowledge Base Consultation (FIRST STEP)
4+
**🚨 CRITICAL - Must be completed BEFORE any code generation**
5+
6+
```bash
7+
# Step 1: List available knowledge bases
8+
ListKnowledgeBases()
9+
10+
# Step 2: Query coding standards (REQUIRED)
11+
QueryKnowledgeBases("coding-standards-KB", "DotNet-code-example-standards")
12+
13+
# Step 3: Query implementation patterns (REQUIRED)
14+
QueryKnowledgeBases("DotNet-premium-KB", ".NET implementation patterns structure")
15+
16+
# Step 4: AWS service research (REQUIRED)
17+
search_documentation("What is [AWS Service] and what are its key API operations?")
18+
read_documentation("https://docs.aws.amazon.com/[service]/latest/[relevant-page]")
19+
```
20+
21+
**FAILURE TO COMPLETE KNOWLEDGE BASE CONSULTATION WILL RESULT IN INCORRECT CODE STRUCTURE**
22+
23+
## Purpose
24+
Generate interactive scenarios that demonstrate complete workflows using multiple service operations in a guided, educational manner. Implementation must be based on the service SPECIFICATION.md file.
25+
26+
## Requirements
27+
- **Specification-Driven**: MUST read the `scenarios/basics/{service}/SPECIFICATION.md`
28+
- **Interactive**: Use Console.WriteLine and Console.ReadLine for user input and guidance
29+
- **Educational**: Break complex workflows into logical phases
30+
- **Comprehensive**: Cover setup, demonstration, examination, and cleanup
31+
- **Error Handling**: Graceful error handling with user-friendly messages
32+
- **Wrapper Classes**: MUST use service wrapper classes for all operations
33+
34+
## File Structure
35+
```
36+
dotnetv4/{Service}/Scenarios/{Service}_Basics/
37+
├── {Service}Basics.cs # Main scenario file
38+
├── {Service}Basics.csproj # Project file
39+
```
40+
41+
## MANDATORY Pre-Implementation Steps
42+
43+
### Step 1: Read Service Specification
44+
**CRITICAL**: Always read `scenarios/basics/{service}/SPECIFICATION.md` first to understand:
45+
- **API Actions Used**: Exact operations to implement
46+
- **Proposed Example Structure**: Setup, demonstration, examination, cleanup phases
47+
- **Error Handling**: Specific error codes and handling requirements
48+
- **Scenario Flow**: Step-by-step workflow description
49+
50+
### Step 2: Extract Implementation Requirements
51+
From the specification, identify:
52+
- **Setup Phase**: What resources need to be created/configured
53+
- **Demonstration Phase**: What operations to demonstrate
54+
- **Examination Phase**: What data to display and how to filter/analyze
55+
- **Cleanup Phase**: What resources to clean up and user options
56+
57+
## Scenario Class Pattern
58+
### Implementation Pattern Based on SPECIFICATION.md
59+
```csharp
60+
// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
61+
// SPDX-License-Identifier: Apache-2.0
62+
63+
/// <summary>
64+
/// Purpose
65+
///
66+
/// Shows how to use {AWS Service} to {scenario description}. This scenario demonstrates:
67+
///
68+
/// 1. {Phase 1 description}
69+
/// 2. {Phase 2 description}
70+
/// 3. {Phase 3 description}
71+
/// 4. {Phase 4 description}
72+
///
73+
/// This example uses the AWS SDK for .NET v4 to interact with {AWS Service}.
74+
/// </summary>
75+
76+
using System;
77+
using System.Threading.Tasks;
78+
using Amazon.{Service};
79+
using Microsoft.Extensions.DependencyInjection;
80+
using Microsoft.Extensions.Hosting;
81+
using Microsoft.Extensions.Logging;
82+
83+
namespace Amazon.DocSamples.{Service}
84+
{
85+
public class {Service}Basics
86+
{
87+
private static ILogger logger = null!;
88+
private static {Service}Wrapper wrapper = null!;
89+
private static string? resourceId = null;
90+
91+
/// <summary>
92+
/// Main entry point for the {AWS Service} basics scenario.
93+
/// </summary>
94+
/// <param name="args">Command line arguments.</param>
95+
public static async Task Main(string[] args)
96+
{
97+
using var host = Host.CreateDefaultBuilder(args)
98+
.ConfigureServices((_, services) =>
99+
services.AddAWSService<IAmazon{Service}>()
100+
.AddTransient<{Service}Wrapper>()
101+
)
102+
.Build();
103+
104+
logger = LoggerFactory.Create(builder => { builder.AddConsole(); })
105+
.CreateLogger<{Service}Basics>();
106+
107+
wrapper = host.Services.GetRequiredService<{Service}Wrapper>();
108+
109+
await RunScenario();
110+
}
111+
112+
/// <summary>
113+
/// Runs the {AWS Service} basics scenario.
114+
/// </summary>
115+
public static async Task RunScenario()
116+
{
117+
Console.WriteLine(new string('-', 88));
118+
Console.WriteLine("Welcome to the {AWS Service} basics scenario!");
119+
Console.WriteLine(new string('-', 88));
120+
Console.WriteLine("{Service description and what users will learn}");
121+
Console.WriteLine();
122+
123+
try
124+
{
125+
await SetupPhase();
126+
await DemonstrationPhase();
127+
await ExaminationPhase();
128+
}
129+
catch (Exception ex)
130+
{
131+
logger.LogError("Scenario failed: {Message}", ex.Message);
132+
Console.WriteLine($"The scenario encountered an error: {ex.Message}");
133+
}
134+
finally
135+
{
136+
await CleanupPhase();
137+
}
138+
}
139+
140+
/// <summary>
141+
/// Setup phase: Implement based on specification's Setup section.
142+
/// </summary>
143+
private static async Task SetupPhase()
144+
{
145+
Console.WriteLine("Setting up {AWS Service}...");
146+
Console.WriteLine();
147+
148+
// Example: Check for existing resources (from specification)
149+
var existingResources = await wrapper.ListResourcesAsync();
150+
if (existingResources.Count > 0)
151+
{
152+
Console.WriteLine($"Found {existingResources.Count} existing resource(s):");
153+
foreach (var resource in existingResources)
154+
{
155+
Console.WriteLine($" - {resource}");
156+
}
157+
158+
Console.Write("Would you like to use an existing resource? (y/n): ");
159+
var useExisting = Console.ReadLine()?.ToLower() == "y";
160+
if (useExisting)
161+
{
162+
resourceId = existingResources[0];
163+
return;
164+
}
165+
}
166+
}
167+
168+
/// <summary>
169+
/// Demonstration phase: Implement operations from specification.
170+
/// </summary>
171+
private static async Task DemonstrationPhase()
172+
{
173+
Console.WriteLine("Demonstrating {AWS Service} capabilities...");
174+
Console.WriteLine();
175+
176+
// Implement specific operations from specification
177+
// Example: Generate sample data if specified
178+
await wrapper.CreateSampleDataAsync(resourceId);
179+
Console.WriteLine("✓ Sample data created successfully");
180+
181+
// Wait if specified in the specification
182+
Console.WriteLine("Waiting for data to be processed...");
183+
await Task.Delay(5000);
184+
}
185+
186+
/// <summary>
187+
/// Examination phase: Implement data analysis from specification.
188+
/// </summary>
189+
private static async Task ExaminationPhase()
190+
{
191+
Console.WriteLine("Examining {AWS Service} data...");
192+
Console.WriteLine();
193+
194+
// List and examine data as specified
195+
var dataItems = await wrapper.ListDataAsync(resourceId);
196+
if (dataItems.Count == 0)
197+
{
198+
Console.WriteLine("No data found. Data may take a few minutes to appear.");
199+
return;
200+
}
201+
202+
Console.WriteLine($"Found {dataItems.Count} data item(s)");
203+
204+
// Get detailed information as specified
205+
var detailedData = await wrapper.GetDataDetailsAsync(resourceId, dataItems.Take(5).ToList());
206+
DisplayDataSummary(detailedData);
207+
208+
// Show detailed view if specified
209+
if (detailedData.Count > 0)
210+
{
211+
Console.Write("Would you like to see detailed information? (y/n): ");
212+
var showDetails = Console.ReadLine()?.ToLower() == "y";
213+
if (showDetails)
214+
{
215+
DisplayDataDetails(detailedData[0]);
216+
}
217+
}
218+
219+
// Filter data as specified
220+
FilterDataByCriteria(dataItems);
221+
}
222+
223+
/// <summary>
224+
/// Cleanup phase: Implement cleanup options from specification.
225+
/// </summary>
226+
private static async Task CleanupPhase()
227+
{
228+
if (string.IsNullOrEmpty(resourceId))
229+
return;
230+
231+
Console.WriteLine("Cleanup options:");
232+
Console.WriteLine("Note: Deleting the resource will stop all monitoring/processing.");
233+
234+
Console.Write("Would you like to delete the resource? (y/n): ");
235+
var deleteResource = Console.ReadLine()?.ToLower() == "y";
236+
237+
if (deleteResource)
238+
{
239+
try
240+
{
241+
await wrapper.DeleteResourceAsync(resourceId);
242+
Console.WriteLine($"✓ Deleted resource: {resourceId}");
243+
}
244+
catch (Exception ex)
245+
{
246+
Console.WriteLine($"Error deleting resource: {ex.Message}");
247+
}
248+
}
249+
else
250+
{
251+
Console.WriteLine($"Resource {resourceId} will continue running.");
252+
Console.WriteLine("You can manage it through the AWS Console or delete it later.");
253+
}
254+
}
255+
}
256+
}
257+
```
258+
259+
## Scenario Phase Structure (Based on Specification)
260+
261+
### Setup Phase
262+
- **Read specification Setup section** for exact requirements
263+
- Check for existing resources as specified
264+
- Create necessary resources using wrapper methods
265+
- Configure service settings per specification
266+
- Verify setup completion as described
267+
268+
### Demonstration Phase
269+
- **Follow specification Demonstration section** exactly
270+
- Perform core service operations using wrapper methods
271+
- Generate sample data if specified in the specification
272+
- Show service capabilities as outlined
273+
- Provide educational context from specification
274+
275+
### Examination Phase
276+
- **Implement specification Examination section** requirements
277+
- List and examine results using wrapper methods
278+
- Filter and analyze data as specified
279+
- Display detailed information per specification format
280+
- Allow user interaction as described in specification
281+
282+
### Cleanup Phase
283+
- **Follow specification Cleanup section** guidance
284+
- Offer cleanup options with warnings from specification
285+
- Handle cleanup errors gracefully using wrapper methods
286+
- Provide alternative management options as specified
287+
- Confirm completion per specification
288+
289+
## User Interaction Patterns
290+
291+
### Question Types
292+
```python
293+
# Yes/No questions
294+
use_existing = q.ask("Use existing resource? (y/n): ", q.is_yesno)
295+
296+
# Text input
297+
resource_name = q.ask("Enter resource name: ")
298+
299+
# Numeric input
300+
count = q.ask("How many items? ", q.is_int)
301+
```
302+
303+
### Information Display
304+
```python
305+
# Progress indicators
306+
print("✓ Operation completed successfully")
307+
print("⚠ Warning message")
308+
print("✗ Error occurred")
309+
310+
# Formatted output
311+
print("-" * 60)
312+
print(f"Found {len(items)} items:")
313+
for item in items:
314+
print(f" • {item['name']}")
315+
```
316+
317+
## Specification-Based Error Handling
318+
319+
### Error Handling from Specification
320+
The specification includes an "Errors" section with specific error codes and handling:
321+
322+
```csharp
323+
// Example error handling based on specification
324+
try
325+
{
326+
var response = await wrapper.CreateResourceAsync();
327+
return response;
328+
}
329+
catch (Amazon{Service}Exception ex)
330+
{
331+
var errorCode = ex.ErrorCode;
332+
if (errorCode == "BadRequestException")
333+
{
334+
// Handle as specified: "Validate input parameters and notify user"
335+
Console.WriteLine("Invalid configuration. Please check your parameters.");
336+
}
337+
else if (errorCode == "InternalServerErrorException")
338+
{
339+
// Handle as specified: "Retry operation with exponential backoff"
340+
Console.WriteLine("Service temporarily unavailable. Retrying...");
341+
// Implement retry logic
342+
}
343+
else
344+
{
345+
Console.WriteLine($"Unexpected error: {ex.Message}");
346+
}
347+
throw;
348+
}
349+
```
350+
351+
## Scenario Requirements
352+
- ✅ **ALWAYS** read and implement based on `scenarios/basics/{service}/SPECIFICATION.md`
353+
- ✅ **ALWAYS** include descriptive XML documentation at top explaining scenario steps from specification
354+
- ✅ **ALWAYS** use Console.WriteLine and Console.ReadLine for user interaction
355+
- ✅ **ALWAYS** use service wrapper classes for all AWS operations
356+
- ✅ **ALWAYS** implement proper cleanup in finally block
357+
- ✅ **ALWAYS** break scenario into logical phases per specification
358+
- ✅ **ALWAYS** include error handling per specification's Errors section
359+
- ✅ **ALWAYS** provide educational context and explanations from specification
360+
- ✅ **ALWAYS** handle edge cases (no resources found, etc.) as specified
361+
362+
## Implementation Workflow
363+
364+
### Step-by-Step Implementation Process
365+
1. **Read Specification**: Study `scenarios/basics/{service}/SPECIFICATION.md` thoroughly
366+
2. **Extract API Actions**: Note all API actions listed in "API Actions Used" section
367+
3. **Map to Wrapper Methods**: Ensure wrapper class has methods for all required actions
368+
4. **Implement Phases**: Follow the "Proposed example structure" section exactly
369+
5. **Add Error Handling**: Implement error handling per the "Errors" section
370+
6. **Test Against Specification**: Verify implementation matches specification requirements
371+
372+
### Specification Sections to Implement
373+
- **API Actions Used**: All operations must be available in wrapper class
374+
- **Proposed example structure**: Direct mapping to scenario phases
375+
- **Setup**: Exact setup steps and resource creation
376+
- **Demonstration**: Specific operations to demonstrate
377+
- **Examination**: Data analysis and filtering requirements
378+
- **Cleanup**: Resource cleanup options and user choices
379+
- **Errors**: Specific error codes and handling strategies
380+
381+
## Error Handling in Scenarios
382+
- **Follow specification error table**: Implement exact error handling per specification
383+
- Catch and display user-friendly error messages per specification guidance
384+
- Continue scenario execution when possible as specified
385+
- Provide guidance on resolving issues from specification
386+
- Ensure cleanup runs even if errors occur
387+
388+
## Educational Elements
389+
- **Use specification descriptions**: Explain operations using specification language
390+
- Show before/after states as outlined in specification
391+
- Provide context about service capabilities from specification
392+
- Include tips and best practices mentioned in specification
393+
- Follow the educational flow described in specification structure

0 commit comments

Comments
 (0)