Fix .NET 10 property directive format in sample files (#497)

achandmsft · Arun Sekhar · web-flow · commit b8d4d6dfc34d · 2025-06-27T10:18:51.000-07:00
* 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 * 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 * 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 --------- Co-authored-by: Arun Sekhar <achand@microsoft.com>
diff --git a/docs/guides/README.MD b/docs/guides/README.MD
@@ -1,10 +1,176 @@
-# OpenAI Documentation Examples for .NET
+# 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
+
+
+#### 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 <sample_name>` 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
@@ -1,6 +1,7 @@
 // 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
+#:property PublishAot false
 
 using OpenAI.Chat; 
 
diff --git a/docs/guides/text/chat/chat_roles.cs b/docs/guides/text/chat/chat_roles.cs
@@ -1,6 +1,7 @@
 // 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
+#:property PublishAot false
 
 using OpenAI.Chat; 
 
diff --git a/docs/guides/text/chat/chat_simpleprompt.cs b/docs/guides/text/chat/chat_simpleprompt.cs
@@ -1,6 +1,7 @@
 // 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
+#:property PublishAot false
 
 using OpenAI.Chat; 
 
diff --git a/docs/guides/text/responses/responses_fileinput.cs b/docs/guides/text/responses/responses_fileinput.cs
@@ -1,6 +1,7 @@
 // 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
+#: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
@@ -1,6 +1,7 @@
 // SAMPLE: Generate text with instructions
+// GUIDANCE: Instructions to run this code: https://aka.ms/oai/net/start 
 #: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
@@ -1,6 +1,7 @@
 // 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
+#: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
@@ -1,6 +1,7 @@
 // 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
+#:property PublishAot false
 
 using OpenAI.Responses; 
 
diff --git a/docs/guides/text/responses/responses_simpleprompt.cs b/docs/guides/text/responses/responses_simpleprompt.cs
@@ -1,6 +1,7 @@
 // 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
+#:property PublishAot false
 
 using OpenAI.Responses; 
 
