Lokasi ngalangkungan proxy:   [ UP ]  
[Ngawartoskeun bug]   [Panyetelan cookie]                
Skip to content

Commit 633b8c0

Browse files
rwestMSFTrwestMSFT
committed
Refresh getting started with CLR and address issue 8300
1 parent ba3477b commit 633b8c0

1 file changed

Lines changed: 130 additions & 126 deletions

File tree

‎docs/relational-databases/clr-integration/database-objects/getting-started-with-clr-integration.md‎

Lines changed: 130 additions & 126 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
11
---
2-
title: "Getting Started with CLR Integration"
2+
title: "Get started with CLR integration"
33
description: This article describes the namespaces and libraries required to compile database objects using the Microsoft SQL Server integration with the .NET Framework CLR.
44
author: rwestMSFT
55
ms.author: randolphwest
6-
ms.date: "08/02/2016"
6+
ms.date: 11/24/2022
77
ms.service: sql
88
ms.subservice: clr
99
ms.topic: quickstart
@@ -23,147 +23,151 @@ dev_langs:
2323
- "TSQL"
2424
- "VB"
2525
- "CSharp"
26-
ms.assetid: c73e628a-f54a-411a-bfe3-6dae519316cc
2726
---
28-
# Getting Started with CLR Integration
27+
# Get started with CLR integration
2928

3029
[!INCLUDE [SQL Server](../../../includes/applies-to-version/sqlserver.md)]
3130

32-
This topic provides an overview of the namespaces and libraries required to compile database objects using the [!INCLUDE[msCoName](../../../includes/msconame-md.md)] [!INCLUDE[ssNoVersion](../../../includes/ssnoversion-md.md)] integration with the .NET Framework common language runtime (CLR). The topic also shows you how to write, compile, and run a simple CLR stored procedure written in [!INCLUDE[msCoName](../../../includes/msconame-md.md)] Visual C#.
33-
34-
## Required Namespaces
31+
This article provides an overview of the namespaces and libraries required to compile database objects using the [!INCLUDE[msCoName](../../../includes/msconame-md.md)] [!INCLUDE[ssNoVersion](../../../includes/ssnoversion-md.md)] integration with the .NET Framework common language runtime (CLR). The article also shows you how to write, compile, and run a small CLR stored procedure written in [!INCLUDE[msCoName](../../../includes/msconame-md.md)] Visual C# and Visual Basic.
3532

36-
The components required to develop basic CLR database objects are installed with [!INCLUDE[ssNoVersion](../../../includes/ssnoversion-md.md)]. CLR integration functionality is exposed in an assembly called system.data.dll, which is part of the .NET Framework. This assembly can be found in the Global Assembly Cache (GAC) as well as in the .NET Framework directory. A reference to this assembly is typically added automatically by both command line tools and [!INCLUDE[msCoName](../../../includes/msconame-md.md)] Visual Studio, so there is no need to add it manually.
37-
38-
The system.data.dll assembly contains the following namespaces, which are required for compiling CLR database objects:
39-
40-
- `System.Data`
41-
- `System.Data.Sql`
42-
- `Microsoft.SqlServer.Server`
43-
- `System.Data.SqlTypes`
33+
## Required namespaces
4434

45-
> [!TIP]
46-
> Loading CLR database objects on Linux is supported, but they must be built with the .NET Framework (SQL Server CLR integration does not support .NET Core). Also, CLR assemblies with the EXTERNAL_ACCESS or UNSAFE permission set are not supported on Linux.
35+
The components required to develop basic CLR database objects are installed with [!INCLUDE[ssNoVersion](../../../includes/ssnoversion-md.md)]. CLR integration functionality is exposed in an assembly called `System.Data.dll`, which is part of the .NET Framework. This assembly can be found in the Global Assembly Cache (GAC) as well as in the .NET Framework directory. A reference to this assembly is typically added automatically by both command line tools and [!INCLUDE[msCoName](../../../includes/msconame-md.md)] Visual Studio, so there's no need to add it manually.
4736

48-
## Writing A Simple "Hello World" Stored Procedure
37+
The `System.Data.dll` assembly contains the following namespaces, which are required for compiling CLR database objects:
4938

