diff --git a/docs/guides/README.MD b/docs/README.md similarity index 62% rename from docs/guides/README.MD rename to docs/README.md index bcea8353d..7fa30b208 100644 --- a/docs/guides/README.MD +++ b/docs/README.md @@ -1,22 +1,34 @@ # 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. + +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. ## Prerequisites -### 1. Install .NET 10 Preview +### 1. Install .NET 10 +#### Option A: Using package manager - Recommended -#### Option A: Using Windows Package Manager (winget) - Recommended -```powershell -# Install .NET 10 SDK Preview -winget install Microsoft.DotNet.SDK.Preview -``` +- Windows + + ```powershell + # Install .NET 10 SDK Preview + winget install Microsoft.DotNet.SDK.Preview + ``` + +- Mac OS + + ```bash + # Install .NET 10 SDK Preview + brew tap isen-ng/dotnet-sdk-versions + brew install --cask dotnet-sdk10-preview + ``` + +#### Option B: Manual download -#### 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`) +1. Download and install: **.NET SDK 10.0 Preview** (required for development and `dotnet run`) -### 2. Verify Installation +### 2. Verify installation After installation, verify you have the correct versions: @@ -24,36 +36,46 @@ After installation, verify you have the correct versions: # Check installed SDKs dotnet --list-sdks -# Check version from the guides directory (should show 10.x) -cd docs/guides +# Check version from the docs directory (should show 10.x) +cd docs dotnet --version ``` You should see output similar to: -``` -10.0.100-preview.5.25277.114 + +```text +10.0.100-rc.1.25451.107 ``` ## Setup -### 1. Clone the Repository +### 1. Clone the repository + ```powershell git clone https://github.com/openai/openai-dotnet.git cd openai-dotnet ``` -### 2. Set Your OpenAI API Key +### 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) +#### Temporary (Current session only) + +```bash +# bash/zsh +export OPENAI_API_KEY="your-api-key-here" +``` + ```powershell +# PowerShell $env:OPENAI_API_KEY = "your-api-key-here" ``` -#### Permanent Options +#### 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" @@ -61,72 +83,101 @@ $env:OPENAI_API_KEY = "your-api-key-here" 5. Variable value: Your API key **Option B: Using PowerShell (Permanent)** + ```powershell [Environment]::SetEnvironmentVariable("OPENAI_API_KEY", "your-api-key-here", "User") ``` **Option C: Using Command Prompt as Administrator** + ```cmd setx OPENAI_API_KEY "your-api-key-here" ``` -### 3. Verify Environment Variable +**Option D: Using bash/zsh** + +```bash +# bash +echo 'export OPENAI_API_KEY=\"your-api-key-here\"' >> ~/.bashrc +source ~/.bashrc +``` + +```bash +# zsh +echo 'export OPENAI_API_KEY=\"your-api-key-here\"' >> ~/.zshrc +source ~/.zshrc +``` + +### 3. Verify environment variable + +```bash +# bash/zsh +echo $OPENAI_API_KEY +``` + ```powershell +# PowerShell echo $env:OPENAI_API_KEY ``` -## Running the Samples +## Running the samples 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 +### 1. Navigate to the docs directory + ```powershell -cd docs/guides +cd docs ``` -### Run a Sample +### 2. Run a sample + ```powershell # Example: Run the simple chat prompt sample -dotnet run text/chat/chat_simpleprompt.cs +dotnet run quickstart/responses/developer_quickstart.cs # Run other samples -dotnet run text/chat/chat_instructions.cs -dotnet run text/chat/chat_roles.cs +dotnet run guides/text/responses/responses_simpleprompt.cs +dotnet run guides/text/responses/responses_roles.cs ``` -### Expected Output -When you run `chat_simpleprompt.cs`, you should see output similar to: -``` +### 3. Expected output + +When you run `developer_quickstart.cs`, you should see output similar to: + +```text 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 +## Sample file structure The samples are organized as follows: -``` + +```text docs/ +├── global.json # Specifies .NET 10 preview SDK +├── README.MD # Basic usage instructions ├── 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 +│ └── ... # Chat handling samples │ └── responses/ -│ └── ... # Response handling samples +│ └── ... # Response handling samples +├── quickstart/ +│ └── responses/ +│ └── ... # Response handling samples ``` -## Understanding the Single-File Format +## 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 +#:package OpenAI@2.* // NuGet package reference +#:property PublishAot=false // Build properties -using OpenAI.Chat; // Regular C# code follows +using OpenAI.Responses; // Regular C# code follows // Your application code here... ``` @@ -134,37 +185,44 @@ using OpenAI.Chat; // Regular C# code follows ## 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**: + +- **Solution**: - Verify your `OPENAI_API_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 +## 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) +- [.NET 10 Preview Documentation](https://docs.microsoft.com/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 +## Next steps Once you have the basic samples working, you can: diff --git a/docs/guides/global.json b/docs/guides/global.json deleted file mode 100644 index 6d1a5f4a6..000000000 --- a/docs/guides/global.json +++ /dev/null @@ -1,5 +0,0 @@ -{ - "sdk": { - "version": "10.*-rc*" - } -} \ No newline at end of file