This package contains a C# SDK for the Rooms Service of Azure Communication Services. Azure Communication Services (ACS) Rooms is a set of APIs, used by Contoso server applications to create a server-managed conversation space with fixed set of lifetime and participants, pre-defining rules from server-tier both who and when can communicate (like scheduled meeting creation).
With the general availability release of ACS Rooms, Contoso will be able to:
- Create a meeting space with known time coordinates (validFrom/validUntil)
- Join voice/video calls within that meeting space using the ACS web calling SDK or native mobile calling SDKs
- Add participants to a room
- Assign pre-defined roles to room participants
The main scenarios where Rooms can best be used:
- Virtual Visits (e.g., telemedicine, remote financial advisor, virtual classroom, etc...)
- Virtual Events (e.g., live event, company all-hands, live concert, etc...)
Source code | Product documentation | Samples
Install the Azure Communication Rooms client library for .NET with NuGet:
dotnet add package Azure.Communication.Rooms
You need an Azure subscription and a Communication Service Resource to use this package.
To create a new Communication Service, you can use the Azure Portal, the Azure PowerShell, or the .NET management client library.
RoomsClient
provides the functionality to create room, update room, get room, list rooms, delete room, add participants, update participants, remove participants, and list participants.
using Azure.Communication.Rooms
Rooms clients can be authenticated using the connection string acquired from an Azure Communication Resource in the Azure Portal.
var connectionString = Environment.GetEnvironmentVariable("connection_string") // Find your Communication Services resource in the Azure portal
RoomsClient client = new RoomsClient(connectionString);
To create a room, call the CreateRoom
or CreateRoomAsync
function from RoomsClient
.
The validFrom
, validUntil
, and participants
arguments are all optional. If validFrom
and validUntil
are not provided, then the default for validFrom
is current date time and the default for validUntil
is validFrom + 180 days
.
When defining RoomParticipant
, if role is not specified, then it will be Attendee
by default.
The returned value is Response<CommunicationRoom>
which contains created room details as well as the status and associated error codes in case of a failure.
// Create communication users using the CommunicationIdentityClient
Response<CommunicationUserIdentifier> communicationUser1 = await communicationIdentityClient.CreateUserAsync();
Response<CommunicationUserIdentifier> communicationUser2 = await communicationIdentityClient.CreateUserAsync();
DateTimeOffset validFrom = DateTimeOffset.UtcNow;
DateTimeOffset validUntil = validFrom.AddDays(1);
RoomParticipant participant1 = new RoomParticipant(communicationUser1.Value); // If role is not provided, then it is set as Attendee by default
RoomParticipant participant2 = new RoomParticipant(communicationUser2.Value) { Role = ParticipantRole.Presenter};
List<RoomParticipant> invitedParticipants = new List<RoomParticipant>
{
participant1,
participant2
};
Response<CommunicationRoom> createRoomResponse = await roomsClient.CreateRoomAsync(validFrom, validUntil, invitedParticipants);
CommunicationRoom createCommunicationRoom = createRoomResponse.Value;
The validFrom
and validUntil
properties of a created room can be updated by calling the UpdateRoom
or UpdateRoomAsync
function from RoomsClient
.
validUntil = validFrom.AddDays(30);
Response<CommunicationRoom> updateRoomResponse = await roomsClient.UpdateRoomAsync(createdRoomId, validFrom, validUntil);
CommunicationRoom updateCommunicationRoom = updateRoomResponse.Value;
A created room can be retrieved by calling the GetRoom
or GetRoomAsync
function from RoomsClient
and passing in the associated roomId
.
Response<CommunicationRoom> getRoomResponse = await roomsClient.GetRoomAsync(createdRoomId);
CommunicationRoom getCommunicationRoom = getRoomResponse.Value;
All valid rooms created under an ACS resource can be retrieved by calling the GetRooms
or GetRoomsAsync
function from RoomsClient
.
AsyncPageable<CommunicationRoom> allRooms = roomsClient.GetRoomsAsync();
await foreach (CommunicationRoom room in allRooms)
{
Console.WriteLine($"Room with id {room.Id} is valid from {room.ValidFrom} to {room.ValidUntil}.");
}
To delete a room, call the DeleteRoom
or DeleteRoomAsync
function from RoomsClient.
Response deleteRoomResponse = await roomsClient.DeleteRoomAsync(createdRoomId);
In order to add new participants or update existing participants, call the AddOrUpdateParticipants
or AddOrUpdateParticipantsAsync
function from RoomsClient.
Response<CommunicationUserIdentifier> communicationUser3 = await communicationIdentityClient.CreateUserAsync();
RoomParticipant newParticipant = new RoomParticipant(communicationUser3.Value) { Role = ParticipantRole.Consumer };
// Previous snippet for create room added participant2 as Presenter
participant2 = new RoomParticipant(communicationUser2) { Role = ParticipantRole.Attendee };
List<RoomParticipant> participantsToAddOrUpdate = new List<RoomParticipant>
{
participant2, // participant2 updated from Presenter to Attendee
newParticipant, // newParticipant added to the room
};
Response addOrUpdateParticipantResponse = await roomsClient.AddOrUpdateParticipantsAsync(createdRoomId, participantsToAddOrUpdate);
To remove participants from a room, call the RemoveParticipants
or RemoveParticipantsAsync
function from RoomsClient.
List<CommunicationIdentifier> participantsToRemove = new List<CommunicationIdentifier>
{
communicationUser1,
communicationUser2
};
Response removeParticipantResponse = await roomsClient.RemoveParticipantsAsync(createdRoomId, participantsToRemove);
To get all the participants from a room, call the GetParticipants
or GetParticipantsAsync
function from RoomsClient.
The returned value is Pageable<RoomParticipant>
or AsyncPageable<RoomParticipant>
which contains the paginated list of participants.
AsyncPageable<RoomParticipant> allParticipants = roomsClient.GetParticipantsAsync(createdRoomId);
await foreach (RoomParticipant participant in allParticipants)
{
Console.WriteLine($" Participant with id {participant.CommunicationIdentifier.RawId} is a {participant.Role}");
}
A RequestFailedException
is thrown as a service response for any unsuccessful requests. The exception contains information about what response code was returned from the service.
try
{
CommunicationIdentityClient communicationIdentityClient = CreateInstrumentedCommunicationIdentityClient();
Response<CommunicationUserIdentifier> communicationUser1 = await communicationIdentityClient.CreateUserAsync();
Response<CommunicationUserIdentifier> communicationUser2 = await communicationIdentityClient.CreateUserAsync();
DateTimeOffset validFrom = DateTimeOffset.UtcNow;
DateTimeOffset validUntil = validFrom.AddDays(1);
List<RoomParticipant> createRoomParticipants = new List<RoomParticipant>();
RoomParticipant participant1 = new RoomParticipant(communicationUser1.Value) { Role = ParticipantRole.Presenter };
RoomParticipant participant2 = new RoomParticipant(communicationUser2.Value) { Role = ParticipantRole.Attendee };
Response<CommunicationRoom> createRoomResponse = await roomsClient.CreateRoomAsync(validFrom, validUntil, createRoomParticipants);
CommunicationRoom createRoomResult = createRoomResponse.Value;
}
catch (RequestFailedException ex)
{
Console.WriteLine(ex.Message);
}
This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit cla.microsoft.com.
This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.
Update the sample code links once the sdk is published