From 39ba8875cc72d5807fa7ce884d771c19ffc659b5 Mon Sep 17 00:00:00 2001 From: Arun Sekhar Date: Thu, 26 Jun 2025 19:44:46 -0700 Subject: [PATCH 1/3] Fix .NET 10 property directive format in sample files - Updated property directive format from 'PropertyName=Value' to 'PropertyName Value' - Fixed all sample .cs files in docs/guides to work with .NET 10 preview - Added comprehensive getting started documentation in docs/README.md - Enables successful execution of single-file C# applications with dotnet run --- docs/guides/README.MD | 176 +++++++++++++++++- docs/guides/text/chat/chat_instructions.cs | 2 +- docs/guides/text/chat/chat_roles.cs | 2 +- docs/guides/text/chat/chat_simpleprompt.cs | 2 +- .../text/responses/responses_fileinput.cs | 2 +- .../text/responses/responses_instructions.cs | 2 +- .../responses/responses_prompttemplate.cs | 2 +- docs/guides/text/responses/responses_roles.cs | 2 +- .../text/responses/responses_simpleprompt.cs | 2 +- 9 files changed, 180 insertions(+), 12 deletions(-) diff --git a/docs/guides/README.MD b/docs/guides/README.MD index 8dd091395..399a7c222 100644 --- a/docs/guides/README.MD +++ b/docs/guides/README.MD @@ -1,10 +1,178 @@ -# OpenAI Documentation Examples for .NET +# OpenAI .NET SDK - Getting Started Guide + +This guide will help you run the OpenAI .NET SDK based code samples (.cs files) in this folder directly without a project using the latest .NET 10 preview features. + +## Prerequisites + +### 1. Install .NET 10 Preview + +You need both the .NET 10 runtime and SDK to run these samples. + +#### Option A: Using Windows Package Manager (winget) - Recommended +```powershell +# Install .NET 10 SDK Preview +winget install Microsoft.DotNet.SDK.Preview +``` + +#### Option B: Manual Download +1. Visit the [.NET 10 Download Page](https://dotnet.microsoft.com/download/dotnet/10.0) +2. Download and install: **.NET SDK 10.0 Preview** (required for development and `dotnet run`) + +### 2. Verify Installation + +After installation, verify you have the correct versions: + +```powershell +# Check installed SDKs +dotnet --list-sdks + +# Check version from the guides directory (should show 10.x) +cd docs/guides +dotnet --version +``` + +You should see output similar to: +``` +10.0.100-preview.5.25277.114 +``` + +## Setup + +### 1. Clone the Repository +```powershell +git clone https://github.com/openai/openai-dotnet.git +cd openai-dotnet +``` + +### 2. Set Your OpenAI API Key + +You need an OpenAI API key to run the samples. Get one from [OpenAI's API platform](https://platform.openai.com/api-keys). + +#### Temporary (Current Session Only) +```powershell +$env:OPENAI_KEY = "your-api-key-here" +``` + +#### Permanent Options + +**Option A: Using System Properties (GUI)** +1. Press `Win + R`, type `sysdm.cpl`, press Enter +2. Click "Environment Variables" +3. Under "User variables", click "New" +4. Variable name: `OPENAI_KEY` +5. Variable value: Your API key + +**Option B: Using PowerShell (Permanent)** +```powershell +[Environment]::SetEnvironmentVariable("OPENAI_KEY", "your-api-key-here", "User") +``` + +**Option C: Using Command Prompt as Administrator** +```cmd +setx OPENAI_KEY "your-api-key-here" +``` + +### 3. Verify Environment Variable +```powershell +echo $env:OPENAI_KEY +``` ## Running the Samples -The samples use a new .NET 10 feature that allows [running single C# file applications](https://devblogs.microsoft.com/dotnet/announcing-dotnet-run-app/). Each file in this folder is a standalone application. +The samples use .NET 10's new single-file application feature. Each `.cs` file in the guides folder is a standalone application. + +### Navigate to the Guides Directory +```powershell +cd docs/guides +``` + +### Run a Sample +```powershell +# Example: Run the simple chat prompt sample +dotnet run text/chat/chat_simpleprompt.cs + +# Run other samples +dotnet run text/chat/chat_instructions.cs +dotnet run text/chat/chat_roles.cs +``` + +### Expected Output +When you run `chat_simpleprompt.cs`, you should see output similar to: +``` +Under a velvet-purple sky, a gentle unicorn named Luna sprinkled stardust over the dreaming forest, filling every heart with peaceful, magical dreams. +``` + +## Sample File Structure + +The samples are organized as follows: +``` +docs/ +├── guides/ +│ ├── global.json # Specifies .NET 10 preview SDK +│ ├── README.MD # Basic usage instructions +│ └── text/ +│ ├── chat/ +│ │ ├── chat_simpleprompt.cs # Basic chat completion +│ │ ├── chat_instructions.cs # Chat with system instructions +│ │ └── chat_roles.cs # Chat with different roles +│ └── responses/ +│ └── ... # Response handling samples +``` + +## Understanding the Single-File Format + +Each sample file contains special directives at the top: + +```csharp +// SAMPLE: Description of what this sample does +#:package OpenAI@2.2.*-* // NuGet package reference +#:property PublishAot false // Build properties + +using OpenAI.Chat; // Regular C# code follows + +// Your application code here... +``` + +## Troubleshooting + +### Problem: "No package found matching input criteria" +- **Solution**: The .NET 10 preview packages might not be available yet. Try installing from the official Microsoft download page instead. + +### Problem: `dotnet --version` shows 9.x instead of 10.x +- **Solution**: You need to install the .NET 10 **SDK** (not just the runtime). The `global.json` file in the guides directory requires the SDK. + +### Problem: "Couldn't find a project to run" +- **Solution**: Make sure you're running the command from the `docs/guides` directory and providing the correct path to the `.cs` file. + +### Problem: "The property directive needs to have two parts" +- **Solution**: The property directive format should be `#:property PropertyName PropertyValue` (space-separated, not equals sign). + +### Problem: API errors +- **Solution**: + - Verify your `OPENAI_KEY` environment variable is set correctly + - Check that your API key is valid and has sufficient credits + - Ensure you're using a valid model name (e.g., "gpt-4", "gpt-3.5-turbo") + +### Problem: Build errors about missing packages +- **Solution**: The package directives should automatically download dependencies. If not, try: + ```powershell + dotnet restore + ``` + +## Additional Resources + +- [OpenAI .NET SDK Documentation](https://github.com/openai/openai-dotnet) +- [.NET 10 Preview Documentation](https://docs.microsoft.com/en-us/dotnet/core/whats-new/dotnet-10) +- [OpenAI API Documentation](https://platform.openai.com/docs) +- [Single-File Applications in .NET 10](https://devblogs.microsoft.com/dotnet/announcing-dotnet-run-app/) + +## Next Steps -To run them, you need to install the .NET 10 preview. +Once you have the basic samples working, you can: -Then, from the command line, you can run them using the `dotnet run ` command, for example: `dotnet run s1-chat_simpleprompt.cs`. +1. **Explore other samples** in the `text/` directory +2. **Modify the prompts** in the sample files to experiment with different outputs +3. **Create your own samples** following the same single-file format +4. **Integrate the OpenAI SDK** into your own .NET applications +Happy coding with OpenAI and .NET 10! 🚀 diff --git a/docs/guides/text/chat/chat_instructions.cs b/docs/guides/text/chat/chat_instructions.cs index d6e5b1abf..faf549d5d 100644 --- a/docs/guides/text/chat/chat_instructions.cs +++ b/docs/guides/text/chat/chat_instructions.cs @@ -1,6 +1,6 @@ // SAMPLE: Generate text with messages using different roles #:package OpenAI@2.2.*-* -#:property PublishAot=false +#:property PublishAot false using OpenAI.Chat; diff --git a/docs/guides/text/chat/chat_roles.cs b/docs/guides/text/chat/chat_roles.cs index 39bb54097..8d2f32d95 100644 --- a/docs/guides/text/chat/chat_roles.cs +++ b/docs/guides/text/chat/chat_roles.cs @@ -1,6 +1,6 @@ // SAMPLE: Generate text with messages using different roles #:package OpenAI@2.2.*-* -#:property PublishAot=false +#:property PublishAot false using OpenAI.Chat; diff --git a/docs/guides/text/chat/chat_simpleprompt.cs b/docs/guides/text/chat/chat_simpleprompt.cs index 9f2eeb6e2..17b9808b9 100644 --- a/docs/guides/text/chat/chat_simpleprompt.cs +++ b/docs/guides/text/chat/chat_simpleprompt.cs @@ -1,6 +1,6 @@ // SAMPLE: Generate text from a simple prompt #:package OpenAI@2.2.*-* -#:property PublishAot=false +#:property PublishAot false using OpenAI.Chat; diff --git a/docs/guides/text/responses/responses_fileinput.cs b/docs/guides/text/responses/responses_fileinput.cs index 40eee1ce1..5aeed1740 100644 --- a/docs/guides/text/responses/responses_fileinput.cs +++ b/docs/guides/text/responses/responses_fileinput.cs @@ -1,6 +1,6 @@ // SAMPLE: Prompt template with file input variable #:package OpenAI@2.2.*-* -#:property PublishAot=false +#:property PublishAot false using OpenAI.Responses; using OpenAI.Files; diff --git a/docs/guides/text/responses/responses_instructions.cs b/docs/guides/text/responses/responses_instructions.cs index ef7b8212a..613a096c7 100644 --- a/docs/guides/text/responses/responses_instructions.cs +++ b/docs/guides/text/responses/responses_instructions.cs @@ -1,6 +1,6 @@ // SAMPLE: Generate text with instructions #:package OpenAI@2.2.*-* -#:property PublishAot=false +#:property PublishAot false using OpenAI.Responses; diff --git a/docs/guides/text/responses/responses_prompttemplate.cs b/docs/guides/text/responses/responses_prompttemplate.cs index bd7f7a65d..b671edd0b 100644 --- a/docs/guides/text/responses/responses_prompttemplate.cs +++ b/docs/guides/text/responses/responses_prompttemplate.cs @@ -1,6 +1,6 @@ // SAMPLE: Generate text with a prompt template #:package OpenAI@2.2.*-* -#:property PublishAot=false +#:property PublishAot false using OpenAI.Responses; using System.ClientModel; diff --git a/docs/guides/text/responses/responses_roles.cs b/docs/guides/text/responses/responses_roles.cs index 4e3a91669..41544748f 100644 --- a/docs/guides/text/responses/responses_roles.cs +++ b/docs/guides/text/responses/responses_roles.cs @@ -1,6 +1,6 @@ // SAMPLE: Generate text with messages using different roles #:package OpenAI@2.2.*-* -#:property PublishAot=false +#:property PublishAot false using OpenAI.Responses; diff --git a/docs/guides/text/responses/responses_simpleprompt.cs b/docs/guides/text/responses/responses_simpleprompt.cs index 2d115e1a3..a418fc343 100644 --- a/docs/guides/text/responses/responses_simpleprompt.cs +++ b/docs/guides/text/responses/responses_simpleprompt.cs @@ -1,6 +1,6 @@ // SAMPLE: Generate text from a simple prompt #:package OpenAI@2.2.*-* -#:property PublishAot=false +#:property PublishAot false using OpenAI.Responses; From 39596590b335c1b650b947175c4009ad76082fe3 Mon Sep 17 00:00:00 2001 From: Arun Sekhar Date: Thu, 26 Jun 2025 19:57:20 -0700 Subject: [PATCH 2/3] Update guides README.MD with simplified instructions - Streamlined the getting started guide for better clarity - Focused on essential steps for running .NET 10 samples - Improved readability and user experience --- docs/guides/README.MD | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/guides/README.MD b/docs/guides/README.MD index 399a7c222..c8df5dca7 100644 --- a/docs/guides/README.MD +++ b/docs/guides/README.MD @@ -1,12 +1,10 @@ -# OpenAI .NET SDK - Getting Started Guide - -This guide will help you run the OpenAI .NET SDK based code samples (.cs files) in this folder directly without a project using the latest .NET 10 preview features. +# OpenAI with .NET 10 - Getting Started Guide +This readme shows you how to run each OpenAI based sample (.cs) file in this folder directly without a project or additional setup using the latest .NET 10 Preview features. ## Prerequisites ### 1. Install .NET 10 Preview -You need both the .NET 10 runtime and SDK to run these samples. #### Option A: Using Windows Package Manager (winget) - Recommended ```powershell From 2241e32acc9bdca69e706c1d41e483c49812e036 Mon Sep 17 00:00:00 2001 From: Arun Sekhar Date: Thu, 26 Jun 2025 20:28:50 -0700 Subject: [PATCH 3/3] Add guidance comments to all sample files - Added '// GUIDANCE: Instructions to run this code: https://aka.ms/oai/net/start' to all .cs files - Provides users with quick access to getting started documentation - Consistent guidance across all sample files --- docs/guides/text/chat/chat_instructions.cs | 1 + docs/guides/text/chat/chat_roles.cs | 1 + docs/guides/text/chat/chat_simpleprompt.cs | 1 + docs/guides/text/responses/responses_fileinput.cs | 1 + docs/guides/text/responses/responses_instructions.cs | 1 + docs/guides/text/responses/responses_prompttemplate.cs | 1 + docs/guides/text/responses/responses_roles.cs | 1 + docs/guides/text/responses/responses_simpleprompt.cs | 1 + 8 files changed, 8 insertions(+) diff --git a/docs/guides/text/chat/chat_instructions.cs b/docs/guides/text/chat/chat_instructions.cs index faf549d5d..06ebf0414 100644 --- a/docs/guides/text/chat/chat_instructions.cs +++ b/docs/guides/text/chat/chat_instructions.cs @@ -1,4 +1,5 @@ // SAMPLE: Generate text with messages using different roles +// GUIDANCE: Instructions to run this code: https://aka.ms/oai/net/start #:package OpenAI@2.2.*-* #:property PublishAot false diff --git a/docs/guides/text/chat/chat_roles.cs b/docs/guides/text/chat/chat_roles.cs index 8d2f32d95..6fefbb95e 100644 --- a/docs/guides/text/chat/chat_roles.cs +++ b/docs/guides/text/chat/chat_roles.cs @@ -1,4 +1,5 @@ // SAMPLE: Generate text with messages using different roles +// GUIDANCE: Instructions to run this code: https://aka.ms/oai/net/start #:package OpenAI@2.2.*-* #:property PublishAot false diff --git a/docs/guides/text/chat/chat_simpleprompt.cs b/docs/guides/text/chat/chat_simpleprompt.cs index 17b9808b9..cf0556365 100644 --- a/docs/guides/text/chat/chat_simpleprompt.cs +++ b/docs/guides/text/chat/chat_simpleprompt.cs @@ -1,4 +1,5 @@ // SAMPLE: Generate text from a simple prompt +// GUIDANCE: Instructions to run this code: https://aka.ms/oai/net/start #:package OpenAI@2.2.*-* #:property PublishAot false diff --git a/docs/guides/text/responses/responses_fileinput.cs b/docs/guides/text/responses/responses_fileinput.cs index 5aeed1740..3d7b2c1a9 100644 --- a/docs/guides/text/responses/responses_fileinput.cs +++ b/docs/guides/text/responses/responses_fileinput.cs @@ -1,4 +1,5 @@ // SAMPLE: Prompt template with file input variable +// GUIDANCE: Instructions to run this code: https://aka.ms/oai/net/start #:package OpenAI@2.2.*-* #:property PublishAot false diff --git a/docs/guides/text/responses/responses_instructions.cs b/docs/guides/text/responses/responses_instructions.cs index 613a096c7..6b195ae8b 100644 --- a/docs/guides/text/responses/responses_instructions.cs +++ b/docs/guides/text/responses/responses_instructions.cs @@ -1,4 +1,5 @@ // SAMPLE: Generate text with instructions +// GUIDANCE: Instructions to run this code: https://aka.ms/oai/net/start #:package OpenAI@2.2.*-* #:property PublishAot false diff --git a/docs/guides/text/responses/responses_prompttemplate.cs b/docs/guides/text/responses/responses_prompttemplate.cs index b671edd0b..dc310f7d6 100644 --- a/docs/guides/text/responses/responses_prompttemplate.cs +++ b/docs/guides/text/responses/responses_prompttemplate.cs @@ -1,4 +1,5 @@ // SAMPLE: Generate text with a prompt template +// GUIDANCE: Instructions to run this code: https://aka.ms/oai/net/start #:package OpenAI@2.2.*-* #:property PublishAot false diff --git a/docs/guides/text/responses/responses_roles.cs b/docs/guides/text/responses/responses_roles.cs index 41544748f..2b9b4a7fb 100644 --- a/docs/guides/text/responses/responses_roles.cs +++ b/docs/guides/text/responses/responses_roles.cs @@ -1,4 +1,5 @@ // SAMPLE: Generate text with messages using different roles +// GUIDANCE: Instructions to run this code: https://aka.ms/oai/net/start #:package OpenAI@2.2.*-* #:property PublishAot false diff --git a/docs/guides/text/responses/responses_simpleprompt.cs b/docs/guides/text/responses/responses_simpleprompt.cs index a418fc343..9c5f4b270 100644 --- a/docs/guides/text/responses/responses_simpleprompt.cs +++ b/docs/guides/text/responses/responses_simpleprompt.cs @@ -1,4 +1,5 @@ // SAMPLE: Generate text from a simple prompt +// GUIDANCE: Instructions to run this code: https://aka.ms/oai/net/start #:package OpenAI@2.2.*-* #:property PublishAot false