Skip to content

Commit 4d89a9c

Browse files
samuel100samuel100
committed
added c# and rust references
1 parent 21df146 commit 4d89a9c

File tree

3 files changed

+468
-0
lines changed

3 files changed

+468
-0
lines changed

‎articles/ai-foundry/foundry-local/includes/sdk-reference/csharp.md

Lines changed: 279 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,279 @@
1+
---
2+
ms.service: azure-ai-foundry
3+
ms.topic: include
4+
ms.date: 06/09/2025
5+
ms.author: samkemp
6+
author: samuel100
7+
---
8+
9+
## C# SDK Reference
10+
11+
### Installation
12+
13+
To use the Foundry Local C# SDK, you need to install the NuGet package:
14+
15+
```bash
16+
dotnet add package Microsoft.AI.Foundry.Local
17+
```
18+
19+
### A note on aliases
20+
21+
Many methods outlined in this reference have an `aliasOrModelId` parameter in the signature. You can pass into the method either an **alias** or **model ID** as a value. Using an alias will:
22+
23+
- Select the *best model* for the available hardware. For example, if a Nvidia CUDA GPU is available, Foundry Local selects the CUDA model. If a supported NPU is available, Foundry Local selects the NPU model.
24+
- Allow you to use a shorter name without needing to remember the model ID.
25+
26+
> [!TIP]
27+
> We recommend passing into the `aliasOrModelId` parameter an **alias** because when you deploy your application, Foundry Local acquires the best model for the end user's machine at run-time.
28+
29+
### Enumerations
30+
31+
#### `DeviceType`
32+
33+
Represents the type of device used for model execution.
34+
35+
| Value | Description |
36+
|---------|--------------------|
37+
| CPU | CPU device |
38+
| GPU | GPU device |
39+
| NPU | NPU device |
40+
| Invalid | Invalid/unknown |
41+
42+
#### `ExecutionProvider`
43+
44+
Represents the execution provider for model inference.
45+
46+
| Value | Description |
47+
|------------------------|-----------------------------|
48+
| Invalid | Invalid provider |
49+
| CPUExecutionProvider | CPU execution |
50+
| WebGpuExecutionProvider| WebGPU execution |
51+
| CUDAExecutionProvider | CUDA GPU execution |
52+
| QNNExecutionProvider | Qualcomm NPU execution |
53+
54+
### `FoundryLocalManager` Class
55+
56+
The main entry point for managing models, cache, and the Foundry Local service.
57+
58+
#### Construction
59+
60+
```csharp
61+
var manager = new FoundryLocalManager();
62+
```
63+
64+
#### Properties
65+
66+
| Property | Type | Description |
67+
|------------------|-----------|------------------------------------------------------------------|
68+
| ServiceUri | `Uri` | The base URI of the Foundry Local service. |
69+
| Endpoint | `Uri` | The API endpoint (`ServiceUri` + `/v1`). |
70+
| ApiKey | `string` | The API key (default: `"OPENAI_API_KEY"`). |
71+
| IsServiceRunning | `bool` | Indicates if the service is running. |
72+
73+
74+
#### Service Management
75+
76+
##### Start the service
77+
78+
```csharp
79+
await manager.StartServiceAsync(CancellationToken.None);
80+
```
81+
Starts the Foundry Local service if not already running.
82+
83+
##### Stop the service
84+
85+
```csharp
86+
await manager.StopServiceAsync(CancellationToken.None);
87+
```
88+
Stops the Foundry Local service.
89+
90+
##### Start and load a model (static helper)
91+
92+
```csharp
93+
var manager = await FoundryLocalManager.StartModelAsync("aliasOrModelId");
94+
```
95+
96+
Starts the service and loads the specified model.
97+
98+
#### Catalog Management
99+
100+
##### List all catalog models
101+
102+
```csharp
103+
List<ModelInfo> models = await manager.ListCatalogModelsAsync();
104+
```
105+
Returns all available models in the catalog.
106+
107+
##### Refresh the catalog
108+
109+
```csharp
110+
manager.RefreshCatalog();
111+
```
112+
Clears the cached catalog so it will be reloaded on next access.
113+
114+
##### Get model info by alias or ID
115+
116+
```csharp
117+
ModelInfo? info = await manager.GetModelInfoAsync("aliasOrModelId");
118+
```
119+
Returns model info or `null` if not found.
120+
121+
#### Cache Management
122+
123+
##### Get cache location
124+
125+
```csharp
126+
string cachePath = await manager.GetCacheLocationAsync();
127+
```
128+
Returns the directory path where models are cached.
129+
130+
##### List cached models
131+
132+
```csharp
133+
List<ModelInfo> cached = await manager.ListCachedModelsAsync();
134+
```
135+
Returns models downloaded to the local cache.
136+
137+
#### Model Management
138+
139+
##### Download a model
140+
141+
```csharp
142+
ModelInfo? model = await manager.DownloadModelAsync("aliasOrModelId");
143+
```
144+
Downloads a model to the local cache.
145+
146+
##### Download a model with progress
147+
148+
```csharp
149+
await foreach (var progress in manager.DownloadModelWithProgressAsync("aliasOrModelId"))
150+
{
151+
// progress.Percentage, progress.Status, etc.
152+
}
153+
```
154+
Streams download progress updates.
155+
156+
##### Load a model
157+
158+
```csharp
159+
ModelInfo loaded = await manager.LoadModelAsync("aliasOrModelId");
160+
```
161+
Loads a model into the inference server.
162+
163+
##### List loaded models
164+
165+
```csharp
166+
List<ModelInfo> loaded = await manager.ListLoadedModelsAsync();
167+
```
168+
Lists all models currently loaded in the service.
169+
170+
##### Unload a model
171+
172+
```csharp
173+
await manager.UnloadModelAsync("aliasOrModelId");
174+
```
175+
Unloads a model from the inference server.
176+
177+
#### Disposal
178+
179+
Implements both `IDisposable` and `IAsyncDisposable` for proper cleanup.
180+
181+
```csharp
182+
manager.Dispose();
183+
// or
184+
await manager.DisposeAsync();
185+
```
186+
187+
### Model Types
188+
189+
This page documents the key data types used by the Foundry Local C# SDK for describing models, downloads, and runtime information.
190+
191+
192+
#### `PromptTemplate`
193+
194+
Represents the prompt template for a model.
195+
196+
| Property | Type | Description |
197+
|------------|---------|------------------------------------|
198+
| Assistant | string | The assistant's prompt template. |
199+
| Prompt | string | The user prompt template. |
200+
201+
#### `Runtime`
202+
203+
Describes the runtime environment for a model.
204+
205+
| Property | Type | Description |
206+
|-------------------|----------------|-----------------------------------|
207+
| DeviceType | `DeviceType` | The device type (CPU, GPU, etc). |
208+
| ExecutionProvider | `ExecutionProvider` | The execution provider (CUDA, CPU, etc). |
209+
210+
211+
#### `ModelSettings`
212+
213+
Represents model-specific parameters.
214+
215+
| Property | Type | Description |
216+
|------------|---------------------|----------------------------|
217+
| Parameters | List\<JsonElement\> | Model parameter collection |
218+
219+
### `ModelInfo`
220+
221+
Describes a model in the Foundry Local catalog or cache.
222+
223+
| Property | Type | Description |
224+
|----------------------|-----------------|-----------------------------------------------|
225+
| ModelId | string | Unique model identifier. |
226+
| DisplayName | string | Human-readable model name. |
227+
| ProviderType | string | Provider type (e.g., "CUDA", "CPU"). |
228+
| Uri | string | Download URI for the model. |
229+
| Version | string | Model version. |
230+
| ModelType | string | Model type (e.g., "llm", "embedding"). |
231+
| PromptTemplate | PromptTemplate | Prompt template for the model. |
232+
| Publisher | string | Publisher of the model. |
233+
| Task | string | Task type (e.g., "chat", "completion"). |
234+
| Runtime | Runtime | Runtime environment info. |
235+
| FileSizeMb | long | Model file size in MB. |
236+
| ModelSettings | ModelSettings | Model-specific settings. |
237+
| Alias | string | Alias for the model. |
238+
| SupportsToolCalling | bool | Whether tool-calling is supported. |
239+
| License | string | License identifier. |
240+
| LicenseDescription | string | License description. |
241+
| ParentModelUri | string | URI of the parent model, if any. |
242+
243+
244+
#### `ModelDownloadProgress`
245+
246+
Represents the progress of a model download operation.
247+
248+
| Property | Type | Description |
249+
|--------------|-------------|---------------------------------------------|
250+
| Percentage | double | Download completion percentage (0-100). |
251+
| IsCompleted | bool | Whether the download is complete. |
252+
| ModelInfo | ModelInfo? | Model info if download completed. |
253+
| ErrorMessage | string? | Error message if download failed. |
254+
255+
**Static methods:**
256+
- `Progress(double percentage)`: Create a progress update.
257+
- `Completed(ModelInfo modelInfo)`: Create a completed progress result.
258+
- `Error(string errorMessage)`: Create an error result.
259+
260+
### Example Usage
261+
262+
```csharp
263+
using Microsoft.AI.Foundry.Local;
264+
265+
var manager = new FoundryLocalManager();
266+
await manager.StartServiceAsync();
267+
268+
var models = await manager.ListCatalogModelsAsync();
269+
var alias = "phi-3.5-mini";
270+
271+
await manager.DownloadModelAsync(alias);
272+
await manager.LoadModelAsync(alias);
273+
274+
var loaded = await manager.ListLoadedModelsAsync();
275+
276+
await manager.UnloadModelAsync(alias);
277+
278+
manager.Dispose();
279+
```

0 commit comments

Comments
 (0)