Migration Guides
Step-by-step migration guides for SmartRAG
Migration Guides
Step-by-step migration guides for upgrading SmartRAG versions.
Migrating from v3.x to v4.0.0
Breaking Changes
v4.0.0 targets .NET 6 and merges the SmartRAG.Dashboard project into the main SmartRAG package.
This migration guide covers the framework and project structure changes when upgrading from SmartRAG v3.x to v4.0.0.
Note: SmartRAG.Dashboard was never published as a NuGet package. In v3.x it existed as a separate project within the solution; in v4.0 that project was removed and the Dashboard code is now included in the SmartRAG package.
Step 1: Update Target Framework
Your project must target .NET 6 or higher:
<TargetFramework>net6.0</TargetFramework>
<!-- or net7.0, net8.0, net9.0 -->
Projects targeting .NET Core 3.0, .NET 5, or .NET Standard 2.1 must upgrade to at least .NET 6.
Step 2: Remove SmartRAG.Dashboard Project Reference
The Dashboard is now included in the SmartRAG package. If you had a ProjectReference to the SmartRAG.Dashboard project, remove it:
<!-- Remove this line -->
<ProjectReference Include="..\..\src\SmartRAG.Dashboard\SmartRAG.Dashboard.csproj" />
If you only reference the SmartRAG NuGet package or the main SmartRAG project, no changes are needed.
Step 3: Keep Using the Same API
No code changes needed. The Dashboard API remains the same:
using SmartRAG.Dashboard;
builder.Services.AddSmartRag(builder.Configuration);
builder.Services.AddSmartRagDashboard(options => { options.Path = "/smartrag"; });
app.UseSmartRagDashboard("/smartrag");
app.MapSmartRagDashboard("/smartrag");
The SmartRAG.Dashboard namespace and extension methods are now part of the SmartRAG package.
Migrating from v2.x to v3.0.0
Key Changes
The primary change is the renaming of GenerateRagAnswerAsync to QueryIntelligenceAsync.
This migration guide covers the changes needed when upgrading from SmartRAG v2.x to v3.0.0.
Step 1: Update Method Call
Update your service method call from GenerateRagAnswerAsync to QueryIntelligenceAsync:
// Before (v2.x)
var response = await _searchService.GenerateRagAnswerAsync(query, maxResults);
// After (v3.0.0)
var response = await _searchService.QueryIntelligenceAsync(query, maxResults);
Step 2: Update API Endpoints (if using Web API)
If you have a Web API controller, simply update the service method call:
// Before (v2.x)
[HttpPost("generate-answer")]
public async Task<IActionResult> GenerateAnswer([FromBody] QueryRequest request)
{
var response = await _searchService.GenerateRagAnswerAsync(request.Query);
return Ok(response);
}
// After (v3.0.0) - Only the method name changed
[HttpPost("generate-answer")]
public async Task<IActionResult> GenerateAnswer([FromBody] QueryRequest request)
{
var response = await _searchService.QueryIntelligenceAsync(request.Query);
return Ok(response);
}
Note
You can keep your existing endpoint paths and controller method names. Only the service method call needs to be updated.
Step 3: Update Client Code (if applicable)
If you have client code that calls the API, update the endpoint:
// Before
const response = await fetch('/api/intelligence/generate-answer', { ... });
// After
const response = await fetch('/api/intelligence/query', { ... });
v4.0.0 Update
GenerateRagAnswerAsync was removed in v4.0.0. You must use QueryIntelligenceAsync when upgrading to v4.
Migrating from v3.8.x to v3.9.0
Breaking Changes
v3.9.0 contains breaking changes for IStorageFactory, IConversationRepository, and removes IQdrantCacheManager.
Step 1: Update IStorageFactory Usage
If you inject IStorageFactory and call GetCurrentRepository(), pass the scoped IServiceProvider:
// Before (v3.8.x)
var repository = _storageFactory.GetCurrentRepository();
// After (v3.9.0)
var repository = _storageFactory.GetCurrentRepository(_serviceProvider);
When using DI, the registration already passes the scoped provider. If you resolve IDocumentRepository directly, no change is needed.
Step 2: Update Custom IConversationRepository Implementations
If you have a custom IConversationRepository implementation, add these methods:
Task AppendSourcesForTurnAsync(string sessionId, string sourcesJson, CancellationToken cancellationToken = default);
Task<string> GetSourcesForSessionAsync(string sessionId, CancellationToken cancellationToken = default);
Task<string[]> GetAllSessionIdsAsync(CancellationToken cancellationToken = default);
Built-in implementations (Sqlite, Redis, FileSystem, InMemory) already include these.
Step 3: Remove IQdrantCacheManager References (if used)
IQdrantCacheManager and QdrantCacheManager were removed. Search no longer uses query result caching. Remove any references to these types.
Migrating from v1.x to v2.0.0
Framework Change
Version 2.0.0 migrated from .NET 9.0 to .NET Standard 2.1
This migration guide covers the framework compatibility changes when upgrading from SmartRAG v1.x to v2.0.0.
Step 1: Verify Framework Compatibility
Your project must target one of these frameworks:
<TargetFramework>netstandard2.0</TargetFramework>
<TargetFramework>netstandard2.1</TargetFramework>
<TargetFramework>netcoreapp2.0</TargetFramework>
<TargetFramework>net461</TargetFramework>
<TargetFramework>net5.0</TargetFramework>
<TargetFramework>net6.0</TargetFramework>
<TargetFramework>net6.0</TargetFramework>
<TargetFramework>net8.0</TargetFramework>
<TargetFramework>net9.0</TargetFramework>
Step 2: Update NuGet Package
Update the SmartRAG package to version 2.0.0:
dotnet add package SmartRAG --version 2.0.0
Step 3: Verify Code Compatibility
No API changes - all functionality remains the same. Just ensure your project targets compatible framework.