50-
Copy and paste the following Visual C# or [!INCLUDE[msCoName](../../../includes/msconame-md.md)] Visual Basic code into a text editor, and save it in a file named "helloworld.cs" or "helloworld.vb".
51-
52-
```csharp
53-
using System;
54-
using System.Data;
55-
using Microsoft.SqlServer.Server;
56-
using System.Data.SqlTypes;
57-
58-
public class HelloWorldProc
59-
{
60-
[Microsoft.SqlServer.Server.SqlProcedure]
61-
public static void HelloWorld(out string text)
62-
{
63-
SqlContext.Pipe.Send("Hello world!" + Environment.NewLine);
64-
text = "Hello world!";
65-
}
66-
}
67-
```
68-
69-
```vb
70-
Imports System
71-
Imports System.Data
72-
Imports Microsoft.SqlServer.Server
73-
Imports System.Data.SqlTypes
74-
Imports System.Runtime.InteropServices
75-
76-
Public Class HelloWorldProc
77-
\<Microsoft.SqlServer.Server.SqlProcedure> _
78-
Public Shared Sub HelloWorld(\<Out()> ByRef text as String)
79-
SqlContext.Pipe.Send("Hello world!" & Environment.NewLine)
80-
text = "Hello world!"
81-
End Sub
82-
End Class
83-
84-
```
85-
86-
This simple program contains a single static method on a public class. This method uses two new classes, **[SqlContext](/dotnet/api/microsoft.sqlserver.server.sqlcontext)** and **[SqlPipe](/dotnet/api/microsoft.sqlserver.server.sqlpipe)**, for creating managed database objects to output a simple text message. The method also assigns the string "Hello world!" as the value of an out parameter. This method can be declared as a stored procedure in [!INCLUDE[ssNoVersion](../../../includes/ssnoversion-md.md)], and then run in the same manner as a [!INCLUDE[tsql](../../../includes/tsql-md.md)] stored procedure.
87-
88-
Compile this program as a library, load it into [!INCLUDE[ssNoVersion](../../../includes/ssnoversion-md.md)], and run it as a stored procedure.
89-
90-
## Compile the "Hello World" stored procedure
39+
- `System.Data`
40+
- `System.Data.Sql`
41+
- `Microsoft.SqlServer.Server`
42+
- `System.Data.SqlTypes`
9143

