Skip to content

Commit aae5a41

Browse files
paulmedynskipaulmedynski
committed
User Story 37654: Create Extensions base package
- Added temporary GitHub Discussion content so the team can review before posting it as a real Discussion.
1 parent 2dce507 commit aae5a41

File tree

1 file changed

+261
-0
lines changed

1 file changed

+261
-0
lines changed

‎src/Microsoft.Data.SqlClient.Extensions/Extensions/github-discussion.md‎

Lines changed: 261 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,261 @@
1+
Decoupling Azure Dependencies
2+
3+
# Overview
4+
5+
For the MDS 7.0.0 release, we are proposing the following package architecture
6+
changes that will decouple several large dependencies from MDS and move them
7+
into a new Azure extensions package:
8+
9+
- Create a new Extensions base package that all other MDS packages depend on.
10+
- This will contain types and definitions common to the other MDS packages,
11+
such as base classes, enums, delegates, etc.
12+
- Create a new Azure package that will own the following implementations:
13+
- Azure Authentication
14+
- Azure Attestation
15+
- Azure Key Vault interactions
16+
- Move the above implementations out of MDS and into the new Azure package.
17+
- Move the existing Azure Key Vault Provider implementation into the new Azure
18+
extensions package.
19+
20+
This will reduce the main MDS package dependency tree along with a moderate
21+
package size reduction.
22+
23+
# Motivation
24+
25+
Issue: #1108
26+
27+
Customers and the developer community have voiced concerns with MDS being
28+
tightly coupled to Azure dependencies. Many customers do not use Azure and do
29+
not want to deploy unnecessary DLLs with their applications.
30+
31+
Moving the Azure dependent implementations into a separate Azure extensions
32+
package achieves two goals:
33+
34+
- Remove Azure packages as direct dependencies of MDS and reduce the MDS
35+
dependency tree.
36+
- Clearly expose existing MDS extension points, prove their functionality, and
37+
demonstrate how to use them.
38+
39+
# Package Architecture
40+
41+
```mermaid
42+
classDiagram
43+
class MDS
44+
class MDS.Extensions
45+
class MDS.Extensions.Azure
46+
class AKV Provider
47+
48+
MDS --> MDS.Extensions
49+
MDS ..> MDS.Extensions.Azure
50+
MDS ..> AKV Provider
51+
MDS.Extensions.Azure --> MDS.Extensions
52+
AKV Provider --> MDS.Extensions.Azure
53+
54+
MDS: Depend on MDS.Extensions
55+
MDS: Load Azure or AKV assembly
56+
MDS.Extensions: Azure Authentication Types
57+
MDS.Extensions: Azure Attestation Types
58+
MDS.Extensions: Azure Key Vault Types
59+
MDS.Extensions.Azure: Depend on MDS.Extensions
60+
MDS.Extensions.Azure: Authentication Implementation
61+
MDS.Extensions.Azure: Attestation Implementation
62+
MDS.Extensions.Azure: Key Vault Implementation
63+
AKV Provider: Depend on MDS.Extensions.Azure
64+
```
65+
66+
In previous MDS versions, the AKV Provider package depended directly on the main
67+
MDS package through a ranged version (for example [6.0.0, 7.0.0) - all 6.x
68+
versions). With the new package architecture this is no longer the case.
69+
Extension packages will not depend on the main MDS package, nor will the main
70+
MDS package depend on any Extension packages. All dependencies between MDS and
71+
its extensions will occur through the Extensions base package.
72+
73+
This new looser coupling gives applications the flexibility to depend on only
74+
the main MDS package, or on MDS and a subset of it extension packages if
75+
desired.
76+
77+
# Consuming
78+
79+
There are several ways that applications may consume MDS and its extensions:
80+
81+
- MDS with without Azure features
82+
- MDS with MDS-supplied Azure features
83+
- MDS with externally supplied Azure features
84+
85+
Applications never need to directly depend on the Extensions base package. This
86+
will be transitively depended on by other MDS packages.
87+
88+
## Without Azure Features
89+
90+
Applications that do not use any Azure features will no longer bring in those
91+
unwanted dependencies transitively. Simply include the main MDS package by
92+
itself:
93+
94+
```xml
95+
<ItemGroup>
96+
<PackageReference Include="Microsoft.Data.SqlClient" Version="7.0.0" />
97+
</ItemGroup>
98+
```
99+
100+
## With MDS Azure Features
101+
102+
Applications that wish to use MDS-supplied Azure features will need to include
103+
the new Azure extensions package as a direct dependency alongside the main MDS
104+
package:
105+
106+
```xml
107+
<ItemGroup>
108+
<PackageReference Include="Microsoft.Data.SqlClient" Version="7.0.0" />
109+
<PackageReference Include="Microsoft.Data.SqlClient.Extensions.Azure" Version="7.0.0" />
110+
</ItemGroup>
111+
```
112+
113+
## With External Azure Features
114+
115+
Applications that wish to use Azure features supplied by another (non-MDS)
116+
package will need to include that package as a direct dependency alongside the
117+
main MDS package:
118+
119+
```xml
120+
<ItemGroup>
121+
<PackageReference Include="Microsoft.Data.SqlClient" Version="7.0.0" />
122+
<PackageReference Include="My.MDS.Azure.Features.Package" Version="1.2.3" />
123+
</ItemGroup>
124+
```
125+
126+
Additionally, the applications will need to instruct MDS to use the external
127+
Azure feature implementations via the appropriate APIs at runtime:
128+
129+
- Authentication: [SqlAuthenticationProvider](https://learn.microsoft.com/en-us/dotnet/api/microsoft.data.sqlclient.sqlauthenticationprovider?view=sqlclient-dotnet-core-6.0)
130+
- Attestation: TBD
131+
- Key Valut: [SqlColumnEncryptionKeyStoreProvider](https://learn.microsoft.com/en-us/dotnet/api/microsoft.data.sqlclient.sqlcolumnencryptionkeystoreprovider?view=sqlclient-dotnet-core-6.0)
132+
133+
# Versioning Strategy
134+
135+
The MDS suite of packages will be versioned together, similar to how .NET system
136+
packages are versioned with the major .NET version. The initial release of
137+
these packages will have the following versions:
138+
139+
|Package|Version|
140+
|-|-|
141+
|Microsoft.Data.SqlClient.Extensions|7.0.0|
142+
|Microsoft.Data.SqlClient.|7.0.0|
143+
|Microsoft.Data.SqlClient.Extensions.Azure|7.0.0|
144+
|Microsoft.Data.SqlClient.AlwaysEncrypted.AzureKeyVaultProvider|7.0.0|
145+
146+
Going forward, the suite will be released with matching version numbers as
147+
changes are made. For example, if the next release is v7.1.0, the packages
148+
will be versioned as follows and released together:
149+
150+
|Package|Version|
151+
|-|-|
152+
|Microsoft.Data.SqlClient.Extensions|7.1.0|
153+
|Microsoft.Data.SqlClient.|7.1.0|
154+
|Microsoft.Data.SqlClient.Extensions.Azure|7.1.0|
155+
156+
**Note**: The AzureKeyVaultProvider package will remain at 7.0.0. It will be
157+
deprecated and eventually removed, as it has been replaced by the Azure
158+
extensions package.
159+
160+
To ensure compatibility between the main MDS package and its extensions, all
161+
packages will maintain a strict dependency on their matching Extensions base
162+
package version. Once an application depends on a specific MDS package version,
163+
and it chooses to use an extension package, it will be forced to also to depend
164+
on the matching version of that extension package.
165+
166+
For example, the following scenario would fail during NuGet restore because
167+
the Azure extension package depends on a different version of the Extensions
168+
base package than the main MDS package:
169+
170+
|Package|Version|Extensions Base Version|
171+
|-|-|-|
172+
|Microsoft.Data.SqlClient.|7.1.0|7.1.0|
173+
|Microsoft.Data.SqlClient.Extensions.Azure|7.0.0|7.0.0|
174+
175+
# Backwards Compatibility
176+
177+
There are several backwards compatibility scenarios to consider for applications
178+
that rely on MDS Azure features currently living in the main MDS package and the
179+
Azure Key Vault Provider package. The new extensions package architecture aims
180+
to reduce the friction for these apps, but not all scenarios will be seamless.
181+
182+
All of the scenarios below assume that the application is upgrading to the MDS
183+
7.0.0 suite of packages.
184+
185+
## App using MDS Azure Authentication
186+
187+
Applications currently using the MDS-supplied Azure Authentication features will
188+
need to add a dependency to the Azure extension package to their project
189+
alongside the main MDS package:
190+
191+
```xml
192+
<ItemGroup>
193+
<PackageReference Include="Microsoft.Data.SqlClient" Version="7.0.0" />
194+
<PackageReference Include="Microsoft.Data.SqlClient.Extensions.Azure" Version="7.0.0" />
195+
</ItemGroup>
196+
```
197+
198+
All Azure Authentication namespaces and types will remain the same, so this
199+
should be the only change necessary for applications.
200+
201+
## App using MDS Azure Attestation
202+
203+
TBD
204+
205+
## App using AKV Provider
206+
207+
Applications currently using the MDS-supplied AKV Provider will have three
208+
options when upgrading to the v7.0.0 suite of packages. All options rely on the
209+
main MDS package finding and loading an appropriate DLL (assembly) at runtime.
210+
The absence of an appropriate DLL will cause Azure Key Vault operations to throw
211+
an exception.
212+
213+
### Use Azure Extension
214+
215+
This is the preferred approach. The application would be updated to depend
216+
on the main MDS package and the Azure extensions package:
217+
218+
```xml
219+
<ItemGroup>
220+
<PackageReference Include="Microsoft.Data.SqlClient" Version="7.0.0" />
221+
<PackageReference Include="Microsoft.Data.SqlClient.Extensions.Azure" Version="7.0.0" />
222+
</ItemGroup>
223+
```
224+
225+
The Azure extensions package will contain the same namespaces and types as the
226+
current AKV Provider and will be a drop-in replacement. The main MDS v7.0.0
227+
package will look for the Azure extensions assembly and automatically load it.
228+
229+
### Use AKV Provider v7.0.0
230+
231+
This is a temporary solution and will removed in a future release. The
232+
applictaion would remain dependent on the AKV Provider, but must update to
233+
the v7.0.0 package to match the main MDS version:
234+
235+
```xml
236+
<ItemGroup>
237+
<PackageReference Include="Microsoft.Data.SqlClient" Version="7.0.0" />
238+
<PackageReference Include="Microsoft.Data.SqlClient.AlwaysEncrypted.AzureKeyVaultProvider" Version="7.0.0" />
239+
</ItemGroup>
240+
```
241+
242+
This v7.0.0 AKV Provider package will be empty and simply depend on the Azure
243+
extensions package to provide the Azure Key Vault features. This transitional
244+
package will be deprecated and eventually removed.
245+
246+
### Use AKV Provider pre-v7.0.0
247+
248+
This is not a recommended approach and will not be supported, although it will
249+
may work in the near term. While MDS will retain its ability to find and load
250+
the AKV Provider DLL (see the approach above), there is no guarantee that an
251+
older DLL will provide the functionality expected by the main MDS package.
252+
253+
```xml
254+
<ItemGroup>
255+
<PackageReference Include="Microsoft.Data.SqlClient" Version="7.0.0" />
256+
<PackageReference Include="Microsoft.Data.SqlClient.AlwaysEncrypted.AzureKeyVaultProvider" Version="6.1.0" />
257+
</ItemGroup>
258+
```
259+
260+
Note that the above example would fail to NuGet restore if the AKV Provider
261+
package didn't advertise that it depends on at least MDS v7.0.0.

0 commit comments

Comments
 (0)