NetCreateProvisioningPackage 函数 (lmjoin.h)
NetCreateProvisioningPackage 函数创建一个预配包，用于预配计算机帐户以供以后在脱机域加入操作中使用。 该包还可能包含有关在预配期间要添加到计算机的证书和策略的信息。
语法
NET_API_STATUS NET_API_FUNCTION NetCreateProvisioningPackage(
[in] PNETSETUP_PROVISIONING_PARAMS pProvisioningParams,
[out, optional] PBYTE *ppPackageBinData,
[out, optional] DWORD *pdwPackageBinDataSize,
[out, optional] LPWSTR *ppPackageTextData
);
参数
[in] pProvisioningParams
指向包含预配包相关信息 的 NETSETUP_PROVISIONING_PARAMS 结构的指针。
为此结构的成员定义了以下值：
| 值 | 含义 |
|---|---|
|
预配包中的 Windows 版本。 此成员应使用 Lmjoin.h 头文件中定义的以下值： NETSETUP_PROVISIONING_PARAMS_CURRENT_VERSION (0x00000001) |
|
指向以 null 结尾的常量字符串的指针，该字符串指定在其中创建计算机帐户的域的名称。 |
|
指向以 null 结尾的常量字符串的指针，该字符串指定计算机帐户属性 sAMAccountName 通过追加“$”从中派生的计算机的短名称。 此参数必须包含有效的 DNS 或 NetBIOS 计算机名称。 |
|
指向以 null 结尾的常量字符串的可选指针，该字符串包含将创建计算机帐户的组织单位 (OU) 的 RFC 1779 格式名称。 如果指定此参数，字符串必须包含完整路径，例如 OU=testOU，DC=domain，DC=Domain，DC=com。 否则，此参数必须为 NULL。
如果此参数为 NULL，则已知计算机对象容器将用作域中的已发布。 |
|
指向以 null 结尾的常量字符串的可选指针，该字符串包含要作为目标的域控制器的名称。 |
|
定义预配选项的一组位标志。 此参数可以是为传递给 NetProvisionComputerAccount 函数的 dwOptions 参数指定的一个或多个值。
这些可能的值在 Lmjoin.h 头文件中定义。 仅Windows 8和Windows Server 2012支持NETSETUP_PROVISION_ROOT_CA_CERTS选项。 |
|
指向以 NULL 结尾的证书模板名称数组的可选指针。 |
|
当 aCertTemplateNames 不为 NULL 时，此成员提供数组中项数的显式计数。 |
|
指向以 NULL 结尾的计算机策略名称数组的可选指针。 |
|
当 aMachinePolicyNames 不为 NULL 时，此成员提供数组中项数的显式计数。 |
|
指向字符串数组的可选指针。 每个数组元素都是一个以 NULL 结尾的字符串，用于指定注册表策略文件格式的文件的完整或部分路径。 有关注册表策略文件格式 的详细信息，请参阅 注册表策略文件格式
该路径可以是远程服务器上的 UNC 路径。 |
|
当 aMachinePolicyPaths 不为 NULL 时，此成员提供数组中项数的显式计数。 |
[out, optional] ppPackageBinData
一个可选指针，如果 NetProvisionComputerAccount 函数成功完成，它将接收 NetRequestOfflineDomainJoin 函数完成脱机域加入所需的包。 数据作为不透明的二进制缓冲区返回，该缓冲区可能传递给 NetRequestOfflineDomainJoin 函数。
如果此参数为 NULL，则 pPackageTextData 参数不得为 NULL。 如果此参数不为 NULL，则 pPackageTextData 参数必须为 NULL。
[out, optional] pdwPackageBinDataSize
指向一个值的指针，该值接收 pProvisionBinData 参数中返回的缓冲区的大小（以字节为单位）。
如果 pPackageBinData 参数不为 NULL，则此参数不得为 NULL。 当 pPackageBinData 参数为 NULL 时，此参数必须为 NULL。
[out, optional] ppPackageTextData
一个可选指针，如果 NetProvisionComputerAccount 函数成功完成，它将接收 NetRequestOfflineDomainJoin 函数完成脱机域加入所需的包。 数据以字符串形式返回，用于嵌入无人参与安装应答文件中。
如果此参数为 NULL，则 pPackageBinData 参数不得为 NULL。 如果此参数不为 NULL，则 pPackageBinData 参数必须为 NULL。
返回值
如果函数成功，则返回值NERR_Success。
如果函数失败，则返回值可以是以下错误代码之一或 系统错误代码之一。
| 返回代码 | 说明 |
|---|---|
|
访问被拒绝。 如果调用方没有足够的权限来完成该操作，则返回此错误。 |
|
只允许域的主域控制器执行此操作。 如果在 pProvisioningParams 参数指向的NETSETUP_PROVISIONING_PARAMS结构的 lpDcName 中指定了域控制器名称，但指定的计算机无法验证为NETSETUP_PROVISIONING_PARAMS的 lpDomain 中指定的目标域的域控制器，则返回此错误。 |
|
参数不正确。 如果 pProvisioningParams 参数均为 NULL，也会返回此错误。 如果 pProvisioningParams 参数指向的NETSETUP_PROVISIONING_PARAMS结构的 lpDomain 或 lpMachineName 成员为 NULL，也会返回此错误。 |
|
指定的域不存在。 |
|
不支持该请求。 如果在 pProvisioningParams 参数指向的NETSETUP_PROVISIONING_PARAMS结构中指定了 lpMachineAccountOU 成员，并且域控制器在不支持此参数的早期版本的 Windows 上运行，则返回此错误。 |
|
指定的域控制器不符合此操作的版本要求。 |
|
此操作需要支持 LDAP 的域控制器。 |
|
帐户已存在于域中，并且 pProvisioningParams 参数指向的 NETSETUP_PROVISIONING_PARAMS 结构的 dwProvisionOptions 成员中未指定NETSETUP_PROVISION_REUSE_ACCOUNT位。 |
|
工作站服务尚未启动。 |
|
此线程的远程过程调用已在进行中。 |
|
不支持远程过程调用协议序列。 |
注解
Windows 8和Windows Server 2012支持 NetCreateProvisioningPackage 函数，用于脱机联接操作。 对于 Windows 7，请使用 NetProvisionComputerAccount 函数。
NetCreateProvisioningPackage 函数用于预配计算机帐户，以便以后使用 NetRequestProvisioningPackageInstall 函数在脱机加入域操作中使用。
脱机加入域方案使用两个函数：
- NetCreateProvisioningPackage 是首先调用的预配函数，用于执行在 Active Directory 中创建和配置计算机对象所需的网络操作。 NetCreateProvisioningPackage 的输出是用于下一步的包。
- 调用 NetRequestProvisioningPackageInstall（映像初始化函数）将 NetCreateProvisioningPackage 预配函数的输出注入 Windows 操作系统映像，以便在预安装和安装后使用。
使用 pPackageBinData 和 pdwPackageBinDataSize out 指针时，将 pPackageTextData out 指针设置为 NULL。 使用 pPackageTextData 时，将 pPackageBinData 和 pdwPackageBinDataSize out 指针设置为 NULL。
pProvisioningParams 参数指定要包含在预配包中的数据。 包包含与域加入相关的信息，还可以包含有关要在计算机上安装的策略和证书的信息。 预配包可通过四种方式使用：
- 域加入
- 域加入和证书安装
- 域加入和策略安装
- 证书和策略的域加入和安装
NetCreateProvisioningPackage 函数在域中创建或重复使用计算机帐户，收集所有必要的元数据，并在包中返回该帐户。 该包可由脱机域加入请求操作使用，该操作提供在首次启动期间完成域加入所需的所有输入，而无需任何网络操作， (仅) 本地状态更新。
安全说明： NetCreateProvisioningPackage 函数返回的包包含非常敏感的数据。 它应该像纯文本密码一样安全处理。 该包包含计算机帐户密码和有关域的其他信息，包括域名、域控制器的名称以及域) SID (安全 ID。 如果正在以物理方式或通过网络传输包，则必须注意安全地传输它。 该设计不对保护此数据作出任何规定。 目前，无人参与安装应答文件存在此问题，这些文件可能携带许多机密，包括域用户密码。 调用方必须保护包。 此问题的解决方案各不相同。 例如，预交换的密钥可用于加密使用者和预配实体之间的会话，从而启用包的安全传输。
NetCreateProvisioningPackage 函数在 pPackageBinData 参数中返回的包进行了版本控制，以允许不同版本的 Windows (之间的互操作性和可维护性方案，例如加入客户端、预配计算机以及使用域控制器) 。 在 Windows 8 或 Windows Server 2012 上创建的包可以使用 Windows 7 或 Windows Server 2008 R2，但只有域加入信息才会生效， (不支持证书和策略) 。 脱机加入方案当前不限制 NetCreateProvisioningPackage 函数返回的包的生存期。
对于脱机加入域，执行的访问检查取决于域的配置。 使用三种方法启用计算机帐户创建：
- 域管理员有权创建计算机帐户。
- 容器上的 SD 可以委托创建计算机帐户的权限。
- 默认情况下，经过身份验证的用户可以按权限创建计算机帐户。 经过身份验证的用户仅限于在域中创建指定为配额的有限数量的帐户， (默认值为 10) 。 有关详细信息，请参阅 Active Directory 架构中的 ms-DS-MachineAccountQuota 属性。
NetCreateProvisioningPackage 函数仅适用于可写域控制器，不适用于只读域控制器。 针对可写域控制器完成预配并将帐户复制到只读域控制器后，脱机加入操作的其他部分不需要访问域控制器。
如果 NetCreateProvisioningPackage 函数成功，则 pPackageBinData 或 pPackageTextData 参数中的指针 (，具体取决于哪个参数不是 NULL) 随序列化数据一起返回，以便在脱机联接操作中使用或作为无人参与安装文件中的文本。
预配过程的所有阶段都追加到本地计算机上的 NetSetup.log 文件。 预配过程最多可以包括三台不同的计算机：创建设置包的计算机、请求安装包的计算机和安装包的计算机。 根据执行的操作，将 NetSetup.log存储在所有 三台计算机上的文件信息。 查看这些文件的内容是排查联机和脱机预配错误的最常见方法。 管理员执行的预配操作将记录到 %WINDIR%\Debug 中的 NetSetup.log 文件中。 非管理员执行的预配操作将记录到 %USERPROFILE%\Debug 文件夹中的 NetSetup.log 文件。
有关脱机加入域操作的详细信息，请参阅 脱机域加入分步指南。
使用 NetJoinDomain 和 NetUnjoinDomain 将 (联接和取消加入) 计算机到域仅由目标计算机上的 Administrators 本地组的成员执行。 请注意，域管理员可以使用委派和权限分配来设置加入域的其他要求。
要求
| 最低受支持的客户端 | Windows 8 [仅限桌面应用] |
| 最低受支持的服务器 | Windows Server 2012 [仅限桌面应用] |
| 目标平台 | Windows |
| 标头 | lmjoin.h (包括 Lm.h) |
| Library | Netapi32.lib |
| DLL | Netapi32.dll |
另请参阅
反馈
即将发布：在整个 2024 年，我们将逐步淘汰作为内容反馈机制的“GitHub 问题”，并将其取代为新的反馈系统。 有关详细信息，请参阅：https://aka.ms/ContentUserFeedback。
提交和查看相关反馈