92-
[!INCLUDE[ssNoVersion](../../../includes/ssnoversion-md.md)] installs the [!INCLUDE[msCoName](../../../includes/msconame-md.md)] .NET Framework redistribution files by default. These files include csc.exe and vbc.exe, the command-line compilers for Visual C# and Visual Basic programs. In order to compile our sample, you must modify your path variable to point to the directory containing csc.exe or vbc.exe. The following is the default installation path of the .NET Framework.
93-
94-
`C:\Windows\Microsoft.NET\Framework\(version)`
95-
96-
Version contains the version number of the installed .NET Framework redistributable. For example:
97-
98-
`C:\Windows\Microsoft.NET\Framework\v4.6.1`
44+
> [!TIP]
45+
> Loading CLR database objects on Linux is supported, but they must be built with the .NET Framework (SQL Server CLR integration does not support .NET Core, or .NET 5 or later versions). Also, CLR assemblies with the `EXTERNAL_ACCESS` or `UNSAFE` permission set are not supported on Linux.
9946
100-
Once you have added the .NET Framework directory to your path, you can compile the sample stored procedure into an assembly with the following command. The **/target** option allows you to compile it into an assembly.
101-
102-
For Visual C# source files:
103-
104-
`csc /target:library helloworld.cs`
105-
106-
For Visual Basic source files:
107-
108-
`vbc /target:library helloworld.vb`
109-
110-
These commands launch the Visual C# or Visual Basic compiler using the /target option to specify building a library DLL.
111-
112-
## Loading and Running the "Hello World" Stored Procedure in SQL Server
47+
## Write a "Hello World" stored procedure
48+
49+
Copy and paste the following Visual C# or Visual Basic code into a text editor, and save it in a file named `helloworld.cs` or `helloworld.vb`.
50+
51+
# [C#](#tab/cs)
52+
53+
```csharp
54+
using System;
55+
using System.Data;
56+
using Microsoft.SqlServer.Server;
57+
using System.Data.SqlTypes;
58+
59+
public class HelloWorldProc
60+
{
61+
[Microsoft.SqlServer.Server.SqlProcedure]
62+
public static void HelloWorld(out string text)
63+
{
64+
SqlContext.Pipe.Send("Hello world!" + Environment.NewLine);
65+
text = "Hello world!";
66+
}
67+
}
68+
```
69+
70+
# [VB](#tab/vb)
71+
72+
```vb
73+
Imports System
74+
Imports System.Data
75+
Imports Microsoft.SqlServer.Server
76+
Imports System.Data.SqlTypes
77+
Imports System.Runtime.InteropServices
78+
79+
Public Class HelloWorldProc
80+
\<Microsoft.SqlServer.Server.SqlProcedure> _
81+
Public Shared Sub HelloWorld(\<Out()> ByRef text as String)
82+
SqlContext.Pipe.Send("Hello world!" & Environment.NewLine)
83+
text = "Hello world!"
84+
End Sub
85+
End Class
86+
```
87+
88+
---
89+
90+
This program contains a single static method on a public class. This method uses two new classes, [SqlContext](/dotnet/api/microsoft.sqlserver.server.sqlcontext) and [SqlPipe](/dotnet/api/microsoft.sqlserver.server.sqlpipe), for creating managed database objects to output a short text message. The method also assigns the string "Hello world!" as the value of an `out` parameter. This method can be declared as a stored procedure in [!INCLUDE[ssNoVersion](../../../includes/ssnoversion-md.md)], and then run in the same manner as a [!INCLUDE[tsql](../../../includes/tsql-md.md)] stored procedure.
91+
92+
Compile this program as a library, load it into [!INCLUDE[ssNoVersion](../../../includes/ssnoversion-md.md)], and run it as a stored procedure.
93+
94+
## Compile the "Hello World" stored procedure
95+
96+
[!INCLUDE[ssNoVersion](../../../includes/ssnoversion-md.md)] installs the .NET Framework redistribution files by default. These files include `csc.exe` and `vbc.exe`, the command-line compilers for Visual C# and Visual Basic programs. In order to compile our sample, you must modify your path variable to point to the directory containing `csc.exe` or `vbc.exe`. The following path is the default installation path of the .NET Framework.
97+
98+
`C:\Windows\Microsoft.NET\Framework\(version)`
99+
100+
Version contains the version number of the installed .NET Framework. For example:
101+
102+
`C:\Windows\Microsoft.NET\Framework\v4.8.0`
103+
104+
Once you've added the .NET Framework directory to your path, you can compile the sample stored procedure into an assembly with the following command. The `/target` option allows you to compile it into an assembly.
105+
106+
For Visual C# source files:
107+
108+
`csc /target:library helloworld.cs`
109+
110+
For Visual Basic source files:
111+
112+
`vbc /target:library helloworld.vb`
113+
114+
These commands launch the Visual C# or Visual Basic compiler using the `/target` option to specify building a library DLL.
115+
116+
## Load and run the "Hello World" stored procedure in SQL Server
117+
118+
Once the sample procedure has successfully compiled, you can test it in [!INCLUDE[ssNoVersion](../../../includes/ssnoversion-md.md)]. To do this, open [!INCLUDE[ssManStudioFull](../../../includes/ssmanstudiofull-md.md)] and create a new query, connecting to a suitable test database (for example, the `AdventureWorks` sample database).
119+
120+
The ability to execute common language runtime (CLR) code is set to `OFF` by default in [!INCLUDE[ssNoVersion](../../../includes/ssnoversion-md.md)]. The CLR code can be enabled by using the `sp_configure` system stored procedure. For more information, see [Enabling CLR Integration](../../../relational-databases/clr-integration/clr-integration-enabling.md).
121+
122+
We'll need to create the assembly so we can access the stored procedure. For this example, we'll assume that you've created the `helloworld.dll` assembly in the `C:\` directory. Add the following [!INCLUDE[tsql](../../../includes/tsql-md.md)] statement to your query.
123+
124+
`CREATE ASSEMBLY helloworld from 'C:\helloworld.dll' WITH PERMISSION_SET = SAFE`
125+
126+
Once the assembly has been created, we can now access our HelloWorld method by using the create procedure statement. We'll call our stored procedure `hello`:
113127

