openai/openai-dotnet
Publicmirrored from https://github.com/openai/openai-dotnetAvailable
docs/README.md
234lines · modecode
| 1 | # OpenAI with .NET 10 - Getting Started Guide |
| 2 | |
| 3 | 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 features. |
| 4 | |
| 5 | ## Prerequisites |
| 6 | |
| 7 | ### 1. Install .NET 10 |
| 8 | |
| 9 | #### Option A: Using package manager - Recommended |
| 10 | |
| 11 | - Windows |
| 12 | |
| 13 | ```powershell |
| 14 | # Install .NET 10 SDK Preview |
| 15 | winget install Microsoft.DotNet.SDK.Preview |
| 16 | ``` |
| 17 | |
| 18 | - Mac OS |
| 19 | |
| 20 | ```bash |
| 21 | # Install .NET 10 SDK Preview |
| 22 | brew tap isen-ng/dotnet-sdk-versions |
| 23 | brew install --cask dotnet-sdk10-preview |
| 24 | ``` |
| 25 | |
| 26 | #### Option B: Manual download |
| 27 | |
| 28 | 1. Visit the [.NET 10 Download Page](https://dotnet.microsoft.com/download/dotnet/10.0) |
| 29 | 1. Download and install: **.NET SDK 10.0 Preview** (required for development and `dotnet run`) |
| 30 | |
| 31 | ### 2. Verify installation |
| 32 | |
| 33 | After installation, verify you have the correct versions: |
| 34 | |
| 35 | ```powershell |
| 36 | # Check installed SDKs |
| 37 | dotnet --list-sdks |
| 38 | |
| 39 | # Check version from the docs directory (should show 10.x) |
| 40 | cd docs |
| 41 | dotnet --version |
| 42 | ``` |
| 43 | |
| 44 | You should see output similar to: |
| 45 | |
| 46 | ```text |
| 47 | 10.0.100-rc.1.25451.107 |
| 48 | ``` |
| 49 | |
| 50 | ## Setup |
| 51 | |
| 52 | ### 1. Clone the repository |
| 53 | |
| 54 | ```powershell |
| 55 | git clone https://github.com/openai/openai-dotnet.git |
| 56 | cd openai-dotnet |
| 57 | ``` |
| 58 | |
| 59 | ### 2. Set your OpenAI API key |
| 60 | |
| 61 | You need an OpenAI API key to run the samples. Get one from [OpenAI's API platform](https://platform.openai.com/api-keys). |
| 62 | |
| 63 | #### Temporary (Current session only) |
| 64 | |
| 65 | ```bash |
| 66 | # bash/zsh |
| 67 | export OPENAI_API_KEY="your-api-key-here" |
| 68 | ``` |
| 69 | |
| 70 | ```powershell |
| 71 | # PowerShell |
| 72 | $env:OPENAI_API_KEY = "your-api-key-here" |
| 73 | ``` |
| 74 | |
| 75 | #### Permanent options |
| 76 | |
| 77 | **Option A: Using System Properties (GUI)** |
| 78 | |
| 79 | 1. Press `Win + R`, type `sysdm.cpl`, press Enter |
| 80 | 2. Click "Environment Variables" |
| 81 | 3. Under "User variables", click "New" |
| 82 | 4. Variable name: `OPENAI_API_KEY` |
| 83 | 5. Variable value: Your API key |
| 84 | |
| 85 | **Option B: Using PowerShell (Permanent)** |
| 86 | |
| 87 | ```powershell |
| 88 | [Environment]::SetEnvironmentVariable("OPENAI_API_KEY", "your-api-key-here", "User") |
| 89 | ``` |
| 90 | |
| 91 | **Option C: Using Command Prompt as Administrator** |
| 92 | |
| 93 | ```cmd |
| 94 | setx OPENAI_API_KEY "your-api-key-here" |
| 95 | ``` |
| 96 | |
| 97 | **Option D: Using bash/zsh** |
| 98 | |
| 99 | ```bash |
| 100 | # bash |
| 101 | echo 'export OPENAI_API_KEY=\"your-api-key-here\"' >> ~/.bashrc |
| 102 | source ~/.bashrc |
| 103 | ``` |
| 104 | |
| 105 | ```bash |
| 106 | # zsh |
| 107 | echo 'export OPENAI_API_KEY=\"your-api-key-here\"' >> ~/.zshrc |
| 108 | source ~/.zshrc |
| 109 | ``` |
| 110 | |
| 111 | ### 3. Verify environment variable |
| 112 | |
| 113 | ```bash |
| 114 | # bash/zsh |
| 115 | echo $OPENAI_API_KEY |
| 116 | ``` |
| 117 | |
| 118 | ```powershell |
| 119 | # PowerShell |
| 120 | echo $env:OPENAI_API_KEY |
| 121 | ``` |
| 122 | |
| 123 | ## Running the samples |
| 124 | |
| 125 | The samples use .NET 10's new single-file application feature. Each `.cs` file in the guides folder is a standalone application. |
| 126 | |
| 127 | ### 1. Navigate to the docs directory |
| 128 | |
| 129 | ```powershell |
| 130 | cd docs |
| 131 | ``` |
| 132 | |
| 133 | ### 2. Run a sample |
| 134 | |
| 135 | ```powershell |
| 136 | # Example: Run the simple chat prompt sample |
| 137 | dotnet run quickstart/responses/developer_quickstart.cs |
| 138 | |
| 139 | # Run other samples |
| 140 | dotnet run guides/text/responses/responses_simpleprompt.cs |
| 141 | dotnet run guides/text/responses/responses_roles.cs |
| 142 | ``` |
| 143 | |
| 144 | ### 3. Expected output |
| 145 | |
| 146 | When you run `developer_quickstart.cs`, you should see output similar to: |
| 147 | |
| 148 | ```text |
| 149 | Under a velvet-purple sky, a gentle unicorn named Luna sprinkled stardust over the dreaming forest, filling every heart with peaceful, magical dreams. |
| 150 | ``` |
| 151 | |
| 152 | ## Sample file structure |
| 153 | |
| 154 | The samples are organized as follows: |
| 155 | |
| 156 | ```text |
| 157 | docs/ |
| 158 | ├── global.json # Specifies .NET 10 preview SDK |
| 159 | ├── README.MD # Basic usage instructions |
| 160 | ├── guides/ |
| 161 | │ └── text/ |
| 162 | │ ├── chat/ |
| 163 | │ └── ... # Chat handling samples |
| 164 | │ └── responses/ |
| 165 | │ └── ... # Response handling samples |
| 166 | ├── quickstart/ |
| 167 | │ └── responses/ |
| 168 | │ └── ... # Response handling samples |
| 169 | ``` |
| 170 | |
| 171 | ## Understanding the single-file format |
| 172 | |
| 173 | Each sample file contains special directives at the top: |
| 174 | |
| 175 | ```csharp |
| 176 | // SAMPLE: Description of what this sample does |
| 177 | #:package OpenAI@2.* // NuGet package reference |
| 178 | #:property PublishAot=false // Build properties |
| 179 | |
| 180 | using OpenAI.Responses; // Regular C# code follows |
| 181 | |
| 182 | // Your application code here... |
| 183 | ``` |
| 184 | |
| 185 | ## Troubleshooting |
| 186 | |
| 187 | ### Problem: "No package found matching input criteria" |
| 188 | |
| 189 | - **Solution**: The .NET 10 preview packages might not be available yet. Try installing from the official Microsoft download page instead. |
| 190 | |
| 191 | ### Problem: `dotnet --version` shows 9.x instead of 10.x |
| 192 | |
| 193 | - **Solution**: You need to install the .NET 10 **SDK** (not just the runtime). The `global.json` file in the guides directory requires the SDK. |
| 194 | |
| 195 | ### Problem: "Couldn't find a project to run" |
| 196 | |
| 197 | - **Solution**: Make sure you're running the command from the `docs/guides` directory and providing the correct path to the `.cs` file. |
| 198 | |
| 199 | ### Problem: "The property directive needs to have two parts" |
| 200 | |
| 201 | - **Solution**: The property directive format should be `#:property PropertyName PropertyValue` (space-separated, not equals sign). |
| 202 | |
| 203 | ### Problem: API errors |
| 204 | |
| 205 | - **Solution**: |
| 206 | - Verify your `OPENAI_API_KEY` environment variable is set correctly |
| 207 | - Check that your API key is valid and has sufficient credits |
| 208 | - Ensure you're using a valid model name (e.g., "gpt-4", "gpt-3.5-turbo") |
| 209 | |
| 210 | ### Problem: Build errors about missing packages |
| 211 | |
| 212 | - **Solution**: The package directives should automatically download dependencies. If not, try: |
| 213 | |
| 214 | ```powershell |
| 215 | dotnet restore |
| 216 | ``` |
| 217 | |
| 218 | ## Additional resources |
| 219 | |
| 220 | - [OpenAI .NET SDK Documentation](https://github.com/openai/openai-dotnet) |
| 221 | - [.NET 10 Preview Documentation](https://docs.microsoft.com/dotnet/core/whats-new/dotnet-10) |
| 222 | - [OpenAI API Documentation](https://platform.openai.com/docs) |
| 223 | - [Single-File Applications in .NET 10](https://devblogs.microsoft.com/dotnet/announcing-dotnet-run-app/) |
| 224 | |
| 225 | ## Next steps |
| 226 | |
| 227 | Once you have the basic samples working, you can: |
| 228 | |
| 229 | 1. **Explore other samples** in the `text/` directory |
| 230 | 2. **Modify the prompts** in the sample files to experiment with different outputs |
| 231 | 3. **Create your own samples** following the same single-file format |
| 232 | 4. **Integrate the OpenAI SDK** into your own .NET applications |
| 233 | |
| 234 | Happy coding with OpenAI and .NET 10! 🚀 |
| 235 | |