Sqlite provider

docs/standard/data/sqlite/custom-versions.md

@@ -1,29 +1,26 @@
 ---
 title: Custom SQLite versions
-ms.date: 12/13/2019
+ms.date: 05/14/2020
 description: Learn how to use a custom version of the native SQLite library.
 ---
+
 # Custom SQLite versions
 
-Microsoft.Data.Sqlite is built on top of SQLitePCLRaw. You can use custom versions of the native SQLite library by using a bundle or by configuring a SQLitePCLRaw provider.
+`Microsoft.Data.Sqlite` is built on top of `SQLitePCLRaw`. You can use custom versions of the native SQLite library by using a bundle or by configuring a `SQLitePCLRaw` provider.
 
 ## Bundles
 
-SQLitePCLRaw provides bundle packages that make it easy to bring in the right dependencies across different platforms.
-
-The main Microsoft.Data.Sqlite package brings in SQLitePCLRaw.bundle_e_sqlite3 by default.
-
-To use a different bundle, install the `Microsoft.Data.Sqlite.Core` package instead along with the bundle package you want to use. Bundles are automatically initialized by Microsoft.Data.Sqlite.
+`SQLitePCLRaw` provides convenience-based bundle packages, that make it easy to bring in the right dependencies across different platforms. The main `Microsoft.Data.Sqlite` package brings in `SQLitePCLRaw.bundle_e_sqlite3` by default. To use a different bundle, install the `Microsoft.Data.Sqlite.Core` package instead along with the bundle package you want to use. Bundles are automatically initialized by `Microsoft.Data.Sqlite`.
 
 | Bundle | Description |
