Επεξεργασία

Κοινή χρήση μέσω

Install SQL Server .NET Language Extension on Windows

  • Άρθρο

Applies to: SQL Server 2019 (15.x) and later versions

Learn how to install the .NET Language Extension component (used by C#) for SQL Server on Windows. The .NET Language Extension is part of SQL Server Language Extensions.

Note

This article is for installation of .NET Language Extension for SQL Server on Windows. Linux isn't supported.

Prerequisites

Note

Feature capabilities and installation options vary between versions of SQL Server. Use the version selector dropdown list to choose the appropriate version of SQL Server.

  • SQL Server Setup is required if you want to install support for the .NET Language Extension.

  • The .NET Language Extension supports .NET 6 and later runtimes, and is only supported on Windows.

  • A Database Engine instance is required. You can't install just the .NET Language Extension features, although you can add them incrementally to an existing instance.

  • For business continuity, Always On availability groups are supported for Language Extensions. You have to install language extensions, and configure packages, on each node. Installing the .NET Language Extension also is supported on a failover cluster instance in SQL Server.

  • Don't install SQL Server Language Extensions or the .NET Language Extension on a domain controller. The Language Extensions portion of setup fails.

  • Language Extensions and Machine Learning Services are installed by default on SQL Server Big Data Clusters. If you use Big Data Clusters, you don't need to follow the steps in this article. For more information, see Run Python and R scripts with Machine Learning Services on SQL Server 2019 Big Data Clusters.

Important

After setup is complete, be sure to complete the post-configuration steps described in this article. These steps include enabling SQL Server to use external code, and adding accounts required for SQL Server to run C# code on your behalf. Configuration changes generally require a restart of the instance, or a restart of the Launchpad service.

.NET runtime

.NET 6 long-term support (LTS) is the earliest supported runtime. You can download the .NET runtime for Windows. Linux isn't supported.

If you want to use the latest LTS release of the .NET runtime, you must recompile the .NET Language Extension.

Get the installation media

The download location for SQL Server depends on the edition:

  • SQL Server Enterprise, Standard, and Express editions. These editions are licensed for production use. For the Enterprise and Standard editions, contact your software vendor for the installation media. You can find purchasing information and a directory of Microsoft partners on the Microsoft purchasing website.

  • The latest free edition.

Run Setup

For local installations, you must run Setup as an administrator. If you install SQL Server from a remote share, you must use a domain account that has read and execute permissions on the remote share.

  1. Start the setup wizard for SQL Server.

  2. On the Installation tab, select New SQL Server stand-alone installation or add features to an existing installation.

  3. On the Feature Selection page, select these options:

    Database Engine Services: To use Language Extensions with SQL Server, you must install an instance of the Database Engine. You can use either a default or a named instance.

    Machine Learning Services and Language Extensions: This option installs the Language Extensions component that support C# code execution.

    Screenshot of instance features.

  4. On the Ready to Install page, verify that these selections are included, and select Install.

    • Database Engine Services
    • Machine Learning Services and Language Extensions

    Note the location of the folder under the path ..\Setup Bootstrap\Log where the configuration files are stored. When setup is complete, you can review the installed components in the Summary file.

  5. After setup is complete, if you're instructed to restart the computer, do so now. It's important to read the message from the Installation Wizard when you finish with Setup. For more information, see View and Read SQL Server Setup Log Files.

Register the language extension

  1. Follow these steps to download and register the .NET language extension, which is used for running C# code.

    1. Download the dotnet-core-CSharp-lang-extension-windows-release.zip file from the .NET language extension for SQL Server GitHub repo. Download the latest Windows dotnet-core-CSharp-lang-extension-windows-release.zip file. If you prefer to use a newer .NET runtime, you need to compile dotnet-core-CSharp-lang-extension from GitHub source code.

    2. Use SQL Server Management Studio (SSMS) or Azure Data Studio to connect to your SQL Server instance and run the following Transact-SQL (T-SQL) command to register the .NET language extension with CREATE EXTERNAL LANGUAGE.

    3. Modify the path in this statement to reflect the location of the downloaded language extension zip file (dotnet-core-CSharp-lang-extension-windows-release.zip).

    CREATE EXTERNAL LANGUAGE [dotnet]
FROM (CONTENT = N'C:\path\to\dotnet-core-CSharp-lang-extension-windows-release.zip',
    FILE_NAME = 'dotnetextension.dll');
GO

  2. Restart Launchpad.

    1. Open SQL Server Configuration Manager.

    2. Under SQL Server Services, right-click SQL Server Launchpad and select Restart.

Restart the service

When the installation is complete, restart the Database Engine before continuing to the next step, enabling script execution.

Restarting the service also automatically restarts the related SQL Server Launchpad service.

You can restart the service using the right-click Restart command for the instance in SSMS, with the Services panel in Control Panel, or by using SQL Server Configuration Manager.

Enable script execution

  1. Open SQL Server Management Studio. Connect to the instance where you installed Language Extensions, select New Query to open a query window, and run the following command:

    EXEC sp_configure;

    The feature is off (value is 0) by default, and must be explicitly enabled by an administrator before you can run C# code.

  2. To enable the external scripting feature, run the following statement:

    EXEC sp_configure 'external scripts enabled', 1;
GO
RECONFIGURE WITH OVERRIDE

    If you already enabled the feature for Machine Learning Services, don't run reconfigure a second time for Language Extensions. The underlying extensibility platform supports both.

Register external language

For each database you want to use language extensions in, you need to register the external language with CREATE EXTERNAL LANGUAGE.

The following example adds an external language called dotnet to a database on SQL Server on Windows.

CREATE EXTERNAL LANGUAGE [dotnet]
FROM (CONTENT = N'<path-to-zip>', FILE_NAME = 'dotnetextension.dll');
GO

For more information, see CREATE EXTERNAL LANGUAGE.

Verify installation

Check the installation status of the instance in the setup logs.

Use the following steps to verify that all components used to launch external script are running.

  1. In SQL Server Management Studio or Azure Data Studio, open a new query window, and run the following statement:

    EXEC sp_configure 'external scripts enabled';

    The run_value is now set to 1.

  2. Open the Services panel or SQL Server Configuration Manager, and verify SQL Server Launchpad service is running. You should have one service for every Database Engine instance that has language extensions installed. For more information about the service, see Extensibility architecture in SQL Server Language Extensions.

Additional configuration

If the verification step was successful, you can run C# code from SQL Server Management Studio, Azure Data Studio, Visual Studio Code, or any other client that can send T-SQL statements to the server.

If you got an error when running the command, review the additional configuration steps in this section. You might need to make extra appropriate configurations to the service or database.

At the instance level, extra configuration might include:

On the database, you might need the following configuration updates:

Note

Whether additional configuration is required depends on your security schema, where you installed SQL Server, and how you expect users to connect to the database and run external scripts.

Suggested optimizations

Now that you have everything working, you might also want to optimize the server to support .NET Language Extension.

Optimize the server for .NET Language Extension

The default settings for SQL Server setup are intended to optimize the balance of the server for a variety of services supported by the Database Engine, which might include extract, transform, and load (ETL) processes, reporting, auditing, and applications that use SQL Server data. Therefore, under the default settings, you might find that resources for language extensions are sometimes restricted or throttled, particularly in memory-intensive operations.

To ensure that language extensions jobs are prioritized and resourced appropriately, we recommend that you use SQL Server Resource Governor to configure an external resource pool. You might also want to change the amount of memory allocated to the Database Engine, or increase the number of accounts that run under the SQL Server Launchpad service.

If you use Standard edition and don't have Resource Governor, you can use dynamic management views (DMVs) and Extended Events, as well as Windows event monitoring, to help manage the server resources.

Next step

C# developers can get started with some simple examples, and learn the basics of how C# works with SQL Server. For your next step, see the following link:

Tutorial: Regular expressions with C#