v4.0.0 mostly adds features. Most apps only need to update the package and replace model IDs that Google has retired. This page lists everything that can change how your code builds or runs.

For the full list of new features, see Release Notes v4.

All packages move to 4.0.0 together:

dotnet add package Google_GenerativeAI --version 4.0.0
dotnet add package Google_GenerativeAI.Microsoft --version 4.0.0   # if you use Microsoft.Extensions.AI
dotnet add package Google_GenerativeAI.Tools --version 4.0.0       # if you use MCP or function tools
dotnet add package Google_GenerativeAI.Live --version 4.0.0        # if you use the Live API
dotnet add package Google_GenerativeAI.Web --version 4.0.0
dotnet add package Google_GenerativeAI.Auth --version 4.0.0

net11.0 assets are built only when the .NET 11 SDK is installed on the build machine.

What to check:

• Microsoft.Extensions.AI: if your app references Microsoft.Extensions.AI or Microsoft.Extensions.AI.Abstractions directly, use the same major version the SDK uses for your target framework: 10.x on net8/net9, 11.x on net10+. Mixed MEAI versions cause MissingMethodException at runtime.
• MCP: ModelContextProtocol went from a 0.4 preview to 2.x. McpTool and McpTransportFactory work as before. If you use types from the MCP SDK directly, such as McpClient, IClientTransport or StdioClientTransportOptions, check the MCP SDK's own breaking changes. McpTransportFactory.CreateHttpTransport* now also has Uri overloads; the string overloads still work.

The protected virtual embedding methods gained a CancellationToken parameter. Code that calls them still compiles, because the parameter is optional. Overrides must be updated:

// v3.x
protected override Task<EmbedContentResponse> EmbedContentAsync(string model, EmbedContentRequest request) { ... }
protected override Task<BatchEmbedContentsResponse> BatchEmbedContentAsync(string model, BatchEmbedContentRequest request) { ... }

// v4.0
protected override Task<EmbedContentResponse> EmbedContentAsync(string model, EmbedContentRequest request,
    CancellationToken cancellationToken = default) { ... }
protected override Task<BatchEmbedContentsResponse> BatchEmbedContentAsync(string model, BatchEmbedContentRequest request,
    CancellationToken cancellationToken = default) { ... }

Libraries compiled against v3.x that override or call these methods must be recompiled.

Gemini 3.x models reject the legacy function role with 400 INVALID_ARGUMENT. Like the official SDKs, v4 sends function results with role user:

• FunctionCallExtensions.ToFunctionCallContent(...) now returns Content with Role = Roles.User.
• GenerativeModel converts any Content with Role == "function" to "user" before sending. Chat histories saved by older versions keep working.
• With Microsoft.Extensions.AI, a turn made up only of function responses still converts back to ChatRole.Tool.

If your code finds function-result turns by checking content.Role == Roles.Function, check the parts instead:

// v3.x
var isFunctionResult = content.Role == Roles.Function;

// v4.0
var isFunctionResult = content.Parts.Count > 0 && content.Parts.All(p => p.FunctionResponse != null);

GoogleAIModels.DefaultGeminiModel changed from models/gemini-2.5-flash to models/gemini-3.8-flash. Code that creates a model without passing one (and without GOOGLE_AI_MODEL) now calls Gemini 3.8 Flash. Pass a model explicitly if you need a specific one.

Other defaults changed to replace retired models:

Constants for models that Google has deprecated are marked [Obsolete(..., false)]. Using one gives compiler warning CS0618, which breaks the build if you use TreatWarningsAsErrors.

4.0.1: constants for models that Google has already shut down were removed, so code using them no longer compiles. This covers the Gemini 2.0 and old 2.5 preview models, the old embeddings, Gemma 3 on the Gemini API, every Imagen and retired Veo model, and the gecko models. The full list and replacements are in Supported Models.

Common replacements:

The full table is in Supported Models. GoogleAIModels.TextEmbedding stays in SupportedEmbedingModels.All, so the SDK still accepts it, but Google's API rejects it.

Google retired Veo models on the Gemini API. VideoGenerationModel now throws NotSupportedException right away on the Gemini API, without sending a request. Vertex AI is unchanged.

// v3.x - request sent, rejected by the API
var video = new VideoGenerationModel(googleAiAdapter, GoogleAIModels.Video.Veo3Generate001);

// v4.0 - use Vertex AI for Veo...
var vertexVideo = new VideoGenerationModel(vertexAdapter, VertexAIModels.Video.Veo31GeneratePreview);
// ...or Gemini Omni on the Gemini API through the Interactions API (see Interactions-API / Video-Generation)

LiveServerGoAway and LiveServerSessionResumptionUpdate in v3.x used field names the Live API never sends, so those objects were always empty. The old properties still exist but are [Obsolete]:

SessionResumptionStatus is also [Obsolete]. MultiModalLiveClient.LastSessionResumptionHandle now tracks the latest handle for you.

The Bidi* Live API message types now use the same names as the official Google GenAI SDKs (python-genai). Only the .NET type names changed; the JSON sent over the WebSocket is identical. Rename any references in your code:

The most common change is in MessageReceived handlers, where e.Payload is now a LiveServerMessage.

GetBaseUrl(bool appendVesion, ...) was renamed to GetBaseUrl(bool appendVersion, ...). Only callers that pass the argument by name (appendVesion: false) need to change.

GoogleAIPlatformAdapter(..., string? apiVersion = null, ...) and VertextPlatformAdapter(..., string? apiVersion = null, ...) used to default to ApiVersions.v1Beta and ApiVersions.v1Beta1. These are still the defaults unless the new GOOGLE_GENAI_API_VERSION environment variable is set. Your source code doesn't need to change. Recompile anything that binds to these constructors. See Configuration and Error Handling.

Google no longer documents Semantic Retrieval / AQA (SemanticRetrieverModel, CorporaManager, CorporaClient, DocumentsClient, ChunkClient, CorpusPermissionClient). The APIs still work in v4, but GoogleAIModels.Aqa is [Obsolete]. Their wiki pages are merged into Legacy Semantic Retrieval (AQA). For new work, use File Search (Gemini API) or the Vertex RAG Engine.

• Update all Google_GenerativeAI* packages to 4.0.0 together.
• Align any direct Microsoft.Extensions.AI* and ModelContextProtocol references with the versions above.
• Fix CS0618 warnings by moving to current model constants (Supported Models).
• Update EmbedContentAsync/BatchEmbedContentAsync overrides to take a CancellationToken.
• Replace Role == Roles.Function checks with checks on FunctionResponse parts.
• Catch ApiException (not only HttpRequestException) around streaming and file uploads.
• Move Veo calls on the Gemini API to Vertex AI or Gemini Omni, and Imagen on the Gemini API to Gemini image models.
• Live API: read NewHandle/Resumable/TimeLeft instead of the obsolete properties.
• Vertex AI: use region: "global" for the newest Gemini models.