-| --- | --- |
-| SQLitePCLRaw.bundle_e_sqlite3 | Provides a consistent version of SQLite on all platforms. Includes the FTS4, FTS5, JSON1, and R*Tree extensions. This is the default. |
-| SQLitePCLRaw.bundle_green | Same as bundle_e_sqlite3, except on iOS where it uses the system SQLite library. |
-| SQLitePCLRaw.bundle_zetetic | Uses the official SQLCipher builds from Zetetic (not included). |
-| SQLitePCLRaw.bundle_winsqlite3 | Uses winsqlite3.dll, the system SQLite library on Windows 10. |
-| SQLitePCLRaw.bundle_e_sqlcipher | Provides an unofficial, open-source build of SQLCipher. |
+|--|--|
+| [SQLitePCLRaw.bundle_e_sqlite3](https://www.nuget.org/packages/SQLitePCLRaw.bundle_e_sqlite3) | Provides a consistent version of SQLite on all platforms. Includes the FTS4, FTS5, JSON1, and R*Tree extensions. This is the default. |
+| [SQLitePCLRaw.bundle_e_sqlcipher](https://www.nuget.org/packages/SQLitePCLRaw.bundle_e_sqlcipher) | Provides an unofficial, open-source build of `SQLCipher`. |
+| [SQLitePCLRaw.bundle_green](https://www.nuget.org/packages/SQLitePCLRaw.bundle_green) | Same as `bundle_e_sqlite3`, except on iOS where it uses the system SQLite library. |
+| [SQLitePCLRaw.bundle_winsqlite3](https://www.nuget.org/packages/SQLitePCLRaw.bundle_winsqlite3) | Uses `winsqlite3.dll`, the system SQLite library on Windows 10. |
+| [SQLitePCLRaw.bundle_zetetic](https://www.nuget.org/packages/SQLitePCLRaw.bundle_zetetic) | Uses the official `SQLCipher` builds from Zetetic (not included). |
 
-For example, to use the unofficial, open-source build of SQLCipher use the following commands.
+For example, to use the unofficial, open-source build of `SQLCipher` use the following commands.
 
 ### [.NET Core CLI](#tab/netcore-cli)
 
@@ -41,14 +38,51 @@ Install-Package SQLitePCLRaw.bundle_e_sqlcipher
 
 ---
 
-## SQLitePCLRaw providers
+## SQLitePCLRaw available providers
+
+When not relying on a bundle, you can use the available providers of SQLite with the core assembly.
+
+| Provider | Description |
+|--|--|
+| [SQLitePCLRaw.provider.dynamic](https://www.nuget.org/packages/SQLitePCLRaw.provider.dynamic) | The `dynamic` provider loads the native library instead of using <xref:System.Runtime.InteropServices.DllImportAttribute?displayProperty=nameWithType> attributes. For more information on using this provider, see [use the dynamic provider](#use-the-dynamic-provider). |
+| [SQLitePCLRaw.provider.e_sqlite3](https://www.nuget.org/packages/SQLitePCLRaw.provider.e_sqlite3) | The `e_sqlite3` is the default provider. |
+| [SQLitePCLRaw.provider.e_sqlcipher](https://www.nuget.org/packages/SQLitePCLRaw.provider.e_sqlcipher) | The `e_sqlcipher` provider is the unofficial and unsupported `SQLCipher`. |
+| [SQLitePCLRaw.provider.sqlite3](https://www.nuget.org/packages/SQLitePCLRaw.provider.sqlite3) | The `sqlite3` provider is a system-provided `SQLite` for iOS, macOS, and Linux. |
+| [SQLitePCLRaw.provider.sqlcipher](https://www.nuget.org/packages/SQLitePCLRaw.provider.sqlcipher) | The `sqlcipher` provider is for official `SQLCipher` builds from `Zetetic`. |
+| [SQLitePCLRaw.provider.winsqlite3](https://www.nuget.org/packages/SQLitePCLRaw.provider.winsqlite3) | The `winsqlite3` provider is for Windows 10 environments. |
+
+To use the `sqlite3` provider use the following commands:
+
+### [.NET Core CLI](#tab/netcore-cli)
+
+```dotnetcli
+dotnet add package Microsoft.Data.Sqlite.Core
+dotnet add package SQLitePCLRaw.core
+dotnet add package SQLitePCLRaw.provider.sqlite3
+```
+
+### [Visual Studio](#tab/visual-studio)
+
+``` PowerShell
+Install-Package Microsoft.Data.Sqlite.Core
+Install-Package SQLitePCLRaw.core
+Install-Package SQLitePCLRaw.provider.sqlite3
+```
+
+---
+
+With the packages installed, you then set the provider to the `sqlite3` instance.
+
+[!code-csharp[](../../../../samples/snippets/standard/data/sqlite/SqliteProviderSample/Program.cs)]
+
+## Use the dynamic provider
 
 You can use your own build of SQLite by leveraging the `SQLitePCLRaw.provider.dynamic_cdecl` package. In this case, you're responsible for deploying the native library with your app. Note, the details of deploying native libraries with your app vary considerably depending on which .NET platform and runtime you're using.
 
-First, you'll need to implement IGetFunctionPointer. The implementation is fairly trivial on .NET Core.
+First, you'll need to implement `IGetFunctionPointer`. The implementation on .NET Core is as follows:
 
 [!code-csharp[](../../../../samples/snippets/standard/data/sqlite/SystemLibrarySample/Program.cs?name=snippet_NativeLibraryAdapter)]
 
-Next, configure the SQLitePCLRaw provider. Ensure this is done before Microsoft.Data.Sqlite is used in your app. Also, avoid using a SQLitePCLRaw bundle package which might override your provider.
+Next, configure the `SQLitePCLRaw` provider. Ensure this is done before `Microsoft.Data.Sqlite` is used in your app. Also, avoid using a `SQLitePCLRaw` bundle package which might override your provider.
 
 [!code-csharp[](../../../../samples/snippets/standard/data/sqlite/SystemLibrarySample/Program.cs?name=snippet_SetProvider)]

samples/snippets/standard/data/sqlite/Microsoft.Data.Sqlite.sln

@@ -39,7 +39,9 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "ExtensionsSample", "Extensi
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "HelloWorldSample", "HelloWorldSample\HelloWorldSample.csproj", "{DFB7A154-EA8D-4DD5-BB90-F87634A640A2}"
 EndProject
-Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "DapperSample", "DapperSample\DapperSample.csproj", "{C9005435-DFED-4986-A405-F7546312E66B}"
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "DapperSample", "DapperSample\DapperSample.csproj", "{C9005435-DFED-4986-A405-F7546312E66B}"
+EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "SqliteProviderSample", "SqliteProviderSample\SqliteProviderSample.csproj", "{E52BF2F4-6941-493F-8022-CD783889C1E2}"
 EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
@@ -123,6 +125,10 @@ Global
 		{C9005435-DFED-4986-A405-F7546312E66B}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{C9005435-DFED-4986-A405-F7546312E66B}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{C9005435-DFED-4986-A405-F7546312E66B}.Release|Any CPU.Build.0 = Release|Any CPU
+		{E52BF2F4-6941-493F-8022-CD783889C1E2}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{E52BF2F4-6941-493F-8022-CD783889C1E2}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{E52BF2F4-6941-493F-8022-CD783889C1E2}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{E52BF2F4-6941-493F-8022-CD783889C1E2}.Release|Any CPU.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE

samples/snippets/standard/data/sqlite/SqliteProviderSample/Program.cs

@@ -0,0 +1,16 @@
+using Microsoft.Data.Sqlite;
+using System;
+
+namespace SqliteProviderSample
+{
+    class Program
+    {
+        static void Main()
+        {
+            SQLitePCL.raw.SetProvider(new SQLitePCL.SQLite3Provider_sqlite3());
+
+            using var connection = new SqliteConnection();
+            Console.WriteLine($"System SQLite version: {connection.ServerVersion}");
+        }
+    }
+}

samples/snippets/standard/data/sqlite/SqliteProviderSample/SqliteProviderSample.csproj

@@ -0,0 +1,14 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>netcoreapp3.1</TargetFramework>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Data.Sqlite.Core" Version="3.1.4" />
+    <PackageReference Include="SQLitePCLRaw.core" Version="2.0.3" />
+    <PackageReference Include="SQLitePCLRaw.provider.sqlite3" Version="2.0.3" />
+  </ItemGroup>
+
+</Project>