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