114-
Once the sample procedure has successfully compiled, you can test it in [!INCLUDE[ssNoVersion](../../../includes/ssnoversion-md.md)]. To do this, open [!INCLUDE[ssManStudioFull](../../../includes/ssmanstudiofull-md.md)] and create a new query, connecting to a suitable test database (for example, the AdventureWorks sample database).
115-
116-
The ability to execute common language runtime (CLR) code is set to OFF by default in [!INCLUDE[ssNoVersion](../../../includes/ssnoversion-md.md)]. The CLR code can be enabled by using the **sp_configure** system stored procedure. For more information, see [Enabling CLR Integration](../../../relational-databases/clr-integration/clr-integration-enabling.md).
117-
118-
We will need to create the assembly so we can access the stored procedure. For this example, we will assume that you have created the helloworld.dll assembly in the C:\ directory. Add the following [!INCLUDE[tsql](../../../includes/tsql-md.md)] statement to your query.
119-
120-
`CREATE ASSEMBLY helloworld from 'c:\helloworld.dll' WITH PERMISSION_SET = SAFE`
121-
122-
Once the assembly has been created, we can now access our HelloWorld method by using the create procedure statement. We will call our stored procedure "hello":
123-
124128
```sql
125-
CREATE PROCEDURE hello
126-
@i nchar(25) OUTPUT
127-
AS
128-
EXTERNAL NAME helloworld.HelloWorldProc.HelloWorld
129-
-- if the HelloWorldProc class is inside a namespace (called MyNS),
130-
-- the last line in the create procedure statement would be
131-
-- EXTERNAL NAME helloworld.[MyNS.HelloWorldProc].HelloWorld
132-
```
133-
134-
Once the procedure has been created, it can be run just like a normal stored procedure written in [!INCLUDE[tsql](../../../includes/tsql-md.md)]. Execute the following command:
135-
129+
CREATE PROCEDURE hello
130+
@i nchar(25) OUTPUT
131+
AS
132+
EXTERNAL NAME helloworld.HelloWorldProc.HelloWorld;
133+
-- if the HelloWorldProc class is inside a namespace (called MyNS),
134+
-- the last line in the create procedure statement would be
135+
-- EXTERNAL NAME helloworld.[MyNS.HelloWorldProc].HelloWorld
136+
```
137+
138+
Once the procedure has been created, it can be run just like a normal stored procedure written in [!INCLUDE[tsql](../../../includes/tsql-md.md)]. Execute the following command:
139+
136140
```sql
137-
DECLARE @J nchar(25)
138-
EXEC hello @J out
139-
PRINT @J
140-
```
141-
142-
This should result in the following output in the [!INCLUDE[ssManStudioFull](../../../includes/ssmanstudiofull-md.md)] messages window.
143-
141+
DECLARE @J NCHAR(25);
142+
EXEC hello @J out;
143+
PRINT @J;
144144
```
145-
Hello world!
146-
Hello world!
147-
```
148-
149-
## Removing the "Hello World" Stored Procedure Sample
150145

151-
When you are finished running the sample stored procedure, you can remove the procedure and the assembly from your test database.
152-
153-
First, remove the procedure using the drop procedure command.
154-
146+
This should result in the following output in the [!INCLUDE[ssManStudioFull](../../../includes/ssmanstudiofull-md.md)] messages window.
147+
148+
```output
149+
Hello world!
150+
Hello world!
151+
```
152+
153+
## Remove the "Hello World" stored procedure sample
154+
155+
When you're finished running the sample stored procedure, you can remove the procedure and the assembly from your test database.
156+
157+
First, remove the procedure using the drop procedure command.
158+
155159
```sql
156-
IF EXISTS (SELECT name FROM sysobjects WHERE name = 'hello')
157-
drop procedure hello
158-
```
159-
160-
Once the procedure has been dropped, you can remove the assembly containing your sample code.
161-
160+
IF EXISTS (SELECT name FROM sysobjects WHERE name = 'hello')
161+
DROP PROCEDURE hello;
162+
```
163+
164+
Once the procedure has been dropped, you can remove the assembly containing your sample code.
165+
162166
```sql
163-
IF EXISTS (SELECT name FROM sys.assemblies WHERE name = 'helloworld')
164-
drop assembly helloworld
165-
```
166-
167+
IF EXISTS (SELECT name FROM sys.assemblies WHERE name = 'helloworld')
168+
DROP ASSEMBLY helloworld;
169+
```
170+
167171
## Next steps
168172

169173
For more information about CLR integration in SQL Server, see the following articles:

0 commit comments

Comments
 (0)