Skip to content

Commit f26e999

Browse files
aaronpowellaaronpowell
authored
Copilot SDK Cookbook (github#80)
* Cookbook: add landing page - Central hub for all language cookbooks - Links to 4 languages with 4 recipes each - Quick-start commands for each language * Cookbook(.NET): add 4 recipes with docs and runnable examples Recipes: - error-handling: try-catch patterns, specific error handling, timeouts - multiple-sessions: manage independent conversations simultaneously - managing-local-files: organize files by metadata with AI - pr-visualization: interactive PR age chart CLI tool Each recipe includes: - Markdown documentation with code examples - File-based app runnable example (.cs) - PublishAot=false directive for compatibility * Cookbook(Go): add 4 recipes with docs and runnable examples Recipes: - error-handling: defer cleanup, error wrapping, timeouts with context - multiple-sessions: concurrent session management - managing-local-files: organize files by metadata with AI - pr-visualization: interactive PR age chart CLI tool with flag parsing Each recipe includes: - Markdown documentation with Go idiomatic code - Standalone runnable example (.go) - Proper error handling with defer patterns - CLI flag support where applicable * Cookbook(Node.js): add 4 recipes with docs and runnable examples Recipes: - error-handling: try-catch async patterns, error types - multiple-sessions: concurrent session management - managing-local-files: organize files by metadata with AI - pr-visualization: interactive PR age chart CLI tool Each recipe includes: - Markdown documentation with TypeScript code - Standalone runnable example (.ts) - package.json with local SDK reference (file:../../..) - npm scripts for easy execution - ESM with top-level await support * Cookbook(Python): add 4 recipes with docs and runnable examples Recipes: - error_handling: exception handling, context managers - multiple_sessions: concurrent session management - managing_local_files: organize files by metadata with AI - pr_visualization: interactive PR age chart CLI tool Each recipe includes: - Markdown documentation with Python examples - Standalone runnable example (.py) - requirements.txt with local SDK (editable install) - Shebang for direct execution - PEP 8 naming conventions (snake_case) * Cookbook: add persisting sessions links * Node: add persisting sessions recipe * Dotnet: add persisting sessions recipe * Go: add persisting sessions recipe * Python: add persisting sessions recipe * Fixing some copilot sloppiness * Formatting
1 parent 0aebae6 commit f26e999

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

52 files changed

+5381
-0
lines changed

‎cookbook/README.md‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
# GitHub Copilot SDK Cookbook
2+
3+
This cookbook collects small, focused recipes showing how to accomplish common tasks with the GitHub Copilot SDK across languages. Each recipe is intentionally short and practical, with copy‑pasteable snippets and pointers to fuller examples and tests.
4+
5+
## Recipes by Language
6+
7+
### .NET (C#)
8+
9+
- [Error Handling](dotnet/cookbook/error-handling.md): Handle errors gracefully including connection failures, timeouts, and cleanup.
10+
- [Multiple Sessions](dotnet/cookbook/multiple-sessions.md): Manage multiple independent conversations simultaneously.
11+
- [Managing Local Files](dotnet/cookbook/managing-local-files.md): Organize files by metadata using AI-powered grouping strategies.
12+
- [PR Visualization](dotnet/cookbook/pr-visualization.md): Generate interactive PR age charts using GitHub MCP Server.
13+
- [Persisting Sessions](dotnet/cookbook/persisting-sessions.md): Save and resume sessions across restarts.
14+
15+
### Node.js / TypeScript
16+
17+
- [Error Handling](nodejs/cookbook/error-handling.md): Handle errors gracefully including connection failures, timeouts, and cleanup.
18+
- [Multiple Sessions](nodejs/cookbook/multiple-sessions.md): Manage multiple independent conversations simultaneously.
19+
- [Managing Local Files](nodejs/cookbook/managing-local-files.md): Organize files by metadata using AI-powered grouping strategies.
20+
- [PR Visualization](nodejs/cookbook/pr-visialisation.md): Generate interactive PR age charts using GitHub MCP Server.
21+
- [Persisting Sessions](nodejs/cookbook/persisting-sessions.md): Save and resume sessions across restarts.
22+
23+
### Python
24+
25+
- [Error Handling](python/cookbook/error-handling.md): Handle errors gracefully including connection failures, timeouts, and cleanup.
26+
- [Multiple Sessions](python/cookbook/multiple-sessions.md): Manage multiple independent conversations simultaneously.
27+
- [Managing Local Files](python/cookbook/managing-local-files.md): Organize files by metadata using AI-powered grouping strategies.
28+
- [PR Visualization](python/cookbook/pr-visualization.md): Generate interactive PR age charts using GitHub MCP Server.
29+
- [Persisting Sessions](python/cookbook/persisting-sessions.md): Save and resume sessions across restarts.
30+
31+
### Go
32+
33+
- [Error Handling](go/cookbook/error-handling.md): Handle errors gracefully including connection failures, timeouts, and cleanup.
34+
- [Multiple Sessions](go/cookbook/multiple-sessions.md): Manage multiple independent conversations simultaneously.
35+
- [Managing Local Files](go/cookbook/managing-local-files.md): Organize files by metadata using AI-powered grouping strategies.
36+
- [PR Visualization](go/cookbook/pr-visualization.md): Generate interactive PR age charts using GitHub MCP Server.
37+
- [Persisting Sessions](go/cookbook/persisting-sessions.md): Save and resume sessions across restarts.
38+
39+
## How to Use
40+
41+
- Browse your language section above and open the recipe links
42+
- Each recipe includes runnable examples in a `recipe/` subfolder with language-specific tooling
43+
- See existing examples and tests for working references:
44+
- Node.js examples: `nodejs/examples/basic-example.ts`
45+
- E2E tests: `go/e2e`, `python/e2e`, `nodejs/test/e2e`, `dotnet/test/Harness`
46+
47+
## Running Examples
48+
49+
### .NET
50+
51+
```bash
52+
cd dotnet/cookbook/recipe
53+
dotnet run <filename>.cs
54+
```
55+
56+
### Node.js
57+
58+
```bash
59+
cd nodejs/cookbook/recipe
60+
npm install
61+
npx tsx <filename>.ts
62+
```
63+
64+
### Python
65+
66+
```bash
67+
cd python/cookbook/recipe
68+
pip install -r requirements.txt
69+
python <filename>.py
70+
```
71+
72+
### Go
73+
74+
```bash
75+
cd go/cookbook/recipe
76+
go run <filename>.go
77+
```
78+
79+
## Contributing
80+
81+
- Propose or add a new recipe by creating a markdown file in your language's `cookbook/` folder and a runnable example in `recipe/`
82+
- Follow repository guidance in [CONTRIBUTING.md](CONTRIBUTING.md)
83+
84+
## Status
85+
86+
Cookbook structure is complete with 4 recipes across all 4 supported languages. Each recipe includes both markdown documentation and runnable examples.

‎dotnet/cookbook/README.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# GitHub Copilot SDK Cookbook — .NET (C#)
2+
3+
This folder hosts short, practical recipes for using the GitHub Copilot SDK with .NET. Each recipe is concise, copy‑pasteable, and points to fuller examples and tests.
4+
5+
## Recipes
6+
7+
- [Error Handling](error-handling.md): Handle errors gracefully including connection failures, timeouts, and cleanup.
8+
- [Multiple Sessions](multiple-sessions.md): Manage multiple independent conversations simultaneously.
9+
- [Managing Local Files](managing-local-files.md): Organize files by metadata using AI-powered grouping strategies.
10+
- [PR Visualization](pr-visualization.md): Generate interactive PR age charts using GitHub MCP Server.
11+
- [Persisting Sessions](persisting-sessions.md): Save and resume sessions across restarts.
12+
13+
## Contributing
14+
15+
Add a new recipe by creating a markdown file in this folder and linking it above. Follow repository guidance in [CONTRIBUTING.md](../../CONTRIBUTING.md).
16+
17+
## Status
18+
19+
This README is a scaffold; recipe files are placeholders until populated.

‎dotnet/cookbook/error-handling.md‎

Lines changed: 156 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
1+
# Error Handling Patterns
2+
3+
Handle errors gracefully in your Copilot SDK applications.
4+
5+
> **Runnable example:** [recipe/error-handling.cs](recipe/error-handling.cs)
6+
>
7+
> ```bash
8+
> dotnet run recipe/error-handling.cs
9+
> ```
10+
11+
## Example scenario
12+
13+
You need to handle various error conditions like connection failures, timeouts, and invalid responses.
14+
15+
## Basic try-catch
16+
17+
```csharp
18+
using GitHub.Copilot.SDK;
19+
20+
var client = new CopilotClient();
21+
22+
try
23+
{
24+
await client.StartAsync();
25+
var session = await client.CreateSessionAsync(new SessionConfig
26+
{
27+
Model = "gpt-5"
28+
});
29+
30+
var done = new TaskCompletionSource<string>();
31+
session.On(evt =>
32+
{
33+
if (evt is AssistantMessageEvent msg)
34+
{
35+
done.SetResult(msg.Data.Content);
36+
}
37+
});
38+
39+
await session.SendAsync(new MessageOptions { Prompt = "Hello!" });
40+
var response = await done.Task;
41+
Console.WriteLine(response);
42+
43+
await session.DisposeAsync();
44+
}
45+
catch (Exception ex)
46+
{
47+
Console.WriteLine($"Error: {ex.Message}");
48+
}
49+
finally
50+
{
51+
await client.StopAsync();
52+
}
53+
```
54+
55+
## Handling specific error types
56+
57+
```csharp
58+
try
59+
{
60+
await client.StartAsync();
61+
}
62+
catch (FileNotFoundException)
63+
{
64+
Console.WriteLine("Copilot CLI not found. Please install it first.");
65+
}
66+
catch (HttpRequestException ex) when (ex.Message.Contains("connection"))
67+
{
68+
Console.WriteLine("Could not connect to Copilot CLI server.");
69+
}
70+
catch (Exception ex)
71+
{
72+
Console.WriteLine($"Unexpected error: {ex.Message}");
73+
}
74+
```
75+
76+
## Timeout handling
77+
78+
```csharp
79+
var session = await client.CreateSessionAsync(new SessionConfig { Model = "gpt-5" });
80+
81+
try
82+
{
83+
var done = new TaskCompletionSource<string>();
84+
session.On(evt =>
85+
{
86+
if (evt is AssistantMessageEvent msg)
87+
{
88+
done.SetResult(msg.Data.Content);
89+
}
90+
});
91+
92+
await session.SendAsync(new MessageOptions { Prompt = "Complex question..." });
93+
94+
// Wait with timeout (30 seconds)
95+
using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(30));
96+
var response = await done.Task.WaitAsync(cts.Token);
97+
98+
Console.WriteLine(response);
99+
}
100+
catch (OperationCanceledException)
101+
{
102+
Console.WriteLine("Request timed out");
103+
}
104+
```
105+
106+
## Aborting a request
107+
108+
```csharp
109+
var session = await client.CreateSessionAsync(new SessionConfig { Model = "gpt-5" });
110+
111+
// Start a request
112+
await session.SendAsync(new MessageOptions { Prompt = "Write a very long story..." });
113+
114+
// Abort it after some condition
115+
await Task.Delay(5000);
116+
await session.AbortAsync();
117+
Console.WriteLine("Request aborted");
118+
```
119+
120+
## Graceful shutdown
121+
122+
```csharp
123+
Console.CancelKeyPress += async (sender, e) =>
124+
{
125+
e.Cancel = true;
126+
Console.WriteLine("Shutting down...");
127+
128+
var errors = await client.StopAsync();
129+
if (errors.Count > 0)
130+
{
131+
Console.WriteLine($"Cleanup errors: {string.Join(", ", errors)}");
132+
}
133+
134+
Environment.Exit(0);
135+
};
136+
```
137+
138+
## Using await using for automatic disposal
139+
140+
```csharp
141+
await using var client = new CopilotClient();
142+
await client.StartAsync();
143+
144+
var session = await client.CreateSessionAsync(new SessionConfig { Model = "gpt-5" });
145+
146+
// ... do work ...
147+
148+
// client.StopAsync() is automatically called when exiting scope
149+
```
150+
151+
## Best practices
152+
153+
1. **Always clean up**: Use try-finally or `await using` to ensure `StopAsync()` is called
154+
2. **Handle connection errors**: The CLI might not be installed or running
155+
3. **Set appropriate timeouts**: Use `CancellationToken` for long-running requests
156+
4. **Log errors**: Capture error details for debugging

0 commit comments

Comments
 (0)